From fa54a080fac977157454beb0853daf0ac0e6af66 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sat, 2 May 2026 17:25:47 +0300 Subject: feat(swap): import .md files and webp transition from myst/current MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Selective import from origin/myst/current (cf9c9b34): - Add/update 255 .md files (full MyST conversion plus webp ref updates) - Delete 175 PNG/JPG from docs/_static/images (webp twins already present) - Delete 5 autotest topology.png (webp twins already present) Preserved on swap (untouched): - All .rst files (incremental swap pattern) - conf.py, _ext/, _include/*.txt, .gitignore - 115 canary md-*.md files - 7 superpowers/specs/*.md design docs - Logos vyos-logo.png / vyos-logo-icon.png (referenced by conf.py) 🤖 Generated by [robots](https://vyos.io) --- docs/configuration/interfaces/bonding.md | 764 ++++++++++++++++++ docs/configuration/interfaces/bridge.md | 431 ++++++++++ docs/configuration/interfaces/dummy.md | 87 ++ docs/configuration/interfaces/ethernet.md | 515 ++++++++++++ docs/configuration/interfaces/geneve.md | 105 +++ docs/configuration/interfaces/index.md | 26 + docs/configuration/interfaces/l2tpv3.md | 170 ++++ docs/configuration/interfaces/loopback.md | 67 ++ docs/configuration/interfaces/macsec.md | 319 ++++++++ docs/configuration/interfaces/openvpn-examples.md | 769 ++++++++++++++++++ docs/configuration/interfaces/openvpn.md | 614 ++++++++++++++ docs/configuration/interfaces/pppoe.md | 419 ++++++++++ docs/configuration/interfaces/pseudo-ethernet.md | 52 ++ docs/configuration/interfaces/sstp-client.md | 170 ++++ docs/configuration/interfaces/tunnel.md | 309 ++++++++ docs/configuration/interfaces/virtual-ethernet.md | 119 +++ docs/configuration/interfaces/vti.md | 121 +++ docs/configuration/interfaces/vxlan.md | 373 +++++++++ docs/configuration/interfaces/wireguard.md | 434 ++++++++++ docs/configuration/interfaces/wireless.md | 923 ++++++++++++++++++++++ docs/configuration/interfaces/wwan.md | 355 +++++++++ 21 files changed, 7142 insertions(+) create mode 100644 docs/configuration/interfaces/bonding.md create mode 100644 docs/configuration/interfaces/bridge.md create mode 100644 docs/configuration/interfaces/dummy.md create mode 100644 docs/configuration/interfaces/ethernet.md create mode 100644 docs/configuration/interfaces/geneve.md create mode 100644 docs/configuration/interfaces/index.md create mode 100644 docs/configuration/interfaces/l2tpv3.md create mode 100644 docs/configuration/interfaces/loopback.md create mode 100644 docs/configuration/interfaces/macsec.md create mode 100644 docs/configuration/interfaces/openvpn-examples.md create mode 100644 docs/configuration/interfaces/openvpn.md create mode 100644 docs/configuration/interfaces/pppoe.md create mode 100644 docs/configuration/interfaces/pseudo-ethernet.md create mode 100644 docs/configuration/interfaces/sstp-client.md create mode 100644 docs/configuration/interfaces/tunnel.md create mode 100644 docs/configuration/interfaces/virtual-ethernet.md create mode 100644 docs/configuration/interfaces/vti.md create mode 100644 docs/configuration/interfaces/vxlan.md create mode 100644 docs/configuration/interfaces/wireguard.md create mode 100644 docs/configuration/interfaces/wireless.md create mode 100644 docs/configuration/interfaces/wwan.md (limited to 'docs/configuration/interfaces') diff --git a/docs/configuration/interfaces/bonding.md b/docs/configuration/interfaces/bonding.md new file mode 100644 index 00000000..7a07a27c --- /dev/null +++ b/docs/configuration/interfaces/bonding.md @@ -0,0 +1,764 @@ +--- +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/bridge.md b/docs/configuration/interfaces/bridge.md new file mode 100644 index 00000000..77775767 --- /dev/null +++ b/docs/configuration/interfaces/bridge.md @@ -0,0 +1,431 @@ +--- +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/dummy.md b/docs/configuration/interfaces/dummy.md new file mode 100644 index 00000000..d2d27c5d --- /dev/null +++ b/docs/configuration/interfaces/dummy.md @@ -0,0 +1,87 @@ +--- +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/ethernet.md b/docs/configuration/interfaces/ethernet.md new file mode 100644 index 00000000..eac0b443 --- /dev/null +++ b/docs/configuration/interfaces/ethernet.md @@ -0,0 +1,515 @@ +--- +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/geneve.md b/docs/configuration/interfaces/geneve.md new file mode 100644 index 00000000..1fce1119 --- /dev/null +++ b/docs/configuration/interfaces/geneve.md @@ -0,0 +1,105 @@ +--- +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/index.md b/docs/configuration/interfaces/index.md new file mode 100644 index 00000000..9082cd80 --- /dev/null +++ b/docs/configuration/interfaces/index.md @@ -0,0 +1,26 @@ +# 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/l2tpv3.md b/docs/configuration/interfaces/l2tpv3.md new file mode 100644 index 00000000..324840fa --- /dev/null +++ b/docs/configuration/interfaces/l2tpv3.md @@ -0,0 +1,170 @@ +--- +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/loopback.md b/docs/configuration/interfaces/loopback.md new file mode 100644 index 00000000..72f14c16 --- /dev/null +++ b/docs/configuration/interfaces/loopback.md @@ -0,0 +1,67 @@ +--- +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/macsec.md b/docs/configuration/interfaces/macsec.md new file mode 100644 index 00000000..b3c70362 --- /dev/null +++ b/docs/configuration/interfaces/macsec.md @@ -0,0 +1,319 @@ +--- +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/openvpn-examples.md b/docs/configuration/interfaces/openvpn-examples.md new file mode 100644 index 00000000..817e6868 --- /dev/null +++ b/docs/configuration/interfaces/openvpn-examples.md @@ -0,0 +1,769 @@ +# 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/openvpn.md b/docs/configuration/interfaces/openvpn.md new file mode 100644 index 00000000..170c585d --- /dev/null +++ b/docs/configuration/interfaces/openvpn.md @@ -0,0 +1,614 @@ +(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/pppoe.md b/docs/configuration/interfaces/pppoe.md new file mode 100644 index 00000000..b79f41a2 --- /dev/null +++ b/docs/configuration/interfaces/pppoe.md @@ -0,0 +1,419 @@ +--- +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/pseudo-ethernet.md b/docs/configuration/interfaces/pseudo-ethernet.md new file mode 100644 index 00000000..fc8833eb --- /dev/null +++ b/docs/configuration/interfaces/pseudo-ethernet.md @@ -0,0 +1,52 @@ +--- +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/sstp-client.md b/docs/configuration/interfaces/sstp-client.md new file mode 100644 index 00000000..da98aecd --- /dev/null +++ b/docs/configuration/interfaces/sstp-client.md @@ -0,0 +1,170 @@ +--- +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/tunnel.md b/docs/configuration/interfaces/tunnel.md new file mode 100644 index 00000000..9c9885d2 --- /dev/null +++ b/docs/configuration/interfaces/tunnel.md @@ -0,0 +1,309 @@ +--- +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/virtual-ethernet.md b/docs/configuration/interfaces/virtual-ethernet.md new file mode 100644 index 00000000..dee1b332 --- /dev/null +++ b/docs/configuration/interfaces/virtual-ethernet.md @@ -0,0 +1,119 @@ +--- +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/vti.md b/docs/configuration/interfaces/vti.md new file mode 100644 index 00000000..dbd2c88c --- /dev/null +++ b/docs/configuration/interfaces/vti.md @@ -0,0 +1,121 @@ +(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/vxlan.md b/docs/configuration/interfaces/vxlan.md new file mode 100644 index 00000000..8dae75ff --- /dev/null +++ b/docs/configuration/interfaces/vxlan.md @@ -0,0 +1,373 @@ +--- +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/wireguard.md b/docs/configuration/interfaces/wireguard.md new file mode 100644 index 00000000..121d1df0 --- /dev/null +++ b/docs/configuration/interfaces/wireguard.md @@ -0,0 +1,434 @@ +--- +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/wireless.md b/docs/configuration/interfaces/wireless.md new file mode 100644 index 00000000..9e6b7c99 --- /dev/null +++ b/docs/configuration/interfaces/wireless.md @@ -0,0 +1,923 @@ +--- +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/wwan.md b/docs/configuration/interfaces/wwan.md new file mode 100644 index 00000000..e8121f28 --- /dev/null +++ b/docs/configuration/interfaces/wwan.md @@ -0,0 +1,355 @@ +--- +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