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