From 7399b53b9d09ef07219631f79aeebd87c1b98d1e Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Tue, 24 Nov 2020 19:38:52 +0100 Subject: interfaces: add generic QinQ VLAN documentation --- docs/_include/interface-address-with-dhcp.txt | 11 +- docs/_include/interface-description.txt | 5 +- docs/_include/interface-dhcp-options.txt | 16 +-- docs/_include/interface-dhcpv6-options.txt | 16 ++- .../interface-dhcpv6-prefix-delegation.txt | 12 +- docs/_include/interface-disable-link-detect.txt | 4 +- docs/_include/interface-disable.txt | 5 +- docs/_include/interface-ipv6-addr-autoconf.txt | 4 +- docs/_include/interface-ipv6-addr-eui64.txt | 4 +- docs/_include/interface-mac.txt | 4 +- docs/_include/interface-mtu.txt | 4 +- docs/_include/interface-vlan-8021ad.txt | 143 +++++++++++++++++++++ docs/_include/interface-vlan-8021q.txt | 111 ++++++++++++++++ docs/_include/interface-vlan.txt | 109 ---------------- docs/_include/interface-vrf.txt | 4 +- docs/_include/need_improvement.txt | 5 +- docs/common-references.rst | 3 + docs/interfaces/advanced-index.rst | 2 - docs/interfaces/bond.rst | 2 +- docs/interfaces/bridge.rst | 2 +- docs/interfaces/ethernet.rst | 12 +- docs/interfaces/pseudo-ethernet.rst | 2 +- docs/interfaces/qinq.rst | 77 ----------- docs/interfaces/vlan.rst | 69 ---------- docs/interfaces/wireless.rst | 12 +- 25 files changed, 333 insertions(+), 305 deletions(-) create mode 100644 docs/_include/interface-vlan-8021ad.txt create mode 100644 docs/_include/interface-vlan-8021q.txt delete mode 100644 docs/_include/interface-vlan.txt delete mode 100644 docs/interfaces/qinq.rst delete mode 100644 docs/interfaces/vlan.rst 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 }} {{ var2 }} {{ var3 }} address
{{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} address
Configure 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 }} {{ var2 }} {{ var3 }} description +.. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} 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 }} {{ var2 }} {{ var3 }} - dhcp-options client-id + {{ var5 }} {{ var6 }} dhcp-options client-id :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 }} {{ var2 }} {{ var3 }} - dhcp-options host-name + {{ var5 }} {{ var6 }} dhcp-options host-name 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 }} {{ var2 }} {{ var3 }} - dhcp-options vendor-class-id + {{ var5 }} {{ var6 }} dhcp-options vendor-class-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 }} {{ 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 }} {{ 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 }} {{ 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 }} {{ 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 }} {{ var2 }} {{ var3 }} - dhcpv6-option pd length + {{ var5 }} {{ var6 }} dhcpv6-option pd 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 }} {{ var2 }} {{ var3 }} - dhcpv6-option pd interface address
+ {{ var5 }} {{ var6 }} dhcpv6-option pd interface 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 }} {{ var2 }} {{ var3 }} - dhcpv6-option pd interface sla-id + {{ var5 }} {{ var6 }} dhcpv6-option pd interface sla-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 }} {{ 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 }} {{ var2 }} {{ var3 }} disable +.. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} disable Disable given ``. 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 }} {{ 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 }} {{ var2 }} {{ var3 }} - ipv6 address eui64 + {{ var5 }} {{ var6 }} ipv6 address eui64 :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 }} {{ var2 }} {{ var3 }} - mac + {{ var5 }} {{ var6 }} mac Configure user defined :abbr:`MAC (Media Access Control)` address on given ``. @@ -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 }} {{ var2 }} {{ var3 }} - mtu + {{ var5 }} {{ var6 }} mtu Configure :abbr:`MTU (Maximum Transmission Unit)` on given ``. 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: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +.. cmdinclude:: ../_include/interface-description.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +.. cmdinclude:: ../_include/interface-disable.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +.. cmdinclude:: ../_include/interface-disable-link-detect.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +.. cmdinclude:: ../_include/interface-mac.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +.. cmdinclude:: ../_include/interface-mtu.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +.. cmdinclude:: ../_include/interface-vrf.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +**DHCP(v6)** + +.. cmdinclude:: ../_include/interface-dhcp-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +.. cmdinclude:: ../_include/interface-dhcpv6-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: + :var4: 1000 + :var5: vif-c + :var6: + :var7: 20 + +.. include:: ../common-references.rst diff --git a/docs/_include/interface-vlan-8021q.txt b/docs/_include/interface-vlan-8021q.txt new file mode 100644 index 00000000..2c7e58f7 --- /dev/null +++ b/docs/_include/interface-vlan-8021q.txt @@ -0,0 +1,111 @@ +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.1q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The +term used for this is ``vif``. + +.. cfgcmd:: set interfaces {{ var0 }} vif + + Create a new VLAN interface on interface `` using the VLAN number + provided via ``. + + You can create multiple VLAN interfaces on a physical interface. The VLAN ID + range is from 0 to 4094. + + .. note:: Only 802.1Q-tagged packets are accepted on Ethernet vifs. + +.. cmdinclude:: ../_include/interface-address-with-dhcp.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +.. cmdinclude:: ../_include/interface-description.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +.. cmdinclude:: ../_include/interface-disable.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +.. cmdinclude:: ../_include/interface-disable-link-detect.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +.. cmdinclude:: ../_include/interface-mac.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +.. cmdinclude:: ../_include/interface-mtu.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +.. cmdinclude:: ../_include/interface-vrf.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +**DHCP(v6)** + +.. cmdinclude:: ../_include/interface-dhcp-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +.. cmdinclude:: ../_include/interface-dhcpv6-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: + :var4: 10 + +.. include:: ../common-references.rst \ No newline at end of file diff --git a/docs/_include/interface-vlan.txt b/docs/_include/interface-vlan.txt deleted file mode 100644 index f1948e84..00000000 --- a/docs/_include/interface-vlan.txt +++ /dev/null @@ -1,109 +0,0 @@ -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.1q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The -term used for this is ``vif``. - -.. cfgcmd:: set interfaces {{ var0 }} vif - - Create a new VLAN interface on interface `` using the VLAN number - provided via ``. - - You can create multiple VLAN interfaces on a physical interface. The VLAN ID - range is from 0 to 4094. - - .. note:: Only 802.1Q-tagged packets are accepted on Ethernet vifs. - -.. cmdinclude:: ../_include/interface-address-with-dhcp.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 - -.. cmdinclude:: ../_include/interface-description.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 - -.. cmdinclude:: ../_include/interface-disable.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 - -.. cmdinclude:: ../_include/interface-disable-link-detect.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 - -.. cmdinclude:: ../_include/interface-mac.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 - -.. cmdinclude:: ../_include/interface-mtu.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 - -.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 - -.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 - -.. cmdinclude:: ../_include/interface-vrf.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 - -**DHCP(v6)** - -.. cmdinclude:: ../_include/interface-dhcp-options.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 - -.. cmdinclude:: ../_include/interface-dhcpv6-options.txt - :var0: {{ var0 }} - :var1: {{ var1 }} - :var2: vif - :var3: - :var4: 10 \ 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 }} {{ var2 }} {{ var3 }} - vrf + {{ var5 }} {{ var6 }} 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 @@

Call for Contributions

-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 - address - address - description - disable - ip - - ipv6 - - vif-s <[0-4096]> - address - address - description - disable - ip - - ipv6 - - vif-c <[0-4096]> - address - address - description - disable - ip - - ipv6 - - - -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 vif `` - -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 `.`, 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 -- cgit v1.2.3