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