From a0a07c6ab314311909ee3c808d13a712cfba2fb2 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 23 Nov 2019 10:42:03 +0100 Subject: interfaces: update base interface definitions and links --- docs/interfaces/addresses.rst | 74 ++++++++++--------- docs/interfaces/bond.rst | 75 ++++++++++++++++++++ docs/interfaces/bonding.rst | 73 ------------------- docs/interfaces/bridge.rst | 112 +++++++++++++++++++++++++++++ docs/interfaces/bridging.rst | 112 ----------------------------- docs/interfaces/dummy.rst | 30 ++++---- docs/interfaces/ethernet.rst | 10 +-- docs/interfaces/index.rst | 4 +- docs/interfaces/l2tpv3.rst | 30 ++++---- docs/interfaces/pppoe.rst | 161 ++++++++++++++++++++++++++++++++---------- docs/interfaces/qinq.rst | 33 ++++++--- docs/interfaces/tunnel.rst | 6 +- docs/interfaces/vlan.rst | 38 +++++++--- docs/interfaces/vxlan.rst | 29 +++++++- docs/interfaces/wireless.rst | 92 ++++++++++++++++-------- 15 files changed, 535 insertions(+), 344 deletions(-) create mode 100644 docs/interfaces/bond.rst delete mode 100644 docs/interfaces/bonding.rst create mode 100644 docs/interfaces/bridge.rst delete mode 100644 docs/interfaces/bridging.rst 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 ipv6 router-advert send-advert + set interfaces ipv6 router-advert send-advert 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 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..accept_ra value 2 + vyos@vyos# set system sysctl custom net.ipv6.conf..accept_ra value 2 diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst new file mode 100644 index 00000000..05ed32c6 --- /dev/null +++ b/docs/interfaces/bond.rst @@ -0,0 +1,75 @@ +.. _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. + +Create interface bondX, where X is just a number: + +.. code-block:: sh + + set interfaces bonding bond0 description 'my-sw1 int 23 and 24' + +You are able to choose a hash policy: + +.. code-block:: sh + + vyos@vyos# set interfaces bonding bond0 hash-policy + Possible completions: + layer2 use MAC addresses to generate the hash (802.3ad) + layer2+3 combine MAC address and IP address to make hash + layer3+4 combine IP address and port to make hash + +For example: + +.. code-block:: sh + + set interfaces bonding bond0 hash-policy 'layer2' + +You may want to set IEEE 802.3ad Dynamic link aggregation (802.3ad) AKA LACP +(don't forget to setup it on the other end of these links): + +.. code-block:: sh + + set interfaces bonding bond0 mode '802.3ad' + +or some other modes: + +.. code-block:: sh + + vyos@vyos# set interfaces bonding bond0 mode + Possible completions: + 802.3ad IEEE 802.3ad Dynamic link aggregation (Default) + active-backup + Fault tolerant: only one slave in the bond is active + broadcast Fault tolerant: transmits everything on all slave interfaces + round-robin Load balance: transmit packets in sequential order + transmit-load-balance + Load balance: adapts based on transmit load and speed + adaptive-load-balance + Load balance: adapts based on transmit and receive plus ARP + xor-hash Load balance: distribute based on MAC address + +Now bond some physical interfaces into bond0: + +.. code-block:: sh + + set interfaces bonding bond0 member interface eth0 + set interfaces bonding bond0 member interface eth1 + +After a commit you may treat bond0 as almost a physical interface (you can't +change its` duplex, for example) and assign IPs or VIFs on it. + +You may check the result: + +.. code-block:: sh + + vyos@vyos# run sh interfaces bonding + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + bond0 - u/u my-sw1 int 23 and 24 + bond0.10 192.168.0.1/24 u/u office-net + bond0.100 10.10.10.1/24 u/u management-net diff --git a/docs/interfaces/bonding.rst b/docs/interfaces/bonding.rst deleted file mode 100644 index 72deb03b..00000000 --- a/docs/interfaces/bonding.rst +++ /dev/null @@ -1,73 +0,0 @@ -Bonding -------- - -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. - -Create interface bondX, where X is just a number: - -.. code-block:: sh - - set interfaces bonding bond0 description 'my-sw1 int 23 and 24' - -You are able to choose a hash policy: - -.. code-block:: sh - - vyos@vyos# set interfaces bonding bond0 hash-policy - Possible completions: - layer2 use MAC addresses to generate the hash (802.3ad) - layer2+3 combine MAC address and IP address to make hash - layer3+4 combine IP address and port to make hash - -For example: - -.. code-block:: sh - - set interfaces bonding bond0 hash-policy 'layer2' - -You may want to set IEEE 802.3ad Dynamic link aggregation (802.3ad) AKA LACP -(don't forget to setup it on the other end of these links): - -.. code-block:: sh - - set interfaces bonding bond0 mode '802.3ad' - -or some other modes: - -.. code-block:: sh - - vyos@vyos# set interfaces bonding bond0 mode - Possible completions: - 802.3ad IEEE 802.3ad Dynamic link aggregation (Default) - active-backup - Fault tolerant: only one slave in the bond is active - broadcast Fault tolerant: transmits everything on all slave interfaces - round-robin Load balance: transmit packets in sequential order - transmit-load-balance - Load balance: adapts based on transmit load and speed - adaptive-load-balance - Load balance: adapts based on transmit and receive plus ARP - xor-hash Load balance: distribute based on MAC address - -Now bond some physical interfaces into bond0: - -.. code-block:: sh - - set interfaces bonding bond0 member interface eth0 - set interfaces bonding bond0 member interface eth1 - -After a commit you may treat bond0 as almost a physical interface (you can't -change its` duplex, for example) and assign IPs or VIFs on it. - -You may check the result: - -.. code-block:: sh - - vyos@vyos# run sh interfaces bonding - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - bond0 - u/u my-sw1 int 23 and 24 - bond0.10 192.168.0.1/24 u/u office-net - bond0.100 10.10.10.1/24 u/u management-net diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst new file mode 100644 index 00000000..6c8510b5 --- /dev/null +++ b/docs/interfaces/bridge.rst @@ -0,0 +1,112 @@ +.. _bridge-interface: + +Bridge +------ + +Interfaces in VyOS can be bridged together to provide software switching of +Layer-2 traffic. + +A bridge is created when a bridge interface is defined. In the example below +we create a bridge named br100 with eth1 and eth2 as the bridge member ports. + +.. code-block:: sh + + set interfaces bridge 'br100' + set interfaces bridge br100 member interface eth1 + set interfaces bridge br100 member interface eth2 + +Each bridge member can be assiged a port cost and priority using the following +commands: + +.. code-block:: sh + + set interfaces bridge br100 member interface eth1 cost 10 + set interfaces bridge br100 member interface eth1 priority 1024 + +Interfaces assigned to a bridge do not have address configuration. An IP +address can be assigned to the bridge interface itself, however, like any +normal interface. + +.. code-block:: sh + + set interfaces bridge br100 address '192.168.100.1/24' + set interfaces bridge br100 address '2001:db8:100::1/64' + +Example Result: + +.. code-block:: sh + + bridge br100 { + address 192.168.100.1/24 + address 2001:db8:100::1/64 + member { + interface eth1 { + cost 10 + priority 1024 + } + interface eth2 { + } + } + + } + [...] + +In addition to normal IP interface configuration, bridge interfaces support +Spanning-Tree Protocol. STP is disabled by default. + +.. note:: Please use caution when introducing spanning-tree protocol on a + network as it may result in topology changes. + +To enable spanning-tree use the `set interfaces bridge stp` command: + +.. code-block:: sh + + set interfaces bridge br100 stp + +STP `priority`, `forwarding-delay`, `hello-time`, and `max-age` can be +configured for the bridge. The MAC aging time can also be configured +using the `aging` directive. + +The `show bridge` operational command can be used to display configured +bridges: + +.. code-block:: sh + + vyos@vyos:~$ show bridge + bridge name bridge id STP enabled interfaces + br100 0000.000c29443b19 yes eth1.100 + +If spanning-tree is enabled, the `show bridge spanning-tree` command +can be used to show STP configuration: + +.. code-block:: sh + + vyos@vyos:~$ show bridge br100 spanning-tree + br100 + bridge id 0000.000c29443b19 + designated root 0000.000c29443b19 + root port 0 path cost 0 + max age 20.00 bridge max age 20.00 + hello time 2.00 bridge hello time 2.00 + forward delay 15.00 bridge forward delay 15.00 + ageing time 300.00 + hello timer 0.47 tcn timer 0.00 + topology change timer 0.00 gc timer 64.63 + flags + + eth1.100 (1) + port id 8001 state forwarding + designated root 0000.000c29443b19 path cost 4 + designated bridge 0000.000c29443b19 message age timer 0.00 + designated port 8001 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + flags + +The MAC address-table for a bridge can be displayed using the +`show bridge macs` command: + +.. code-block:: sh + + vyos@vyos:~$ show bridge br100 macs + port no mac addr is local? ageing timer + 1 00:0c:29:44:3b:19 yes 0.00 diff --git a/docs/interfaces/bridging.rst b/docs/interfaces/bridging.rst deleted file mode 100644 index f31e30e6..00000000 --- a/docs/interfaces/bridging.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _bridge: - -Interface Bridge ----------------- - -Interfaces in VyOS can be bridged together to provide software switching of -Layer-2 traffic. - -A bridge is created when a bridge interface is defined. In the example below -we create a bridge named br100 with eth1 and eth2 as the bridge member ports. - -.. code-block:: sh - - set interfaces bridge 'br100' - set interfaces bridge br100 member interface eth1 - set interfaces bridge br100 member interface eth2 - -Each bridge member can be assiged a port cost and priority using the following -commands: - -.. code-block:: sh - - set interfaces bridge br100 member interface eth1 cost 10 - set interfaces bridge br100 member interface eth1 priority 1024 - -Interfaces assigned to a bridge do not have address configuration. An IP -address can be assigned to the bridge interface itself, however, like any -normal interface. - -.. code-block:: sh - - set interfaces bridge br100 address '192.168.100.1/24' - set interfaces bridge br100 address '2001:db8:100::1/64' - -Example Result: - -.. code-block:: sh - - bridge br100 { - address 192.168.100.1/24 - address 2001:db8:100::1/64 - member { - interface eth1 { - cost 10 - priority 1024 - } - interface eth2 { - } - } - - } - [...] - -In addition to normal IP interface configuration, bridge interfaces support -Spanning-Tree Protocol. STP is disabled by default. - -.. note:: Please use caution when introducing spanning-tree protocol on a - network as it may result in topology changes. - -To enable spanning-tree use the `set interfaces bridge stp` command: - -.. code-block:: sh - - set interfaces bridge br100 stp - -STP `priority`, `forwarding-delay`, `hello-time`, and `max-age` can be -configured for the bridge. The MAC aging time can also be configured -using the `aging` directive. - -The `show bridge` operational command can be used to display configured -bridges: - -.. code-block:: sh - - vyos@vyos:~$ show bridge - bridge name bridge id STP enabled interfaces - br100 0000.000c29443b19 yes eth1.100 - -If spanning-tree is enabled, the `show bridge spanning-tree` command -can be used to show STP configuration: - -.. code-block:: sh - - vyos@vyos:~$ show bridge br100 spanning-tree - br100 - bridge id 0000.000c29443b19 - designated root 0000.000c29443b19 - root port 0 path cost 0 - max age 20.00 bridge max age 20.00 - hello time 2.00 bridge hello time 2.00 - forward delay 15.00 bridge forward delay 15.00 - ageing time 300.00 - hello timer 0.47 tcn timer 0.00 - topology change timer 0.00 gc timer 64.63 - flags - - eth1.100 (1) - port id 8001 state forwarding - designated root 0000.000c29443b19 path cost 4 - designated bridge 0000.000c29443b19 message age timer 0.00 - designated port 8001 forward delay timer 0.00 - designated cost 0 hold timer 0.00 - flags - -The MAC address-table for a bridge can be displayed using the -`show bridge macs` command: - -.. code-block:: sh - - vyos@vyos:~$ show bridge br100 macs - port no mac addr is local? ageing timer - 1 00:0c:29:44:3b:19 yes 0.00 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 - + 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 physical` -* `show interfaces ethernet statistics` +* ``show interfaces ethernet physical`` +* ``show interfaces ethernet 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 - set interface ethernet eth0 pppoe 0 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 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 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 vif `. +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:: sh @@ -44,4 +67,3 @@ VLAN interfaces are shown as `.`, 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 remote-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: 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: 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: 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 @@ -225,12 +239,17 @@ The wireless interface identifier can range from wlan0 to wlan999. .. code-block:: sh vyos@vyos:~$ show interfaces wireless wlan0 - wlan0: 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: 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 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 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 + -- cgit v1.2.3