Date: Mon, 8 Sep 2014 00:16:34 +0000 (UTC) From: Bryan Venteicher <bryanv@FreeBSD.org> To: src-committers@freebsd.org, svn-src-projects@freebsd.org Subject: svn commit: r271242 - in projects/vxlan: sbin/ifconfig share/man/man4 Message-ID: <201409080016.s880GYAl098788@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: bryanv Date: Mon Sep 8 00:16:34 2014 New Revision: 271242 URL: http://svnweb.freebsd.org/changeset/base/271242 Log: Add initial man pages for vxlan Added: projects/vxlan/share/man/man4/vxlan.4 (contents, props changed) Modified: projects/vxlan/sbin/ifconfig/ifconfig.8 projects/vxlan/share/man/man4/Makefile Modified: projects/vxlan/sbin/ifconfig/ifconfig.8 ============================================================================== --- projects/vxlan/sbin/ifconfig/ifconfig.8 Sun Sep 7 22:56:57 2014 (r271241) +++ projects/vxlan/sbin/ifconfig/ifconfig.8 Mon Sep 8 00:16:34 2014 (r271242) @@ -28,7 +28,7 @@ .\" From: @(#)ifconfig.8 8.3 (Berkeley) 1/5/94 .\" $FreeBSD$ .\" -.Dd June 5, 2014 +.Dd September 7, 2014 .Dt IFCONFIG 8 .Os .Sh NAME @@ -2491,6 +2491,76 @@ argument is useless and hence deprecated .El .Pp The following parameters are used to configure +.Xr vxlan 4 +interfaces. +.Bl -tag -width indent +.It Cm vni Ar identifier +This value is a 16-bit VXLAN Network Identifier (VNI) that identifies the +virtual network segment membership of the interface. +.It Cm local Ar address +The source address used in the encapsulating IPv4/IPv6 header. +The address should already be assigned to an existing interface. +When the interface is configured in unicast mode, the listening socket +is bound to this address. +.It Cm remote Ar address +The interface can be configured in a unicast, or point-to-point, mode +to create a tunnel between two hosts. +This is the IP address of the remote end of the tunnel. +.It Cm group Ar address +The interface can be configured in a multicast mode +to create a virtual network of hosts. +This is the IP multicast group address the interface will join. +.It Cm localport Ar port +The port number the interface will listen on. +The default port number is 4789. +.It Cm remoteport Ar port +The destination port number used in the encapsulating IPv4/IPv6 header. +The remote host should be listening on this port. +The default port number is 4789. +Note some other implementations, such as Linux, +do not default to the IANA assigned port, +but instead listen on port 8472. +.It Cm portrange Ar low high +The range of source ports used in the encapsulating IPv4/IPv6 header. +The port selected within the range is based on a hash of the inner frame. +A range is useful to provide entropy within the outer IP header +for more effective load balancing. +The default range is between the +.Xr sysctl 8 +variables +.Va net.inet.ip.portrange.first +and +.Va net.inet.ip.portrange.last +.It Cm timeout Ar timeout +The maximum time, in seconds, before an entry in the forwarding table +is pruned. +The default is 1200 seconds (20 minutes). +.It Cm maxaddr Ar max +The maximum number of entries in the forwarding table. +The default is 2000. +.It Cm vxlandev Ar dev +When the interface is configured in multicast mode, the +.Ar Cm dev +interface is used to transmit IP multicast packets. +.It Cm ttl Ar ttl +The TTL used in the encapsulating IPv4/IPv6 header. +The default is 64. +.It Cm learn +The source IP address and inner source Ethernet MAC address of +received packets are used to dynamically populate the forwarding table. +When in multicast mode, an entry in the forwarding table allows the +interface to send the frame directly to the remote host instead of +broadcasting the frame to the multicast group. +This is the default. +.It Fl learn +The forwarding table is not populated by recevied packets. +.It Cm flush +Delete all dynamically-learned addresses from the forwarding table. +.It Cm flushall +Delete all addresses, including static addresses, from the forwarding table. +.El +.Pp +The following parameters are used to configure .Xr carp 4 protocol on an interface: .Bl -tag -width indent @@ -2695,6 +2765,7 @@ tried to alter an interface's configurat .Xr pfsync 4 , .Xr polling 4 , .Xr vlan 4 , +.Xr vxlan 4 , .Xr devd.conf 5 , .\" .Xr eon 5 , .Xr devd 8 , Modified: projects/vxlan/share/man/man4/Makefile ============================================================================== --- projects/vxlan/share/man/man4/Makefile Sun Sep 7 22:56:57 2014 (r271241) +++ projects/vxlan/share/man/man4/Makefile Mon Sep 8 00:16:34 2014 (r271242) @@ -563,6 +563,7 @@ MAN= aac.4 \ ${_virtio_scsi.4} \ vkbd.4 \ vlan.4 \ + vxlan.4 \ ${_vmx.4} \ vpo.4 \ vr.4 \ Added: projects/vxlan/share/man/man4/vxlan.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ projects/vxlan/share/man/man4/vxlan.4 Mon Sep 8 00:16:34 2014 (r271242) @@ -0,0 +1,203 @@ +.\" Copyright (c) 2014 Bryan Venteicher +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 7, 2014 +.Dt VXLAN 4 +.Os +.Sh NAME +.Nm vxlan +.Nd "Virtual eXtensible LAN interface" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device vxlan" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_vxlan_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver creates a virtual tunnel endpoint in a +.Nm +segment. +A +.Nm +segment is a virtual Layer 2 (Ethernet) network that is overlaid +in a Layer 3 (IP/UDP) network. +.Nm +is analogous to +.Xr vlan 4 +but is designed to be better suited for large, multiple tenant +data center environments. +.Pp +Each +.Nm +interface is created at runtime using interface cloning. +This is most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +The interface may be removed with the +.Xr ifconfig 8 +.Cm destroy +command. +.Pp +The +.Nm +driver creates a pseudo Ethernet network interface +that supports the usual network +.Xr ioctl 2 Ns s +and is thus can be used with +.Xr ifconfig 8 . +like any other Ethernet interface. +The +.Nm +interface encapsulates the Ethernet frame +by prepending IP/UDP and +.Nm +headers. +Thus, the encapsulated (inner) frame is able to transmitted +over a routed, Layer 3 network to the remote host. +.Pp +The +.Nm +interface may be configured in either unicast or multicast mode. +When in unicast mode, +the interface creates a tunnel to a single remote host, +and all traffic is transmitted to that host. +When in multicast mode, +the interface joins an IP multicast group, +and receives packets sent to the group address, +and transmits packets to either the multicast group address, +or directly the remote host if there is an appropriate +forwarding table entry. +.Pp +When the +.Nm +interface is brought up, a +.Xr UDP 4 +.Xr socket 9 +is created based on the configuration, +such as the local address for unicast mode or +the group address for multicast mode, +and the listening (local) port number. +Since multiple +.Nm +interfaces may be created that either +use the same local address +or join the same group address, +and use the same port, +the driver may share a socket among multiple interfaces. +However, each interface within a socket must belong to +a unique +.Nm +segment. +The analogous +.Xr vlan 4 +configuration would be a physical interface configured as +the parent device for multiple VLAN interfaces, each with +a unique VLAN tag. +Each +.Nm +segment is identified by a 24-bit value in the +.Nm +header called the +.Dq VXLAN Network Identifier , +or VNI. +.Pp +When configured with the +.Xr ifconfig 8 +.Cm learn +parameter, the interface dynamically creates forwarding table entries +from received packets. +An entry in the forwarding table maps the inner source MAC address +to the outer remote IP address. +During transmit, the interface attempts to lookup an entry for +the encapsulated destination MAC address. +If an entry is found, the IP address in the entry is used to directly +transmit the encapsulated frame to the destination. +Otherwise, when configured in multicast mode, +the interface must flood the frame to all hosts in the group. +The maximum number of entries in the table is configurable with the +.Xr ifconfig 8 +.Cm maxaddr +command. +Stale entries in the table periodically pruned. +The timeout is configurable with the +.Xr ifconfig 8 +.Cm timeout +command. +The table may be viewed with the +.Xr sysctl 8 +.Cm net.link.vlxan.N.ftable.dump +command. +.Sh MTU +Since the +.Nm +interface encapsulates the Ethernet frame with an IP, UDP, and +.Nm +header, the resulting frame may be larger than the MTU of the +physical network. +The +.Nm +specification recommends the physical network MTU be configured +to use jumbo frames to accommodate the encapsulated frame size. +Alternatively, the +.Xr ifconfig 8 +.Cm mtu +command may be used to reduce the MTU size on the +.Nm +interface to allow the encapsulated frame to fit in the +physical network current MTU. +.Sh SEE ALSO +.Xr ifconfig 8 , +.Xr inet 4 , +.Xr inet 6 , +.Xr sysctl 8 , +.Xr vlan 8 +.Rs +.%A "M. Mahalingam" +.%A "et al" +.%T "Virtual eXtensible Local Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks" +.%D August 2014 +.%O "RFC 7348" +.Re +.Sh AUTHOR +.An -nosplit +The +.Nm +driver was written by +.An Bryan Venteicher Aq bryanv@freebsd.org .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409080016.s880GYAl098788>