diff options
Diffstat (limited to 'docs/interfaces')
| -rw-r--r-- | docs/interfaces/addresses.rst | 175 | ||||
| -rw-r--r-- | docs/interfaces/advanced-index.rst | 19 | ||||
| -rw-r--r-- | docs/interfaces/basic-index.rst | 12 | ||||
| -rw-r--r-- | docs/interfaces/bond.rst | 368 | ||||
| -rw-r--r-- | docs/interfaces/bridge.rst | 300 | ||||
| -rw-r--r-- | docs/interfaces/common-ipv6-addr-autoconf.txt | 12 | ||||
| -rw-r--r-- | docs/interfaces/dummy.rst | 107 | ||||
| -rw-r--r-- | docs/interfaces/ethernet.rst | 292 | ||||
| -rw-r--r-- | docs/interfaces/geneve.rst | 3 | ||||
| -rw-r--r-- | docs/interfaces/index.rst | 62 | ||||
| -rw-r--r-- | docs/interfaces/loopback.rst | 75 | ||||
| -rw-r--r-- | docs/interfaces/pppoe.rst | 40 | ||||
| -rw-r--r-- | docs/interfaces/vxlan.rst | 209 |
13 files changed, 1108 insertions, 566 deletions
diff --git a/docs/interfaces/addresses.rst b/docs/interfaces/addresses.rst deleted file mode 100644 index 709490c8..00000000 --- a/docs/interfaces/addresses.rst +++ /dev/null @@ -1,175 +0,0 @@ -.. _interfaces-addresses: - -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`` - -.. cfgcmd:: set interfaces ethernet eth0 description 'OUTSIDE' - - An interface description is assigned using the following command: - -IPv4 -^^^^ - -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. - -The command is ``set interfaces $type $name address $address``. Examples: - -.. code-block:: none - - set interfaces ethernet eth0 address 192.0.2.1/24 - set interfaces tunnel tun0 address 10.0.0.1/30 - set interfaces bridge br0 address 203.0.113.45/26 - set interfaces ethernet eth0 vif 30 address 198.51.100.254/24 - -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). - -The command is ``set interfaces $type $name address dhcp``. Examples: - -.. code-block:: none - - set interfaces ethernet eth0 vif 90 address dhcp - set interfaces bridge br0 address dhcp - -IPv6 -^^^^ - -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:`tunnel-interface`. - -The command is ``set interfaces $type $name address $address``. Examples: - -.. code-block:: none - - set interfaces ethernet eth0 address 2001:db8:100::ffff/64 - set interfaces tunnel tun0 address 2001:db8::1/64 - set interfaces bridge br0 address 2001:db8:200::1/64 - set interfaces ethernet eth0 vif 30 address 2001:db8:3::ffff/64 - -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). - -The command is `set interfaces $type $name address dhcpv6`. Examples: - -.. code-block:: none - - set interfaces bonding bond1 address dhcpv6 - set interfaces bridge br0 vif 56 address dhcpv6 - -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). - -The command is ``set interfaces $type $name ipv6 address autoconf``. Examples: - -.. code-block:: none - - set interfaces ethernet eth0 vif 90 ipv6 address autoconf - set interfaces bridge br0 ipv6 address autoconf - -.. note:: This method automatically disables IPv6 traffic forwarding on the - interface in question. - -EUI-64 -****** - -EUI-64 (64-Bit Extended Unique Identifier) as specified in :rfc:`4291`. IPv6 -addresses in /64 networks can be automatically generated from the prefix and -MAC address, if you specify the prefix. - -The command is `set interfaces $type $name ipv6 address eui64 $prefix`. -Examples: - -.. code-block:: none - - set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 - set interfaces pseudo-ethernet peth0 ipv6 address eui64 2001:db8:aa::/64 - - -Router Advertisements -********************* - -Router advertisements are described in :rfc:`4861#section-4.6.2`. They are part -of what is known as SLAAC (Stateless Address Autoconfiguration). - -To enable or disable, use: - -.. code-block:: none - - set interfaces <interface> ipv6 router-advert send-advert <true|false> - - -To set the options described in "Router Advertisement Message Format": - -.. code-block:: none - - vyos@vyos# set interfaces <interface> 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 -~~~~~~~~~~~~~~~~~~ - -Prefix information is described in :rfc:`4861#section-4.6.2`. - -.. code-block:: none - - vyos@vyos# set interfaces <interface> ipv6 router-advert prefix <h:h:h:h:h:h:h:h/x> - Possible completions: - autonomous-flag Whether prefix can be used for address auto-configuration - on-link-flag Flag that prefix can be used for on-link determination - 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To receive and accept RAs on an interface, you need to enable it with the -following configuration command - -.. code-block:: none - - vyos@vyos# set system sysctl custom net.ipv6.conf.<interface>.accept_ra value 2 - diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst new file mode 100644 index 00000000..00c1c73e --- /dev/null +++ b/docs/interfaces/advanced-index.rst @@ -0,0 +1,19 @@ +.. _network-interfaces: + +################## +Network Interfaces +################## + +.. toctree:: + :maxdepth: 1 + + dummy + bridge + bond + l2tpv3 + wireless + tunnel + vlan + qinq + vxlan + geneve diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst new file mode 100644 index 00000000..c652c7bb --- /dev/null +++ b/docs/interfaces/basic-index.rst @@ -0,0 +1,12 @@ +.. _basic_network-interfaces: + +################ +Basic Interfaces +################ + +.. toctree:: + :maxdepth: 1 + + ethernet + loopback + pppoe diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst index 880c7580..c0fc0ca6 100644 --- a/docs/interfaces/bond.rst +++ b/docs/interfaces/bond.rst @@ -1,72 +1,362 @@ .. _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. +The bonding interface provides a method for aggregating multiple network +interfaces into a single logical "bonded" interface, or LAG, or ether-channel, +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. -Create interface bondX, where X is just a number: +Configuration +############# -.. code-block:: none +Address +------- - set interfaces bonding bond0 description 'my-sw1 int 23 and 24' +.. cfgcmd:: set interfaces bonding <interface> address <address | dhcp | dhcpv6> -You are able to choose a hash policy: + Configure interface `<interface>` with one or more interface addresses. -.. code-block:: none + * **address** can be specified multiple times as IPv4 and/or IPv6 address, + e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server on this + segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on + this segment. + + Example: + + .. code-block:: none + + set interfaces bonding bond0 address 192.0.2.1/24 + set interfaces bonding bond0 address 192.0.2.2/24 + set interfaces bonding bond0 address 2001:db8::ffff/64 + set interfaces bonding bond0 address 2001:db8:100::ffff/64 + + +.. cfgcmd:: set interfaces bonding <interface> ipv6 address autoconf + + .. include:: common-ipv6-addr-autoconf.txt + +.. cfgcmd:: set interfaces bonding <interface> ipv6 address eui64 <prefix> + + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. + + .. code-block:: none + + set interfaces bonding bond0 ipv6 address eui64 2001:db8:beef::/64 + + +Link Administration +------------------- + +.. cfgcmd:: set interfaces bonding <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + + +.. cfgcmd:: set interfaces bonding <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + +.. cfgcmd:: set interfaces bonding <interface> mac <mac-address> + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + `<interface>`. + +.. cfgcmd:: set interfaces bonding <interface> mode <mode> + + Specifies one of the bonding policies. The default is 802.3ad. Possible + values are: + + * **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. + + Slave selection for outgoing traffic is done according to the transmit + hash policy, which may be changed from the default simple XOR policy via + the :cfgcmd:`hash-policy` option, documented below. + + .. note:: Not all transmit policies may be 802.3ad compliant, particularly + 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. 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. + + When a failover occurs in active-backup mode, bonding will issue one or + more gratuitous ARPs on the newly active slave. One gratuitous ARP is + issued for the bonding master interface and each VLAN interfaces + configured above it, provided that the interface has at least one IP + address configured. Gratuitous ARPs issued for VLAN interfaces are tagged + with the appropriate VLAN id. + + 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 + interfaces. + + This mode provides fault tolerance. + + * **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 + 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 + 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 + Replies sent by the local system on their way out and overwrites the + source hardware address with the unique hardware address of one of the + slaves in the bond such that different peers use different hardware + addresses for the server. + + Receive traffic from connections created by the server is also balanced. + When the local system sends an ARP Request the bonding driver copies and + saves the peer's IP information from the ARP packet. When the ARP Reply + arrives from the peer, its hardware address is retrieved and the bonding + driver initiates an ARP reply to this peer assigning it to one of the + slaves in the bond. A problematic outcome of using ARP negotiation for + balancing is that each time that an ARP request is broadcast it uses the + hardware address of the bond. Hence, peers learn the hardware address + of the bond and the balancing of receive traffic collapses to the current + slave. This is handled by sending updates (ARP Replies) to all the peers + with their individually assigned hardware address such that the traffic + is redistributed. Receive traffic is also redistributed when a new slave + is added to the bond and when an inactive slave is re-activated. The + receive load is distributed sequentially (round robin) among the group + of highest speed slaves in the bond. + + When a link is reconnected or a new slave joins the bond the receive + traffic is redistributed among all active slaves in the bond by initiating + ARP Replies with the selected MAC address to each of the clients. The + updelay parameter (detailed below) must be set to a value equal or greater + 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 + 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` + option, described below. + + This mode provides load balancing and fault tolerance. + +.. cfgcmd:: set interfaces bonding <interface> hash-policy <policy> + + * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field + to generate the hash. The formula is + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + slave number = hash modulo slave count - 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 + This algorithm will place all traffic to a particular network peer on + the same slave. -For example: + This algorithm is 802.3ad compliant. + + * **layer2+3** - This policy uses a combination of layer2 and layer3 + protocol information to generate the hash. Uses XOR of hardware MAC + addresses and IP addresses to generate the hash. The formula is: + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + This algorithm will place all traffic to a particular network peer on the + same slave. For non-IP traffic, the formula is the same as for the layer2 + transmit hash policy. + + This policy is intended to provide a more balanced distribution of traffic + than layer2 alone, especially in environments where a layer3 gateway + device is required to reach most destinations. + + This algorithm is 802.3ad compliant. + + * **layer3+4** - This policy uses upper layer protocol information, when + available, to generate the hash. This allows for traffic to a particular + network peer to span multiple slaves, although a single connection will + not span multiple slaves. + + The formula for unfragmented TCP and UDP packets is + + .. code-block:: none + + hash = source port, destination port (as in the header) + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol + traffic, the source and destination port information is omitted. For + non-IP traffic, the formula is the same as for the layer2 transmit hash + policy. + + This algorithm is not fully 802.3ad compliant. A single TCP or UDP + conversation containing both fragmented and unfragmented packets will see + packets striped across two interfaces. This may result in out of order + delivery. Most traffic types will not meet this criteria, as TCP rarely + fragments traffic, and most UDP traffic is not involved in extended + conversations. Other implementations of 802.3ad may or may not tolerate + this noncompliance. + +.. cfgcmd:: set interfaces bonding <interface> primary <interface> + + An `<interface>` specifying which slave is the primary device. The specified + device will always be the active slave while it is available. Only when the + primary is off-line will alternate devices be used. This is useful when one + slave is preferred over another, e.g., when one slave has higher throughput + than another. + + The primary option is only valid for active-backup, transmit-load-balance, + and adaptive-load-balance mode. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time> + + Specifies the ARP link monitoring `<time>` in seconds. + + The ARP monitor works by periodically checking the slave devices to determine + whether they have sent or received traffic recently (the precise criteria + depends upon the bonding mode, and the state of the slave). Regular traffic + is generated via ARP probes issued for the addresses specified by the + :cfgcmd:`arp-monitor target` option. + + If ARP monitoring is used in an etherchannel compatible mode (modes + round-robin and xor-hash), the switch should be configured in a mode that + evenly distributes packets across all links. If the switch is configured to + distribute the packets in an XOR fashion, all replies from the ARP targets + will be received on the same link which could cause the other team members + to fail. + + A value of 0 disables ARP monitoring. The default value is 0. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address> + + Specifies the IP addresses to use as ARP monitoring peers when + :cfgcmd:`arp-monitor interval` option is > 0. These are the targets of the + ARP request sent to determine the health of the link to the targets. + + Multiple target IP addresses can be specified. At least one IP address must + be given for ARP monitoring to function. + + The maximum number of targets that can be specified is 16. The default value + is no IP addresses. + +Member Interfaces +----------------- + +.. cfgcmd:: set interfaces bonding <interface> member interface <member> + + Enslave `<member>` interface to bond `<interface>`. + +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 +a per VIF IPv4 address. .. code-block:: none + # Create bonding interface bond0 with 802.3ad LACP set interfaces bonding bond0 hash-policy 'layer2' + set interfaces bonding bond0 mode '802.3ad' -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): + # Add the required vlans and IPv4 addresses on them + set interfaces bonding bond0 vif 10 address 192.168.0.1/24 + set interfaces bonding bond0 vif 100 address 10.10.10.1/24 -.. code-block:: none + # Add the member interfaces to the bonding interface + set interfaces bonding bond0 member interface eth1 + set interfaces bonding bond0 member interface eth2 + +Cisco +^^^^^ - set interfaces bonding bond0 mode '802.3ad' +An example configuration for a Cisco PortChannel to VyOS would be nice -or some other modes: +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. .. code-block:: none - 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: + # Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s + set interfaces ae0 aggregated-ether-options link-speed 10g + set interfaces ae0 aggregated-ether-options lacp active + + # Create layer 2 on the aggregated ethernet device with trunking for our vlans + set interfaces ae0 unit 0 family ethernet-switching port-mode trunk + + # Add the required vlans to the device + set interfaces ae0 unit 0 family ethernet-switching vlan members 10 + set interfaces ae0 unit 0 family ethernet-switching vlan members 100 + + # Add the two interfaces to the aggregated ethernet device, in this setup both + # ports are on the same switch (switch 0, module 1, port 0 and 1) + set interfaces xe-0/1/0 ether-options 802.3ad ae0 + set interfaces xe-0/1/1 ether-options 802.3ad ae0 + + # But this can also be done with multiple switches in a stack, a virtual + # chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) + set interfaces xe-0/1/0 ether-options 802.3ad ae0 + 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. .. code-block:: none - set interfaces bonding bond0 member interface eth0 - set interfaces bonding bond0 member interface eth1 + # Create trunk with 2 member interfaces (interface 1 and 2) and LACP + trunk 1-2 Trk1 LACP -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. + # Add the required vlans to the trunk + vlan 10 tagged Trk1 + vlan 100 tagged Trk1 -You may check the result: +Operation +######### .. code-block:: none - vyos@vyos# run sh interfaces bonding + vyos@vyos:~$ show interfaces bonding Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down Interface IP Address S/L Description --------- ---------- --- ----------- diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst index a7bbbca6..d51f4ec2 100644 --- a/docs/interfaces/bridge.rst +++ b/docs/interfaces/bridge.rst @@ -1,112 +1,254 @@ .. _bridge-interface: +###### Bridge ------- +###### -Interfaces in VyOS can be bridged together to provide software switching of -Layer-2 traffic. +A Bridge is a way to connect two Ethernet segments together in a protocol +independent way. Packets are forwarded based on Ethernet address, rather than +IP address (like a router). Since forwarding is done at Layer 2, all protocols +can go transparently through a bridge. The Linux bridge code implements a +subset of the ANSI/IEEE 802.1d standard. -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. +Configuration +############# -.. code-block:: none +Address +------- - set interfaces bridge 'br100' - set interfaces bridge br100 member interface eth1 - set interfaces bridge br100 member interface eth2 +.. cfgcmd:: set interfaces bridge <interface> address <address | dhcp | dhcpv6> -Each bridge member can be assiged a port cost and priority using the following -commands: + Configure interface `<interface>` with one or more interface addresses. -.. code-block:: none + * **address** can be specified multiple times as IPv4 and/or IPv6 address, + e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server on this + segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on + this segment. - set interfaces bridge br100 member interface eth1 cost 10 - set interfaces bridge br100 member interface eth1 priority 1024 + Example: -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:: none -.. code-block:: none + set interfaces bridge br0 address 192.0.2.1/24 + set interfaces bridge br0 address 192.0.2.2/24 + set interfaces bridge br0 address 2001:db8::ffff/64 + set interfaces bridge br0 address 2001:db8:100::ffff/64 - set interfaces bridge br100 address '192.168.100.1/24' - set interfaces bridge br100 address '2001:db8:100::1/64' -Example Result: +.. cfgcmd:: set interfaces bridge <interface> ipv6 address autoconf -.. code-block:: none + .. include:: common-ipv6-addr-autoconf.txt - bridge br100 { - address 192.168.100.1/24 - address 2001:db8:100::1/64 - member { - interface eth1 { - cost 10 - priority 1024 - } - interface eth2 { - } - } +.. cfgcmd:: set interfaces bridge <interface> ipv6 address eui64 <prefix> - } - [...] + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. -In addition to normal IP interface configuration, bridge interfaces support -Spanning-Tree Protocol. STP is disabled by default. + .. code-block:: none -.. note:: Please use caution when introducing spanning-tree protocol on a - network as it may result in topology changes. + set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 -To enable spanning-tree use the `set interfaces bridge <name> stp` command: -.. code-block:: none +.. cfgcmd:: set interfaces bridge <interface> aging <time> - set interfaces bridge br100 stp + MAC address aging `<time`> in seconds (default: 300). -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: +.. cfgcmd:: set interfaces bridge <interface> max-age <time> -.. code-block:: none + 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. + + +Link Administration +------------------- + +.. cfgcmd:: set interfaces bridge <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + + +.. cfgcmd:: set interfaces bridge <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + + +.. cfgcmd:: set interfaces bridge <interface> disable-flow-control + + Disable Ethernet flow control (pause frames). + + +.. cfgcmd:: set interfaces bridge <interface> mac <mac-address> + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + `<interface>`. + + +.. cfgcmd:: set interfaces bridge <interface> igmp querier + + Enable IGMP querier + + +Member Interfaces +----------------- + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + + Assign `<member>` interface to bridge `<interface>`. A completion helper + will help you with all allowed interfaces which can be bridged. This includes + :ref:`ethernet-interface`, :ref:`bond-interface`, :ref:`l2tpv3-interface`, + :ref:`openvpn`, :ref:`vxlan-interface`, :ref:`wireless-interface`, + :ref:`tunnel-interface` and :ref:`geneve-interface`. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> priority <priority> + + Configure individual bridge port `<priority>`. + + Each bridge has a relative priority and cost. Each interface is associated + with a port (number) in the STP code. Each has a priority and a cost, that + is used to decide which is the shortest path to forward a packet. The lowest + cost path is always used unless the other path is down. If you have multiple + bridges and interfaces then you may need to adjust the priorities to achieve + optimium performance. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> cost <cost> - vyos@vyos:~$ show bridge - bridge name bridge id STP enabled interfaces - br100 0000.000c29443b19 yes eth1.100 + Path `<cost>` value for Spanning Tree Protocol. Each interface in a bridge + could have a different speed and this value is used when deciding which + link to use. Faster interfaces should have lower costs. -If spanning-tree is enabled, the `show bridge <name> spanning-tree` command -can be used to show STP configuration: + +STP Parameter +------------- + +:abbr:`STP (Spanning Tree Protocol)` is a network protocol that builds a +loop-free logical topology for Ethernet networks. The basic function of STP is +to prevent bridge loops and the broadcast radiation that results from them. +Spanning tree also allows a network design to include backup links providing +fault tolerance if an active link fails. + +.. cfgcmd:: set interfaces bridge <interface> stp + + Enable spanning tree protocol. STP is disabled by default. + + +.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay> + + Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15). + + Forwarding delay time is the time spent in each of the Listening and + Learning states before the Forwarding state is entered. This delay is so + that when a new bridge comes onto a busy network it looks at some traffic + before participating. + + +.. cfgcmd:: set interfaces bridge <interface> hello-time <interval> + + Spanning Tree Protocol hello advertisement `<interval>` in seconds + (default: 2). + + Periodically, a hello packet is sent out by the Root Bridge and the + Designated Bridges. Hello packets are used to communicate information about + the topology throughout the entire Bridged Local Area Network. + + +Exammple +-------- + +Creating a bridge interface is very simple. In this example we will have: + +* A bridge named `br100` +* Member interfaces `eth1` and VLAN 10 on interface `eth2` +* Enable STP +* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 .. code-block:: none - 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 <name> macs` command: + set interfaces bridge br100 address 192.0.2.1/24 + set interfaces bridge br100 address 2001:db8::ffff/64 + set interfaces bridge br100 member interface eth1 + set interfaces bridge br100 member interface eth2.10 + set interfaces bridge br100 stp + +This results in the active configuration: .. code-block:: none - vyos@vyos:~$ show bridge br100 macs - port no mac addr is local? ageing timer - 1 00:53:29:44:3b:19 yes 0.00 + vyos@vyos# show interfaces bridge br100 + address 192.0.2.1/24 + address 2001:db8::ffff/64 + member { + interface eth1 { + } + interface eth2.10 { + } + } + stp + + +Operation +========= + +.. opcmd:: show bridge + + The `show bridge` operational command can be used to display configured + bridges: + + .. code-block:: none + + vyos@vyos:~$ show bridge + bridge name bridge id STP enabled interfaces + br100 8000.0050569d11df yes eth1 + eth2.10 + +.. opcmd:: show bridge <name> spanning-tree + + Show bridge `<name>` STP configuration. + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 spanning-tree + br100 + bridge id 8000.0050569d11df + designated root 8000.0050569d11df + 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 14.00 bridge forward delay 14.00 + ageing time 300.00 + hello timer 0.06 tcn timer 0.00 + topology change timer 0.00 gc timer 242.02 + flags + + eth1 (1) + port id 8001 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8001 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + flags + + eth2.10 (2) + port id 8002 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8002 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + +.. opcmd: show bridge <name> macs + + Show bridge Media Access Control (MAC) address table + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 macs + port no mac addr is local? ageing timer + 1 00:53:29:44:3b:19 yes 0.00 diff --git a/docs/interfaces/common-ipv6-addr-autoconf.txt b/docs/interfaces/common-ipv6-addr-autoconf.txt new file mode 100644 index 00000000..838b299f --- /dev/null +++ b/docs/interfaces/common-ipv6-addr-autoconf.txt @@ -0,0 +1,12 @@ +:abbr:`SLAAC (Stateless Address Autoconfiguration)`
+:rfc:`4862`. IPv6 hosts can configure themselves automatically when connected
+to an IPv6 network using the Neighbor Discovery Protocol via :abbr:`ICMPv6
+(Internet Control Message Protocol version 6)` router discovery messages.
+When first connected to a network, a host sends a link-local router
+solicitation multicast request for its configuration parameters; routers
+respond to such a request with a router advertisement packet that contains
+Internet Layer configuration parameters.
+
+.. note:: This method automatically disables IPv6 traffic forwarding on the
+ interface in question.
+
diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst index 9dbb9668..4627d1dc 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/interfaces/dummy.rst @@ -1,25 +1,90 @@ .. _dummy-interface: +##### Dummy ------ - -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:: none - - 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 +##### + +The dummy interface is really a little exotic, but rather useful nevertheless. +Dummy interfaces are much like the :ref:`loopback-interface` interface, except +you can have as many as you want. + +.. note:: Dummy interfaces can be used as interfaces that always stay up (in + the same fashion to loopbacks in Cisco IOS), or for testing purposes. + +.. hint:: A Dummy interface is always up, thus it could be used for + management traffic or as source/destination for and :abbr:`IGP (Interior + Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependant + on physical link states and multiple routes can be choosen to the + destination. A :ref:`dummy-interface` Interface should always be preferred + over a :ref:`loopback-interface` interface. + + +Configuration +############# + +Address +------- + +.. cfgcmd:: set interfaces dummy <interface> address <address | dhcp | dhcpv6> + + Configure dummy interface `<interface>` with one or more interface + addresses. Address can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + + Example: + + .. code-block:: none + + set interfaces dummy dum10 address 192.0.2.1/24 + set interfaces dummy dum10 address 192.0.2.2/24 + set interfaces dummy dum10 address 2001:db8::ffff/64 + set interfaces dummy dum10 address 2001:db8:100::ffff/64 + +Link Administration +------------------- + +.. cfgcmd:: set interfaces dummy <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + +.. cfgcmd:: set interfaces dummy <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + state. + +Operation +========= + +.. opcmd:: show interfaces dummy + + Show brief interface information.information + + .. code-block:: none + + vyos@vyos:~$ show interfaces dummy + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + dum0 172.18.254.201/32 u/u + +.. opcmd:: show interfaces dummy <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 + link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff + inet 172.18.254.201/32 scope global dum0 + valid_lft forever preferred_lft forever + inet6 fe80::247c:8eff:febc:fcf5/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 + diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index a8cee8c2..1f691269 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -1,72 +1,226 @@ .. _ethernet-interface: +######## Ethernet --------- - -Ethernet interfaces allow for the configuration of speed, duplex, and hw-id -(MAC address). Below is an example configuration: - -.. code-block:: none - - set interfaces ethernet eth1 address '192.168.0.1/24' - set interfaces ethernet eth1 address '2001:db8:1::ffff/64' - set interfaces ethernet eth1 description 'INSIDE' - set interfaces ethernet eth1 duplex 'auto' - set interfaces ethernet eth1 speed 'auto' - -Resulting in: - -.. code-block:: none - - ethernet eth1 { - address 192.168.0.1/24 - address 2001:db8:1::ffff/64 - description INSIDE - duplex auto - hw-id 00:53:29:44:3b:19 - smp_affinity auto - speed auto - } - -In addition, Ethernet interfaces provide the extended operational commands: - -* ``show interfaces ethernet <name> physical`` -* ``show interfaces ethernet <name> statistics`` - -Statistics available are driver dependent. - -.. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 physical - Settings for eth0: - Supported ports: [ TP ] - Supported link modes: 10baseT/Half 10baseT/Full - 100baseT/Half 100baseT/Full - 1000baseT/Full - Supports auto-negotiation: Yes - Advertised link modes: 10baseT/Half 10baseT/Full - 100baseT/Half 100baseT/Full - 1000baseT/Full - Advertised pause frame use: No - Advertised auto-negotiation: Yes - Speed: 1000Mb/s - Duplex: Full - Port: Twisted Pair - PHYAD: 0 - Transceiver: internal - Auto-negotiation: on - MDI-X: Unknown - Supports Wake-on: d - Wake-on: d - Current message level: 0x00000007 (7) - Link detected: yes - driver: e1000 - version: 7.3.21-k8-NAPI - firmware-version: - bus-info: 0000:02:01.0 - - vyos@vyos:~$ show interfaces ethernet eth0 statistics - NIC statistics: - rx_packets: 3530 - tx_packets: 2179 - [...] +######## + +Configuration +############# + +Address +------- + +.. cfgcmd:: set interfaces ethernet <interface> address <address | dhcp | dhcpv6> + + Configure interface `<interface>` with one or more interface addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 address, + e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server on this + segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on + this segment. + + Example: + + .. code-block:: none + + set interfaces ethernet eth0 address 192.0.2.1/24 + set interfaces ethernet eth0 address 192.0.2.2/24 + set interfaces ethernet eth0 address 2001:db8::ffff/64 + set interfaces ethernet eth0 address 2001:db8:100::ffff/64 + +.. cfgcmd:: set interfaces ethernet <interface> ipv6 address autoconf + + .. include:: common-ipv6-addr-autoconf.txt + +.. cfgcmd:: set interfaces ethernet <interface> ipv6 address eui64 <prefix> + + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. + + .. code-block:: none + + set interfaces ethernet eth0 ipv6 address eui64 2001:db8:beef::/64 + +Speed/Duplex +------------ + +.. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half> + + Configure physical interface duplex setting. + + * auto - interface duplex setting is auto-negotiated + * full - always use full-duplex + * half - always use half-duplex + + VyOS default will be `auto`. + +.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000> + + Configure physical interface speed setting. + + * auto - interface speed is auto-negotiated + * 10 - 10 MBit/s + * 100 - 100 MBit/s + * 1000 - 1 GBit/s + * 2500 - 2.5 GBit/s + * 5000 - 5 GBit/s + * 10000 - 10 GBit/s + * 25000 - 25 GBit/s + * 40000 - 40 GBit/s + * 50000 - 50 GBit/s + * 100000 - 100 GBit/s + + VyOS default will be `auto`. + +Link Administration +------------------- + +.. cfgcmd:: set interfaces ethernet <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + +.. cfgcmd:: set interfaces ethernet <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + +.. cfgcmd:: set interfaces ethernet <interface> disable-flow-control + + Disable Ethernet flow control (pause frames). + + +.. cfgcmd:: set interfaces ethernet <interface> mac <mac-address> + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + `<interface>`. + +.. cfgcmd:: set interfaces ethernet <interface> mtu <mtu> + + Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It + is the size (in bytes) of the largest ethernet frame sent on this link. + +Router Advertisements +--------------------- + +Router advertisements are described in :rfc:`4861#section-4.6.2`. They are part +of what is known as :abbr:`SLAAC (Stateless Address Autoconfiguration)`. + +.. cfgcmd:: set interfaces ethernet <interface> ipv6 router-advert send-advert <true | false> + + Enable or disable router advertisements in this `<interface>`. + +.. cfgcmd:: set interfaces ethernet <interface> ipv6 router-advert prefix <prefix> + + Prefix information is described in :rfc:`4861#section-4.6.2`. + +Operation +========= + +.. opcmd:: show interfaces ethernet + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 172.18.201.10/24 u/u LAN + eth1 172.18.202.11/24 u/u WAN + eth2 - u/D + +.. opcmd:: show interfaces ethernet <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 + +.. opcmd:: show interfaces ethernet <interface> physical + + Show information about physical `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical + Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes + driver: vmxnet3 + version: 1.4.16.0-k-NAPI + firmware-version: + expansion-rom-version: + bus-info: 0000:0b:00.0 + supports-statistics: yes + supports-test: no + supports-eeprom-access: no + supports-register-dump: yes + supports-priv-flags: no + +.. opcmd:: show interfaces ethernet <interface> transceiver + + Show transceiver information from plugin modules, e.g SFP+, QSFP + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx + diff --git a/docs/interfaces/geneve.rst b/docs/interfaces/geneve.rst index dc762738..b0bfde06 100644 --- a/docs/interfaces/geneve.rst +++ b/docs/interfaces/geneve.rst @@ -32,6 +32,9 @@ Geneve Header: | Variable Length Options | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +Configuration +============= + .. cfgcmd:: set interfaces geneve gnv0 address '192.0.2.2/24' Create GENEVE tunnel listening on local address `192.0.2.2/24`. diff --git a/docs/interfaces/index.rst b/docs/interfaces/index.rst deleted file mode 100644 index 0513adf1..00000000 --- a/docs/interfaces/index.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _network-interfaces: - -################## -Network Interfaces -################## - -Configured interfaces on a VyOS system can be displayed using the -``show interfaces`` command. - -.. 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 - lo 127.0.0.1/8 u/u - ::1/128 - -A specific interface can be shown using the ``show interfaces <type> <name>`` -command. - -.. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 - eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 - link/ether 00:53:29:44:3b:0f brd ff:ff:ff:ff:ff:ff - inet 172.16.51.129/24 brd 172.16.51.255 scope global eth0 - inet6 fe80::20c:29ff:fe44:3b0f/64 scope link - valid_lft forever preferred_lft forever - Description: OUTSIDE - - RX: bytes packets errors dropped overrun mcast - 274397 3064 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 257276 1890 0 0 0 0 - -Different network interfaces provide type-specific configuration. Ethernet -interfaces, for example, allow the configuration of speed and duplex. - -Many services, such as network routing, firewall, and traffic policy also -maintain interface-specific configuration. These will be covered in their -respective sections. - - -.. toctree:: - :maxdepth: 2 - - addresses - dummy - ethernet - l2tpv3 - pppoe - wireless - bridge - bond - tunnel - vlan - qinq - vxlan - geneve diff --git a/docs/interfaces/loopback.rst b/docs/interfaces/loopback.rst new file mode 100644 index 00000000..f7519631 --- /dev/null +++ b/docs/interfaces/loopback.rst @@ -0,0 +1,75 @@ +.. _loopback-interface: + +######## +Loopback +######## + +The loopback networking interface is a virtual network device implemented +entirely in software. All traffic sent to it "loops back" and just targets +services on your local machine. + +.. note:: There can only be one loopback ``lo`` interface on the system. If + you need multiple interfaces, please use the :ref:`dummy-interface` + interface type. + +.. hint:: A lookback interface is always up, thus it could be used for + management traffic or as source/destination for and :abbr:`IGP (Interior + Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependant + on physical link states and multiple routes can be choosen to the + destination. A :ref:`dummy-interface` Interface should always be preferred + over a :ref:`loopback-interface` interface. + +Configuration +============= + +Address +------- + +.. cfgcmd:: set interfaces loopback lo address <address> + + Configure Loopback interface `lo` with one or more interface addresses. + Address can be specified multiple times as IPv4 and/or IPv6 address, e.g. + 192.0.2.1/24 and/or 2001:db8::1/64. + +Link Administration +------------------- + +.. cfgcmd:: set interfaces loopback lo description <description> + + Assign given `<description>` to interface `lo`. Description will also be + passed to SNMP monitoring systems. + +Operation +========= + +.. opcmd:: show interfaces loopback + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces loopback + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + lo 127.0.0.1/8 u/u + ::1/128 + +.. opcmd:: show interfaces loopback lo + + Show detailed information on given loopback interface `lo`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 300 6 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 300 6 0 0 0 0 diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index ef595b97..9888d682 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -1,7 +1,8 @@ .. _pppoe-interface: +##### PPPoE -===== +##### :abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, @@ -14,14 +15,14 @@ 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` @@ -34,7 +35,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 @@ -50,8 +51,8 @@ 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 -~~~~~~~~~~~~~~~~~~~~~ +Example +======= Requirements: @@ -95,7 +96,7 @@ assigning it to the pppoe0 itself as shown here: set interfaces ethernet eth0 pppoe 0 firewall out name NET-OUT VLAN Example -++++++++++++ +------------ 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 @@ -116,30 +117,31 @@ which is the default VLAN for Deutsche Telekom: set interfaces ethernet eth0 vif 7 pppoe 0 password 'secret' Troubleshooting ---------------- +=============== .. opcmd:: disconnect interface <interface> -Test disconnecting given connection-oriented interface. `<interface>` can be -``pppoe0`` as example. + Test disconnecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as example. .. opcmd:: connect interface <interface> -Test connecting given connection-oriented interface. `<interface>` can be -``pppoe0`` as example. + Test connecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as example. .. opcmd:: show interfaces pppoe <interface> -Check 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 <interface> (e.g. ``pppoe0``) + Check 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 <interface> (e.g. ``pppoe0``) .. opcmd:: show interfaces pppoe <interface> log -Show entire log for the PPPoE connection starting with the oldest data. Scroll -down with the <space> key to reach the end where the current data is. + Show entire log for the PPPoE connection starting with the oldest data. + Scroll down with the <space> key to reach the end where the current data is. .. opcmd:: show interfaces pppoe <interface> log tail -Shows the same log as without the 'tail' option but start with the last few -lines and continues to show added lines until you exit with ``Ctrl + x`` + Shows the same log as without the 'tail' option but start with the last few + lines and continues to show added lines until you exit with ``Ctrl + x`` + diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst index e597e167..67dab820 100644 --- a/docs/interfaces/vxlan.rst +++ b/docs/interfaces/vxlan.rst @@ -1,7 +1,8 @@ .. _vxlan-interface: +##### VXLAN ------ +##### :abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology that attempts to address the scalability problems associated with large cloud @@ -32,12 +33,102 @@ may be blocked by the hypervisor. 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 -^^^^^^^^^^^^^^^^ +Configuration +============= + +Address +------- + +.. cfgcmd:: set interfaces vxlan <interface> address <address> + + Configure VXLAN interface `<interface>` with one or more interface + addresses. Address can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + + Example: + + .. code-block:: none + + set interfaces vxlan vxlan0 address 192.0.2.1/24 + set interfaces vxlan vxlan0 address 192.0.2.2/24 + set interfaces vxlan vxlan0 address 2001:db8::ffff/64 + set interfaces vxlan vxlan0 address 2001:db8:100::ffff/64 + + +.. cfgcmd:: set interfaces vxlan <interface> ipv6 address autoconf + + .. include:: common-ipv6-addr-autoconf.txt + +.. cfgcmd:: set interfaces vxlan <interface> ipv6 address eui64 <prefix> + + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. + + .. code-block:: none + + set interfaces vxlan vxlan0 ipv6 address eui64 2001:db8:beef::/64 + + +.. cfgcmd:: set interfaces vxlan <interface> link <interface> + + Interface used for VXLAN underlay. This is mandatory when using VXLAN via + a multicast network. VXLAN traffic will always enter and exit this interface. + + +.. cfgcmd:: set interfaces vxlan <interface> group <address> + + Multicast group address for VXLAN interface. VXLAN tunnels can be built + either via Multicast or via Unicast. + + Both IPv4 and IPv6 multicast is possible. + + +.. cfgcmd:: set interfaces vxlan <interface> remote <address> + + IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the + remote IPv4/IPv6 address can set directly. + + +.. cfgcmd:: set interfaces vxlan <interface> port <port> + + Configure port number of remote VXLAN endpoint. -Example Topology: + .. note:: As VyOS is Linux based the default port used is not using 4789 + as the default IANA-assigned destination UDP port number. Instead VyOS + uses the Linux default port of 8472. -PC4 - Leaf2 - Spine1 - Leaf3 - PC5 + +.. cfgcmd:: set interfaces vxlan <interface> vni <number> + + Each VXLAN segment is identified through a 24-bit segment ID, termed the + :abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows + up to 16M VXLAN segments to coexist within the same administrative domain. + + +Link Administration +------------------- + +.. cfgcmd:: set interfaces vxlan <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + +.. cfgcmd:: set interfaces vxlan <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + +.. cfgcmd:: set interfaces vxlan <interface> mtu <mtu> + + Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It + is the size (in bytes) of the largest ethernet frame sent on this link. + MTU ranges from 1450 to 9000 bytes. For best performance you should have + a MTU > 1550 bytes on your underlay. + +Multicast VXLAN +=============== + +Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in the same broadcast domain. @@ -65,30 +156,10 @@ For optimal scalability Multicast shouldn't be used at all, but instead use BGP to signal all connected devices between leafs. Unfortunately, VyOS does not yet support this. -Configuration commands -^^^^^^^^^^^^^^^^^^^^^^ +Example +------- -.. code-block:: none - - interfaces - vxlan <vxlan[0-16777215]> - address # IP address of the VXLAN interface - description # Description - group <ipv4> # IPv4 Multicast group address (required) - ip # IPv4 routing options - ipv6 # IPv6 routing options - link <dev> # IP interface for underlay of this vxlan overlay (optional) - mtu # MTU - policy # Policy routing options - remote # Remote address of the VXLAN tunnel, used for PTP instead of multicast - vni <1-16777215> # Virtual Network Identifier (required) - -Configuration Example -^^^^^^^^^^^^^^^^^^^^^ - -The setup is this: - -Leaf2 - Spine1 - Leaf3 +The setup is this: Leaf2 - Spine1 - Leaf3 Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a VyOS router running 1.2. @@ -111,7 +182,7 @@ Topology: Eth0 towards Spine1, IP-address 10.1.3.3/24 Eth1 towards a vlan-aware switch -Spine1 Configuration: +**Spine1 Configuration:** .. code-block:: none @@ -131,10 +202,10 @@ Spine1 Configuration: Multicast-routing is required for the leafs to forward traffic between each other in a more scalable way. This also requires PIM to be enabled towards the -Leafs so that the Spine can learn what multicast groups each Leaf expect traffic -from. +Leafs so that the Spine can learn what multicast groups each Leaf expect +traffic from. -Leaf2 configuration: +**Leaf2 configuration:** .. code-block:: none @@ -159,7 +230,7 @@ Leaf2 configuration: set interfaces vxlan vxlan242 link 'eth0' set interfaces vxlan vxlan242 vni '242' -Leaf3 configuration: +**Leaf3 configuration:** .. code-block:: none @@ -238,77 +309,11 @@ its pre-standard value of 8472 to preserve backwards compatibility. A configuration directive to support a user-specified destination port to override that behavior is available using the above command. -Older Examples -^^^^^^^^^^^^^^ - -Example for bridging normal L2 segment and vxlan overlay network, and using a -vxlan interface as routing interface. - -.. code-block:: none - - interfaces { - bridge br0 { - member { - interface vxlan0 { - } - } - } - ethernet eth0 { - address dhcp - } - loopback lo { - } - vxlan vxlan0 { - group 239.0.0.1 - vni 0 - } - vxlan vxlan1 { - address 192.168.0.1/24 - link eth0 - group 239.0.0.1 - vni 1 - } - } - -Here is a working configuration that creates a VXLAN between two routers. Each -router has a VLAN interface (26) facing the client devices and a VLAN interface -(30) that connects it to the other routers. With this configuration, traffic -can flow between both routers' VLAN 26, but can't escape since there is no L3 -gateway. You can add an IP to a bridge to create a gateway. - -.. code-block:: none - - interfaces { - bridge br0 { - member { - interface eth0.26 { - } - interface vxlan0 { - } - } - } - ethernet eth0 { - duplex auto - smp-affinity auto - speed auto - vif 30 { - address 10.7.50.6/24 - } - } - loopback lo { - } - vxlan vxlan0 { - group 239.0.0.241 - vni 241 - } - } - Unicast VXLAN -^^^^^^^^^^^^^ - -Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can set directly. -Let's change the Multicast example from above: +============= +Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be +set directly. Let's change the Multicast example from above: .. code-block:: none |