diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-10 17:27:05 +0300 |
|---|---|---|
| committer | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-10 17:27:05 +0300 |
| commit | e7a0bebdb5dc4b436b8b610bcb4f01afc33152e0 (patch) | |
| tree | d9ad6bc834c8e5240c300dff6d47841c2787ce61 /docs/configuration/interfaces | |
| parent | 15855844e1fe5b0bd39b020639f4c08c69d24864 (diff) | |
| download | vyos-documentation-e7a0bebdb5dc4b436b8b610bcb4f01afc33152e0.tar.gz vyos-documentation-e7a0bebdb5dc4b436b8b610bcb4f01afc33152e0.zip | |
chore: remove RST swap mechanism, archive rst-*.rst under docs/_rst_legacy/
The swap mechanism (RST-as-fallback for migrated MD pages) is dormant —
docs/_rst_overrides.txt has been empty since the MyST flip trio
landed. The mechanism's surface area is dead weight and the rst-*.rst
shadows scattered across the source tree cause Context7's parser to
misclassify the project as RST.
Sibling PRs:
- yuriy/remove-rst-swap-mechanism (rolling)
- yuriy/remove-rst-swap-mechanism-circinus
Changes:
- Move 210 rst-*.rst shadow files into docs/_rst_legacy/ preserving
subdirectory structure. They remain in the repo for reference; Sphinx
excludes the folder via exclude_patterns.
- Strip swap_sources.py invocation from docs/Makefile.
- Strip rst-*.rst exclude entry and the _md_exclude.txt loader from
docs/conf.py; replace with a single _rst_legacy exclude.
- Delete scripts/swap_sources.py, tests/test_swap_sources.py,
docs/_rst_overrides.txt.
- Update AGENTS.md: drop the "RST override mechanism" section and the
test-runner snippet for the deleted test.
Note: .readthedocs.yml on sagitta has no jobs: block to remove (the
swap was wired only at build-time via the Makefile chain on this branch).
Verified: sphinx-build -b html with --keep-going produces identical
warning set (409 unique — pre-existing cli.rst/aws.rst title-level
warnings on this branch), identical sitemap entry count (215),
identical llms.txt entry count (23), zero rst-* URLs in any artifact.
🤖 Generated by [robots](https://vyos.io)
Diffstat (limited to 'docs/configuration/interfaces')
20 files changed, 0 insertions, 5695 deletions
diff --git a/docs/configuration/interfaces/rst-bonding.rst b/docs/configuration/interfaces/rst-bonding.rst deleted file mode 100644 index 27f1bbed..00000000 --- a/docs/configuration/interfaces/rst-bonding.rst +++ /dev/null @@ -1,645 +0,0 @@ -:lastproofread: 2021-06-30 - -.. _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 -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: bonding - :var1: bond0 - -Member Interfaces -================= - -.. cfgcmd:: set interfaces bonding <interface> member interface <member> - - Enslave `<member>` interface to bond `<interface>`. - -Bond options -============ - -.. cfgcmd:: set interfaces bonding <interface> mode <802.3ad | active-backup | - broadcast | round-robin | transmit-load-balance | adaptive-load-balance | - xor-hash> - - Specifies one of the bonding policies. The default is 802.3ad. Possible - values are: - - * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation - 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 misordering 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> min-links <0-16> - - Specifies the minimum number of links that must be active before asserting - carrier. It is similar to the Cisco EtherChannel min-links feature. This - allows setting the minimum number of member ports that must be up (link-up - state) before marking the bond device as up (carrier on). This is useful for - situations where higher level services such as clustering want to ensure a - minimum number of low bandwidth links are active before switchover. - - This option only affects 802.3ad mode. - - The default value is 0. This will cause the carrier to be asserted - (for 802.3ad mode) whenever there is an active aggregator, - regardless of the number of available links in that aggregator. - - .. note:: Because an aggregator cannot be active without at least one - available link, setting this option to 0 or to 1 has the exact same - effect. - -.. cfgcmd:: set interfaces bonding <interface> lacp-rate <slow|fast> - - Option specifying the rate in which we'll ask our link partner to transmit - LACPDU packets in 802.3ad mode. - - This option only affects 802.3ad mode. - - * slow: Request partner to transmit LACPDUs every 30 seconds - - * fast: Request partner to transmit LACPDUs every 1 second - - The default value is slow. - -.. cfgcmd:: set interfaces bonding <interface> system-mac <mac address> - - This option allow to specifies the 802.3ad system MAC address.You can set a - random mac-address that can be used for these LACPDU exchanges. - -.. 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 these 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 address. - -VLAN -==== - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: bonding - :var1: bond0 - -Port Mirror (SPAN) -================== - -.. cmdinclude:: ../../_include/interface-mirror.txt - :var0: bondinging - :var1: bond1 - :var2: eth3 - -EVPN Multihoming ----------------- - -All-Active Multihoming is used for redundancy and load sharing. Servers are -attached to two or more PEs and the links are bonded (link-aggregation). -This group of server links is referred to as an :abbr:`ES (Ethernet Segment)`. - -An Ethernet Segment can be configured by specifying a system-MAC and a local -discriminator or a complete ESINAME against the bond interface on the PE. - -.. cfgcmd:: set interfaces bonding <interface> evpn es-id <<1-16777215|10-byte ID> -.. cfgcmd:: set interfaces bonding <interface> evpn es-sys-mac <xx:xx:xx:xx:xx:xx> - - The sys-mac and local discriminator are used for generating a 10-byte, Type-3 - Ethernet Segment ID. ESINAME is a 10-byte, Type-0 Ethernet Segment ID - - "00:AA:BB:CC:DD:EE:FF:GG:HH:II". - - Type-1 (EAD-per-ES and EAD-per-EVI) routes are used to advertise the locally - attached ESs and to learn off remote ESs in the network. Local Type-2/MAC-IP - routes are also advertised with a destination ESI allowing for MAC-IP syncing - between Ethernet Segment peers. Reference: RFC 7432, RFC 8365 - - EVPN-MH is intended as a replacement for MLAG or Anycast VTEPs. In multihoming - each PE has an unique VTEP address which requires the introduction of a new - dataplane construct, MAC-ECMP. Here a MAC/FDB entry can point to a list of - remote PEs/VTEPs. - -.. cfgcmd:: set interfaces bonding <interface> evpn es-df-pref <1-65535> - - Type-4 (ESR) routes are used for Designated Forwarder (DF) election. - DFs forward BUM traffic received via the overlay network. This - implementation uses a preference based DF election specified by - draft-ietf-bess-evpn-pref-df. - - The DF preference is configurable per-ES. - - BUM traffic is rxed via the overlay by all PEs attached to a server but - only the DF can forward the de-capsulated traffic to the access port. - To accommodate that non-DF filters are installed in the dataplane to drop - the traffic. - - Similarly traffic received from ES peers via the overlay cannot be forwarded - to the server. This is split-horizon-filtering with local bias. - -.. cmdinclude:: /_include/interface-evpn-uplink.txt - :var0: bonding - :var1: bond0 - -******* -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 - - -.. note:: If you happen to run this in a virtual environment like by EVE-NG - you need to ensure your VyOS NIC is set to use the e1000 driver. Using the - default ``virtio-net-pci`` or the ``vmxnet3`` driver will not work. ICMP - messages will not be properly processed. They are visible on the virtual wire - but will not make it fully up the networking stack. - - You can check your NIC driver by issuing :opcmd:`show interfaces ethernet - eth0 physical | grep -i driver` - -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 - -Arista EOS -========== - -When utilizing VyOS in an environment with Arista gear you can use this blue -print as an initial setup to get an LACP bond / port-channel operational between -those two devices. - -Lets assume the following topology: - -.. figure:: /_static/images/vyos_arista_bond_lacp.png - :alt: VyOS Arista EOS setup - -**R1** - - .. code-block:: none - - interfaces { - bonding bond10 { - hash-policy layer3+4 - member { - interface eth1 - interface eth2 - } - mode 802.3ad - vif 100 { - address 192.0.2.1/30 - address 2001:db8::1/64 - } - } - -**R2** - - .. code-block:: none - - interfaces { - bonding bond10 { - hash-policy layer3+4 - member { - interface eth1 - interface eth2 - } - mode 802.3ad - vif 100 { - address 192.0.2.2/30 - address 2001:db8::2/64 - } - } - -**SW1** - - .. code-block:: none - - ! - vlan 100 - name FOO - ! - interface Port-Channel10 - switchport trunk allowed vlan 100 - switchport mode trunk - spanning-tree portfast - ! - interface Port-Channel20 - switchport mode trunk - no spanning-tree portfast auto - spanning-tree portfast network - ! - interface Ethernet1 - channel-group 10 mode active - ! - interface Ethernet2 - channel-group 10 mode active - ! - interface Ethernet3 - channel-group 20 mode active - ! - interface Ethernet4 - channel-group 20 mode active - ! - -**SW2** - - .. code-block:: none - - ! - vlan 100 - name FOO - ! - interface Port-Channel10 - switchport trunk allowed vlan 100 - switchport mode trunk - spanning-tree portfast - ! - interface Port-Channel20 - switchport mode trunk - no spanning-tree portfast auto - spanning-tree portfast network - ! - interface Ethernet1 - channel-group 10 mode active - ! - interface Ethernet2 - channel-group 10 mode active - ! - interface Ethernet3 - channel-group 20 mode active - ! - interface Ethernet4 - channel-group 20 mode active - ! - -.. note:: When using EVE-NG to lab this environment ensure you are using e1000 - as the desired driver for your VyOS network interfaces. When using the - regular virtio network driver no LACP PDUs will be sent by VyOS thus the - port-channel will never become active! - -********* -Operation -********* - -.. opcmd:: show interfaces bonding - - Show brief interface information. - - .. 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 - - -.. opcmd:: show interfaces bonding <interface> - - Show detailed information on given `<interface>` - - .. code-block:: none - - vyos@vyos:~$ show interfaces bonding bond5 - bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000 - link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff - inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative - 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 - 0 0 0 0 0 0 - -.. opcmd:: show interfaces bonding <interface> detail - - Show detailed information about the underlaying physical links on given - bond `<interface>`. - - .. code-block:: none - - vyos@vyos:~$ show interfaces bonding bond5 detail - Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) - - Bonding Mode: IEEE 802.3ad Dynamic link aggregation - Transmit Hash Policy: layer2 (0) - MII Status: down - MII Polling Interval (ms): 100 - Up Delay (ms): 0 - Down Delay (ms): 0 - - 802.3ad info - LACP rate: slow - Min links: 0 - Aggregator selection policy (ad_select): stable - - Slave Interface: eth1 - MII Status: down - Speed: Unknown - Duplex: Unknown - Link Failure Count: 0 - Permanent HW addr: 00:50:56:bf:ef:aa - Slave queue ID: 0 - Aggregator ID: 1 - Actor Churn State: churned - Partner Churn State: churned - Actor Churned Count: 1 - Partner Churned Count: 1 - - Slave Interface: eth2 - MII Status: down - Speed: Unknown - Duplex: Unknown - Link Failure Count: 0 - Permanent HW addr: 00:50:56:bf:19:26 - Slave queue ID: 0 - Aggregator ID: 2 - Actor Churn State: churned - Partner Churn State: churned - Actor Churned Count: 1 - Partner Churned Count: 1 diff --git a/docs/configuration/interfaces/rst-bridge.rst b/docs/configuration/interfaces/rst-bridge.rst deleted file mode 100644 index e69a6e26..00000000 --- a/docs/configuration/interfaces/rst-bridge.rst +++ /dev/null @@ -1,339 +0,0 @@ -:lastproofread: 2021-06-30 - -.. _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 -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: bridge - :var1: br0 - -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 optimum - 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. - -Bridge Options -============== - -.. cfgcmd:: set interfaces bridge <interface> aging <time> - - MAC address aging `<time`> in seconds (default: 300). - -.. cfgcmd:: set interfaces bridge <interface> max-age <time> - - Bridge maximum aging `<time>` in seconds (default: 20). - - If an another bridge in the spanning tree does not send out a hello - packet for a long period of time, it is assumed to be dead. - -.. cfgcmd:: set interfaces bridge <interface> igmp querier - - Enable IGMP and MLD querier. - -.. cfgcmd:: set interfaces bridge <interface> igmp snooping - - Enable IGMP and MLD snooping. - -.. _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). - - The 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. - -VLAN -==== - -Enable VLAN-Aware Bridge ------------------------- - -.. cfgcmd:: set interfaces bridge <interface> enable-vlan - - To activate the VLAN aware bridge, you must activate this setting to use VLAN - settings for the bridge - -.. cfgcmd:: set interfaces bridge <interface> protocol <802.1ad|802.1q> - - Define used ethertype of bridge interface. - - Ethertype ``0x8100`` is used for ``802.1q`` and ethertype ``0x88a8`` is used - for ``802.1ad``. - - The default is ``802.1q``. - -VLAN Options ------------- - -.. note:: It is not valid to use the `vif 1` option for VLAN aware bridges - because VLAN aware bridges assume that all unlabeled packets belong to - the default VLAN 1 member and that the VLAN ID of the bridge's parent - interface is always 1 - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: bridge - :var1: br0 - -.. cfgcmd:: set interfaces bridge <interface> member interface <member> - native-vlan <vlan-id> - - Set the native VLAN ID flag of the interface. When a data packet without a - VLAN tag enters the port, the data packet will be forced to add a tag of a - specific vlan id. When the vlan id flag flows out, the tag of the vlan id - will be stripped - - Example: Set `eth0` member port to be native VLAN 2 - - .. code-block:: none - - set interfaces bridge br1 member interface eth0 native-vlan 2 - -.. cfgcmd:: set interfaces bridge <interface> member interface <member> - allowed-vlan <vlan-id> - - Allows specific VLAN IDs to pass through the bridge member interface. This - can either be an individual VLAN id or a range of VLAN ids delimited by a - hyphen. - - Example: Set `eth0` member port to be allowed VLAN 4 - - .. code-block:: none - - set interfaces bridge br1 member interface eth0 allowed-vlan 4 - - Example: Set `eth0` member port to be allowed VLAN 6-8 - - .. code-block:: none - - set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 - -Port Mirror (SPAN) -================== -.. cmdinclude:: ../../_include/interface-mirror.txt - :var0: bridge - :var1: br1 - :var2: eth3 - -******** -Examples -******** - -Create a basic bridge -===================== - -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 - - -Using VLAN aware Bridge -======================= - -An example of creating a VLAN-aware bridge is as follows: - -* A bridge named `br100` -* The member interface `eth1` is a trunk that allows VLAN 10 to pass -* VLAN 10 on member interface `eth2` (ACCESS mode) -* Enable STP -* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 - -.. code-block:: none - - set interfaces bridge br100 enable-vlan - set interfaces bridge br100 member interface eth1 allowed-vlan 10 - set interfaces bridge br100 member interface eth2 native-vlan 10 - set interfaces bridge br100 vif 10 address 192.0.2.1/24 - set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 - set interfaces bridge br100 stp - -This results in the active configuration: - -.. code-block:: none - - vyos@vyos# show interfaces bridge br100 - enable-vlan - member { - interface eth1 { - allowed-vlan 10 - } - interface eth2 { - native-vlan 10 - } - } - stp - vif 10 { - address 192.0.2.1/24 - address 2001:db8::ffff/64 - } - - -Using the operation mode command to view Bridge Information -=========================================================== - -.. opcmd:: show bridge - - The `show bridge` operational command can be used to display - configured bridges: - - .. code-block:: none - - vyos@vyos:~$ show bridge - 3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding - priority 32 cost 100 - 4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding - priority 32 cost 100 - -.. opcmd:: show bridge <name> fdb - - Show bridge `<name>` fdb displays the current forwarding table: - - .. code-block:: none - - vyos@vyos:~$ show bridge br0 fdb - 50:00:00:08:00:01 dev eth1 vlan 20 master br0 permanent - 50:00:00:08:00:01 dev eth1 vlan 10 master br0 permanent - 50:00:00:08:00:01 dev eth1 master br0 permanent - 33:33:00:00:00:01 dev eth1 self permanent - 33:33:00:00:00:02 dev eth1 self permanent - 01:00:5e:00:00:01 dev eth1 self permanent - 50:00:00:08:00:02 dev eth2 vlan 20 master br0 permanent - 50:00:00:08:00:02 dev eth2 vlan 10 master br0 permanent - 50:00:00:08:00:02 dev eth2 master br0 permanent - 33:33:00:00:00:01 dev eth2 self permanent - 33:33:00:00:00:02 dev eth2 self permanent - 01:00:5e:00:00:01 dev eth2 self permanent - 33:33:00:00:00:01 dev br0 self permanent - 33:33:00:00:00:02 dev br0 self permanent - 33:33:ff:08:00:01 dev br0 self permanent - 01:00:5e:00:00:6a dev br0 self permanent - 33:33:00:00:00:6a dev br0 self permanent - 01:00:5e:00:00:01 dev br0 self permanent - 33:33:ff:00:00:00 dev br0 self permanent - -.. opcmd:: show bridge <name> mdb - - Show bridge `<name>` mdb displays the current multicast group membership - table.The table is populated by IGMP and MLD snooping in the bridge driver - automatically. - - .. code-block:: none - - vyos@vyos:~$ show bridge br0 mdb - dev br0 port br0 grp ff02::1:ff00:0 temp vid 1 - dev br0 port br0 grp ff02::2 temp vid 1 - dev br0 port br0 grp ff02::1:ff08:1 temp vid 1 - dev br0 port br0 grp ff02::6a temp vid 1 - -.. 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/configuration/interfaces/rst-dummy.rst b/docs/configuration/interfaces/rst-dummy.rst deleted file mode 100644 index 945361c2..00000000 --- a/docs/configuration/interfaces/rst-dummy.rst +++ /dev/null @@ -1,84 +0,0 @@ -:lastproofread: 2023-01-20 - -.. _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:: On systems with multiple redundant uplinks and routes, - it's a good idea to use a dedicated address for management and dynamic routing protocols. - However, assigning that address to a physical link is risky: - if that link goes down, that address will become inaccessible. - A common solution is to assign the management address to a loopback or a dummy interface - and advertise that address via all physical links, so that it's reachable - through any of them. Since in Linux-based systems, there can be only one loopback interface, - it's better to use a dummy interface for that purpose, since they can be added, removed, - and taken up and down independently. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address.txt - :var0: dummy - :var1: dum0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: dummy - :var1: dum0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: dummy - :var1: dum0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: dummy - :var1: dum0 - -********* -Operation -********* - -.. opcmd:: show interfaces dummy - - Show brief interface 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 dummy dum0 - 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/configuration/interfaces/rst-ethernet.rst b/docs/configuration/interfaces/rst-ethernet.rst deleted file mode 100644 index 30a13b5b..00000000 --- a/docs/configuration/interfaces/rst-ethernet.rst +++ /dev/null @@ -1,305 +0,0 @@ -:lastproofread: 2023-01-20 - -.. _ethernet-interface: - -######## -Ethernet -######## - -This will be the most widely used interface on a router carrying traffic to the -real world. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: ethernet - :var1: eth0 - -Ethernet options -================ - -.. 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`. - -.. cfgcmd:: set interface ethernet <interface> ring-buffer rx <value> -.. cfgcmd:: set interface ethernet <interface> ring-buffer tx <value> - - Configures the ring buffer size of the interface. - - The supported values for a specific interface can be obtained - with: `ethtool -g <interface>` - - -Offloading ----------- - -.. cfgcmd:: set interfaces ethernet <interface> offload <gro | gso | lro | rps | - sg | tso> - - Enable different types of hardware offloading on the given NIC. - - :abbr:`LRO (Large Receive Offload)` is a technique designed to boost the - efficiency of how your computer's network interface card (NIC) processes - incoming network traffic. Typically, network data arrives in smaller chunks - called packets. Processing each packet individually consumes CPU (central - processing unit) resources. Lots of small packets can lead to a performance - bottleneck. Instead of handing the CPU each packet as it comes in, LRO - instructs the NIC to combine multiple incoming packets into a single, larger - packet. This larger packet is then passed to the CPU for processing. - - .. note:: Under some circumstances, LRO is known to modify the packet headers - of forwarded traffic, which breaks the end-to-end principle of computer - networking. LRO is also only able to offload TCP segments encapsulated in - IPv4 packets. Due to these limitations, it is recommended to use GRO - (Generic Receive Offload) where possible. More information on the - limitations of LRO can be found here: https://lwn.net/Articles/358910/ - - :abbr:`GSO (Generic Segmentation Offload)` is a pure software offload that is - meant to deal with cases where device drivers cannot perform the offloads - described above. What occurs in GSO is that a given skbuff will have its data - broken out over multiple skbuffs that have been resized to match the MSS - provided via skb_shinfo()->gso_size. - - Before enabling any hardware segmentation offload a corresponding software - offload is required in GSO. Otherwise it becomes possible for a frame to be - re-routed between devices and end up being unable to be transmitted. - - :abbr:`GRO (Generic receive offload)` is the complement to GSO. Ideally any - frame assembled by GRO should be segmented to create an identical sequence of - frames using GSO, and any sequence of frames segmented by GSO should be able - to be reassembled back to the original by GRO. The only exception to this is - IPv4 ID in the case that the DF bit is set for a given IP header. If the - value of the IPv4 ID is not sequentially incrementing it will be altered so - that it is when a frame assembled via GRO is segmented via GSO. - - :abbr:`RPS (Receive Packet Steering)` is logically a software implementation - of :abbr:`RSS (Receive Side Scaling)`. Being in software, it is necessarily - called later in the datapath. Whereas RSS selects the queue and hence CPU that - will run the hardware interrupt handler, RPS selects the CPU to perform - protocol processing above the interrupt handler. This is accomplished by - placing the packet on the desired CPU's backlog queue and waking up the CPU - for processing. RPS has some advantages over RSS: - - - it can be used with any NIC - - software filters can easily be added to hash over new protocols - - it does not increase hardware device interrupt rate, although it does - introduce inter-processor interrupts (IPIs) - - .. note:: In order to use TSO/LRO with VMXNET3 adapters, the SG offloading - option must also be enabled. - -Authentication (EAPoL) ----------------------- - -.. cmdinclude:: /_include/interface-eapol.txt - :var0: ethernet - :var1: eth0 - -EVPN Multihoming ----------------- - -Uplink/Core tracking. - -.. cmdinclude:: /_include/interface-evpn-uplink.txt - :var0: ethernet - :var1: eth0 - -VLAN -==== - -Regular VLANs (802.1q) ----------------------- - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: ethernet - :var1: eth0 - -QinQ (802.1ad) --------------- - -.. cmdinclude:: /_include/interface-vlan-8021ad.txt - :var0: ethernet - :var1: eth0 - -Port Mirror (SPAN) -================== -.. cmdinclude:: ../../_include/interface-mirror.txt - :var0: ethernet - :var1: eth1 - :var2: eth3 - -********* -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 - -.. stop_vyoslinter - -.. 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 - -.. start_vyoslinter - -.. 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/configuration/interfaces/rst-geneve.rst b/docs/configuration/interfaces/rst-geneve.rst deleted file mode 100644 index 1e8b8096..00000000 --- a/docs/configuration/interfaces/rst-geneve.rst +++ /dev/null @@ -1,87 +0,0 @@ -:lastproofread: 2023-01-20 - -.. _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 -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-mac.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-ip.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: geneve - :var1: gnv0 - -GENEVE options -============== - -.. 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. diff --git a/docs/configuration/interfaces/rst-index.rst b/docs/configuration/interfaces/rst-index.rst deleted file mode 100644 index 0f02d1e3..00000000 --- a/docs/configuration/interfaces/rst-index.rst +++ /dev/null @@ -1,30 +0,0 @@ -########## -Interfaces -########## - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - bonding - bridge - dummy - ethernet - geneve - l2tpv3 - loopback - macsec - openvpn - wireguard - pppoe - pseudo-ethernet - sstp-client - tunnel - virtual-ethernet - vti - vxlan - wireless - wwan - - diff --git a/docs/configuration/interfaces/rst-l2tpv3.rst b/docs/configuration/interfaces/rst-l2tpv3.rst deleted file mode 100644 index 4fa47199..00000000 --- a/docs/configuration/interfaces/rst-l2tpv3.rst +++ /dev/null @@ -1,191 +0,0 @@ -:lastproofread: 2023-01-20 - -.. include:: /_include/need_improvement.txt - -.. _l2tpv3-interface: - -###### -L2TPv3 -###### - -Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that -can be used as an alternative protocol to :ref:`mpls` for encapsulation of -multiprotocol Layer 2 communications traffic over IP networks. Like L2TP, -L2TPv3 provides a pseudo-wire service but is scaled to fit carrier requirements. - -L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version -of the same concept, with much of the same benefit achieved at a fraction of the -effort, at the cost of losing some technical features considered less important -in the market. - -In the case of L2TPv3, the features lost are teletraffic engineering features -considered important in MPLS. However, there is no reason these features could -not be re-engineered in or on top of L2TPv3 in later products. - -The protocol overhead of L2TPv3 is also significantly bigger than MPLS. - -L2TPv3 is described in :rfc:`3931`. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-without-dhcp.txt - :var0: l2tpv3 - :var1: l2tpeth0 - -L2TPv3 options -============== - -.. cfgcmd:: set interfaces l2tpv3 <interface> encapsulation <udp | ip> - - Set the encapsulation type of the tunnel. Valid values for encapsulation are: - udp, ip. - - This defaults to UDP - -.. cfgcmd:: set interfaces l2tpv3 <interface> source-address <address> - - Set the IP address of the local interface to be used for the tunnel. - - This address must be the address of a local interface. It may be specified as - an IPv4 address or an IPv6 address. - -.. cfgcmd:: set interfaces l2tpv3 <interface> remote <address> - - Set the IP address of the remote peer. It may be specified as - an IPv4 address or an IPv6 address. - -.. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id> - - Set the session id, which is a 32-bit integer value. Uniquely identifies the - session being created. The value used must match the peer_session_id value - being used at the peer. - -.. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id> - - Set the peer-session-id, which is a 32-bit integer value assigned to the - session by the peer. The value used must match the session_id value being - used at the peer. - -.. cfgcmd:: set interfaces l2tpv3 <interface> tunnel-id <id> - - Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the - tunnel into which the session will be created. - -.. cfgcmd:: set interfaces l2tpv3 <interface> peer-tunnel-id <id> - - Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the - tunnel into which the session will be created. - -******* -Example -******* - -Over IP -======= - -.. code-block:: none - - # show interfaces l2tpv3 - l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - encapsulation ip - source-address 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote 203.0.113.24 - session-id 100 - tunnel-id 200 - } - -The inverse configuration has to be applied to the remote side. - -Over UDP -======== - -UDP mode works better with NAT: - -* Set source-address 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 - source-address 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote 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 authentication psk <pre-shared-name> id '%any' - set vpn ipsec authentication psk <pre-shared-name> secret <pre-shared-key> - set vpn ipsec interface <VPN-interface> - 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 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 <connection-name> authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer <connection-name> connection-type 'initiate' - set vpn ipsec site-to-site peer <connection-name> ike-group 'test-IKE-1' - set vpn ipsec site-to-site peer <connection-name> ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer <connection-name> local-address <local-ip> - set vpn ipsec site-to-site peer <connection-name> tunnel 1 esp-group 'test-ESP-1' - set vpn ipsec site-to-site peer <connection-name> 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 source-address <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 <peer-ip> - set interfaces l2tpv3 l2tpeth0 session-id '110' - set interfaces l2tpv3 l2tpeth0 source-port '5000' - set interfaces l2tpv3 l2tpeth0 tunnel-id '10' diff --git a/docs/configuration/interfaces/rst-loopback.rst b/docs/configuration/interfaces/rst-loopback.rst deleted file mode 100644 index b5fbdf83..00000000 --- a/docs/configuration/interfaces/rst-loopback.rst +++ /dev/null @@ -1,73 +0,0 @@ -:lastproofread: 2023-01-20 - -.. _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 loopback 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:`routing-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 -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address.txt - :var0: loopback - :var1: lo - -.. cmdinclude:: /_include/interface-description.txt - :var0: loopback - :var1: lo - -********* -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 the given loopback interface `lo`. - - .. code-block:: none - - vyos@vyos:~$ show interfaces loopback lo - 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/configuration/interfaces/rst-macsec.rst b/docs/configuration/interfaces/rst-macsec.rst deleted file mode 100644 index 1ab7f361..00000000 --- a/docs/configuration/interfaces/rst-macsec.rst +++ /dev/null @@ -1,285 +0,0 @@ -:lastproofread: 2023-01-20 - -.. _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 -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: macsec - :var1: macsec0 - -MACsec options -============== - -.. cfgcmd:: set interfaces macsec <interface> security cipher <gcm-aes-128|gcm-aes-256> - - Select cipher suite used for cryptographic operations. This setting is - mandatory. - -.. 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 interface will now be authenticated/encrypted. - -Static Keys ------------ -Static :abbr:`SAK (Secure Authentication Key)` mode can be configured manually on each -device wishing to use MACsec. Keys must be set statically on all devices for traffic -to flow properly. Key rotation is dependent on the administrator updating all keys -manually across connected devices. Static SAK mode can not be used with MKA. - -.. cfgcmd:: set interfaces macsec <interface> security static key <key> - - Set the device's transmit (TX) key. This key must be a hex string that is 16-bytes - (GCM-AES-128) or 32-bytes (GCM-AES-256). - -.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> mac <mac address> - - Set the peer's MAC address - -.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> key <key> - - Set the peer's key used to receive (RX) traffic - -.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> disable - - Disable the peer configuration - -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 configuring MACsec with - a pre-shared key using a :abbr:`CAK (MACsec connectivity association key)` and - :abbr:`CKN (MACsec connectivity association name)` pair. - -.. cfgcmd:: set interfaces macsec <interface> security mka ckn <key> - - :abbr:`CKN (MACsec connectivity association name)` key - -.. 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 <gcm-aes-128|gcm-aes-256> - - Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key 128 or 256 bits. - - .. code-block:: none - - vyos@vyos:~$ generate macsec mka cak gcm-aes-128 - 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.( - -**R1 Static Key** - -.. 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 static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02 - set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 source-interface 'eth1' - -**R2 Static Key** - -.. 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 static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:01 - set interfaces macsec macsec1 security static peer R2 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 source-interface 'eth1' - -*************** -MACsec over wan -*************** - -MACsec is an interesting alternative to existing tunneling solutions that -protects layer 2 by performing integrity, origin authentication, and optionally -encryption. The typical use case is to use MACsec between hosts and access -switches, between two hosts, or between two switches. in this example below, -we use VXLAN and MACsec to secure the tunnel. - -**R1 MACsec01** - -.. 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 static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02' - set interfaces macsec macsec1 source-interface 'vxlan1' - set interfaces vxlan vxlan1 mac '00:11:22:33:44:01' - set interfaces vxlan vxlan1 remote '10.1.3.3' - set interfaces vxlan vxlan1 source-address '172.16.100.1' - set interfaces vxlan vxlan1 vni '10' - set protocols static route 10.1.3.3/32 next-hop 172.16.100.2 - -**R2 MACsec02** - -.. 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 static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01' - set interfaces macsec macsec1 source-interface 'vxlan1' - set interfaces vxlan vxlan1 mac '00:11:22:33:44:02' - set interfaces vxlan vxlan1 remote '10.1.2.2' - set interfaces vxlan vxlan1 source-address '172.16.100.2' - set interfaces vxlan vxlan1 vni '10' - set protocols static route 10.1.2.2/32 next-hop 172.16.100.1 diff --git a/docs/configuration/interfaces/rst-openvpn.rst b/docs/configuration/interfaces/rst-openvpn.rst deleted file mode 100644 index 76d44ed5..00000000 --- a/docs/configuration/interfaces/rst-openvpn.rst +++ /dev/null @@ -1,867 +0,0 @@ -:lastproofread: 2021-07-05 - -.. _openvpn: - -####### -OpenVPN -####### - -Traditionally hardware routers implement IPsec exclusively due to relative -ease of implementing it in hardware and insufficient CPU power for doing -encryption in software. Since VyOS is a software router, this is less of a -concern. OpenVPN has been widely used on UNIX platform for a long time and is -a popular option for remote access VPN, though it's also capable of -site-to-site connections. - -Advantages of OpenVPN are: - -* It uses a single TCP or UDP connection and does not rely on packet source - addresses, so it will work even through a double NAT: perfect for public - hotspots and such - -* It's easy to setup and offers very flexible split tunneling - -* There's a variety of client GUI frontends for any platform - -Disadvantages are: - -* It's slower than IPsec due to higher protocol overhead and the fact it runs - in user mode while IPsec, on Linux, is in kernel mode - -* None of the operating systems have client software installed by default - -In the VyOS CLI, a key point often overlooked is that rather than being -configured using the `set vpn` stanza, OpenVPN is configured as a network -interface using `set interfaces openvpn`. - -************ -Site-to-Site -************ - -.. figure:: /_static/images/openvpn_site2site_diagram.jpg - -OpenVPN is popular for client-server setups, but its site-to-site mode -remains a relatively obscure feature, and many router appliances -still don't support it. However, it's very useful for quickly setting up -tunnels between routers. - -As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. - -The pre-shared key mode is deprecated and will be removed from future OpenVPN versions, -so VyOS will have to remove support for that option as well. The reason is that using pre-shared keys -is significantly less secure than using TLS. - -We'll configure OpenVPN using self-signed certificates, and then discuss the legacy -pre-shared key mode. - -In both cases, we will use the following settings: - -* The public IP address of the local side of the VPN will be 198.51.100.10. -* The public IP address of the remote side of the VPN will be 203.0.113.11. -* The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote. -* The local site will have a subnet of 10.0.0.0/16. -* The remote site will have a subnet of 10.1.0.0/16. -* The official port for OpenVPN is 1194, which we reserve for client VPN; we - will use 1195 for site-to-site VPN. -* The ``persistent-tunnel`` directive will allow us to configure tunnel-related - attributes, such as firewall policy as we would on any normal network - interface. -* If known, the IP of the remote router can be configured using the - ``remote-host`` directive; if unknown, it can be omitted. We will assume a - dynamic IP for our remote router. - -Setting up certificates -======================= - -Setting up a full-blown PKI with a CA certificate would arguably defeat the purpose -of site-to-site OpenVPN, since its main goal is supposed to be configuration simplicity, -compared to server setups that need to support multiple clients. - -However, since VyOS 1.4, it is possible to verify self-signed certificates using -certificate fingerprints. - -On both sides, you need to generate a self-signed certificate, preferrably using the "ec" (elliptic curve) type. -You can generate them by executing command ``run generate pki certificate self-signed install <name>`` in the configuration mode. -Once the command is complete, it will add the certificate to the configuration session, to the ``pki`` subtree. -You can then review the proposed changes and commit them. - -.. code-block:: none - - vyos@vyos# run generate pki certificate self-signed install openvpn-local - Enter private key type: [rsa, dsa, ec] (Default: rsa) ec - Enter private key bits: (Default: 256) - Enter country code: (Default: GB) - Enter state: (Default: Some-State) - Enter locality: (Default: Some-City) - Enter organization name: (Default: VyOS) - Enter common name: (Default: vyos.io) - Do you want to configure Subject Alternative Names? [y/N] - Enter how many days certificate will be valid: (Default: 365) - Enter certificate type: (client, server) (Default: server) - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - - vyos@vyos# compare - [pki] - + certificate openvpn-local { - + certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/ uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" - + private { - + key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" - + } - + } - - [edit] - - vyos@vyos# commit - -You do **not** need to copy the certificate to the other router. Instead, you need to retrieve its SHA-256 fingerprint. -OpenVPN only supports SHA-256 fingerprints at the moment, so you need to use the following command: - -.. code-block:: none - - vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 - 5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 - -Note: certificate names don't matter, we use 'openvpn-local' and 'openvpn-remote' but they can be arbitrary. - -Repeat the procedure on the other router. - -Setting up OpenVPN -================== - -Local Configuration: - -.. code-block:: none - - Configure the tunnel: - - set interfaces openvpn vtun1 mode site-to-site - set interfaces openvpn vtun1 protocol udp - set interfaces openvpn vtun1 persistent-tunnel - set interfaces openvpn vtun1 remote-host '203.0.113.11' # Public IP of the other side - set interfaces openvpn vtun1 local-port '1195' - set interfaces openvpn vtun1 remote-port '1195' - set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface - set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface - set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate - set interfaces openvpn vtun1 tls peer-fingerprint <remote cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 - on the remote rout - -Remote Configuration: - -.. code-block:: none - - set interfaces openvpn vtun1 mode site-to-site - set interfaces openvpn vtun1 protocol udp - set interfaces openvpn vtun1 persistent-tunnel - set interfaces openvpn vtun1 remote-host '198.51.100.10' # Pub IP of other site - set interfaces openvpn vtun1 local-port '1195' - set interfaces openvpn vtun1 remote-port '1195' - set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface - set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface - set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate - set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 - on the local router - -Pre-shared keys -=============== - -Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use pre-shared keys. -That option is still available but it is deprecated and will be removed in the future. -However, if you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, -you need to still need to know how to use it. - -First, you need to generate a key by running ``run generate pki openvpn shared-secret install <name>`` from configuration mode. -You can use any name, we will use ``s2s``. - -.. code-block:: none - - vyos@local# run generate pki openvpn shared-secret install s2s - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - vyos@local# compare - [pki openvpn shared-secret] - + s2s { - + key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" - + version "1" - + } - - [edit] - - vyos@local# commit - [edit] - -Then you need to install the key on the remote router: - -.. code-block:: none - - vyos@remote# set pki openvpn shared-secret s2s key <generated key string> - -Then you need to set the key in your OpenVPN interface settings: - -.. code-block:: none - - set interfaces openvpn vtun1 shared-secret-key s2s - -Firewall Exceptions -=================== - -For the OpenVPN traffic to pass through the WAN interface, you must create a -firewall exception. - -.. code-block:: none - - set firewall name OUTSIDE_LOCAL rule 10 action accept - set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related' - set firewall name OUTSIDE_LOCAL rule 10 state established enable - set firewall name OUTSIDE_LOCAL rule 10 state related enable - set firewall name OUTSIDE_LOCAL rule 20 action accept - set firewall name OUTSIDE_LOCAL rule 20 description OpenVPN_IN - set firewall name OUTSIDE_LOCAL rule 20 destination port 1195 - set firewall name OUTSIDE_LOCAL rule 20 log enable - set firewall name OUTSIDE_LOCAL rule 20 protocol udp - set firewall name OUTSIDE_LOCAL rule 20 source - -You should also ensure that the OUTISDE_LOCAL firewall group is applied to the -WAN interface and a direction (local). - -.. code-block:: none - - set firewall interface eth0 local name 'OUTSIDE-LOCAL' - - -Static Routing: - -Static routes can be configured referencing the tunnel interface; for example, -the local router will use a network of 10.0.0.0/16, while the remote has a -network of 10.1.0.0/16: - -Local Configuration: - -.. code-block:: none - - set protocols static route 10.1.0.0/16 interface vtun1 - -Remote Configuration: - -.. code-block:: none - - set protocols static route 10.0.0.0/16 interface vtun1 - -The configurations above will default to using 256-bit AES in GCM mode -for encryption (if both sides support NCP) and SHA-1 for HMAC authentication. -SHA-1 is considered weak, but other hashing algorithms are available, as are -encryption algorithms: - -For Encryption: - -This sets the cipher when NCP (Negotiable Crypto Parameters) is disabled or -OpenVPN version < 2.4.0. - -.. code-block:: none - - vyos@vyos# set interfaces openvpn vtun1 encryption cipher - Possible completions: - des DES algorithm - 3des DES algorithm with triple encryption - bf128 Blowfish algorithm with 128-bit key - bf256 Blowfish algorithm with 256-bit key - aes128 AES algorithm with 128-bit key CBC - aes128gcm AES algorithm with 128-bit key GCM - aes192 AES algorithm with 192-bit key CBC - aes192gcm AES algorithm with 192-bit key GCM - aes256 AES algorithm with 256-bit key CBC - aes256gcm AES algorithm with 256-bit key GCM - -This sets the accepted ciphers to use when version => 2.4.0 and NCP is -enabled (which is the default). Default NCP cipher for versions >= 2.4.0 is -aes256gcm. The first cipher in this list is what server pushes to clients. - -.. code-block:: none - - vyos@vyos# set int open vtun0 encryption ncp-ciphers - Possible completions: - des DES algorithm - 3des DES algorithm with triple encryption - aes128 AES algorithm with 128-bit key CBC - aes128gcm AES algorithm with 128-bit key GCM - aes192 AES algorithm with 192-bit key CBC - aes192gcm AES algorithm with 192-bit key GCM - aes256 AES algorithm with 256-bit key CBC - aes256gcm AES algorithm with 256-bit key GCM - -For Hashing: - -.. code-block:: none - - vyos@vyos# set interfaces openvpn vtun1 hash - Possible completions: - md5 MD5 algorithm - sha1 SHA-1 algorithm - sha256 SHA-256 algorithm - sha512 SHA-512 algorithm - -If you change the default encryption and hashing algorithms, be sure that the -local and remote ends have matching configurations, otherwise the tunnel will -not come up. - - -Firewall policy can also be applied to the tunnel interface for `local`, `in`, -and `out` directions and functions identically to ethernet interfaces. - -If making use of multiple tunnels, OpenVPN must have a way to distinguish -between different tunnels aside from the pre-shared-key. This is either by -referencing IP address or port number. One option is to dedicate a public IP -to each tunnel. Another option is to dedicate a port number to each tunnel -(e.g. 1195,1196,1197...). - -OpenVPN status can be verified using the `show openvpn` operational commands. -See the built-in help for a complete list of options. - -****** -Server -****** - -Multi-client server is the most popular OpenVPN mode on routers. It always uses -x.509 authentication and therefore requires a PKI setup. Refer this topic -:ref:`configuration/pki/index:pki` to generate a CA certificate, -a server certificate and key, a certificate revocation list, a Diffie-Hellman -key exchange parameters file. You do not need client certificates and keys for -the server setup. - -In this example we will use the most complicated case: a setup where each -client is a router that has its own subnet (think HQ and branch offices), since -simpler setups are subsets of it. - -Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and -all client subnets belong to 10.23.0.0/20. All clients need access to the -192.168.0.0/16 network. - -First we need to specify the basic settings. 1194/UDP is the default. The -``persistent-tunnel`` option is recommended, it prevents the TUN/TAP device from -closing on connection resets or daemon reloads. - -.. note:: Using **openvpn-option -reneg-sec** can be tricky. This option is - used to renegotiate data channel after n seconds. When used at both server - and client, the lower value will trigger the renegotiation. If you set it to - 0 on one side of the connection (to disable it), the chosen value on the - other side will determine when the renegotiation will occur. - -.. code-block:: none - - set interfaces openvpn vtun10 mode server - set interfaces openvpn vtun10 local-port 1194 - set interfaces openvpn vtun10 persistent-tunnel - set interfaces openvpn vtun10 protocol udp - -Then we need to generate, add and specify the names of the cryptographic materials. -Each of the install command should be applied to the configuration and commited -before using under the openvpn interface configuration. - -.. code-block:: none - - run generate pki ca install ca-1 # Follow the instructions to generate CA cert. - Configure mode commands to install: - set pki ca ca-1 certificate 'generated_cert_string' - set pki ca ca-1 private key 'generated_private_key' - - run generate pki certificate sign ca-1 install srv-1 # Follow the instructions to generate server cert. - Configure mode commands to install: - set pki certificate srv-1 certificate 'generated_server_cert' - set pki certificate srv-1 private key 'generated_private_key' - - run generate pki dh install dh-1 # Follow the instructions to generate set of - Diffie-Hellman parameters. - Generating parameters... - Configure mode commands to install DH parameters: - set pki dh dh-1 parameters 'generated_dh_params_set' - - set interfaces openvpn vtun10 tls ca-certificate ca-1 - set interfaces openvpn vtun10 tls certificate srv-1 - set interfaces openvpn vtun10 tls dh-params dh-1 - -Now we need to specify the server network settings. In all cases we need to -specify the subnet for client tunnel endpoints. Since we want clients to access -a specific network behind our router, we will use a push-route option for -installing that route on clients. - -.. code-block:: none - - set interfaces openvpn vtun10 server push-route 192.168.0.0/16 - set interfaces openvpn vtun10 server subnet 10.23.1.0/24 - -Since it's a HQ and branch offices setup, we will want all clients to have -fixed addresses and we will route traffic to specific subnets through them. We -need configuration for each client to achieve this. - -.. note:: Clients are identified by the CN field of their x.509 certificates, - in this example the CN is ``client0``: - -.. code-block:: none - - set interfaces openvpn vtun10 server client client0 ip 10.23.1.10 - set interfaces openvpn vtun10 server client client0 subnet 10.23.2.0/25 - -OpenVPN **will not** automatically create routes in the kernel for client -subnets when they connect and will only use client-subnet association -internally, so we need to create a route to the 10.23.0.0/20 network ourselves: - -.. code-block:: none - - set protocols static route 10.23.0.0/20 interface vtun10 - -Additionally, each client needs a copy of ca cert and its own client key and -cert files. The files are plaintext so they may be copied either manually from the CLI. -Client key and cert files should be signed with the proper ca cert and generated on the -server side. - -HQ's router requires the following steps to generate crypto materials for the Branch 1: - -.. code-block:: none - - run generate pki certificate sign ca-1 install branch-1 # Follow the instructions to generate client - cert for Branch 1 - Configure mode commands to install: - -Branch 1's router might have the following lines: - -.. code-block:: none - - set pki ca ca-1 certificate 'generated_cert_string' # CA cert generated on HQ router - set pki certificate branch-1 certificate 'generated_branch_cert' # Client cert generated and signed on HQ router - set pki certificate branch-1 private key 'generated_private_key' # Client cert key generated on HQ router - - set interfaces openvpn vtun10 tls ca-cert ca-1 - set interfaces openvpn vtun10 tls certificate branch-1 - - -Client Authentication -===================== - -LDAP ----- - -Enterprise installations usually ship a kind of directory service which is used -to have a single password store for all employees. VyOS and OpenVPN support -using LDAP/AD as single user backend. - -Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is -shipped with every VyOS installation. A dedicated configuration file is -required. It is best practise to store it in ``/config`` to survive image -updates - -.. code-block:: none - - set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" - -The required config file may look like this: - -.. code-block:: none - - <LDAP> - # LDAP server URL - URL ldap://ldap.example.com - # Bind DN (If your LDAP server doesn't support anonymous binds) - BindDN cn=LDAPUser,dc=example,dc=com - # Bind Password password - Password S3cr3t - # Network timeout (in seconds) - Timeout 15 - </LDAP> - - <Authorization> - # Base DN - BaseDN "ou=people,dc=example,dc=com" - # User Search Filter - SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" - # Require Group Membership - allow all users - RequireGroup false - </Authorization> - -Active Directory -^^^^^^^^^^^^^^^^ - -Despite the fact that AD is a superset of LDAP - -.. code-block:: none - - <LDAP> - # LDAP server URL - URL ldap://dc01.example.com - # Bind DN (If your LDAP server doesn’t support anonymous binds) - BindDN CN=LDAPUser,DC=example,DC=com - # Bind Password - Password mysecretpassword - # Network timeout (in seconds) - Timeout 15 - # Enable Start TLS - TLSEnable no - # Follow LDAP Referrals (anonymously) - FollowReferrals no - </LDAP> - - <Authorization> - # Base DN - BaseDN "DC=example,DC=com" - # User Search Filter, user must be a member of the VPN AD group - SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" - # Require Group Membership - RequireGroup false # already handled by SearchFilter - <Group> - BaseDN "OU=Groups,DC=example,DC=com" - SearchFilter "(|(cn=VPN))" - MemberAttribute memberOf - </Group> - </Authorization> - -If you only want to check if the user account is enabled and can authenticate -(against the primary group) the following snipped is sufficient: - -.. code-block:: none - - <LDAP> - URL ldap://dc01.example.com - BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com - Password ThisIsTopSecret - Timeout 15 - TLSEnable no - FollowReferrals no - </LDAP> - - <Authorization> - BaseDN "DC=example,DC=com" - SearchFilter "sAMAccountName=%u" - RequireGroup false - </Authorization> - -A complete LDAP auth OpenVPN configuration could look like the following -example: - -.. code-block:: none - - vyos@vyos# show interfaces openvpn - openvpn vtun0 { - mode server - openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" - openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" - openvpn-option "--push redirect-gateway" - openvpn-option --duplicate-cn - openvpn-option "--verify-client-cert none" - openvpn-option --comp-lzo - openvpn-option --persist-key - openvpn-option --persist-tun - server { - domain-name example.com - max-connections 5 - name-server 203.0.113.0.10 - name-server 198.51.100.3 - subnet 172.18.100.128/29 - } - tls { - ca-certificate ca.crt - certificate server.crt - dh-params dh1024.pem - } - } - - -****** -Client -****** - -VyOS can not only act as an OpenVPN site-to-site or server for multiple clients. -You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client -connecting to a VyOS OpenVPN server or any other OpenVPN server. - -Given the following example we have one VyOS router acting as OpenVPN server -and another VyOS router acting as OpenVPN client. The server also pushes a -static client IP address to the OpenVPN client. Remember, clients are identified -using their CN attribute in the SSL certificate. - -.. _openvpn:client_server: - -Configuration -============= - -Server Side ------------ - -.. code-block:: none - - set interfaces openvpn vtun10 encryption cipher 'aes256' - set interfaces openvpn vtun10 hash 'sha512' - set interfaces openvpn vtun10 local-host '172.18.201.10' - set interfaces openvpn vtun10 local-port '1194' - set interfaces openvpn vtun10 mode 'server' - set interfaces openvpn vtun10 persistent-tunnel - set interfaces openvpn vtun10 protocol 'udp' - set interfaces openvpn vtun10 server client client1 ip '10.10.0.10' - set interfaces openvpn vtun10 server domain-name 'vyos.net' - set interfaces openvpn vtun10 server max-connections '250' - set interfaces openvpn vtun10 server name-server '172.16.254.30' - set interfaces openvpn vtun10 server subnet '10.10.0.0/24' - set interfaces openvpn vtun10 server topology 'subnet' - set interfaces openvpn vtun10 tls ca-cert ca-1 - set interfaces openvpn vtun10 tls certificate srv-1 - set interfaces openvpn vtun10 tls crypt-key srv-1 - set interfaces openvpn vtun10 tls dh-params dh-1 - set interfaces openvpn vtun10 use-lzo-compression - -.. _openvpn:client_client: - -Client Side ------------ - -.. code-block:: none - - set interfaces openvpn vtun10 encryption cipher 'aes256' - set interfaces openvpn vtun10 hash 'sha512' - set interfaces openvpn vtun10 mode 'client' - set interfaces openvpn vtun10 persistent-tunnel - set interfaces openvpn vtun10 protocol 'udp' - set interfaces openvpn vtun10 remote-host '172.18.201.10' - set interfaces openvpn vtun10 remote-port '1194' - set interfaces openvpn vtun10 tls ca-cert ca-1 - set interfaces openvpn vtun10 tls certificate client-1 - set interfaces openvpn vtun10 tls crypt-key client-1 - set interfaces openvpn vtun10 use-lzo-compression - -Options -======= - -We do not have CLI nodes for every single OpenVPN option. If an option is -missing, a feature request should be opened at Phabricator_ so all users can -benefit from it (see :ref:`issues_features`). - -If you are a hacker or want to try on your own we support passing raw OpenVPN -options to OpenVPN. - -.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'persistent-key' - -Will add ``persistent-key`` at the end of the generated OpenVPN configuration. -Please use this only as last resort - things might break and OpenVPN won't start -if you pass invalid options/syntax. - -.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option - 'push "keepalive 1 10"' - -Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. - -.. note:: Sometimes option lines in the generated OpenVPN configuration require - quotes. This is done through a hack on our config generator. You can pass - quotes using the ``"`` statement. - -Server bridge -============= - -In Ethernet bridging configurations, OpenVPN's server mode can be set as a -'bridge' where the VPN tunnel encapsulates entire Ethernet frames -(up to 1514 bytes) instead of just IP packets (up to 1500 bytes). This setup -allows clients to transmit Layer 2 frames through the OpenVPN tunnel. Below, -we outline a basic configuration to achieve this: - - -Server Side: - -.. code-block:: none - - set interfaces bridge br10 member interface eth1.10 - set interfaces bridge br10 member interface vtun10 - set interfaces openvpn vtun10 device-type 'tap' - set interfaces openvpn vtun10 encryption data-ciphers 'aes192' - set interfaces openvpn vtun10 hash 'sha256'' - set interfaces openvpn vtun10 local-host '172.18.201.10' - set interfaces openvpn vtun10 local-port '1194' - set interfaces openvpn vtun10 mode 'server' - set interfaces openvpn vtun10 server bridge gateway '10.10.0.1' - set interfaces openvpn vtun10 server bridge start '10.10.0.100' - set interfaces openvpn vtun10 server bridge stop '10.10.0.200' - set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' - set interfaces openvpn vtun10 server topology 'subnet' - set interfaces openvpn vtun10 tls ca-certificate 'ca-1' - set interfaces openvpn vtun10 tls certificate 'srv-1' - set interfaces openvpn vtun10 tls dh-params 'srv-1' - -Client Side : - -.. code-block:: none - - set interfaces openvpn vtun10 device-type 'tap' - set interfaces openvpn vtun10 encryption data-ciphers 'aes192' - set interfaces openvpn vtun10 hash 'sha256'' - set interfaces openvpn vtun10 mode 'client' - set interfaces openvpn vtun10 protocol 'udp' - set interfaces openvpn vtun10 remote-host '172.18.201.10' - set interfaces openvpn vtun10 remote-port '1194' - set interfaces openvpn vtun10 tls ca-certificate 'ca-1' - set interfaces openvpn vtun10 tls certificate 'client-1' - -*************************** -Multi-factor Authentication -*************************** - -VyOS supports multi-factor authentication (MFA) or two-factor authentication -using Time-based One-Time Password (TOTP). Compatible with Google Authenticator -software token, other software tokens. - -MFA TOTP options -================ - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp challenge <enable | disable> - - If set to enable, openvpn-otp will expect password as result of challenge/ - response protocol. - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp digits <1-65535> - - Configure number of digits to use for totp hash (default: 6) - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp drift <1-65535> - - Configure time drift in seconds (default: 0) - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp slop <1-65535> - - Configure maximum allowed clock slop in seconds (default: 180) - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp step <1-65535> - - Configure step value for totp in seconds (default: 30) - -Example -======= - -.. code-block:: none - - set interfaces openvpn vtun20 encryption cipher 'aes256' - set interfaces openvpn vtun20 hash 'sha512' - set interfaces openvpn vtun20 mode 'server' - set interfaces openvpn vtun20 persistent-tunnel - set interfaces openvpn vtun20 server client user1 - set interfaces openvpn vtun20 server mfa totp challenge 'disable' - set interfaces openvpn vtun20 server subnet '10.10.2.0/24' - set interfaces openvpn vtun20 server topology 'subnet' - set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' - set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' - set interfaces openvpn vtun20 tls dh-params 'dh-pem' - -For every client in the openvpn server configuration a totp secret is created. -To display the authentication information, use the command: - -.. cfgcmd:: show interfaces openvpn <interface> user <username> mfa <qrcode|secret|uri> - -An example: - -.. code-block:: none - - vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode - █████████████████████████████████████ - █████████████████████████████████████ - ████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ - ████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ - ████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ - ████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ - ████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ - ████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ - ████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ - ████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ - ████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ - ████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ - ████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ - ████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ - ████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ - ████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ - ████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ - █████████████████████████████████████ - █████████████████████████████████████ - -Use the QR code to add the user account in Google authenticator application and -on client side, use the OTP number as password. - - -********************************** -OpenVPN Data Channel Offload (DCO) -********************************** - -OpenVPN Data Channel Offload (DCO) enables significant performance enhancement -in encrypted OpenVPN data processing. By minimizing context switching for each -packet, DCO effectively reduces overhead. This optimization is achieved by -keeping most data handling tasks within the kernel, avoiding frequent switches -between kernel and user space for encryption and packet handling. - -As a result, the processing of each packet becomes more efficient, potentially -leveraging hardware encryption offloading support available in the kernel. - -.. note:: OpenVPN DCO is not full OpenVPN features supported , is currently - considered experimental. Furthermore, there are certain OpenVPN features and - use cases that remain incompatible with DCO. To get a comprehensive - understanding of the limitations associated with DCO, refer to the list of - known limitations in the documentation. - - https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features - - -Enabling OpenVPN DCO -==================== - -DCO support is a per-tunnel option and it is not automatically enabled by -default for new or upgraded tunnels. Existing tunnels will continue to function -as they have in the past. - -DCO can be enabled for both new and existing tunnels,VyOS adds an option in each -tunnel configuration where we can enable this function .The current best -practice is to create a new tunnel with DCO to minimize the chance of problems -with existing clients. - -.. cfgcmd:: set interfaces openvpn <name> offload dco - - Enable OpenVPN Data Channel Offload feature by loading the appropriate kernel - module. - - Disabled by default - no kernel module loaded. - - .. note:: Enable this feature causes an interface reset. - - -Troubleshooting -=============== - -VyOS provides some operational commands on OpenVPN. - -Check status ------------- - -The following commands let you check tunnel status. - -.. opcmd:: show openvpn client - - Use this command to check the tunnel status for OpenVPN client interfaces. - -.. opcmd:: show openvpn server - - Use this command to check the tunnel status for OpenVPN server interfaces. - -.. opcmd:: show openvpn site-to-site - - Use this command to check the tunnel status for OpenVPN site-to-site - interfaces. - - -Reset OpenVPN -------------- - -The following commands let you reset OpenVPN. - -.. opcmd:: reset openvpn client <text> - - Use this command to reset the specified OpenVPN client. - -.. opcmd:: reset openvpn interface <interface> - - Use this command to reset the OpenVPN process on a specific interface. - - - -.. include:: /_include/common-references.txt diff --git a/docs/configuration/interfaces/rst-pppoe.rst b/docs/configuration/interfaces/rst-pppoe.rst deleted file mode 100644 index 65081e1c..00000000 --- a/docs/configuration/interfaces/rst-pppoe.rst +++ /dev/null @@ -1,403 +0,0 @@ -:lastproofread: 2022-07-27 - -.. _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 because 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 Transceiver 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 -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-description.txt - :var0: pppoe - :var1: pppoe0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: pppoe - :var1: pppoe0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: pppoe - :var1: pppoe0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: pppoe - :var1: pppoe0 - -PPPoE options -============= - -.. 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 username <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 - - When set the interface is enabled for "dial-on-demand". - - Use this command to instruct the system to establish a PPPoE 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. - - 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> no-default-route - - Only request an address from the PPPoE server but do not install any default - route. - - Example: - - .. code-block:: none - - set interfaces pppoe pppoe0 no-default-route - - .. note:: This command got added in VyOS 1.4 and inverts the logic from the old - ``default-route`` CLI option. - -.. cfgcmd:: set interfaces pppoe <interface> default-route-distance <distance> - - Set the distance for the default gateway sent by the PPPoE server. - - Example: - - .. code-block:: none - - set interfaces pppoe pppoe0 default-route-distance 220 - -.. cfgcmd:: set interfaces pppoe <interface> mru <mru> - - Set the :abbr:`MRU (Maximum Receive Unit)` to `mru`. PPPd will ask the peer to - send packets of no more than `mru` bytes. The value of `mru` must be between 128 - and 16384. - - A value of 296 works well on very slow links (40 bytes for TCP/IP header + 256 - bytes of data). - - The default is 1492. - - .. note:: When using the IPv6 protocol, MRU must be at least 1280 bytes. - -.. 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> holdoff <time> - - Use this command to set re-dial delay time to be used with persist PPPoE - sessions. When the PPPoE session is terminated by peer, and on-demand - option is not set, the router will attempt to re-establish the PPPoE link. - - If this parameter is not set, the default holdoff time is 30 seconds. - -.. 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> 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. - -.. cfgcmd:: set interfaces pppoe <interface> ip adjust-mss <mss | clamp-mss-to-pmtu> - - As Internet wide PMTU discovery rarely works, we sometimes need to clamp our - TCP MSS value to a specific value. This is a field in the TCP options part of - a SYN packet. By setting the MSS value, you are telling the remote side - unequivocally 'do not try to send me packets bigger than this value'. - - .. note:: This command was introduced in VyOS 1.4 - it was previously called: - ``set firewall options interface <name> adjust-mss <value>`` - - .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in - 1452 bytes on a 1492 byte MTU. - - Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to - automatically set the proper value. - -.. cfgcmd:: set interfaces pppoe <interface> ip disable-forwarding - - Configure interface-specific Host/Router behaviour. If set, the interface will - switch to host mode and IPv6 forwarding will be disabled on this interface. - -.. cfgcmd:: set interfaces pppoe <interface> ip source-validation <strict | loose | disable> - - Enable policy for source validation by reversed path, as specified in - :rfc:`3704`. Current recommended practice in :rfc:`3704` is to enable strict - mode to prevent IP spoofing from DDos attacks. If using asymmetric routing - or other complicated routing, then loose mode is recommended. - - - strict: Each incoming packet is tested against the FIB and if the interface - is not the best reverse path the packet check will fail. By default failed - packets are discarded. - - - loose: Each incoming packet's source address is also tested against the FIB - and if the source address is not reachable via any interface the packet - check will fail. - - - disable: No source validation - -IPv6 ----- - -.. cfgcmd:: set interfaces pppoe <interface> ipv6 address autoconf - - Use this command to enable acquisition of IPv6 address using stateless - autoconfig (SLAAC). - -.. cfgcmd:: set interfaces pppoe <interface> ipv6 adjust-mss <mss | clamp-mss-to-pmtu> - - As Internet wide PMTU discovery rarely works, we sometimes need to clamp our - TCP MSS value to a specific value. This is a field in the TCP options part of - a SYN packet. By setting the MSS value, you are telling the remote side - unequivocally 'do not try to send me packets bigger than this value'. - - .. note:: This command was introduced in VyOS 1.4 - it was previously called: - ``set firewall options interface <name> adjust-mss <value>`` - - .. hint:: MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in - 1432 bytes on a 1492 byte MTU. - - Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to - automatically set the proper value. - -.. cfgcmd:: set interfaces pppoe <interface> ipv6 disable-forwarding - - Configure interface-specific Host/Router behaviour. If set, the interface will - switch to host mode and IPv6 forwarding will be disabled on this interface. - -.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt - :var0: pppoe - :var1: pppoe0 - -********* -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 the example. - -.. opcmd:: connect interface <interface> - - Test connecting given connection-oriented interface. `<interface>` can be - ``pppoe0`` as the 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 ``name-server`` option set to ``none``, VyOS will ignore the - nameservers your ISP sends 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. - -.. note:: A default route is automatically installed once the interface is up. - To change this behavior use the ``no-default-route`` CLI option. - -.. code-block:: none - - set interfaces pppoe pppoe0 authentication username '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 firewall interface pppoe0 in name NET-IN - set firewall interface pppoe0 local name NET-LOCAL - set firewall interface pppoe0 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 authentication username 'userid' - set interfaces pppoe pppoe0 authentication password 'secret' - set interfaces pppoe pppoe0 source-interface 'eth0.7' - - -IPv6 DHCPv6-PD Example ----------------------- - -.. stop_vyoslinter - -The following configuration will setup a PPPoE session source from eth1 and -assign a /64 prefix out of a /56 delegation (requested from the ISP) to eth0. -The IPv6 address assigned to eth0 will be <prefix>::1/64. If you do not know -the prefix size delegated to you, start with sla-len 0. - -In addition we setup IPv6 :abbr:`RA (Router Advertisements)` to make the -prefix known on the eth0 link. - -.. start_vyoslinter - -.. code-block:: none - - set interfaces pppoe pppoe0 authentication username vyos - set interfaces pppoe pppoe0 authentication password vyos - set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' - set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' - set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' - set interfaces pppoe pppoe0 ipv6 address autoconf - set interfaces pppoe pppoe0 source-interface eth1 - - set service router-advert interface eth0 prefix ::/64 diff --git a/docs/configuration/interfaces/rst-pseudo-ethernet.rst b/docs/configuration/interfaces/rst-pseudo-ethernet.rst deleted file mode 100644 index 59b3581c..00000000 --- a/docs/configuration/interfaces/rst-pseudo-ethernet.rst +++ /dev/null @@ -1,67 +0,0 @@ -:lastproofread: 2023-01-26 - -.. _pseudo-ethernet-interface: - -######################### -MACVLAN - Pseudo Ethernet -######################### - -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 learn the MAC address of the NIC - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: pseudo-ethernet - :var1: peth0 - -Pseudo Ethernet/MACVLAN options -=============================== - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> - - Specifies the physical `<ethX>` Ethernet interface associated with a Pseudo - Ethernet `<interface>`. - -VLAN -==== - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: pseudo-ethernet - :var1: peth0 diff --git a/docs/configuration/interfaces/rst-sstp-client.rst b/docs/configuration/interfaces/rst-sstp-client.rst deleted file mode 100644 index 27eb9c39..00000000 --- a/docs/configuration/interfaces/rst-sstp-client.rst +++ /dev/null @@ -1,150 +0,0 @@ -:lastproofread: 2022-12-11 - -.. _sstp-client-interface: - -########### -SSTP Client -########### - -:abbr:`SSTP (Secure Socket Tunneling Protocol)` is a form of :abbr:`VTP (Virtual -Private Network)` tunnel that provides a mechanism to transport PPP traffic -through an SSL/TLS channel. SSL/TLS provides transport-level security with key -negotiation, encryption and traffic integrity checking. The use of SSL/TLS over -TCP port 443 (by default, port can be changed) allows SSTP to pass through -virtually all firewalls and proxy servers except for authenticated web proxies. - -.. note:: VyOS also comes with a build in SSTP server, see :ref:`sstp`. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-description.txt - :var0: sstpc - :var1: sstpc0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: sstpc - :var1: sstpc0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: sstpc - :var1: sstpc0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: sstpc - :var1: sstpc0 - -SSTP Client Options -=================== - -.. cfgcmd:: set interfaces sstpc <interface> no-default-route - - Only request an address from the SSTP server but do not install any default - route. - - Example: - - .. code-block:: none - - set interfaces sstpc sstpc0 no-default-route - - .. note:: This command got added in VyOS 1.4 and inverts the logic from the old - ``default-route`` CLI option. - -.. cfgcmd:: set interfaces sstpc <interface> default-route-distance <distance> - - Set the distance for the default gateway sent by the SSTP server. - - Example: - - .. code-block:: none - - set interfaces sstpc sstpc0 default-route-distance 220 - -.. cfgcmd:: set interfaces sstpc <interface> no-peer-dns - - Use this command to not install advertised DNS nameservers into the local - system. - -.. cfgcmd:: set interfaces sstpc <interface> server <address> - - SSTP remote server to connect to. Can be either an IP address or FQDN. - -.. cfgcmd:: set interfaces sstpc <interface> ip adjust-mss <mss | clamp-mss-to-pmtu> - - As Internet wide PMTU discovery rarely works, we sometimes need to clamp our - TCP MSS value to a specific value. This is a field in the TCP options part of - a SYN packet. By setting the MSS value, you are telling the remote side - unequivocally 'do not try to send me packets bigger than this value'. - - .. note:: This command was introduced in VyOS 1.4 - it was previously called: - ``set firewall options interface <name> adjust-mss <value>`` - - .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in - 1452 bytes on a 1492 byte MTU. - - Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to - automatically set the proper value. - -.. cfgcmd:: set interfaces sstpc <interface> ip disable-forwarding - - Configure interface-specific Host/Router behaviour. If set, the interface will - switch to host mode and IPv6 forwarding will be disabled on this interface. - -.. cfgcmd:: set interfaces sstpc <interface> ip source-validation <strict | loose | disable> - - Enable policy for source validation by reversed path, as specified in - :rfc:`3704`. Current recommended practice in :rfc:`3704` is to enable strict - mode to prevent IP spoofing from DDos attacks. If using asymmetric routing - or other complicated routing, then loose mode is recommended. - - - strict: Each incoming packet is tested against the FIB and if the interface - is not the best reverse path the packet check will fail. By default failed - packets are discarded. - - - loose: Each incoming packet's source address is also tested against the FIB - and if the source address is not reachable via any interface the packet - check will fail. - - - disable: No source validation - -********* -Operation -********* - -.. opcmd:: show interfaces sstpc <interface> - - Show detailed information on given `<interface>` - - .. code-block:: none - - vyos@vyos:~$ show interfaces sstpc sstpc10 - sstpc10: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3 - link/ppp - inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10 - valid_lft forever preferred_lft forever - inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 215 9 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 539 14 0 0 0 0 - - -Connect/Disconnect -================== - -.. opcmd:: disconnect interface <interface> - - Test disconnecting given connection-oriented interface. `<interface>` can be - ``sstpc0`` as the example. - -.. opcmd:: connect interface <interface> - - Test connecting given connection-oriented interface. `<interface>` can be - ``sstpc0`` as the example. diff --git a/docs/configuration/interfaces/rst-tunnel.rst b/docs/configuration/interfaces/rst-tunnel.rst deleted file mode 100644 index 31539d9f..00000000 --- a/docs/configuration/interfaces/rst-tunnel.rst +++ /dev/null @@ -1,286 +0,0 @@ -:lastproofread: 2023-01-26 - -.. _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. - -Common interface configuration ------------------------------- - -.. cmdinclude:: /_include/interface-address.txt - :var0: tunnel - :var1: tun0 - -.. cmdinclude:: /_include/interface-common-without-mac.txt - :var0: tunnel - :var1: tun0 - -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 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 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 source-address 2001:db8:aa::1 - set interfaces tunnel tun0 remote 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 source-address 2001:db8:aa::1 - set interfaces tunnel tun0 remote 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 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 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 represented by IP -protocol 47. The main benefit of a GRE tunnel is that you are able to carry -multiple protocols inside the same tunnel. GRE also supports multicast traffic -and supports routing protocols that leverage multicast to form neighbor -adjacencies. - -A VyOS GRE tunnel can carry both IPv4 and IPv6 traffic and can also be created -over either IPv4 (gre) or IPv6 (ip6gre). - - -Configuration -^^^^^^^^^^^^^ - -A basic configuration requires a tunnel source (source-address), a tunnel -destination (remote), an encapsulation type (gre), and an address (ipv4/ipv6). -Below is a basic IPv4 only 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 source-address '198.51.100.2' - set interfaces tunnel tun100 remote '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 - -Here is a second example of a dual-stack tunnel over IPv6 between a VyOS router -and a Linux host using systemd-networkd. - -**VyOS Router:** - -.. code-block:: none - - set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' - set interfaces tunnel tun101 address '192.168.5.1/30' - set interfaces tunnel tun101 encapsulation 'ip6gre' - set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3' - set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5' - -**Linux systemd-networkd:** - -This requires two files, one to create the device (XXX.netdev) and one -to configure the network on the device (XXX.network) - -.. code-block:: none - - # cat /etc/systemd/network/gre-example.netdev - [NetDev] - Name=gre-example - Kind=ip6gre - MTUBytes=14180 - - [Tunnel] - Remote=2001:db8:babe:face::3afe:3 - - - # cat /etc/systemd/network/gre-example.network - [Match] - Name=gre-example - - [Network] - Address=2001:db8:feed:beef::2/126 - - [Address] - Address=192.168.5.2/30 - -Tunnel keys -^^^^^^^^^^^ - -GRE is also the only classic protocol that allows creating multiple tunnels -with the same source and destination due to its support for tunnel keys. -Despite its name, this feature has nothing to do with security: it's simply -an identifier that allows routers to tell one tunnel from another. - -An example: - -.. code-block:: none - - set interfaces tunnel tun0 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 192.0.2.20 - set interfaces tunnel tun0 address 10.40.50.60/24 - set interfaces tunnel tun0 parameters ip key 10 - -.. code-block:: none - - set interfaces tunnel tun0 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 192.0.2.20 - set interfaces tunnel tun0 address 172.16.17.18/24 - set interfaces tunnel tun0 parameters ip key 20 - -GRETAP -^^^^^^^ - -While normal GRE is for layer 3, GRETAP is for layer 2. GRETAP can encapsulate -Ethernet frames, thus it can be bridged with other interfaces to create -datalink layer segments that span multiple remote sites. - -.. code-block:: none - - set interfaces bridge br0 member interface eth0 - set interfaces bridge br0 member interface tun0 - set interfaces tunnel tun0 encapsulation gretap - set interfaces tunnel tun0 source-address 198.51.100.2 - set interfaces tunnel tun0 remote 203.0.113.10 - - -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/destination traffic. - -**1. Confirm IP connectivity between tunnel source-address and remote:** - -.. 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 - -.. note:: There is also a GRE over IPv6 encapsulation available, it is - called: ``ip6gre``. - -.. _`other proposals`: https://www.isc.org/othersoftware/ -.. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/configuration/interfaces/rst-virtual-ethernet.rst b/docs/configuration/interfaces/rst-virtual-ethernet.rst deleted file mode 100644 index 3324feb6..00000000 --- a/docs/configuration/interfaces/rst-virtual-ethernet.rst +++ /dev/null @@ -1,110 +0,0 @@ -:lastproofread: 2022-11-25 - -.. _virtual-ethernet: - -################ -Virtual Ethernet -################ - -The veth devices are virtual Ethernet devices. They can act as tunnels between -network namespaces to create a bridge to a physical network device in another -namespace or VRF, but can also be used as standalone network devices. - -.. note:: veth interfaces need to be created in pairs - it's called the peer name - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address-with-dhcp.txt - :var0: virtual-ethernet - :var1: veth0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: virtual-ethernet - :var1: veth0 -VLAN -==== - -Regular VLANs (802.1q) ----------------------- -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: virtual-ethernet - :var1: veth0 - -QinQ (802.1ad) --------------- - -.. cmdinclude:: /_include/interface-vlan-8021ad.txt - :var0: virtual-ethernet - :var1: veth0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: virtual-ethernet - :var1: veth0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: virtual-ethernet - :var1: veth0 - -********* -Operation -********* - -.. opcmd:: show interfaces virtual-ethernet - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces virtual-ethernet - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - veth10 100.64.0.0/31 u/u - veth11 100.64.0.1/31 u/u - -.. opcmd:: show interfaces virtual-ethernet <interface> - - Show detailed information on given `<interface>` - - .. code-block:: none - - vyos@vyos:~$ show interfaces virtual-ethernet veth11 - 10: veth11@veth10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP group default qlen 1000 - link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff - inet 100.64.0.1/31 scope global veth11 - valid_lft forever preferred_lft forever - inet6 fe80::b07b:dfff:fe47:e911/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 - -******* -Example -******* - -Interconnect the global VRF with vrf "red" using the veth10 <-> veth 11 pair - -.. code-block:: none - - set interfaces virtual-ethernet veth10 address '100.64.0.0/31' - set interfaces virtual-ethernet veth10 peer-name 'veth11' - set interfaces virtual-ethernet veth11 address '100.64.0.1/31' - set interfaces virtual-ethernet veth11 peer-name 'veth10' - set interfaces virtual-ethernet veth11 vrf 'red' - set vrf name red table '1000' - - vyos@vyos:~$ ping 100.64.0.1 - PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. - 64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms - 64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms - - diff --git a/docs/configuration/interfaces/rst-vti.rst b/docs/configuration/interfaces/rst-vti.rst deleted file mode 100644 index 1704b9d1..00000000 --- a/docs/configuration/interfaces/rst-vti.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _vti-interface: - -############################## -VTI - Virtual Tunnel Interface -############################## - -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" - } - -.. warning:: When using site-to-site IPsec with VTI interfaces, - be sure to disable route autoinstall - -.. code-block:: none - - set vpn ipsec options disable-route-autoinstall - -More details about the IPsec and VTI issue and option disable-route-autoinstall -https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july - -The root cause of the problem is that for VTI tunnels to work, their traffic -selectors have to be set to 0.0.0.0/0 for traffic to match the tunnel, even -though actual routing decision is made according to netfilter marks. Unless -route insertion is disabled entirely, StrongSWAN thus mistakenly inserts a -default route through the VTI peer address, which makes all traffic routed -to nowhere.
\ No newline at end of file diff --git a/docs/configuration/interfaces/rst-vxlan.rst b/docs/configuration/interfaces/rst-vxlan.rst deleted file mode 100644 index 831870c5..00000000 --- a/docs/configuration/interfaces/rst-vxlan.rst +++ /dev/null @@ -1,349 +0,0 @@ -:lastproofread: 2023-01-26 - -.. _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 an overlay encapsulation -protocol. It increases the 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. - -Configuration -============= - -Common interface configuration ------------------------------- - -.. cmdinclude:: /_include/interface-common-without-dhcp.txt - :var0: vxlan - :var1: vxlan0 - -VXLAN specific options ------------------------ - -.. 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. - -.. cfgcmd:: set interfaces vxlan <interface> port <port> - - Configure port number of remote VXLAN endpoint. - -.. cfgcmd:: set interfaces vxlan <interface> source-address <IP address> - - Source IP address used for VXLAN underlay. This is mandatory when using VXLAN - via L2VPN/EVPN. - -.. cfgcmd:: set interfaces vxlan <interface> gpe - - Enables the Generic Protocol extension (VXLAN-GPE). Currently, this is only - supported together with the external keyword. - -.. cfgcmd:: set interfaces vxlan <interface> parameters external - - Specifies whether an external control plane (e.g. BGP L2VPN/EVPN) or the - internal FDB should be used. - -.. cfgcmd:: set interfaces vxlan <interface> parameters neighbor-suppress - - In order to minimize the flooding of ARP and ND messages in the VXLAN network, - EVPN includes provisions :rfc:`7432#section-10` that allow participating VTEPs - to suppress such messages in case they know the MAC-IP binding and can reply - on behalf of the remote host. - -.. cfgcmd:: set interfaces vxlan <interface> parameters nolearning - - Specifies if unknown source link layer addresses and IP addresses are entered - into the VXLAN device forwarding database. - -.. cfgcmd:: set interfaces vxlan <interface> parameters vni-filter - - Specifies whether the VXLAN device is capable of vni filtering. - - Only works with a VXLAN device with external flag set. - - .. note:: The device can only receive packets with VNIs configured in - the VNI filtering table. - -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. - -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. - -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 leaves 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 leaves 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 leaves are -added. - -For optimal scalability, Multicast shouldn't be used at all, but instead use BGP -to signal all connected devices between leaves. Unfortunately, VyOS does not yet -support this. - -Single VXLAN device (SVD) -========================= - -FRR supports a new way of configuring VLAN-to-VNI mappings for EVPN-VXLAN, when -working with the Linux kernel. In this new way, the mapping of a VLAN to a -:abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))` is configured -against a container VXLAN interface which is referred to as a -:abbr:`SVD (Single VXLAN device)`. - -Multiple VLAN to VNI mappings can be configured against the same SVD. This -allows for a significant scaling of the number of VNIs since a separate VXLAN -interface is no longer required for each VNI. - -.. cfgcmd:: set interfaces vxlan <interface> vlan-to-vni <vlan> vni <vni> - - Maps the VNI to the specified VLAN id. The VLAN can then be consumed by - a bridge. - - Sample configuration of SVD with VLAN to VNI mappings is shown below. - - .. code-block:: none - - set interfaces bridge br0 member interface vxlan0 - set interfaces vxlan vxlan0 parameters external - set interfaces vxlan vxlan0 source-interface 'dum0' - set interfaces vxlan vxlan0 vlan-to-vni 10 vni '10010' - set interfaces vxlan vxlan0 vlan-to-vni 11 vni '10011' - set interfaces vxlan vxlan0 vlan-to-vni 30 vni '10030' - set interfaces vxlan vxlan0 vlan-to-vni 31 vni '10031' - -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 leaves to forward traffic between each -other in a more scalable way. This also requires PIM to be enabled towards the -leaves so that the Spine can learn what multicast groups each Leaf expects -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 source-interface '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 source-interface '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 source-interface '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 source-interface '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 leaves for this vlan extension. Has to be the -same on all leaves that has this interface. - -.. code-block:: none - - set interfaces vxlan vxlan241 source-interface '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 port 12345 - -The destination port used for creating a VXLAN interface defaults to -4789. Aconfiguration 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 source-interface '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 4789. -It can be changed with ``set interface vxlan <vxlanN> port <port>`` diff --git a/docs/configuration/interfaces/rst-wireguard.rst b/docs/configuration/interfaces/rst-wireguard.rst deleted file mode 100644 index a40bee01..00000000 --- a/docs/configuration/interfaces/rst-wireguard.rst +++ /dev/null @@ -1,428 +0,0 @@ -:lastproofread: 2023-01-26 - -.. _wireguard: - -######### -WireGuard -######### - -WireGuard is an extremely simple yet fast and modern VPN that utilizes -state-of-the-art cryptography. See https://www.wireguard.com for more -information. - -**************** -Site to Site VPN -**************** - -This diagram corresponds with the example site to site configuration below. - -.. figure:: /_static/images/wireguard_site2site_diagram.jpg - -******** -Keypairs -******** - -WireGuard requires the generation of a keypair, which includes a private key to -decrypt incoming traffic, and a public key for peer(s) to encrypt traffic. - -Generate Keypair -================ - -.. opcmd:: generate pki wireguard key-pair - - It generates the keypair, which includes the public and private parts. - The key is not stored on the system - only a keypair is generated. - - .. code-block:: none - - vyos@vyos:~$ generate pki wireguard key-pair - Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY= - Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= - -.. opcmd:: generate pki wireguard key-pair install interface <interface> - - Generates a keypair, which includes the public and private parts, and build - a configuration command to install this key to ``interface``. - - .. code-block:: none - - vyos@vyos:~$ generate pki wireguard key-pair install interface wg10 - "generate" CLI command executed from operational level. - Generated private-key is not stored to CLI, use configure mode commands to install key: - - set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0=' - - Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro=' - - .. note:: If this command is invoked from configure mode with the ``run`` - prefix the key is automatically installed to the appropriate interface: - - .. code-block:: none - - vyos@vyos# run generate pki wireguard key-pair install interface wg10 - "generate" CLI command executed from config session. - Generated private-key was imported to CLI! - - Use the following command to verify: show interfaces wireguard wg10 - Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8=' - - vyos@vyos# compare - [edit interfaces] - +wireguard wg10 { - + private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc= - +} - -.. opcmd:: show interfaces wireguard <interface> public-key - - Retrieve public key portion from configured WIreGuard interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wireguard wg01 public-key - EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= - - -Optional --------- - -.. opcmd:: generate pki wireguard preshared-key - - An additional layer of symmetric-key crypto can be used on top of the - asymmetric crypto. - - This is optional. - - .. code-block:: none - - vyos@vyos:~$ generate pki wireguard preshared-key - Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= - - -.. opcmd:: generate pki wireguard preshared-key install interface <interface> peer <peer> - - An additional layer of symmetric-key crypto can be used on top of the - asymmetric crypto. This command automatically creates for you the required - CLI command to install this PSK for a given peer. - - This is optional. - - .. code-block:: none - - vyos@vyos:~$ generate pki wireguard preshared-key install interface wg10 peer foo - "generate" CLI command executed from operational level. - Generated preshared-key is not stored to CLI, use configure mode commands to install key: - - set interfaces wireguard wg10 peer foo preshared-key '32vQ1w1yFKTna8n7Gu7EimubSe2Y63m8bafz55EG3Ro=' - - Pre-shared key: +LuaZ8W6DjsDFJFX3jJzoNqrsXHhvq08JztM9z8LHCs= - - - .. note:: If this command is invoked from configure mode with the ``run`` - prefix the key is automatically installed to the appropriate interface: - - -*********************** -Interface configuration -*********************** - -The next step is to configure your local side as well as the policy based -trusted destination addresses. If you only initiate a connection, the listen -port and address/port is optional; however, if you act like a server and -endpoints initiate the connections to your system, you need to define a port -your clients can connect to, otherwise the port is randomly chosen and may -make connection difficult with firewall rules, since the port may be different -each time the system is rebooted. - -You will also need the public key of your peer as well as the network(s) you -want to tunnel (allowed-ips) to configure a WireGuard tunnel. The public key -below is always the public key from your peer, not your local one. - -**local side - commands** - -- WireGuard interface itself uses address 10.1.0.1/30 -- We only allow the 192.168.2.0/24 subnet to travel over the tunnel -- Our remote end of the tunnel for peer `to-wg02` is reachable at 192.0.2.1 - port 51820 -- The remote peer `to-wg02` uses XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI= - as its public key portion -- We listen on port 51820 -- We route all traffic for the 192.168.2.0/24 network to interface `wg01` - -.. code-block:: none - - set interfaces wireguard wg01 address '10.1.0.1/30' - set interfaces wireguard wg01 description 'VPN-to-wg02' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' - set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' - set interfaces wireguard wg01 peer to-wg02 port '51820' - set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' - set interfaces wireguard wg01 port '51820' - - set protocols static route 192.168.2.0/24 interface wg01 - -The last step is to define an interface route for 192.168.2.0/24 to get through -the WireGuard interface `wg01`. Multiple IPs or networks can be defined and -routed. The last check is allowed-ips which either prevents or allows the -traffic. - -.. warning:: You can not assign the same allowed-ips statement to multiple - WireGuard peers. This a design decision. For more information please - check the `WireGuard mailing list`_. - -.. cfgcmd:: set interfaces wireguard <interface> private-key <private-key> - - Associates the previously generated private key to a specific WireGuard - interface. The private key can be generate via the command - - :opcmd:`generate pki wireguard key-pair`. - - .. code-block:: none - - set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' - - The command :opcmd:`show interfaces wireguard wg01 public-key` will then show the - public key, which needs to be shared with the peer. - -.. cmdinclude:: /_include/interface-per-client-thread.txt - :var0: wireguard - :var1: wg01 - -**remote side - commands** - -.. code-block:: none - - set interfaces wireguard wg01 address '10.1.0.2/30' - set interfaces wireguard wg01 description 'VPN-to-wg01' - set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' - set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' - set interfaces wireguard wg01 peer to-wg01 port '51820' - set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' - set interfaces wireguard wg01 port '51820' - set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=' - - set protocols static route 192.168.1.0/24 interface wg01 - -******************* -Firewall Exceptions -******************* - -For the WireGuard traffic to pass through the WAN interface, you must create a -firewall exception. - -.. code-block:: none - - set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept - set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' - set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable - set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable - set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept - set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN - set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 - set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable - set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp - -You should also ensure that the OUTISDE_LOCAL firewall group is applied to the -WAN interface and in an input (local) direction. - -.. code-block:: none - - set firewall ipv4 input filter rule 10 action jump - set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' - set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' - -Assure that your firewall rules allow the traffic, in which case you have a -working VPN using WireGuard. - -.. code-block:: none - - wg01# ping 192.168.1.1 - PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. - 64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms - 64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms - - wg02# ping 192.168.2.1 - PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. - 64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms - 64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms - -An additional layer of symmetric-key crypto can be used on top of the -asymmetric crypto. This is optional. - -.. code-block:: none - - vyos@vyos:~$ generate pki wireguard preshared-key - Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= - -Copy the key, as it is not stored on the local filesystem. Because it -is a symmetric key, only you and your peer should have knowledge of -its content. Make sure you distribute the key in a safe manner, - -.. code-block:: none - - wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' - wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' - - -*********************************** -Remote Access "RoadWarrior" Example -*********************************** - -With WireGuard, a Road Warrior VPN config is similar to a site-to-site -VPN. It just lacks the ``address`` and ``port`` statements. - -In the following example, the IPs for the remote clients are defined in -the peers. This allows the peers to interact with one another. In -comparison to the site-to-site example the ``persistent-keepalive`` -flag is set to 15 seconds to assure the connection is kept alive. -This is mainly relevant if one of the peers is behind NAT and can't -be connected to if the connection is lost. To be effective this -value needs to be lower than the UDP timeout. - -.. code-block:: none - - wireguard wg01 { - address 10.172.24.1/24 - address 2001:db8:470:22::1/64 - description RoadWarrior - peer MacBook { - allowed-ips 10.172.24.30/32 - allowed-ips 2001:db8:470:22::30/128 - persistent-keepalive 15 - public-key F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= - } - peer iPhone { - allowed-ips 10.172.24.20/32 - allowed-ips 2001:db8:470:22::20/128 - persistent-keepalive 15 - public-key BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= - } - port 2224 - private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU= - } - -The following is the config for the iPhone peer above. It's important to -note that the ``AllowedIPs`` wildcard setting directs all IPv4 and IPv6 traffic -through the connection. - -.. code-block:: none - - [Interface] - PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= - Address = 10.172.24.20/24, 2001:db8:470:22::20/64 - DNS = 10.0.0.53, 10.0.0.54 - - [Peer] - PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= - AllowedIPs = 0.0.0.0/0, ::/0 - Endpoint = 192.0.2.1:2224 - PersistentKeepalive = 25 - -However, split-tunneling can be achieved by specifying the remote subnets. -This ensures that only traffic destined for the remote site is sent over the -tunnel. All other traffic is unaffected. - -.. code-block:: none - - [Interface] - PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= - Address = 10.172.24.30/24, 2001:db8:470:22::30/64 - - [Peer] - PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= - AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64 - Endpoint = 192.0.2.1:2224 - PersistentKeepalive = 25 - - -******************** -Operational Commands -******************** - -Status -====== - -.. opcmd:: show interfaces wireguard wg01 summary - - Show info about the Wireguard service. - It also shows the latest handshake. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wireguard wg01 summary - interface: wg01 - public key: - private key: (hidden) - listening port: 51820 - - peer: <peer public-key> - endpoint: <peer public IP> - allowed ips: 10.69.69.2/32 - latest handshake: 23 hours, 45 minutes, 26 seconds ago - transfer: 1.26 MiB received, 6.47 MiB sent - -.. opcmd:: show interfaces wireguard - - Get a list of all wireguard interfaces - - .. code-block:: none - - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - wg01 10.0.0.1/24 u/u - - -.. opcmd:: show interfaces wireguard <interface> - - Show general information about specific WireGuard interface - - .. code-block:: none - - vyos@vyos:~$ show interfaces wireguard wg01 - interface: wg01 - address: 10.0.0.1/24 - public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= - private key: (hidden) - listening port: 41751 - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 0 0 0 0 0 0 - -*********************************** -Remote Access "RoadWarrior" clients -*********************************** - -Some users tend to connect their mobile devices using WireGuard to their VyOS -router. To ease deployment one can generate a "per mobile" configuration from -the VyOS CLI. - -.. warning:: From a security perspective, it is not recommended to let a third - party create and share the private key for a secured connection. - You should create the private portion on your own and only hand out the - public key. Please keep this in mind when using this convenience feature. - -.. opcmd:: generate wireguard client-config <name> interface <interface> server - <ip|fqdn> address <client-ip> - - Using this command, you will create a new client configuration which can - connect to ``interface`` on this router. The public key from the specified - interface is automatically extracted and embedded into the configuration. - - The command also generates a configuration snipped which can be copy/pasted - into the VyOS CLI if needed. The supplied ``<name>`` on the CLI will become - the peer name in the snippet. - - In addition you will specifiy the IP address or FQDN for the client where it - will connect to. The address parameter can be used up to two times and is used - to assign the clients specific IPv4 (/32) or IPv6 (/128) address. - - .. figure:: /_static/images/wireguard_qrcode.jpg - :alt: WireGuard Client QR code - -.. stop_vyoslinter - -.. _`WireGuard mailing list`: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html - -.. start_vyoslinter diff --git a/docs/configuration/interfaces/rst-wireless.rst b/docs/configuration/interfaces/rst-wireless.rst deleted file mode 100644 index df153763..00000000 --- a/docs/configuration/interfaces/rst-wireless.rst +++ /dev/null @@ -1,618 +0,0 @@ -:lastproofread: 2023-01-26 - -.. _wireless-interface: - -######################## -WLAN/WIFI - Wireless LAN -######################## - -: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. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: wireless - :var1: wlan0 - -Wireless options -================ - -.. cfgcmd:: set interfaces wireless <interface> channel <number> - - Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from - 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173 - -.. cfgcmd:: set interfaces wireless <interface> country-code <cc> - - Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed - to indicate country in which device is operating. This can limit available - channels and transmit power. - - .. note:: This option is mandatory in Access-Point mode. - -.. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid - - Send empty SSID in beacons and ignore probe request frames that do not specify - full SSID, i.e., require stations to know SSID. - -.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations - - Disassociate stations based on excessive transmission failures or other - indications of connection loss. - - This depends on the driver capabilities and may not be available with all - drivers. - -.. cfgcmd:: set interfaces wireless <interface> isolate-stations - - Client isolation can be used to prevent low-level bridging of frames between - associated stations in the BSS. - - By default, this bridging is allowed. - -.. cfgcmd:: set interfaces wireless <interface> max-stations - - Maximum number of stations allowed in station table. New stations will be - rejected after the station table is full. IEEE 802.11 has a limit of 2007 - different association IDs, so this number should not be larger than that. - - This defaults to 2007. - -.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection - - Management Frame Protection (MFP) according to IEEE 802.11w - -.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac> - - Operation mode of wireless radio. - - * ``a`` - 802.11a - 54 Mbits/sec - * ``b`` - 802.11b - 11 Mbits/sec - * ``g`` - 802.11g - 54 Mbits/sec (default) - * ``n`` - 802.11n - 600 Mbits/sec - * ``ac`` - 802.11ac - 1300 Mbits/sec - -.. cfgcmd:: set interfaces wireless <interface> physical-device <device> - - Wireless hardware device used as underlay radio. - - This defaults to phy0. - -.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> - - Add Power Constraint element to Beacon and Probe Response frames. - - This option adds Power Constraint element when applicable and Country element - is added. Power Constraint element is required by Transmit Power Control. - - Valid values are 0..255. - -.. cfgcmd:: set interfaces wireless <interface> ssid <ssid> - - SSID to be used in IEEE 802.11 management frames - -.. cfgcmd:: set interfaces wireless <interface> type - <access-point | station | monitor> - - Wireless device type for this interface - - * ``access-point`` - Access-point forwards packets between other nodes - * ``station`` - Connects to another access point - * ``monitor`` - Passively monitor all packets on the frequency/channel - -.. cmdinclude:: /_include/interface-per-client-thread.txt - :var0: wireless - :var1: wlan0 - -PPDU ----- - -.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht - -.. cfgcmd:: set interfaces wireless <interface> capabilities require-hvt - -HT (High Throughput) capabilities (802.11n) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable - - Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave - - WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - channel-set-width <ht20 | ht40+ | ht40-> - - Supported channel width set. - - * ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary - channel - * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary - channel - - .. note:: There are limits on which channels can be used with HT40- and HT40+. - Following table shows the channels that may be available for HT40- and HT40+ - use per IEEE 802.11n Annex J: - - Depending on the location, not all of these channels may be available for - use! - - .. code-block:: none - - freq HT40- HT40+ - 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) - 5 GHz 40,48,56,64 36,44,52,60 - - .. note:: 40 MHz channels may switch their primary and secondary channels if - needed or creation of 40 MHz channel maybe rejected based on overlapping - BSSes. These changes are done automatically when hostapd is setting up the - 40 MHz channel. - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - delayed-block-ack - - Enable HT-delayed Block Ack ``[DELAYED-BA]`` - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40 - - DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield - - This enables the greenfield option which sets the ``[GF]`` option - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc - - Enable LDPC coding capability - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection - - Enable L-SIG TXOP protection capability - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu - <3839 | 7935> - - Maximum A-MSDU length 3839 (default) or 7935 octets - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - short-gi <20 | 40> - - Short GI capabilities for 20 and 40 MHz - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - smps <static | dynamic> - - Spatial Multiplexing Power Save (SMPS) settings - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num> - - Enable receiving PPDU using STBC (Space Time Block Coding) - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx - - Enable sending PPDU using STBC (Space Time Block Coding) - -VHT (Very High Throughput) capabilities (802.11ac) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count - - Number of antennas on this card - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - antenna-pattern-fixed - - Set if antenna pattern does not change during the lifetime of an association - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform - <single-user-beamformer | single-user-beamformee | multi-user-beamformer | - multi-user-beamformee> - - Beamforming capabilities: - - * ``single-user-beamformer`` - Support for operation as single user beamformer - * ``single-user-beamformee`` - Support for operation as single user beamformee - * ``multi-user-beamformer`` - Support for operation as single user beamformer - * ``multi-user-beamformee`` - Support for operation as single user beamformer - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - center-channel-freq <freq-1 | freq-2> <number> - - VHT operating channel center frequency - center freq 1 - (for use with 80, 80+80 and 160 modes) - - VHT operating channel center frequency - center freq 2 - (for use with the 80+80 mode) - - <number> must be from 34 - 173. For 80 MHz channels it should be channel + 6. - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - channel-set-width <0 | 1 | 2 | 3> - - * ``0`` - 20 or 40 MHz channel width (default) - * ``1`` - 80 MHz channel width - * ``2`` - 160 MHz channel width - * ``3`` - 80+80 MHz channel width - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc - - Enable LDPC (Low Density Parity Check) coding capability - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht link-adaptation - - VHT link adaptation capabilities - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - max-mpdu <value> - - Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - max-mpdu-exp <value> - - Set the maximum length of A-MPDU pre-EOF padding that the station can receive - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - short-gi <80 | 160> - - Short GI capabilities - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num> - - Enable receiving PPDU using STBC (Space Time Block Coding) - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx - - Enable sending PPDU using STBC (Space Time Block Coding) - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave - - Enable VHT TXOP Power Save Mode - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf - - Station supports receiving VHT variant HT Control field - -Wireless options (Station/Client) -================================= - -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 country-code de - set interfaces wireless wlan0 ssid Test - set interfaces wireless wlan0 security wpa passphrase '12345678' - -Resulting in - -.. code-block:: none - - interfaces { - [...] - wireless wlan0 { - address dhcp - country-code de - security { - wpa { - passphrase "12345678" - } - } - ssid TEST - type station - } - -Security -======== - -: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 country-code de - 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 - country-code de - 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 - } - } - -VLAN -==== - -Regular VLANs (802.1q) ----------------------- - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: wireless - :var1: wlan0 - -QinQ (802.1ad) --------------- - -.. cmdinclude:: /_include/interface-vlan-8021ad.txt - :var0: wireless - :var1: wlan0 - -********* -Operation -********* - -.. 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 details 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 - - -******** -Examples -******** - -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' - set interfaces wireless wlan0 country-code de - -Resulting in - -.. code-block:: none - - interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - country-code de - 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 an 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. - -.. _wireless-interface-intel-ax200: - -Intel AX200 -=========== - -The Intel AX200 card does not work out of the box in AP mode, see -https://unix.stackexchange.com/questions/598275/intel-ax200-ap-mode. You can -still put this card into AP mode using the following configuration: - -.. stop_vyoslinter -.. code-block:: none - - set interfaces wireless wlan0 channel '1' - set interfaces wireless wlan0 country-code 'us' - set interfaces wireless wlan0 mode 'n' - set interfaces wireless wlan0 physical-device 'phy0' - set interfaces wireless wlan0 ssid 'VyOS' - set interfaces wireless wlan0 type 'access-point' - -.. start_vyoslinter diff --git a/docs/configuration/interfaces/rst-wwan.rst b/docs/configuration/interfaces/rst-wwan.rst deleted file mode 100644 index 76a4a3d7..00000000 --- a/docs/configuration/interfaces/rst-wwan.rst +++ /dev/null @@ -1,338 +0,0 @@ -:lastproofread: 2023-01-27 - -.. _wwan-interface: - -################################# -WWAN - Wireless Wide-Area-Network -################################# - -The Wireless Wide-Area-Network interface provides access (through a wireless -modem/wwan) to wireless networks provided by various cellular providers. - -VyOS uses the `interfaces wwan` subsystem for configuration. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address-with-dhcp.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-disable-link-detect.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-ip.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: wwan - :var1: wwan0 - -**DHCP(v6)** - -.. cmdinclude:: /_include/interface-dhcp-options.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-dhcpv6-options.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt - :var0: wwan - :var1: wwan0 - -WirelessModem (WWAN) options -============================ - -.. cfgcmd:: set interfaces wwan <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. - - -********* -Operation -********* - -.. opcmd:: show interfaces wwan <interface> - - Show detailed information on given `<interface>` - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 - wwan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 - link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff - inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0 - valid_lft 7012sec preferred_lft 7012sec - inet6 fe80::c2:f3ff:fe00:0102/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 640 2 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 3229 16 0 0 0 0 - -.. opcmd:: show interfaces wwan <interface> summary - - Show detailed information summary on given `<interface>` - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 summary - -------------------------------- - General | dbus path: /org/freedesktop/ModemManager1/Modem/0 - | device id: 79f4e9cc2e9fc8d4a3b8c8f6327c2e363170194d - -------------------------------- - Hardware | manufacturer: Sierra Wireless, Incorporated - | model: MC7710 - | revision: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 - | h/w revision: 1.0 - | supported: gsm-umts, lte - | current: gsm-umts, lte - | equipment id: 358xxxxxxxxxxxx - -------------------------------- - System | device: /sys/devices/pci0000:00/0000:00:13.0/usb3/3-1/3-1.3 - | drivers: qcserial, qmi_wwan - | plugin: Generic - | primary port: cdc-wdm0 - | ports: ttyUSB0 (qcdm), ttyUSB2 (at), cdc-wdm0 (qmi), wwan0 (net) - -------------------------------- - Numbers | own: 4917xxxxxxxx - -------------------------------- - Status | lock: sim-pin2 - | unlock retries: sim-pin (3), sim-pin2 (3), sim-puk (10), sim-puk2 (10) - | state: connected - | power state: on - | access tech: lte - | signal quality: 63% (recent) - -------------------------------- - Modes | supported: allowed: 2g; preferred: none - | allowed: 3g; preferred: none - | allowed: 4g; preferred: none - | allowed: 2g, 3g; preferred: 3g - | allowed: 2g, 3g; preferred: 2g - | allowed: 2g, 4g; preferred: 4g - | allowed: 2g, 4g; preferred: 2g - | allowed: 3g, 4g; preferred: 3g - | allowed: 3g, 4g; preferred: 4g - | allowed: 2g, 3g, 4g; preferred: 4g - | allowed: 2g, 3g, 4g; preferred: 3g - | allowed: 2g, 3g, 4g; preferred: 2g - | current: allowed: 2g, 3g, 4g; preferred: 2g - -------------------------------- - Bands | supported: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, - | eutran-7, eutran-8, eutran-20 - | current: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, - | eutran-7, eutran-8, eutran-20 - -------------------------------- - IP | supported: ipv4, ipv6, ipv4v6 - -------------------------------- - 3GPP | imei: 358xxxxxxxxxxxx - | operator id: 26201 - | operator name: Telekom.de - | registration: home - -------------------------------- - 3GPP EPS | ue mode of operation: ps-1 - -------------------------------- - SIM | dbus path: /org/freedesktop/ModemManager1/SIM/0 - -------------------------------- - Bearer | dbus path: /org/freedesktop/ModemManager1/Bearer/0 - - -.. opcmd:: show interfaces wwan <interface> capabilities - - Show WWAN module hardware capabilities. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 capabilities - Max TX channel rate: '50000000' - Max RX channel rate: '100000000' - Data Service: 'simultaneous-cs-ps' - SIM: 'supported' - Networks: 'gsm, umts, lte' - Bands: 'gsm-dcs-1800, gsm-900-extended, gsm-900-primary, gsm-pcs-1900, wcdma-2100, wcdma-900' - LTE bands: '1, 3, 7, 8, 20' - -.. opcmd:: show interfaces wwan <interface> firmware - - Show WWAN module firmware. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 firmware - Model: MC7710 - Boot version: SWI9200X_03.05.29.03bt r6485 CNSHZ-ED-XP0031 2014/12/02 17:33:08 - AMSS version: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 - SKU ID: unknown - Package ID: unknown - Carrier ID: 0 - Config version: unknown - - -.. opcmd:: show interfaces wwan <interface> imei - - Show WWAN module IMEI. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 imei - ESN: '0' - IMEI: '358xxxxxxxxxxxx' - MEID: 'unknown' - -.. opcmd:: show interfaces wwan <interface> imsi - - Show WWAN module IMSI. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 imsi - IMSI: '262xxxxxxxxxxxx' - -.. opcmd:: show interfaces wwan <interface> model - - Show WWAN module model. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 model - Model: 'MC7710' - -.. opcmd:: show interfaces wwan <interface> msisdn - - Show WWAN module MSISDN. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 msisdn - MSISDN: '4917xxxxxxxx' - -.. opcmd:: show interfaces wwan <interface> revision - - Show WWAN module hardware revision. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 revision - Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' - -.. opcmd:: show interfaces wwan <interface> signal - - Show WWAN module signal strength. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 signal - LTE: - RSSI: '-74 dBm' - RSRQ: '-7 dB' - RSRP: '-100 dBm' - SNR: '13.0 dB' - Radio Interface: 'lte' - Active Band Class: 'eutran-3' - Active Channel: '1300' - -.. opcmd:: show interfaces wwan <interface> sim - - Show WWAN module SIM card information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 sim - Provisioning applications: - Primary GW: slot '1', application '1' - Primary 1X: session doesn't exist - Secondary GW: session doesn't exist - Secondary 1X: session doesn't exist - Slot [1]: - Card state: 'present' - UPIN state: 'not-initialized' - UPIN retries: '0' - UPUK retries: '0' - Application [1]: - Application type: 'usim (2)' - Application state: 'ready' - Application ID: - A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00 - Personalization state: 'ready' - UPIN replaces PIN1: 'no' - PIN1 state: 'disabled' - PIN1 retries: '3' - PUK1 retries: '10' - PIN2 state: 'enabled-not-verified' - PIN2 retries: '3' - PUK2 retries: '10' - -******* -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 wwan wwan0 apn 'internet.telekom' - set interfaces wwan wwan0 address 'dhcp' - -***************** -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) -* Huawei ME909s-120 miniPCIe card (LTE) -* HP LT4120 Snapdragon X5 LTE - -*************** -Firmware Update -*************** - -All available WWAN cards have a build in, reprogrammable firmware. Most of the -vendors provide a regular update to the firmware used in the baseband chip. - -As VyOS makes use of the QMI interface to connect to the WWAN modem cards, also -the firmware can be reprogrammed. - -To update the firmware, VyOS also ships the `qmi-firmware-update` binary. To -upgrade the firmware of an e.g. Sierra Wireless MC7710 module to the firmware -provided in the file ``9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe`` -use the following command: - -.. code-block:: bash - - $ sudo qmi-firmware-update --update -d 1199:68a2 \ - 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe |