vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

interfaces: use common toc and chapter style

Browse Source
This commit is contained in:
Christian Poessinger 2020-11-13 14:46:04 +01:00
parent 85206b1c28
commit d20c299b9d
13 changed files with 210 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/interfaces/advanced-index.rst
View File

@ -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

41
docs/interfaces/bond.rst
View File

@ -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

52
docs/interfaces/bridge.rst
View File

@ -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

9
docs/interfaces/dummy.rst
View File

@ -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

22
docs/interfaces/ethernet.rst
View File

@ -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

9
docs/interfaces/geneve.rst
View File

@ -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>

75
docs/interfaces/l2tpv3.rst
View File

@ -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

8
docs/interfaces/loopback.rst
View File

@ -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

19
docs/interfaces/macsec.rst
View File

@ -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

24
docs/interfaces/pppoe.rst
View File

@ -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:

9
docs/interfaces/pseudo-ethernet.rst
View File

@ -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>

57
docs/interfaces/wirelessmodem.rst
View File

@ -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)

6
docs/routing/mpls.rst
View File

@ -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