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