1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source. A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015, Joyent, Inc.
.\"
.Dd Apr 13, 2015
.Dt OVERLAY_FILES 4
.Os
.Sh NAME
.Nm overlay_files
.Nd Overlay files plugin file format
.Sh DESCRIPTION
The
.Sy files
plugin provides a means for a dynamic overlay where the destinations are
determined based on a static description contained in a
.Sy JSON
file. This manual describes the format of the file used by the
.Sy files/config
property. To create and manage overlays
with the
.Sy files
plugin, use
.Xr dladm 1M .
For more information on overlays, see
.Xr overlay 5 .
.Pp
Using the
.Sy files
module, a static and simple overlay network can be created. This network
does not support the use of
.Em broadcast
or
.Em multicast
traffic. Both ARP and NDP traffic are proxied by the plugin itself. In
addition, the plugin allows for DHCP. Instead of providing a traditional
DHCP proxy, when an initial DHCP broadcast goes out to a broadcast
address, it will get rewritten to target a specific MAC address. The
.Sy files
plugin is useful as proof of concept and for simple static networks
where addresses do not need to be reconfigured. If more advanced
topologies or more streamlined updates are required, consider a different
plugin.
.Pp
The file format is encoded as a series of
.Sy JSON
objects. Each object has a key, which is a MAC address on the
.Sy overlay
network. It has multiple values, some required, some optional, which
describe various properties. The valid properties are:
.Bl -hang -width Ds
.It Sy ip
.Bd -filled -compact
The
.Sy ip
key indicates the IP address on the
.Sy underlay
network that houses the MAC address in question. Packets directed for
the MAC address will be encapsulated and set to this address. This field
is required.
.Pp
The value is a
.Em JSON String .
Both IPv4 and IPv6 addresses are supported and should be written out in their
traditional forms. Follow the guidelines for writing addresses in
.Xr inet_aton 3SOCKET .
.Ed
.It Sy port
.Bd -filled -compact
The
.Sy port
key indicates the port on the
.Sy underlay
network that houses the MAC address in question. This property is required if
the encapsulation module requires a port for its destination. The value is
a
.Em JSON Number .
.Ed
.It Sy arp
.Bd -filled -compact
The
.Sy arp
key stores the IPv4 address that corresponds to this MAC address on the
.Sy overlay
network. This will be used to respond to ARP queries that would traditionally
have been received by the OS kernel. If this address is not present, no IPv4
packets directed to this IP address will be received by the network interface
that has this MAC address, regardless of what is configured on top of it.
.Pp
The value is a
.Em JSON String
and should be written out following the guidelines for IPv4 addresses in
.Xr inet_aton 3SOCKET .
.Ed
.It Sy ndp
.Bd -filled -compact
The
.Sy ndp
key stores the IPv6 address that corresponds to this MAC address on the
.Sy overlay
network. This will be used to respond to NDP queries that would traditionally
have been received by the OS kernel. If this address is not present, no IPv6
packets directed to this IP address will be received by the network interface
that has this MAC address, regardless of what is configured on top of it.
.Pp
The value is a
.Em JSON String
and should be written out following the guidelines for IPv6 addresses in
.Xr inet_aton 3SOCKET .
.Ed
.It Sy dhcp-proxy
.Bd -filled -compact
The
.Sy dhcp-proxy
key stores a MAC address that DHCP messages directed to a broadcast address get
rewritten to be sent to. This can be viewed as a form of proxy DHCP, but is
different in mechanism from a traditional proxy. The value is a
.Em JSON String
and should be written as a traditional MAC address string as described by
.Xr ether_aton 3SOCKET .
.Ed
.El
.Sh EXAMPLES
.Sy Example 1
Sample configuration file
.Pp
This configuration file provides information for three different MAC
addresses. Each MAC address has an entry which describes what its IPv4
and IPv6 address is, as well as the IP address and port of the host on
the underlay network. Finally, one host has a DHCP proxy entry to
demonstrate how one might configure DHCP.
.Bd -literal -offset indent
{
"de:ad:be:ef:00:00": {
"arp": "10.55.55.2",
"ip": "10.88.88.69",
"ndp": "fe80::3",
"port": 4789
},
"de:ad:be:ef:00:01": {
"arp": "10.55.55.3",
"dhcp-proxy": "de:ad:be:ef:00:00",
"ip": "10.88.88.70",
"ndp": "fe80::4",
"port": 4789
},
"de:ad:be:ef:00:02": {
"arp": "10.55.55.4",
"ip": "10.88.88.71",
"ndp": "fe80::5",
"port": 4789
}
}
.Ed
.Sh STABILITY
This file format is
.Sy committed ;
however, keys that are not listed here are reserved for future use.
.Sh SEE ALSO
.Xr dladm 1M
.Xr overlay 5
|
