diff options
Diffstat (limited to 'docs/interfaces')
| -rw-r--r-- | docs/interfaces/advanced-index.rst | 22 | ||||
| -rw-r--r-- | docs/interfaces/basic-index.rst | 12 | ||||
| -rw-r--r-- | docs/interfaces/bond.rst | 390 | ||||
| -rw-r--r-- | docs/interfaces/bridge.rst | 271 | ||||
| -rw-r--r-- | docs/interfaces/common-ip-ipv6-addr.txt | 8 | ||||
| -rw-r--r-- | docs/interfaces/common-ipv6-addr-autoconf.txt | 12 | ||||
| -rw-r--r-- | docs/interfaces/dummy.rst | 90 | ||||
| -rw-r--r-- | docs/interfaces/ethernet.rst | 237 | ||||
| -rw-r--r-- | docs/interfaces/geneve.rst | 70 | ||||
| -rw-r--r-- | docs/interfaces/l2tpv3.rst | 122 | ||||
| -rw-r--r-- | docs/interfaces/loopback.rst | 75 | ||||
| -rw-r--r-- | docs/interfaces/macsec.rst | 179 | ||||
| -rw-r--r-- | docs/interfaces/pppoe.rst | 329 | ||||
| -rw-r--r-- | docs/interfaces/pseudo-ethernet.rst | 89 | ||||
| -rw-r--r-- | docs/interfaces/qinq.rst | 77 | ||||
| -rw-r--r-- | docs/interfaces/tunnel.rst | 205 | ||||
| -rw-r--r-- | docs/interfaces/vlan.rst | 69 | ||||
| -rw-r--r-- | docs/interfaces/vxlan.rst | 343 | ||||
| -rw-r--r-- | docs/interfaces/wireless.rst | 310 | ||||
| -rw-r--r-- | docs/interfaces/wirelessmodem.rst | 126 |
20 files changed, 0 insertions, 3036 deletions
diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst deleted file mode 100644 index c666f7ae..00000000 --- a/docs/interfaces/advanced-index.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _advanced_network-interfaces: - -########################### -Advanced Network Interfaces -########################### - -.. toctree:: - :maxdepth: 1 - - bond - bridge - dummy - geneve - l2tpv3 - macsec - pseudo-ethernet - qinq - tunnel - vlan - vxlan - wireless - wirelessmodem diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst deleted file mode 100644 index 425792a2..00000000 --- a/docs/interfaces/basic-index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _basic_network-interfaces: - -######################## -Basic Network Interfaces -######################## - -.. toctree:: - :maxdepth: 1 - - ethernet - loopback - pppoe diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst deleted file mode 100644 index 74089f96..00000000 --- a/docs/interfaces/bond.rst +++ /dev/null @@ -1,390 +0,0 @@ -.. _bond-interface: - -####################### -Bond / Link Aggregation -####################### - -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. - -Configuration -############# - -Address -------- - -.. cfgcmd:: set interfaces bonding <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 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 - - This algorithm will place all traffic to a particular network peer on - the same slave. - - 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' - - # 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 - - # Add the member interfaces to the bonding interface - set interfaces bonding bond0 member interface eth1 - set interfaces bonding bond0 member interface eth2 - -Cisco Catalyst -^^^^^^^^^^^^^^ - -Assign member interfaces to PortChannel - -.. code-block:: none - - interface GigabitEthernet1/0/23 - description VyOS eth1 - channel-group 1 mode active - ! - interface GigabitEthernet1/0/24 - description VyOS eth2 - channel-group 1 mode active - ! - -A new interface becomes present ``Port-channel1``, all configuration like -allowed VLAN interfaces, STP will happen here. - -.. code-block:: none - - interface Port-channel1 - description LACP Channel for VyOS - switchport trunk encapsulation dot1q - switchport trunk allowed vlan 10,100 - switchport mode trunk - spanning-tree portfast trunk - ! - - -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 - - # 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 - - # Create trunk with 2 member interfaces (interface 1 and 2) and LACP - trunk 1-2 Trk1 LACP - - # Add the required vlans to the trunk - vlan 10 tagged Trk1 - vlan 100 tagged Trk1 - -Operation -######### - -.. code-block:: none - - vyos@vyos:~$ show interfaces bonding - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - bond0 - u/u my-sw1 int 23 and 24 - bond0.10 192.168.0.1/24 u/u office-net - bond0.100 10.10.10.1/24 u/u management-net diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst deleted file mode 100644 index a7343a0d..00000000 --- a/docs/interfaces/bridge.rst +++ /dev/null @@ -1,271 +0,0 @@ -.. _bridge-interface: - -###### -Bridge -###### - -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. - -.. note:: Spanning Tree Protocol is not enabled by default in VyOS. - :ref:`stp` can be easily enabled if needed. - -Configuration -############# - -Address -------- - -.. cfgcmd:: set interfaces bridge <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 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 - - -.. cfgcmd:: set interfaces bridge <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -.. 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. - - .. code-block:: none - - set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 - - -.. 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. - - -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> - - 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. - - -.. _stp: - -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. - - -Example -------- - -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 - - 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 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-ip-ipv6-addr.txt b/docs/interfaces/common-ip-ipv6-addr.txt deleted file mode 100644 index f53eaeee..00000000 --- a/docs/interfaces/common-ip-ipv6-addr.txt +++ /dev/null @@ -1,8 +0,0 @@ -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. diff --git a/docs/interfaces/common-ipv6-addr-autoconf.txt b/docs/interfaces/common-ipv6-addr-autoconf.txt deleted file mode 100644 index 838b299f..00000000 --- a/docs/interfaces/common-ipv6-addr-autoconf.txt +++ /dev/null @@ -1,12 +0,0 @@ -: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 deleted file mode 100644 index e452ae73..00000000 --- a/docs/interfaces/dummy.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. _dummy-interface: - -##### -Dummy -##### - -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 dependent - on physical link states and multiple routes can be chosen 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 deleted file mode 100644 index 0633ad2c..00000000 --- a/docs/interfaces/ethernet.rst +++ /dev/null @@ -1,237 +0,0 @@ -.. _ethernet-interface: - -######## -Ethernet -######## - -Configuration -############# - -Address -------- - -.. cfgcmd:: set interfaces ethernet <interface> address <address | dhcp | dhcpv6> - - .. include:: common-ip-ipv6-addr.txt - - 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. - -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> physical offload - - Show available offloading functions on given `<interface>` - - .. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 physical offload - rx-checksumming on - tx-checksumming on - tx-checksum-ip-generic on - scatter-gather off - tx-scatter-gather off - tcp-segmentation-offload off - tx-tcp-segmentation off - tx-tcp-mangleid-segmentation off - tx-tcp6-segmentation off - udp-fragmentation-offload off - generic-segmentation-offload off - generic-receive-offload off - large-receive-offload off - rx-vlan-offload on - tx-vlan-offload on - ntuple-filters off - receive-hashing on - tx-gre-segmentation on - tx-gre-csum-segmentation on - tx-udp_tnl-segmentation on - tx-udp_tnl-csum-segmentation on - tx-gso-partial on - tx-nocache-copy off - rx-all off - -.. 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 deleted file mode 100644 index a4bc22aa..00000000 --- a/docs/interfaces/geneve.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _geneve-interface: - -###### -GENEVE -###### - -:abbr:`GENEVE (Generic Network Virtualization Encapsulation)` supports all of -the capabilities of :abbr:`VXLAN (Virtual Extensible LAN)`, :abbr:`NVGRE -(Network Virtualization using Generic Routing Encapsulation)`, and :abbr:`STT -(Stateless Transport Tunneling)` and was designed to overcome their perceived -limitations. Many believe GENEVE could eventually replace these earlier formats -entirely. - -GENEVE is designed to support network virtualization use cases, where tunnels -are typically established to act as a backplane between the virtual switches -residing in hypervisors, physical switches, or middleboxes or other appliances. -An arbitrary IP network can be used as an underlay although Clos networks - A -technique for composing network fabrics larger than a single switch while -maintaining non-blocking bandwidth across connection points. ECMP is used to -divide traffic across the multiple links and switches that constitute the -fabric. Sometimes termed "leaf and spine" or "fat tree" topologies. - -Geneve Header: - -.. code-block:: none - - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |Ver| Opt Len |O|C| Rsvd. | Protocol Type | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Virtual Network Identifier (VNI) | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Variable Length Options | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - -Configuration -============= - -.. cfgcmd:: set interfaces geneve gnv0 address <address> - - 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 - - Example: - - .. code-block:: none - - set interfaces geneve gnv0 address 192.0.2.1/24 - set interfaces geneve gnv0 address 192.0.2.2/24 - set interfaces geneve gnv0 address 2001:db8::ffff/64 - set interfaces geneve gnv0 address 2001:db8:100::ffff/64 - -.. cfgcmd:: set interfaces geneve gnv0 remote <address> - - Configure GENEVE tunnel far end/remote tunnel endpoint. - -.. cfgcmd:: set interfaces geneve gnv0 vni <vni> - - :abbr:`VNI (Virtual Network Identifier)` is an identifier for a unique - element of a virtual network. In many situations this may represent an L2 - segment, however, the control plane defines the forwarding semantics of - decapsulated packets. The VNI MAY be used as part of ECMP forwarding - decisions or MAY be used as a mechanism to distinguish between overlapping - address spaces contained in the encapsulated packet when load balancing - across CPUs. - -.. cfgcmd:: set interfaces geneve gnv0 mtu <mtu> - - Set interface :abbr:`MTU (Maximum Transfer Unit)` size. diff --git a/docs/interfaces/l2tpv3.rst b/docs/interfaces/l2tpv3.rst deleted file mode 100644 index ea540c01..00000000 --- a/docs/interfaces/l2tpv3.rst +++ /dev/null @@ -1,122 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -.. _l2tpv3-interface: - -L2TPv3 ------- - -L2TPv3 is a pseudowire protocol, you can read more about on `Wikipedia L2TPv3`_ -or in :rfc:`3921` - -L2TPv3 can transport any traffic including ethernet frames. L2TPv2 is limited -to PPP. - -Over IP -^^^^^^^ - -.. code-block:: none - - # show interfaces l2tpv3 - l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - encapsulation ip - local-ip 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote-ip 203.0.113.24 - session-id 100 - tunnel-id 200 - } - -Inverse configuration has to be applied to the remote side. - -Over UDP -^^^^^^^^ - -UDP mode works better with NAT: - -* Set local-ip to your local IP (LAN). -* Add a forwarding rule matching UDP port on your internet router. - -.. code-block:: none - - # show interfaces l2tpv3 - l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - destination-port 9001 - encapsulation udp - local-ip 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote-ip 203.0.113.24 - session-id 100 - source-port 9000 - tunnel-id 200 - } - -To create more than one tunnel, use distinct UDP ports. - - -Over IPSec, L2 VPN (bridge) -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This is the LAN extension use case. The eth0 port of the distant VPN peers -will be directly connected like if there was a switch between them. - -IPSec: - -.. code-block:: none - - set vpn ipsec ipsec-interfaces <VPN-interface> - set vpn ipsec esp-group test-ESP-1 compression 'disable' - set vpn ipsec esp-group test-ESP-1 lifetime '3600' - set vpn ipsec esp-group test-ESP-1 mode 'transport' - set vpn ipsec esp-group test-ESP-1 pfs 'enable' - set vpn ipsec esp-group test-ESP-1 proposal 1 encryption 'aes128' - set vpn ipsec esp-group test-ESP-1 proposal 1 hash 'sha1' - set vpn ipsec ike-group test-IKE-1 ikev2-reauth 'no' - set vpn ipsec ike-group test-IKE-1 key-exchange 'ikev1' - set vpn ipsec ike-group test-IKE-1 lifetime '3600' - set vpn ipsec ike-group test-IKE-1 proposal 1 dh-group '5' - set vpn ipsec ike-group test-IKE-1 proposal 1 encryption 'aes128' - set vpn ipsec ike-group test-IKE-1 proposal 1 hash 'sha1' - set vpn ipsec site-to-site peer <peer-ip> authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer <peer-ip> authentication pre-shared-secret <pre-shared-key> - set vpn ipsec site-to-site peer <peer-ip> connection-type 'initiate' - set vpn ipsec site-to-site peer <peer-ip> ike-group 'test-IKE-1' - set vpn ipsec site-to-site peer <peer-ip> ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer <peer-ip> local-address <local-ip> - set vpn ipsec site-to-site peer <peer-ip> tunnel 1 allow-nat-networks 'disable' - set vpn ipsec site-to-site peer <peer-ip> tunnel 1 allow-public-networks 'disable' - set vpn ipsec site-to-site peer <peer-ip> tunnel 1 esp-group 'test-ESP-1' - set vpn ipsec site-to-site peer <peer-ip> tunnel 1 protocol 'l2tp' - -Bridge: - -.. code-block:: none - - set interfaces bridge br0 description 'L2 VPN Bridge' - # remote side in this example: - # set interfaces bridge br0 address '172.16.30.18/30' - set interfaces bridge br0 address '172.16.30.17/30' - set interfaces bridge br0 member interface eth0 - set interfaces ethernet eth0 description 'L2 VPN Physical port' - -L2TPv3: - -.. code-block:: none - - set interfaces bridge br0 member interface 'l2tpeth0' - set interfaces l2tpv3 l2tpeth0 description 'L2 VPN Tunnel' - set interfaces l2tpv3 l2tpeth0 destination-port '5000' - set interfaces l2tpv3 l2tpeth0 encapsulation 'ip' - set interfaces l2tpv3 l2tpeth0 local-ip <local-ip> - set interfaces l2tpv3 l2tpeth0 mtu '1500' - set interfaces l2tpv3 l2tpeth0 peer-session-id '110' - set interfaces l2tpv3 l2tpeth0 peer-tunnel-id '10' - set interfaces l2tpv3 l2tpeth0 remote-ip <peer-ip> - 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 deleted file mode 100644 index e15062cf..00000000 --- a/docs/interfaces/loopback.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _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 dependent - on physical link states and multiple routes can be chosen 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/macsec.rst b/docs/interfaces/macsec.rst deleted file mode 100644 index d7af0c16..00000000 --- a/docs/interfaces/macsec.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. _macsec-interface: - -###### -MACsec -###### - -MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in 2006. -It defines a way to establish a protocol independent connection between two -hosts with data confidentiality, authenticity and/or integrity, using -GCM-AES-128. MACsec operates on the Ethernet layer and as such is a layer 2 -protocol, which means it's designed to secure traffic within a layer 2 network, -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 -############# - -.. cfgcmd:: set interfaces macsec <interface> security cipher [gcm-aes-128] - - Select cipher suite used for cryptographic operations. This setting is - mandatory. - - .. note:: gcm-aes-256 support planned once iproute2 package is updated to - version >=5.2. - -.. cfgcmd:: set interfaces macsec <interface> security encrypt - - MACsec only provides authentication by default, encryption is optional. This - command will enable encryption for all outgoing packets. - -.. cfgcmd:: set interfaces macsec <interface> source-interface <physical-source> - - A physical interface is required to connect this MACsec instance to. Traffic - leaving this interfac will now be authenticated/encrypted. - - -Key Management --------------- - -:abbr:`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between -individual peers. - -.. cfgcmd:: set interfaces macsec <interface> security mka cak <key> - - IEEE 802.1X/MACsec pre-shared key mode. This allows to configure MACsec with - a pre-shared key using a (CAK,CKN) pair. - -.. cfgcmd:: set interfaces macsec <interface> security mka ckn <key> - - CAK Name - -.. cfgcmd:: set interfaces macsec <interface> security mka priority <priority> - - The peer with lower priority will become the key server and start - distributing SAKs. - -Replay protection ------------------ - -.. cfgcmd:: set interfaces macsec <interface> security replay-window <window> - - IEEE 802.1X/MACsec replay protection window. This determines a window in which - replay is tolerated, to allow receipt of frames that have been misordered by - the network. - - - ``0``: No replay window, strict check - - ``1-4294967295``: Number of packets that could be misordered - -Operation -========= - -.. opcmd:: run generate macsec mka-cak - - Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key - - .. code-block:: none - - vyos@vyos:~$ generate macsec mka-cak - 20693b6e08bfa482703a563898c9e3ad - - -.. opcmd:: run generate macsec mka-ckn - - Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key - - .. code-block:: none - - vyos@vyos:~$ generate macsec mka-ckn - 88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 - -.. opcmd:: show interfaces macsec - - List all MACsec interfaces - - .. code-block:: none - - vyos@vyos:~$ show interfaces macsec - 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off - cipher suite: GCM-AES-128, using ICV length 16 - TXSC: 005056bfefaa0001 on SA 0 - 20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off - cipher suite: GCM-AES-128, using ICV length 16 - TXSC: 005056bfefaa0001 on SA 0 - -.. opcmd:: show interfaces macsec <interface> - - Show specific MACsec interface information - - .. code-block:: none - - vyos@vyos:~$ show interfaces macsec macsec1 - 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off - 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 -* R2 has 192.0.2.2/24 & 2001:db8::2/64 - -**R1** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.1/24' - set interfaces macsec macsec1 address '2001:db8::1/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' - set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' - set interfaces macsec macsec1 source-interface 'eth1' - -**R2** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.2/24' - set interfaces macsec macsec1 address '2001:db8::2/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' - set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' - set interfaces macsec macsec1 source-interface 'eth1' - -Pinging (IPv6) the other host and intercepting the traffic in ``eth1`` will -show you the content is encrypted. - -.. code-block:: none - - 17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: - 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... - 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df - 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. - 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... - 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. - 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; - 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i - 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... - 0x0080: 6b30 92a5 7ccc 720b k0..|.r. - -Disabling the encryption on the link by removing ``security encrypt`` will show -the unencrypted but authenticated content. - -.. code-block:: none - - 17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: - 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... - 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ - 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ - 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. - 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ - 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ - 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ - 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ - 0x0080: a282 c842 5254 ef28 ...BRT.( - diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst deleted file mode 100644 index ae6b11cc..00000000 --- a/docs/interfaces/pppoe.rst +++ /dev/null @@ -1,329 +0,0 @@ -.. _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, -in the context of the boom of DSL as the solution for tunneling packets -over the DSL connection to the :abbr:`ISPs (Internet Service Providers)` -IP network, and from there to the rest of the Internet. A 2005 networking -book noted that "Most DSL providers use PPPoE, which provides authentication, -encryption, and compression." Typical use of PPPoE involves leveraging the -PPP facilities for authenticating the user with a username and password, -predominately via the PAP protocol and less often via CHAP. - -Operating Modes -=============== - -VyOS supports setting up PPPoE in two different ways to a PPPoE internet -connection. This is due to most ISPs provide a modem that is also a wireless -router. - -Home Users ----------- - -In this method, the DSL Modem/Router connects to the ISP for you with your -credentials preprogrammed into the device. This gives you an :rfc:`1918` -address, such as ``192.168.1.0/24`` by default. - -For a simple home network using just the ISP's equipment, this is usually -desirable. But if you want to run VyOS as your firewall and router, this -will result in having a double NAT and firewall setup. This results in a -few extra layers of complexity, particularly if you use some NAT or -tunnel features. - -Business Users --------------- - -In order to have full control and make use of multiple static public IP -addresses, your VyOS will have to initiate the PPPoE connection and control -it. In order for this method to work, you will have to figure out how to make -your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL -Transceiver device to connect between the Ethernet link of your VyOS and the -phone cable. Once your DSL Transceiver is in Bridge Mode, you should get no -IP address from it. Please make sure you connect to the Ethernet Port 1 if -your DSL Transeiver has a switch, as some of them only work this way. - -Once you have an Ethernet device connected, i.e. `eth0`, then you can -configure it to open the PPPoE session for you and your DSL Transceiver -(Modem/Router) just acts to translate your messages in a way that -vDSL/aDSL understands. - -Configuration -============= - -.. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> - - Use this command to restrict the PPPoE session on a given access - concentrator. Normally, a host sends a PPPoE initiation packet to start the - PPPoE discovery process, a number of access concentrators respond with offer - packets and the host selects one of the responding access concentrators to - serve this session. - - This command allows you to select a specific access concentrator when you - know the access concentrators `<name>`. - -.. cfgcmd:: set interfaces pppoe <interface> authentication user <username> - - Use this command to set the username for authenticating with a remote PPPoE - endpoint. Authentication is optional from the system's point of view but - most service providers require it. - -.. cfgcmd:: set interfaces pppoe <interface> authentication password <password> - - Use this command to set the password for authenticating with a remote PPPoE - endpoint. Authentication is optional from the system's point of view but - most service providers require it. - -.. cfgcmd:: set interfaces pppoe <interface> connect-on-demand - - Enables or disables on-demand PPPoE connection on a PPPoE unit. - - Use this command to instruct the system to establish a PPPoE connections - automatically once traffic passes through the interface. A disabled on-demand - connection is established at boot time and remains up. If the link fails for - any reason, the link is brought back up immediately. - - Enabled on-demand PPPoE connections bring up the link only when traffic needs - to pass this link. If the link fails for any reason, the link is brought - back up automatically once traffic passes the interface again. If you - configure an on-demand PPPoE connection, you must also configure the idle - timeout period, after which an idle PPPoE link will be disconnected. A - non-zero idle timeout will never disconnect the link after it first came up. - -.. cfgcmd:: set interfaces pppoe <interface> default-route - - Use this command to specify whether to automatically add a default route - pointing to the endpoint of the PPPoE when the link comes up. The default - route is only added if no other default route already exists in the system. - - **default:** A default route to the remote endpoint is automatically added - when the link comes up (i.e. auto). - -.. cfgcmd:: set interfaces pppoe <interface> description - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - -.. cfgcmd:: set interfaces pppoe <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. - -.. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time> - - Use this command to set the idle timeout interval to be used with on-demand - PPPoE sessions. When an on-demand connection is established, the link is - brought up only when traffic is sent and is disabled when the link is idle - for the interval specified. - - If this parameter is not set or 0, an on-demand link will not be taken down - when it is idle and after the initial establishment of the connection. It - will stay up forever. - -.. cfgcmd:: set interfaces pppoe <interface> local-address <address> - - Use this command to set the IP address of the local endpoint of a PPPoE - session. If it is not set it will be negotiated. - -.. cfgcmd:: set interfaces pppoe <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. - -.. cfgcmd:: set interfaces pppoe <interface> no-peer-dns - - Use this command to not install advertised DNS nameservers into the local - system. - -.. cfgcmd:: set interfaces pppoe <interface> remote-address <address> - - Use this command to set the IP address of the remote endpoint of a PPPoE - session. If it is not set it will be negotiated. - -.. cfgcmd:: set interfaces pppoe <interface> service-name <name> - - Use this command to specify a service name by which the local PPPoE interface - can select access concentrators to connect with. It will connect to any - access concentrator if not set. - -.. cfgcmd:: set interfaces pppoe <interface> source-interface <source-interface> - - Use this command to link the PPPoE connection to a physical interface. Each - PPPoE connection must be established over a physical interface. Interfaces - can be regular Ethernet interfaces, VIFs or bonding interfaces/VIFs. - -IPv6 ----- - -.. cfgcmd:: set interfaces pppoe <interface> ipv6 enable - - Use this command to enable IPv6 support on this PPPoE connection. - -.. cfgcmd:: set interfaces pppoe <interface> ipv6 address autoconf - - Use this command to enable acquisition of IPv6 address using stateless - autoconfig (SLAAC). - -Prefix Delegation (DHCPv6-PD) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -VyOS 1.3 (equuleus) supports DHCPv6-PD. DHCPv6 Prefix Delegation is supported -by most ISPs who provide native IPv6 for consumers on fixed networks. - -.. cfgcmd:: set interfaces pppoe <interface> dhcpv6-option pd <id> length <length> - - Some ISPs by default only delegate a /64 prefix. To request for a specific - prefix size use this option to request for a bigger delegation for this pd - `<id>`. This value - is in the range from 32 - 64 so you could request up to /32 down to a /64 - delegation. - - Default value is 64. - -.. cfgcmd:: set interfaces pppoe <interface> dhcpv6-option pd <id> interface <prefix-interface> address <local-addr> - - This statement specifies the interface address used locally on the interfcae - where the prefix has been delegated to. ID must be a decimal integer. - It will be combined with the delegated prefix and the sla-id to form a - complete interface address. The default is to use the EUI-64 address of the - interface. - - Example: - - Using `<id>` value 65535 will assign IPv6 address <prefix>::ffff to the - interface. - -.. cfgcmd:: set interfaces pppoe <interface> dhcpv6-option pd <id> interface <prefix-interface> sla-id <id> - - This statement specifies the identifier value of the site-level aggregator - (SLA) on the interface. ID must be a decimal number greater then 0 which - fits in the length of SLA IDs (see below). For example, if ID is 1 and the - client is delegated an IPv6 prefix 2001:db8:ffff::/48, dhcp6c will combine - the two values into a single IPv6 prefix, 2001:db8:ffff:1::/64, and will - configure the prefix on the specified interface. - -Operation -========= - -.. opcmd:: show interfaces pppoe <interface> - - Show detailed information on given `<interface>` - - .. code-block:: none - - vyos@vyos:~$ show interfaces pppoe pppoe0 - pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 - link/ppp - inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 7002658233 5064967 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 533822843 1620173 0 0 0 0 - -.. opcmd:: show interfaces pppoe <interface> queue - - Displays queue information for a PPPoE interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces pppoe pppoe0 queue - qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 - Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) - backlog 0b 0p requeues 0 - -Connect/Disconnect ------------------- - -.. opcmd:: disconnect interface <interface> - - 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. - -Example -======= - -Requirements: - -* Your ISPs modem is connected to port ``eth0`` of your VyOS box. -* No VLAN tagging required by your ISP. -* You need your PPPoE credentials from your DSL ISP in order to configure - this. The usual username is in the form of name@host.net but may vary - depending on ISP. -* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. - If you are switching from a DHCP based ISP like cable then be aware that - things like VPN links may need to have their MTU sizes adjusted to work - within this limit. -* With the ``default-route`` option set to ``auto``, VyOS will only add the - default gateway you receive from your DSL ISP to the routing table if you - have no other WAN connections. If you wish to use a dual WAN connection, - change the ``default-route`` option to ``force``. -* With the ``name-server`` option set to ``none``, VyOS will ignore the - nameservers your ISP sens you and thus you can fully rely on the ones you - have configured statically. - -.. note:: Syntax has changed from VyOS 1.2 (crux) and it will be automatically - migrated during an upgrade. - -.. code-block:: none - - set interfaces pppoe pppoe0 default-route 'auto' - set interfaces pppoe pppoe0 mtu 1492 - set interfaces pppoe pppoe0 authentication user 'userid' - set interfaces pppoe pppoe0 authentication password 'secret' - set interfaces pppoe pppoe0 source-interface 'eth0' - - -You should add a firewall to your configuration above as well by -assigning it to the pppoe0 itself as shown here: - -.. code-block:: none - - set interfaces pppoe pppoe0 firewall in name NET-IN - set interfaces pppoe pppoe0 firewall local name NET-LOCAL - set interfaces pppoe pppoe0 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 -can easily create a PPPoE session through an encapsulated VLAN interface. -The following configuration will run your PPPoE connection through VLAN7 -which is the default VLAN for Deutsche Telekom: - -.. code-block:: none - - set interfaces pppoe pppoe0 default-route 'auto' - set interfaces pppoe pppoe0 mtu 1492 - set interfaces pppoe pppoe0 authentication user 'userid' - set interfaces pppoe pppoe0 authentication password 'secret' - set interfaces pppoe pppoe0 source-interface 'eth0.7' - - -IPv6 DHCPv6-PD Example ----------------------- - -The following configuration will assign a /64 prefix out of a /56 delegation -to eth0. The IPv6 address assigned to eth0 will be <prefix>::ffff/64. -If you do not know the prefix size delegated to you, start with sla-len 0. - -.. code-block:: none - - set interfaces pppoe pppoe0 authentication user vyos - set interfaces pppoe pppoe0 authentication password vyos - set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 address 65535 - set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 sla-id 0 - set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 sla-len 8 - set interfaces pppoe pppoe0 ipv6 address autoconf - set interfaces pppoe pppoe0 ipv6 enable - set interfaces pppoe pppoe0 source-interface eth1 diff --git a/docs/interfaces/pseudo-ethernet.rst b/docs/interfaces/pseudo-ethernet.rst deleted file mode 100644 index a2066555..00000000 --- a/docs/interfaces/pseudo-ethernet.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. _pseudo-ethernet-interface: - -####################### -Pseudo Ethernet/MACVLAN -####################### - -Pseudo-Ethernet or MACVLAN interfaces can be seen as subinterfaces to regular -ethernet interfaces. Each and every subinterface is created a different media -access control (MAC) address, for a single physical Ethernet port. Pseudo- -Ethernet interfaces have most of their application in virtualized environments, - -By using Pseudo-Ethernet interfaces there will be less system overhead compared -to running a traditional bridging approach. Pseudo-Ethernet interfaces can also -be used to workaround the general limit of 4096 virtual LANs (VLANs) per -physical Ethernet port, since that limit is with respect to a single MAC -address. - -Every Virtual Ethernet interfaces behaves like a real Ethernet interface. They -can have IPv4/IPv6 addresses configured, or can request addresses by DHCP/ -DHCPv6 and are associated/mapped with a real ethernet port. This also makes -Pseudo-Ethernet interfaces interesting for testing purposes. A Pseudo-Ethernet -device will inherit characteristics (speed, duplex, ...) from its physical -parent (the so called link) interface. - -Once created in the system, Pseudo-Ethernet interfaces can be referenced in -the exact same way as other Ethernet interfaces. Notes about using Pseudo- -Ethernet interfaces: - -* Pseudo-Ethernet interfaces can not be reached from your internal host. This - means that you can not try to ping a Pseudo-Ethernet interface from the host - system on which it is defined. The ping will be lost. -* Loopbacks occurs at the IP level the same way as for other interfaces, - ethernet frames are not forwarded between Pseudo-Ethernet interfaces. -* Pseudo-Ethernet interfaces may not work in environments which expect a - :abbr:`NIC (Network Interface Card)` to only have a single address. This - applies to: - - VMware machines using default settings - - Network switches with security settings allowing only a single MAC address - - xDSL modems that try to lear the MAC address of the NIC - -Configuration -============= - -Address -------- - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> address <address | dhcp | dhcpv6> - - .. include:: common-ip-ipv6-addr.txt - - Example: - - .. code-block:: none - - set interfaces pseudo-ethernet peth0 address 192.0.2.1/24 - set interfaces pseudo-ethernet peth0 address 192.0.2.2/24 - set interfaces pseudo-ethernet peth0 address 2001:db8::ffff/64 - set interfaces pseudo-ethernet peth0 address 2001:db8:100::ffff/64 - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -Physical Asignment ------------------- - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> - - Specifies the physical `<ethX>` Ethernet interface associated with a Pseudo - Ethernet `<interface>`. - -Link Administration -------------------- - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> description <description> - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> mac <mac-address> - - Configure user defined :abbr:`MAC (Media Access Control)` address on given - `<interface>`. - diff --git a/docs/interfaces/qinq.rst b/docs/interfaces/qinq.rst deleted file mode 100644 index 01d9c64a..00000000 --- a/docs/interfaces/qinq.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -.. _qinq-interface: - -QinQ (802.1ad) --------------- - -IEEE 802.1ad was an Ethernet networking standard informally known as QinQ as -an amendment to IEEE standard :ref:`vlan-interface`. 802.1ad was incorporated -into the base 802.1q standard in 2011. The technique is also known as provider -bridging, Stacked VLANs, or simply QinQ or Q-in-Q. "Q-in-Q" can for supported -devices apply to C-tag stacking on C-tag (Ethernet Type = 0x8100). - -The original 802.1q specification allows a single Virtual Local Area Network -(VLAN) header to be inserted into an Ethernet frame. QinQ allows multiple -VLAN tags to be inserted into a single frame, an essential capability for -implementing Metro Ethernet network topologies. Just as QinQ extends 802.1Q, -QinQ itself is extended by other Metro Ethernet protocols. - -In a multiple VLAN header context, out of convenience the term "VLAN tag" or -just "tag" for short is often used in place of "802.1Q VLAN header". QinQ -allows multiple VLAN tags in an Ethernet frame; together these tags constitute -a tag stack. When used in the context of an Ethernet frame, a QinQ frame is a -frame that has 2 VLAN 802.1Q headers (double-tagged). - -In VyOS the terms **vif-s** and **vif-c** stand for the ethertype tags that -are used: - -The inner tag is the tag which is closest to the payload portion of the frame. -It is officially called C-TAG (customer tag, with ethertype 0x8100). The outer -tag is the one closer/closest to the Ethernet header, its name is S-TAG -(service tag with ethertype 0x88a8). - -Configuration commands: - -.. code-block:: none - - interfaces - ethernet <eth[0-999]> - address <ipv4> - address <ipv6> - description <txt> - disable - ip - <usual IP options> - ipv6 - <usual IPv6 options> - vif-s <[0-4096]> - address <ipv4> - address <ipv6> - description <txt> - disable - ip - <usual IP options> - ipv6 - <usual IPv6 options> - vif-c <[0-4096]> - address <ipv4> - address <ipv6> - description <txt> - disable - ip - <usual IP options> - ipv6 - <usual IPv6 options> - - -Example: - -.. code-block:: none - - set interfaces ethernet eth0 vif-s 333 - set interfaces ethernet eth0 vif-s 333 address 192.0.2.10/32 - set interfaces ethernet eth0 vif-s 333 vif-c 777 - set interfaces ethernet eth0 vif-s 333 vif-c 777 address 10.10.10.10/24 - -.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad
\ No newline at end of file diff --git a/docs/interfaces/tunnel.rst b/docs/interfaces/tunnel.rst deleted file mode 100644 index f20127f5..00000000 --- a/docs/interfaces/tunnel.rst +++ /dev/null @@ -1,205 +0,0 @@ -.. _tunnel-interface: - -Tunnel -====== - -This article touches on 'classic' IP tunneling protocols. - -GRE is often seen as a one size fits all solution when it comes to classic IP -tunneling protocols, and for a good reason. However, there are more specialized -options, and many of them are supported by VyOS. There are also rather obscure -GRE options that can be useful. - -All those protocols are grouped under ``interfaces tunnel`` in VyOS. Let's take -a closer look at the protocols and options currently supported by VyOS. - -IPIP ----- - -This is one of the simplest types of tunnels, as defined by :rfc:`2003`. -It takes an IPv4 packet and sends it as a payload of another IPv4 packet. For -this reason, there are no other configuration options for this kind of tunnel. - -An example: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation ipip - set interfaces tunnel tun0 local-ip 192.0.2.10 - set interfaces tunnel tun0 remote-ip 203.0.113.20 - set interfaces tunnel tun0 address 192.168.100.200/24 - -IP6IP6 ------- - -This is the IPv6 counterpart of IPIP. I'm not aware of an RFC that defines this -encapsulation specifically, but it's a natural specific case of IPv6 -encapsulation mechanisms described in :rfc:2473`. - -It's not likely that anyone will need it any time soon, but it does exist. - -An example: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation ip6ip6 - set interfaces tunnel tun0 local-ip 2001:db8:aa::1 - set interfaces tunnel tun0 remote-ip 2001:db8:aa::2 - set interfaces tunnel tun0 address 2001:db8:bb::1/64 - -IPIP6 ------ - -In the future this is expected to be a very useful protocol (though there are -`other proposals`_). - -As the name implies, it's IPv4 encapsulated in IPv6, as simple as that. - -An example: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation ipip6 - set interfaces tunnel tun0 local-ip 2001:db8:aa::1 - set interfaces tunnel tun0 remote-ip 2001:db8:aa::2 - set interfaces tunnel tun0 address 192.168.70.80/24 - -6in4 (SIT) ----------- - -6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in -:rfc:`4213`. The 6in4 traffic is sent over IPv4 inside IPv4 packets whose IP -headers have the IP protocol number set to 41. This protocol number is -specifically designated for IPv6 encapsulation, the IPv4 packet header is -immediately followed by the IPv6 packet being carried. The encapsulation -overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of -1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This -tunneling technique is frequently used by IPv6 tunnel brokers like `Hurricane -Electric`_. - -An example: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation sit - set interfaces tunnel tun0 local-ip 192.0.2.10 - set interfaces tunnel tun0 remote-ip 192.0.2.20 - set interfaces tunnel tun0 address 2001:db8:bb::1/64 - -A full example of a Tunnelbroker.net config can be found at :ref:`here <examples-tunnelbroker-ipv6>`. - -Generic Routing Encapsulation (GRE) ------------------------------------ - -A GRE tunnel operates at layer 3 of the OSI model and is repsented by IP -protocol 47.The main benefit of a GRE tunnel is that you are able to route -traffic across disparate networks. GRE also supports multicast traffic and -supports routing protocols that leverage multicast to form neighbor adjacencies. - -Configuration -^^^^^^^^^^^^^ - -A basic configuration requires a tunnel source (local-ip), a tunnel destination -(remote-ip), an encapsulation type (gre), and an address (ipv4/ipv6).Below is a -configuration example taken from a VyOS router and a Cisco IOS router. The main -difference between these two configurations is that VyOS requires you -explicitly configure the encapsulation type. The Cisco router defaults to gre -ip otherwise it would have to be configured as well. - -**VyOS Router:** - -.. code-block:: none - - set interfaces tunnel tun100 address '10.0.0.1/30' - set interfaces tunnel tun100 encapsulation 'gre' - set interfaces tunnel tun100 local-ip '198.51.100.2' - set interfaces tunnel tun100 remote-ip '203.0.113.10' - -**Cisco IOS Router:** - -.. code-block:: none - - interface Tunnel100 - ip address 10.0.0.2 255.255.255.252 - tunnel source 203.0.113.10 - tunnel destination 198.51.100.2 - -Troubleshooting -^^^^^^^^^^^^^^^ - -GRE is a well defined standard that is common in most networks. While not -inherently difficult to configure there are a couple of things to keep in mind -to make sure the configuration performs as expected. A common cause for GRE -tunnels to fail to come up correctly include ACL or Firewall configurations -that are discarding IP protocol 47 or blocking your source/desintation traffic. - -**1. Confirm IP connectivity between tunnel local-ip and remote-ip:** - -.. code-block:: none - - vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 - PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. - 64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms - 64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms - 64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms - 64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms - - --- 203.0.113.10 ping statistics --- - 4 packets transmitted, 4 received, 0% packet loss, time 3007ms - rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms - -**2. Confirm the link type has been set to GRE:** - -.. code-block:: none - - vyos@vyos:~$ show interfaces tunnel tun100 - tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 - link/gre 198.51.100.2 peer 203.0.113.10 - inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 - valid_lft forever preferred_lft forever - inet6 fe80::5efe:c612:2/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 2183 27 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 836 9 0 0 0 0 - -**3. Confirm IP connectivity across the tunnel:** - -.. code-block:: none - - vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 - PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. - 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms - 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms - 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms - 64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms - - --- 10.0.0.2 ping statistics --- - 4 packets transmitted, 4 received, 0% packet loss, time 3008ms - rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms - -Virtual Tunnel Interface (VTI) ------------------------------- - -Set Virtual Tunnel Interface - -.. code-block:: none - - set interfaces vti vti0 address 192.168.2.249/30 - set interfaces vti vti0 address 2001:db8:2::249/64 - -Results in: - -.. code-block:: none - - vyos@vyos# show interfaces vti - vti vti0 { - address 192.168.2.249/30 - address 2001:db8:2::249/64 - description "Description" - } - -.. _`other proposals`: https://www.isc.org/othersoftware/ -.. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/interfaces/vlan.rst b/docs/interfaces/vlan.rst deleted file mode 100644 index 55656d5d..00000000 --- a/docs/interfaces/vlan.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _vlan-interface: - -VLAN (802.1q) -------------- - -IEEE 802.1q, often referred to as Dot1q, is the networking standard that -supports virtual LANs (VLANs) on an IEEE 802.3 Ethernet network. The -standard defines a system of VLAN tagging for Ethernet frames and the -accompanying procedures to be used by bridges and switches in handling -such frames. The standard also contains provisions for a quality-of-service -prioritization scheme commonly known as IEEE 802.1p and defines the Generic -Attribute Registration Protocol. - -Portions of the network which are VLAN-aware (i.e., IEEE 802.1q conformant) -can include VLAN tags. When a frame enters the VLAN-aware portion of the -network, a tag is added to represent the VLAN membership. Each frame must -be distinguishable as being within exactly one VLAN. A frame in the -VLAN-aware portion of the network that does not contain a VLAN tag is -assumed to be flowing on the native VLAN. - -The standard was developed by IEEE 802.1, a working group of the IEEE 802 -standards committee, and continues to be actively revised. One of the -notable revisions is 802.1Q-2014 which incorporated IEEE 802.1aq (Shortest -Path Bridging) and much of the IEEE 802.1d standard. - -802.1a VLAN interfaces are represented as virtual sub-interfaces in VyOS. The -term used for this is ``vif``. Configuration of a tagged sub-interface is -accomplished using the configuration command: -``set interfaces ethernet <name> vif <vlan-id>`` - -To assign a vif 100 using the VLAN 100 tag to physical interface eth1 use: - -.. code-block:: none - - set interfaces ethernet eth1 vif 100 description 'VLAN 100' - set interfaces ethernet eth1 vif 100 address '192.168.100.1/24' - set interfaces ethernet eth1 vif 100 address '2001:db8:100::1/64' - -Resulting in: - -.. code-block:: none - - ethernet eth1 { - address 192.168.100.1/24 - address 2001:db8:100::1/64 - description INSIDE - duplex auto - hw-id 00:53:29:44:3b:19 - smp_affinity auto - speed auto - vif 100 { - address 192.168.100.1/24 - description "VLAN 100" - } - } - -VLAN interfaces are shown as `<name>.<vlan-id>`, e.g. `eth1.100`: - -.. code-block:: none - - vyos@vyos:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 172.16.51.129/24 u/u OUTSIDE - eth1 192.168.0.1/24 u/u INSIDE - eth1.100 192.168.100.1/24 u/u VLAN 100 - lo 127.0.0.1/8 u/u - ::1/128 diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst deleted file mode 100644 index a11f4b62..00000000 --- a/docs/interfaces/vxlan.rst +++ /dev/null @@ -1,343 +0,0 @@ -.. _vxlan-interface: - -##### -VXLAN -##### - -:abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology -that attempts to address the scalability problems associated with large cloud -computing deployments. It uses a VLAN-like encapsulation technique to -encapsulate OSI layer 2 Ethernet frames within layer 4 UDP datagrams, using -4789 as the default IANA-assigned destination UDP port number. VXLAN -endpoints, which terminate VXLAN tunnels and may be either virtual or physical -switch ports, are known as :abbr:`VTEPs (VXLAN tunnel endpoints)`. - -VXLAN is an evolution of efforts to standardize on an overlay encapsulation -protocol. It increases scalability up to 16 million logical networks and -allows for layer 2 adjacency across IP networks. Multicast or unicast with -head-end replication (HER) is used to flood broadcast, unknown unicast, -and multicast (BUM) traffic. - -The VXLAN specification was originally created by VMware, Arista Networks -and Cisco. Other backers of the VXLAN technology include Huawei, Broadcom, -Citrix, Pica8, Big Switch Networks, Cumulus Networks, Dell EMC, Ericsson, -Mellanox, FreeBSD, OpenBSD, Red Hat, Joyent, and Juniper Networks. - -VXLAN was officially documented by the IETF in :rfc:`7348`. - -If configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing -(Hyper-V) or Forged Transmits (ESX) are permitted, otherwise forwarded frames -may be blocked by the hypervisor. - -.. note:: As VyOS is based on Linux and there was no official IANA port assigned - for VXLAN, VyOS uses a default port of 8472. You can change the port on a - per VXLAN interface basis to get it working across multiple vendors. - -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> 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. - -Multicast -^^^^^^^^^ - -.. cfgcmd:: set interfaces vxlan <interface> source-interface <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. - -Unicast -^^^^^^^ - -.. 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. - - .. 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. - -L2VVPN / EVPN -^^^^^^^^^^^^^ - -.. cfgcmd:: set interfaces vxlan <interface> source-address <interface> - - Source IP address used for VXLAN underlay. This is mandatory when using - VXLAN via L2VPN/EVPN. - - -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. - -Let's assume PC4 on Leaf2 wants to ping PC5 on Leaf3. Instead of setting Leaf3 -as our remote end manually, Leaf2 encapsulates the packet into a UDP-packet and -sends it to its designated multicast-address via Spine1. When Spine1 receives -this packet it forwards it to all other Leafs who has joined the same -multicast-group, in this case Leaf3. When Leaf3 receives the packet it forwards -it, while at the same time learning that PC4 is reachable behind Leaf2, because -the encapsulated packet had Leaf2's IP-address set as source IP. - -PC5 receives the ping echo, responds with an echo reply that Leaf3 receives and -this time forwards to Leaf2's unicast address directly because it learned the -location of PC4 above. When Leaf2 receives the echo reply from PC5 it sees that -it came from Leaf3 and so remembers that PC5 is reachable via Leaf3. - -Thanks to this discovery, any subsequent traffic between PC4 and PC5 will not -be using the multicast-address between the Leafs as they both know behind which -Leaf the PCs are connected. This saves traffic as less multicast packets sent -reduces the load on the network, which improves scalability when more Leafs are -added. - -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. - -Example -------- - -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. - -This topology was built using GNS3. - -Topology: - -.. code-block:: none - - Spine1: - fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 - fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 - - Leaf2: - Eth0 towards Spine1, IP-address: 10.1.2.2/24 - Eth1 towards a vlan-aware switch - - Leaf3: - Eth0 towards Spine1, IP-address 10.1.3.3/24 - Eth1 towards a vlan-aware switch - -**Spine1 Configuration:** - -.. code-block:: none - - conf t - ip multicast-routing - ! - interface fastethernet0/2 - ip address 10.1.2.1 255.255.255.0 - ip pim sparse-dense-mode - ! - interface fastethernet0/3 - ip address 10.1.3.1 255.255.255.0 - ip pim sparse-dense-mode - ! - router ospf 1 - network 10.0.0.0 0.255.255.255 area 0 - -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. - -**Leaf2 configuration:** - -.. code-block:: none - - set interfaces ethernet eth0 address '10.1.2.2/24' - set protocols ospf area 0 network '10.0.0.0/8' - - ! Our first vxlan interface - set interfaces bridge br241 address '172.16.241.1/24' - set interfaces bridge br241 member interface 'eth1.241' - set interfaces bridge br241 member interface 'vxlan241' - - set interfaces vxlan vxlan241 group '239.0.0.241' - set interfaces vxlan vxlan241 link 'eth0' - set interfaces vxlan vxlan241 vni '241' - - ! Our seconds vxlan interface - set interfaces bridge br242 address '172.16.242.1/24' - set interfaces bridge br242 member interface 'eth1.242' - set interfaces bridge br242 member interface 'vxlan242' - - set interfaces vxlan vxlan242 group '239.0.0.242' - set interfaces vxlan vxlan242 link 'eth0' - set interfaces vxlan vxlan242 vni '242' - -**Leaf3 configuration:** - -.. code-block:: none - - set interfaces ethernet eth0 address '10.1.3.3/24' - set protocols ospf area 0 network '10.0.0.0/8' - - ! Our first vxlan interface - set interfaces bridge br241 address '172.16.241.1/24' - set interfaces bridge br241 member interface 'eth1.241' - set interfaces bridge br241 member interface 'vxlan241' - - set interfaces vxlan vxlan241 group '239.0.0.241' - set interfaces vxlan vxlan241 link 'eth0' - set interfaces vxlan vxlan241 vni '241' - - ! Our seconds vxlan interface - set interfaces bridge br242 address '172.16.242.1/24' - set interfaces bridge br242 member interface 'eth1.242' - set interfaces bridge br242 member interface 'vxlan242' - - set interfaces vxlan vxlan242 group '239.0.0.242' - set interfaces vxlan vxlan242 link 'eth0' - set interfaces vxlan vxlan242 vni '242' - -As you can see, Leaf2 and Leaf3 configuration is almost identical. There are -lots of commands above, I'll try to into more detail below, command -descriptions are placed under the command boxes: - -.. code-block:: none - - set interfaces bridge br241 address '172.16.241.1/24' - -This commands creates a bridge that is used to bind traffic on eth1 vlan 241 -with the vxlan241-interface. The IP-address is not required. It may however be -used as a default gateway for each Leaf which allows devices on the vlan to -reach other subnets. This requires that the subnets are redistributed by OSPF -so that the Spine will learn how to reach it. To do this you need to change the -OSPF network from '10.0.0.0/8' to '0.0.0.0/0' to allow 172.16/12-networks to be -advertised. - -.. code-block:: none - - set interfaces bridge br241 member interface 'eth1.241' - set interfaces bridge br241 member interface 'vxlan241' - -Binds eth1.241 and vxlan241 to each other by making them both member interfaces of -the same bridge. - -.. code-block:: none - - set interfaces vxlan vxlan241 group '239.0.0.241' - -The multicast-group used by all Leafs for this vlan extension. Has to be the -same on all Leafs that has this interface. - -.. code-block:: none - - set interfaces vxlan vxlan241 link 'eth0' - -Sets the interface to listen for multicast packets on. Could be a loopback, not -yet tested. - -.. code-block:: none - - set interfaces vxlan vxlan241 vni '241' - -Sets the unique id for this vxlan-interface. Not sure how it correlates with -multicast-address. - -.. code-block:: none - - set interfaces vxlan vxlan241 remote-port 12345 - -The destination port used for creating a VXLAN interface in Linux defaults to -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. - -Unicast VXLAN -============= - -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 - - # leaf2 and leaf3 - delete interfaces vxlan vxlan241 group '239.0.0.241' - delete interfaces vxlan vxlan241 link 'eth0' - - # leaf2 - set interface vxlan vxlan241 remote 10.1.3.3 - - # leaf3 - set interface vxlan vxlan241 remote 10.1.2.2 - -The default port udp is set to 8472. -It can be changed with ``set interface vxlan <vxlanN> remote-port <port>`` diff --git a/docs/interfaces/wireless.rst b/docs/interfaces/wireless.rst deleted file mode 100644 index 8b1195fa..00000000 --- a/docs/interfaces/wireless.rst +++ /dev/null @@ -1,310 +0,0 @@ -.. _wireless-interface: - -Wireless LAN (WiFi) -------------------- - -:abbr:`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless -support (commonly referred to as Wi-Fi) by means of compatible hardware. If your -hardware supports it, VyOS supports multiple logical wireless interfaces per -physical device. - -There are three modes of operation for a wireless interface: - -* :abbr:`WAP (Wireless Access-Point)` provides network access to connecting - stations if the physical hardware supports acting as a WAP - -* A station acts as a Wi-Fi client accessing the network through an available - WAP - -* Monitor, the system passively monitors any kind of wireless traffic - -If the system detects an unconfigured wireless device, it will be automatically -added the configuration tree, specifying any detected settings (for example, -its MAC address) and configured to run in monitor mode. - -To be able to use the wireless interfaces you will first need to set a -regulatory domain with the country code of your location. - -.. cfgcmd:: set system wifi-regulatory-domain DE - - Configure system wide Wi-Fi regulatory domain. A reboot is required for this - change to be enabled. - -Configuring Access-Point -^^^^^^^^^^^^^^^^^^^^^^^^ - -The following example creates a WAP. When configuring multiple WAP interfaces, -you must specify unique IP addresses, channels, Network IDs commonly referred -to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses. - -The WAP in this example has the following characteristics: - -* IP address ``192.168.2.1/24`` -* Network ID (SSID) ``TEST`` -* WPA passphrase ``12345678`` -* Use 802.11n protocol -* Wireless channel ``1`` - -.. code-block:: none - - set interfaces wireless wlan0 address '192.168.2.1/24' - set interfaces wireless wlan0 type access-point - set interfaces wireless wlan0 channel 1 - set interfaces wireless wlan0 mode n - set interfaces wireless wlan0 ssid 'TEST' - set interfaces wireless wlan0 security wpa mode wpa2 - set interfaces wireless wlan0 security wpa cipher CCMP - set interfaces wireless wlan0 security wpa passphrase '12345678' - -Resulting in - -.. code-block:: none - - interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - passphrase "12345678" - } - } - ssid "TEST" - type access-point - } - } - system { - [...] - wifi-regulatory-domain DE - } - -To get it to work as a access point with this configuration you will need -to set up a DHCP server to work with that network. You can - of course - also -bridge the Wireless interface with any configured bridge -(:ref:`bridge-interface`) on the system. - -WPA/WPA2 enterprise -******************* - -:abbr:`WPA (Wi-Fi Protected Access)` and WPA2 Enterprise in combination with -802.1x based authentication can be used to authenticate users or computers -in a domain. - -The wireless client (supplicant) authenticates against the RADIUS server -(authentication server) using an :abbr:`EAP (Extensible Authentication -Protocol)` method configured on the RADIUS server. The WAP (also referred -to as authenticator) role is to send all authentication messages between the -supplicant and the configured authentication server, thus the RADIUS server -is responsible for authenticating the users. - -The WAP in this example has the following characteristics: - -* IP address ``192.168.2.1/24`` -* Network ID (SSID) ``Enterprise-TEST`` -* WPA passphrase ``12345678`` -* Use 802.11n protocol -* Wireless channel ``1`` -* RADIUS server at ``192.168.3.10`` with shared-secret ``VyOSPassword`` - -.. code-block:: none - - set interfaces wireless wlan0 address '192.168.2.1/24' - set interfaces wireless wlan0 type access-point - set interfaces wireless wlan0 channel 1 - set interfaces wireless wlan0 mode n - set interfaces wireless wlan0 ssid 'TEST' - set interfaces wireless wlan0 security wpa mode wpa2 - set interfaces wireless wlan0 security wpa cipher CCMP - set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' - set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 - -Resulting in - -.. code-block:: none - - interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - radius { - server 192.168.3.10 { - key 'VyOSPassword' - port 1812 - } - } - } - } - ssid "Enterprise-TEST" - type access-point - } - } - system { - [...] - wifi-regulatory-domain DE - } - - -Configuring Wireless Station -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The example creates a wireless station (commonly referred to as Wi-Fi client) -that accesses the network through the WAP defined in the above example. The -default physical device (``phy0``) is used. - -.. code-block:: none - - set interfaces wireless wlan0 type station - set interfaces wireless wlan0 address dhcp - set interfaces wireless wlan0 ssid Test - set interfaces wireless wlan0 security wpa - -Resulting in - -.. code-block:: none - - interfaces { - [...] - wireless wlan0 { - address dhcp - security { - wpa { - passphrase "12345678" - } - } - ssid TEST - type station - } - -Operational Commands -^^^^^^^^^^^^^^^^^^^^ - -.. opcmd:: show interfaces wireless info - -Use this command to view operational status and wireless-specific information -about all wireless interfaces. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless info - Interface Type SSID Channel - wlan0 access-point VyOS-TEST-0 1 - -.. opcmd:: show interfaces wireless detail - -Use this command to view operational status and detailes wireless-specific -information about all wireless interfaces. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless detail - wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.99.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 66072 282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 83413 430 0 0 0 0 - - wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.100.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 166072 5282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 183413 5430 0 0 0 0 - -.. opcmd:: show interfaces wireless <wlanX> - -This command shows both status and statistics on the specified wireless interface. -The wireless interface identifier can range from wlan0 to wlan999. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 - wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.99.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 66072 282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 83413 430 0 0 0 0 - - -.. opcmd:: show interfaces wireless <wlanX> brief - -This command gives a brief status overview of a specified wireless interface. -The wireless interface identifier can range from wlan0 to wlan999. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 brief - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - wlan0 192.168.2.254/24 u/u - - -.. opcmd:: show interfaces wireless <wlanX> queue - -Use this command to view wireless interface queue information. -The wireless interface identifier can range from wlan0 to wlan999. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 queue - qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 - Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) - rate 0bit 0pps backlog 0b 0p requeues 0 - - -.. opcmd:: show interfaces wireless <wlanX> scan - -This command is used to retrieve information about WAP within the range of your -wireless interface. This command is useful on wireless interfaces configured -in station mode. - -.. note:: Scanning is not supported on all wireless drivers and wireless - hardware. Refer to your driver and wireless hardware documentation for - further details. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 scan - Address SSID Channel Signal (dbm) - 00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 - 00:53:3b:88:6e:da Telekom_FON 1 -64.00 - 00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 - 00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 - 00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 - 00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 - 00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 - 00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 - 00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 - 00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 - 00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 - 00:53:86:40:30:da Telekom_FON 1 -86.00 - 00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 - 00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 - diff --git a/docs/interfaces/wirelessmodem.rst b/docs/interfaces/wirelessmodem.rst deleted file mode 100644 index 5cded6c5..00000000 --- a/docs/interfaces/wirelessmodem.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. _wwan-interface: - -#################### -WirelessModem (WWAN) -#################### - -Configuration -############# - -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. - -Address -------- - -.. cfgcmd:: set interfaces wirelessmodem <interface> apn <apn> - - Every WWAN connection requires an :abbr:`APN (Access Point Name)` which is - used by the client to dial into the ISPs network. This is a mandatory - parameter. Contact your Service Provider for correct APN. - -.. cfgcmd:: set interfaces wirelessmodem <interface> backup distance <metric> - - Configure metric of the default route added via the Wireless Modem interface. - The default metric if not specified is 10. - -.. cfgcmd:: set interfaces wirelessmodem <interface> device <tty> - - Device identifier of the underlaying physical interface. This is usually a - ttyUSB device, if not configured this defaults to ttyUSB2. - -.. cfgcmd:: set interfaces wirelessmodem <interface> no-peer-dns - - Do not install DNS nameservers received from ISP into system wide nameserver - list. - -.. cfgcmd:: set interfaces wirelessmodem <interface> ondemand - - Enables or disables on-demand WWAN connection. - - Use this command to instruct the system to establish a PPP connection - automatically once traffic passes through the interface. A disabled on-demand - connection is established at boot time and remains up. If the link fails for - any reason, the link is brought back up immediately. - -Link Administration -------------------- - -.. cfgcmd:: set interfaces wirelessmodem <interface> description <description> - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - -.. cfgcmd:: set interfaces wirelessmodem <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - state. - -.. cfgcmd:: set interfaces wirelessmodem <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. - -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> - - Retrive interface information from given WWAN interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wirelessmodem wlm0 - wlm0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master black state UNKNOWN group default qlen 3 - link/ppp - inet 10.26.238.93 peer 10.64.64.64/32 scope global wlm0 - valid_lft forever preferred_lft forever - Description: baaar - - RX: bytes packets errors dropped overrun mcast - 38 5 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 217 8 0 0 0 0 - -.. opcmd:: show interfaces wirelessmodem <interface> statistics - - Retrive interface statistics from given WWAN interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wirelessmodem wlm0 statistics - IN PACK VJCOMP VJUNC VJERR | OUT PACK VJCOMP VJUNC NON-VJ - 38 5 0 0 0 | 217 8 0 0 8 - -.. opcmd:: show interfaces wirelessmodem <interface> log - - Displays log information for a WWAN interface. - -Supported Modules -################# - -The following hardware modules have been tested successfully in an -:ref:`pc-engines-apu4` board: - -* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) -* Huawei ME909u-521 miniPCIe card (LTE) - |