From dfea790b36ddab4c6661436c8eed3cea7af5bd3a Mon Sep 17 00:00:00 2001 From: Daniil Baturin Date: Wed, 6 May 2026 14:08:24 +0100 Subject: Revert "Add incremental RST-to-MyST swap mechanism (#1857)" (#1892) This reverts commit 4b36114e053ee11d0cb264a1e4cfe4692d78f194. --- docs/configuration/interfaces/md-bonding.md | 764 ----------------- docs/configuration/interfaces/md-bridge.md | 431 ---------- docs/configuration/interfaces/md-dummy.md | 87 -- docs/configuration/interfaces/md-ethernet.md | 515 ------------ docs/configuration/interfaces/md-geneve.md | 105 --- docs/configuration/interfaces/md-index.md | 26 - docs/configuration/interfaces/md-l2tpv3.md | 170 ---- docs/configuration/interfaces/md-loopback.md | 67 -- docs/configuration/interfaces/md-macsec.md | 319 ------- .../interfaces/md-openvpn-examples.md | 769 ----------------- docs/configuration/interfaces/md-openvpn.md | 614 -------------- docs/configuration/interfaces/md-pppoe.md | 419 ---------- .../configuration/interfaces/md-pseudo-ethernet.md | 52 -- docs/configuration/interfaces/md-sstp-client.md | 170 ---- docs/configuration/interfaces/md-tunnel.md | 309 ------- .../interfaces/md-virtual-ethernet.md | 119 --- docs/configuration/interfaces/md-vti.md | 121 --- docs/configuration/interfaces/md-vxlan.md | 373 --------- docs/configuration/interfaces/md-wireguard.md | 434 ---------- docs/configuration/interfaces/md-wireless.md | 923 --------------------- docs/configuration/interfaces/md-wwan.md | 355 -------- 21 files changed, 7142 deletions(-) delete mode 100644 docs/configuration/interfaces/md-bonding.md delete mode 100644 docs/configuration/interfaces/md-bridge.md delete mode 100644 docs/configuration/interfaces/md-dummy.md delete mode 100644 docs/configuration/interfaces/md-ethernet.md delete mode 100644 docs/configuration/interfaces/md-geneve.md delete mode 100644 docs/configuration/interfaces/md-index.md delete mode 100644 docs/configuration/interfaces/md-l2tpv3.md delete mode 100644 docs/configuration/interfaces/md-loopback.md delete mode 100644 docs/configuration/interfaces/md-macsec.md delete mode 100644 docs/configuration/interfaces/md-openvpn-examples.md delete mode 100644 docs/configuration/interfaces/md-openvpn.md delete mode 100644 docs/configuration/interfaces/md-pppoe.md delete mode 100644 docs/configuration/interfaces/md-pseudo-ethernet.md delete mode 100644 docs/configuration/interfaces/md-sstp-client.md delete mode 100644 docs/configuration/interfaces/md-tunnel.md delete mode 100644 docs/configuration/interfaces/md-virtual-ethernet.md delete mode 100644 docs/configuration/interfaces/md-vti.md delete mode 100644 docs/configuration/interfaces/md-vxlan.md delete mode 100644 docs/configuration/interfaces/md-wireguard.md delete mode 100644 docs/configuration/interfaces/md-wireless.md delete mode 100644 docs/configuration/interfaces/md-wwan.md (limited to 'docs/configuration/interfaces') diff --git a/docs/configuration/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md deleted file mode 100644 index 7a07a27c..00000000 --- a/docs/configuration/interfaces/md-bonding.md +++ /dev/null @@ -1,764 +0,0 @@ ---- -lastproofread: '2025-12-09' ---- - -(bond-interface)= - -# Bond / link aggregation - -A **bonding interface** aggregates multiple network interfaces into a single -logical interface (referred to as a bond, {abbr}`LAG (Link Aggregation Group)`, -EtherChannel, or port-channel). - -The behavior of a bonding interface depends on the selected mode. Modes provide -either fault tolerance or a combination of load balancing and fault tolerance. -Additionally, the bonding interface can be configured for link integrity -monitoring. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: bonding -:var1: bond0 -``` - -### Member interfaces - -```{cfgcmd} set interfaces bonding \ member interface \ - -**Add an interface to the bonding group.** - -**Example:** - -To configure eth0 and eth1 as members of the bonding interface bond0, execute -the following commands: -``` - -```none -set interfaces bonding bond0 member interface eth0 -set interfaces bonding bond0 member interface eth1 -``` - -### Bond modes - -````{cfgcmd} set interfaces bonding \ mode \<802.3ad | active-backup | broadcast | round-robin | transmit-load-balance | adaptive-load-balance | xor-hash\> - -```{eval-rst} -**Configure the bonding mode on the interface. The default mode is** -``802.3ad``. - -The available modes are: - -* ``802.3ad`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - IEEE 802.3ad Dynamic Link Aggregation. Groups only member - interfaces with the same speed (e.g., 1 Gbps) and duplex - settings. Member interfaces with different speed and duplex - settings are not included in the active bond. - - Provides load balancing and fault tolerance. Uses the - :abbr:`LACP (Link Aggregation Control Protocol)` to - negotiate the bond with the switch. - * - **Traffic distribution:** - - Traffic is distributed according to the **transmit hash - policy** (default: XOR). - - The bonding driver applies an XOR operation to specific - packet header fields, generating a hash value that maps to - a particular member interface. This ensures the same network - flow is consistently transmitted over the same member - interface. - - The transmit hash policy is configured via the ``hash-policy`` option. - * - **Failover:** - - If a member interface fails, the hash is recalculated to distribute - traffic among the remaining active member interfaces. - -.. note:: Not all transmit hash policies comply with 802.3ad, particularly - section 43.2.4. Using a non-compliant policy may result in out-of-order - packet delivery. - -* ``active-backup`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides fault tolerance. Only one member interface is active - at a time. Other member interfaces remain in a standby mode. - * - **Traffic distribution:** - - All traffic (incoming and outgoing) is routed via one active - member interface. - * - **Failover:** - - If the designated member interface fails, all traffic is - routed to another member interface. The bonding driver sends - a Gratuitous ARP to update the peer's MAC address table, - linking the bond's MAC address to another physical port. - -* ``broadcast`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides maximum fault tolerance by duplicating traffic. - * - **Traffic distribution:** - - Every packet is duplicated and transmitted on **all** member - interfaces. - * - **Failover:** - - Traffic flow is not interrupted as long as at least one - member interface remains active. - -* ``round-robin`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides load balancing and fault tolerance. - * - **Traffic distribution:** - - Packets are transmitted in sequential order across the member - interfaces (e.g., packet 1 > interface A, packet 2 > - interface B, etc.). - * - **Failover:** - - If a member interface fails, the sequence skips the failed - interface and continues with the remaining active members. - -* ``transmit-load-balance`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides adaptive transmit load balancing and fault tolerance. - * - **Traffic distribution:** - - **Outgoing:** Distributed across all active member interfaces - based on the current load. - - **Incoming:** Received by a designated member interface - (active receiver). - * - **Failover:** - - If the active receiver fails, another member interface takes - over as the new active receiver. - -* ``adaptive-load-balance`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides adaptive transmit load balancing identical to - ``transmit-load-balance``, receive load balancing for IPv4 - traffic, and fault tolerance for both incoming and outgoing - traffic. - * - **Traffic distribution:** - - **Outgoing:** Identical to ``transmit-load-balance``. - - **Incoming:** Distributed based on ARP manipulation. For - both local and remote connections, the bonding driver - intercepts ARP traffic and changes the source MAC address - to the MAC address of the least loaded member interface. - - All traffic from that peer is then routed to the chosen - member interface. - * - **Failover:** - - If a member interface's state changes (fails, recovers, is - added, or excluded), the traffic is redistributed among all - active member interfaces. - -* ``xor-hash``: Provides load balancing and fault tolerance - based on a hash formula. Distributes traffic and handles - failover identically to ``802.3ad``, but operates without - the :abbr:`LACP (Link Aggregation Control Protocol)`. -``` - -```` - -```{cfgcmd} set interfaces bonding \ min-links \<0-16\> - -**Configure how many member interfaces must be active (in the -link-up state) to mark the bonding interface UP (carrier -asserted).** - -This command applies only when the bonding interface is configured -in 802.3ad mode and functions like the Cisco EtherChannel min-links -feature. It ensures that a bonding interface is marked UP (carrier -asserted) only when a specified number of member interfaces are -active (in the link-up state). This helps guarantee a minimum level -of bandwidth for higher-level services (such as clustering) relying -on the bonding interface. - -The default value is 0. This marks the bonding interface UP -(carrier asserted) whenever an active LACP aggregator exists, -regardless of the number of member interfaces in that aggregator. - -:::{note} -In 802.3ad mode, a bond cannot be active without at least one active -member interface. Therefore, setting min-links to 0 or 1 has the same result: -the bonding interface is marked UP (carrier asserted). -::: -``` - -```{cfgcmd} set interfaces bonding \ lacp-rate \ - -**Configure the rate at which the bonding interface requests its link -partner to send** {abbr}`LACPDUs (Link Aggregation Control Protocol Data -Units)` **in 802.3ad mode.** - -This command applies only when the bonding interface is configured in -802.3ad mode. - -The following options are available: - -* **slow (default):** Requests the link partner to transmit LACPDUs every 30 seconds. - -* **fast:** Requests the link partner to transmit LACPDUs every 1 second. -``` -```{cfgcmd} set interfaces bonding \ system-mac \ - -**Configure a specific MAC address for the bonding interface.** - -This sets the 802.3ad system MAC address, which is used for {abbr}`LACPDU (Link -Aggregation Control Protocol Data Unit)` exchanges with the link partner. -You can assign a fixed MAC address or generate a random one for these -{abbr}`LACPDU (Link Aggregation Control Protocol Data Unit)` exchanges. -``` -```{cfgcmd} set interfaces bonding \ hash-policy \ - -**Configure which transmit hash policy to use for distributing traffic across -member interfaces.** - -The following policies are available: - -* ``layer2`` - -**Description:** Routes all traffic destined for a specific network peer through -the same member interface. The policy is 802.3ad-compliant. - -**Hash inputs:** Source MAC address, destination MAC address, and Ethernet packet -type ID. - -**Formula:** - -:::{code-block} none -hash = source MAC address XOR destination MAC address XOR packet type ID -member interface number = hash modulo member interface count -::: - -* ``layer2+3`` - -**Description:** Similar to ``layer2``, routes all traffic destined for a specific -network peer through the same member interface and is IEEE 802.3ad-compliant. Uses -both Layer 2 and Layer 3 information to provide a more balanced traffic distribution. - -**Hash inputs:** -* Source MAC address, destination MAC address, and Ethernet packet type ID. -* Source IP address, destination IP address. IPv6 addresses are first hashed - using ``IPv6_addr_hash``. - -**Formula:** - -:::{code-block} none -hash = source MAC address XOR destination MAC address XOR packet type ID -hash = hash XOR source IP address XOR destination IP address -hash = hash XOR (hash RSHIFT 16) -hash = hash XOR (hash RSHIFT 8) -member interface number = hash modulo member interface count -::: - -For non-IP traffic, the formula is the same as for ``layer2``. - -* ``layer3+4`` - -**Description:** Routes different connections (flows) destined for a specific -network peer through multiple member interfaces, but ensures each individual -flow is routed through only one member interface. - -:::{note} -This policy is not fully 802.3ad-compliant. When a single TCP or UDP flow -contains both fragmented and unfragmented packets, the algorithm may distribute -them across different member interfaces. This may result in out-of-order packet -delivery, violating the 802.3ad standard. -::: - -**Hash inputs:** -* Source port, destination port (if available). -* Source IP address, destination IP address. IPv6 addresses are first hashed - using ``IPv6_addr_hash``. - -**Formula:** - -:::{code-block} none -hash = source port, destination port (as in the header) -hash = hash XOR source IP address XOR destination IP address -hash = hash XOR (hash RSHIFT 16) -hash = hash XOR (hash RSHIFT 8) -member interface number = hash modulo member interface count -::: - -For fragmented TCP or UDP packets and all other IPv4 and IPv6 traffic, the -source and destination port information is omitted. - -For non-IP traffic, the formula is the same as for ``layer2``. -``` - - -```{cfgcmd} set interfaces bonding \ primary \ - -**Configure the primary member interface in the bond.** - -The primary member interface remains active as long as it is operational; -alternative member interfaces are used only if it fails. - -Use this configuration when a specific member interface is preferred, -such as one with higher throughput. - -This command applies only to ``active-backup``, ``transmit-load-balance``, and -``adaptive-load-balance`` modes. -``` - - -```{cfgcmd} set interfaces bonding \ arp-monitor interval \ - -**Configure the ARP monitoring interval, in seconds, for the bonding interface.** - -ARP monitoring periodically assesses the health of each member interface by -checking whether it has recently sent or received traffic (this criterion -varies depending on the bonding mode and the member interface’s state). ARP -probes are sent to the IP addresses specified with the arp-monitor target option. - -When ARP monitoring is used with EtherChannel-compatible modes (such as -``round-robin`` or ``xor-hash``), the switch should be configured to distribute -traffic across all member interfaces. If the switch distributes traffic using -an XOR-based policy, all ARP replies will be received on one member interface, -causing other member interfaces to be incorrectly marked as failed. - -Setting this value to 0 disables ARP monitoring. - -The default value is 0. -``` - - -```{cfgcmd} set interfaces bonding \ arp-monitor target \ - -**Configure the IP addresses for ARP monitoring requests.** - -The bonding driver sends ARP requests to these IP addresses to check the -state of member interfaces. - -To enable ARP monitoring, configure at least one IP address (up to 16 per -bonding interface). - -By default, no IP addresses are configured. -``` - -### {abbr}`VLAN (Virtual Local Area Network)` - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: bonding -:var1: bond0 -``` - -### SPAN port mirroring - -```{cmdincludemd} ../../_include/interface-mirror.txt -:var0: bonding -:var1: bond1 -:var2: eth3 -``` - -#### EVPN multihoming - - -EVPN multihoming (EVPN-MH) is a standards-based solution (RFC 7432, RFC 8365) -that enables Customer Edge (CE) devices, such as servers, to connect to two -or more Provider Edge (PE) devices for redundancy and load balancing. - - -EVPN-MH is often used as a modern, standards-based alternative to -{abbr}`MLAG (Multi-Chassis Link Aggregation)` and {abbr}`VTEPs (Virtual -Tunnel Endpoints)`. - - -**Ethernet Segment (ES) and Ethernet Segment Identifier (ESI)** - - -Physical links that connect a CE device to PE devices are bundled using link -aggregation. This logical bundle is called an Ethernet Segment (ES) and is -uniquely identified by an Ethernet Segment Identifier (ESI) within the -EVPN domain. - - -To enable EVPN-MH, configure the same ESI on the bonding interfaces of all -PE devices connected to a single CE device. - - -An ESI is configured by specifying either a system MAC address and a local -discriminator, or an Ethernet Segment Identifier Name (ESINAME). - - -The following two commands generate a 10-byte Type-3 ESI by combining the -system MAC and local discriminator: - -```{cfgcmd} set interfaces bonding \ evpn es-id \<1-16777215|10-byte ID\> - -``` -```{cfgcmd} set interfaces bonding \ evpn es-sys-mac \ - -Alternatively, assign an ESINAME directly as a 10-byte Type-0 ESI using the -following format: 00:AA:BB:CC:DD:EE:FF:GG:HH:II. - -**BGP-EVPN route usage** - -EVPN-MH uses BGP-EVPN route types 1 and 2 for ES discovery and MAC-IP -synchronization: - -* **Type 1 (EAD-per-ES and EAD-per-EVI)** routes advertise the locally -attached ESs and discover remote ESs in the network. -* **Type 2 (MAC-IP advertisement)** routes are advertised with a -destination ESI, enabling MAC-IP synchronization between ES peers. -``` - -```{cfgcmd} set interfaces bonding \ evpn es-df-pref \<1-65535\> - -**Configure the** {abbr}`DF (Designated Forwarder)` **preference (1-65535) for -the interface. A higher value indicates a higher preference to become the** -{abbr}`DF (Designated Forwarder)`. **The** {abbr}`DF (Designated Forwarder)` -**preference is configured per-ES.** - -The DF election process determines which interface in a specific ES forwards -{abbr}`BUM (Broadcast, Unknown Unicast, and Multicast)` traffic from the EVPN -overlay to the connected CE device. EVPN Type-4 (Ethernet Segment) routes are -used to elect the DF, implementing the preference-based election method defined -in RFC 9785. - -Interfaces not elected as the DF drop any BUM traffic from the EVPN overlay -using non-DF filters. Similarly, traffic received from ES peers via the EVPN -overlay is blocked from forwarding to the CE device to maintain split-horizon -filtering with local bias. -``` - -```{cmdincludemd} /_include/interface-evpn-uplink.txt -:var0: bonding -:var1: bond0 -``` - -## Example - - -The following configuration example applies to all listed third-party vendors. -It creates a bonding interface with two member interfaces, defines VLANs 10 -and 100 on the bonding interface, and assigns an IPv4 address to each VLAN -subinterface. - -```none -# Create the 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 are running this configuration in a virtual environment like -EVE-NG, ensure the e1000 driver is chosen for your VyOS NIC. The default -drivers, such as ``virtio-net-pci`` or ``vmxnet3``, are incompatible with -this configuration. Specifically, ICMP messages will not be processed -correctly. - -To check your NIC driver, use the following command: -``show interfaces ethernet eth0 physical | grep -i driver`` -::: - - -### Cisco Catalyst configuration - - -Configure a Cisco Catalyst switch to integrate with a two-member VyOS bonding -interface. - - -Assign member interfaces to PortChannel: - -```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, `Port-channel1`, becomes available; all configuration, -such as allowed VLAN interfaces and STP, is applied here. - -```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 configuration - - -Configure a Juniper EX Series switch to integrate with a two-member VyOS bonding -interface. - -```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 configuration - - -Configure an Aruba/HP 2510G switch to integrate with a two-member VyOS bonding -interface. - -```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 configuration - - -When deploying VyOS in environments with Arista switches, use the following -blueprint as an initial setup to configure an operational LACP port-channel -between the two devices. - - -Let's assume the following topology: - - -```{eval-rst} -.. figure:: /_static/images/vyos_arista_bond_lacp.webp - :alt: VyOS Arista EOS setup -``` - - -**R1** - -```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** - - - -```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** - -```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** - - - -```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 testing this environment in EVE-NG, ensure the e1000 driver -is chosen for your VyOS network interfaces. If the default virtio driver -is used, VyOS will not transmit LACP PDUs, preventing the port-channel -from ever becoming active. -::: - - -(operation)= - -## 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 \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces bonding bond5 -bond5: 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 \ detail - -Show detailed information about the underlying physical links on the given -bonding 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 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-bridge.md b/docs/configuration/interfaces/md-bridge.md deleted file mode 100644 index 77775767..00000000 --- a/docs/configuration/interfaces/md-bridge.md +++ /dev/null @@ -1,431 +0,0 @@ ---- -lastproofread: '2025-12-22' ---- - -(bridge-interface)= - -# Bridge - -VyOS bridges connect Ethernet segments by grouping multiple interfaces into a -single bridge interface, which acts as a virtual software switch. Unlike -routers, which forward traffic based on Layer 3 IP addresses, bridges operate -at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2, -bridges are protocol-agnostic and transparently forward all Ethernet- -encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial -protocols. - -This implementation utilizes the Linux bridge subsystem to support a subset of -the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning. - -:::{note} -{abbr}`STP (Spanning Tree Protocol)` is disabled by default in VyOS -and must be explicitly enabled if required. See {ref}`stp` for details. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: bridge -:var1: br0 -``` - - -### Member interfaces - -```{cfgcmd} set interfaces bridge \ member interface \ - -**Configure an interface as a bridge member.** - -Valid interface types are: {ref}`ethernet-interface`, {ref}`bond-interface`, -{ref}`l2tpv3-interface`, {ref}`openvpn`, {ref}`vxlan-interface`, -{ref}`wireless-interface`, {ref}`tunnel-interface`, and -{ref}`geneve-interface`. - -Use tab completion to list interfaces that can be bridged. -``` - -```{cfgcmd} set interfaces bridge \ member interface \ priority \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **port priority -for a specific member interface within a bridge.** - -Within the {abbr}`STP (Spanning Tree Protocol)` topology, each member interface -in a bridge operates as a port with an assigned **priority** and **path cost**. -{abbr}`STP (Spanning Tree Protocol)` uses these values to determine the -**lowest-cost path** to the root bridge, maintaining a loop-free topology. -Traffic flows through the path with the lowest path cost, while alternate -paths remain in standby. - -A **lower** priority value means **higher** precedence in path selection. - -{abbr}`STP (Spanning Tree Protocol)` considers the port priority only if -multiple member interfaces have the same path costs. -``` - -```{cfgcmd} set interfaces bridge \ member interface \ cost \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **path cost for a -specific member interface within the bridge.** - -Path cost is the primary metric {abbr}`STP (Spanning Tree Protocol)` uses to -determine the path to the root bridge. This value is based on interface -bandwidth; faster interfaces receive lower costs. - -By assigning a lower cost, you give the interface higher precedence during -path selection. -``` - -```{cfgcmd} set interfaces bridge \ member interface \ disable-learning - -**Disable MAC address learning for a specific member interface -within a bridge.** - -When learning is disabled, the bridge will not add source MAC addresses -observed on this port to its forwarding database (FDB). Frames destined -to MACs not present in the FDB are then flooded to all bridge ports -rather than unicast-forwarded. -``` - - -### Bridge options - -Configure how bridge interfaces maintain their {abbr}`FDB (Forwarding Database)` -, react to topology changes, and optimize multicast data streams. - -```{cfgcmd} set interfaces bridge \ aging \ - -**Configure the MAC address aging time for the bridge.** - -The duration in seconds that a MAC address remains in the bridge’s {abbr}`FDB -(Forwarding Database)` before removal if no traffic is received from that -address. - -The default value is 300 seconds. -``` - -```{cfgcmd} set interfaces bridge \ max-age \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **max age timer for -the bridge.** - -The duration in seconds that the bridge waits for a {abbr}`BPDU (Bridge -Protocol Data Unit)` from the root bridge. - -If the bridge does not receive a {abbr}`BPDU (Bridge Protocol Data Unit)` -within this period, it recalculates the path to the root bridge or initiates -a new root bridge election. -``` - -```{cfgcmd} set interfaces bridge \ igmp querier - -**Configure the bridge interface to act as the** {abbr}`IGMP (Internet Group -Management Protocol)`/{abbr}`MLD (Multicast Listener Discovery)` **Querier.** - -**When configured:** The bridge interface sends {abbr}`IGMP (Internet Group -Management Protocol)` (IPv4) and {abbr}`MLD (Multicast Listener Discovery)` -(IPv6) general queries to all connected hosts to identify active multicast -listeners. -``` - -```{cfgcmd} set interfaces bridge \ igmp snooping - -**Configure the bridge interface to perform** {abbr}`IGMP (Internet Group -Management Protocol)`/{abbr}`MLD (Multicast Listener Discovery)` -**snooping.** - -**When configured:** The bridge interface monitors {abbr}`IGMP (Internet Group -Management Protocol)` (IPv4) and {abbr}`MLD (Multicast Listener Discovery)` -(IPv6) join requests and restricts multicast traffic forwarding to only active -listeners. This prevents network flooding. -``` - -(stp)= - -#### STP configuration - -{abbr}`STP (Spanning Tree Protocol)` is a Layer 2 protocol that prevents loops -in Ethernet networks by ensuring only one logical path exists between any two -bridges. This creates a loop-free topology and prevents broadcast storms that -can crash the network. - -By default, {abbr}`STP (Spanning Tree Protocol)` is disabled on bridge interfaces. -To activate loop prevention, you must explicitly enable the protocol and -configure its parameters. - -```{cfgcmd} set interfaces bridge \ stp - -Enable {abbr}`STP (Spanning Tree Protocol)` on the bridge interface. -``` - -```{cfgcmd} set interfaces bridge \ forwarding-delay \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **delay, in seconds, -for the bridge interface.** - -This parameter defines how long the bridge interface remains in the listening -and learning states before forwarding traffic. The delay ensures that the -bridge has sufficient time to detect loops (in the listening state) and learn -the MAC addresses of connected devices (in the learning state). - -The default value is 15 seconds. The total time before forwarding begins is -twice this value. -``` - -```{cfgcmd} set interfaces bridge \ hello-time \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **Hello advertisement -interval, in seconds.** - -This parameter sets the frequency at which the bridge interface transmits -Hello packets ({abbr}`BPDUs (Bridge Protocol Data Units)`). These packets -originate from the root bridge and are propagated by designated bridges. If -neighbors stop receiving Hello packets, they assume a connection failure and -trigger a topology recalculation. - -The default value is 2 seconds. -``` - - -### VLAN - -#### VLAN-aware bridges - -```{cfgcmd} set interfaces bridge \ enable-vlan - -**Enable VLAN filtering (also known as VLAN awareness) on the bridge interface.** - -When enabled, the bridge strictly segregates traffic among VLANs configured -on its member interfaces. - -:::{note} -Do not configure **vif 1** on a VLAN-aware bridge. The main bridge -interface acts as VLAN 1 (the default native VLAN) and automatically -handles all untagged traffic. -::: -``` - -```{cfgcmd} set interfaces bridge \ protocol \<802.1ad | 802.1q\> - -**Configure the VLAN protocol (EtherType) for the bridge interface.** - -The following options are available: -* ``802.1q`` (default): Sets the EtherType to ``0x8100``. Used for standard -enterprise VLANs. -* ``802.1ad``: Sets the EtherType to ``0x88a8``. Used for QinQ (provider bridging). -``` - - -#### VLAN configuration - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: bridge -:var1: br0 -``` - -```{cfgcmd} set interfaces bridge \ member interface \ native-vlan \ - -**Configure the native VLAN ID for a specific member interface within a -VLAN-aware bridge.** - -This assigns the specified ```` to untagged traffic entering the member -interface. The bridge strips the VLAN tag from outgoing traffic matching this -ID. - -**Example:** - -Set the native VLAN ID to 2 for the member interface ``eth0``: - -:::{code-block} none -set interfaces bridge br1 member interface eth0 native-vlan 2 -::: -``` - -```{cfgcmd} set interfaces bridge \ member interface \ allowed-vlan \ - -**Configure allowed VLAN IDs for a specific member interface within a -VLAN-aware bridge.** - -Enter a single VLAN ID or a range of VLAN IDs separated by a hyphen. - -**Example:** - -To allow VLAN ID 4 on member interface ``eth0``: - -:::{code-block} none -set interfaces bridge br1 member interface eth0 allowed-vlan 4 -::: -**Example:** - -To allow VLAN IDs 6 through 8 on member interface ``eth0``: - -:::{code-block} none -set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 -::: -``` - - -### SPAN port mirroring - -```{cmdincludemd} ../../_include/interface-mirror.txt -:var0: bridge -:var1: br1 -:var2: eth3 -``` - - -## Examples - -### Configure a standard bridge - -The following example creates a bridge named br100 with {abbr}`STP (Spanning -Tree Protocol)` enabled. - -Configuration requirements: -- **Bridge name:** `br100` -- **Member interfaces:** Physical interface `eth1` and VLAN interface `eth2.10`. -- **STP:** Enabled. -- **Bridge IP addresses:** `192.0.2.1/24` (IPv4) and `2001:db8::ffff/64` (IPv6). - -```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 -``` - -Verify the configuration: - -```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 -``` - - -### Configure a VLAN-aware bridge - -The following example creates a VLAN-aware bridge named br100. In this setup, -one member interface is configured as a trunk port, and the other as an access -port. The VLAN interface is configured with IP addresses. - -**Configuration requirements:** -- **Bridge name:** `br100`. -- **Trunk port** (`eth1`): Handles **tagged** traffic for VLAN 10. -- **Access port** (`eth2`): Handles **untagged** traffic (assigned to native - VLAN 10). -- **STP:** Enabled. -- **VLAN IP addresses** (`vif 10`): `192.0.2.1/24` (IPv4) and - `2001:db8::ffff/64` (IPv6). - -```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 -``` - -Verify the configuration: - -```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 - } -``` - - -### Operation - -```{opcmd} show bridge - -Show the status of member interfaces for all configured bridges. - -:::{code-block} none -vyos@vyos:~$ show bridge -3: eth1: mtu 1500 master br0 state forwarding -priority 32 cost 100 -4: eth2: mtu 1500 master br0 state forwarding -priority 32 cost 100 -::: -``` - -```{opcmd} show bridge \ fdb - -Show the {abbr}`FDB (Forwarding Database)` for the specified bridge. - -:::{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 \ mdb - -Show the {abbr}`MDB (Multicast group Database)` for the specified bridge. - -The {abbr}`MDB (Multicast group Database)` is populated by {abbr}`IGMP -(Internet Group Management Protocol)`/{abbr}`MLD (Multicast Listener -Discovery)` snooping and lists the multicast groups currently active on the -bridge. - -:::{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 \ macs - -Show the learned {abbr}`MAC (Media Access Control)` address table for the -specified bridge. - -:::{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 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-dummy.md b/docs/configuration/interfaces/md-dummy.md deleted file mode 100644 index d2d27c5d..00000000 --- a/docs/configuration/interfaces/md-dummy.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -lastproofread: '2026-01-23' ---- - -(dummy-interface)= - -# Dummy - -A dummy interface is a virtual network interface that operates like the -loopback interface, accepting traffic and routing it back to the local host. -Unlike the loopback interface, which is limited to one per system and reserved -for internal system use, multiple dummy interfaces can be created, removed, and -managed without impacting core operations. - -As a software-based interface, the dummy interface does not depend on physical -link state and remains active as long as the operating system is running. - -Dummy interfaces are commonly used in environments with multiple redundant -uplinks (e.g., a server connected to two different switches), where assigning a -management IP address to a specific physical interface is risky. If that -interface fails, the management IP address becomes unreachable. - -Assigning the management IP address to a dummy interface and advertising it -over all available physical links ensures the address remains reachable as long -as at least one physical path is active. - -Dummy interfaces are also used for testing and simulation purposes. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: dummy -:var1: dum0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: dummy -:var1: dum0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: dummy -:var1: dum0 -``` - -```{cmdincludemd} /_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 \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces dummy dum0 -dum0: 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 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-ethernet.md b/docs/configuration/interfaces/md-ethernet.md deleted file mode 100644 index eac0b443..00000000 --- a/docs/configuration/interfaces/md-ethernet.md +++ /dev/null @@ -1,515 +0,0 @@ ---- -lastproofread: '2026-01-19' ---- - -(ethernet-interface)= - -# Ethernet - -Ethernet interfaces (e.g., `eth0`, `eth1`) represent the host's physical -or virtual network ports. - -They are the most common interface type, serving as the base layer upon which -IP addresses, VLANs, and tunnels are configured to carry traffic across both -LANs and WANs. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: ethernet -:var1: eth0 -``` - -```{cfgcmd} set interfaces ethernet \ switchdev - -**Enable** ``switchdev`` **mode for the interface.** - -In ``switchdev`` mode, the interface offloads traffic switching between ports -to the hardware, bypassing the host CPU. This increases the interface’s -traffic-handling capacity and reduces its forwarding delay. -``` - -:::{note} -`switchdev` mode is available only on certain physical network -interfaces and requires a switchdev-compatible driver. -::: - -### Ethernet options - -```{cfgcmd} set interfaces ethernet \ duplex \ - -**Configure duplex mode for the interface.** - -The following duplex modes are available: - -* ``auto``: The interface negotiates the duplex mode with the connected device. -* ``full``: The interface sends and receives data simultaneously. The - connected device must also be set to full-duplex to avoid a duplex mismatch. -* ``half``: The interface either sends or receives data, but not both at the - same time. - -The default duplex mode is ``auto``. -``` - -```{cfgcmd} set interfaces ethernet \ speed \ - -**Configure the interface's speed, in Mbit/s.** - -The following options are available: - -* ``auto``: The interface negotiates the speed with the connected device. -* ``10, 100, 1000 ...``: The interface operates at the selected speed. The - connected device must be set to the same speed to establish a connection. - -The default option is ``auto``. -``` - -```{cfgcmd} set interfaces ethernet \ ring-buffer rx \ - -**Configure the receive (RX) ring buffer size for the interface.** - -The RX ring buffer size defines the number of incoming packets the interface -can queue in hardware before the CPU processes them. - -Higher values reduce the risk of drops when the NIC receives network traffic -faster than the CPU can process it, though latency may increase. Lower values -reduce latency but increase the risk of packet drops during incoming traffic -bursts. - -To view supported values for a specific interface, use: -``` - -```none -ethtool -g -``` - -```{cfgcmd} set interfaces ethernet \ ring-buffer tx \ - -**Configure the transmit (TX) ring buffer size.** - -The TX ring buffer size defines the number of outgoing packets the interface -can queue in hardware before they are transmitted onto the network. - -Higher values reduce the risk of drops when the CPU generates traffic faster -than the NIC can handle, though latency may increase. Lower values reduce -latency but increase the risk of packet drops during outgoing traffic bursts. - -To view supported values for a specific interface, use: -``` - -```none -ethtool -g -``` - - -#### Interrupt Coalescing - -Interrupt coalescing is a mechanism that reduces CPU interrupt load by bundling -multiple packets into a single interrupt event instead of interrupting -the CPU for every packet arrival or transmission. - -:::{note} -Not all network drivers or virtual interfaces support all -coalescing parameters. Use `ethtool --show-coalesce ` -to verify which settings are supported by your hardware and driver. -::: - -**Basic adaptive coalescing** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing adaptive-rx - -``` -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing adaptive-tx - -Enable adaptive interrupt coalescing. The NIC automatically tunes RX/TX -interrupt pacing based on traffic patterns to reduce CPU utilization -during high throughput while preserving latency at low packet rates. -``` - -**Basic interrupt delay** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs \<0-16384\> -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs \<0-16384\> - -Set the delay in microseconds before generating an RX/TX interrupt after -receiving or transmitting a packet. Lower values reduce latency; higher -values reduce CPU load. -``` - -**Interrupt frame thresholds** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frames \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frames \ - -Generate an RX/TX interrupt only after the specified number of packets -have been received or transmitted. -``` - -**IRQ-specific coalescing** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frames-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frames-irq \ - -Control interrupt coalescing parameters while the driver is already -servicing an interrupt (IRQ context). These settings allow finer tuning -of interrupt behavior under sustained load. -``` - -**Adaptive rate thresholds** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing pkt-rate-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing pkt-rate-high \ - -Define packet-rate thresholds (packets per second) used by adaptive -coalescing to switch between low-rate and high-rate interrupt coalescing -profiles. -``` - -**Low-rate adaptive parameters** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frame-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frame-low \ - -Interrupt coalescing parameters applied when the packet rate is below -``pkt-rate-low``. Typically optimized for lower latency. -``` - -**High-rate adaptive parameters** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frame-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frame-high \ - -Interrupt coalescing parameters applied when the packet rate exceeds -``pkt-rate-high``. Typically optimized for maximum throughput and -reduced CPU utilization. -``` - -**Statistics and sampling** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing stats-block-usecs \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing sample-interval \ - -Control how frequently coalescing statistics are updated and how often -the NIC samples traffic rates for adaptive coalescing decisions. -``` - -**Completion queue (CQE) mode** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing cqe-mode-rx -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing cqe-mode-tx - -Enable RX/TX Completion Queue Entry (CQE) mode, if supported by the -driver. CQE mode can improve performance on high-speed NICs by -optimizing completion handling. -``` - -**Transmit aggregation** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-max-bytes \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-max-frames \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-time-usecs \ - -Control transmit packet aggregation. Packets may be buffered and sent -together until one of the configured limits (bytes, frames, or time) -is reached, reducing interrupt and DMA overhead. -``` - -#### Offloading - -```{cfgcmd} set interfaces ethernet \ offload \ - -**Configure the offloading features for the interface.** - -The interface offloading features define whether specific packet-processing tasks -are performed by hardware (the NIC) or by software (the kernel). You can enable -multiple offloading features for a single interface. - - * ``lro`` **(Large Receive Offload):** Instructs the NIC to merge multiple - incoming packets into one larger packet before sending it to the CPU. - - :::{note} - {abbr}`LRO (Large Receive Offload)` hardware support is often limited - to TCP/IPv4 packets. For details on LRO limitations, see - https://lwn.net/Articles/358910/ - ::: - :::{warning} - {abbr}`LRO (Large Receive Offload)` irreversibly alters packet - headers during merging. This prevents the merged packet from being correctly - split back into the original packets, causing packet drops and forwarding - failures on routers and bridges. Use {abbr}`LRO (Large Receive Offload)` only - for end-hosts that do not forward traffic. - ::: - * ``tso`` **(TCP Segmentation Offload):** Instructs the NIC to split large TCP - packets into smaller ones before transmitting them to the network. - - **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled - for {abbr}`TSO (TCP Segmentation Offload)` to work. Additionally, {abbr}`GSO - (Generic Segmentation Offload)` should be enabled as a safety fallback; it - ensures that if traffic is rerouted to hardware without {abbr}`TSO (TCP - Segmentation Offload)` support, the kernel can still segment the packets, - preventing transmission failures. - - * ``gso`` **(Generic Segmentation Offload):** Instructs the kernel to split - large packets into smaller ones before sending them to the NIC. - - {abbr}`GSO (Generic Segmentation Offload)` serves as a software fallback for - hardware that does not support {abbr}`TSO (TCP Segmentation Offload)` or for - protocols (like UDP) that hardware cannot offload. - - **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled - for {abbr}`GSO (Generic Segmentation Offload)` to work. - - * ``gro`` **(Generic Receive Offload):** Instructs the kernel to merge multiple - incoming packets into one larger packet before passing it to upper protocol - layers. - - Unlike LRO, GRO preserves the necessary packet metadata so the merged packet - can be correctly split back into the original packets. This makes GRO safe for - use on routers and bridges. - - :::{note} -The exception is for IPv4 IDs. If the "Don't Fragment" (DF) bit is -set and IDs are not sequential, {abbr}`GSO (Generic Segmentation Offload)` -alters them to maintain a consistent sequence for {abbr}`GSO (Generic -Segmentation Offload)` compatibility. - ::: - * ``rps`` **(Receive Packet Steering):** Instructs the kernel to distribute - the processing of incoming packets across multiple CPU cores. - - The kernel calculates a hash from packet headers (IP addresses and ports) to - ensure packets from the same flow are processed by the same CPU core. - - :::{note} -{abbr}`RPS (Receive Packet Steering)` is a software version of -{abbr}`RSS (Receive Side Scaling)` and is useful for NICs without hardware -multi-queue support. - ::: - * ``sg`` **(Scatter-Gather/Scatter-Gather DMA):** Instructs the NIC to fetch - data fragments from various RAM locations and transmit them as a single packet - to the network, eliminating the need for the kernel to copy them into a - contiguous block first. -``` - -#### 802.1X (EAPOL) authentication - -```{cmdincludemd} /_include/interface-eapol.txt -:var0: ethernet -:var1: eth0 -``` - -#### EVPN Multihoming - -Uplink/core tracking. - -```{cmdincludemd} /_include/interface-evpn-uplink.txt -:var0: ethernet -:var1: eth0 -``` - -### VLAN -#### Regular VLANs (802.1q) - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: ethernet -:var1: eth0 -``` - -#### 802.1ad (QinQ) - -```{cmdincludemd} /_include/interface-vlan-8021ad.txt -:var0: ethernet -:var1: eth0 -``` - -### SPAN port mirroring - -```{cmdincludemd} ../../_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 \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth0 -eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 - link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff - inet6 fe80::250:44ff:fe00:f5c9/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 56735451 179841 0 0 0 142380 - TX: bytes packets errors dropped carrier collisions - 5601460 62595 0 0 0 0 -::: -``` - -```{opcmd} show interfaces ethernet \ physical - -Show interface hardware-level and driver details. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth0 physical -Settings for eth0: - Supported ports: [ TP ] - Supported link modes: 1000baseT/Full - 10000baseT/Full - Supported pause frame use: No - Supports auto-negotiation: No - Supported FEC modes: Not reported - Advertised link modes: Not reported - Advertised pause frame use: No - Advertised auto-negotiation: No - Advertised FEC modes: Not reported - Speed: 10000Mb/s - Duplex: Full - Port: Twisted Pair - PHYAD: 0 - Transceiver: internal - Auto-negotiation: off - MDI-X: Unknown - Supports Wake-on: uag - Wake-on: d - Link detected: yes -driver: vmxnet3 -version: 1.4.16.0-k-NAPI -firmware-version: -expansion-rom-version: -bus-info: 0000:0b:00.0 -supports-statistics: yes -supports-test: no -supports-eeprom-access: no -supports-register-dump: yes -supports-priv-flags: no -::: -``` - -```{opcmd} show interfaces ethernet \ physical offload - -Show the status of the interface offloading features. - -:::{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 \ transceiver - -Show information about the transceiver module plugged into the interface -(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 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-geneve.md b/docs/configuration/interfaces/md-geneve.md deleted file mode 100644 index 1fce1119..00000000 --- a/docs/configuration/interfaces/md-geneve.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -lastproofread: '2026-02-02' ---- - -(geneve-interface)= - -# Geneve - -{abbr}`Geneve (Generic Network Virtualization Encapsulation)` interfaces -operate as virtual network ports. Administrators can apply standard network -configurations on them, such as IP addressing, bridging, or firewall rules, -just as they would on physical Ethernet ports. - -The Geneve protocol encapsulates Layer 2 Ethernet frames originating from -endpoints such as virtual machines, containers, or physical servers inside UDP -packets. It unifies the features of earlier encapsulation protocols, including -VXLAN, NVGRE, and STT, and addresses their limitations, such as fixed header -structures and a lack of metadata support. Because of its extensibility, Geneve -may eventually replace those older protocols. - -Geneve tunnels are used to connect virtual switches residing within -hypervisors, physical switches, middleboxes, and other network appliances. - -Geneve tunnels operate over any standard IP network. In larger deployments, -the underlying network (underlay) is often built using a **Clos** topology, -also known as a *leaf-and-spine* or *fat-tree* topology. - -Geneve header: - -```none -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -|Ver| Opt Len |O|C| Rsvd. | Protocol Type | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Virtual Network Identifier (VNI) | Reserved | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Variable Length Options | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -``` - - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-mac.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-ip.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: geneve -:var1: gnv0 -``` - - -### Geneve options - -```{cfgcmd} set interfaces geneve gnv0 remote \ - -Configure the remote endpoint IP address for the Geneve tunnel. -``` - -```{cfgcmd} set interfaces geneve gnv0 vni \ - -**Configure** {abbr}`VNI (Virtual Network Identifier)` **for the Geneve -interface.** - -The VNI is a virtual network identifier. It allows multiple virtual networks to -share the same physical infrastructure and remain isolated. - -The VNI is also used to distribute traffic after it leaves the tunnel, for -example, to map packets with overlapping IP addresses to specific routing -tables. -``` - -```{cfgcmd} set interfaces gnv0 \ port \ - -**Configure the destination UDP port for the remote Geneve tunnel endpoint.** -Ensure the remote peer is configured to listen on this specific port. -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md deleted file mode 100644 index 9082cd80..00000000 --- a/docs/configuration/interfaces/md-index.md +++ /dev/null @@ -1,26 +0,0 @@ -# Interfaces - -```{toctree} -:includehidden: true -:maxdepth: 1 - -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/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md deleted file mode 100644 index 324840fa..00000000 --- a/docs/configuration/interfaces/md-l2tpv3.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -lastproofread: '2026-02-05' ---- - -(l2tpv3-interface)= - -# L2TPv3 - -{abbr}`L2TPv3 (Layer 2 Tunneling Protocol version 3)` interfaces let you -establish L2TPv3 tunnels to transport Layer 2 traffic over IP networks. - -The L2TPv3 protocol (defined in RFC 3931) wraps Layer 2 frames (e.g., Ethernet, -Frame Relay, HDLC) within IP packets, allowing them to traverse the underlying -IP infrastructure. - -Unlike L2TPv2, which strictly requires UDP encapsulation, the L2TPv3 protocol -is more flexible and supports two encapsulation types: - -> - **Direct IP:** Tunnel data is encapsulated directly inside IP packets -> (Protocol 115) for lower overhead. -> - **UDP:** Tunnel data is encapsulated inside a UDP datagram. This allows the -> tunnel to traverse NAT more easily. - -L2TPv3 tunnels connect geographically separated sites, serving as a simpler -alternative to {ref}`mpls` by operating over basic IP connectivity rather than -requiring a full MPLS infrastructure. - -L2TPv3 tunnels can be established over both IPv4 and IPv6 underlying networks. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-without-dhcp.txt -:var0: l2tpv3 -:var1: l2tpeth0 -``` - - -### L2TPv3 options - -Use the following commands to configure the L2TPv3 tunnel's specific parameters. - -```{cfgcmd} set interfaces l2tpv3 \ encapsulation \ - -**Configure the encapsulation type for the L2TPv3 tunnel.** - -Valid values are ``udp`` and ``ip``. - -The default encapsulation type is ``udp``. -``` - -:::{note} -The encapsulation type must match on both the local and remote peers -for the tunnel to establish. -::: - -```{cfgcmd} set interfaces l2tpv3 \ source-address \ - -**Configure the L2TPv3 tunnel source IP address.** - -The specified address must be a local interface IP address and can be either -IPv4 or IPv6. -``` - -```{cfgcmd} set interfaces l2tpv3 \ remote \ - -**Configure the L2TPv3 tunnel destination IP address.** - -The specified address must be a remote peer’s interface IP address and can be -either IPv4 or IPv6. -``` - -```{cfgcmd} set interfaces l2tpv3 \ session-id \ - -**Configure the local session ID within the L2TPv3 tunnel.** - -The ``session-id`` is a 32-bit value that identifies an incoming tunnel session -on the local peer. - -The ``peer-session-id`` that identifies this session on the remote peer must be -set to the same value. -``` - -```{cfgcmd} set interfaces l2tpv3 \ peer-session-id \ - -**Configure the peer session ID within the L2TPv3 tunnel.** - -The ``peer-session-id`` is a 32-bit value that identifies an outgoing tunnel -session from the local peer. - -The ``peer-session-id`` must match the ``session-id`` configured for this -session on the remote peer. -``` - -```{cfgcmd} set interfaces l2tpv3 \ tunnel-id \ - -**Configure the local identifier for the L2TPv3 tunnel.** - -The ``tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on the -local peer. - -The ``peer-tunnel-id`` that identifies this tunnel on the remote peer must be -set to the same value. -``` - -```{cfgcmd} set interfaces l2tpv3 \ peer-tunnel-id \ - -**Configure the peer identifier for the L2TPv3 tunnel.** - -The ``peer-tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on -the remote peer and must correspond to the ``tunnel-id`` configured for that -tunnel on that peer. - -The ``peer-tunnel-id`` must match the ``tunnel-id`` that identifies this tunnel -on the remote peer. -``` - - -## Example - -### L2TPv3 tunnel with IP encapsulation - -The following example shows the configuration of an L2TPv3 tunnel using direct -IP encapsulation: - -```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 must be applied to the remote peer. - -### L2TPv3 tunnel with UDP encapsulation - -The following example shows the configuration of an L2TPv3 tunnel using UDP -encapsulation. - -This setup is recommended when the tunnel traverses NAT devices. - -Configuration notes: -- Use a local LAN IP address as the `source-address`. -- Configure a forwarding rule to allow tunnel traffic on the specified UDP port - on the upstream NAT device. -- Use a distinct UDP port for each individual tunnel. - -```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 -} -``` diff --git a/docs/configuration/interfaces/md-loopback.md b/docs/configuration/interfaces/md-loopback.md deleted file mode 100644 index 72f14c16..00000000 --- a/docs/configuration/interfaces/md-loopback.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -lastproofread: '2026-01-23' ---- - -(loopback-interface)= - -# Loopback - -The loopback interface is a virtual, software-based network interface. All -traffic sent to it loops back and only targets services on the local host. - -:::{note} -Only one loopback `lo` interface is allowed per operating system. -If you require multiple virtual interfaces, use the {ref}`dummy-interface` -interface type. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: loopback -:var1: lo -``` - -```{cmdincludemd} /_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 interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces loopback lo -lo: 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 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-macsec.md b/docs/configuration/interfaces/md-macsec.md deleted file mode 100644 index b3c70362..00000000 --- a/docs/configuration/interfaces/md-macsec.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -lastproofread: '2026-02-13' ---- - -(macsec-interface)= - -# MACsec - -MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in -2006\. It enables protocol-independent connectivity between two hosts, providing -data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec -operates at the Ethernet layer as a Layer 2 protocol and secures traffic within -Layer 2 networks, including DHCP and ARP requests. It does not compete with -other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each -addresses distinct use cases. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: macsec -:var1: macsec0 -``` - - -### MACsec options - -```{cfgcmd} set interfaces macsec \ security cipher \ - -**Configure the cipher suite for the MACsec interface.** - -This configuration parameter is mandatory. -``` - -```{cfgcmd} set interfaces macsec \ security encrypt - -**Enable encryption on the MACsec interface.** - -By default, MACsec interfaces only provide authentication; encryption is -optional. -When enabled, outgoing packets are encrypted using the configured cipher suite. -``` - -```{cfgcmd} set interfaces macsec \ source-interface \ - -**Configure a physical source interface for the MACsec interface.** - -Traffic transmitted through this interface is authenticated and, if configured, -encrypted. -``` - - -#### MACsec key management - -**Static** {abbr}`SAK (Secure Authentication Key)` **mode** - -In static SAK mode, administrators must manually configure and update SAKs on -each MACsec peer. {abbr}`MKA (MACsec Key Agreement protocol)` cannot be used in -this mode. - -```{cfgcmd} set interfaces macsec \ security static key \ - -**Configure the Transmit (TX) SAK for the MACsec interface.** - -The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal -string. -``` - -```{cfgcmd} set interfaces macsec \ security static peer \ mac \ - -**Configure the MAC address associated with the MACsec peer.** -``` - -```{cfgcmd} set interfaces macsec \ security static peer \ key \ - -**Configure the RX SAK for traffic from the MACsec peer.** - -The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal -string. -``` - -```{cfgcmd} set interfaces macsec \ security static peer \ disable -``` - -**Dynamic** {abbr}`MKA (MACsec Key Agreement protocol)` **mode** - -In this mode, the {abbr}`MKA (MACsec Key Agreement protocol)` protocol is used -to generate, distribute, and update {abbr}`CAKs (MACsec Connectivity -Association Keys)`, and to authenticate MACsec peers. - -```{cfgcmd} set interfaces macsec \ security mka cak \ - -**Configure the** {abbr}`CAK (MACsec Connectivity Association Key)` **for the -MACsec interface.** - -The {abbr}`CAK (MACsec Connectivity Association Key)` and its {abbr}`CKN -(MACsec Connectivity Association Key Name)` form the pre-shared master key pair -used to authenticate MACsec peers. -``` - -```{cfgcmd} set interfaces macsec \ security mka ckn \ - -Configure the {abbr}`CKN (MACsec Connectivity Association Key Name)` for the -MACsec interface. -``` - -```{cfgcmd} set interfaces macsec \ security mka priority \ - -Configure the MKA key server priority for the MACsec interface. -The peer with the lowest priority is elected as the key server. -``` - -#### Replay protection - -```{cfgcmd} set interfaces macsec \ security replay-window \ - -The replay protection window defines how many out-of-order frames can be -received before they are dropped as a potential replay attack. -The following values are valid: -- ``0``: Any out-of-order frame is immediately dropped. -- ``1-4294967295``: Allows the specified number of out-of-order frames. -``` - -## Operation - -```{opcmd} run generate macsec mka cak \ - -Generate a 128-bit (GCM-AES-128) or 256-bit (GCM-AES-256) {abbr}`MKA (MACsec -Key Agreement protocol)` {abbr}`CAK (MACsec Connectivity Association Key)`. - -:::{code-block} none -vyos@vyos:~$ generate macsec mka cak gcm-aes-128 -20693b6e08bfa482703a563898c9e3ad -::: -``` - -```{opcmd} run generate macsec mka ckn - -Generate an {abbr}`MKA (MACsec Key Agreement protocol)` {abbr}`CAK (MACsec -Connectivity Association Key)`. - -:::{code-block} none -vyos@vyos:~$ generate macsec mka ckn -88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 -::: -``` - -```{opcmd} show interfaces macsec - -Show 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 \ - -Show information for a specific MACsec interface. - -:::{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 - -**Site-to-site MACsec with dynamic MKA over an untrusted network** - -In the following example, two routers (R1 and R2) are connected via an -untrusted switch, using their `eth1` interfaces as the underlay. The MACsec -interface (`macsec1`) with dynamic MKA encrypts traffic between them. - -Topology details: -- R1 IP addresses: `192.0.2.1/24` and `2001:db8::1/64`. -- R2 IP addresses: `192.0.2.2/24` and `2001:db8::2/64`. - -**R1** - -```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** - -```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 traffic on `eth1` confirm that -the content is encrypted. - -```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 encryption on the MACsec interface by removing the `security -encrypt` option shows the unencrypted but authenticated content. - -```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.( -``` - -**Site-to-site MACsec with static SAK over an untrusted network** - -This example uses the same topology as above, but applies static SAK mode to -the MACsec interface configuration. - -**R1** - -```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** - -```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 R1 mac 00:11:22:33:44:01 -set interfaces macsec macsec1 security static peer R1 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' -set interfaces macsec macsec1 source-interface 'eth1' -``` - -## MACsec over WAN - -MACsec offers an alternative to traditional tunneling solutions by securing -Layer 2 with integrity, origin authentication, and optional encryption. - -While typically deployed between hosts and access switches, MACsec can also -secure traffic over a WAN. In the following example, we combine VXLAN (for -transport) and MACsec (for security) to create a secure tunnel between two -sites. - -**R1 MACsec01** - -```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** - -```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/md-openvpn-examples.md b/docs/configuration/interfaces/md-openvpn-examples.md deleted file mode 100644 index 817e6868..00000000 --- a/docs/configuration/interfaces/md-openvpn-examples.md +++ /dev/null @@ -1,769 +0,0 @@ -# Site-to-site - -:::{todo} -Convert raw command blocks in this file to cfgcmd/opcmd directives for command coverage tracking. -::: - -OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, it is effective for quickly establishing tunnels between routers. - -As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. - -Pre-shared key mode is now deprecated and will be removed from future OpenVPN versions. VyOS will also discontinue support for this option because pre-shared keys are significantly less secure than TLS. - -We will configure OpenVPN with 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 VPN endpoint is 198.51.100.10. -- The public IP address of the remote VPN endpoint is 203.0.113.11. -- The tunnel uses 10.255.1.1 for the local IP address and 10.255.1.2 for the remote IP address. -- The local site has a subnet of 10.0.0.0/16. -- The remote site has a subnet of 10.1.0.0/16. -- The official OpenVPN port 1194 is reserved for client VPN. For site-to-site VPN, port 1195 is used. -- The `persistent-tunnel` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface. -- If known, the remote router\'s IP address can be configured using the `remote-host` directive. If unknown, it can be omitted. We assume the remote router has a dynamic IP address. - -![](/_static/images/openvpn_site2site_diagram.webp) - -## Set up site-to-site certificates - -Deploying a complete Public Key Infrastructure (PKI) with a Certificate Authority (CA) would overcomplicate site-to-site OpenVPN setups, which are primarily designed for simplicity. To keep their configuration simple without compromising security, VyOS 1.4 and later lets you verify self-signed certificates using certificate fingerprints. - -Generate a self-signed certificate on each router, preferably using the Elliptic Curve (EC) type. In configuration mode, run the following command: `run generate pki certificate self-signed install `. This adds the certificate to the configuration session\'s `pki` subtree. Review and commit the changes. - -``` 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, retrieve its SHA-256 fingerprint. Since OpenVPN currently supports only SHA-256 fingerprints, use the following command: - -``` 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 are arbitrary. While `openvpn-local` and `openvpn-remote` are used here, you may choose any names. -:::: - -Repeat the procedure on the other router. - -## Set up site-to-site OpenVPN - -Local configuration: - -``` 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 # The output of 'run show pki certificate fingerprint sha256' on the remote router -set interfaces openvpn vtun1 tls role active -``` - -Remote configuration: - -``` 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 # The output of 'run show pki certificate fingerprint sha256 on the local router -set interfaces openvpn vtun1 tls role passive -``` - - -## Set up pre-shared keys - -Before VyOS 1.4, site-to-site OpenVPN without PKI required pre-shared keys. This option is still available but is deprecated and will be removed in future releases. If you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, you still need to use pre-shared keys. - -First, generate a key by running `run generate pki openvpn shared-secret install ` in configuration mode. You can use any name; in this example, we use `s2s`. - -``` 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] -``` - -Next, install the key on the remote router: - -``` none -vyos@remote# set pki openvpn shared-secret s2s key -``` - -Finally, configure the key in your OpenVPN interface settings: - -``` none -set interfaces openvpn vtun1 shared-secret-key s2s -``` - - -## Set up firewall exceptions - -To allow OpenVPN traffic to pass through the WAN interface, create a firewall exception: - -``` 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' -set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'related' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 action 'accept' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 description 'OpenVPN_IN' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port '1195' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 log -set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol 'udp' -``` - -Apply the OUTSIDE_LOCAL firewall group to the WAN interface and to the input filter for traffic destined for the router itself: - -``` none -set firewall ipv4 input filter rule 10 action 'jump' -set firewall ipv4 input filter rule 10 inbound-interface name eth0 -set firewall ipv4 input filter rule 10 jump-target OUTSIDE_LOCAL -``` - -Static routing: - -Configure static routes by referencing the tunnel interface. For example, if the local router\'s network is `10.0.0.0/16` and the remote router\'s network is `10.1.0.0/16`, define the routes as follows: - -Local configuration: - -``` none -set protocols static route 10.1.0.0/16 interface vtun1 -``` - -Remote configuration: - -``` none -set protocols static route 10.0.0.0/16 interface vtun1 -``` - -As with standard Ethernet interfaces, you can apply firewall policies to the tunnel interface for input, output, and forward directions. - -If you use multiple tunnels, OpenVPN must distinguish between them beyond just the pre-shared key. To achieve this, assign either unique IP addresses or unique ports to each tunnel. - -Verify OpenVPN status using the show openvpn operational commands. - -``` none -vyos@vyos:~$ show openvpn site-to-site - -OpenVPN status on vtun1 - -Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ------------ ----------------- ----------- ------------ ---------- ---------- ----------------- -N/A 10.110.12.54:1195 N/A N/A 504.0 B 656.0 B N/A -``` - - -### Server-client - -In OpenVPN's server-client mode, the server acts as a central hub, allowing multiple clients to connect and securely route their traffic or access a private network. Multi-client server is the most popular OpenVPN mode for routers. - -## Set up server-client certificates - -Server-client mode always uses x.509 authentication and therefore requires a PKI setup. The PKI utility now simplifies the creation of Certificate Authorities (CAs), server and client certificates, and Diffie-Hellman keys directly in VyOS using configuration or operational mode commands. - -On the server, generate all certificates by running the following commands in configuration mode. The certificates will be added to the configuration session\'s PKI subtree. - -Certificate Authority (CA): - -``` none -vyos@vyos# run generate pki ca install ca-1 -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -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) ca-1 -Enter how many days certificate will be valid: (Default: 1825) -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] -+ ca ca-1 { -+ certificate "MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4EFgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZzph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHwY6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZWXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyxzRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55YmtmctGO2o+NBCFi0=" -+ private { -+ key "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAECggEAZdykF6wV8Z4n8NsoG4j8E/ZJbWEhWjO3x1y3JNutJw735LhmmysMSsreToXtxGfgYRTgNwt5l7oHoqmGHCsLxO1NBb5A7JBllIkIwUYqn31syOJofg0NsJpuwZ2zVLfvWe5mGg4tV2lvVPNEWXWwbp+Ow2KLcFWXkA+H8tFuW6F2mH3ntYlIi/WiCNjsEotNx8Kk7OVwt43DbkN/rbF5lxquuLedaSspOHuhIAOfZB5ZySfqohQalSAaguVD66rGPMrerZ2Vc7B1iJ6Mn/KZrSaQeHwyWrwDDHdzVwG9waydevtGTVO0dvH4etWnRypDx8p1FPJJKD4XVcsl3rR6oQKBgQD497Ep2RJcbNnKVj+kNXGriSGmyRSp6CL61KotepzgucK0RtGMeFJge56/otMHMAxIOcDMX6vRn2MB2pqVqwqUBQy6JfLrSemdpIjMN9xlX6Dw3BWP39SdewZ896/Eo0Q1ythMj1ORp+u3PqOlSa14Cy9aPwDWmNy2deD68YDnsQKBgQDpZE/T84BMQ0FzL6NRijZRzR6Dc775hRfmmSTYI0KqpG0gXNSc5UgrWSLN5H7fnx36mT01P7UkgXCInV0AlJOfkt4a8QTqM1Fh/rZbLLWpQE55S6Fs28GDiFYl2kvZT/TtxhA/E0POf/YXl/8KITS7ZVAZxE8rxBe1hVUfDbnlCwKBgQDeWUguGaGeTdCMNk8MNnbYPdaCAB+mRp3G6ls51sF4qi5Lltva2jKn3H/AoohZaP3vGzUm0WLACdsAct2QQXtnCsN9FBtJK2+qzKEn0dPR7X/s3IGdRse6BX+b6BFgSnfGmuxmI7L86L1JoHXCTnTQOx0FOjNjdI3ZnplZRIpdYQKBgFJacASU9l9yl+SiGZnLEDG7FBpEPE3lVbKrtSGDB6IY1NzHhMo76URKdop6Jv6XMcfcTIm+ihdwiRnblRaAVrrG4xJUm2xcYUoXy5bOZudq5oXMVxCHVngoImXG6l6q5P0Fl3P6Q0HZSye2HWsgnm/FZwdAisMhtU/61TdY65BTAoGBAM4jKeImiXta5lz1RgNiW/TPhft3UbOLj3TbzchNCNAamqCv4Tmh9YKB2d/mz2hNxbnAGe2cYn4iRYKcjJLMZ0UfBL2WxlrgQYQPPGzSD0fH1pLIXPohpBZpsGqNR3Nc8Jd+Uw3IiIJ2oxPCOPTOJsklNB0Xf1AlUUagB16bhhZZ" -+ } -+ } - -[edit] -vyos@vyos# commit -``` - -Server certificate: - -``` none -vyos@vyos# run generate pki certificate sign ca-1 install srv-1 -Do you already have a certificate request? [y/N] N -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -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) srv-1 -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) 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] -+ srv-1 { -+ certificate "MIIDrDCCApSgAwIBAgIULpu+qZjfG01kUI58XNmqXbQC3qQwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTMxMDJaFw0yNjA2MTExMTMxMDJaMFUxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDjAMBgNVBAMMBXNydi0xMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAysTrMfVH63aVidJT7bIf+zLwkLse07nGsv4aliGEbufr239RBHV4Jn8LbQ+nB/8mhYGjNY4OnZ7NYz3FU/iglo8qFtaZ26mWtPWpv2xW1F8JAEK7l5BAg42cBucxiIZFeRm+jkE6VN1bcNU0utnn3sbCwZMyH6pS9k08G1qrrFLA7ZFhv5AmgJcODmO8sigSAu7rRS/6O3eO6ICnVjvIfHLb+9DKKUEffHzFV8RrkqVCGmgisz9fF+j1Rvg9s+ylNc2lZJTbb1XnzixvSRro4t9I3uIWdpJ0iOu09YiTXGQgH9ER6V3rFiX00RdSiSXf+MJCV64hC1msg+8V3Nrw9QIDAQABo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUzH0h4vBxma89HF9rUQ+DW052c5swHwYDVR0jBBgwFoAUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAI/Cyd0y7AJ7wY3yRssCud2iJAl9/ZjgxzXOUo6ibawYIYOnSf9tS3eD4CIH4BgppDXoJZ/qEA4WvIsLx3yvnyOxiqyk3TQmKIZ27VJH+yQkgzPeiKrHn1pCXBKEb1/jlT8Ozu4Lmn/oFwDH6nk8toxI8DM+qsTxqUFlTA3ea9yaRtxeNPMWJdaxZSUYGVSZL0wVKw5ZuQ1Gn7vGVApWlYDKYbMozCuZUG1q8wMzFBRa7x0anvh5hM4bksLz+Y1ujCS8f8b4Xtb8KIdFrZtTvtl97crv62bN05VueAcbwtYbIBNWNoT/CvmqV7k3uPg95GYSNddFqEMbQHoyd8hdDCo=" -+ private { -+ key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDKxOsx9UfrdpWJ0lPtsh/7MvCQux7Tucay/hqWIYRu5+vbf1EEdXgmfwttD6cH/yaFgaM1jg6dns1jPcVT+KCWjyoW1pnbqZa09am/bFbUXwkAQruXkECDjZwG5zGIhkV5Gb6OQTpU3Vtw1TS62efexsLBkzIfqlL2TTwbWqusUsDtkWG/kCaAlw4OY7yyKBIC7utFL/o7d47ogKdWO8h8ctv70MopQR98fMVXxGuSpUIaaCKzP18X6PVG+D2z7KU1zaVklNtvVefOLG9JGuji30je4hZ2knSI67T1iJNcZCAf0RHpXesWJfTRF1KJJd/4wkJXriELWayD7xXc2vD1AgMBAAECggEACsUk3PVzSX11+ekTDigM7NHK11UpEQPoGu/GR70mBKIK9BCyI/N9W0YaPEO9kn4p9KNrINgXzKV3sVLBnXEyTmzyRl5Fs9YxLBF0X7eIcSVPHBVvU2CVHKez5uX2ypKfNAx7A6FRUNqlFbwtXdNfLoUOKSwBWI86ctytWaKaRb/TTSGQkaP/z/cwIsXOLfG9m6iFkw98ShUzalrUWNo/4fJKlO1+DvXVYE9sv9rjD8J7DtAbr5KykQ5n0AAlZTCWQ7jwMybSnjjY9ypZUms0l17raJrfhrdbWayc6xMDvtrmNIDebkF+J7cHU06aEV+yQXV/7yjyZgUSM2ANcHMdzQKBgQDmTi5tUeaj1JUSl9lAP/XUzcElw2tcU1B8qpX69J4ofjTNgj5okLWQZVIy1UyAfLOI3LJbHTBUtSvedhH0VaMulq99NXs5qnbPGG3//RBAc0wKhJknB5Qv0D3FxMI14kMO6jzPly+aIGEk4dTtHvZuHbbVHbKSZ5MMouLyT+SS7wKBgQDhZETARZ0MazeWRaPJwdkjlfNcqqcsnDicdcppCkcDCjeLxkVPZc8ej37rshOvw2Pf1D0PddGyOhJoWCWA8QE2LQoDHLaDnQ0L6aQ3yjN5Gxx9RCDFi3Zuat/mPcv3tFO7uUmeYvRC5fGYrghq29NADmUefOopAc06Izd4A3iqWwKBgQC1uPrpR7a1jwgRo7/I8q8HO1MseQY903+u3ut5GYuyZ+NCRYL4/zZEua4ibivvNnZzh7E0M9PvAwWag4+nO+uG11+hbJHO7rLQtnYVh5lLQa6+neI66cAD+kzDwH1+BwriufFB3Amzk9kTQR7B+6x3NvsNLmG5JADj96Mbj+7MAQKBgFIevEXplyzdK6WevexWqoyip8aNjtdcG+w1pofa7MCYymAs3zfseihCVBYADdguModsxsqJPNvY+Lf31cJDDRP2GP3FSmJtqEE84U5KZ7KqRBkH54DSLVZRrj4vKc+YbiGpgr8ogqKVMQ9V6U81xKREGmefT5mdRG74Qc+CREadAoGAFtdsH5js1yFEeGFad4BZJ69grEavD3pNCfIe9oIPtXvvFdzxd+QbKgqFf3JMJp/HYi8A0iv/i4mzf00KXzF4JU7bIJYrUVlk/w8x77gzDRIphsPqpMBJkTI0jisQHZKWNEe7IbmM/dWW2S4jvCkrhB7F5Szf72Q+j/lPbfx2g/8=" -+ } -+ } - -[edit] -vyos@vyos# commit -``` - -Diffie-Hellman key: - -``` none -vyos@vyos# run generate pki dh install dh-1 -Enter DH parameters key size: (Default: 2048) -Generating parameters... -1 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] -vyos@vyos# compare -[pki] -+ dh dh-1 { -+ parameters "MIIBCAKCAQEAp25kxwZeLZ7wcbRii5E5RD4uWCUOBxarzKEE0msa84omh5nZ9dv/4bfJw4gIXlA2+sGc2lLV/jajZminMryiSwJdisyVuUdOB7sJWZwrzHBAY0qFbNyaRMVJBar2xVm+XcKd3A2eNTEgn10G7rPPvf6CJ5isUKFaKT8ymUv+mI0upLneYdGs8/yS3sAojzeulCf49fa5SiaGCcZZkdOI3Nby1u/ZG4okqJ2wE2c2hRVLs1k5qrrono0OF4Dh0B91ihnywRfp1xPYeqpiln+OPh+PPgTuBxkz4VxwRDoQ+NhVr/LOCb3vbhnyFisxI0w4r3109cA3QiDmo1L14aKl1wIBAg==" -+ } - -[edit] -vyos@vyos# commit -``` - -Client certificate: - -``` none -vyos@vyos:~$ generate pki certificate sign ca-1 install client1 -Do you already have a certificate request? [y/N] N -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -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) client1 -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) client -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] -You are not in configure mode, commands to install manually from configure mode: -set pki certificate client1 certificate 'MIIDrjCCApagAwIBAgIUPvtffeYTdoOiHxu++wdrjHwwVX4wDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTQxMDlaFw0yNjA2MTExMTQxMDlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQnUyqEzG+AqZzsdSud5MDqsOxiXTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTANBgkqhkiG9w0BAQsFAAOCAQEAplItvZpoX/joG3QREu9tHVKwDTmXB2lwUM5G8iKPgd6D6oOILZMe2KuvWt12dcdEzUCGfJwJJ8M8R2WD0OmcLdFqvM/8UM1hYzUP2BCnFCLtElVD+b4wMlQNpdHqNbdckw8J4MLQlhUgu9rZAZ0XjWCprr+U50bX++vYRw7Un3Ds6ETEvjflm5WAPb2e0V1hhISPl8K+VXO7RAwxy0DHcDuR+YaD+hnNgMsJV3/QwA17Iy8x86RpOgqmesbt0U7e9Rmo81aVgiy/V4OCV7u6bPX03fmZNS8UwwJuRUlxkjO+epHNYB2cnOcjSkUxaIJ9Hv3tMWHQEtbVZsNYSOZozw==' -set pki certificate client1 private key 'MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAECggEAPS/Fhtt5k2BgFivZW3FcVc+OS0keGwV8hkFsGoXTZIKEIzSFWIn/mX0CUY90C0Rn9MRwiqB4PwssOAsHY6QQjdRK8irRbVK8l2ZeydHC7DfVUdXtKR0YnxTaePML3nTV/TqPF14Rx6EINtHrkLeBbu2DhGsKfhoHIoTVbvUiKLHa2TkGJOkhvjsyMSPKzUXa1AzLmu+UBIhRYpEPHj0SQUUJJnKgIb7mTR2fhJScHcKwsrPq6S8OpChvsYZ6zatgrTFz9tuhD4IjL7NBiYP45BwGaLIaQjph8yAJwwHWoOP+TTj5WYflkW6Uu8F9gC0ve6dPGPNEi2TUdirvAe4LYQKBgQD0UfAPm6tQg8pdkvfMBvYc21fk8zqmgcA4OtvDi60aXuv5jI5+faISvOG2JLuFhKIDOb5ZerzGvkN+LvWgzr9H7YdGZNNtwKgpS/MGqcuuHncTxWBAwYgKhf26a/tqFZRNurJ6GowxDiAcQEc1mWnmdngRa+dvvCwNbXvGVqfVEQKBgQDGKi447TqD76QfvRPn/fRSjM+QE1duk+XorEJ0HHIha5HV9kCrZdV/olGRjDLwPJO6JW7iE2FUsS9SsIrccFE/9P2ZUqfYP2wL5vNO5kAmoLLUl0gwqg1WnBTPJfXeKReTj2uGmOdEuuMPXpL/49hDuPViiE2Q4MGe2Z+oEYN/EwKBgHfQMuTEl2e9qaDn8OM6SrluC5V4fjunh6dLnfgwaCx1fk1702lOnQuJWzsiml9o4raoO6PP4AGqzphz2PsKSJ2ya1NnIJRDFXRjDYQoAn2Z7RViBsja36chfINObxXgDUFtHBdrK3LnFXIlR4aOfHOLh2grvWx7IDNZjIiAeH+xAoGAJlmFZnjqiRv4bDgAQTZRcSRVCvHjSsAOj0++8I+MutEBgSHN9B2aCsBT/tHeDcX7ZNvXsKLFhElh+iO2S+DkqHb2GRT47I2hkFAaqBtBMPiKgz/ftaNDP46nLEuRYHQdXu4zhfHTV+a/CHtqAWGLuddyjaYJNM96SQ6eqjzxcMcCgYAzdxOF2e27hIgo2ttjsROMGqW0/0r/HsKGKPnao7xHQNCAswTnBT+QGugPCe0NXjuxbySP7V1GeWMWF+WV5khtteWerT1/ELAC48NSDpaMxVa4GP8Q/0w6+ZyJty3UGbCYQzZZue81dU+42LUIaVJ4NAc2tYj3jD780udasawS6w==' -``` - -Manually copy the CA, client certificate, and Diffie-Hellman key to the client device, then commit them before configuring the OpenVPN interface. - -For more options, refer to {ref}`configuration/pki/index:pki`. - -## Set up server-client OpenVPN - -The following example demonstrates the most complicated scenario: each client acts as a router with its own subnet (e.g., an HQ and multiple branch offices). Simpler setups are subsets of it. - -In this scenario, the 10.23.1.0/24 network is used for client tunnel endpoints, and all client subnets belong to 10.23.0.0/20. Each client needs access to the 192.168.0.0/16 network. - -Server configuration: - -``` none -set interfaces openvpn vtun10 encryption data-ciphers '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.23.1.10' -set interfaces openvpn vtun10 server client client1 subnet '10.23.2.0/25' -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.23.1.0/24' -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 dh-1 -``` - -The configuration above uses the default 1194/UDP port, 256-bit AES encryption, SHA-512 for HMAC authentication, and the persistent-tunnel option. Persistent-tunnel is recommended as it keeps the TUN/TAP device active during connection resets or daemon reloads. Clients are identified by the CN attribute in their SSL certificates. - -To grant clients access to a specific network behind the router, use the push-route option to automatically install the appropriate route on each client. - -``` none -set interfaces openvpn vtun10 server push-route 192.168.0.0/16 -``` - -OpenVPN does not automatically create kernel routes for client subnets when clients connect; it only uses client-subnet association internally. Therefore, you must manually create a route to the 10.23.0.0/20 network: - -``` none -set protocols static route 10.23.0.0/20 interface vtun10 -``` - - -## Set up OpenVPN client - -VyOS can operate not only as an OpenVPN site-to-site peer or a server for multiple clients, but also as an OpenVPN client. Any VyOS OpenVPN interface can be configured to connect to another VyOS or third-party OpenVPN server. - -Client configuration: - -``` none -set interfaces openvpn vtun10 encryption data-ciphers '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-certificate ca-1 -set interfaces openvpn vtun10 tls certificate client1 -``` - - -## Verification - -Check the tunnel status: - -``` none -vyos@vyos:~$ show openvpn server - -OpenVPN status on vtun10 - -Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ------------ ------------------ ----------- ---------------- ---------- ---------- ------------------- -client1 172.16.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 -``` - - -### Server bridge - -In Ethernet bridging configurations, an OpenVPN interface operating in server mode with the device type set to TAP can be added to a bridge. By encapsulating entire Ethernet frames (up to 1514 bytes) rather than just IP packets (up to 1500 bytes), this setup enables clients to transmit Layer 2 frames through the OpenVPN tunnel. - -The following is a basic configuration example: - -Server side: - -``` 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 'dh-1' -``` - -Client side: - -``` 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' -``` - - -### Server LDAP authentication - -## LDAP - -Enterprise installations usually include a directory service to centralize employee password management. VyOS and OpenVPN support using LDAP and Active Directory as a single user backend. - -Authentication is performed by the `openvpn-auth-ldap.so` plugin, included with every VyOS installation. To use it, you must create a dedicated configuration file. -**Best practice:** Store the configuration file in the `/config` directory to ensure it is preserved after image updates. - -``` none -set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" -``` - -A sample configuration file is shown below: - -``` none - -# 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 - - - -# 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 - -``` - - -### Active Directory - -A sample configuration file is shown below: - -``` none - - # 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 - - - - # 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 - - BaseDN "OU=Groups,DC=example,DC=com" - SearchFilter "(|(cn=VPN))" - MemberAttribute memberOf - - -``` - -If you only want to check that the user account is enabled and can authenticate (against the primary group), the following snippet is sufficient: - -``` none - - URL ldap://dc01.example.com - BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com - Password ThisIsTopSecret - Timeout 15 - TLSEnable no - FollowReferrals no - - - - BaseDN "DC=example,DC=com" - SearchFilter "sAMAccountName=%u" - RequireGroup false - -``` - -A complete example of an LDAP authentication configuration for OpenVPN is shown below: - -``` 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 - } - } -``` - -For a detailed example, refer to {doc}`OpenVPN with LDAP`. - -### Multi-factor authentication - -VyOS supports multi-factor authentication (MFA) or two-factor authentication using Time-based One-Time Passwords (TOTP). It is compatible with Google Authenticator and other software tokens. - -## Server side - -``` 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' -``` - -A TOTP secret is created for each client in the OpenVPN server configuration. To display authentication information, use the following command: `show interfaces openvpn vtun20 user user1 mfa qrcode`. - -Example: - -``` none -vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode -█████████████████████████████████████ -█████████████████████████████████████ -████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ -████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ -████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ -████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ -████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ -████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ -████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ -████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ -████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ -████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ -████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ -████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ -████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ -████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ -████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ -█████████████████████████████████████ -█████████████████████████████████████ -``` - -Scan the QR code to add the user account to Google Authenticator. On the client side, use the generated OTP as the password. - -### Authentication with username/password - -An OpenVPN server can securely obtain a username and password from a connecting client and use this information for authentication. - -First, configure the server to use an authentication plugin or script. The server calls this plugin every time a client tries to connect, passing it the client\'s credentials. - -In the following example, the `--auth-user-pass-verify` directive is used with the via-env method and a specified script path to validate the client\'s username and password. - -## Server configuration - -``` none -set interfaces openvpn vtun10 local-port '1194' -set interfaces openvpn vtun10 mode 'server' -set interfaces openvpn vtun10 openvpn-option '--auth-user-pass-verify /config/auth/check_user.sh via-env' -set interfaces openvpn vtun10 openvpn-option '--script-security 3' -set interfaces openvpn vtun10 persistent-tunnel -set interfaces openvpn vtun10 protocol 'udp' -set interfaces openvpn vtun10 server client client-1 ip '10.10.10.55' -set interfaces openvpn vtun10 server push-route 192.0.2.0/24 -set interfaces openvpn vtun10 server subnet '10.10.10.0/24' -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 'dh-1' -``` - -The /config/auth/check_user.sh example includes two test users: - -``` none -#!/bin/bash -USERNAME="$username" -PASSWORD="$password" - -# Replace this with real user checking logic or use getent -if [[ "$USERNAME" == "client1" && "$PASSWORD" == "pass123" ]]; then - exit 0 -elif [[ "$USERNAME" == "peter" && "$PASSWORD" == "qwerty" ]]; then - exit 0 -else - exit 1 -fi -``` - - -## Client configuration - -Storing the client certificate locally lets you generate the OpenVPN client configuration file. Use the following command: - -``` none -vyos@vyos:~$ generate openvpn client-config interface vtun10 ca ca-1 certificate client1 -``` - -Copy the output and save it as a .ovpn file. Add the `auth-user-pass` directive to the file. This instructs the OpenVPN client to prompt the user for a username and password, which are then sent to the server over the TLS channel. You can now import this file into any OpenVPN client application. - -``` none -client -dev tun -proto udp -remote 192.168.77.10 1194 - -remote-cert-tls server -proto udp -dev tun -dev-type tun -persist-key -persist-tun -verb 3 -auth-user-pass - - - ------BEGIN CERTIFICATE----- -MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQEL -BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM -CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 -MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQI -DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx -DTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi -+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0 -RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8 -PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnD -rxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIh -BL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs -5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0P -AQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4E -FgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa -8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZ -zph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHw -Y6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZ -WXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyx -zRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55Ym -tmctGO2o+NBCFi0= ------END CERTIFICATE----- - - - - ------BEGIN CERTIFICATE----- -MIIDrjCCApagAwIBAgIUN6vPxDEW89cfbEFPa0tZlnsW1GkwDQYJKoZIhvcNAQEL -BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM -CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 -MTExMTQ0MjlaFw0yNjA2MTExMTQ0MjlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQI -DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx -EDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB -AQCdOWq8vdO8CznGN83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmu -QBmeCj7SlbYtVYo1uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/ -RcZcW530pu/QpYinKTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585 -A7L40043VtsVVbPjQq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3 -UtRHiq74CfGtJzYtplgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6 -QjEL0RkYloMgkbv/2HLCu09hAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0P -AQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQCkfdfq3hv -7UtqAxq/5VDRIdgJLTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTAN -BgkqhkiG9w0BAQsFAAOCAQEAJ43+aDVRC+y2vsu6WRG2l6zYnLoIJZW4afdKMC1a -nhTWhj4AhAt8evhVbAxi/8qhQX3yXF2bUQKdS++8AVcvZFlSES32S5eBx83AwGLt -QkgvGx+QThKmoJwrelyuS2X0XX3P0WzohYI6HzSr6p9F8KhTvSW97E6SnldpdvEM -uG1C+61/Vys7WLmDBh1PZTGE03nRp3H4Q9ynyXEEf1MK3eZkzg5H3Evj66p82pD5 -8IauRfghMHJf3tOC+y0YIoXshF3lPq4nYso5Jc/HGCHlsboCODMCnY3CZsH7/O1n -/MI710KpzZTCLnv4Qtx9JpZxR7FTddl36OOuYUXU3Gcnsg== ------END CERTIFICATE----- - - - - ------BEGIN PRIVATE KEY----- -MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCdOWq8vdO8CznG -N83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmuQBmeCj7SlbYtVYo1 -uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/RcZcW530pu/QpYin -KTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585A7L40043VtsVVbPj -Qq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3UtRHiq74CfGtJzYt -plgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6QjEL0RkYloMgkbv/ -2HLCu09hAgMBAAECggEAOR3xRVUO9Sr816JRSQwz486eNDpNSxazgwtOb3JUTUH9 -E7onq1y/kMOgOmSIEHoP9GaTcQxbbPe86IxomhLT/50ri52YzWzx/heY2SVPyQXB -FMo79putKw0vnj5UyydNiyLrbMQyrhFc5iFmWVdz5/c4cWHwjIThPp7V4znXYwHZ -OB/Xn1NNHDNy872oQn5wZWzuA4ml0OqjU5D+Ne9srODl3r4OTo3lb1N3JuH3aOSA -cACl1JnN/KElN8IotIdweeUFAdn2jsGjZnCpGaJvZQ+2iMn6doJXHgFiF5+GMF7o -aOatglElIuqgPtB/4nvnegSL0DSnB36ojqv2PAh24wKBgQDPBt4S4muqo8SqP2e0 -8X78MyK3tz1VmgPKn3O68Vdi1V7FPz0RHRGsw/kdgxXsJlfZTWgzcq2NNFu0yPBJ -A/h7qo16mv8GW7cJCd2exjb+/oq4r5iWeqLdSsMUXN87x02LRaMNd9wz1mls1Z73 -oQ5hJ7zTtlyYXnvKPQo8X1ImjwKBgQDCaptQxZ/a3tcUQQlXAFMAScviODZd0LCL -30ZalwpNs6nVVIPoZHD3tlzWN5Es74gndfkC7/Gm2cnsOW9QQaU56q+5LeNXItW8 -rc6yXq3vNQerqJxHNUmKWwLCQtSyLRjFqpGTl/PyX2bGXQ7/zjTL3W8VMD5otf4Y -SJJB+sKjDwKBgHSVX3WvAAamFtfwwMwKuwH3IfPnQqj0BHKUfK2nvxgvJCFbzV3X -yt5Jtf3ClhPYO9xpVOa0C7va4lHaXkYf8Exj7SxAIKFKALccUStaYBoU6bW7XOhQ -w2pu8ZCEBEo7oBVv77Rj7SNb+R6K5ex5TAm2QQXQSjCb9IYc/ail3TNNAoGBALu6 -GPMrgKnlFyV1j0E1DPBwUbDEuqpoArFtDRAYXFifLVTS4PQbWIG403f9++659Gy2 -G5ZcfqiwD6xL4VJLsPF1zewvhR/0gRJJehb+GVGrkRaOHykbKUGxk75kreDGbu8f -PqaXyXS17hWIch1Lzes0jDiXdwvA//QOzztqmVq9AoGAVMbmf04+QtzckLolAP4q -Uwr5svfy14A7V3IGkwlsHZdm37L26lfxW0kpOOE7g7D6gdinuALo6oopP7RN/IDq -PLaaHaGrIoLAEVFa0bRLGsrU2q87ytwfSgdra4jmsTn+xEabdI4IgmqWgwSRvGVf -KN18e19Ssw5x7Wq0Rsw/3VM= ------END PRIVATE KEY----- - - -``` - -When prompted, log in with the username and password. diff --git a/docs/configuration/interfaces/md-openvpn.md b/docs/configuration/interfaces/md-openvpn.md deleted file mode 100644 index 170c585d..00000000 --- a/docs/configuration/interfaces/md-openvpn.md +++ /dev/null @@ -1,614 +0,0 @@ -(openvpn)= - -# OpenVPN - -Traditionally, hardware routers use IPsec exclusively because it is easy to -implement in hardware, and their CPUs lack sufficient power for software-based -encryption. This limitation is less relevant for VyOS, as it is a software -router. - -OpenVPN has been widely used on UNIX platforms for a long time and is a popular -choice for remote-access VPNs. It also supports site-to-site connections. - -OpenVPN offers the following advantages: - -- It uses a single TCP or UDP connection and does not rely on packet source - addresses, so it works even through double NAT. This makes it well-suited for - public hotspots. -- It is easy to set up and offers very flexible split tunneling. -- A variety of client GUI frontends are available for any platform. - -Disadvantages include: - -- It is slower than IPsec due to higher protocol overhead and because it runs - in user mode, while IPsec on Linux runs in kernel mode. -- No operating system includes OpenVPN client software by default. - -In the VyOS CLI, OpenVPN is configured as a network interface using `set -interfaces openvpn` rather than `set vpn`, which is often overlooked. - -## Configuration - -```{cfgcmd} set interfaces openvpn \ authentication password \ - - **Configure the password for the** ``auth-user-pass`` **authentication method.** - - This option applies only to OpenVPN clients. -``` - - -```{cfgcmd} set interfaces openvpn \ authentication username \ - -**Configure the username for the** ``auth-user-pass`` **authentication method.** - -This option applies only to OpenVPN clients. -``` - - -```{cfgcmd} set interfaces openvpn \ description \ - -Configure the description for the OpenVPN interface. -``` - - -```{cfgcmd} set interfaces openvpn \ device-type \ - -**Configure the virtual network device type for the OpenVPN interface:** - -* ``tun`` **(default)**: Operates at Layer 3, encapsulating IPv4 or IPv6 packets. -* ``tap``: Operates at Layer 2, encapsulating Ethernet 802.3 frames. -``` - - -```{cfgcmd} set interfaces openvpn \ disable - -Disable the specific OpenVPN interface. -``` - - -```{cfgcmd} set interfaces openvpn \ encryption cipher \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> - -**Configure the static encryption cipher for the OpenVPN tunnel.** - -The ``cipher`` option maps to OpenVPN’s ``--cipher`` directive and specifies -the symmetric encryption algorithm for both control and data channels. - -This was previously the default encryption method in all OpenVPN modes. In -newer OpenVPN versions, the ``--cipher`` directive is considered **legacy** -and should be used only in compatibility scenarios. -``` - - -```{cfgcmd} set interfaces openvpn \ encryption data-ciphers \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> - -**Configure a prioritized list of negotiated ciphers for OpenVPN in** -``client`` **or** ``server`` **mode.** - -The ``data-ciphers`` option represents a list of supported encryption -algorithms. It corresponds to OpenVPN’s ``--data-ciphers`` directive and -enables cipher negotiation, where both peers automatically agree on a mutually -supported cipher during session startup. - -:::{note} -This option is not compatible with ``site-to-site`` mode. -::: -``` - - -```{cfgcmd} set interfaces openvpn \ encryption data-ciphers-fallback \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> - -**Configure the fallback cipher for** ``site-to-site`` **mode.** - -The ``data-ciphers-fallback`` option maps to OpenVPN’s ``--data-ciphers- -fallback`` directive. It defines the cipher to use if negotiation is **not -supported**. - -:::{note} -This option ensures consistent encryption between two static peers -without cipher negotiation capability. -::: -``` - - -```{cfgcmd} set interfaces openvpn \ hash \ - -Configure the hashing algorithm for the OpenVPN interface. -``` - - -```{cmdincludemd} /_include/interface-ip.txt -:var0: openvpn -:var1: vtun0 -``` - - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: openvpn -:var1: vtun0 -``` - - -```{cfgcmd} set interfaces openvpn \ keep-alive failure-count \ - -**Configure the number of tolerated keepalive packet failures.** - -Default: 60 consecutive failures. -``` - - -```{cfgcmd} set interfaces openvpn \ keep-alive interval \ - -**Configure the frequency, in seconds, at which keepalive packets are sent.** - -Default: 10 seconds. -``` - - -```{cfgcmd} set interfaces openvpn \ local-address \ - -Configure the local tunnel IP address for ``site-to-site`` mode. -``` - - -```{cfgcmd} set interfaces openvpn \ local-host \ - -**Configure the local IP address to accept connections.** - -If configured, OpenVPN binds to this IP address only. - -By default, OpenVPN binds to all interfaces. -``` - - -```{cfgcmd} set interfaces openvpn \ local-port \ - -Configure the local port to accept connections. -``` - - -```{cfgcmd} set interfaces openvpn \ mirror egress \ - -Configure mirroring of outgoing traffic from this OpenVPN interface to the -designated monitor interface. -``` - - -```{cfgcmd} set interfaces openvpn \ mirror ingress \ - -Configure mirroring of incoming traffic from this OpenVPN interface to the -designated monitor interface. -``` - - -```{cfgcmd} set interfaces openvpn \ mode \ - -**Configure OpenVPN operation mode:** - -* ``site-to-site``: Establishes a site-to-site VPN connection. -* ``client``: Operates as a client in server-client mode. -* ``server``: Operates as a server in server-client mode. -``` - -### OpenVPN Data Channel Offload (DCO) - -OpenVPN {abbr}`DCO (Data Channel Offload)` improves the performance of -encrypted OpenVPN data processing by keeping most data handling in the kernel -and avoiding frequent context switches between the kernel and user space. - -As a result, packet processing becomes more efficient and may utilize hardware -encryption offload support available in the kernel. - -:::{note} -- {abbr}`DCO (Data Channel Offload)` is an **experimental**, not fully supported - OpenVPN feature. Some OpenVPN features and deployment scenarios are **not - compatible** with {abbr}`DCO (Data Channel Offload)`. - - For a complete list of supported features, visit: - -- {abbr}`DCO (Data Channel Offload)` is configured per tunnel and disabled - by default. Existing tunnels operate without {abbr}`DCO (Data Channel - Offload)` unless it is explicitly enabled. -- Enabling {abbr}`DCO (Data Channel Offload)` resets the interface. -::: - -**Best practice:** Create a new tunnel with {abbr}`DCO (Data Channel Offload)` -enabled to avoid compatibility issues with existing clients. - -```{cfgcmd} set interfaces openvpn \ offload dco - - **Enable** {abbr}`DCO (Data Channel Offload)` **for the specified OpenVPN - interface.** - - Example: - - :::{code-block} none - set interfaces openvpn vtun0 offload dco - ::: - This command enables {abbr}`DCO (Data Channel Offload)` and loads the required - kernel module. -``` - - -```{cfgcmd} set interfaces openvpn \ openvpn-option \ - -**Add raw OpenVPN configuration options to the openvpn.conf file.** - -OpenVPN provides many configuration options, but not all are available in the -VyOS CLI. - -If a required option is missing, you may submit a feature request at -Phabricator so all users can benefit from it (see Contributing/Issues and Features). - -Alternatively, use ``openvpn-option`` to pass raw OpenVPN configuration options -to the openvpn.conf file. - -:::{warning} -Use this option only as a last resort. Invalid options or syntax -may prevent OpenVPN from starting. Check system logs for errors after applying -changes. -::: -Example: - -:::{code-block} none -set interfaces openvpn vtun0 openvpn-option 'persist-key' -::: -This command adds ``persist-key`` to the configuration file. This solves the -problem by persisting keys across resets, so they do not need to be re-read. - -:::{code-block} none -set interfaces openvpn vtun0 openvpn-option 'route-up "/config/auth/tun_up.sh arg1"' -::: -This command adds ``route-up "/config/auth/tun_up.sh arg1"`` to the -configuration file. This option is executed after connection authentication, -either immediately or after a short delay, as defined. - -Ensure the path and arguments are enclosed in single or double quotes. - -:::{note} -Some raw configuration options require quotes. To include them, use -the " statement. -::: -``` - - -```{cfgcmd} set interfaces openvpn \ persistent-tunnel - -**Enable always-active mode for the TUN/TAP device.** - -When enabled, the TUN/TAP device remains active upon connection resets or -daemon reloads. -``` - - -```{cfgcmd} set interfaces openvpn \ protocol \ - -**Configure the protocol for OpenVPN communication with a remote host:** - -* ``udp`` **(default)**: Uses the UDP protocol. -* ``tcp-passive``: Uses the TCP protocol and accepts connections passively. -* ``tcp-active``: Uses the TCP protocol and initiates connections actively. -``` - - -```{cfgcmd} set interfaces openvpn \ redirect \ - -Enable redirection of incoming packets to the specified interface. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-address \ - -Configure the remote tunnel IP address for site-to-site mode. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-host \
- -**Configure the IPv4/IPv6 address or hostname for a server device if OpenVPN -runs in client mode.** - -This setting is not used in server mode. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-port \ - -Configure the remote port to connect to the server. -``` - - -```{cfgcmd} set interfaces openvpn \ replace-default-route - -Configure the OpenVPN tunnel as the default route. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge disable - -Disable the given instance. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge gateway \ - -Configure the gateway IP address. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge start \ - -Configure the first IP address in the pool to allocate to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge stop \ - -Configure the last IP address in the pool to allocate to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge subnet-mask \ - -Configure the subnet mask pushed to dynamic clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ - -Configure the Common Name (CN) specified in the client certificate. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ disable - -Disable the client connection. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ ip \ - -Configure the IPv4/IPv6 address for the client. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ push-route \ - -Configure a route to be pushed to the specific client. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ subnet \ - -**Configure a fixed subnet to be routed from the server to the specified -client.** - -Used as OpenVPN’s ``iroute`` directive. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool start \ - -Configure the first IP address in the subnet's IPv4 pool to be dynamically -allocated to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool stop \ - -Configure the last IP address in the subnet's IPv4 pool to be dynamically -allocated to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool subnet \ - -**Configure the subnet mask pushed to dynamic clients.** - -Use this command only for the TAP device type. Do not use it for bridged -interfaces. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ipv6-pool base \ - -Configure the IPv6 address pool for dynamic assignment to clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server domain-name \ - -Configure the DNS suffix to be pushed to all clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server max-connections \<1-4096\> - -Configure the maximum number of client connections. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp challenge \ - -If enabled, openvpn-otp expects a password as a result of the challenge/ -response protocol. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp digits \<1-65535\> - -**Configure the number of digits to use for the** {abbr}`TOTP (Time-based -One-Time Password)` **hash.** - -Default: 6. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp drift \<1-65535\> - -**Configure the time drift in seconds.** - -Default: 0. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp slop \<1-65535\> - -**Configure the allowed clock slop in seconds.** - -Default: 180. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp step \<1-65535\> - -**Configure the step value for** {abbr}`TOTP (Time-based One-Time Password)` -**in seconds.** - -Default: 30. -``` - - -```{cfgcmd} set interfaces openvpn \ server name-server \ - -Define the client DNS configuration to be used with the connection. -``` - - -```{cfgcmd} set interfaces openvpn \ server push-route \ - -Configure the route to be pushed to all clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server reject-unconfigured-client - -Reject connections from clients that are not explicitly configured. -``` - - -```{cfgcmd} set interfaces openvpn \ server subnet \ - -**Configure the IPv4 or IPv6 network.** - -This parameter is mandatory when operating in server mode. -``` - - -```{cfgcmd} set interfaces openvpn \ server topology \< net30 | point-to-point | subnet\> - -**Configure the virtual addressing topology for** ``tun`` **mode.** - -This command does not affect ``tap`` mode, which always uses the ``subnet`` -topology. - -* ``subnet`` **(default)**: Allocates a single IP address to each connecting client. -This is the recommended topology. -* ``net30``: Allocates a /30 subnet to each connecting client. This is a legacy -topology used to support Windows clients. It is now effectively deprecated. -* ``point-to-point``: Creates a point-to-point topology where the remote -endpoint of the client’s ``tun`` interface always points to the local endpoint -of the server’s ``tun`` interface. - -Like ``subnet``, this topology allocates a single IP address per client. Use it -only if no clients run Windows operating systems. -``` -```{cfgcmd} set interfaces openvpn \ shared-secret-key \ - -Configure the static secret key for a site-to-site OpenVPN connection. -``` -```{cfgcmd} set interfaces openvpn \ tls auth-key \ - -**Configure the TLS secret key for tls-auth.** - -This adds an HMAC signature to all SSL/TLS handshake packets to verify -integrity. - -Use ``run generate pki openvpn shared-secret install `` to generate -the key. -``` -```{cfgcmd} set interfaces openvpn \ tls ca-certificate \ - -Configure the Certificate Authority chain in the PKI configuration. -``` -```{cfgcmd} set interfaces openvpn \ tls certificate \ - -Configure the certificate name in the PKI configuration. -``` -```{cfgcmd} set interfaces openvpn \ tls crypt-key - -Configure a shared secret key to provide an additional level of security, -a variant similar to tls-auth. -``` -```{cfgcmd} set interfaces openvpn \ tls dh-params - -Configure Diffie-Hellman parameters for server mode. -``` -```{cfgcmd} set interfaces openvpn \ tls peer-fingerprint \ - -Configure the peer certificate SHA256 fingerprint for site-to-site mode. -``` -```{cfgcmd} set interfaces openvpn \ tls role \ - -**Configure the TLS negotiation role, preferably used in site-to-site mode:** -* ``active``: Initiates TLS negotiation actively. -* ``passive``: Waits for incoming TLS connections. -``` -```{cfgcmd} set interfaces openvpn \ tls tls-version-min \<1.0 | 1.1 | 1.2 | 1.3 \> - -Configure the minimum TLS version to be accepted from the peer. -``` -```{cfgcmd} set interfaces openvpn \ use-lzo-compression - -Configure fast LZO compression on this TUN/TAP interface. -``` -```{cfgcmd} set interfaces openvpn \ vrf \ - -Assign the interface to a specific VRF instance. -``` - -## Operation mode - -```{opcmd} show openvpn site-to-site - -Show tunnel status for OpenVPN site-to-site interfaces. -``` -```{opcmd} show openvpn server - -Show tunnel status for OpenVPN server interfaces. -``` -```{opcmd} show openvpn client - -Show tunnel status for OpenVPN client interfaces. -``` -```{opcmd} show log openvpn - -Show logs for all OpenVPN interfaces. -``` -```{opcmd} show log openvpn interface \ - -Show logs for the specific OpenVPN interface. -``` -```{opcmd} reset openvpn client \ - -Reset the specified OpenVPN client. -``` -```{opcmd} reset openvpn interface \ - -Reset the OpenVPN process on the specified interface. -``` -```{opcmd} generate openvpn client-config interface \ ca \ certificate \ - -Generate an OpenVPN client configuration file in the .ovpn format for client machines. -``` - -## Examples - -This section covers examples of OpenVPN configurations for various deployments. - -```{toctree} -:includehidden: true -:maxdepth: 1 - -openvpn-examples -``` - diff --git a/docs/configuration/interfaces/md-pppoe.md b/docs/configuration/interfaces/md-pppoe.md deleted file mode 100644 index b79f41a2..00000000 --- a/docs/configuration/interfaces/md-pppoe.md +++ /dev/null @@ -1,419 +0,0 @@ ---- -lastproofread: '2026-03-03' ---- - -(pppoe-interface)= - -# PPPoE - -{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol -that encapsulates PPP frames within Ethernet frames. -It's often used for connecting ISP clients to a broadband access server. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-description.txt -:var0: pppoe -:var1: pppoe0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: pppoe -:var1: pppoe0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: pppoe -:var1: pppoe0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: pppoe -:var1: pppoe0 -``` - - -### PPPoE options - -```{cfgcmd} set interfaces pppoe \ access-concentrator \ - -**Configure the name of the target access concentrator for the PPPoE session.** - -During the PPPoE discovery process, the client sends a PPPoE initiation packet. -Multiple access concentrators may respond with offer packets, and the client -selects one of them. - -This setting restricts the client to establishing sessions only with the -specified access concentrator. -``` - -```{cfgcmd} set interfaces pppoe \ authentication username \ - -**Configure the username for PPPoE session authentication.** - -Although authentication is optional in the interface configuration, most ISPs -require it to establish a connection. -``` - -```{cfgcmd} set interfaces pppoe \ authentication password \ - -**Configure the password for PPPoE session authentication.** - -Although authentication is optional in the interface configuration, most ISPs -require it to establish a connection. -``` - -```{cfgcmd} set interfaces pppoe \ connect-on-demand - -**Enable dial-on-demand on the PPPoE interface.** - -When enabled, the system establishes a PPPoE connection only when traffic -passes through the interface. If the connection fails, it is reestablished when -traffic resumes. - -For on-demand connections, you must also configure an ``idle-timeout`` period -to disconnect the session after inactivity. - -:::{note} -Setting the idle timeout to zero, or leaving it unconfigured, keeps -the connection active continuously once established. -::: - -By default, the PPPoE connection is established at boot and remains active -continuously; if the connection fails, it is reestablished immediately. -``` - -```{cfgcmd} set interfaces pppoe \ no-default-route - -Request an IP address from the PPPoE server without installing a default route. - -Example: - -:::{code-block} none -set interfaces pppoe pppoe0 no-default-route -::: - -:::{note} -Introduced in VyOS 1.4, this command inverts the logic of the former -``default-route`` CLI option. -::: -``` - -```{cfgcmd} set interfaces pppoe \ default-route-distance \ - -Configure the distance for the default gateway provided by the PPPoE server. - -Example: - -:::{code-block} none -set interfaces pppoe pppoe0 default-route-distance 220 -::: -``` - -```{cfgcmd} set interfaces pppoe \ mru \ - -**Configure the** {abbr}`MRU (Maximum Receive Unit)` **for the PPPoE -interface.** - -This setting instructs the pppd daemon to restrict the remote peer from sending -packets larger than the configured MRU. Allowed MRU values range from 128 to -16384 bytes. - -An MRU of 296 is suitable for very slow links (40 bytes for the TCP/IP header -and 256 bytes for data). - -The default MRU is 1492 bytes. - -:::{note} -When using the IPv6 protocol, the MRU must be at least 1280 bytes. -::: -``` - -```{cfgcmd} set interfaces pppoe \ idle-timeout \ - -**Configure the idle timeout for on-demand PPPoE sessions.** - -This setting defines how long the connection remains active without any traffic -before being disconnected. - -:::{note} -Setting the idle timeout to zero, or leaving it unconfigured, keeps -the connection active continuously once established. -::: -``` - -```{cfgcmd} set interfaces pppoe \ holdoff \ - -**Configure the redial delay for persistent PPPoE sessions.** - -If a persistent session (with ``connect-on-demand`` disabled) is terminated by -the remote peer or drops unexpectedly, the router waits the specified interval -before attempting to reconnect. - -The default redial delay is 30 seconds. -``` - -```{cfgcmd} set interfaces pppoe \ local-address \ - -**Configure the local endpoint IP address for PPPoE sessions.** - -By default, this IP address is negotiated. -``` - -```{cfgcmd} set interfaces pppoe \ no-peer-dns - -Disable the installation of advertised DNS nameservers on the local system. -``` - -```{cfgcmd} set interfaces pppoe \ remote-address \ - -**Configure the remote endpoint IP address for PPPoE sessions.** - -By default, this IP address is negotiated. -``` - -```{cfgcmd} set interfaces pppoe \ service-name \ - -**Configure the service name of the target access concentrator for the PPPoE -session.** - -By default, the PPPoE interface connects to any available access concentrator. -``` - -```{cfgcmd} set interfaces pppoe \ source-interface \ - -**Configure the underlying interface for the PPPoE connection.** - -Each PPPoE connection is established over an underlying interface, which can be -an Ethernet interface, a VIF, or a bonding interface. -``` - -```{cfgcmd} set interfaces pppoe \ ip adjust-mss \ - -**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing -TCP SYN packets on the specified interface.** - -By clamping the MSS value in TCP SYN packets, you instruct the remote side not -to send packets larger than the specified size. This helps prevent connection -issues if {abbr}`PMTUD (Path MTU Discovery)` fails. - -The following options are available: - -* ``mss``: Sets the MSS to a specific value in bytes. -* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for - IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). - This option is recommended to automatically set the proper value. - -:::{note} -Introduced in VyOS 1.4, this command replaces the older ``set firewall -options interface adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces pppoe \ ip disable-forwarding - -**Configure the interface for host or router behavior.** - -If configured, the interface switches to host mode, and IPv4 forwarding is -disabled on it. -``` - -```{cfgcmd} set interfaces pppoe \ ip source-validation \ - -**Configure source IP address validation using** -{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** -{rfc}`3704`. - -The following options are available: - -* ``strict``: Each incoming packet’s source IP address is checked against the - {abbr}`FIB (Forwarding Information Base)`. If the interface is not the best - route back to that source, validation fails, and the packet is dropped. -* ``loose``: Each incoming packet’s source IP address is checked against the - {abbr}`FIB (Forwarding Information Base)`. If the source IP address is - unreachable through any interface, validation fails. -* ``disable``: No source IP address validation is performed. All incoming - packets are accepted. - -{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as -DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` -mode. -``` - - -#### IPv6 - -```{cfgcmd} set interfaces pppoe \ ipv6 address autoconf - -Enable IPv6 address assignment via {abbr}`SLAAC (Stateless Address -Auto-Configuration)` on this interface. -``` - -```{cfgcmd} set interfaces pppoe \ ipv6 adjust-mss \ - -**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing -TCP SYN packets on the specified interface.** - -By clamping the MSS value in TCP SYN packets, you instruct the remote side not -to send packets larger than the specified size. This helps prevent connection -issues if {abbr}`PMTUD (Path MTU Discovery)` fails. - -The following options are available: - -* ``mss``: Sets the MSS to a specific value in bytes. -* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 60 bytes for - IPv6 traffic (40 bytes for the IPv6 header and 20 bytes for the TCP header). - This option is recommended to automatically set the proper value. - -:::{note} -Introduced in VyOS 1.4, this command replaces the older ``set firewall -options interface adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces pppoe \ ipv6 disable-forwarding - -**Configure the interface for host or router behavior.** - -If configured, the interface switches to host mode, and IPv6 forwarding is -disabled on it. -``` - -```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt -:var0: pppoe -:var1: pppoe0 -``` - - -## Operation - -```{opcmd} show interfaces pppoe \ - -Show detailed information about a specific PPPoE interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces pppoe pppoe0 -pppoe0: 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 \ queue - -Show queue information for a specific 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 \ - -Disconnect the specified interface. -``` - -```{opcmd} connect interface \ - -Initiate a session on the specified interface. -``` - - -## Example - -### PPPoE over DSL - -**Configuration scenario:** - -- Your ISP's DSL modem is connected to the `eth0` interface on your VyOS - router. -- Your ISP does not require VLAN tagging. -- PPPoE credentials are provided by your ISP. The typical username format is - `name@host.net`, though this may vary. - -**Configuration notes:** - -- The maximum MTU size for DSL is 1492 because of PPPoE overhead. If you are - switching from a DHCP-based ISP (e.g., a standard cable connection), ensure - VPN links have MTU sizes adjusted accordingly. -- To ignore ISP-provided nameservers and use only your statically configured - ones, set the `name-server` option to `none`. -- A default route is automatically installed once the interface is up. To - change this behavior, use the `no-default-route` CLI option. - -:::{note} -The PPPoE configuration syntax changed after VyOS 1.2 (Crux) and is -automatically migrated during an upgrade. -::: - -```none -set interfaces pppoe pppoe0 authentication username 'userid' -set interfaces pppoe pppoe0 authentication password 'secret' -set interfaces pppoe pppoe0 source-interface 'eth0' -``` - -Secure your setup by creating rules matching the `pppoe0` interface in the -firewall chains: - -```none -set firewall ipv4 input filter rule 10 inbound-interface name 'pppoe0' -set firewall ipv4 forward filter rule 10 inbound-interface name 'pppoe0' -``` - - -### PPPoE over VLAN - -Some ISPs require PPPoE connections to be -established over a VLAN interface. This specific topology is fully supported by -VyOS. - -The following configuration establishes the PPPoE connection through VLAN 7, -which is the default VLAN for Deutsche Telekom: - -```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 prefix delegation - -**Configuration scenario:** - -The following configuration establishes a PPPoE session on the `eth1` -interface, requests a `/56` IPv6 prefix delegation from the ISP, and assigns -a `/64` subnet from that delegation to the `eth0` interface. - -**Configuration notes:** - -- The IPv6 address assigned to `eth0` is `::1/64`. -- If you do not know your delegated prefix size, begin with `sla-len 0`. -- To advertise the prefix on the `eth0` link, configure IPv6 Router - Advertisement. - -```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/md-pseudo-ethernet.md b/docs/configuration/interfaces/md-pseudo-ethernet.md deleted file mode 100644 index fc8833eb..00000000 --- a/docs/configuration/interfaces/md-pseudo-ethernet.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -lastproofread: '2026-03-05' ---- - -(pseudo-ethernet-interface)= - -# MACVLAN (pseudo-Ethernet) - -MACVLAN, or pseudo-Ethernet interfaces, operate as logical subinterfaces of -standard Ethernet interfaces. Each subinterface has a unique MAC address but -shares a single physical Ethernet port. -That allows the user to send packets from different source IPv4 or IPv6 addresses -using a different MAC address. - -Pseudo-Ethernet interfaces behave like physical Ethernet interfaces. They -support IPv4 and IPv6 addressing, can obtain IP addresses through DHCP or -DHCPv6, and are mapped to a physical Ethernet port. They inherit -characteristics such as speed and duplex from their parent interface and can -be referenced like standard Ethernet interfaces once created. - -```{eval-rst} -Pseudo-Ethernet interfaces may not work in environments that require a - :abbr:`NIC (Network Interface Card)` to have only one MAC address. - This includes: - - * VMware machines with default settings. - * Network switches that permit only a single MAC address. - * xDSL modems that learn the NIC's MAC address. -``` - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: pseudo-ethernet -:var1: peth0 -``` - -### MACVLAN (pseudo-Ethernet) options - -```{cfgcmd} set interfaces pseudo-ethernet \ source-interface \ - -Assign a physical Ethernet interface to the specified pseudo-Ethernet interface. -``` - -### VLAN - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: pseudo-ethernet -:var1: peth0 -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-sstp-client.md b/docs/configuration/interfaces/md-sstp-client.md deleted file mode 100644 index da98aecd..00000000 --- a/docs/configuration/interfaces/md-sstp-client.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(sstp-client-interface)= - -# SSTP client - -{abbr}`SSTP (Secure Socket Tunneling Protocol)` transports PPP traffic over an -SSL/TLS channel, providing transport-level security through key negotiation, -encryption, and traffic integrity checking. The use of SSL/TLS over TCP port -443 (by default, the port can be changed) allows SSTP to pass through virtually -all firewalls and proxy servers, except for authenticated web proxies. - -:::{note} -VyOS includes a built-in SSTP server. For more information, see -{ref}`sstp`. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-description.txt -:var0: sstpc -:var1: sstpc0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: sstpc -:var1: sstpc0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: sstpc -:var1: sstpc0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: sstpc -:var1: sstpc0 -``` - - -### SSTP client options - -```{cfgcmd} set interfaces sstpc \ no-default-route - -Request an IP address from the SSTP server without installing a default route. - -Example: - -:::{code-block} none -set interfaces sstpc sstpc0 no-default-route -::: -:::{note} Introduced in VyOS 1.4, this command inverts the logic of the former -``default-route`` CLI option. -::: -``` - -```{cfgcmd} set interfaces sstpc \ default-route-distance \ - -Configure the distance for the default gateway provided by the SSTP server. - -Example: - -:::{code-block} none -set interfaces sstpc sstpc0 default-route-distance 220 -::: -``` - -```{cfgcmd} set interfaces sstpc \ no-peer-dns - -Disable the installation of advertised DNS nameservers on the local system. -``` - -```{cfgcmd} set interfaces sstpc \ server \ - -**Configure the remote SSTP server address for the client connection.** - -The address can be either an IP address or a {abbr}`FQDN (Fully Qualified -Domain Name)`. -``` - -```{cfgcmd} set interfaces sstpc \ ip adjust-mss \ - -**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing -TCP SYN packets on the specified interface.** - -By clamping the MSS value in TCP SYN packets, you instruct the remote side not -to send packets larger than the specified size. This helps prevent connection -issues if {abbr}`PMTUD (Path MTU Discovery)` fails. - -The following options are available: - -* ``mss``: Sets the MSS to a specific value in bytes. -* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for -IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). -This option is recommended to automatically set the proper value. - -:::{note} Introduced in VyOS 1.4, this command replaces the older ``set firewall -options interface adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces sstpc \ ip disable-forwarding - -**Configure the interface for host or router behavior.** - -If configured, the interface switches to host mode, and IPv4 forwarding is -disabled on it. -``` - -```{cfgcmd} set interfaces sstpc \ ip source-validation \ - -**Configure source IP address validation using** -{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** -{rfc}`3704`. - -The following options are available: - -* ``strict``: Each incoming packet’s source IP address is checked against the -{abbr}`FIB (Forwarding Information Base)`. If the interface is not the best -route back to that source, validation fails, and the packet is dropped. -* ``loose``: Each incoming packet’s source IP address is checked against the -{abbr}`FIB (Forwarding Information Base)`. If the source IP address is -unreachable through any interface, validation fails. -* ``disable``: No source IP address validation is performed. All incoming -packets are accepted. - -{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as -DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` -mode. -``` - - -## Operation - -```{opcmd} show interfaces sstpc \ - -Show detailed information about the specified interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces sstpc sstpc10 -sstpc10: 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 \ - -Disconnect the specified interface. -``` - -```{opcmd} connect interface \ - -Initiate a session on the specified interface. -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-tunnel.md b/docs/configuration/interfaces/md-tunnel.md deleted file mode 100644 index 9c9885d2..00000000 --- a/docs/configuration/interfaces/md-tunnel.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -lastproofread: '2026-01-23' ---- - -(tunnel-interface)= - -# Tunnel - -Tunnel interfaces are virtual links that transmit encapsulated traffic between -private networks or hosts across public infrastructure, such as the Internet. -They operate using encapsulation protocols to wrap original traffic for -transport. The supported protocols include {abbr}`GRE (Generic Routing -Encapsulation)`, IPIP, IPIP6, IP6IP6, and 6in4 (SIT). - -While {abbr}`GRE (Generic Routing Encapsulation)` is often the preferred -one-size-fits-all solution due to its versatility, other encapsulation -protocols may be better suited for specific use cases. - -VyOS uses a single tunnel interface type for all of these protocols. There are -no separate {abbr}`GRE (Generic Routing Encapsulation)`, IPIP, or IP6IP6 -interface types; instead, the desired encapsulation protocol is selected within -the `set interfaces tunnel` configuration. - -Configuration options for each protocol are described below. - -:::{warning} -Do not change the encapsulation type for already configured tunnel -interfaces, as this may break their dependent configurations. -::: - -## Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: tunnel -:var1: tun0 -``` - -```{cmdincludemd} /_include/interface-common-without-mac.txt -:var0: tunnel -:var1: tun0 -``` - - -## IPIP - -IPIP is a straightforward encapsulation protocol defined in RFC 2003. It -encapsulates one IPv4 packet inside another IPv4 packet. - -Tunnels with IPIP encapsulation do not have protocol-specific configuration -options except for explicitly defining the encapsulation type as IPIP (see -the example below). - -Example: - -```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 - -IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside -another IPv6 packet. - -Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not -have protocol-specific configuration options except for explicitly defining -the encapsulation type as IP6IP6. - -Example: - -```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 - -IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets. - -Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with -IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6. - -Example: - -```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, also known as {abbr}`SIT (Simple Internet Transition)`, is an -encapsulation protocol defined in {rfc}`4213` that wraps IPv6 packets -inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41, -which is reserved exclusively for IPv6 encapsulation. - -The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet. -Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes -over an underlying network with a standard MTU of 1500 bytes without -fragmentation. - -6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as -[Hurricane Electric]) to connect isolated IPv6 networks or individual hosts to -the IPv6 internet. - -Example: - -```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 -``` - -:::{seealso} -For a practical configuration example, see the -{ref}`Tunnelbroker.net (IPv6) ` section. -::: - -## Generic Routing Encapsulation (GRE) - -{abbr}`GRE (Generic Routing Encapsulation)` is a versatile encapsulation -protocol defined in RFC 2784. Unlike simpler protocols such as IPIP, it allows -both IPv4 and IPv6 to be transported through the same tunnel. - -{abbr}`GRE (Generic Routing Encapsulation)` encapsulates original data packets -by adding a {abbr}`GRE (Generic Routing Encapsulation)` header, followed by an -IP header (the delivery header). The delivery header uses IP protocol number 47 -to identify {abbr}`GRE (Generic Routing Encapsulation)`-encapsulated traffic. - -In VyOS, {abbr}`GRE (Generic Routing Encapsulation)` tunnels can be established -over both IPv4 (encapsulation `gre`) and IPv6 (encapsulation `ip6gre`) -transport networks. - -### Configuration - -To configure a {abbr}`GRE (Generic Routing Encapsulation)` tunnel, you need to -define a tunnel source IP address, a tunnel destination IP address, an -encapsulation type ({abbr}`GRE (Generic Routing Encapsulation)`), and a tunnel -interface IP address. - -Example: - -The following example shows how to configure an IPv4/IPv6-over-IPv6 {abbr}`GRE -(Generic Routing Encapsulation)` tunnel between a VyOS router and a Linux host -running `systemd-networkd`. - -**VyOS router:** - -```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`: - -The `systemd-networkd` setup requires two configuration files: `xxx.netdev` -to create the {abbr}`GRE (Generic Routing Encapsulation)` tunnel interface, and -`xxx.network` to assign IP addresses to it. - -```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 -``` - - -### GRE keys - -A GRE key is an optional 32-bit field in the GRE header that allows multiple -GRE tunnels to operate between the same source and destination endpoints. When -a packet arrives, the receiver checks the GRE key to determine which tunnel -interface should process it. - -Although it may sound security-related, the GRE key is only an identifier and -provides no encryption or data protection. - -Example: - -```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 -``` - -```none -set interfaces tunnel tun1 source-address 192.0.2.10 -set interfaces tunnel tun1 remote 192.0.2.20 -set interfaces tunnel tun1 address 172.16.17.18/24 -set interfaces tunnel tun1 parameters ip key 20 -``` - - -### GRETAP - -Unlike GRE, which encapsulates only Layer 3 (IP) traffic, GRETAP encapsulates -Layer 2 (Ethernet) frames. - -That means that GRETAP tunnel interfaces can be members of a bridge interface. -This allows two geographically distant sites to connect as if they were on the -same LAN. - -GRETAP tunnels can be established over both IPv4 and IPv6 transport networks. - -Example: - -```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 standardized tunneling protocol used in many network environments. - -Although the GRE tunnel setup is straightforward, connectivity failures -frequently occur because ACLs or firewall rules block IP protocol 47 or -prevent direct communication between the tunnel endpoints. - -If your GRE tunnel fails to establish, perform these diagnostic steps: - -1\. Verify that the remote peer is reachable from the configured -`source-address`. - -This ensures that the underlying physical path between the two endpoints is -functional. - -```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\. Verify that the tunnel interface is correctly configured (with the link type -set to GRE) and is actively processing traffic. - -```none -vyos@vyos:~$ show interfaces tunnel tun100 -tun100@NONE: 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\. Test the connection through the tunnel using the private IP addresses -assigned to each tunnel endpoint. - -```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 -``` - -[hurricane electric]: https://tunnelbroker.net/ -[other proposals]: https://www.isc.org/othersoftware/ diff --git a/docs/configuration/interfaces/md-virtual-ethernet.md b/docs/configuration/interfaces/md-virtual-ethernet.md deleted file mode 100644 index dee1b332..00000000 --- a/docs/configuration/interfaces/md-virtual-ethernet.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -lastproofread: '2026-01-26' ---- - -(virtual-ethernet)= - -# Virtual Ethernet - -Virtual Ethernet (veth) interfaces are software-based interfaces that operate -in pairs, creating a tunnel between each other. Traffic transmitted into one -interface of the pair (e.g., `veth0`) is delivered directly to its peer -interface (e.g., `veth1`). - -Veth interfaces are commonly used to connect network namespaces or VRFs, but -they can also function as standalone virtual network interfaces. - -:::{note} -Veth interfaces must be created in pairs, where each interface acts -as the peer of the other. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address-with-dhcp.txt -:var0: virtual-ethernet -:var1: veth0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: virtual-ethernet -:var1: veth0 -``` - - -### VLAN - -#### Regular VLANs (802.1q) - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: virtual-ethernet -:var1: veth0 -``` - - -#### 802.1ad (QinQ) - -```{cmdincludemd} /_include/interface-vlan-8021ad.txt -:var0: virtual-ethernet -:var1: veth0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: virtual-ethernet -:var1: veth0 -``` - -```{cmdincludemd} /_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 \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces virtual-ethernet veth11 -10: veth11@veth10: 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 - -The following example shows how to connect the global VRF to VRF ‘red ‘ using -the `veth10` and `veth11` veth pair. - -```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/md-vti.md b/docs/configuration/interfaces/md-vti.md deleted file mode 100644 index dbd2c88c..00000000 --- a/docs/configuration/interfaces/md-vti.md +++ /dev/null @@ -1,121 +0,0 @@ -(vti-interface)= - -# VTI (virtual tunnel interface) - -{abbr}`VTIs (virtual tunnel interfaces)` let you create secure, encrypted -tunnels between private networks or hosts across public infrastructure, such as -the Internet. They operate alongside an underlying IPsec tunnel, which handles -encapsulation and encryption, while VTIs function exclusively as routing -interfaces. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-ip.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: vti -:var1: vti0 -``` - -```{cfgcmd} set interfaces vti \ mirror egress \ - -Configure mirroring of outgoing traffic from the specified VTI to the -designated monitor interface. -``` - -```{cfgcmd} set interfaces vti \ mirror ingress \ - -Configure mirroring of incoming traffic from the specified VTI to the -designated monitor interface. -``` - -```{cfgcmd} set interfaces vti \ redirect \ - -Enable redirection of incoming packets to the specified interface. -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: vti -:var1: vti0 -``` - - -## Operation - -```{opcmd} show interfaces vti \ - -Show the operational status and traffic statistics for the specified VTI. -``` - -```{opcmd} show interfaces vti \ brief - -Show a brief operational status summary for the specified VTI. -``` - - -## Example - -**Configure a VTI** - -Assign IPv4 and IPv6 addresses to the VTI, along with a brief description: - -```none -set interfaces vti vti0 address 192.168.2.249/30 -set interfaces vti vti0 address 2001:db8:2::249/64 -set interfaces vti vti0 description "Description" -``` - -Resulting configuration: - -```none -vyos@vyos# show interfaces vti -vti vti0 { - address 192.168.2.249/30 - address 2001:db8:2::249/64 - description "Description" -} -``` - -:::{warning} -When configuring site-to-site IPsec with VTIs, ensure that route -autoinstall is disabled. -::: - -```none -set vpn ipsec options disable-route-autoinstall -``` - -For more information about the IPsec and VTI issue, as well as the -`disable-route-autoinstall` option, see: - - -The root cause of the problem is that VTI tunnels require their traffic -selectors to be set to `0.0.0.0/0` for traffic to match the tunnel, even -though routing decisions are based on netfilter marks. Unless route insertion -is explicitly disabled, strongSWAN incorrectly inserts a default route through -the VTI peer address, causing all traffic to be misrouted. diff --git a/docs/configuration/interfaces/md-vxlan.md b/docs/configuration/interfaces/md-vxlan.md deleted file mode 100644 index 8dae75ff..00000000 --- a/docs/configuration/interfaces/md-vxlan.md +++ /dev/null @@ -1,373 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(vxlan-interface)= - -# VXLAN - -{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology -that addresses scalability challenges in large cloud computing environments. -It encapsulates Ethernet frames (Layer 2) within UDP datagrams (Layer 4), which -are then transmitted via UDP port 4789, as assigned by IANA. VXLAN endpoints, -called {abbr}`VTEPs (VXLAN tunnel endpoints)`, terminate VXLAN tunnels and can -be either virtual or physical switch ports. - -VXLAN supports up to 16 million logical networks and enables Layer 2 adjacency -across Layer 3 IP networks. It uses multicast or unicast with head-end -replication (HER) to flood broadcast, unknown unicast, and multicast (BUM) -traffic. - -The VXLAN specification was initially developed by VMware, Arista Networks, and -Cisco. Other supporters include Huawei, Broadcom, Citrix, Pica8, Big Switch -Networks, Cumulus Networks, Dell EMC, Ericsson, Mellanox, FreeBSD, OpenBSD, Red -Hat, Joyent, and Juniper Networks. - -VXLAN is officially documented by the IETF in {rfc}`7348`. - -When configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing -(Hyper-V) or Forged Transmits (ESX) are permitted. Otherwise, the hypervisor -may block forwarded frames. - -:::{note} -Although the IANA-assigned VXLAN port is **4789**, VyOS uses the -Linux default UDP port **8472** for VXLAN interfaces. To ensure compatibility -with other vendors, set the port to the IANA standard **4789**. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-without-dhcp.txt -:var0: vxlan -:var1: vxlan0 -``` - - -### VXLAN-specific options - -```{cfgcmd} set interfaces vxlan \ vni \ - -**Configure a** {abbr}`VNI (VXLAN Network Identifier)` **for the VXLAN -interface.** - -Each VXLAN segment is identified by this 24-bit VNI, allowing up to 16 million -segments to coexist within the same administrative domain. -``` - -```{cfgcmd} set interfaces vxlan \ port \ - -Configure the UDP port of the remote VXLAN endpoint. - -:::{note} -Although the IANA-assigned VXLAN port is **4789**, VyOS uses the -Linux default UDP port **8472** for VXLAN interfaces. -::: -``` - -```{cfgcmd} set interfaces vxlan \ source-address \ - -Configure the source IP address for the VXLAN underlay. - -:::{warning} -This setting is mandatory when deploying VXLAN via L2VPN/EVPN. -::: -``` - -```{cfgcmd} set interfaces vxlan \ gpe - -**Enable the** {abbr}`GPE (Generic Protocol Extension)` **for the VXLAN -interface.** - -To use this feature, you must configure the interface with the ``external`` -parameter. -``` - -```{cfgcmd} set interfaces vxlan \ parameters external - -**Configure the VXLAN interface to use an external control plane, such as BGP -L2VPN/EVPN, for remote endpoint discovery.** - -If not configured, the internal {abbr}`FDB (Forwarding Database)` is used. -``` - -```{cfgcmd} set interfaces vxlan \ parameters neighbor-suppress - -**Enable ARP and ND suppression on the VXLAN interface.** - -This reduces ARP and ND message flooding across the VXLAN network. As defined -in {rfc}`7432#section-10`, participating VTEPs use known MAC-to-IP bindings -to reply to local requests on behalf of remote hosts. -``` - -```{cfgcmd} set interfaces vxlan \ parameters nolearning - -Disable {abbr}`SLLA (Source Link-Layer Address)` and IP address learning on -the VXLAN interface. -``` - -```{cfgcmd} set interfaces vxlan \ parameters vni-filter - -**Enable** {abbr}`VNI (VXLAN Network Identifier)` **filtering on the VXLAN -interface.** - -When enabled, the interface only receives packets with VNIs configured in its -VNI filtering table. - -:::{note} -VNI filtering works only if the interface is configured with the -``external`` parameter. -::: -``` - - -#### Unicast - -```{cfgcmd} set interfaces vxlan \ remote \ - -**Configure the IPv4 or IPv6 address of the remote VTEP.** - -Unlike multicast setups, this command allows you to directly configure the -remote IPv4 or IPv6 address. -``` - - -#### Multicast - -```{cfgcmd} set interfaces vxlan \ source-interface \ - -**Configure the source interface for the VXLAN underlay.** - -All VXLAN traffic is sent and received through the specified interface. -This setting is mandatory when deploying VXLAN over a multicast network. -``` - -```{cfgcmd} set interfaces vxlan \ group \ - -**Configure the IPv4 or IPv6 multicast group address for the VXLAN interface.** - -VXLAN tunnels can be built using either multicast group or unicast IP addresses. -``` - - -## Multicast VXLAN - -Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 - -PC4 uses the IP address `10.0.0.4/24`, and PC5 uses the IP address -`10.0.0.5/24`. Both devices assume they reside within the same broadcast -domain. - -Assume PC4 on Leaf2 pings PC5 on Leaf3. Rather than manually specifying Leaf3 -as the remote endpoint, Leaf2 encapsulates the packet into a UDP datagram and -sends it to the designated multicast address via Spine1. Spine1 forwards the -packet to all leaves in the same multicast group, including Leaf3. Upon -receiving the datagram, Leaf3 forwards it to PC5 and learns that PC4 is -reachable through Leaf2 by inspecting the source IP in the encapsulated -datagram. - -PC5 receives the ping and responds with an echo reply. Leaf3, now aware of -PC4's location, forwards the reply directly to Leaf2's unicast address. Upon -receiving the echo reply, Leaf2 learns that PC5 is reachable through Leaf3. - -After this discovery, subsequent traffic between PC4 and PC5 will not use the -multicast address between the leaves, as both leaves have learned the PCs' -locations. This reduces multicast traffic and network load, improving -scalability as more leaves are added. - -## Single VXLAN device (SVD) - -In VyOS, you can configure multiple **VLAN-to-VNI mappings** for EVPN-VXLAN on -a single container interface, known as a single VXLAN device (SVD). This -enables significant VNI scaling because a separate VXLAN interface is not -required for each VNI. - -```{cfgcmd} set interfaces vxlan \ vlan-to-vni \ vni \ - -**Map a VLAN ID to a VNI on the specified VXLAN interface.** - -The VXLAN interface can be added to a bridge. - -The following example shows an SVD configuration with multiple VLAN-to-VNI -mappings. - -:::{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 following example demonstrates a multicast VXLAN deployment. - -The setup includes three routers: Spine1, a Cisco IOS router, and Leaf2 and -Leaf3, which are VyOS routers. - -**Topology:** Leaf2 - Spine1 - Leaf3. - -The topology is built using GNS3. - -```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:** - -```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 scalable traffic forwarding between leaves. -{abbr}`PIM (Protocol Independent Multicast)` must be enabled towards the leaves -so the spine can learn from which multicast groups each leaf expects traffic. - -**Leaf2 configuration:** - -```none -set interfaces ethernet eth0 address '10.1.2.2/24' -set protocols ospf area 0 network '10.0.0.0/8' - -! 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' - -! Second 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:** - -```none -set interfaces ethernet eth0 address '10.1.3.3/24' -set protocols ospf area 0 network '10.0.0.0/8' - -! 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' - -! Second 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' -``` - -The configurations for Leaf2 and Leaf3 are nearly identical. Detailed -explanations for each command are provided below. - -```none -set interfaces bridge br241 address '172.16.241.1/24' -``` - -This command creates a bridge to bind traffic on `eth1` VLAN 241 with the -`vxlan241` interface. The IP address is optional. If configured, it can serve -as the default gateway for each leaf, allowing devices on the VLAN to reach -other subnets. Subnets must be redistributed by {abbr}`OSPF (Open Shortest Path -First)` so the spine can learn how to reach them. To advertise `172.16/12` -networks, change the {abbr}`OSPF (Open Shortest Path First)` network from -`10.0.0.0/8` to `0.0.0.0/0`. - -```none -set interfaces bridge br241 member interface 'eth1.241' -set interfaces bridge br241 member interface 'vxlan241' -``` - -These commands bind `eth1.241` and `vxlan241` as member interfaces of the -same bridge. - -```none -set interfaces vxlan vxlan241 group '239.0.0.241' -``` - -This command configures the multicast group used by all leaves for this VLAN -extension. It must be the same on all leaves that have this interface. - -```none -set interfaces vxlan vxlan241 source-interface 'eth0' -``` - -This command configures the interface that listens for multicast packets. It -can also be a loopback interface. - -```none -set interfaces vxlan vxlan241 vni '241' -``` - -This command configures the unique ID for the VXLAN interface. - -```none -set interfaces vxlan vxlan241 port 12345 -``` - -VyOS uses the Linux default UDP port **8472** for VXLAN interfaces. This -command allows you to configure a different UDP port. - -## Unicast VXLAN - -As an alternative to multicast, you can configure the VXLAN tunnel by -specifying the remote IPv4 address directly. The following updates the previous -multicast example: - -```none -# leaf2 and leaf3 -delete interfaces vxlan vxlan241 group '239.0.0.241' -delete interfaces vxlan vxlan241 source-interface 'eth0' - -# leaf2 -set interfaces vxlan vxlan241 remote 10.1.3.3 - -# leaf3 -set interfaces vxlan vxlan241 remote 10.1.2.2 -``` - -The default UDP port is 8472. To configure a different port, use `set -interfaces vxlan port `. diff --git a/docs/configuration/interfaces/md-wireguard.md b/docs/configuration/interfaces/md-wireguard.md deleted file mode 100644 index 121d1df0..00000000 --- a/docs/configuration/interfaces/md-wireguard.md +++ /dev/null @@ -1,434 +0,0 @@ ---- -lastproofread: '2026-03-02' ---- - -(wireguard)= - -# WireGuard - -WireGuard is an extremely simple, fast, and modern VPN that utilizes -state-of-the-art cryptography. See for more -information. - -## Site-to-site VPN - -The following diagram illustrates a site-to-site VPN setup. - -:::{figure} /_static/images/wireguard_site2site_diagram.webp -::: - -## Keypairs - -WireGuard requires a keypair, which includes a **private** key -to decrypt incoming traffic, and a **public** key for peer(s) to encrypt -outgoing traffic. - -### Generate keypair - -```{opcmd} generate pki wireguard key-pair - -Generate a keypair: a public and a private key. - -:::{note} -This command only outputs the keys to your console. It neither stores -them in the system nor applies them to the system configuration. -::: - -:::{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 \ - -Generate a keypair and output the private key assignment command for the -specified 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 automatically added to the VyOS configuration, use the following configuration mode commands to install key: - -set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0=' - -Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro=' -::: - -:::{note} -If you invoke this command from configuration mode with the ``run`` -prefix, the generated private key is automatically assigned to the specified -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 \ public-key - -Show the public key assigned to the interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces wireguard wg01 public-key -EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= -::: -``` - -#### Optional - -```{opcmd} generate pki wireguard preshared-key - -Generate a pre-shared key. - -The pre-shared key is optional. It adds an additional layer of symmetric-key -cryptography on top of the asymmetric cryptography. - -:::{code-block} none -vyos@vyos:~$ generate pki wireguard preshared-key -Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= -::: -``` - -```{opcmd} generate pki wireguard preshared-key install interface \ peer \ - -Generate a pre-shared key and output the key assignment command for the -specified peer. - -:::{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 you invoke this command from configuration mode with the run -prefix, the generated key is automatically assigned to the specified peer. -::: -``` - -## Interface configuration - -The next step is to configure your local WireGuard interface and define the -networks you want to tunnel (`allowed-ips`). - -If your system only initiates connections, specifying the listen port is -optional. If your system accepts incoming connections, you must define a port -for peers to connect to. Otherwise, WireGuard selects a random port at each -reboot, and that may break your peers' ability to connect if that port is not enabled in your firewall rules. - -To configure a WireGuard tunnel, you also need your peer's public key. - -:::{note} -The public key specified in the peer configuration block is always -the **remote** peer's public key, never your local one. -::: - -**Local side configuration** - -The local side is configured with the following parameters: -- Local WireGuard interface IP: `10.1.0.1/30` -- Local listen port: `51820` -- Remote peer name: `to-wg02` -- Remote peer endpoint: `192.0.2.1` on port `51820` -- Remote peer public key: `XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=` -- Allowed networks: `192.168.2.0/24` - -```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 -``` - -To send traffic destined for `192.168.2.0/24` through the WireGuard interface -(`wg01`), configure a static route. Multiple IP addresses or networks can be -defined and routed. The final check is performed against `allowed-ips`, which -either permits or drops the traffic. - -:::{warning} -You cannot assign the same `allowed-ips` to multiple WireGuard -peers. This is a strict design restriction. For more information, check the -[WireGuard mailing list]. -::: - -```{cfgcmd} set interfaces wireguard \ private-key \ - -Assign a private key to the specified WireGuard interface. - -Example: - -:::{code-block} none -set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' -::: - -To generate a private key, use the following command: -{opcmd}`generate pki wireguard key-pair`. - -To view the public key assigned to the interface so you can share it with a -peer, use the following command: -{opcmd}`show interfaces wireguard wg01 public-key`. -``` - - -```{cmdincludemd} /_include/interface-per-client-thread.txt -:var0: wireguard -:var1: wg01 -``` - -**Remote side configuration** - -```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 - - -To allow WireGuard traffic through the WAN interface, create a firewall -exception: - -```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 -``` - -Ensure that the OUTSIDE_LOCAL firewall group is applied to the WAN interface -and in an input (local) direction. - -```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' -``` - -Verify that your firewall rules permit traffic. If so, your WireGuard VPN -should be operational. - -```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 cryptography can be used on top of the -asymmetric cryptography. This is optional. - -```none -vyos@vyos:~$ generate pki wireguard preshared-key -Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= -``` - -Copy the key, as it is not stored locally. Since it is a symmetric key, only -you and your peer should know its contents. Distribute the key securely. - -```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 (road warrior) - - -With WireGuard, a road warrior VPN configuration is similar to a site-to-site -VPN. It just omits the `address` and `port` statements. - - -In the following example, the IP addresses for remote clients are defined -within each peer configuration. This allows peers to communicate with each -other. - - -Additionally, this setup uses a `persistent-keepalive` flag set to 15 seconds -to keep the connection alive. This setting is mainly relevant if a peer is -behind NAT and cannot be reached if the connection is lost. For effectiveness, -the value should be lower than the UDP timeout. - -```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 - pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= - } - peer iPhone { - allowed-ips 10.172.24.20/32 - allowed-ips 2001:db8:470:22::20/128 - persistent-keepalive 15 - pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= - } - port 2224 - private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU= -} -``` - -Below is the configuration for the iPhone peer. The `AllowedIPs` wildcard -setting directs all IPv4 and IPv6 traffic through the VPN connection. - -```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 = 15 -``` - -To enable split tunneling, specify the remote subnets. This ensures that only -traffic destined for the remote site is sent through the tunnel, while all -other traffic remains unaffected. - -```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 = 15 -``` - -## Operational commands - - -### Status - -```{opcmd} show interfaces wireguard wg01 summary - -Show information about the WireGuard service, including the latest handshake. - -:::{code-block} none -vyos@vyos:~$ show interfaces wireguard wg01 summary -interface: wg01 -public key: -private key: (hidden) -listening port: 51820 - -peer: -endpoint: -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 - -Show 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 \ - -Show general information about a 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 (road warrior) clients - -Some users connect mobile devices to their VyOS router using WireGuard. To -simplify deployment, 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 secure connection. You should -create the private portion yourself and hand out only the public key. -::: - -```{opcmd} generate wireguard client-config \ interface \ server \ address \ - -**Generate a client configuration file that establishes a connection to the -specified interface.** - -The public key from the specified interface is automatically included in the -configuration file. - -The command also generates a configuration snippet that can be copied into the -VyOS CLI. The ```` you provide will be used as the peer name in the -snippet. - -You must also specify the IP address or FQDN of the server the client connects -to. The address parameter can be used twice to assign both an IPv4 (/32) and -an IPv6 (/128) address to the client. - -:::{figure} /_static/images/wireguard_qrcode.webp -:alt: WireGuard Client QR code -::: -``` - -[wireguard mailing list]: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html diff --git a/docs/configuration/interfaces/md-wireless.md b/docs/configuration/interfaces/md-wireless.md deleted file mode 100644 index 9e6b7c99..00000000 --- a/docs/configuration/interfaces/md-wireless.md +++ /dev/null @@ -1,923 +0,0 @@ ---- -lastproofread: '2026-03-23' ---- - -(wireless-interface)= - -# Wireless LAN / Wi-Fi - -{abbr}`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless -connectivity, referred to as Wi-Fi, and operate in one of the following -modes: - -- {abbr}`WAP (Wireless Access-Point)` mode provides network access to connecting - stations if the physical hardware supports acting as a WAP -- Station mode acts as a Wi-Fi client accessing the network through an available - WAP -- Monitor mode lets the system passively monitor wireless traffic - -If the system detects an unconfigured wireless device, it will be automatically -added to the configuration tree, specifying any detected settings (for example, -its MAC address) and configured to run in monitor mode. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: wireless -:var1: wlan0 -``` - - -### System-wide configuration - -```{cfgcmd} set system wireless country-code \ - -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. -::: -``` - - -### Wireless options - -```{cfgcmd} set interfaces wireless \ channel \ - -Configure the IEEE 802.11 wireless radio channel for the interface. -Channel allocation depends on the frequency band: -* **2.4 GHz** (802.11b/g/n/ax): Channels range from 1 to 14. -* **5 GHz** (802.11a/h/j/n/ac/ax): Channels range from 34 to 177. -* **6 GHz** (802.11ax): Channels range from 1 to 233. -* **Automatic channel selection:** 0. -``` - -```{cfgcmd} set interfaces wireless \ 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 the SSID. -``` - -```{cfgcmd} set interfaces wireless \ 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 \ 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 \ 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 \ mgmt-frame-protection - -Management Frame Protection (MFP) according to IEEE 802.11w - -:::{note} -{abbr}`MFP (Management Frame Protection)` is required for WPA3. -::: -``` - -```{cfgcmd} set interfaces wireless \ enable-bf-protection - -Beacon Protection: management frame protection for Beacon frames. - -:::{note} -This option requires {abbr}`MFP (Management Frame Protection)` -to be enabled. -::: -``` - -```{cfgcmd} set interfaces wireless \ mode \ - -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 -* ``ax`` - 802.11ax - exceeds 1GBit/sec - -:::{note} -In VyOS, 802.11ax is only implemented for 2.4GHz and 6GHz. -::: -``` - -```{cfgcmd} set interfaces wireless \ physical-device \ - -Wireless hardware device used as underlay radio. - -This defaults to phy0. -``` - -```{cfgcmd} set interfaces wireless \ reduce-transmit-power \ - -Adds the Power Constraint information element to Beacon and Probe Response -frames. - -This option adds the Power Constraint information element when applicable -and the Country information element is configured. The Power Constraint -element is required by Transmit Power Control. - -Valid values are 0..255. -``` - -```{cfgcmd} set interfaces wireless \ ssid \ - -SSID to be used in IEEE 802.11 management frames -``` - -```{cfgcmd} set interfaces wireless \ type \ - -Wireless device type for this interface -* ``access-point``: Forwards packets between other nodes. -* ``station``: Connects to another {abbr}`AP (Access Point)`. -* ``monitor``: Passively monitors all packets on the frequency/channel. -``` - -```{cmdincludemd} /_include/interface-per-client-thread.txt -:var0: wireless -:var1: wlan0 -``` - - -#### PPDU - -```{cfgcmd} set interfaces wireless \ capabilities require-ht - -``` -```{cfgcmd} set interfaces wireless \ capabilities require-vht -``` - -```{cfgcmd} set interfaces wireless \ capabilities require-he -``` - -##### HT (High Throughput) capabilities (802.11n) - -> Configuring HT mode options is required when using 802.11n or -> 802.11ax at 2.4GHz. - -```{cfgcmd} set interfaces wireless \ capabilities ht 40mhz-incapable - -Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht auto-powersave - -WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht channel-set-width \ - -Supported channel width set. -* ``ht20`` - 20 MHz channel width -* ``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} -Channel availability for HT40- and HT40+ is limited. The following -table lists channels permitted for HT40- and HT40+ according to IEEE -802.11n Annex J. Channel availability may vary by location. - - ::::{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 may be rejected based on overlapping -BSSes. These changes are done automatically when hostapd is setting up the -40 MHz channel. -::: -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht delayed-block-ack - -Enable HT-delayed Block Ack ``[DELAYED-BA]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht dsss-cck-40 - -DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht greenfield - -This enables the greenfield option which sets the ``[GF]`` option -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht ldpc - -Enable LDPC coding capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht lsig-protection - -Enable L-SIG TXOP protection capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht max-amsdu \<3839 | 7935\> - -Maximum A-MSDU length 3839 (default) or 7935 octets -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht short-gi \<20 | 40\> - -Short GI capabilities for 20 and 40 MHz -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht smps \ - -Spatial Multiplexing Power Save (SMPS) settings -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht stbc rx \ - -Enable receiving PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht stbc tx - -Enable sending PPDU using STBC (Space Time Block Coding) -``` - -##### VHT (Very High Throughput) capabilities (802.11ac) - -```{cfgcmd} set interfaces wireless \ capabilities vht antenna-count \ -``` - -% -% Number of antennas on this card - -```{cfgcmd} set interfaces wireless \ capabilities vht antenna-pattern-fixed - -Set if antenna pattern does not change during the lifetime of an association -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht beamform \ - -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 -multi user beamformer -* ``multi-user-beamformee`` - Support for operation as -multi user beamformee -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht center-channel-freq \ \ - -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) - -\ must be from 34 - 173. For 80 MHz channels it should be channel + 6. -``` - -```{cfgcmd} set interfaces wireless \ 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 \ capabilities vht ldpc - -Enable LDPC (Low Density Parity Check) coding capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht link-adaptation - -VHT link adaptation capabilities -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht max-mpdu \ - -Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht max-mpdu-exp \ - -Set the maximum length of A-MPDU pre-EOF padding that the station can -receive -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht short-gi \<80 | 160\> - -Short GI capabilities -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht stbc rx \ - -Enable receiving PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht stbc tx - -Enable sending PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht tx-powersave - -Enable VHT TXOP Power Save Mode -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht vht-cf - -Station supports receiving VHT variant HT Control field -``` - -##### HE (High Efficiency) capabilities (802.11ax) - -```{cfgcmd} set interfaces wireless \ capabilities he antenna-pattern-fixed - -Tell the AP that antenna positions are fixed and will not change -during the lifetime of an association. -``` - -```{cfgcmd} set interfaces wireless \ capabilities he beamform \ - -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 multi -user beamformer -``` - -```{cfgcmd} set interfaces wireless \ capabilities he bss-color \ - -BSS coloring helps to prevent channel jamming when multiple APs use -the same channels. - -Valid values are 1..63 -``` - -```{cfgcmd} set interfaces wireless \ capabilities he center-channel-freq \ \ - -HE operating channel center frequency - center freq 1 -(for use with 80, 80+80 and 160 modes) - -HE operating channel center frequency - center freq 2 -(for use with the 80+80 mode) - -\ must be within 1..233. For 80 MHz channels it should be -channel + 6 and for 160 MHz channels, it should be channel + 14. -``` - -```{cfgcmd} set interfaces wireless \ capabilities he channel-set-width \ - -\ must be one of: - -* ``81`` - 20 MHz channel width (2.4GHz) -* ``83`` - 40 MHz channel width, secondary 20MHz channel above primary -channel (2.4GHz) -* ``84`` - 40 MHz channel width, secondary 20MHz channel below primary -channel (2.4GHz) -* ``131`` - 20 MHz channel width (6GHz) -* ``132`` - 40 MHz channel width (6GHz) -* ``133`` - 80 MHz channel width (6GHz) -* ``134`` - 160 MHz channel width (6GHz) -* ``135`` - 80+80 MHz channel width (6GHz) -``` - -```{cfgcmd} set interfaces wireless \ capabilities he coding-scheme \ - -This setting configures Spatial Stream and Modulation Coding Scheme -settings for HE mode (HE-MCS). It is usually not needed to set this -explicitly, but it might help with some WiFi adapters. - -\ must be one of: -* ``0`` - HE-MCS 0-7 -* ``1`` - HE-MCS 0-9 -* ``2`` - HE-MCS 0-11 -* ``3`` - HE-MCS is not supported -``` - -### 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. - -```none -set system wireless country-code de -set interfaces wireless wlan0 type station -set interfaces wireless wlan0 address dhcp -set interfaces wireless wlan0 ssid 'TEST' -set interfaces wireless wlan0 security wpa passphrase '12345678' -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - wireless wlan0 { - address dhcp - security { - wpa { - passphrase "12345678" - } - } - ssid TEST - type station - } -``` - -### Security - -{abbr}`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 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` - -```none -set system wireless country-code de -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 'Enterprise-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 configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - radius { - server 192.168.3.10 { - key 'VyOSPassword' - port 1812 - } - } - } - } - ssid "Enterprise-TEST" - type access-point - } -} -``` - -### VLAN -#### Regular VLANs (802.1q) - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: wireless -:var1: wlan0 -``` - -#### QinQ (802.1ad) - -```{cmdincludemd} /_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. - -```none -vyos@vyos:~$ show interfaces wireless info -Interface Type SSID Channel -wlan0 access-point VyOS-TEST-0 1 -``` - -```{opcmd} show interfaces wireless detail -``` - -Show the operational status and detailed wireless-specific -information about all wireless interfaces. - -```none -vyos@vyos:~$ show interfaces wireless detail -wlan0: 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: 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 \ -``` - -This command shows both status and statistics on the specified wireless -interface. The wireless interface identifier can range from wlan0 to wlan999. - -```none -vyos@vyos:~$ show interfaces wireless wlan0 -wlan0: 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 \ brief -``` - -This command gives a brief status overview of a specified wireless interface. -The wireless interface identifier can range from wlan0 to wlan999. - -```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 \ queue -``` - -Use this command to view wireless interface queue information. -The wireless interface identifier can range from wlan0 to wlan999. - -```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 \ 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. -::: -```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` - -```none -set system wireless country-code de -set interfaces wireless wlan0 address '192.168.2.1/24' -set interfaces wireless wlan0 type access-point -set interfaces wireless wlan0 channel 1 -set interfaces wireless wlan0 mode n -set interfaces wireless wlan0 ssid 'TEST' -set interfaces wireless wlan0 security wpa mode wpa2 -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa passphrase '12345678' -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - passphrase "12345678" - } - } - ssid "TEST" - type access-point - } -} -``` - -To enable access point functionality, configure a DHCP server for this -interface's network, or add the interface to an existing local bridge -(see {ref}`bridge-interface` for details). - -### Wi-Fi 6/6E (802.11ax) - -The following examples configure Wi-Fi 6 (2.4 GHz) and Wi-Fi 6E (6 GHz) -{abbr}`APs (Access Points)` with the following parameters: -- Network ID (SSID): `test.ax` -- WPA passphrase: `super-dooper-secure-passphrase` -- Protocol: 802.11ax -- Wireless channel for 2.4 GHz: `11` -- Wireless channel for 6 GHz: `5` - -#### Example configuration: Wi-Fi 6 at 2.4 GHz - -You may expect real throughput around 10 MB/s or higher in crowded areas. - -```none -set system wireless country-code de -set interfaces wireless wlan0 capabilities he antenna-pattern-fixed -set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer -set interfaces wireless wlan0 capabilities he beamform single-user-beamformee -set interfaces wireless wlan0 capabilities he beamform single-user-beamformer -set interfaces wireless wlan0 capabilities he bss-color 13 -set interfaces wireless wlan0 capabilities he channel-set-width 81 -set interfaces wireless wlan0 capabilities ht 40mhz-incapable -set interfaces wireless wlan0 capabilities ht channel-set-width ht20 -set interfaces wireless wlan0 capabilities ht channel-set-width ht40+ -set interfaces wireless wlan0 capabilities ht channel-set-width ht40- -set interfaces wireless wlan0 capabilities ht short-gi 20 -set interfaces wireless wlan0 capabilities ht short-gi 40 -set interfaces wireless wlan0 capabilities ht stbc rx 2 -set interfaces wireless wlan0 capabilities ht stbc tx -set interfaces wireless wlan0 channel 11 -set interfaces wireless wlan0 description "802.11ax 2.4GHz" -set interfaces wireless wlan0 mode ax -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa cipher CCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP -set interfaces wireless wlan0 security wpa mode wpa2 -set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase -set interfaces wireless wlan0 ssid test.ax -set interfaces wireless wlan0 type access-point -commit -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - capabilities { - he { - antenna-pattern-fixed - beamform { - multi-user-beamformer - single-user-beamformee - single-user-beamformer - } - bss-color 13 - channel-set-width 81 - } - ht { - 40mhz-incapable - channel-set-width ht20 - channel-set-width ht40+ - channel-set-width ht40- - short-gi 20 - short-gi 40 - stbc { - rx 2 - tx - } - } - } - channel 11 - description "802.11ax 2.4GHz" - hw-id [...] - mode ax - physical-device phy0 - security { - wpa { - cipher CCMP - cipher CCMP-256 - cipher GCMP-256 - cipher GCMP - mode wpa2 - passphrase super-dooper-secure-passphrase - } - } - ssid test.ax - type access-point - } -} -``` - -#### Example configuration: Wi-Fi 6E at 6 GHz - -You may expect real throughput between 50 MB/s and 150 MB/s, depending on -obstructions from walls, water, metal, or other materials -with high electromagnetic damping at 6 GHz. Best results are achieved -with the AP being in the same room and in line-of-sight. - -```none -set system wireless country-code de -set interfaces wireless wlan0 capabilities he antenna-pattern-fixed -set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer -set interfaces wireless wlan0 capabilities he beamform single-user-beamformee -set interfaces wireless wlan0 capabilities he beamform single-user-beamformer -set interfaces wireless wlan0 capabilities he bss-color 13 -set interfaces wireless wlan0 capabilities he channel-set-width 134 -set interfaces wireless wlan0 capabilities he center-channel-freq freq-1 15 -set interfaces wireless wlan0 channel 5 -set interfaces wireless wlan0 description "802.11ax 6GHz" -set interfaces wireless wlan0 mode ax -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa cipher CCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP -set interfaces wireless wlan0 security wpa mode wpa3 -set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase -set interfaces wireless wlan0 mgmt-frame-protection required -set interfaces wireless wlan0 enable-bf-protection -set interfaces wireless wlan0 ssid test.ax -set interfaces wireless wlan0 type access-point -set interfaces wireless wlan0 stationary-ap -commit -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - capabilities { - he { - antenna-pattern-fixed - beamform { - multi-user-beamformer - single-user-beamformee - single-user-beamformer - } - bss-color 13 - center-channel-freq { - freq-1 15 - } - channel-set-width 134 - } - } - channel 5 - description "802.11ax 6GHz" - enable-bf-protection - hw-id [...] - mgmt-frame-protection required - mode ax - physical-device phy0 - security { - wpa { - cipher CCMP - cipher CCMP-256 - cipher GCMP-256 - cipher GCMP - mode wpa3 - passphrase super-dooper-secure-passphrase - } - } - ssid test.ax - stationary-ap - type access-point - } -} -``` - -(wireless-interface-intel-ax200)= - -### Intel AX200 - -The Intel AX200 card does not work out of the box in AP mode. You can -still put this card into AP mode using the following configuration: - -```none -set system wireless country-code 'us' -set interfaces wireless wlan0 channel '1' -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' -``` - diff --git a/docs/configuration/interfaces/md-wwan.md b/docs/configuration/interfaces/md-wwan.md deleted file mode 100644 index e8121f28..00000000 --- a/docs/configuration/interfaces/md-wwan.md +++ /dev/null @@ -1,355 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(wwan-interface)= - -# WWAN - -{abbr}`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular -networks via a cellular modem or card. - -Configure these interfaces under the `interfaces wwan` node. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address-with-dhcp.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-disable-link-detect.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-ip.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: wwan -:var1: wwan0 -``` - -**DHCP(v6)** - -```{cmdincludemd} /_include/interface-dhcp-options.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-dhcpv6-options.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt -:var0: wwan -:var1: wwan0 -``` - - -### WWAN options - -```{cfgcmd} set interfaces wwan \ apn \ - -**Configure the** {abbr}`APN (Access Point Name)` **for the WWAN connection.** - -Every WWAN connection requires an {abbr}`APN (Access Point Name)` to connect to -the cellular network. - -This parameter is mandatory. Contact your service provider for the correct -{abbr}`APN (Access Point Name)`. -``` - - -## Operation - -```{opcmd} show interfaces wwan \ - -Show the operational status and traffic statistics for the specified WWAN -interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 -wwan0: 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 \ summary - -Show WWAN module hardware characteristics and connection information. - -:::{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 \ capabilities - -Show WWAN module radio 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 \ firmware - -Show WWAN module firmware information. - -:::{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 \ 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 \ imsi - -Show the IMSI of the associated SIM card. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 imsi -IMSI: '262xxxxxxxxxxxx' -::: -``` - -```{opcmd} show interfaces wwan \ model - -Show WWAN module model. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 model -Model: 'MC7710' -::: -``` - -```{opcmd} show interfaces wwan \ msisdn - -Show the MSISDN of the associated SIM card. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 msisdn -MSISDN: '4917xxxxxxxx' -::: -``` - -```{opcmd} show interfaces wwan \ 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 \ signal - -Show signal information for the cellular connection. - -:::{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 \ 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 shows how to configure a cellular connection using a -Sierra Wireless MC7710 miniPCIe card that operates over USB despite its form -factor. The card is installed in a {ref}`pc-engines-apu4`. - -```none -set interfaces wwan wwan0 apn 'internet.telekom' -set interfaces wwan wwan0 address 'dhcp' -``` - - -## Supported hardware - -The following WWAN modules have been successfully tested with a -{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 - -WWAN modules include reprogrammable firmware, and most vendors regularly -provide updates for it. - -Since VyOS communicates with these devices via the QMI interface, you can -update firmware directly within the system using the `qmi-firmware-update` -utility. - -The following example shows how to update the firmware for a Sierra Wireless -MC7710 module using the provided .cwe file. - -```bash -$ sudo qmi-firmware-update --update -d 1199:68a2 \ - 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe -``` -- cgit v1.2.3