interfaces: add generic QinQ VLAN documentation

15 files changed, 199 insertions, 46 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