OVERLAY_FILES(5) File Formats and Configurations OVERLAY_FILES(5)

NAME

overlay_files - Overlay files plugin file format

DESCRIPTION

The files plugin provides a means for a dynamic overlay where the
destinations are determined based on a static description contained in a
JSON file. This manual describes the format of the file used by the
files/config property. To create and manage overlays with the files
plugin, use dladm(8). For more information on overlays, see overlay(7).

Using the files module, a static and simple overlay network can be created.
This network does not support the use of broadcast or 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 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.

The file format is encoded as a series of JSON objects. Each object has a
key, which is a MAC address on the overlay network. It has multiple
values, some required, some optional, which describe various properties.
The valid properties are:

ip
The ip key indicates the IP address on the 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.

The value is a 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 inet_aton(3C).

port
The port key indicates the port on the 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 JSON Number.

arp
The arp key stores the IPv4 address that corresponds to this MAC
address on the 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.

The value is a JSON String and should be written out following the
guidelines for IPv4 addresses in inet_aton(3C).

ndp
The ndp key stores the IPv6 address that corresponds to this MAC
address on the 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.

The value is a JSON String and should be written out following the
guidelines for IPv6 addresses in inet_aton(3C).

dhcp-proxy
The 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 JSON String and should be
written as a traditional MAC address string as described by
ether_aton(3SOCKET).

EXAMPLES

Example 1 Sample configuration file

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.

{
"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
}
}

STABILITY

This file format is committed; however, keys that are not listed here are
reserved for future use.

SEE ALSO

overlay(7), dladm(8)

illumos March 30, 2022 illumos