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

overlay_files — Overlay files plugin file format

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 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 or 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:

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).

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.
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).

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).

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).

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

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

overlay(7), dladm(8)

March 30, 2022 OmniOS