OS-3958 want documentation for overlay devices

OS-4182 need dladm create-overlay -t
OS-4174 long options for dladm *-overlay
OS-4179 want search plugin in overlay property list
OS-4181 Clean up duplicate VXLAN_MAGIC definition

13 files changed, 1285 insertions, 25 deletions

diff --git a/usr/src/cmd/dladm/dladm.c b/usr/src/cmd/dladm/dladm.c
index b847a3ba58..8e4f61fae0 100644
--- a/usr/src/cmd/dladm/dladm.c
+++ b/usr/src/cmd/dladm/dladm.c
@@ -413,16 +413,16 @@ static cmd_t	cmds[] = {
 	    "    show-bridge      -t [-p] [-o <field>,...] [-s [-i <interval>]]"
 	    " <bridge>\n"						},
 	{ "create-overlay",	do_create_overlay,
-	    "    create-overlay   -e <encap> -s <search> -v <vnetid>\n"
-	    "\t\t     [ -p <prop>=<value>[,...]] <overlay-name>"	},
+	    "    create-overlay   [-t] -e <encap> -s <search> -v <vnetid>\n"
+	    "\t\t     [ -p <prop>=<value>[,...]] <overlay>"	},
 	{ "delete-overlay",	do_delete_overlay,
-	    "    delete-overlay   <overlay-name>"			},
+	    "    delete-overlay   <overlay>"			},
 	{ "modify-overlay",	do_modify_overlay,
-	    "    modify-overlay   [-d mac] [-f] [-s mac=ip:port] "
-	    "<overlay-name>"						},
+	    "    modify-overlay   -d mac | -f | -s mac=ip:port "
+	    "<overlay>"						},
 	{ "show-overlay",	do_show_overlay,
-	    "    show-overlay     [-f | -t] [-p] [-o <field>,...]"
-	    "<overlay> \n"						},
+	    "    show-overlay     [-f | -t] [[-p] -o <field>,...] "
+	    "[<overlay>]\n"						},
 	{ "show-usage",		do_show_usage,
 	    "    show-usage       [-a] [-d | -F <format>] "
 	    "[-s <DD/MM/YYYY,HH:MM:SS>]\n"
@@ -1451,6 +1451,31 @@ static ofmt_field_t bridge_trill_fields[] = {
     offsetof(bridge_trill_fields_buf_t, bridget_nexthop), print_default_cb },
 { NULL,		0, 0, NULL}};
 
+static const struct option overlay_create_lopts[] = {
+	{ "encap",	required_argument,	NULL,	'e' },
+	{ "prop",	required_argument,	NULL,	'p' },
+	{ "search",	required_argument,	NULL,	's' },
+	{ "temporary", 	no_argument,		NULL,	't' },
+	{ "vnetid",	required_argument,	NULL,	'v' },
+	{ NULL,		0,			NULL,	0 }
+};
+
+static const struct option overlay_modify_lopts[] = {
+	{ "delete-entry",	required_argument,	NULL,	'd' },
+	{ "flush-table",	no_argument,		NULL,	'f' },
+	{ "set-entry",		required_argument,	NULL,	's' },
+	{ NULL,			0,			NULL,	0 }
+};
+
+static const struct option overlay_show_lopts[] = {
+	{ "fma",	no_argument,		NULL,	'f' },
+	{ "target",	no_argument,		NULL,	't' },
+	{ "parsable",	no_argument,		NULL,	'p' },
+	{ "parseable",	no_argument,		NULL,	'p' },
+	{ "output",	required_argument,	NULL,	'o' },
+	{ NULL,		0,			NULL,	0 }
+};
+
 /*
  * Structures for dladm show-overlay
  */
@@ -9891,14 +9916,15 @@ do_create_overlay(int argc, char *argv[], const char *use)
 	char			*encap = NULL, *endp, *search = NULL;
 	char			name[MAXLINKNAMELEN];
 	dladm_status_t		status;
-	uint32_t		flags = DLADM_OPT_ACTIVE | DLADM_OPT_TRANSIENT;
+	uint32_t		flags = DLADM_OPT_ACTIVE | DLADM_OPT_PERSIST;
 	uint64_t		vid;
 	boolean_t		havevid = B_FALSE;
 	char			propstr[DLADM_STRSIZE];
 	dladm_arg_list_t	*proplist = NULL;
 
 	bzero(propstr, sizeof (propstr));
-	while ((opt = getopt(argc, argv, ":e:v:p:s:")) != -1) {
+	while ((opt = getopt_long(argc, argv, ":te:v:p:s:",
+	    overlay_create_lopts, NULL)) != -1) {
 		switch (opt) {
 		case 'e':
 			encap = optarg;
@@ -9906,6 +9932,9 @@ do_create_overlay(int argc, char *argv[], const char *use)
 		case 's':
 			search = optarg;
 			break;
+		case 't':
+			flags &= ~DLADM_OPT_PERSIST;
+			break;
 		case 'p':
 			(void) strlcat(propstr, optarg, DLADM_STRSIZE);
 			if (strlcat(propstr, ",", DLADM_STRSIZE) >=
@@ -10412,7 +10441,8 @@ do_show_overlay(int argc, char *argv[], const char *use)
 	fieldsp = overlay_fields;
 	parse = B_FALSE;
 	ofmtflags = OFMT_WRAP;
-	while ((opt = getopt(argc, argv, ":o:pft")) != -1) {
+	while ((opt = getopt_long(argc, argv, ":o:pft", overlay_show_lopts,
+	    NULL)) != -1) {
 		switch (opt) {
 		case 'f':
 			funcp = show_one_overlay_fma;
@@ -10474,7 +10504,8 @@ do_modify_overlay(int argc, char *argv[], const char *use)
 	dladm_status_t		status;
 
 	flush = set = delete = B_FALSE;
-	while ((opt = getopt(argc, argv, ":fd:s:")) != -1) {
+	while ((opt = getopt_long(argc, argv, ":fd:s:", overlay_modify_lopts,
+	    NULL)) != -1) {
 		switch (opt) {
 		case 'd':
 			if (delete == B_TRUE)
diff --git a/usr/src/lib/varpd/libvarpd/common/libvarpd.c b/usr/src/lib/varpd/libvarpd/common/libvarpd.c
index b08bd629e0..62bf9cc14c 100644
--- a/usr/src/lib/varpd/libvarpd/common/libvarpd.c
+++ b/usr/src/lib/varpd/libvarpd/common/libvarpd.c
@@ -57,7 +57,6 @@ libvarpd_instance_lcomparator(const void *lp, const void *rp)
 	return (0);
 }
 
-
 int
 libvarpd_create(varpd_handle_t **vphp)
 {
diff --git a/usr/src/lib/varpd/libvarpd/common/libvarpd_impl.h b/usr/src/lib/varpd/libvarpd/common/libvarpd_impl.h
index c273b800f7..7ecd3a952f 100644
--- a/usr/src/lib/varpd/libvarpd/common/libvarpd_impl.h
+++ b/usr/src/lib/varpd/libvarpd/common/libvarpd_impl.h
@@ -193,6 +193,7 @@ extern void libvarpd_plugin_postfork(void);
 extern void libvarpd_plugin_fini(void);
 extern int libvarpd_plugin_comparator(const void *, const void *);
 extern varpd_plugin_t *libvarpd_plugin_lookup(varpd_impl_t *, const char *);
+
 extern varpd_instance_t *libvarpd_instance_lookup_by_dlid(varpd_impl_t *,
     datalink_id_t);
 
diff --git a/usr/src/lib/varpd/libvarpd/common/libvarpd_prop.c b/usr/src/lib/varpd/libvarpd/common/libvarpd_prop.c
index 4d50fb372d..ebd40bdfa7 100644
--- a/usr/src/lib/varpd/libvarpd/common/libvarpd_prop.c
+++ b/usr/src/lib/varpd/libvarpd/common/libvarpd_prop.c
@@ -35,6 +35,26 @@ typedef struct varpd_prop_info {
 	uint8_t			vprop_poss[LIBVARPD_PROP_SIZEMAX];
 } varpd_prop_info_t;
 
+/* Internal Properties */
+static int varpd_nintprops = 1;
+static const char *varpd_intprops[] = {
+	"search"
+};
+
+static int
+libvarpd_prop_get_search(varpd_prop_info_t *infop, void *buf, uint32_t *sizep)
+{
+	varpd_plugin_t *vpp = infop->vprop_instance->vri_plugin;
+	size_t nlen;
+
+	nlen = strlen(vpp->vpp_name) + 1;
+	if (nlen > *sizep)
+		return (EOVERFLOW);
+	*sizep = nlen;
+	(void) strlcpy(buf, vpp->vpp_name, *sizep);
+	return (0);
+}
+
 void
 libvarpd_prop_set_name(varpd_prop_handle_t *phdl, const char *name)
 {
@@ -151,9 +171,38 @@ libvarpd_prop_handle_free(varpd_prop_handle_t *phdl)
 int
 libvarpd_prop_nprops(varpd_instance_handle_t *ihdl, uint_t *np)
 {
+	int ret;
 	varpd_instance_t *instp = (varpd_instance_t *)ihdl;
 
-	return (instp->vri_plugin->vpp_ops->vpo_nprops(instp->vri_private, np));
+	ret = instp->vri_plugin->vpp_ops->vpo_nprops(instp->vri_private, np);
+	if (ret != 0)
+		return (ret);
+	*np += varpd_nintprops;
+	return (0);
+}
+
+static int
+libvarpd_prop_info_fill_int_cb(varpd_handle_t *handle, const char *name,
+    void *arg)
+{
+	varpd_prop_handle_t *vph = arg;
+	libvarpd_prop_set_range_str(vph, name);
+	return (0);
+}
+
+static int
+libvarpd_prop_info_fill_int(varpd_prop_handle_t *vph, uint_t propid)
+{
+	varpd_prop_info_t *infop = (varpd_prop_info_t *)vph;
+	if (propid >= varpd_nintprops)
+		abort();
+	libvarpd_prop_set_name(vph, varpd_intprops[0]);
+	libvarpd_prop_set_prot(vph, OVERLAY_PROP_PERM_READ);
+	libvarpd_prop_set_type(vph, OVERLAY_PROP_T_STRING);
+	libvarpd_prop_set_nodefault(vph);
+	libvarpd_plugin_walk((varpd_handle_t *)infop->vprop_instance->vri_impl,
+	    libvarpd_prop_info_fill_int_cb, vph);
+	return (0);
 }
 
 int
@@ -164,9 +213,15 @@ libvarpd_prop_info_fill(varpd_prop_handle_t *phdl, uint_t propid)
 	mac_propval_range_t *rangep = (mac_propval_range_t *)infop->vprop_poss;
 
 	infop->vprop_psize = sizeof (mac_propval_range_t);
+
 	bzero(rangep, sizeof (mac_propval_range_t));
-	return (instp->vri_plugin->vpp_ops->vpo_propinfo(instp->vri_private,
-	    propid, phdl));
+	if (propid < varpd_nintprops) {
+		return (libvarpd_prop_info_fill_int(phdl, propid));
+	} else {
+		varpd_plugin_t *vpp = instp->vri_plugin;
+		return (vpp->vpp_ops->vpo_propinfo(instp->vri_private,
+		    propid - varpd_nintprops, phdl));
+	}
 }
 
 int
@@ -193,12 +248,18 @@ libvarpd_prop_info(varpd_prop_handle_t *phdl, const char **namep,
 int
 libvarpd_prop_get(varpd_prop_handle_t *phdl, void *buf, uint32_t *sizep)
 {
+	int i;
 	varpd_prop_info_t *infop = (varpd_prop_info_t *)phdl;
 	varpd_instance_t *instp = infop->vprop_instance;
 
 	if (infop->vprop_name[0] == '\0')
 		return (EINVAL);
 
+	if (strcmp(varpd_intprops[0], infop->vprop_name) == 0) {
+		/* search property */
+		return (libvarpd_prop_get_search(infop, buf, sizep));
+	}
+
 	return (instp->vri_plugin->vpp_ops->vpo_getprop(instp->vri_private,
 	    infop->vprop_name, buf, sizep));
 }
@@ -206,12 +267,19 @@ libvarpd_prop_get(varpd_prop_handle_t *phdl, void *buf, uint32_t *sizep)
 int
 libvarpd_prop_set(varpd_prop_handle_t *phdl, const void *buf, uint32_t size)
 {
+	int i;
 	varpd_prop_info_t *infop = (varpd_prop_info_t *)phdl;
 	varpd_instance_t *instp = infop->vprop_instance;
 
 	if (infop->vprop_name[0] == '\0')
 		return (EINVAL);
 
+	for (i = 0; i < varpd_nintprops; i++) {
+		if (strcmp(infop->vprop_name, varpd_intprops[i]) == 0) {
+			return (EPERM);
+		}
+	}
+
 	return (instp->vri_plugin->vpp_ops->vpo_setprop(instp->vri_private,
 	    infop->vprop_name, buf, size));
 }
diff --git a/usr/src/man/man1m/dladm.1m b/usr/src/man/man1m/dladm.1m
index 6a390899ab..9120023170 100644
--- a/usr/src/man/man1m/dladm.1m
+++ b/usr/src/man/man1m/dladm.1m
@@ -1,6 +1,6 @@
 '\" te
 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
-.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved
+.\" Copyright (c) 2015, Joyent, Inc. All Rights Reserved
 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.
 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
@@ -9,7 +9,7 @@
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH DLADM 1M "Dec 03, 2014"
+.TH DLADM 1M "Apr 09, 2015"
 .SH NAME
 dladm \- administer data links
 .SH SYNOPSIS
@@ -141,6 +141,14 @@ dladm \- administer data links
 
 .LP
 .nf
+\fBdladm create-overlay\fR [\fB-t\fR] \fB-e\fR \fIencap\fR \fB-s\fR \fIsearch\fR \fB-v\fR \fIvnetid\fR [\fB-p\fR \fIprop\fR=\fIvalue\fR[,...]] \fIoverlay\fR
+\fBdladm delete-overlay\fR \fIoverlay\fR
+\fBdladm modify-overlay\fR \fB-d\fR \fImac\fR | \fB-f\fR | \fB-s\fR \fImac=ip:port\fR \fIoverlay\fR
+\fBdladm show-overlay\fR [ \fB-f\fR | \fB-t\fR ] [[\fB-p\fR] \fB-o\fR \fIfield\fR[,...]] [\fIoverlay\fR]
+.fi
+
+.LP
+.nf
 \fBdladm show-usage\fR [\fB-a\fR] \fB-f\fR \fIfilename\fR [\fB-p\fR \fIplotfile\fR \fB-F\fR \fIformat\fR] [\fB-s\fR \fItime\fR]
      [\fB-e\fR \fItime\fR] [\fIlink\fR]
 .fi
@@ -228,9 +236,9 @@ A WiFi datalink.
 .ad
 .sp .6
 .RS 4n
-A virtual network interface created on a link or an \fBetherstub\fR. It is a
-pseudo device that can be treated as if it were an network interface card on a
-machine.
+A virtual network interface created on a link, an \fBetherstub\fR, or \fBan
+overlay\fR. It is a pseudo device that can be treated as if it were an network
+interface card on a machine.
 .RE
 
 .sp
@@ -298,6 +306,20 @@ use any alphanumeric characters, as well as underscore (\fB_\fR), period
 characters.
 .RE
 
+.sp
+.ne 2
+.na
+.B overlay
+.ad
+.sp .6
+.RS 4n
+An overlay instance, identified by an administratively-chosen name. An overlay
+can be used to create or join an existing software defined network.
+VNICs created on an overlay will appear to be connected by a local virtual
+switch and will also be connected to interfaces on matching overlays provided by
+other hosts. For more information on overlay devices, see \fBoverlay\fR(5).
+.RE
+
 .SS "Options"
 .LP
 Each \fBdladm\fR subcommand has its own set of options. However, many of the
@@ -4376,6 +4398,348 @@ The tunnel destination address.
 .sp
 .ne 2
 .na
+\fBdladm create-overlay\fR \fB-e\fR \fIencap\fR \fB-s\fR \fIsearch\fR
+\fB-v\fR \fIvnetid\fR [\fB-p\fR \fIprop\fR=\fIvalue\fR[,...]] \fIoverlay\fR
+.ad
+.sp .6
+.RS 4n
+Create an overlay device named \fIoverlay\fR.
+.sp
+Overlay devices are similar to etherstubs. VNICs can be created on top
+of them. However, unlike an etherstub which is local to the system, an
+overlay device can be configured to communicate to remote hosts,
+providing a means for network virtualization. The way in which it does
+this is described by the encapsulation module and the search plugin. For
+more information on these, see \fBoverlay\fR(5).
+.sp
+An overlay device has a series of required and optional properties.  These
+properties vary based upon the search and encapsulation modules and are fully
+specified in \fBoverlay\fR(5). Not every property needs to be specified - some
+have default values which will be used if nothing specific is specified. For
+example, the default port for VXLAN comes from its IANA standard. If a
+required property is missing, the command will fail and inform you of the
+missing properties.
+.sp
+.ne 2
+.na
+\fB\fB-t\fR, \fB--temporary\fR\fR
+.ad
+.sp .6
+.RS 4n
+Specifies that the overlay is temporary. Temporary overlays last until
+the next reboot.
+.RE
+
+.sp
+.ne 2
+.na
+\fB-e\fR \fIencap\fR, \fB--encap\fR=\fIencap\fR
+.ad
+.sp .6
+.RS 4n
+Use \fIencap\fR as the encapsulation plugin for the overlay device
+\fIoverlay\fR. The encapsulation plugin determines how packets are transformed
+before being put on the wire.
+.RE
+
+.sp
+.ne 2
+.na
+\fB-s\fR \fIsearch\fR, \fB--search\fR=\fIsearch\fR
+.ad
+.sp .6
+.RS 4n
+Use \fIsearch\fR as the search plugin for \fIoverlay\fR. The search plugin
+determines how non-local targets are found and where packets are directed to.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fB-p\fR \fIprop\fR=\fIvalue\fR,..., \fB--prop\fR
+\fIprop\fR=\fIvalue\fR,...\fR
+.ad
+.sp .6
+.RS 4n
+A comma-separated list of properties to set to the specified values.
+.RE
+
+.sp
+.ne 2
+.na
+\fB-v\fR \fIvnetid\fR, \fB--vnetid\fR=\fIvnetid\fR
+.ad
+.sp .6
+.RS 4n
+Sets the virtual networking identfier to \fIvnetid\fR. A virtual network
+identifier determines is similar to a VLAN identifier, in that it identifies a
+unique virtual network. All overlay devices on the system share the same space
+for the virtual network idenfifiter. However, the valid range of identifiers is
+determined by the encapsulation plugin specified by \fB-e\fR.
+.RE
+
+.RE
+
+.sp
+.ne 2
+.na
+\fBdladm delete-overlay\fR \fIoverlay\fR
+.ad
+.sp .6
+.RS 4n
+Delete the specified overlay. This will fail if there are VNICs on top of the
+device.
+.RE
+
+.sp
+.ne 2
+.na
+\fBdladm modify-overlay\fR \fB-d\fR \fImac\fR | \fB-f\fR | \fB-s\fR \fImac=ip:port\fR \fIoverlay\fR
+.ad
+.sp .6
+.RS 4n
+Modifies the target tables for the specified overlay.
+.sp
+The different options allow for different ways of modifying the target table.
+One of \fB-d\fR, \fB-f\fR, and \fB-s\fR is required. This is not applicable for
+all kinds of overlay devices. For more information, see \fBoverlay\fR(5).
+.sp
+.ne 2
+.na
+\fB-d\fR \fImac\fR, \fB--delete-entry\fR=\fImac\fR
+.ad
+.sp .6
+.RS 4n
+Deletes the entry for \fImac\fR from the target table for \fIoverlay\fR. Note,
+if a lookup is pending or outstanding, this does not cancel it or stop it from
+updating the value.
+.RE
+
+.sp
+.ne 2
+.na
+\fB-f\fR, \fB--flush-table\fR
+.ad
+.sp .6
+.RS 4n
+Flushes all values in the target table for \fIoverlay\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fB-s\fR \fImac\fR=\fIvalue\fR, \fB--set-entry\fR=\fImac\fR=\fIvalue\fR
+.ad
+.sp .6
+.RS 4n
+Sets the value of \fIoverlay\fR's target table entry for \fImac\fR to the
+specified value. The specified value varies upon the encapsulation plugin. The
+value may be a combination of a MAC address, IP adress, and port. Generall, this
+looks like [\fImac\fR,][\fIIP\fR:][\fIport\fR]. If a component is the last one,
+then there is no need for a separator. eg. if just the MAC address or IP is
+needed, it would look like \fImac\fR and \fIIP\fR respectively.
+.RE
+
+.RE
+
+.sp
+.ne 2
+.na
+\fBdladm show-overlay\fR [ \fB-f\fR | \fB-t\fR ] [[\fB-p\fR] \fB-o\fR \fIfield\fR[,...]] [\fIoverlay\fR]
+.ad
+.sp .6
+.RS 4n
+Shows overlay configuration (the default), internal target tables (\fB-t\fR), or
+the FMA state (\fB-f\fR), either for all overlays or the specified overlay.
+.sp
+By default (with neither \fB-f\fR or \fB-t\fR specified), the following fields
+will be displayed:
+.sp
+.ne 2
+.na
+\fB\fBLINK\fR\fR
+.ad
+.sp .6
+.RS 4n
+The name of the overlay.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPROPERTY\fR\fR
+.ad
+.sp .6
+.RS 4n
+The name of the property.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPERM\fR\fR
+.ad
+.sp .6
+.RS 4n
+The read/write permissions of the property. The value shown is one of \fBr-\fR
+or \fBrw\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBVALUE\fR\fR
+.ad
+.sp .6
+.RS 4n
+The current  property value. If the value is not set, it is shown as \fB--\fR.
+If it is unknown, the value is shown as \fB?\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBDEFAULT\fR\fR
+.ad
+.sp .6
+.RS 4n
+The default value of the property. If the property has no default value,
+\fB--\fR is shown.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBPOSSIBLE\fR\fR
+.ad
+.sp .6
+.RS 4n
+A comma-separated list of the values the property can have. If the values span
+a numeric range, \fImin\fR - \fImax\fR might be shown as shorthand. If the
+possible values are unknown or unbounded, \fB--\fR is shown.
+.RE
+
+.sp
+When the \fB-f\fR option is displayed, the following fields will be displayed:
+.sp
+.ne 2
+.na
+\fB\fBLINK\fR\fR
+.ad
+.sp .6
+.RS 4n
+The name of the overlay.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBSTATUS\fR\fR
+.ad
+.sp .6
+.RS 4n
+Either \fBONLINE\fR or \fBDEGRADED\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBDETAILS\fR\fR
+.ad
+.sp .6
+.RS 4n
+When the \fBoverlay\fR's status is \fBONLINE\fR, then this has the value
+\fB--\fR. Otherwise, when it is \fBDEGRADED\fR, this field provides a more
+detailed explanation as to why it's degraded.
+.RE
+
+.sp
+When the \fB-t\fR option is displayed, the following fields will be displayed:
+.sp
+.ne 2
+.na
+\fB\fBLINK\fR\fR
+.ad
+.sp .6
+.RS 4n
+The name of the overlay.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBTARGET\fR\fR
+.ad
+.sp .6
+.RS 4n
+The target MAC address of a table entry.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBDESTINATION\fR\fR
+.ad
+.sp .6
+.RS 4n
+The address that an encapsulated packet will be sent to when a packet has the
+address specified by \fBTARGET\fR.
+.RE
+
+The \fBshow-overlay\fR command supports the following options:
+
+.sp
+.ne 2
+.na
+\fB-f\fR, \fB--fma\fR
+.ad
+.sp .6
+.RS 4n
+Displays information about an overlay device's FMA state. For more
+information on the target table, see \fBoverlay\fR(5).
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fB-o\fR \fIfield\fR[,...], \fB--output\fR=\fIfield\fR\fR
+.ad
+.sp .6
+.RS 4n
+A case-insensitive, comma-separated list of output fields to display. The field
+name must be one of the fields listed above, or the special value \fBall\fR, to
+display all fields. The fields applicable to the \fB-o\fR option are limited to
+those listed under each output mode. For example, if using \fB-L\fR, only the
+fields listed under \fB-L\fR, above, can be used with \fB-o\fR.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fB-p\fR, \fB--parseable\fR\fR
+.ad
+.sp .6
+.RS 4n
+Display using a stable machine-parseable format. The \fB-o\fR option is
+required with \fB-p\fR. See "Parseable Output Format", below.
+.RE
+
+.sp
+.ne 2
+.na
+\fB-t\fR, \fB--target\fR
+.ad
+.sp .6
+.RS 4n
+Displays information about an overlay device's target table. For more
+information on the target table, see \fBoverlay\fR(5).
+.RE
+
+.RE
+
+.sp
+.ne 2
+.na
 \fB\fBdladm show-usage\fR [\fB-a\fR] \fB-f\fR \fIfilename\fR [\fB-p\fR
 \fIplotfile\fR \fB-F\fR \fIformat\fR] [\fB-s\fR \fItime\fR] [\fB-e\fR
 \fItime\fR] [\fIlink\fR]\fR
@@ -5536,7 +5900,7 @@ Interface Stability	Committed
 .LP
 \fBacctadm\fR(1M), \fBautopush\fR(1M), \fBifconfig\fR(1M), \fBipsecconf\fR(1M),
 \fBndd\fR(1M), \fBpsrset\fR(1M), \fBwpad\fR(1M), \fBzonecfg\fR(1M),
-\fBattributes\fR(5), \fBieee802.3\fR(5), \fBdlpi\fR(7P)
+\fBattributes\fR(5), \fBieee802.3\fR(5), \fBoverlay\fR(5), \fBdlpi\fR(7P)
 .SH NOTES
 .LP
 The preferred method of referring to an aggregation in the aggregation
diff --git a/usr/src/man/man4/Makefile b/usr/src/man/man4/Makefile
index 6598c115a3..4ba45bd662 100644
--- a/usr/src/man/man4/Makefile
+++ b/usr/src/man/man4/Makefile
@@ -138,6 +138,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..c1a4ce4b3b
--- /dev/null
+++ b/usr/src/man/man4/overlay_files.4
@@ -0,0 +1,169 @@
+.\"
+.\" 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
diff --git a/usr/src/man/man5/Makefile b/usr/src/man/man5/Makefile
index 3247fec698..27c549e44d 100644
--- a/usr/src/man/man5/Makefile
+++ b/usr/src/man/man5/Makefile
@@ -79,6 +79,7 @@ MANFILES=	Intro.5			\
 		ms.5			\
 		mutex.5			\
 		nfssec.5		\
+		overlay.5		\
 		pam_allow.5		\
 		pam_authtok_check.5	\
 		pam_authtok_get.5	\
diff --git a/usr/src/man/man5/overlay.5 b/usr/src/man/man5/overlay.5
new file mode 100644
index 0000000000..12134ebb82
--- /dev/null
+++ b/usr/src/man/man5/overlay.5
@@ -0,0 +1,499 @@
+.\"
+.\" 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 09, 2015
+.Dt OVERLAY 5
+.Os
+.Sh NAME
+.Nm overlay
+.Nd Overlay Devices
+.Sh DESCRIPTION
+Overlay devices are a GLDv3 device that allows users to create overlay
+networks that can be used to form the basis of network virtualization
+and software defined networking. Overlay networks allow a single
+physical network, often called an
+.Sy underlay
+network, to provide the means for creating multiple logical, isolated,
+and discrete layer two and layer three networks on top of it.
+.Pp
+Overlay devices are administered through
+.Xr dladm 1M .
+Overlay devices themselves cannot be plumbed up with
+.Sy IP ,
+.Sy vnd ,
+or any other protocol. Instead, like an
+.Sy etherstub ,
+they allow for VNICs to be created on top of them. Like an
+.Sy etherstub ,
+an overlay device acts as a local switch; however, when it encounters a
+non-local destination address, it instead looks up where it should send
+the packet, encapsulates it, and sends it out another interface in the
+system.
+.Pp
+A single overlay device encapsulates the logic to answer two different,
+but related, questions:
+.Pp
+.Bl -enum -offset indent -compact
+.It
+How should a packet be transformed and put on the wire?
+.It
+Where should a transformed packet be sent?
+.El
+.Pp
+Each of these questions is answered by a plugin. The first question is
+answered by what's called an
+.Em encapsulation plugin .
+The second question is answered by what's called a
+.Em search plugin .
+Packets are encapsulated and decapsulated using the encapsulation plugin
+by the kernel. The search plugins are all user land plugins that are
+consumed by the varpd service whose FMRI is
+.Em svc:/network/varpd:default .
+This separation allows for the kernel to be responsible for the data
+path, while having the search plugins in userland allows the system to
+provide a much more expressive interface.
+.Ss Overlay Types
+Overlay devices come in
+two different flavors, one where all packets are always sent to a single
+address, the other, where the destination of a packet varies based on
+the target MAC address of the packet. This information is maintained in
+a
+.Em target table ,
+which is independent and unique to each overlay device. We call the
+plugins that send traffic to a single location, for example a single
+unicast or multicast IP address, a
+.Sy point to point
+overlay and the overlay devices that can send traffic to different
+locations based on the MAC address of that packet a
+.Sy dynamic
+overlay. The plugin type is determined based on the type of the
+.Sy search plugin .
+These are all fully listed in the section
+.Sx Plugins and their Properties .
+.Ss Overlay Destination
+Both encapsulation and search plugins define the kinds of destinations
+that they know how to support. An encapsulation plugin always has a
+single destination type that's determined based on how the encapsulation
+is defined. A search plugin, on the other hand, can support multiple
+combinations of destinations. A search plugin must support the
+destination type of the encapsulation device. The destination may
+require any of the following three pieces of information, depending on
+the encapsulation plugin:
+.Bl -hang -width Ds
+.It Sy MAC Address
+.Bd -filled -compact
+An Ethernet MAC address is required to determine the destination.
+.Ed
+.It Sy IP Address
+.Bd -filled -compact
+An IP address is required. Both IPv4 and IPv6 addresses are supported.
+.Ed
+.It Sy Port
+.Bd -filled -compact
+An IP protocol level (TCP, UDP, SCTP, etc.) port is required.
+.Ed
+.El
+.Pp
+The list of destination types that are supported by both the search and
+encapsulation plugins is listed in the section
+.Sx Plugins and their Properties .
+.Ss varpd
+The varpd service, mentioned above, is responsible for providing the
+virtual ARP daemon. Its responsibility is conceptually similar to ARP.
+It runs all instances of search plugins in the system and is responsible
+for answering the kernel's ARP-like questions for where packets should
+be sent.
+.Pp
+The varpd service, svc:/network/varpd:default, must be enabled for
+overlay devices to function. If it is disabled while there are active
+devices, then most overlay devices will not function correctly and
+likely will end up dropping traffic.
+.Sh PLUGINS AND PROPERTIES
+Properties fall into three categories in the system:
+.Bl -enum -offset indent -compact
+.It
+Generic properties all overlay devices have
+.It
+Properties specific to the encapsulation plugin
+.It
+Properties specific to the search plugin
+.El
+.Pp
+Each property in the system has the following attributes, which mirror
+the traditional
+.Xr dladm 1M
+link properties:
+.Bl -hang -width Ds
+.It Sy Name
+.Bd -filled -compact
+The name of a property is namespaced by its module and always structured
+and referred to as as module/property. This allows for both an
+encapsulation and search plugin to have a property with the same name.
+Properties that are valid for all overlay devices and not specific to a
+module do not generally use a module prefix.
+.Pp
+For example, the property
+.Sy vxlan/listen_ip
+is associated with the
+.Sy vxlan
+encapsulation module.
+.Ed
+.It Sy Type
+.Bd -filled -compact
+Each property in the system has a type.
+.Xr dladm 1M
+takes care of converting between the internal representation and a
+value, but the type influences the acceptable input range. The types
+are:
+.Bl -hang -width Ds
+.It Sy INT
+A signed integer that is up to eight bytes long
+.Pq Sy int64_t .
+.It Sy UINT
+An unsigned integer that is up to eight bytes long
+.Pq Sy uint64_t .
+.It Sy IP
+Either an IPv4 or IPv6 address in traditional string form. For example,
+192.168.128.23 or 2001:470:8af4::1:1. IPv4 addresses may also be encoded
+as IPv4-mapped IPv6 addresses.
+.It Sy STRING
+A string of ASCII or UTF-8 encoded characters terminated with a
+.Sy NUL
+byte. The maximum string length, including the terminator, is currently
+256 bytes.
+.El
+.Ed
+.It Sy Permissions
+.Bd -filled -compact
+Each property has permissions associated with it, which indicate whether
+the system considers them read-only properties or read-write properties.
+A read-only property can never be updated once the device is created.
+This generally includes things like the overlay's encapsulation module.
+.Ed
+.It Sy Required
+.Bd -filled -compact
+This property indicates whether the property is required for the given
+plugin. If it is not specified during a call to
+.Sy dladm create-overlay ,
+then the overlay cannot be successfully created. Properties which have a
+.Sy default
+will use that value if one is not specified rather than cause the
+overlay creation to fail.
+.Ed
+.It Sy Current Value
+.Bd -filled -compact
+The current value of a property, if the property has a value set.
+Required properties always have a value set.
+.Ed
+.It Sy Default Value
+.Bd -filled -compact
+The default value is an optional part of a given property. If a property
+does define a default value, then it will be used when an overlay is
+created and no other value is given.
+.Ed
+.It Sy Value ranges
+.Bd -filled -compact
+Value ranges are an optional part of a given property. They indicate a
+range or set of values that are valid and may be set for a property. A
+property may not declare such a range as it may be impractical or
+unknown. For example, most properties based on IP addresses will not
+declare a range.
+.Ed
+.El
+.Pp
+The following sections describe both the modules and the properties that
+exist for each module, noting their name, type, permissions, whether or
+not they are required, and if there is a default value. In addition, the
+effects of each property will be described.
+.Ss Encapsulation Plugins
+.Bl -hang -width Ds
+.It Sy vxlan
+The
+.Sy vxlan
+module is a UDP based encapsulation method. It takes a frame that would
+be put on the wire, wraps it up in a VXLAN header and places it in a UDP
+packet that gets sent out on the underlying network. For more details
+about the specific format of the VXLAN header, see
+.Xr vxlan 7P .
+.Pp
+The
+.Sy vxlan
+module requires both an
+.Sy IP address
+and
+.Sy port
+to address it. It has a 24-bit virtual network ID space, allowing for
+virtual network identifiers that range from
+.Sy 0
+-
+.Sy 16777215 .
+.Pp
+The
+.Sy vxlan
+module has the following properties:
+.Bl -hang -width Ds
+.It Sy vxlan/listen_ip
+.Bd -filled -compact
+Type:
+.Sy IP |
+Permissions:
+.Sy Read/Write |
+.Sy Required
+.Ed
+.Bd -filled
+The
+.Sy vxlan/listen_ip
+property determines the IP address that the system will accept VXLAN
+encapsulated packets on for this overlay.
+.Ed
+.It Sy vxlan/listen_port
+.Bd -filled -compact
+Type:
+.Sy UINT |
+Permissions:
+.Sy Read/Write |
+.Sy Required
+.Ed
+.Bd -filled -compact
+Default Value:
+.Sy 4789 |
+Range:
+.Sy 0 - 65535
+.Ed
+.Bd -filled
+The
+.Sy vxlan/listen_port
+property determines the UDP port that the system will listen on for
+VXLAN traffic for this overlay. The default value is
+.Sy 4789 ,
+the IANA assigned port for VXLAN.
+.Ed
+.El
+.Pp
+The
+.Sy vxlan/listen_ip
+and
+.Sy vxlan/listen_port
+properties determine how the system will accept VXLAN encapsulated
+packets for this interface. It does not determine the interface that
+packets will be sent out over. Multiple overlays that all use VXLAN can
+share the same IP and port combination, as the virtual network
+identifier can be used to tell the different overlays apart.
+.El
+.Ss Search Plugins
+Because search plugins may support multiple destinations, they may have
+more properties listed than necessarily show up for a given overlay.
+For example, the
+.Sy direct
+plugin supports destinations that are identified by both an IP address
+and a port, or just an IP address. In cases where the device is created
+over an overlay that only uses an IP address for its destination, then
+it will not have the
+.Sy direct/dest_port
+property.
+.Bl -hang -width Ds
+.It Sy direct
+The
+.Sy direct
+plugin is a point to point module that can be used to create an overlay
+that forwards all non-local traffic to a single destination. It supports
+destinations that are a combination of an
+.Sy IP Address
+and a
+.Sy port .
+.Pp
+The
+.Sy direct
+plugin has the following properties:
+.Bl -hang -width Ds
+.It Sy direct/dest_ip
+.Bd -filled -compact
+Type:
+.Sy IP |
+Permissions:
+.Sy Read/Write |
+.Sy Required
+.Ed
+.Bd -filled
+The
+.Sy direct/dest_ip
+property indicates the IP address that all traffic will be sent out.
+Traffic will be sent out the corresponding interface based on
+traditional IP routing rules and the configuration of the networking
+stack of the global zone.
+.Ed
+.It Sy direct/dest_port
+.Bd -filled -compact
+Type:
+.Sy UINT |
+Permissions:
+.Sy Read/Write |
+.Sy Required
+.Ed
+.Bd -filled -compact
+Default Value:
+.Sy - |
+Range:
+.Sy 0 - 65535
+.Ed
+.Bd -filled
+The
+.Sy direct/dest_port
+property indicates the TCP or UDP port that all traffic will be directed
+to.
+.Ed
+.El
+.It Sy files
+The
+.Sy files
+plugin implements a
+.Sy dynamic
+plugin that specifies where traffic should be sent based on a file. It
+is a glorified verison of /etc/ethers. The
+.Sy dynamic
+plugin does not support broadcast or multicast traffic, but it has
+support for proxy ARP, NDP, and DHCPv4. For the full details of the file
+format, see
+.Xr overlay_files 4 .
+.Pp
+The
+.Sy files
+plugin has the following property:
+.Bl -hang -width Ds
+.It Sy files/config
+.Bd -filled -compact
+Type:
+.Sy String |
+Permissions:
+.Sy Read/Write |
+.Sy Required
+.Ed
+.Bd -filled
+The
+.Sy files/config
+property specifies an absolute path to a file to read. The file is a
+JSON file that is formatted according to
+.Xr overlay_files 4 .
+.Ed
+.El
+.El
+.Ss General Properties
+Each overaly has the following properties which are used to give
+additional information about the system. None of these properties may be
+specified as part of a
+.Sy dladm create-overlay ,
+instead they come from other arguments or from internal parts of the
+system.
+.Bl -hang -width Ds
+.It Sy encap
+.Bd -filled -compact
+.Sy String |
+Permissions:
+.Sy Read Only
+.Ed
+.Bd -filled
+The
+.Sy encap
+property contains the name of the encapsulation module that's in use.
+.Ed
+.It Sy mtu
+.Bd -filled -compact
+.Sy UINT |
+Permissions:
+.Sy Read/Write
+.Ed
+.Bd -filled -compact
+Default Value:
+.Sy 1400 |
+Range:
+.Sy 576 - 9000
+.Ed
+.Bd -filled
+The
+.Sy mtu
+property describes the maximum transmission unit of the overlay. The
+default value is
+.Sy 1400
+bytes, which ensures that in a traditional deployment with an MTU of
+1500 bytes, the overhead that is added from encapsulation is all
+accounted for. It is the administrator's responsibility to ensure that
+the device's MTU and the encapsulation overhead does not exceed that of
+the interfaces that the encapsulated traffic will be sent out of.
+.Pp
+To modify the
+.Sy mtu
+property, use
+.Sy dladm set-linkprop .
+.Ed
+.It Sy search
+.Bd -filled -compact
+.Sy String |
+Permissions:
+.Sy Read Only
+.Ed
+.Bd -filled
+The
+.Sy search
+property contains the name of the search plugin that's in use.
+.Ed
+.It Sy varpd/id
+.Bd -filled -compact
+.Sy String |
+Permissions:
+.Sy Read Only
+.Ed
+.Bd -filled
+The
+.Sy varpd/id
+property indicates the identifier which the
+.Sy varpd
+service uses for this overlay.
+.Ed
+.It Sy vnetid
+.Bd -filled -compact
+.Sy UINT |
+Permissions:
+.Sy Read/Write
+.Ed
+.Bd -filled
+The
+.Sy vnetid
+property has the virtual network identifier that belongs to this overlay.
+The valid range for the virtual network identifier depends on the
+encapsulation engine.
+.Ed
+.El
+.Sh FMA INTEGRATION
+Overlay devices are wired into FMA, the illumos fault management
+architecture, and generates error reports depending on the
+.Sy search
+plugin in use. Due to limitations in FMA today, when a single overlay
+enters a degraded state, meaning that it cannot properly perform look
+ups or another error occurred, then it degrades the overall
+.Sy overlay
+psuedo-device driver.
+.Pp
+For more fine-grained information about which overlay is actually in a
+.Em degraded
+state, one should run
+.Sy dladm show-overlay -f .
+In addition, for each overlay in a degraded state a more useful
+diagnostic message is provided which describes the reason that caused
+this overlay to enter into a degraded state.
+.Pp
+The overlay driver is self-healing. If the problem corrects itself on
+its own, it will clear the fault on the corresponding device.
+.Sh SEE ALSO
+.Xr dladm 1M ,
+.Xr overlay_files 4 ,
+.Xr vxlan 7P
diff --git a/usr/src/man/man7p/Makefile b/usr/src/man/man7p/Makefile
index bbcf5ecf1d..2b3a92386b 100644
--- a/usr/src/man/man7p/Makefile
+++ b/usr/src/man/man7p/Makefile
@@ -38,7 +38,8 @@ MANFILES= 	arp.7p		\
 	 	sip.7p		\
 	 	slp.7p		\
 	 	tcp.7p		\
-	 	udp.7p
+	 	udp.7p		\
+		vxlan.7p
 
 MANLINKS=	AH.7p		\
 		ARP.7p		\
@@ -49,6 +50,7 @@ MANLINKS=	AH.7p		\
 		SCTP.7p		\
 		TCP.7p		\
 		UDP.7p		\
+		VXLAN.7p	\
 	 	if.7p
 
 ARP.7p		:= LINKSRC = arp.7p
@@ -71,6 +73,8 @@ TCP.7p		:= LINKSRC = tcp.7p
 
 UDP.7p		:= LINKSRC = udp.7p
 
+VXLAN.7p	:= LINKSRC = vxlan.7p
+
 .KEEP_STATE:
 
 include		$(SRC)/man/Makefile.man
diff --git a/usr/src/man/man7p/vxlan.7p b/usr/src/man/man7p/vxlan.7p
new file mode 100644
index 0000000000..a32637b484
--- /dev/null
+++ b/usr/src/man/man7p/vxlan.7p
@@ -0,0 +1,124 @@
+.\"
+.\" 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 10, 2015
+.Dt VXLAN 7P
+.Os
+.Sh NAME
+.Nm VXLAN ,
+.Nm vxlan
+.Nd Virtual eXtensible Local Area Network
+.Sh SYNOPSIS
+.In sys/vxlan.h
+.Sh DESCRIPTION
+.Nm
+(RFC 7348) is a network encapsulation protocol that is used by
+.Xr overlay 5
+devices. A payload, commonly an Ethernet frame, is placed inside of a
+UDP packet and prepended with an 8-byte
+.Nm
+header.
+.Pp
+The
+.Nm
+header contains two 32-bit words. The first word is an 8-bit flags field
+followed by 24 reserved bits. The second word is a 24-bit virtual network
+identifier followed by 8 reserved bits. The virtual network identifier
+identifies a unique
+.Nm
+and
+is similar in concept to an IEEE 802.1Q VLAN identifier.
+.Pp
+The system provides access to
+.Nm
+through dladm overlays. See
+.Xr dladm 1M
+and
+.Xr overlay 5
+for more information.
+.Pp
+The
+.In sys/vxlan.h
+header provides information for working with the
+.Nm
+protocol. The contents of this header are
+.Sy uncommitted .
+The header defines a structure that may be used to encode and decode a VXLAN
+header. It defines a packed structure type
+.Sy vxlan_hdr_t
+which represents the
+.Nm
+frame header and has the following members:
+.Bd -literal
+	uint32_t	vxlan_flags;	/* flags in upper 8 bits */
+	uint32_t	vxlan_id;	/* VXLAN ID in upper 24 bits */
+.Ed
+.Sh EXAMPLES
+.Sy Example 1
+Decoding a
+.Nm
+header
+.Pp
+The following example shows how to validate a
+.Nm header. For more information on this process, see RFC 7348.
+.Bd -literal -offset indent
+#include <sys/types.h>
+#include <netinet/in.h>
+#include <inttypes.h>
+#include <sys/vxlan.h>
+
+\&...
+
+/*
+ * Validate the following bytes as a VXLAN header. If valid, return
+ * 0 and store the VXLAN identifier in *vidp. Otherwise, return an
+ * error.
+ */
+int
+validate_vxlan(void *buf, int len, uint32_t *vidp)
+{
+	vxlan_hdr_t *hdr;
+
+	if (len < sizeof (vxlan_hdr_t))
+		return (EINAVL);
+
+	hdr = buf;
+	if ((ntohl(hdr->vxlan_flags) & VXLAN_MAGIC) == 0)
+		return (EINAVL);
+
+	*vidp = ntohl(vxlan->vxlan_id) >> VXLAN_ID_SHIFT;
+
+	return (0);
+}
+.Ed
+.Sh STABILITY
+The contents of
+.In sys/vxlan.h
+are
+.Sy Uncommitted .
+.Sh SEE ALSO
+.Xr dladm 1M ,
+.Xr overlay 5
+.Rs
+.%A Mahalingam, M.
+.%A Dutt, D.
+.%A Duda, K.
+.%A Agarwal, P.
+.%A Kreeger L.
+.%A Sridhar, T.
+.%A Bursell, M.
+.%A C. Wright
+.%T RFC 7348, Virtual eXtensible Local Area Network (VXLAN): A Framework
+.%T for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks
+.%D August 2014
+.Re
diff --git a/usr/src/uts/common/io/overlay/plugins/overlay_vxlan.c b/usr/src/uts/common/io/overlay/plugins/overlay_vxlan.c
index 7361462dfd..8b4e4ecb42 100644
--- a/usr/src/uts/common/io/overlay/plugins/overlay_vxlan.c
+++ b/usr/src/uts/common/io/overlay/plugins/overlay_vxlan.c
@@ -163,7 +163,7 @@ vxlan_o_encap(void *arg, mblk_t *mp, ovep_encap_info_t *einfop,
 		return (ENOMEM);
 
 	vxh = (vxlan_hdr_t *)ob->b_rptr;
-	vxh->vxlan_flags = ntohl(VXLAN_MAGIC);
+	vxh->vxlan_flags = ntohl(VXLAN_F_VDI);
 	vxh->vxlan_id = htonl((uint32_t)einfop->ovdi_id << VXLAN_ID_SHIFT);
 	ob->b_wptr += VXLAN_HDR_LEN;
 	*outp = ob;
@@ -180,7 +180,7 @@ vxlan_o_decap(void *arg, mblk_t *mp, ovep_encap_info_t *dinfop)
 	if (MBLKL(mp) < sizeof (vxlan_hdr_t))
 		return (EINVAL);
 	vxh = (vxlan_hdr_t *)mp->b_rptr;
-	if ((ntohl(vxh->vxlan_flags) & VXLAN_MAGIC) == 0)
+	if ((ntohl(vxh->vxlan_flags) & VXLAN_F_VDI) == 0)
 		return (EINVAL);
 
 	dinfop->ovdi_id = ntohl(vxh->vxlan_id) >> VXLAN_ID_SHIFT;
diff --git a/usr/src/uts/common/sys/vxlan.h b/usr/src/uts/common/sys/vxlan.h
index c0f4a0f119..d87786b507 100644
--- a/usr/src/uts/common/sys/vxlan.h
+++ b/usr/src/uts/common/sys/vxlan.h
@@ -30,7 +30,6 @@ extern "C" {
 #define	VXLAN_HDR_LEN	8
 #define	VXLAN_ID_LEN	3
 
-#define	VXLAN_MAGIC	0x08000000
 #define	VXLAN_F_VDI	0x08000000
 #define	VXLAN_ID_SHIFT	8