interfaces: update base interface definitions and links

1 files changed, 30 insertions, 8 deletions

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
-