13500 Want support for overlay networks

Portions contributed by: Dan McDonald <danmcd@joyent.com>
Portions contributed by: Jason King <jason.king@joyent.com>
Portions contributed by: Jerry Jelinek <jerry.jelinek@joyent.com>
Portions contributed by: Mike Zeller <mike@mikezeller.net>
Portions contributed by: Andy Fiddaman <omnios@citrus-it.co.uk>
Reviewed by: Andy Fiddaman <andy@omnios.org>
Reviewed by: Dan McDonald <danmcd@joyent.com>
Reviewed by: Jason King <jbk@joyent.com>
Reviewed by: Jerry Jelinek <jerry.jelinek@joyent.com>
Reviewed by: Joshua M. Clulow <jmc@joyent.com>
Reviewed by: Mike Gerdts <mike.gerdts@joyent.com>
Reviewed by: Mike Zeller <mike.zeller@joyent.com>
Reviewed by: Patrick Mooney <patrick.mooney@joyent.com>
Reviewed by: Rob Gulewich <robert.gulewich@joyent.com>
Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Ryan Zezeski <rpz@joyent.com>
Approved by: Joshua M. Clulow <josh@sysmgr.org>

2 files changed, 188 insertions, 0 deletions

diff --git a/usr/src/man/man4/Makefile b/usr/src/man/man4/Makefile
index 40c7f78d41..941757d4f3 100644
--- a/usr/src/man/man4/Makefile
+++ b/usr/src/man/man4/Makefile
@@ -133,6 +133,7 @@ _MANFILES=	Intro.4				\
 		nsmbrc.4			\
 		nss.4				\
 		nsswitch.conf.4			\
+		overlay_files.4			\
 		packingrules.4			\
 		pam.conf.4			\
 		passwd.4			\
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