diff options
| -rw-r--r-- | docs/interfaces/advanced-index.rst | 7 | ||||
| -rw-r--r-- | docs/interfaces/bond.rst | 41 | ||||
| -rw-r--r-- | docs/interfaces/bridge.rst | 52 | ||||
| -rw-r--r-- | docs/interfaces/dummy.rst | 9 | ||||
| -rw-r--r-- | docs/interfaces/ethernet.rst | 22 | ||||
| -rw-r--r-- | docs/interfaces/geneve.rst | 9 | ||||
| -rw-r--r-- | docs/interfaces/l2tpv3.rst | 75 | ||||
| -rw-r--r-- | docs/interfaces/loopback.rst | 8 | ||||
| -rw-r--r-- | docs/interfaces/macsec.rst | 19 | ||||
| -rw-r--r-- | docs/interfaces/pppoe.rst | 24 | ||||
| -rw-r--r-- | docs/interfaces/pseudo-ethernet.rst | 9 | ||||
| -rw-r--r-- | docs/interfaces/wirelessmodem.rst | 57 | ||||
| -rw-r--r-- | docs/routing/mpls.rst | 6 |
13 files changed, 210 insertions, 128 deletions
diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst index f955c6b1..6e35dac2 100644 --- a/docs/interfaces/advanced-index.rst +++ b/docs/interfaces/advanced-index.rst @@ -1,8 +1,8 @@ .. _advanced_network-interfaces: -########################### -Advanced Network Interfaces -########################### +################## +Network Interfaces +################## .. toctree:: :maxdepth: 1 @@ -15,6 +15,7 @@ Advanced Network Interfaces loopback l2tpv3 macsec + pppoe pseudo-ethernet qinq tunnel diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst index 859c25c3..21088c02 100644 --- a/docs/interfaces/bond.rst +++ b/docs/interfaces/bond.rst @@ -10,32 +10,35 @@ or port-channel. The behavior of the bonded interfaces depends upon the mode; generally speaking, modes provide either hot standby or load balancing services. Additionally, link integrity monitoring may be performed. +************* Configuration -############# +************* Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-common-with-dhcp.txt :var0: bond :var1: bond0 Member Interfaces ------------------ +================= .. cfgcmd:: set interfaces bonding <interface> member interface <member> Enslave `<member>` interface to bond `<interface>`. Bond options ------------- +============ -.. cfgcmd:: set interfaces bonding <interface> mode <mode> +.. cfgcmd:: set interfaces bonding <interface> mode <802.3ad | active-backup | + broadcast | round-robin | transmit-load-balance | adaptive-load-balance | + xor-hash> Specifies one of the bonding policies. The default is 802.3ad. Possible values are: - * **802.3ad** - IEEE 802.3ad Dynamic link aggregation. Creates aggregation + * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation groups that share the same speed and duplex settings. Utilizes all slaves in the active aggregator according to the 802.3ad specification. @@ -47,7 +50,7 @@ Bond options in regards to the packet mis-ordering requirements of section 43.2.4 of the 802.3ad standard. - * **active-backup** - Active-backup policy: Only one slave in the bond is + * ``active-backup`` - Active-backup policy: Only one slave in the bond is active. A different slave becomes active if, and only if, the active slave fails. The bond's MAC address is externally visible on only one port (network adapter) to avoid confusing the switch. @@ -62,24 +65,24 @@ Bond options This mode provides fault tolerance. The :cfgcmd:`primary` option, documented below, affects the behavior of this mode. - * **broadcast** - Broadcast policy: transmits everything on all slave + * ``broadcast`` - Broadcast policy: transmits everything on all slave interfaces. This mode provides fault tolerance. - * **round-robin** - Round-robin policy: Transmit packets in sequential + * ``round-robin`` - Round-robin policy: Transmit packets in sequential order from the first available slave through the last. This mode provides load balancing and fault tolerance. - * **transmit-load-balance** - Adaptive transmit load balancing: channel + * ``transmit-load-balance`` - Adaptive transmit load balancing: channel bonding that does not require any special switch support. Incoming traffic is received by the current slave. If the receiving slave fails, another slave takes over the MAC address of the failed receiving slave. - * **adaptive-load-balance** - Adaptive load balancing: includes + * ``adaptive-load-balance`` - Adaptive load balancing: includes transmit-load-balance plus receive load balancing for IPV4 traffic, and does not require any special switch support. The receive load balancing is achieved by ARP negotiation. The bonding driver intercepts the ARP @@ -111,7 +114,7 @@ Bond options than the switch's forwarding delay so that the ARP Replies sent to the peers will not be blocked by the switch. - * **xor-hash** - XOR policy: Transmit based on the selected transmit + * ``xor-hash`` - XOR policy: Transmit based on the selected transmit hash policy. The default policy is a simple [(source MAC address XOR'd with destination MAC address XOR packet type ID) modulo slave count]. Alternate transmit policies may be selected via the :cfgcmd:`hash-policy` @@ -253,8 +256,9 @@ Bond options The maximum number of targets that can be specified is 16. The default value is no IP addresses. +******* Example -------- +******* The following configuration on VyOS applies to all following 3rd party vendors. It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with @@ -275,7 +279,7 @@ a per VIF IPv4 address. set interfaces bonding bond0 member interface eth2 Cisco Catalyst -^^^^^^^^^^^^^^ +============== Assign member interfaces to PortChannel @@ -305,7 +309,7 @@ allowed VLAN interfaces, STP will happen here. Juniper EX Switch -^^^^^^^^^^^^^^^^^ +================= For a headstart you can use the below example on how to build a bond with two interfaces from VyOS to a Juniper EX Switch system. @@ -334,7 +338,7 @@ interfaces from VyOS to a Juniper EX Switch system. set interfaces xe-1/1/0 ether-options 802.3ad ae0 Aruba/HP -^^^^^^^^ +======== For a headstart you can use the below example on how to build a bond,port-channel with two interfaces from VyOS to a Aruba/HP 2510G switch. @@ -349,7 +353,7 @@ with two interfaces from VyOS to a Aruba/HP 2510G switch. vlan 100 tagged Trk1 Arista EOS -^^^^^^^^^^ +========== When utilizing VyOS in an environment with Arista gear you can use this blue print as an initial setup to get an LACP bond / port-channel operational between @@ -463,8 +467,9 @@ Lets assume the following topology: virtio network driver no LACP PDUs will be sent by VyOS thus the port-channel will never become active! +********* Operation -######### +********* .. opcmd:: show interfaces bonding diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst index 144e5f6d..ba6d70fb 100644 --- a/docs/interfaces/bridge.rst +++ b/docs/interfaces/bridge.rst @@ -14,18 +14,19 @@ standard. .. note:: Spanning Tree Protocol is not enabled by default in VyOS. :ref:`stp` can be easily enabled if needed. +************* Configuration -############# +************* Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-common-with-dhcp.txt :var0: bridge :var1: br0 Member Interfaces ------------------ +================= .. cfgcmd:: set interfaces bridge <interface> member interface <member> @@ -59,6 +60,24 @@ Member Interfaces deciding which link to use. Faster interfaces should have lower costs. +Bridge Options +============== + +.. cfgcmd:: set interfaces bridge <interface> aging <time> + + MAC address aging `<time`> in seconds (default: 300). + +.. cfgcmd:: set interfaces bridge <interface> max-age <time> + + Bridge maximum aging `<time>` in seconds (default: 20). + + If a another bridge in the spanning tree does not send out a hello + packet for a long period of time, it is assumed to be dead. + +.. cfgcmd:: set interfaces bridge <interface> igmp querier + + Enable IGMP querier + .. _stp: STP Parameter @@ -94,26 +113,9 @@ links providing fault tolerance if an active link fails. Designated Bridges. Hello packets are used to communicate information about the topology throughout the entire Bridged Local Area Network. -Additional Bridge Options -------------------------- - -.. cfgcmd:: set interfaces bridge <interface> aging <time> - - MAC address aging `<time`> in seconds (default: 300). - -.. cfgcmd:: set interfaces bridge <interface> max-age <time> - - Bridge maximum aging `<time>` in seconds (default: 20). - - If a another bridge in the spanning tree does not send out a hello - packet for a long period of time, it is assumed to be dead. - -.. cfgcmd:: set interfaces bridge <interface> igmp querier - - Enable IGMP querier - +******* Example -####### +******* Creating a bridge interface is very simple. In this example we will have: @@ -146,9 +148,9 @@ This results in the active configuration: } stp - -Operation -######### +******* +Example +******* .. opcmd:: show bridge diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst index e0557d1d..c36d0024 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/interfaces/dummy.rst @@ -18,12 +18,12 @@ you can have as many as you want. destination. A :ref:`dummy-interface` Interface should always be preferred over a :ref:`loopback-interface` interface. - +************* Configuration -############# +************* Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-address.txt :var0: dummy @@ -41,8 +41,9 @@ Common interface configuration :var0: dummy :var1: dum0 +********* Operation -========= +********* .. opcmd:: show interfaces dummy diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index 1d3aeda3..71a340b1 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -4,18 +4,22 @@ Ethernet ######## +This will be the most widely used interface on a router carrying traffic to the +real world. + +************* Configuration -############# +************* Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-common-with-dhcp.txt :var0: ethernet :var1: eth0 -Speed/Duplex ------------- +Ethernet options +================ .. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half> @@ -45,15 +49,9 @@ Speed/Duplex VyOS default will be `auto`. -VLAN (802.1q) configuration ---------------------------- - -.. cmdinclude:: ../_include/interface-vlan.txt - :var0: ethernet - :var1: eth0 - +********* Operation -========= +********* .. opcmd:: show interfaces ethernet diff --git a/docs/interfaces/geneve.rst b/docs/interfaces/geneve.rst index b59bb311..47068687 100644 --- a/docs/interfaces/geneve.rst +++ b/docs/interfaces/geneve.rst @@ -32,18 +32,19 @@ Geneve Header: | Variable Length Options | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +************* Configuration -============= +************* Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-common-without-dhcp.txt :var0: geneve :var1: gnv0 -GENEVE specific options ------------------------ +GENEVE options +============== .. cfgcmd:: set interfaces geneve gnv0 remote <address> diff --git a/docs/interfaces/l2tpv3.rst b/docs/interfaces/l2tpv3.rst index c456a58e..e9b00bef 100644 --- a/docs/interfaces/l2tpv3.rst +++ b/docs/interfaces/l2tpv3.rst @@ -6,22 +6,83 @@ L2TPv3 ###### -L2TPv3 is a pseudowire protocol, you can read more about on `Wikipedia L2TPv3`_ -or in :rfc:`3921` +Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that +can be used as an alternative protocol to :ref:`mpls` for encapsulation of +multiprotocol Layer 2 communications traffic over IP networks. Like L2TP, +L2TPv3 provides a pseudo-wire service, but scaled to fit carrier requirements. -L2TPv3 can transport any traffic including ethernet frames. L2TPv2 is limited -to PPP. +L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version +of the same concept, with much of the same benefit achieved at a fraction of the +effort, at the cost of losing some technical features considered less important +in the market. +In the case of L2TPv3, the features lost are teletraffic engineering features +considered important in MPLS. However, there is no reason these features could +not be re-engineered in or on top of L2TPv3 in later products. + +The protocol overhead of L2TPv3 is also significantly bigger than MPLS. + +L2TPv3 is described in :rfc:`3921`. + +************* Configuration -############# +************* Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-common-without-dhcp.txt :var0: l2tpv3 :var1: l2tpeth0 +L2TPv3 options +============== + +.. cfgcmd:: set interfaces l2tpv3 <interface> encapsulation <udp | ip> + + Set the encapsulation type of the tunnel. Valid values for encapsulation are: + udp, ip. + + This defaults to UDP + +.. cfgcmd:: set interfaces l2tpv3 <interface> local-ip <address> + + set the IP address of the local interface to be used for the tunnel. + + This address must be the address of a local interface. May be specified as an + IPv4 address or an IPv6 address. + +.. cfgcmd:: set interfaces l2tpv3 <interface> remote-ip <address> + + Set the IP address of the remote peer. May be specified as an IPv4 address or + an IPv6 address. + +.. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id> + + Set the session id, which is a 32-bit integer value. Uniquely identifies the + session being created. The value used must match the peer_session_id value + being used at the peer. + +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id> + + Set the peer session id, which is a 32-bit integer value assigned to the + session by the peer. The value used must match the session_id value being + used at the peer. + +.. cfgcmd:: set interfaces l2tpv3 <interface> tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. + +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. + +******* +Example +******* + Over IP ^^^^^^^ @@ -129,5 +190,3 @@ L2TPv3: set interfaces l2tpv3 l2tpeth0 session-id '110' set interfaces l2tpv3 l2tpeth0 source-port '5000' set interfaces l2tpv3 l2tpeth0 tunnel-id '10' - -.. _`Wikipedia L2TPv3`: https://en.wikipedia.org/wiki/L2TPv3 diff --git a/docs/interfaces/loopback.rst b/docs/interfaces/loopback.rst index ed241eb2..a6d659b5 100644 --- a/docs/interfaces/loopback.rst +++ b/docs/interfaces/loopback.rst @@ -19,11 +19,12 @@ services on your local machine. destination. A :ref:`dummy-interface` Interface should always be preferred over a :ref:`loopback-interface` interface. +************* Configuration -============= +************* Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-address.txt :var0: loopback @@ -33,8 +34,9 @@ Common interface configuration :var0: loopback :var1: lo +********* Operation -========= +********* .. opcmd:: show interfaces loopback diff --git a/docs/interfaces/macsec.rst b/docs/interfaces/macsec.rst index f841e17d..ebc8f151 100644 --- a/docs/interfaces/macsec.rst +++ b/docs/interfaces/macsec.rst @@ -13,18 +13,19 @@ including DHCP or ARP requests. It does not compete with other security solutions such as IPsec (layer 3) or TLS (layer 4), as all those solutions are used for their own specific use cases. +************* Configuration -############# +************* Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-common-with-dhcp.txt :var0: macsec :var1: macsec0 -MACsec specific options ------------------------ +MACsec options +============== .. cfgcmd:: set interfaces macsec <interface> security cipher [gcm-aes-128] @@ -45,7 +46,7 @@ MACsec specific options leaving this interfac will now be authenticated/encrypted. Key Management -^^^^^^^^^^^^^^ +-------------- :abbr:`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between individual peers. @@ -65,7 +66,7 @@ individual peers. distributing SAKs. Replay protection -^^^^^^^^^^^^^^^^^ +----------------- .. cfgcmd:: set interfaces macsec <interface> security replay-window <window> @@ -76,8 +77,9 @@ Replay protection - ``0``: No replay window, strict check - ``1-4294967295``: Number of packets that could be misordered +********* Operation -######### +********* .. opcmd:: run generate macsec mka-cak @@ -123,8 +125,9 @@ Operation cipher suite: GCM-AES-128, using ICV length 16 TXSC: 005056bfefaa0001 on SA 0 +******** Examples -######## +******** * Two routers connected both via eth1 through an untrusted switch * R1 has 192.0.2.1/24 & 2001:db8::1/64 diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index e85c16aa..7b2c319d 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -14,15 +14,16 @@ 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` @@ -35,7 +36,7 @@ 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 @@ -51,11 +52,12 @@ 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 -============= +************* Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-description.txt :var0: pppoe @@ -69,8 +71,8 @@ Common interface configuration :var0: pppoe :var1: pppoe0 -PPPoE specific configuration ----------------------------- +PPPoE options +============= .. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> @@ -179,8 +181,9 @@ IPv6 :var0: pppoe :var1: pppoe0 +********* Operation -========= +********* .. opcmd:: show interfaces pppoe <interface> @@ -211,7 +214,7 @@ Operation backlog 0b 0p requeues 0 Connect/Disconnect ------------------- +================== .. opcmd:: disconnect interface <interface> @@ -223,8 +226,9 @@ Connect/Disconnect Test connecting given connection-oriented interface. `<interface>` can be ``pppoe0`` as example. +******* Example -======= +******* Requirements: diff --git a/docs/interfaces/pseudo-ethernet.rst b/docs/interfaces/pseudo-ethernet.rst index 26d8a364..b373a617 100644 --- a/docs/interfaces/pseudo-ethernet.rst +++ b/docs/interfaces/pseudo-ethernet.rst @@ -38,18 +38,19 @@ Ethernet interfaces: - Network switches with security settings allowing only a single MAC address - xDSL modems that try to lear the MAC address of the NIC +************* Configuration -============= +************* Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-common-with-dhcp.txt :var0: pseudo-ethernet :var1: peth0 -Pseudo Ethernet/MACVLAN specific options ----------------------------------------- +Pseudo Ethernet/MACVLAN options +=============================== .. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> diff --git a/docs/interfaces/wirelessmodem.rst b/docs/interfaces/wirelessmodem.rst index 4590a3bb..f9dfa228 100644 --- a/docs/interfaces/wirelessmodem.rst +++ b/docs/interfaces/wirelessmodem.rst @@ -4,15 +4,16 @@ WirelessModem (WWAN) #################### -Configuration -############# - -The wirelessmodem interface provides access (through a wireless modem/wwan) to -wireless networks provided by various cellular providers. VyOS uses the +The wirelessmodem interface provides access (through a wireless modem/wwan) +to wireless networks provided by various cellular providers. VyOS uses the interfaces wirelessmodem subsystem for configuration. +************* +Configuration +************* + Common interface configuration ------------------------------- +============================== .. cmdinclude:: ../_include/interface-description.txt :var0: wirelessmodem @@ -26,8 +27,8 @@ Common interface configuration :var0: wirelessmodem :var1: wlm0 -WWAN specific options ---------------------- +WirelessModem (WWAN) options +============================ .. cfgcmd:: set interfaces wirelessmodem <interface> apn <apn> @@ -59,23 +60,9 @@ WWAN specific options connection is established at boot time and remains up. If the link fails for any reason, the link is brought back up immediately. -Example -======= - -The following example is based on a Sierra Wireless MC7710 miniPCIe card (only -the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card -is assembled into a :ref:`pc-engines-apu4`. - -.. code-block:: none - - set interfaces wirelessmodem wlm0 apn 'internet.telekom' - set interfaces wirelessmodem wlm0 backup distance '100' - set interfaces wirelessmodem wlm0 device 'ttyUSB2' - set interfaces wirelessmodem wlm0 disable - set interfaces wirelessmodem wlm0 no-peer-dns - +********* Operation -========= +********* .. opcmd:: show interfaces wirelessmodem <interface> @@ -109,8 +96,26 @@ Operation Displays log information for a WWAN interface. + +******* +Example +******* + +The following example is based on a Sierra Wireless MC7710 miniPCIe card (only +the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card +is assembled into a :ref:`pc-engines-apu4`. + +.. code-block:: none + + set interfaces wirelessmodem wlm0 apn 'internet.telekom' + set interfaces wirelessmodem wlm0 backup distance '100' + set interfaces wirelessmodem wlm0 device 'ttyUSB2' + set interfaces wirelessmodem wlm0 disable + set interfaces wirelessmodem wlm0 no-peer-dns + +***************** Supported Modules -################# +***************** The following hardware modules have been tested successfully in an :ref:`pc-engines-apu4` board: @@ -120,4 +125,4 @@ The following hardware modules have been tested successfully in an * Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) * Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) * Huawei ME909u-521 miniPCIe card (LTE) - +* Huawei ME909s-120 miniPCIe card (LTE) diff --git a/docs/routing/mpls.rst b/docs/routing/mpls.rst index 86221104..82e99a17 100644 --- a/docs/routing/mpls.rst +++ b/docs/routing/mpls.rst @@ -1,8 +1,8 @@ .. _mpls: -#### -MPLS -#### +#################################### +MPLS (Multiprotocol Label Switching) +#################################### :abbr:`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm which differs from regular IP forwarding. Instead of IP addresses being used to |