Merge branch 'master' into newdirectives

13 files changed, 1108 insertions, 566 deletions

diff --git a/docs/interfaces/addresses.rst b/docs/interfaces/addresses.rst
deleted file mode 100644
index 709490c8..00000000
--- a/docs/interfaces/addresses.rst
+++ /dev/null
@@ -1,175 +0,0 @@
-.. _interfaces-addresses:
-
-Addresses
----------
-
-Each interface can be configured with a description and address. Interface
-addresses might be:
-
-* Static IPv4 ``address 172.16.51.129/24``
-* Static IPv6 ``address 2001:db8:1::ffff/64``
-* DHCP IPv4 ``address dhcp``
-* DHCP IPv6 ``address dhcpv6``
-
-.. cfgcmd:: set interfaces ethernet eth0 description 'OUTSIDE'
-
-   An interface description is assigned using the following command:
-
-IPv4
-^^^^
-
-Static Address
-**************
-
-This method is supported on all interfaces, apart from OpenVPN that uses
-different syntax and wireless modems that are always autoconfigured through
-PPP.
-
-The command is ``set interfaces $type $name address $address``. Examples:
-
-.. code-block:: none
-
-  set interfaces ethernet eth0 address 192.0.2.1/24
-  set interfaces tunnel tun0 address 10.0.0.1/30
-  set interfaces bridge br0 address 203.0.113.45/26
-  set interfaces ethernet eth0 vif 30 address 198.51.100.254/24
-
-DHCP
-****
-
-This method is supported on all physical interfaces, and those that are
-directly connected to a physical interface (Ethernet, VLAN, Bridge, Bond,
-Pseudo-ethernet, Wireless).
-
-The command is ``set interfaces $type $name address dhcp``. Examples:
-
-.. code-block:: none
-
-  set interfaces ethernet eth0 vif 90 address dhcp
-  set interfaces bridge br0 address dhcp
-
-IPv6
-^^^^
-
-Static Address
-**************
-
-This method is supported on all interfaces, apart from OpenVPN that uses
-different syntax and wireless modems that are always autoconfigured through
-PPP. Static IPv6 addresses are supported on all interfaces
-except :ref:`tunnel-interface`.
-
-The command is ``set interfaces $type $name address $address``. Examples:
-
-.. code-block:: none
-
-  set interfaces ethernet eth0 address 2001:db8:100::ffff/64
-  set interfaces tunnel tun0 address 2001:db8::1/64
-  set interfaces bridge br0 address  2001:db8:200::1/64
-  set interfaces ethernet eth0 vif 30 address 2001:db8:3::ffff/64
-
-DHCP
-****
-
-This method is supported on all physical interfaces, and those that are
-directly connected to a physical interface (Ethernet, VLAN, Bridge, Bond,
-Pseudo-ethernet, Wireless).
-
-The command is `set interfaces $type $name address dhcpv6`. Examples:
-
-.. code-block:: none
-
-  set interfaces bonding bond1 address dhcpv6
-  set interfaces bridge br0 vif 56 address dhcpv6
-
-Autoconfiguration (SLAAC)
-*************************
-
-SLAAC is specified in :rfc:`4862`. This method is supported on all physical
-interfaces, and those that are directly connected to a physical interface
-(Ethernet, VLAN, Bridge, Bond, Pseudo-ethernet, Wireless).
-
-The command is ``set interfaces $type $name ipv6 address autoconf``. Examples:
-
-.. code-block:: none
-
-  set interfaces ethernet eth0 vif 90 ipv6 address autoconf
-  set interfaces bridge br0 ipv6 address autoconf
-
-.. note:: This method automatically disables IPv6 traffic forwarding on the
-   interface in question.
-
-EUI-64
-******
-
-EUI-64 (64-Bit Extended Unique Identifier) as specified in :rfc:`4291`. IPv6
-addresses in /64 networks can be automatically generated from the prefix and
-MAC address, if you specify the prefix.
-
-The command is `set interfaces $type $name ipv6 address eui64 $prefix`.
-Examples:
-
-.. code-block:: none
-
-  set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64
-  set interfaces pseudo-ethernet peth0 ipv6 address eui64 2001:db8:aa::/64
-
-
-Router Advertisements
-*********************
-
-Router advertisements are described in :rfc:`4861#section-4.6.2`. They are part
-of what is known as SLAAC (Stateless Address Autoconfiguration).
-
-To enable or disable, use:
-
-.. code-block:: none
-
-  set interfaces <interface> ipv6 router-advert send-advert <true|false>
-
-
-To set the options described in "Router Advertisement Message Format":
-
-.. code-block:: none
-
-  vyos@vyos#  set interfaces <interface> ipv6 router-advert
-  Possible completions:
-     cur-hop-limit         Value to be placed in the "Current Hop Limit" field in RAs
-     default-lifetime      Value to be placed in "Router Lifetime" field in RAs
-     default-preference    Default router preference
-     link-mtu              Value of link MTU to place in RAs
-     managed-flag          Value for "managed address configuration" flag in RAs
-     max-interval          Maximum interval between unsolicited multicast RAs
-     min-interval          Minimum interval between unsolicited multicast RAs
-  +  name-server           IPv6 address of a Recursive DNS Server
-     other-config-flag     Value to be placed in the "other configuration" flag in RAs
-  +> prefix                IPv6 prefix to be advertised in Router Advertisements (RAs)
-     reachable-time        Value to be placed in "Reachable Time" field in RAs
-     retrans-timer         Value to place in "Retrans Timer" field in RAs.
-     send-advert           Enable/disable sending RAs
-
-
-Prefix Information
-~~~~~~~~~~~~~~~~~~
-
-Prefix information is described in :rfc:`4861#section-4.6.2`.
-
-.. code-block:: none
-
-  vyos@vyos# set interfaces <interface> ipv6 router-advert prefix <h:h:h:h:h:h:h:h/x>
-  Possible completions:
-    autonomous-flag       Whether prefix can be used for address auto-configuration
-    on-link-flag          Flag that prefix can be used for on-link determination
-    preferred-lifetime    Time in seconds that the prefix will remain preferred
-    valid-lifetime        Time in seconds that the prefix will remain valid
-
-Receiving Router Advertisements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To receive and accept RAs on an interface, you need to enable it with the
-following configuration command
-
-.. code-block:: none
-
-  vyos@vyos# set system sysctl custom net.ipv6.conf.<interface>.accept_ra value 2
-
diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst
new file mode 100644
index 00000000..00c1c73e
--- /dev/null
+++ b/docs/interfaces/advanced-index.rst
@@ -0,0 +1,19 @@
+.. _network-interfaces:
+
+##################
+Network Interfaces
+##################
+
+.. toctree::
+   :maxdepth: 1
+
+   dummy
+   bridge
+   bond
+   l2tpv3
+   wireless
+   tunnel
+   vlan
+   qinq
+   vxlan
+   geneve
diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst
new file mode 100644
index 00000000..c652c7bb
--- /dev/null
+++ b/docs/interfaces/basic-index.rst
@@ -0,0 +1,12 @@
+.. _basic_network-interfaces:
+
+################
+Basic Interfaces
+################
+
+.. toctree::
+   :maxdepth: 1
+
+   ethernet
+   loopback
+   pppoe
diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst
index 880c7580..c0fc0ca6 100644
--- a/docs/interfaces/bond.rst
+++ b/docs/interfaces/bond.rst
@@ -1,72 +1,362 @@
 .. _bond-interface:
 
+####
 Bond
-----
+####
 
-You can combine (aggregate) 2 or more physical interfaces into a single
-logical one. It's called bonding, or LAG, or ether-channel, or port-channel.
+The bonding interface provides a method for aggregating multiple network
+interfaces into a single logical "bonded" interface, or LAG, or ether-channel,
+or port-channel. The behavior of the bonded interfaces depends upon the mode;
+generally speaking, modes provide either hot standby or load balancing services.
+Additionally, link integrity monitoring may be performed.
 
-Create interface bondX, where X is just a number:
+Configuration
+#############
 
-.. code-block:: none
+Address
+-------
 
-  set interfaces bonding bond0 description 'my-sw1 int 23 and 24'
+.. cfgcmd:: set interfaces bonding <interface> address <address | dhcp | dhcpv6>
 
-You are able to choose a hash policy:
+   Configure interface `<interface>` with one or more interface addresses.
 
-.. code-block:: none
+   * **address** can be specified multiple times as IPv4 and/or IPv6 address,
+     e.g. 192.0.2.1/24 and/or 2001:db8::1/64
+   * **dhcp** interface address is received by DHCP from a DHCP server on this
+     segment.
+   * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on
+     this segment.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces bonding bond0 address 192.0.2.1/24
+     set interfaces bonding bond0 address 192.0.2.2/24
+     set interfaces bonding bond0 address 2001:db8::ffff/64
+     set interfaces bonding bond0 address 2001:db8:100::ffff/64
+
+
+.. cfgcmd:: set interfaces bonding <interface> ipv6 address autoconf
+
+   .. include:: common-ipv6-addr-autoconf.txt
+
+.. cfgcmd:: set interfaces bonding <interface> ipv6 address eui64 <prefix>
+
+   :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in
+   :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address.
+
+   .. code-block:: none
+
+     set interfaces bonding bond0 ipv6 address eui64 2001:db8:beef::/64
+
+
+Link Administration
+-------------------
+
+.. cfgcmd:: set interfaces bonding <interface> description <description>
+
+   Assign given `<description>` to interface. Description will also be passed
+   to SNMP monitoring systems.
+
+
+.. cfgcmd:: set interfaces bonding <interface> disable
+
+   Disable given `<interface>`. It will be placed in administratively down
+   (``A/D``) state.
+
+.. cfgcmd:: set interfaces bonding <interface> mac <mac-address>
+
+   Configure user defined :abbr:`MAC (Media Access Control)` address on given
+   `<interface>`.
+
+.. cfgcmd:: set interfaces bonding <interface> mode <mode>
+
+   Specifies one of the bonding policies. The default is 802.3ad. Possible
+   values are:
+
+   * **802.3ad** - IEEE 802.3ad Dynamic link aggregation. Creates aggregation
+     groups that share the same speed and duplex settings. Utilizes all slaves
+     in the active aggregator according to the 802.3ad specification.
+
+     Slave selection for outgoing traffic is done according to the transmit
+     hash policy, which may be changed from the default simple XOR policy via
+     the :cfgcmd:`hash-policy` option, documented below.
+
+     .. note:: Not all transmit policies may be 802.3ad compliant, particularly
+        in regards to the packet mis-ordering requirements of section 43.2.4
+        of the 802.3ad standard.
+
+   * **active-backup** - Active-backup policy: Only one slave in the bond is
+     active. A different slave becomes active if, and only if, the active slave
+     fails. The bond's MAC address is externally visible on only one port
+     (network adapter) to avoid confusing the switch.
+
+     When a failover occurs in active-backup mode, bonding will issue one or
+     more gratuitous ARPs on the newly active slave. One gratuitous ARP is
+     issued for the bonding master interface and each VLAN interfaces
+     configured above it, provided that the interface has at least one IP
+     address configured. Gratuitous ARPs issued for VLAN interfaces are tagged
+     with the appropriate VLAN id.
+
+     This mode provides fault tolerance. The :cfgcmd:`primary` option,
+     documented below, affects the behavior of this mode.
+
+   * **broadcast** - Broadcast policy: transmits everything on all slave
+     interfaces.
+
+     This mode provides fault tolerance.
+
+   * **round-robin** - Round-robin policy: Transmit packets in sequential
+     order from the first available slave through the last.
+
+     This mode provides load balancing and fault tolerance.
+
+   * **transmit-load-balance** - Adaptive transmit load balancing: channel
+     bonding that does not require any special switch support.
+
+     Incoming traffic is received by the current slave. If the receiving slave
+     fails, another slave takes over the MAC address of the failed receiving
+     slave.
+
+   * **adaptive-load-balance** - Adaptive load balancing: includes
+     transmit-load-balance plus receive load balancing for IPV4 traffic, and
+     does not require any special switch support. The receive load balancing
+     is achieved by ARP negotiation. The bonding driver intercepts the ARP
+     Replies sent by the local system on their way out and overwrites the
+     source hardware address with the unique hardware address of one of the
+     slaves in the bond such that different peers use different hardware
+     addresses for the server.
+
+     Receive traffic from connections created by the server is also balanced.
+     When the local system sends an ARP Request the bonding driver copies and
+     saves the peer's IP information from the ARP packet. When the ARP Reply
+     arrives from the peer, its hardware address is retrieved and the bonding
+     driver initiates an ARP reply to this peer assigning it to one of the
+     slaves in the bond. A problematic outcome of using ARP negotiation for
+     balancing is that each time that an ARP request is broadcast it uses the
+     hardware address of the bond. Hence, peers learn the hardware address
+     of the bond and the balancing of receive traffic collapses to the current
+     slave. This is handled by sending updates (ARP Replies) to all the peers
+     with their individually assigned hardware address such that the traffic
+     is redistributed. Receive traffic is also redistributed when a new slave
+     is added to the bond and when an inactive slave is re-activated. The
+     receive load is distributed sequentially (round robin) among the group
+     of highest speed slaves in the bond.
+
+     When a link is reconnected or a new slave joins the bond the receive
+     traffic is redistributed among all active slaves in the bond by initiating
+     ARP Replies with the selected MAC address to each of the clients. The
+     updelay parameter (detailed below) must be set to a value equal or greater
+     than the switch's forwarding delay so that the ARP Replies sent to the
+     peers will not be blocked by the switch.
+
+   * **xor-hash** - XOR policy: Transmit based on the selected transmit
+     hash policy.  The default policy is a simple [(source MAC address XOR'd
+     with destination MAC address XOR packet type ID) modulo slave count].
+     Alternate transmit policies may be selected via the :cfgcmd:`hash-policy`
+     option, described below.
+
+     This mode provides load balancing and fault tolerance.
+
+.. cfgcmd:: set interfaces bonding <interface> hash-policy <policy>
+
+   * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field
+     to generate the hash. The formula is
+
+     .. code-block:: none
+
+       hash = source MAC XOR destination MAC XOR packet type ID
+       slave number = hash modulo slave count
 
-  vyos@vyos# set interfaces bonding bond0 hash-policy
-  Possible completions:
-    layer2       use MAC addresses to generate the hash (802.3ad)
-    layer2+3     combine MAC address and IP address to make hash
-    layer3+4     combine IP address and port to make hash
+     This algorithm will place all traffic to a particular network peer on
+     the same slave.
 
-For example:
+     This algorithm is 802.3ad compliant.
+
+   * **layer2+3** - This policy uses a combination of layer2 and layer3
+     protocol information to generate the hash. Uses XOR of hardware MAC
+     addresses and IP addresses to generate the hash. The formula is:
+
+     .. code-block:: none
+
+       hash = source MAC XOR destination MAC XOR packet type ID
+       hash = hash XOR source IP XOR destination IP
+       hash = hash XOR (hash RSHIFT 16)
+       hash = hash XOR (hash RSHIFT 8)
+
+     And then hash is reduced modulo slave count.
+
+     If the protocol is IPv6 then the source and destination addresses are
+     first hashed using ipv6_addr_hash.
+
+     This algorithm will place all traffic to a particular network peer on the
+     same slave. For non-IP traffic, the formula is the same as for the layer2
+     transmit hash policy.
+
+     This policy is intended to provide a more balanced distribution of traffic
+     than layer2 alone, especially in environments where a layer3 gateway
+     device is required to reach most destinations.
+
+     This algorithm is 802.3ad compliant.
+
+   * **layer3+4** - This policy uses upper layer protocol information, when
+     available, to generate the hash. This allows for traffic to a particular
+     network peer to span multiple slaves, although a single connection will
+     not span multiple slaves.
+
+     The formula for unfragmented TCP and UDP packets is
+
+     .. code-block:: none
+
+       hash = source port, destination port (as in the header)
+       hash = hash XOR source IP XOR destination IP
+       hash = hash XOR (hash RSHIFT 16)
+       hash = hash XOR (hash RSHIFT 8)
+
+     And then hash is reduced modulo slave count.
+
+     If the protocol is IPv6 then the source and destination addresses are
+     first hashed using ipv6_addr_hash.
+
+     For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol
+     traffic, the source and destination port information is omitted. For
+     non-IP traffic, the formula is the same as for the layer2 transmit hash
+     policy.
+
+     This algorithm is not fully 802.3ad compliant. A single TCP or UDP
+     conversation containing both fragmented and unfragmented packets will see
+     packets striped across two interfaces. This may result in out of order
+     delivery. Most traffic types will not meet this criteria, as TCP rarely
+     fragments traffic, and most UDP traffic is not involved in extended
+     conversations. Other implementations of 802.3ad may or may not tolerate
+     this noncompliance.
+
+.. cfgcmd:: set interfaces bonding <interface> primary <interface>
+
+    An `<interface>` specifying which slave is the primary device. The specified
+    device will always be the active slave while it is available. Only when the
+    primary is off-line will alternate devices be used. This is useful when one
+    slave is preferred over another, e.g., when one slave has higher throughput
+    than another.
+
+    The primary option is only valid for active-backup, transmit-load-balance,
+    and adaptive-load-balance mode.
+
+.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time>
+
+   Specifies the ARP link monitoring `<time>` in seconds.
+
+   The ARP monitor works by periodically checking the slave devices to determine
+   whether they have sent or received traffic recently (the precise criteria
+   depends upon the bonding mode, and the state of the slave). Regular traffic
+   is generated via ARP probes issued for the addresses specified by the
+   :cfgcmd:`arp-monitor target` option.
+
+   If ARP monitoring is used in an etherchannel compatible mode (modes
+   round-robin and xor-hash), the switch should be configured in a mode that
+   evenly distributes packets across all links. If the switch is configured to
+   distribute the packets in an XOR fashion, all replies from the ARP targets
+   will be received on the same link which could cause the other team members
+   to fail.
+
+   A value of 0 disables ARP monitoring. The default value is 0.
+
+.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address>
+
+   Specifies the IP addresses to use as ARP monitoring peers when
+   :cfgcmd:`arp-monitor interval` option is > 0. These are the targets of the
+   ARP request sent to determine the health of the link to the targets.
+
+   Multiple target IP addresses can be specified. At least one IP address must
+   be given for ARP monitoring to function.
+
+   The maximum number of targets that can be specified is 16. The default value
+   is no IP addresses.
+
+Member Interfaces
+-----------------
+
+.. cfgcmd:: set interfaces bonding <interface> member interface <member>
+
+   Enslave `<member>` interface to bond `<interface>`.
+
+Example
+-------
+
+The following configuration on VyOS applies to all following 3rd party vendors.
+It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with
+a per VIF IPv4 address.
 
 .. code-block:: none
 
+  # Create bonding interface bond0 with 802.3ad LACP
   set interfaces bonding bond0 hash-policy 'layer2'
+  set interfaces bonding bond0 mode '802.3ad'
 
-You may want to set IEEE 802.3ad Dynamic link aggregation (802.3ad) AKA LACP
-(don't forget to setup it on the other end of these links):
+  # Add the required vlans and IPv4 addresses on them
+  set interfaces bonding bond0 vif 10 address 192.168.0.1/24
+  set interfaces bonding bond0 vif 100 address 10.10.10.1/24
 
-.. code-block:: none
+  # Add the member interfaces to the bonding interface
+  set interfaces bonding bond0 member interface eth1
+  set interfaces bonding bond0 member interface eth2
+
+Cisco
+^^^^^
 
- set interfaces bonding bond0 mode '802.3ad'
+An example configuration for a Cisco PortChannel to VyOS would be nice
 
-or some other modes:
+Juniper EX Switch
+^^^^^^^^^^^^^^^^^
+
+For a headstart you can use the below example on how to build a bond with two
+interfaces from VyOS to a Juniper EX Switch system.
 
 .. code-block:: none
 
-  vyos@vyos# set interfaces bonding bond0 mode
-  Possible completions:
-    802.3ad      IEEE 802.3ad Dynamic link aggregation (Default)
-    active-backup
-                 Fault tolerant: only one slave in the bond is active
-    broadcast    Fault tolerant: transmits everything on all slave interfaces
-    round-robin  Load balance: transmit packets in sequential order
-    transmit-load-balance
-                 Load balance: adapts based on transmit load and speed
-    adaptive-load-balance
-                 Load balance: adapts based on transmit and receive plus ARP
-    xor-hash     Load balance: distribute based on MAC address
-
-Now bond some physical interfaces into bond0:
+  # Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s
+  set interfaces ae0 aggregated-ether-options link-speed 10g
+  set interfaces ae0 aggregated-ether-options lacp active
+
+  # Create layer 2 on the aggregated ethernet device with trunking for our vlans
+  set interfaces ae0 unit 0 family ethernet-switching port-mode trunk
+
+  # Add the required vlans to the device
+  set interfaces ae0 unit 0 family ethernet-switching vlan members 10
+  set interfaces ae0 unit 0 family ethernet-switching vlan members 100
+
+  # Add the two interfaces to the aggregated ethernet device, in this setup both
+  # ports are on the same switch (switch 0, module 1, port 0 and 1)
+  set interfaces xe-0/1/0 ether-options 802.3ad ae0
+  set interfaces xe-0/1/1 ether-options 802.3ad ae0
+
+  # But this can also be done with multiple switches in a stack, a virtual
+  # chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches)
+  set interfaces xe-0/1/0 ether-options 802.3ad ae0
+  set interfaces xe-1/1/0 ether-options 802.3ad ae0
+
+Aruba/HP
+^^^^^^^^
+
+For a headstart you can use the below example on how to build a bond,port-channel
+with two interfaces from VyOS to a Aruba/HP 2510G switch.
 
 .. code-block:: none
 
-  set interfaces bonding bond0 member interface eth0
-  set interfaces bonding bond0 member interface eth1
+  # Create trunk with 2 member interfaces (interface 1 and 2) and LACP
+  trunk 1-2 Trk1 LACP
 
-After a commit you may treat bond0 as almost a physical interface (you can't
-change its` duplex, for example) and assign IPs or VIFs on it.
+  # Add the required vlans to the trunk
+  vlan 10 tagged Trk1
+  vlan 100 tagged Trk1
 
-You may check the result:
+Operation
+#########
 
 .. code-block:: none
 
-  vyos@vyos# run sh interfaces bonding
+  vyos@vyos:~$ show interfaces bonding
   Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
   Interface        IP Address                        S/L  Description
   ---------        ----------                        ---  -----------
diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst
index a7bbbca6..d51f4ec2 100644
--- a/docs/interfaces/bridge.rst
+++ b/docs/interfaces/bridge.rst
@@ -1,112 +1,254 @@
 .. _bridge-interface:
 
+######
 Bridge
-------
+######
 
-Interfaces in VyOS can be bridged together to provide software switching of
-Layer-2 traffic.
+A Bridge is a way to connect two Ethernet segments together in a protocol
+independent way. Packets are forwarded based on Ethernet address, rather than
+IP address (like a router). Since forwarding is done at Layer 2, all protocols
+can go transparently through a bridge. The Linux bridge code implements a
+subset of the ANSI/IEEE 802.1d standard.
 
-A bridge is created when a bridge interface is defined. In the example below
-we create a bridge named br100 with eth1 and eth2 as the bridge member ports.
+Configuration
+#############
 
-.. code-block:: none
+Address
+-------
 
-  set interfaces bridge 'br100'
-  set interfaces bridge br100 member interface eth1
-  set interfaces bridge br100 member interface eth2
+.. cfgcmd:: set interfaces bridge <interface> address <address | dhcp | dhcpv6>
 
-Each bridge member can be assiged a port cost and priority using the following
-commands:
+   Configure interface `<interface>` with one or more interface addresses.
 
-.. code-block:: none
+   * **address** can be specified multiple times as IPv4 and/or IPv6 address,
+     e.g. 192.0.2.1/24 and/or 2001:db8::1/64
+   * **dhcp** interface address is received by DHCP from a DHCP server on this
+     segment.
+   * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on
+     this segment.
 
-  set interfaces bridge br100 member interface eth1 cost 10
-  set interfaces bridge br100 member interface eth1 priority 1024
+   Example:
 
-Interfaces assigned to a bridge do not have address configuration. An IP
-address can be assigned to the bridge interface itself, however, like any
-normal interface.
+   .. code-block:: none
 
-.. code-block:: none
+     set interfaces bridge br0 address 192.0.2.1/24
+     set interfaces bridge br0 address 192.0.2.2/24
+     set interfaces bridge br0 address 2001:db8::ffff/64
+     set interfaces bridge br0 address 2001:db8:100::ffff/64
 
-  set interfaces bridge br100 address '192.168.100.1/24'
-  set interfaces bridge br100 address '2001:db8:100::1/64'
 
-Example Result:
+.. cfgcmd:: set interfaces bridge <interface> ipv6 address autoconf
 
-.. code-block:: none
+   .. include:: common-ipv6-addr-autoconf.txt
 
-  bridge br100 {
-      address 192.168.100.1/24
-      address 2001:db8:100::1/64
-      member {
-          interface eth1 {
-              cost 10
-              priority 1024
-          }
-          interface eth2 {
-          }
-      }
+.. cfgcmd:: set interfaces bridge <interface> ipv6 address eui64 <prefix>
 
-  }
-  [...]
+   :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in
+   :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address.
 
-In addition to normal IP interface configuration, bridge interfaces support
-Spanning-Tree Protocol. STP is disabled by default.
+   .. code-block:: none
 
-.. note:: Please use caution when introducing spanning-tree protocol on a
-   network as it may result in topology changes.
+     set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64
 
-To enable spanning-tree use the `set interfaces bridge <name> stp` command:
 
-.. code-block:: none
+.. cfgcmd:: set interfaces bridge <interface> aging <time>
 
-  set interfaces bridge br100 stp
+   MAC address aging `<time`> in seconds (default: 300).
 
-STP `priority`, `forwarding-delay`, `hello-time`, and `max-age` can be
-configured for the bridge. The MAC aging time can also be configured
-using the `aging` directive.
 
-The `show bridge` operational command can be used to display configured
-bridges:
+.. cfgcmd:: set interfaces bridge <interface> max-age <time>
 
-.. code-block:: none
+   Bridge maximum aging `<time>` in seconds (default: 20).
+
+   If a another bridge in the spanning tree does not send out a hello packet
+   for a long period of time, it is assumed to be dead.
+
+
+Link Administration
+-------------------
+
+.. cfgcmd:: set interfaces bridge <interface> description <description>
+
+   Assign given `<description>` to interface. Description will also be passed
+   to SNMP monitoring systems.
+
+
+.. cfgcmd:: set interfaces bridge <interface> disable
+
+   Disable given `<interface>`. It will be placed in administratively down
+   (``A/D``) state.
+
+
+.. cfgcmd:: set interfaces bridge <interface> disable-flow-control
+
+   Disable Ethernet flow control (pause frames).
+
+
+.. cfgcmd:: set interfaces bridge <interface> mac <mac-address>
+
+   Configure user defined :abbr:`MAC (Media Access Control)` address on given
+   `<interface>`.
+
+
+.. cfgcmd:: set interfaces bridge <interface> igmp querier
+
+   Enable IGMP querier
+
+
+Member Interfaces
+-----------------
+
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+
+   Assign `<member>` interface to bridge `<interface>`. A completion helper
+   will help you with all allowed interfaces which can be bridged. This includes
+   :ref:`ethernet-interface`, :ref:`bond-interface`, :ref:`l2tpv3-interface`,
+   :ref:`openvpn`, :ref:`vxlan-interface`, :ref:`wireless-interface`,
+   :ref:`tunnel-interface` and :ref:`geneve-interface`.
+
+
+.. cfgcmd:: set interfaces bridge <interface> member interface <member> priority <priority>
+
+   Configure individual bridge port `<priority>`.
+
+   Each bridge has a relative priority and cost. Each interface is associated
+   with a port (number) in the STP code. Each has a priority and a cost, that
+   is used to decide which is the shortest path to forward a packet. The lowest
+   cost path is always used unless the other path is down. If you have multiple
+   bridges and interfaces then you may need to adjust the priorities to achieve
+   optimium performance.
+
+
+.. cfgcmd:: set interfaces bridge <interface> member interface <member> cost <cost>
 
-  vyos@vyos:~$ show bridge
-  bridge name     bridge id               STP enabled     interfaces
-  br100           0000.000c29443b19       yes             eth1.100
+   Path `<cost>` value for Spanning Tree Protocol. Each interface in a bridge
+   could have a different speed and this value is used when deciding which
+   link to use. Faster interfaces should have lower costs.
 
-If spanning-tree is enabled, the `show bridge <name> spanning-tree` command
-can be used to show STP configuration:
+
+STP Parameter
+-------------
+
+:abbr:`STP (Spanning Tree Protocol)` is a network protocol that builds a
+loop-free logical topology for Ethernet networks. The basic function of STP is
+to prevent bridge loops and the broadcast radiation that results from them.
+Spanning tree also allows a network design to include backup links providing
+fault tolerance if an active link fails.
+
+.. cfgcmd:: set interfaces bridge <interface> stp
+
+   Enable spanning tree protocol. STP is disabled by default.
+
+
+.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay>
+
+   Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15).
+
+   Forwarding delay time is the time spent in each of the Listening and
+   Learning states before the Forwarding state is entered. This delay is so
+   that when a new bridge comes onto a busy network it looks at some traffic
+   before participating.
+
+
+.. cfgcmd:: set interfaces bridge <interface> hello-time <interval>
+
+   Spanning Tree Protocol hello advertisement `<interval>` in seconds
+   (default: 2).
+
+   Periodically, a hello packet is sent out by the Root Bridge and the
+   Designated Bridges. Hello packets are used to communicate information about
+   the topology throughout the entire Bridged Local Area Network.
+
+
+Exammple
+--------
+
+Creating a bridge interface is very simple. In this example we will have:
+
+* A bridge named `br100`
+* Member interfaces `eth1` and VLAN 10 on interface `eth2`
+* Enable STP
+* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64
 
 .. code-block:: none
 
-  vyos@vyos:~$ show bridge br100 spanning-tree
-  br100
-   bridge id              0000.000c29443b19
-   designated root        0000.000c29443b19
-   root port                 0                    path cost                  0
-   max age                  20.00                 bridge max age            20.00
-   hello time                2.00                 bridge hello time          2.00
-   forward delay            15.00                 bridge forward delay      15.00
-   ageing time             300.00
-   hello timer               0.47                 tcn timer                  0.00
-   topology change timer     0.00                 gc timer                  64.63
-   flags
-
-  eth1.100 (1)
-   port id                8001                    state                forwarding
-   designated root        0000.000c29443b19       path cost                  4
-   designated bridge      0000.000c29443b19       message age timer          0.00
-   designated port        8001                    forward delay timer        0.00
-   designated cost           0                    hold timer                 0.00
-   flags
-
-The MAC address-table for a bridge can be displayed using the
-`show bridge <name> macs` command:
+  set interfaces bridge br100 address 192.0.2.1/24
+  set interfaces bridge br100 address 2001:db8::ffff/64
+  set interfaces bridge br100 member interface eth1
+  set interfaces bridge br100 member interface eth2.10
+  set interfaces bridge br100 stp
+
+This results in the active configuration:
 
 .. code-block:: none
 
-  vyos@vyos:~$ show bridge br100 macs
-  port no mac addr                is local?       ageing timer
-    1     00:53:29:44:3b:19       yes                0.00
+   vyos@vyos# show interfaces bridge br100
+    address 192.0.2.1/24
+    address 2001:db8::ffff/64
+    member {
+        interface eth1 {
+        }
+        interface eth2.10 {
+        }
+    }
+    stp
+
+
+Operation
+=========
+
+.. opcmd:: show bridge
+
+   The `show bridge` operational command can be used to display configured
+   bridges:
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show bridge
+     bridge name     bridge id               STP enabled     interfaces
+     br100           8000.0050569d11df       yes             eth1
+                                                           eth2.10
+
+.. opcmd:: show bridge <name> spanning-tree
+
+   Show bridge `<name>` STP configuration.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show bridge br100 spanning-tree
+     br100
+      bridge id              8000.0050569d11df
+      designated root        8000.0050569d11df
+      root port                 0                    path cost                  0
+      max age                  20.00                 bridge max age            20.00
+      hello time                2.00                 bridge hello time          2.00
+      forward delay            14.00                 bridge forward delay      14.00
+      ageing time             300.00
+      hello timer               0.06                 tcn timer                  0.00
+      topology change timer     0.00                 gc timer                 242.02
+      flags
+
+     eth1 (1)
+      port id                8001                    state                  disabled
+      designated root        8000.0050569d11df       path cost                100
+      designated bridge      8000.0050569d11df       message age timer          0.00
+      designated port        8001                    forward delay timer        0.00
+      designated cost           0                    hold timer                 0.00
+      flags
+
+     eth2.10 (2)
+      port id                8002                    state                  disabled
+      designated root        8000.0050569d11df       path cost                100
+      designated bridge      8000.0050569d11df       message age timer          0.00
+      designated port        8002                    forward delay timer        0.00
+      designated cost           0                    hold timer                 0.00
+
+.. opcmd: show bridge <name> macs
+
+   Show bridge Media Access Control (MAC) address table
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show bridge br100 macs
+     port no mac addr                is local?       ageing timer
+       1     00:53:29:44:3b:19       yes                0.00
diff --git a/docs/interfaces/common-ipv6-addr-autoconf.txt b/docs/interfaces/common-ipv6-addr-autoconf.txt
new file mode 100644
index 00000000..838b299f
--- /dev/null
+++ b/docs/interfaces/common-ipv6-addr-autoconf.txt
@@ -0,0 +1,12 @@
+:abbr:`SLAAC (Stateless Address Autoconfiguration)`

+:rfc:`4862`. IPv6 hosts can configure themselves automatically when connected

+to an IPv6 network using the Neighbor Discovery Protocol via :abbr:`ICMPv6

+(Internet Control Message Protocol version 6)` router discovery messages.

+When first connected to a network, a host sends a link-local router

+solicitation multicast request for its configuration parameters; routers

+respond to such a request with a router advertisement packet that contains

+Internet Layer configuration parameters.

+

+.. note:: This method automatically disables IPv6 traffic forwarding on the

+  interface in question.

+

diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst
index 9dbb9668..4627d1dc 100644
--- a/docs/interfaces/dummy.rst
+++ b/docs/interfaces/dummy.rst
@@ -1,25 +1,90 @@
 .. _dummy-interface:
 
+#####
 Dummy
------
-
-Dummy interfaces are much like the loopback interface, except you can have
-as many as you want. Dummy interfaces can be used as interfaces that always
-stay up (in the same fashion to loopbacks in Cisco IOS), or for testing
-purposes.
-
-Configuration commands:
-
-.. code-block:: none
-
-  vyos@vyos# set interfaces dummy dum0
-  Possible completions:
-  +  address      IP address
-     description  Interface description
-     disable      Disable interface
-   > ip           IPv4 routing parameters
-   > ipv6         IPv6 routing parameters
-     redirect     Incoming packet redirection destination
-   > traffic-policy
-                  Traffic-policy for interface
+#####
+
+The dummy interface is really a little exotic, but rather useful nevertheless.
+Dummy interfaces are much like the :ref:`loopback-interface` interface, except
+you can have as many as you want.
+
+.. note:: Dummy interfaces can be used as interfaces that always stay up (in
+   the same fashion to loopbacks in Cisco IOS), or for testing purposes.
+
+.. hint:: A Dummy interface is always up, thus it could be used for
+   management traffic or as source/destination for and :abbr:`IGP (Interior
+   Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependant
+   on physical link states and multiple routes can be choosen to the
+   destination. A :ref:`dummy-interface` Interface should always be preferred
+   over a :ref:`loopback-interface` interface.
+
+
+Configuration
+#############
+
+Address
+-------
+
+.. cfgcmd:: set interfaces dummy <interface> address <address | dhcp | dhcpv6>
+
+   Configure dummy interface `<interface>` with one or more interface
+   addresses. Address can be specified multiple times as IPv4 and/or IPv6
+   address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces dummy dum10 address 192.0.2.1/24
+     set interfaces dummy dum10 address 192.0.2.2/24
+     set interfaces dummy dum10 address 2001:db8::ffff/64
+     set interfaces dummy dum10 address 2001:db8:100::ffff/64
+
+Link Administration
+-------------------
+
+.. cfgcmd:: set interfaces dummy <interface> description <description>
+
+   Assign given `<description>` to interface. Description will also be passed
+   to SNMP monitoring systems.
+
+.. cfgcmd:: set interfaces dummy <interface> disable
+
+   Disable given `<interface>`. It will be placed in administratively down
+   state.
+
+Operation
+=========
+
+.. opcmd:: show interfaces dummy
+
+   Show brief interface information.information
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces dummy
+     Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+     Interface        IP Address                        S/L  Description
+     ---------        ----------                        ---  -----------
+     dum0             172.18.254.201/32                 u/u
+
+.. opcmd:: show interfaces dummy <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet eth0
+     dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000
+         link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff
+         inet 172.18.254.201/32 scope global dum0
+            valid_lft forever preferred_lft forever
+         inet6 fe80::247c:8eff:febc:fcf5/64 scope link
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes    packets     errors    dropped    overrun      mcast
+                  0          0          0          0          0          0
+         TX:  bytes    packets     errors    dropped    carrier collisions
+            1369707       4267          0          0          0          0
+
 
diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst
index a8cee8c2..1f691269 100644
--- a/docs/interfaces/ethernet.rst
+++ b/docs/interfaces/ethernet.rst
@@ -1,72 +1,226 @@
 .. _ethernet-interface:
 
+########
 Ethernet
---------
-
-Ethernet interfaces allow for the configuration of speed, duplex, and hw-id
-(MAC address). Below is an example configuration:
-
-.. code-block:: none
-
-  set interfaces ethernet eth1 address '192.168.0.1/24'
-  set interfaces ethernet eth1 address '2001:db8:1::ffff/64'
-  set interfaces ethernet eth1 description 'INSIDE'
-  set interfaces ethernet eth1 duplex 'auto'
-  set interfaces ethernet eth1 speed 'auto'
-
-Resulting in:
-
-.. code-block:: none
-
-  ethernet eth1 {
-      address 192.168.0.1/24
-      address 2001:db8:1::ffff/64
-      description INSIDE
-      duplex auto
-      hw-id 00:53:29:44:3b:19
-      smp_affinity auto
-      speed auto
-  }
-
-In addition, Ethernet interfaces provide the extended operational commands:
-
-* ``show interfaces ethernet <name> physical``
-* ``show interfaces ethernet <name> statistics``
-
-Statistics available are driver dependent.
-
-.. code-block:: none
-
-  vyos@vyos:~$ show interfaces ethernet eth0 physical
-  Settings for eth0:
-          Supported ports: [ TP ]
-          Supported link modes:   10baseT/Half 10baseT/Full
-                                  100baseT/Half 100baseT/Full
-                                  1000baseT/Full
-          Supports auto-negotiation: Yes
-          Advertised link modes:  10baseT/Half 10baseT/Full
-                                  100baseT/Half 100baseT/Full
-                                  1000baseT/Full
-          Advertised pause frame use: No
-          Advertised auto-negotiation: Yes
-          Speed: 1000Mb/s
-          Duplex: Full
-          Port: Twisted Pair
-          PHYAD: 0
-          Transceiver: internal
-          Auto-negotiation: on
-          MDI-X: Unknown
-          Supports Wake-on: d
-          Wake-on: d
-          Current message level: 0x00000007 (7)
-          Link detected: yes
-  driver: e1000
-  version: 7.3.21-k8-NAPI
-  firmware-version:
-  bus-info: 0000:02:01.0
-
-  vyos@vyos:~$ show interfaces ethernet eth0 statistics
-  NIC statistics:
-       rx_packets: 3530
-       tx_packets: 2179
-  [...]
+########
+
+Configuration
+#############
+
+Address
+-------
+
+.. cfgcmd:: set interfaces ethernet <interface> address <address | dhcp | dhcpv6>
+
+   Configure interface `<interface>` with one or more interface addresses.
+
+   * **address** can be specified multiple times as IPv4 and/or IPv6 address,
+     e.g. 192.0.2.1/24 and/or 2001:db8::1/64
+   * **dhcp** interface address is received by DHCP from a DHCP server on this
+     segment.
+   * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on
+     this segment.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces ethernet eth0 address 192.0.2.1/24
+     set interfaces ethernet eth0 address 192.0.2.2/24
+     set interfaces ethernet eth0 address 2001:db8::ffff/64
+     set interfaces ethernet eth0 address 2001:db8:100::ffff/64
+
+.. cfgcmd:: set interfaces ethernet <interface> ipv6 address autoconf
+
+   .. include:: common-ipv6-addr-autoconf.txt
+
+.. cfgcmd:: set interfaces ethernet <interface> ipv6 address eui64 <prefix>
+
+   :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in
+   :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address.
+
+   .. code-block:: none
+
+     set interfaces ethernet eth0 ipv6 address eui64 2001:db8:beef::/64
+
+Speed/Duplex
+------------
+
+.. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half>
+
+   Configure physical interface duplex setting.
+
+   * auto - interface duplex setting is auto-negotiated
+   * full - always use full-duplex
+   * half - always use half-duplex
+
+   VyOS default will be `auto`.
+
+.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000>
+
+   Configure physical interface speed setting.
+
+   * auto - interface speed is auto-negotiated
+   * 10 - 10 MBit/s
+   * 100 - 100 MBit/s
+   * 1000 - 1 GBit/s
+   * 2500 - 2.5 GBit/s
+   * 5000 - 5 GBit/s
+   * 10000 - 10 GBit/s
+   * 25000 - 25 GBit/s
+   * 40000 - 40 GBit/s
+   * 50000 - 50 GBit/s
+   * 100000 - 100 GBit/s
+
+   VyOS default will be `auto`.
+
+Link Administration
+-------------------
+
+.. cfgcmd:: set interfaces ethernet <interface> description <description>
+
+   Assign given `<description>` to interface. Description will also be passed
+   to SNMP monitoring systems.
+
+.. cfgcmd:: set interfaces ethernet <interface> disable
+
+   Disable given `<interface>`. It will be placed in administratively down
+   (``A/D``) state.
+
+.. cfgcmd:: set interfaces ethernet <interface> disable-flow-control
+
+   Disable Ethernet flow control (pause frames).
+
+
+.. cfgcmd:: set interfaces ethernet <interface> mac <mac-address>
+
+   Configure user defined :abbr:`MAC (Media Access Control)` address on given
+   `<interface>`.
+
+.. cfgcmd:: set interfaces ethernet <interface> mtu <mtu>
+
+   Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It
+   is the size (in bytes) of the largest ethernet frame sent on this link.
+
+Router Advertisements
+---------------------
+
+Router advertisements are described in :rfc:`4861#section-4.6.2`. They are part
+of what is known as :abbr:`SLAAC (Stateless Address Autoconfiguration)`.
+
+.. cfgcmd:: set interfaces ethernet <interface> ipv6 router-advert send-advert <true | false>
+
+   Enable or disable router advertisements in this `<interface>`.
+
+.. cfgcmd:: set interfaces ethernet <interface> ipv6 router-advert prefix <prefix>
+
+   Prefix information is described in :rfc:`4861#section-4.6.2`.
+
+Operation
+=========
+
+.. opcmd:: show interfaces ethernet
+
+   Show brief interface information.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet
+     Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+     Interface        IP Address                        S/L  Description
+     ---------        ----------                        ---  -----------
+     eth0             172.18.201.10/24                  u/u  LAN
+     eth1             172.18.202.11/24                  u/u  WAN
+     eth2             -                                 u/D
+
+.. opcmd:: show interfaces ethernet <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet eth0
+     eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
+         link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff
+         inet6 fe80::250:44ff:fe00:f5c9/64 scope link
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes    packets     errors    dropped    overrun      mcast
+           56735451     179841          0          0          0     142380
+         TX:  bytes    packets     errors    dropped    carrier collisions
+            5601460      62595          0          0          0          0
+
+.. opcmd:: show interfaces ethernet <interface> physical
+
+   Show information about physical `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet eth0 physical
+     Settings for eth0:
+             Supported ports: [ TP ]
+             Supported link modes:   1000baseT/Full
+                                     10000baseT/Full
+             Supported pause frame use: No
+             Supports auto-negotiation: No
+             Supported FEC modes: Not reported
+             Advertised link modes:  Not reported
+             Advertised pause frame use: No
+             Advertised auto-negotiation: No
+             Advertised FEC modes: Not reported
+             Speed: 10000Mb/s
+             Duplex: Full
+             Port: Twisted Pair
+             PHYAD: 0
+             Transceiver: internal
+             Auto-negotiation: off
+             MDI-X: Unknown
+             Supports Wake-on: uag
+             Wake-on: d
+             Link detected: yes
+     driver: vmxnet3
+     version: 1.4.16.0-k-NAPI
+     firmware-version:
+     expansion-rom-version:
+     bus-info: 0000:0b:00.0
+     supports-statistics: yes
+     supports-test: no
+     supports-eeprom-access: no
+     supports-register-dump: yes
+     supports-priv-flags: no
+
+.. opcmd:: show interfaces ethernet <interface> transceiver
+
+   Show transceiver information from plugin modules, e.g SFP+, QSFP
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet eth5 transceiver
+        Identifier              : 0x03 (SFP)
+        Extended identifier     : 0x04 (GBIC/SFP defined by 2-wire interface ID)
+        Connector               : 0x07 (LC)
+        Transceiver codes       : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00
+        Transceiver type        : Ethernet: 1000BASE-SX
+        Encoding                : 0x01 (8B/10B)
+        BR, Nominal             : 1300MBd
+        Rate identifier         : 0x00 (unspecified)
+        Length (SMF,km)         : 0km
+        Length (SMF)            : 0m
+        Length (50um)           : 550m
+        Length (62.5um)         : 270m
+        Length (Copper)         : 0m
+        Length (OM3)            : 0m
+        Laser wavelength        : 850nm
+        Vendor name             : CISCO-FINISAR
+        Vendor OUI              : 00:90:65
+        Vendor PN               : FTRJ-8519-7D-CS4
+        Vendor rev              : A
+        Option values           : 0x00 0x1a
+        Option                  : RX_LOS implemented
+        Option                  : TX_FAULT implemented
+        Option                  : TX_DISABLE implemented
+        BR margin, max          : 0%
+        BR margin, min          : 0%
+        Vendor SN               : FNS092xxxxx
+        Date code               : 0506xx
+
diff --git a/docs/interfaces/geneve.rst b/docs/interfaces/geneve.rst
index dc762738..b0bfde06 100644
--- a/docs/interfaces/geneve.rst
+++ b/docs/interfaces/geneve.rst
@@ -32,6 +32,9 @@ Geneve Header:
   |                    Variable Length Options                    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 
+Configuration
+=============
+
 .. cfgcmd:: set interfaces geneve gnv0 address '192.0.2.2/24'
 
    Create GENEVE tunnel listening on local address `192.0.2.2/24`.
diff --git a/docs/interfaces/index.rst b/docs/interfaces/index.rst
deleted file mode 100644
index 0513adf1..00000000
--- a/docs/interfaces/index.rst
+++ /dev/null
@@ -1,62 +0,0 @@
-.. _network-interfaces:
-
-##################
-Network Interfaces
-##################
-
-Configured interfaces on a VyOS system can be displayed using the
-``show interfaces`` command.
-
-.. code-block:: none
-
-  vyos@vyos:~$ show interfaces
-  Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
-  Interface        IP Address                        S/L  Description
-  ---------        ----------                        ---  -----------
-  eth0             172.16.51.129/24                  u/u  OUTSIDE
-  eth1             192.168.0.1/24                    u/u  INSIDE
-  lo               127.0.0.1/8                       u/u
-                   ::1/128
-
-A specific interface can be shown using the ``show interfaces <type> <name>``
-command.
-
-.. code-block:: none
-
-  vyos@vyos:~$ show interfaces ethernet eth0
-  eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000
-      link/ether 00:53:29:44:3b:0f brd ff:ff:ff:ff:ff:ff
-      inet 172.16.51.129/24 brd 172.16.51.255 scope global eth0
-      inet6 fe80::20c:29ff:fe44:3b0f/64 scope link
-         valid_lft forever preferred_lft forever
-      Description: OUTSIDE
-
-      RX:  bytes    packets     errors    dropped    overrun      mcast
-          274397       3064          0          0          0          0
-      TX:  bytes    packets     errors    dropped    carrier collisions
-          257276       1890          0          0          0          0
-
-Different network interfaces provide type-specific configuration. Ethernet
-interfaces, for example, allow the configuration of speed and duplex.
-
-Many services, such as network routing, firewall, and traffic policy also
-maintain interface-specific configuration. These will be covered in their
-respective sections.
-
-
-.. toctree::
-   :maxdepth: 2
-
-   addresses
-   dummy
-   ethernet
-   l2tpv3
-   pppoe
-   wireless
-   bridge
-   bond
-   tunnel
-   vlan
-   qinq
-   vxlan
-   geneve
diff --git a/docs/interfaces/loopback.rst b/docs/interfaces/loopback.rst
new file mode 100644
index 00000000..f7519631
--- /dev/null
+++ b/docs/interfaces/loopback.rst
@@ -0,0 +1,75 @@
+.. _loopback-interface:
+
+########
+Loopback
+########
+
+The loopback networking interface is a virtual network device implemented
+entirely in software. All traffic sent to it "loops back" and just targets
+services on your local machine.
+
+.. note:: There can only be one loopback ``lo`` interface on the system. If
+   you need multiple interfaces, please use the :ref:`dummy-interface`
+   interface type.
+
+.. hint:: A lookback interface is always up, thus it could be used for
+   management traffic or as source/destination for and :abbr:`IGP (Interior
+   Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependant
+   on physical link states and multiple routes can be choosen to the
+   destination. A :ref:`dummy-interface` Interface should always be preferred
+   over a :ref:`loopback-interface` interface.
+
+Configuration
+=============
+
+Address
+-------
+
+.. cfgcmd:: set interfaces loopback lo address <address>
+
+   Configure Loopback interface `lo` with one or more interface addresses.
+   Address can be specified multiple times as IPv4 and/or IPv6 address, e.g.
+   192.0.2.1/24 and/or 2001:db8::1/64.
+
+Link Administration
+-------------------
+
+.. cfgcmd:: set interfaces loopback lo description <description>
+
+   Assign given `<description>` to interface `lo`. Description will also be
+   passed to SNMP monitoring systems.
+
+Operation
+=========
+
+.. opcmd:: show interfaces loopback
+
+   Show brief interface information.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces loopback
+     Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+     Interface        IP Address                        S/L  Description
+     ---------        ----------                        ---  -----------
+     lo               127.0.0.1/8                       u/u
+                      ::1/128
+
+.. opcmd:: show interfaces loopback lo
+
+   Show detailed information on given loopback interface `lo`.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet eth0
+     lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
+         link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+         inet 127.0.0.1/8 scope host lo
+            valid_lft forever preferred_lft forever
+         inet6 ::1/128 scope host
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes    packets     errors    dropped    overrun      mcast
+                300          6          0          0          0          0
+         TX:  bytes    packets     errors    dropped    carrier collisions
+                300          6          0          0          0          0
diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst
index ef595b97..9888d682 100644
--- a/docs/interfaces/pppoe.rst
+++ b/docs/interfaces/pppoe.rst
@@ -1,7 +1,8 @@
 .. _pppoe-interface:
 
+#####
 PPPoE
-=====
+#####
 
 :abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol
 for encapsulating PPP frames inside Ethernet frames. It appeared in 1999,
@@ -14,14 +15,14 @@ PPP facilities for authenticating the user with a username and password,
 predominately via the PAP protocol and less often via CHAP.
 
 Operating Modes
----------------
+===============
 
 VyOS supports setting up PPPoE in two different ways to a PPPoE internet
 connection. This is due to most ISPs provide a modem that is also a wireless
 router.
 
 Home Users
-**********
+----------
 
 In this method, the DSL Modem/Router connects to the ISP for you with your
 credentials preprogrammed into the device. This gives you an :rfc:`1918`
@@ -34,7 +35,7 @@ few extra layers of complexity, particularly if you use some NAT or
 tunnel features.
 
 Business Users
-**************
+--------------
 
 In order to have full control and make use of multiple static public IP
 addresses, your VyOS will have to initiate the PPPoE connection and control
@@ -50,8 +51,8 @@ configure it to open the PPPoE session for you and your DSL Transceiver
 (Modem/Router) just acts to translate your messages in a way that
 vDSL/aDSL understands.
 
-Configuration Example
-~~~~~~~~~~~~~~~~~~~~~
+Example
+=======
 
 Requirements:
 
@@ -95,7 +96,7 @@ assigning it to the pppoe0 itself as shown here:
   set interfaces ethernet eth0 pppoe 0 firewall out name NET-OUT
 
 VLAN Example
-++++++++++++
+------------
 
 Some recent ISPs require you to build the PPPoE connection through a VLAN
 interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS
@@ -116,30 +117,31 @@ which is the default VLAN for Deutsche Telekom:
   set interfaces ethernet eth0 vif 7 pppoe 0 password 'secret'
 
 Troubleshooting
----------------
+===============
 
 .. opcmd:: disconnect interface <interface>
 
-Test disconnecting given connection-oriented interface. `<interface>` can be
-``pppoe0`` as example.
+   Test disconnecting given connection-oriented interface. `<interface>` can be
+   ``pppoe0`` as example.
 
 .. opcmd:: connect interface <interface>
 
-Test connecting given connection-oriented interface. `<interface>` can be
-``pppoe0`` as example.
+   Test connecting given connection-oriented interface. `<interface>` can be
+   ``pppoe0`` as example.
 
 .. opcmd:: show interfaces pppoe <interface>
 
-Check PPPoE connection logs with the following command which shows the current
-statistics, status and some of the settings (i.e. MTU) for the current
-connection on <interface> (e.g. ``pppoe0``)
+   Check PPPoE connection logs with the following command which shows the
+   current statistics, status and some of the settings (i.e. MTU) for the
+   current connection on <interface> (e.g. ``pppoe0``)
 
 .. opcmd:: show interfaces pppoe <interface> log
 
-Show entire log for the PPPoE connection starting with the oldest data. Scroll
-down with the <space> key to reach the end where the current data is.
+   Show entire log for the PPPoE connection starting with the oldest data.
+   Scroll down with the <space> key to reach the end where the current data is.
 
 .. opcmd::  show interfaces pppoe <interface> log tail
 
-Shows the same log as without the 'tail' option but start with the last few
-lines and continues to show added lines until you exit with ``Ctrl + x``
+   Shows the same log as without the 'tail' option but start with the last few
+   lines and continues to show added lines until you exit with ``Ctrl + x``
+
diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst
index e597e167..67dab820 100644
--- a/docs/interfaces/vxlan.rst
+++ b/docs/interfaces/vxlan.rst
@@ -1,7 +1,8 @@
 .. _vxlan-interface:
 
+#####
 VXLAN
------
+#####
 
 :abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology
 that attempts to address the scalability problems associated with large cloud
@@ -32,12 +33,102 @@ may be blocked by the hypervisor.
    for VXLAN, VyOS uses a default port of 8472. You can change the port on a
    per VXLAN interface basis to get it working accross multiple vendors.
 
-Multicast VXLAN
-^^^^^^^^^^^^^^^^
+Configuration
+=============
+
+Address
+-------
+
+.. cfgcmd:: set interfaces vxlan <interface> address <address>
+
+   Configure VXLAN interface `<interface>` with one or more interface
+   addresses. Address can be specified multiple times as IPv4 and/or IPv6
+   address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces vxlan vxlan0 address 192.0.2.1/24
+     set interfaces vxlan vxlan0 address 192.0.2.2/24
+     set interfaces vxlan vxlan0 address 2001:db8::ffff/64
+     set interfaces vxlan vxlan0 address 2001:db8:100::ffff/64
+
+
+.. cfgcmd:: set interfaces vxlan <interface> ipv6 address autoconf
+
+   .. include:: common-ipv6-addr-autoconf.txt
+
+.. cfgcmd:: set interfaces vxlan <interface> ipv6 address eui64 <prefix>
+
+   :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in
+   :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address.
+
+   .. code-block:: none
+
+     set interfaces vxlan vxlan0 ipv6 address eui64 2001:db8:beef::/64
+
+
+.. cfgcmd:: set interfaces vxlan <interface> link <interface>
+
+   Interface used for VXLAN underlay. This is mandatory when using VXLAN via
+   a multicast network. VXLAN traffic will always enter and exit this interface.
+
+
+.. cfgcmd:: set interfaces vxlan <interface> group <address>
+
+   Multicast group address for VXLAN interface. VXLAN tunnels can be built
+   either via Multicast or via Unicast.
+
+   Both IPv4 and IPv6 multicast is possible.
+
+
+.. cfgcmd:: set interfaces vxlan <interface> remote <address>
+
+   IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the
+   remote IPv4/IPv6 address can set directly.
+
+
+.. cfgcmd:: set interfaces vxlan <interface> port <port>
+
+    Configure port number of remote VXLAN endpoint.
 
-Example Topology:
+    .. note:: As VyOS is Linux based the default port used is not using 4789
+       as the default IANA-assigned destination UDP port number. Instead VyOS
+       uses the Linux default port of 8472.
 
-PC4 - Leaf2 - Spine1 - Leaf3 - PC5
+
+.. cfgcmd:: set interfaces vxlan <interface> vni <number>
+
+   Each VXLAN segment is identified through a 24-bit segment ID, termed the
+   :abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows
+   up to 16M VXLAN segments to coexist within the same administrative domain.
+
+
+Link Administration
+-------------------
+
+.. cfgcmd:: set interfaces vxlan <interface> description <description>
+
+   Assign given `<description>` to interface. Description will also be passed
+   to SNMP monitoring systems.
+
+.. cfgcmd:: set interfaces vxlan <interface> disable
+
+   Disable given `<interface>`. It will be placed in administratively down
+   (``A/D``) state.
+
+.. cfgcmd:: set interfaces vxlan <interface> mtu <mtu>
+
+   Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It
+   is the size (in bytes) of the largest ethernet frame sent on this link.
+   MTU ranges from 1450 to 9000 bytes. For best performance you should have
+   a MTU > 1550 bytes on your underlay.
+
+Multicast VXLAN
+===============
+
+Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5
 
 PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in
 the same broadcast domain.
@@ -65,30 +156,10 @@ For optimal scalability Multicast shouldn't be used at all, but instead use BGP
 to signal all connected devices between leafs. Unfortunately, VyOS does not yet
 support this.
 
-Configuration commands
-^^^^^^^^^^^^^^^^^^^^^^
+Example
+-------
 
-.. code-block:: none
-
-  interfaces
-    vxlan <vxlan[0-16777215]>
-      address          # IP address of the VXLAN interface
-      description      # Description
-      group <ipv4>     # IPv4 Multicast group address (required)
-      ip               # IPv4 routing options
-      ipv6             # IPv6 routing options
-      link <dev>       # IP interface for underlay of this vxlan overlay (optional)
-      mtu              # MTU
-      policy           # Policy routing options
-      remote           # Remote address of the VXLAN tunnel, used for PTP instead of multicast
-      vni <1-16777215> # Virtual Network Identifier (required)
-
-Configuration Example
-^^^^^^^^^^^^^^^^^^^^^
-
-The setup is this:
-
-Leaf2 - Spine1 - Leaf3
+The setup is this: Leaf2 - Spine1 - Leaf3
 
 Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a
 VyOS router running 1.2.
@@ -111,7 +182,7 @@ Topology:
   Eth0 towards Spine1, IP-address 10.1.3.3/24
   Eth1 towards a vlan-aware switch
 
-Spine1 Configuration:
+**Spine1 Configuration:**
 
 .. code-block:: none
 
@@ -131,10 +202,10 @@ Spine1 Configuration:
 
 Multicast-routing is required for the leafs to forward traffic between each
 other in a more scalable way. This also requires PIM to be enabled towards the
-Leafs so that the Spine can learn what multicast groups each Leaf expect traffic
-from.
+Leafs so that the Spine can learn what multicast groups each Leaf expect
+traffic from.
 
-Leaf2 configuration:
+**Leaf2 configuration:**
 
 .. code-block:: none
 
@@ -159,7 +230,7 @@ Leaf2 configuration:
   set interfaces vxlan vxlan242 link 'eth0'
   set interfaces vxlan vxlan242 vni '242'
 
-Leaf3 configuration:
+**Leaf3 configuration:**
 
 .. code-block:: none
 
@@ -238,77 +309,11 @@ its pre-standard value of 8472 to preserve backwards compatibility. A
 configuration directive to support a user-specified destination port to override
 that behavior is available using the above command.
 
-Older Examples
-^^^^^^^^^^^^^^
-
-Example for bridging normal L2 segment and vxlan overlay network, and using a
-vxlan interface as routing interface.
-
-.. code-block:: none
-
-  interfaces {
-       bridge br0 {
-           member {
-               interface vxlan0 {
-               }
-           }
-       }
-       ethernet eth0 {
-           address dhcp
-       }
-       loopback lo {
-       }
-       vxlan vxlan0 {
-           group 239.0.0.1
-           vni 0
-       }
-       vxlan vxlan1 {
-           address 192.168.0.1/24
-           link eth0
-           group 239.0.0.1
-           vni 1
-       }
-  }
-
-Here is a working configuration that creates a VXLAN between two routers. Each
-router has a VLAN interface (26) facing the client devices and a VLAN interface
-(30) that connects it to the other routers. With this configuration, traffic
-can flow between both routers' VLAN 26, but can't escape since there is no L3
-gateway. You can add an IP to a bridge to create a gateway.
-
-.. code-block:: none
-
-  interfaces {
-       bridge br0 {
-           member {
-               interface eth0.26 {
-               }
-               interface vxlan0 {
-               }
-           }
-       }
-       ethernet eth0 {
-           duplex auto
-           smp-affinity auto
-           speed auto
-           vif 30 {
-               address 10.7.50.6/24
-           }
-       }
-       loopback lo {
-       }
-       vxlan vxlan0 {
-           group 239.0.0.241
-           vni 241
-       }
-  }
-
 Unicast VXLAN
-^^^^^^^^^^^^^
-
-Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can set directly.
-Let's change the Multicast example from above:
+=============
 
+Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be
+set directly. Let's change the Multicast example from above:
 
 .. code-block:: none