interfaces: add generic QinQ VLAN documentation

24 files changed, 227 insertions, 199 deletions

diff --git a/docs/_include/interface-address-with-dhcp.txt b/docs/_include/interface-address-with-dhcp.txt
index 20cd53ac..4ff78c01 100644
--- a/docs/_include/interface-address-with-dhcp.txt
+++ b/docs/_include/interface-address-with-dhcp.txt
@@ -1,4 +1,5 @@
-.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} address <address | dhcp |
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} address <address | dhcp |
    dhcpv6>
 
   Configure interface `<interface>` with one or more interface addresses.
@@ -14,7 +15,7 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} address 192.0.2.1/24
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} address 2001:db8::1/64
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcp
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcpv6
\ No newline at end of file
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} address 192.0.2.1/24
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} address 2001:db8::1/64
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6
\ No newline at end of file
diff --git a/docs/_include/interface-description.txt b/docs/_include/interface-description.txt
index 4347b837..064d9559 100644
--- a/docs/_include/interface-description.txt
+++ b/docs/_include/interface-description.txt
@@ -1,4 +1,5 @@
-.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} description <description>
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} description <description>
 
   Set a human readable, descriptive alias for this connection. Alias is used by
   e.g. the :opcmd:`show interfaces` command or SNMP based monitoring tools.
@@ -7,4 +8,4 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} description 'This is an awesome interface running on VyOS'
\ No newline at end of file
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} description 'This is an awesome interface running on VyOS'
\ No newline at end of file
diff --git a/docs/_include/interface-dhcp-options.txt b/docs/_include/interface-dhcp-options.txt
index 2bc23efc..1a0ce260 100644
--- a/docs/_include/interface-dhcp-options.txt
+++ b/docs/_include/interface-dhcp-options.txt
@@ -1,5 +1,5 @@
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-   dhcp-options client-id <description>
+  {{ var5 }} {{ var6 }} dhcp-options client-id <description>
 
   :rfc:`2131` states: The client MAY choose to explicitly provide the identifier
   through the 'client identifier' option. If the client supplies a 'client
@@ -11,10 +11,10 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcp-options client-id 'foo-bar'
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options client-id 'foo-bar'
 
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  dhcp-options host-name <hostname>
+  {{ var5 }} {{ var6 }} dhcp-options host-name <hostname>
 
   Instead of sending the real system hostname to the DHCP server, overwrite the
   host-name with this given-value.
@@ -23,10 +23,10 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcp-options host-name 'VyOS'
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options host-name 'VyOS'
 
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  dhcp-options vendor-class-id <vendor-id>
+  {{ var5 }} {{ var6 }} dhcp-options vendor-class-id <vendor-id>
 
   The vendor-class-id option can be used to request a specific class of vendor
   options from the server.
@@ -35,10 +35,10 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcp-options vendor-class-id 'VyOS'
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options vendor-class-id 'VyOS'
 
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  dhcp-options no-default-route
+  {{ var5 }} {{ var6 }} dhcp-options no-default-route
 
   Only request an address from the DHCP server but do not request a default
   gateway.
@@ -47,4 +47,4 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcp-options no-default-route
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options no-default-route
diff --git a/docs/_include/interface-dhcpv6-options.txt b/docs/_include/interface-dhcpv6-options.txt
index 00b5e817..a54a7dce 100644
--- a/docs/_include/interface-dhcpv6-options.txt
+++ b/docs/_include/interface-dhcpv6-options.txt
@@ -1,5 +1,5 @@
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  dhcpv6-options parameters-only
+  {{ var5 }} {{ var6 }} dhcpv6-options parameters-only
 
   This statement specifies dhcp6c to only exchange informational configuration
   parameters with servers. A list of DNS server addresses is an example of such
@@ -8,27 +8,27 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcpv6-options parameters-only
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options parameters-only
 
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  dhcpv6-options rapid-commit
+  {{ var5 }} {{ var6 }} dhcpv6-options rapid-commit
 
   When rapid-commit is specified, dhcp6c will include a rapid-commit option in
   solicit messages and wait for an immediate reply instead of advertisements.
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcpv6-options rapid-commit
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options rapid-commit
 
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  dhcpv6-options temporary
+  {{ var5 }} {{ var6 }} dhcpv6-options temporary
 
   Request only a temporary address and not form an IA_NA (Identity Association
   for Non-temporary Addresses) partnership.
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcpv6-options temporary
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options temporary
 
 .. cmdinclude:: ../_include/interface-dhcpv6-prefix-delegation.txt
   :var0: {{ var0 }}
@@ -36,3 +36,7 @@
   :var2: {{ var2 }}
   :var3: {{ var3 }}
   :var4: {{ var4 }}
+  :var5: {{ var5 }}
+  :var6: {{ var6 }}
+  :var7: {{ var7 }}
+
diff --git a/docs/_include/interface-dhcpv6-prefix-delegation.txt b/docs/_include/interface-dhcpv6-prefix-delegation.txt
index 21721400..99132d17 100644
--- a/docs/_include/interface-dhcpv6-prefix-delegation.txt
+++ b/docs/_include/interface-dhcpv6-prefix-delegation.txt
@@ -4,7 +4,7 @@ VyOS 1.3 (equuleus) supports DHCPv6-PD (:rfc:`3633`). DHCPv6 Prefix Delegation
 is supported by most ISPs who provide native IPv6 for consumers on fixed networks.
 
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  dhcpv6-option pd <id> length <length>
+  {{ var5 }} {{ var6 }} dhcpv6-option pd <id> length <length>
 
   Some ISPs by default only delegate a /64 prefix. To request for a specific
   prefix size use this option to request for a bigger delegation for this pd
@@ -17,10 +17,10 @@ is supported by most ISPs who provide native IPv6 for consumers on fixed network
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcpv6-options pd 0 length 56
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options pd 0 length 56
 
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  dhcpv6-option pd <id> interface <delegatee> address <address>
+  {{ var5 }} {{ var6 }} dhcpv6-option pd <id> interface <delegatee> address <address>
 
   Specify the interface address used locally on the interfcae where the prefix
   has been delegated to. ID must be a decimal integer.
@@ -35,10 +35,10 @@ is supported by most ISPs who provide native IPv6 for consumers on fixed network
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcpv6-option pd 0 interface eth8 address 65534
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-option pd 0 interface eth8 address 65534
 
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  dhcpv6-option pd <id> interface <delegatee> sla-id <id>
+  {{ var5 }} {{ var6 }} dhcpv6-option pd <id> interface <delegatee> sla-id <id>
 
   Specify the identifier value of the site-level aggregator (SLA) on the
   interface. ID must be a decimal number greater then 0 which fits in the
@@ -51,5 +51,5 @@ is supported by most ISPs who provide native IPv6 for consumers on fixed network
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} dhcpv6-option pd 0 interface eth8 sla-id 1
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-option pd 0 interface eth8 sla-id 1
 
diff --git a/docs/_include/interface-disable-link-detect.txt b/docs/_include/interface-disable-link-detect.txt
index efd45e46..1a766715 100644
--- a/docs/_include/interface-disable-link-detect.txt
+++ b/docs/_include/interface-disable-link-detect.txt
@@ -1,5 +1,5 @@
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  disable-link-detect
+  {{ var5 }} {{ var6 }} disable-link-detect
 
   Use this command to direct an interface to not detect any physical state
   changes on a link, for example, when the cable is unplugged.
@@ -10,4 +10,4 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} disable-link-detect
\ No newline at end of file
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} disable-link-detect
\ No newline at end of file
diff --git a/docs/_include/interface-disable.txt b/docs/_include/interface-disable.txt
index a9511d8e..774c1cdd 100644
--- a/docs/_include/interface-disable.txt
+++ b/docs/_include/interface-disable.txt
@@ -1,4 +1,5 @@
-.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} disable
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} disable
 
   Disable given `<interface>`. It will be placed in administratively down
   (``A/D``) state.
@@ -7,4 +8,4 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} disable
\ No newline at end of file
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} disable
\ No newline at end of file
diff --git a/docs/_include/interface-ipv6-addr-autoconf.txt b/docs/_include/interface-ipv6-addr-autoconf.txt
index e349a730..fea1125e 100644
--- a/docs/_include/interface-ipv6-addr-autoconf.txt
+++ b/docs/_include/interface-ipv6-addr-autoconf.txt
@@ -1,5 +1,5 @@
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  ipv6 address autoconf
+  {{ var5 }} {{ var6 }} ipv6 address autoconf
 
   :abbr:`SLAAC (Stateless Address Autoconfiguration)` :rfc:`4862`. IPv6 hosts
   can configure themselves automatically when connected to an IPv6 network using
@@ -16,4 +16,4 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} ipv6 address autoconf
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 address autoconf
diff --git a/docs/_include/interface-ipv6-addr-eui64.txt b/docs/_include/interface-ipv6-addr-eui64.txt
index 10732bf3..e6a58372 100644
--- a/docs/_include/interface-ipv6-addr-eui64.txt
+++ b/docs/_include/interface-ipv6-addr-eui64.txt
@@ -1,9 +1,9 @@
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  ipv6 address eui64 <prefix>
+  {{ var5 }} {{ var6 }} 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 {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} ipv6 address eui64 2001:db8:beef::/64
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 address eui64 2001:db8:beef::/64
diff --git a/docs/_include/interface-mac.txt b/docs/_include/interface-mac.txt
index 2daeaccf..03aa6106 100644
--- a/docs/_include/interface-mac.txt
+++ b/docs/_include/interface-mac.txt
@@ -1,5 +1,5 @@
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  mac <xx:xx:xx:xx:xx:xx>
+  {{ var5 }} {{ var6 }} mac <xx:xx:xx:xx:xx:xx>
 
   Configure user defined :abbr:`MAC (Media Access Control)` address on given
   `<interface>`.
@@ -8,4 +8,4 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} mac '00:01:02:03:04:05'
\ No newline at end of file
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} mac '00:01:02:03:04:05'
\ No newline at end of file
diff --git a/docs/_include/interface-mtu.txt b/docs/_include/interface-mtu.txt
index 8509779b..76812507 100644
--- a/docs/_include/interface-mtu.txt
+++ b/docs/_include/interface-mtu.txt
@@ -1,5 +1,5 @@
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  mtu <mtu>
+  {{ var5 }} {{ var6 }} 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.
@@ -8,4 +8,4 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} mtu 1450
\ No newline at end of file
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} mtu 9000
\ No newline at end of file
diff --git a/docs/_include/interface-vlan-8021ad.txt b/docs/_include/interface-vlan-8021ad.txt
new file mode 100644
index 00000000..a1e971be
--- /dev/null
+++ b/docs/_include/interface-vlan-8021ad.txt
@@ -0,0 +1,143 @@
+.. include:: ../_include/need_improvement.txt
+
+IEEE 802.1ad_ was an Ethernet networking standard informally known as QinQ as
+an amendment to IEEE standard 802.1q VLAN interfaces as described above.
+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).
+
+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.
+
+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).
+
+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 Ethernet Type = 0x88a8).
+
+
+.. cmdinclude:: ../_include/interface-address-with-dhcp.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+.. cmdinclude:: ../_include/interface-description.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+.. cmdinclude:: ../_include/interface-disable.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+.. cmdinclude:: ../_include/interface-disable-link-detect.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+.. cmdinclude:: ../_include/interface-mac.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+.. cmdinclude:: ../_include/interface-mtu.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+.. cmdinclude:: ../_include/interface-vrf.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+**DHCP(v6)**
+
+.. cmdinclude:: ../_include/interface-dhcp-options.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+.. cmdinclude:: ../_include/interface-dhcpv6-options.txt
+   :var0: {{ var0 }}
+   :var1: {{ var1 }}
+   :var2: vif-s
+   :var3: <vlan-id>
+   :var4: 1000
+   :var5: vif-c
+   :var6: <vlan-id>
+   :var7: 20
+
+.. include:: ../common-references.rst
diff --git a/docs/_include/interface-vlan.txt b/docs/_include/interface-vlan-8021q.txt
index f1948e84..2c7e58f7 100644
--- a/docs/_include/interface-vlan.txt
+++ b/docs/_include/interface-vlan-8021q.txt
@@ -1,11 +1,11 @@
-IEEE 802.1q, often referred to as Dot1q, is the networking standard that supports
+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
+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
@@ -106,4 +106,6 @@ term used for this is ``vif``.
    :var1: {{ var1 }}
    :var2: vif
    :var3: <vlan-id>
-   :var4: 10
\ No newline at end of file
+   :var4: 10
+
+.. include:: ../common-references.rst
\ No newline at end of file
diff --git a/docs/_include/interface-vrf.txt b/docs/_include/interface-vrf.txt
index 450c82aa..1fa94f9f 100644
--- a/docs/_include/interface-vrf.txt
+++ b/docs/_include/interface-vrf.txt
@@ -1,5 +1,5 @@
 .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
-  vrf <vrf>
+  {{ var5 }} {{ var6 }} vrf <vrf>
 
   Place interface in given VRF instance.
 
@@ -10,4 +10,4 @@
 
   .. code-block:: none
 
-    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} vrf red
\ No newline at end of file
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} vrf red
\ No newline at end of file
diff --git a/docs/_include/need_improvement.txt b/docs/_include/need_improvement.txt
index f7556465..1ce50685 100644
--- a/docs/_include/need_improvement.txt
+++ b/docs/_include/need_improvement.txt
@@ -8,8 +8,9 @@
    <p class="admonition-title">Call for Contributions</p>
 
 
-This page needs improvements, examples and explanations.
-Please take a look at the Contributing Guide for :ref:`documentation`.
+This section needs improvements, examples and explanations.
+
+Please take a look at the Contributing Guide for our :ref:`documentation`.
 
 .. raw:: html
 
diff --git a/docs/common-references.rst b/docs/common-references.rst
index d7e376eb..79881972 100644
--- a/docs/common-references.rst
+++ b/docs/common-references.rst
@@ -1,3 +1,6 @@
 .. _`accel-ppp`: https://accel-ppp.org/
 .. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol
 .. _Phabricator: https://phabricator.vyos.net/
+
+.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad
+.. _802.1q: https://en.wikipedia.org/wiki/IEEE_802.1Q
diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst
index 6e35dac2..7b9bde1e 100644
--- a/docs/interfaces/advanced-index.rst
+++ b/docs/interfaces/advanced-index.rst
@@ -17,9 +17,7 @@ Network Interfaces
    macsec
    pppoe
    pseudo-ethernet
-   qinq
    tunnel
-   vlan
    vxlan
    wireless
    wirelessmodem
diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst
index eea35e2c..7faddd6f 100644
--- a/docs/interfaces/bond.rst
+++ b/docs/interfaces/bond.rst
@@ -259,7 +259,7 @@ Bond options
 VLAN
 ====
 
-.. cmdinclude:: ../_include/interface-vlan.txt
+.. cmdinclude:: ../_include/interface-vlan-8021q.txt
    :var0: bond
    :var1: bond0
 
diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst
index 045ae2a8..dc94a761 100644
--- a/docs/interfaces/bridge.rst
+++ b/docs/interfaces/bridge.rst
@@ -116,7 +116,7 @@ links providing fault tolerance if an active link fails.
 VLAN
 ====
 
-.. cmdinclude:: ../_include/interface-vlan.txt
+.. cmdinclude:: ../_include/interface-vlan-8021q.txt
    :var0: bridge
    :var1: br0
 
diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst
index 343a7d59..8b1ad6bd 100644
--- a/docs/interfaces/ethernet.rst
+++ b/docs/interfaces/ethernet.rst
@@ -52,7 +52,17 @@ Ethernet options
 VLAN
 ====
 
-.. cmdinclude:: ../_include/interface-vlan.txt
+Regular VLANs (802.1q)
+----------------------
+
+.. cmdinclude:: ../_include/interface-vlan-8021q.txt
+   :var0: ethernet
+   :var1: eth0
+
+QinQ (802.1ad)
+--------------
+
+.. cmdinclude:: ../_include/interface-vlan-8021ad.txt
    :var0: ethernet
    :var1: eth0
 
diff --git a/docs/interfaces/pseudo-ethernet.rst b/docs/interfaces/pseudo-ethernet.rst
index d4eb8eff..c2baca39 100644
--- a/docs/interfaces/pseudo-ethernet.rst
+++ b/docs/interfaces/pseudo-ethernet.rst
@@ -60,6 +60,6 @@ Pseudo Ethernet/MACVLAN options
 VLAN
 ====
 
-.. cmdinclude:: ../_include/interface-vlan.txt
+.. cmdinclude:: ../_include/interface-vlan-8021q.txt
    :var0: pseudo-ethernet
    :var1: peth0
diff --git a/docs/interfaces/qinq.rst b/docs/interfaces/qinq.rst
deleted file mode 100644
index 01d9c64a..00000000
--- a/docs/interfaces/qinq.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-.. include:: ../_include/need_improvement.txt
-
-.. _qinq-interface:
-
-QinQ (802.1ad)
---------------
-
-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).
-
-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.
-
-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).
-
-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:
-
-.. code-block:: none
-
-  interfaces
-      ethernet <eth[0-999]>
-          address <ipv4>
-          address <ipv6>
-          description <txt>
-          disable
-          ip
-              <usual IP options>
-          ipv6
-              <usual IPv6 options>
-          vif-s <[0-4096]>
-              address <ipv4>
-              address <ipv6>
-              description <txt>
-              disable
-              ip
-                  <usual IP options>
-              ipv6
-                  <usual IPv6 options>
-              vif-c <[0-4096]>
-                  address <ipv4>
-                  address <ipv6>
-                  description <txt>
-                  disable
-                  ip
-                      <usual IP options>
-                  ipv6
-                      <usual IPv6 options>
-
-
-Example:
-
-.. code-block:: none
-
-  set interfaces ethernet eth0 vif-s 333
-  set interfaces ethernet eth0 vif-s 333 address 192.0.2.10/32
-  set interfaces ethernet eth0 vif-s 333 vif-c 777
-  set interfaces ethernet eth0 vif-s 333 vif-c 777 address 10.10.10.10/24
-
-.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad
\ No newline at end of file
diff --git a/docs/interfaces/vlan.rst b/docs/interfaces/vlan.rst
deleted file mode 100644
index 55656d5d..00000000
--- a/docs/interfaces/vlan.rst
+++ /dev/null
@@ -1,69 +0,0 @@
-.. _vlan-interface:
-
-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:: none
-
-  set interfaces ethernet eth1 vif 100 description 'VLAN 100'
-  set interfaces ethernet eth1 vif 100 address '192.168.100.1/24'
-  set interfaces ethernet eth1 vif 100 address '2001:db8:100::1/64'
-
-Resulting in:
-
-.. code-block:: none
-
-  ethernet eth1 {
-      address 192.168.100.1/24
-      address 2001:db8:100::1/64
-      description INSIDE
-      duplex auto
-      hw-id 00:53:29:44:3b:19
-      smp_affinity auto
-      speed auto
-      vif 100 {
-          address 192.168.100.1/24
-          description "VLAN 100"
-      }
-  }
-
-VLAN interfaces are shown as `<name>.<vlan-id>`, e.g. `eth1.100`:
-
-.. 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
-  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/wireless.rst b/docs/interfaces/wireless.rst
index b51eb274..2de3b126 100644
--- a/docs/interfaces/wireless.rst
+++ b/docs/interfaces/wireless.rst
@@ -375,7 +375,17 @@ Resulting in
 VLAN
 ====
 
-.. cmdinclude:: ../_include/interface-vlan.txt
+Regular VLANs (802.1q)
+----------------------
+
+.. cmdinclude:: ../_include/interface-vlan-8021q.txt
+   :var0: wireless
+   :var1: wlan0
+
+QinQ (802.1ad)
+--------------
+
+.. cmdinclude:: ../_include/interface-vlan-8021ad.txt
    :var0: wireless
    :var1: wlan0