interfaces: update base interface definitions and links

13 files changed, 355 insertions, 164 deletions

diff --git a/docs/interfaces/addresses.rst b/docs/interfaces/addresses.rst
index 0ced23f8..c8bccb18 100644
--- a/docs/interfaces/addresses.rst
+++ b/docs/interfaces/addresses.rst
@@ -6,10 +6,10 @@ Interface 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`
+* Static IPv4 ``address 172.16.51.129/24``
+* Static IPv6 ``address 2001:db8:1::ffff/64``
+* DHCP IPv4 ``address dhcp``
+* DHCP IPv6 ``address dhcpv6``
 
 An interface description is assigned using the following command:
 
@@ -27,7 +27,7 @@ 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:
+The command is ``set interfaces $type $name address $address``. Examples:
 
 .. code-block:: sh
 
@@ -40,10 +40,10 @@ 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).
+directly connected to a physical interface (Ethernet, VLAN, Bridge, Bond,
+Pseudo-ethernet, Wireless).
 
-The command is `set interfaces $type $name address dhcp`. Examples:
+The command is ``set interfaces $type $name address dhcp``. Examples:
 
 .. code-block:: sh
 
@@ -59,9 +59,9 @@ 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:`interfaces-tunnel`.
+except :ref:`tunnel-interface`.
 
-The command is `set interfaces $type $name address $address`. Examples:
+The command is ``set interfaces $type $name address $address``. Examples:
 
 .. code-block:: sh
 
@@ -74,8 +74,8 @@ 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).
+directly connected to a physical interface (Ethernet, VLAN, Bridge, Bond,
+Pseudo-ethernet, Wireless).
 
 The command is `set interfaces $type $name address dhcpv6`. Examples:
 
@@ -89,9 +89,9 @@ 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).
+(Ethernet, VLAN, Bridge, Bond, Pseudo-ethernet, Wireless).
 
-The command is `set interfaces $type $name ipv6 address autoconf`. Examples:
+The command is ``set interfaces $type $name ipv6 address autoconf``. Examples:
 
 .. code-block:: sh
 
@@ -120,13 +120,14 @@ Examples:
 Router Advertisements
 *********************
 
-Router advertisements are described in :rfc:`4861` section 4.2. They are part of what is known as SLAAC (Stateless Address Autoconfiguration). 
+Router advertisements are described in :rfc:`4861` section 4.2. They are part
+of what is known as SLAAC (Stateless Address Autoconfiguration).
 
 To enable or disable, use:
 
 .. code-block:: sh
 
-  set interfaces <interface> ipv6 router-advert send-advert <true or false>
+  set interfaces <interface> ipv6 router-advert send-advert <true|false>
 
 
 To set the options described in "Router Advertisement Message Format":
@@ -135,22 +136,23 @@ To set the options described in "Router Advertisement Message Format":
 
   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**
+     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.
 
@@ -163,11 +165,13 @@ Prefix information is described in :rfc:`4861` section 4.6.2.
     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**
+Receiving Router Advertisements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To receive and accept RAs on an interface, you need to enable it with the following configuration command
+To receive and accept RAs on an interface, you need to enable it with the
+following configuration command
 
 .. code-block:: sh
 
-  vyos@vyos# set system sysctl custom net.ipv6.conf.<interface name>.accept_ra value 2
+  vyos@vyos# set system sysctl custom net.ipv6.conf.<interface>.accept_ra value 2
 
diff --git a/docs/interfaces/bonding.rst b/docs/interfaces/bond.rst
index 72deb03b..05ed32c6 100644
--- a/docs/interfaces/bonding.rst
+++ b/docs/interfaces/bond.rst
@@ -1,5 +1,7 @@
-Bonding
--------
+.. _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.
diff --git a/docs/interfaces/bridging.rst b/docs/interfaces/bridge.rst
index f31e30e6..6c8510b5 100644
--- a/docs/interfaces/bridging.rst
+++ b/docs/interfaces/bridge.rst
@@ -1,7 +1,7 @@
-.. _bridge:
+.. _bridge-interface:
 
-Interface Bridge
-----------------
+Bridge
+------
 
 Interfaces in VyOS can be bridged together to provide software switching of
 Layer-2 traffic.
diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst
index dc46a4cb..8a24d4db 100644
--- a/docs/interfaces/dummy.rst
+++ b/docs/interfaces/dummy.rst
@@ -1,21 +1,25 @@
 .. _dummy-interface:
 
-Dummy Interfaces
-----------------
+Dummy
+-----
 
-Dummy interfaces — much like the loopback, 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 IOS), or for testing purposes.
+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:: sh
 
-    interfaces
-        dummy <dum[0-999]>
-        + address           IP address
-        description         Description
-        disable             Disable interface
-        > ip                IPv4 routing parameters
-        > ipv6              IPv6 routing parameters
-        redirect            Incoming packet redirection destination
-        > traffic-policy    Traffic-policy for interface
\ No newline at end of file
+  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
+
diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst
index 075b3836..625f2eed 100644
--- a/docs/interfaces/ethernet.rst
+++ b/docs/interfaces/ethernet.rst
@@ -1,7 +1,7 @@
+.. _ethernet-interface:
 
-Ethernet Interfaces
--------------------
-.. _interfaces-ethernet:
+Ethernet
+--------
 
 Ethernet interfaces allow for the configuration of speed, duplex, and hw-id
 (MAC address). Below is an example configuration:
@@ -30,8 +30,8 @@ Resulting in:
 
 In addition, Ethernet interfaces provide the extended operational commands:
 
-* `show interfaces ethernet <name> physical`
-* `show interfaces ethernet <name> statistics` 
+* ``show interfaces ethernet <name> physical``
+* ``show interfaces ethernet <name> statistics``
 
 Statistics available are driver dependent.
 
diff --git a/docs/interfaces/index.rst b/docs/interfaces/index.rst
index 7b661567..9aebf7df 100644
--- a/docs/interfaces/index.rst
+++ b/docs/interfaces/index.rst
@@ -52,8 +52,8 @@ respective sections.
    l2tpv3
    pppoe
    wireless
-   bridging
-   bonding
+   bridge
+   bond
    tunnel
    vlan
    qinq
diff --git a/docs/interfaces/l2tpv3.rst b/docs/interfaces/l2tpv3.rst
index ec2762eb..d5788c35 100644
--- a/docs/interfaces/l2tpv3.rst
+++ b/docs/interfaces/l2tpv3.rst
@@ -1,19 +1,20 @@
 .. _l2tpv3-interface:
 
-L2TPv3 Interfaces
------------------
+L2TPv3
+------
 
-L2TPv3 is a pseudowire protocol, you can read more about here `Wikipedia L2TPv3`_ or :rfc:`3921`
+L2TPv3 is a pseudowire protocol, you can read more about on `Wikipedia L2TPv3`_
+or in :rfc:`3921`
 
-L2TPv3 can transport any traffic including ethernet frames. L2TPv2 is limited to PPP.
+L2TPv3 can transport any traffic including ethernet frames. L2TPv2 is limited
+to PPP.
 
-
-L2TPv3 over IP
-^^^^^^^^^^^^^^
+Over IP
+^^^^^^^
 
 .. code-block:: sh
 
-  # show interfaces l2tpv3 
+  # show interfaces l2tpv3
   l2tpv3 l2tpeth10 {
       address 192.168.37.1/27
       encapsulation ip
@@ -27,8 +28,8 @@ L2TPv3 over IP
 
 Inverse configuration has to be applied to the remote side.
 
-L2TPv3 over UDP
-^^^^^^^^^^^^^^^
+Over UDP
+^^^^^^^^
 
 UDP mode works better with NAT:
 
@@ -37,7 +38,7 @@ UDP mode works better with NAT:
 
 .. code-block:: sh
 
-  # show interfaces l2tpv3 
+  # show interfaces l2tpv3
   l2tpv3 l2tpeth10 {
       address 192.168.37.1/27
       destination-port 9001
@@ -54,10 +55,11 @@ UDP mode works better with NAT:
 To create more than one tunnel, use distinct UDP ports.
 
 
-L2TPv3 over IPSec, L2 VPN (bridge)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Over IPSec, L2 VPN (bridge)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This is the LAN extension use case. The eth0 port of the distant VPN peers will be directly connected like if there was a switch between them.
+This is the LAN extension use case. The eth0 port of the distant VPN peers
+will be directly connected like if there was a switch between them.
 
 IPSec:
 
diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst
index 42d7c3b4..576513a1 100644
--- a/docs/interfaces/pppoe.rst
+++ b/docs/interfaces/pppoe.rst
@@ -1,79 +1,162 @@
-.. _pppoe:
-
+.. _pppoe-interface:
 
 PPPoE
 =====
 
-There are two main ways to setup VyOS to connect over a PPPoE internet connection. This is due to most ISPs (Internet Service Providers) providing a DSL modem that is also a wireless router.
-
-**First Method:** (Common for Homes)
-
-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` address, such as ``192.168.1.0/24`` by default.
+:abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol
+for encapsulating PPP frames inside Ethernet frames. It appeared in 1999,
+in the context of the boom of DSL as the solution for tunneling packets
+over the DSL connection to the :abbr:`ISPs (Internet Service Providers)`
+IP network, and from there to the rest of the Internet. A 2005 networking
+book noted that "Most DSL providers use PPPoE, which provides authentication,
+encryption, and compression." Typical use of PPPoE involves leveraging the
+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`
+address, such as ``192.168.1.0/24`` by default.
+
+For a simple home network using just the ISP's equipment, this is usually
+desirable. But if you want to run VyOS as your firewall and router, this
+will result in having a double NAT and firewall setup. This results in a
+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
+it. In order for this method to work, you will have to figure out how to make
+your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL
+Transceiver device to connect between the Ethernet link of your VyOS and the
+phone cable. Once your DSL Transceiver is in Bridge Mode, you should get no
+IP address from it. Please make sure you connect to the Ethernet Port 1 if
+your DSL Transeiver has a switch, as some of them only work this way.
+
+Once you have an Ethernet device connected, i.e. `eth0`, then you can
+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
+~~~~~~~~~~~~~~~~~~~~~
+
+Requirements:
+
+* Your ISPs modem is connected to port ``eth0`` of your VyOS box.
+* No VLAN tagging required by your ISP.
+* You need your PPPoE credentials from your DSL ISP in order to configure
+  this. The usual username is in the form of name@host.net but may vary
+  depending on ISP.
+* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead.
+  If you are switching from a DHCP based ISP like cable then be aware that
+  things like VPN links may need to have their MTU sizes adjusted to work
+  within this limit.
+* With the ``default-route`` option set to ``auto``, VyOS will only add the
+  default gateway you receive from your DSL ISP to the routing table if you
+  have no other WAN connections. If you wish to use a dual WAN connection,
+  change the ``default-route`` option to ``force``.
+* With the ``name-server`` option set to ``none``, VyOS will ignore the
+  nameservers your ISP sens you and thus you can fully rely on the ones you
+  have configured statically.
 
-For a simple home network using just the ISP's equipment, this is usually desirable.  But if you want to run VyOS as your firewall and router, this will result in having a double NAT and firewall setup. This results in a few extra layers of complexity, particularly if you use some NAT or tunnel features.
+.. code-block:: sh
 
-**Second Method:** (Common for Businesses)
+  set interfaces ethernet eth0 description "DSL Modem"
+  set interfaces ethernet eth0 duplex auto
+  set interfaces ethernet eth0 smp_affinity auto
+  set interfaces ethernet eth0 speed auto
+  set interfaces ethernet eth0 pppoe 0 default-route 'auto'
+  set interfaces ethernet eth0 pppoe 0 mtu 1492
+  set interfaces ethernet eth0 pppoe 0 name-server 'auto'
+  set interfaces ethernet eth0 pppoe 0 user-id 'userid'
+  set interfaces ethernet eth0 pppoe 0 password 'secret'
 
-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 it.
-In order for this method to work, you will have to figure out how to make your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL Transceiver device to connect between the Ethernet link of your VyOS and the phone cable.
-Once your DSL Transceiver is in Bridge Mode, you should get no IP address from it.
-Please make sure you connect to the Ethernet Port 1 if your DSL Transeiver has a switch, as some of them only work this way.
-Once you have an Ethernet device connected, i.e. eth0, then you can 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.
 
-**Here is an example configuration:**
+You should add a firewall to your configuration above as well by
+assigning it to the pppoe0 itself as shown here:
 
 .. code-block:: sh
 
-  set interface ethernet eth0 description "DSL Modem"
-  set interface ethernet eth0 duplex auto
-  set interface ethernet eth0 smp_affinity auto
-  set interface ethernet eth0 speed auto
-  set interface ethernet eth0 pppoe 0 default-route auto
-  set interface ethernet eth0 pppoe 0 mtu 1492
-  set interface ethernet eth0 pppoe 0 name-server auto
-  set interface ethernet eth0 pppoe 0 user-id <PPPoE Username>
-  set interface ethernet eth0 pppoe 0 password <PPPoE Password>
+  set interfaces ethernet eth0 pppoe 0 firewall in name NET-IN
+  set interfaces ethernet eth0 pppoe 0 firewall local name NET-LOCAL
+  set interfaces ethernet eth0 pppoe 0 firewall out name NET-OUT
 
+VLAN Example
+++++++++++++
 
-* You should add a firewall to your configuration above as well by assigning it to the pppoe0 itself as shown here:
+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
+can easily create a PPPoe session through an encapsulated VLAN interface.
+The following configuration will run your PPPoE connection through VLAN7
+which is the default VLAN for Deutsche Telekom:
 
 .. code-block:: sh
 
-  set interface ethernet eth0 pppoe 0 firewall in name NET-IN
-  set interface ethernet eth0 pppoe 0 firewall local name NET-LOCAL
-  set interface ethernet eth0 pppoe 0 firewall out name NET-OUT
+  set interfaces ethernet eth0 description "DSL Modem"
+  set interfaces ethernet eth0 duplex auto
+  set interfaces ethernet eth0 smp_affinity auto
+  set interfaces ethernet eth0 speed auto
+  set interfaces ethernet eth0 vif 7 pppoe 0 default-route 'auto'
+  set interfaces ethernet eth0 vif 7 pppoe 0 mtu '1492'
+  set interfaces ethernet eth0 vif 7 pppoe 0 name-server 'auto'
+  set interfaces ethernet eth0 vif 7 pppoe 0 user-id 'userid#0001@t-online.de'
+  set interfaces ethernet eth0 vif 7 pppoe 0 password 'secret'
 
-* You need your PPPoE credentials from your DSL ISP in order to configure this. The usual username is in the form of name@host.net but may vary depending on ISP.
-* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. If you are switching from a DHCP based ISP like cable then be aware that things like VPN links may need to have their MTU sizes adjusted to work within this limit.
-* With the ``default-route`` option set to ``auto``, VyOS will only add the Default Gateway you receive from your DSL ISP to the routing table if you have no other WAN connections. If you wish to use a Dual WAN connection, change the ``default-route`` option to ``force``.
+Troubleshooting
+---------------
 
-Handling and troubleshooting
-----------------------------
+Connect/Disconnect
+******************
 
-You can test connecting and disconnecting with the below commands:
+You can test connecting and disconnecting with the below commands issued
+on the operational level of your VyOS isntallation:
 
 .. code-block:: sh
 
   disconnect interface 0
   connect interface 0
 
+Logs
+****
 
-You can check the PPPoE connection logs with the following:
-
-This command shows the current statistics, status and some of the settings (i.e. MTU) for the current connection on pppoe0.
+You can check the 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 pppoe0.
 
 .. code-block:: sh
 
   show interfaces pppoe 0
 
-This command shows the 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.
+Full Log
+~~~~~~~~
+
+This command shows the 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.
 
 .. code-block:: sh
 
   show interfaces pppoe 0 log
 
+Recent Log
+~~~~~~~~~~
 
-This command shows the same log as without the 'tail' option but only starts with the last few lines and continues to show added lines until you exit with ``Ctrl + x``
+This command shows the same log as without the 'tail' option but only starts
+with the last few lines and continues to show added lines until you exit with
+``Ctrl + x``
 
 .. code-block:: sh
 
diff --git a/docs/interfaces/qinq.rst b/docs/interfaces/qinq.rst
index 12fbd47d..cc1812d0 100644
--- a/docs/interfaces/qinq.rst
+++ b/docs/interfaces/qinq.rst
@@ -1,16 +1,33 @@
-.. _interfaces-qinq:
+.. _qinq-interface:
 
-QinQ
-----
+QinQ (802.1ad)
+--------------
 
-QinQ (802.1ad_) — allows multiple VLAN tags to be inserted into a single frame.
+IEEE 802.1ad was an Ethernet networking standard informally known as QinQ as
+an amendment to IEEE standard :ref:`vlan-interface`. 802.1ad was incorporated
+into the base 802.1q standard in 2011. The technique is also known as provider
+bridging, Stacked VLANs, or simply QinQ or Q-in-Q. "Q-in-Q" can for supported
+devices apply to C-tag stacking on C-tag (Ethernet Type = 0x8100).
 
-QinQ can be used to tunnel vlans in a vlan.
+The original 802.1q specification allows a single Virtual Local Area Network
+(VLAN) header to be inserted into an Ethernet frame. QinQ allows multiple
+VLAN tags to be inserted into a single frame, an essential capability for
+implementing Metro Ethernet network topologies. Just as QinQ extends 802.1Q,
+QinQ itself is extended by other Metro Ethernet protocols.
 
-**vif-s** and **vif-c** stand for the ethertype tags that get set:
+In a multiple VLAN header context, out of convenience the term "VLAN tag" or
+just "tag" for short is often used in place of "802.1Q VLAN header". QinQ
+allows multiple VLAN tags in an Ethernet frame; together these tags constitute
+a tag stack. When used in the context of an Ethernet frame, a QinQ frame is a
+frame that has 2 VLAN 802.1Q headers (double-tagged).
 
-The inner tag is the tag which is closest to the payload portion of the frame; it is officially called C-TAG (Customer tag, with ethertype 0x8100).
-The outer tag is the one closer/closest to the Ethernet header; its name is S-TAG (Service tag, ethertype 0x88a8).
+In VyOS the terms **vif-s** and **vif-c** stand for the ethertype tags that
+are used:
+
+The inner tag is the tag which is closest to the payload portion of the frame.
+It is officially called C-TAG (customer tag, with ethertype 0x8100). The outer
+tag is the one closer/closest to the Ethernet header, its name is S-TAG
+(service tag with ethertype 0x88a8).
 
 Configuration commands:
 
diff --git a/docs/interfaces/tunnel.rst b/docs/interfaces/tunnel.rst
index f7f14aec..259e0d6b 100644
--- a/docs/interfaces/tunnel.rst
+++ b/docs/interfaces/tunnel.rst
@@ -1,7 +1,7 @@
-.. _interfaces-tunnel:
+.. _tunnel-interface:
 
-Tunnel Interfaces
-=================
+Tunnel
+======
 
 This article touches on 'classic' IP tunneling protocols.
 
diff --git a/docs/interfaces/vlan.rst b/docs/interfaces/vlan.rst
index 76fadd3c..2c2a7ea6 100644
--- a/docs/interfaces/vlan.rst
+++ b/docs/interfaces/vlan.rst
@@ -1,11 +1,34 @@
-VLAN Sub-Interfaces (802.1Q)
-----------------------------
-.. _interfaces-vlan:
+.. _vlan-interface:
 
-802.1Q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The
-term used for this is `vif`. Configuration of a tagged sub-interface is
-accomplished using the configuration command
-`set interfaces ethernet <name> vif <vlan-id>`.
+VLAN (802.1q)
+-------------
+
+IEEE 802.1q, often referred to as Dot1q, is the networking standard that
+supports virtual LANs (VLANs) on an IEEE 802.3 Ethernet network. The
+standard defines a system of VLAN tagging for Ethernet frames and the
+accompanying procedures to be used by bridges and switches in handling
+such frames. The standard also contains provisions for a quality-of-service
+prioritization scheme commonly known as IEEE 802.1p and defines the Generic
+Attribute Registration Protocol.
+
+Portions of the network which are VLAN-aware (i.e., IEEE 802.1q conformant)
+can include VLAN tags. When a frame enters the VLAN-aware portion of the
+network, a tag is added to represent the VLAN membership. Each frame must
+be distinguishable as being within exactly one VLAN. A frame in the
+VLAN-aware portion of the network that does not contain a VLAN tag is
+assumed to be flowing on the native VLAN.
+
+The standard was developed by IEEE 802.1, a working group of the IEEE 802
+standards committee, and continues to be actively revised. One of the
+notable revisions is 802.1Q-2014 which incorporated IEEE 802.1aq (Shortest
+Path Bridging) and much of the IEEE 802.1d standard.
+
+802.1a VLAN interfaces are represented as virtual sub-interfaces in VyOS. The
+term used for this is ``vif``. Configuration of a tagged sub-interface is
+accomplished using the configuration command:
+``set interfaces ethernet <name> vif <vlan-id>``
+
+To assign a vif 100 using the VLAN 100 tag to physical interface eth1 use:
 
 .. code-block:: sh
 
@@ -44,4 +67,3 @@ VLAN interfaces are shown as `<name>.<vlan-id>`, e.g. `eth1.100`:
   eth1.100         192.168.100.1/24                  u/u  VLAN 100
   lo               127.0.0.1/8                       u/u
                    ::1/128
-
diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst
index d432bdc6..ac818fcc 100644
--- a/docs/interfaces/vxlan.rst
+++ b/docs/interfaces/vxlan.rst
@@ -1,12 +1,37 @@
+.. _vxlan-interface:
+
 VXLAN
 -----
 
-VXLAN is an overlaying Ethernet over IP protocol, it's described in :rfc:`7348`.
+:abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology
+that attempts to address the scalability problems associated with large cloud
+computing deployments. It uses a VLAN-like encapsulation technique to
+encapsulate OSI layer 2 Ethernet frames within layer 4 UDP datagrams, using
+4789 as the default IANA-assigned destination UDP port number. VXLAN
+endpoints, which terminate VXLAN tunnels and may be either virtual or physical
+switch ports, are known as :abbr:`VTEPs (VXLAN tunnel endpoints)`.
+
+VXLAN is an evolution of efforts to standardize on an overlay encapsulation
+protocol. It increases scalability up to 16 million logical networks and
+allows for layer 2 adjacency across IP networks. Multicast or unicast with
+head-end replication (HER) is used to flood broadcast, unknown unicast,
+and multicast (BUM) traffic.
+
+The VXLAN specification was originally created by VMware, Arista Networks
+and Cisco. Other backers of the VXLAN technology include Huawei, Broadcom,
+Citrix, Pica8, Big Switch Networks, Cumulus Networks, Dell EMC, Ericsson,
+Mellanox, FreeBSD, OpenBSD, Red Hat, Joyent, and Juniper Networks.
+
+VXLAN was officially documented by the IETF in :rfc:`7348`.
 
 If configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing
 (Hyper-V) or Forged Transmits (ESX) are permitted, otherwise forwarded frames
 may be blocked by the hypervisor.
 
+.. note:: As VyOS is based on Linux and there was no official IANA port assigned
+   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
 ^^^^^^^^^^^^^^^^
 
@@ -297,5 +322,5 @@ Let's change the Multicast example from above:
   # leaf3
   set interface vxlan vxlan241 remote 10.1.2.2
 
-The default port udp is set to 8472. 
+The default port udp is set to 8472.
 It can be changed with ``set interface vxlan <vxlanN> remote-port <port>``
diff --git a/docs/interfaces/wireless.rst b/docs/interfaces/wireless.rst
index ceb41b5d..e94eb09a 100644
--- a/docs/interfaces/wireless.rst
+++ b/docs/interfaces/wireless.rst
@@ -1,7 +1,7 @@
-.. _wireless:
+.. _wireless-interface:
 
-Wireless Interfaces
--------------------
+Wireless (Wi-Fi)
+----------------
 
 :abbr:`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless
 support (commonly referred to as Wi-Fi) by means of compatible hardware. If your
@@ -35,7 +35,7 @@ Configuring Access-Point
 
 The following example creates a WAP. When configuring multiple WAP interfaces,
 you must specify unique IP addresses, channels, Network IDs commonly refered
-to as :addr:`SSID (Service Set Identifier), and MAC addresses.
+to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses.
 
 The WAP in this example has the following characteristics:
 
@@ -84,8 +84,8 @@ Resulting in
 
 To get it to work as a access point with this configuration you will need
 to set up a DHCP server to work with that network. You can - of course - also
-bridge the Wireless interface with any configured bridge (:ref:`bridge`) on
-the system.
+bridge the Wireless interface with any configured bridge
+(:ref:`bridge-interface`) on the system.
 
 WPA/WPA2 enterprise
 *******************
@@ -196,10 +196,8 @@ about all wireless interfaces.
 .. code-block:: sh
 
   vyos@vyos:~$ show interfaces wireless info
-  Interface   Type        SSID             Channel
-  mon.wlan0   monitor     ?                ?
-  wlan0       AP          testing          3
-
+  Interface  Type          SSID                         Channel
+  wlan0      access-point  VyOS-TEST-0                        1
 
 .. option:: show interfaces wireless detail
 
@@ -209,13 +207,29 @@ information about all wireless interfaces.
 .. code-block:: sh
 
   vyos@vyos:~$ show interfaces wireless detail
-  wlan0: <NO?CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast state DOWN0
-      link/ether 00:21:91:d1:18:ca brd ff:ff:ff:ff:ff:ff
-      RX: bytes   packets   errors   dropped   overrun      mcast
-              0         0        0         0         0          0
-      TX: bytes   packets   errors   dropped   carrier collisions
-              0         0        0         0         0          0
-
+  wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+      link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+      inet xxx.xxx.99.254/24 scope global wlan0
+         valid_lft forever preferred_lft forever
+      inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link
+         valid_lft forever preferred_lft forever
+
+      RX:  bytes    packets     errors    dropped    overrun      mcast
+           66072        282          0          0          0          0
+      TX:  bytes    packets     errors    dropped    carrier collisions
+           83413        430          0          0          0          0
+
+  wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+      link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+      inet xxx.xxx.100.254/24 scope global wlan0
+         valid_lft forever preferred_lft forever
+      inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link
+         valid_lft forever preferred_lft forever
+
+      RX:  bytes    packets     errors    dropped    overrun      mcast
+           166072      5282          0          0          0          0
+      TX:  bytes    packets     errors    dropped    carrier collisions
+           183413      5430          0          0          0          0
 
 .. option:: show interfaces wireless <wlanX>
 
@@ -225,12 +239,17 @@ The wireless interface identifier can range from wlan0 to wlan999.
 .. code-block:: sh
 
   vyos@vyos:~$ show interfaces wireless wlan0
-  wlan0: <NO?CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast state DOWN0
-      link/ether 00:21:91:d1:18:ca brd ff:ff:ff:ff:ff:ff
-      RX: bytes   packets   errors   dropped   overrun      mcast
-              0         0        0         0         0          0
-      TX: bytes   packets   errors   dropped   carrier collisions
-              0         0        0         0         0          0
+  wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+      link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+      inet xxx.xxx.99.254/24 scope global wlan0
+         valid_lft forever preferred_lft forever
+      inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link
+         valid_lft forever preferred_lft forever
+
+      RX:  bytes    packets     errors    dropped    overrun      mcast
+           66072        282          0          0          0          0
+      TX:  bytes    packets     errors    dropped    carrier collisions
+           83413        430          0          0          0          0
 
 
 .. option:: show interfaces wireless <wlanX> brief
@@ -241,8 +260,10 @@ The wireless interface identifier can range from wlan0 to wlan999.
 .. code-block:: sh
 
   vyos@vyos:~$ show interfaces wireless wlan0 brief
-  Interface   IP Address         State   Link   Description
-  wlan0       192.168.40.1/24    up      up
+  Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+  Interface        IP Address                        S/L  Description
+  ---------        ----------                        ---  -----------
+  wlan0            192.0.2.254/24                    u/u
 
 
 .. option:: show interfaces wireless <wlanX> queue
@@ -250,7 +271,6 @@ The wireless interface identifier can range from wlan0 to wlan999.
 Use this command to view wireless interface queue information.
 The wireless interface identifier can range from wlan0 to wlan999.
 
-
 .. code-block:: sh
 
   vyos@vyos:~$ show interfaces wireless wlan0 queue
@@ -272,7 +292,19 @@ in station mode.
 .. code-block:: sh
 
   vyos@vyos:~$ show interfaces wireless wlan0 scan
-  Access-point       SSID             Chan    Signal (dbm)
-  00:53:00:b5:8b:d6  VyOS-TEST-NET    1       -77
-  00:53:29:10:45:03  GUESTS           11      -67
-  00:53:ab:20:45:03  Hotspot          10      -68
+  Address            SSID                          Channel  Signal (dbm)
+  00:53:3b:88:6e:d8  WLAN-576405                         1  -64.00
+  00:53:3b:88:6e:da  Telekom_FON                         1  -64.00
+  00:53:00:f2:c2:a4  BabyView_F2C2A4                     6  -60.00
+  00:53:3b:88:6e:d6  Telekom_FON                       100  -72.00
+  00:53:3b:88:6e:d4  WLAN-576405                       100  -71.00
+  00:53:44:a4:96:ec  KabelBox-4DC8                      56  -81.00
+  00:53:d9:7a:67:c2  WLAN-741980                         1  -75.00
+  00:53:7c:99:ce:76  Vodafone Homespot                   1  -86.00
+  00:53:44:a4:97:21  KabelBox-4DC8                       1  -78.00
+  00:53:44:a4:97:21  Vodafone Hotspot                    1  -79.00
+  00:53:44:a4:97:21  Vodafone Homespot                   1  -79.00
+  00:53:86:40:30:da  Telekom_FON                         1  -86.00
+  00:53:7c:99:ce:76  Vodafone Hotspot                    1  -86.00
+  00:53:44:46:d2:0b  Vodafone Hotspot                    1  -87.00
+