.\"
.\" 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 March 30, 2022
.Dt OVERLAY_FILES 5
.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 8 .
For more information on overlays, see
.Xr overlay 7 .
.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 3C .
.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 3C .
.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 3C .
.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 overlay 7 ,
.Xr dladm 8