diff options
Diffstat (limited to 'usr/src/man/man4/overlay_files.4')
| -rw-r--r-- | usr/src/man/man4/overlay_files.4 | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/usr/src/man/man4/overlay_files.4 b/usr/src/man/man4/overlay_files.4 new file mode 100644 index 0000000000..b9e5387871 --- /dev/null +++ b/usr/src/man/man4/overlay_files.4 @@ -0,0 +1,187 @@ +.\" +.\" 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 Apr 13, 2015 +.Dt OVERLAY_FILES 4 +.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 1M . +For more information on overlays, see +.Xr overlay 5 . +.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 3SOCKET . +.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 3SOCKET . +.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 3SOCKET . +.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 dladm 1M , +.Xr overlay 5 |