diff options
Diffstat (limited to 'docs/configuration/interfaces')
21 files changed, 0 insertions, 7091 deletions
diff --git a/docs/configuration/interfaces/rst-bonding.rst b/docs/configuration/interfaces/rst-bonding.rst deleted file mode 100644 index 7637790c..00000000 --- a/docs/configuration/interfaces/rst-bonding.rst +++ /dev/null @@ -1,767 +0,0 @@ -:lastproofread: 2025-12-09 - -.. _bond-interface: - -####################### -Bond / link aggregation -####################### - -A **bonding interface** aggregates multiple network interfaces into a single -logical interface (referred to as a bond, :abbr:`LAG (Link Aggregation Group)`, -EtherChannel, or port-channel). - -The behavior of a bonding interface depends on the selected mode. Modes provide -either fault tolerance or a combination of load balancing and fault tolerance. -Additionally, the bonding interface can be configured for link integrity -monitoring. - - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: bonding - :var1: bond0 - -Member interfaces -================= - -.. cfgcmd:: set interfaces bonding <interface> member interface <member> - - **Add an interface to the bonding group.** - - **Example:** - - To configure eth0 and eth1 as members of the bonding interface bond0, execute - the following commands: - -.. code-block:: none - - set interfaces bonding bond0 member interface eth0 - set interfaces bonding bond0 member interface eth1 - -Bond modes -============ - -.. cfgcmd:: set interfaces bonding <interface> mode <802.3ad | active-backup | - broadcast | round-robin | transmit-load-balance | adaptive-load-balance | - xor-hash> - - **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 <interface> 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 <interface> lacp-rate <slow|fast> - - **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 <interface> system-mac <mac address> - - **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 <interface> hash-policy <policy> - - **Configure which transmit hash policy to use for distributing - traffic across member interfaces.** - - The following policies are available: - - * ``layer2`` - - .. list-table:: - :widths: 20 80 - - * - **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`` - - .. list-table:: - :widths: 20 80 - - * - **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`` - - .. list-table:: - :widths: 20 80 - - * - **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 <interface> primary <interface> - - **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 <interface> arp-monitor interval <time> - - **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 <interface> arp-monitor target <address> - - **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)` -========================================= - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: bonding - :var1: bond0 - -SPAN port mirroring -=================== - -.. cmdinclude:: ../../_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: - -.. stop_vyoslinter - -.. cfgcmd:: set interfaces bonding <interface> evpn es-id <1-16777215|10-byte ID> -.. cfgcmd:: set interfaces bonding <interface> evpn es-sys-mac <xx:xx:xx:xx:xx:xx> - - 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. - -.. stop_vyoslinter - -.. cfgcmd:: set interfaces bonding <interface> 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. - -.. start_vyoslinter - -.. cmdinclude:: /_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. - -.. code-block:: 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: - :opcmd:`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: - -.. code-block:: none - - interface GigabitEthernet1/0/23 - description VyOS eth1 - channel-group 1 mode active - ! - interface GigabitEthernet1/0/24 - description VyOS eth2 - channel-group 1 mode active - ! - -A new interface, ``Port-channel1``, becomes available; all configuration, -such as allowed VLAN interfaces and STP, is applied here. - -.. code-block:: none - - interface Port-channel1 - description LACP Channel for VyOS - switchport trunk encapsulation dot1q - switchport trunk allowed vlan 10,100 - switchport mode trunk - spanning-tree portfast trunk - ! - - -Juniper EX Switch configuration -=============================== - -Configure a Juniper EX Series switch to integrate with a two-member VyOS -bonding interface. - -.. code-block:: none - - # Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s - set interfaces ae0 aggregated-ether-options link-speed 10g - set interfaces ae0 aggregated-ether-options lacp active - - # Create layer 2 on the aggregated ethernet device with trunking for our VLANs - set interfaces ae0 unit 0 family ethernet-switching port-mode trunk - - # Add the required vlans to the device - set interfaces ae0 unit 0 family ethernet-switching vlan members 10 - set interfaces ae0 unit 0 family ethernet-switching vlan members 100 - - # Add the two interfaces to the aggregated ethernet device, in this setup both - # ports are on the same switch (switch 0, module 1, port 0 and 1) - set interfaces xe-0/1/0 ether-options 802.3ad ae0 - set interfaces xe-0/1/1 ether-options 802.3ad ae0 - - # But this can also be done with multiple switches in a stack, a virtual - # chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) - set interfaces xe-0/1/0 ether-options 802.3ad ae0 - set interfaces xe-1/1/0 ether-options 802.3ad ae0 - -Aruba/HP configuration -====================== - -Configure an Aruba/HP 2510G switch to integrate with a two-member VyOS bonding -interface. - -.. code-block:: none - - # Create trunk with 2 member interfaces (interface 1 and 2) and LACP - trunk 1-2 Trk1 LACP - - # Add the required VLANs to the trunk - vlan 10 tagged Trk1 - vlan 100 tagged Trk1 - -Arista EOS 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: - -.. figure:: /_static/images/vyos_arista_bond_lacp.* - :alt: VyOS Arista EOS setup - -**R1** - - .. code-block:: none - - interfaces { - bonding bond10 { - hash-policy layer3+4 - member { - interface eth1 - interface eth2 - } - mode 802.3ad - vif 100 { - address 192.0.2.1/30 - address 2001:db8::1/64 - } - } - -**R2** - - .. code-block:: none - - interfaces { - bonding bond10 { - hash-policy layer3+4 - member { - interface eth1 - interface eth2 - } - mode 802.3ad - vif 100 { - address 192.0.2.2/30 - address 2001:db8::2/64 - } - } - -**SW1** - - .. code-block:: none - - ! - vlan 100 - name FOO - ! - interface Port-Channel10 - switchport trunk allowed vlan 100 - switchport mode trunk - spanning-tree portfast - ! - interface Port-Channel20 - switchport mode trunk - no spanning-tree portfast auto - spanning-tree portfast network - ! - interface Ethernet1 - channel-group 10 mode active - ! - interface Ethernet2 - channel-group 10 mode active - ! - interface Ethernet3 - channel-group 20 mode active - ! - interface Ethernet4 - channel-group 20 mode active - ! - -**SW2** - - .. code-block:: none - - ! - vlan 100 - name FOO - ! - interface Port-Channel10 - switchport trunk allowed vlan 100 - switchport mode trunk - spanning-tree portfast - ! - interface Port-Channel20 - switchport mode trunk - no spanning-tree portfast auto - spanning-tree portfast network - ! - interface Ethernet1 - channel-group 10 mode active - ! - interface Ethernet2 - channel-group 10 mode active - ! - interface Ethernet3 - channel-group 20 mode active - ! - interface Ethernet4 - channel-group 20 mode active - ! - -.. note:: When 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 -********* - -.. opcmd:: show interfaces bonding - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces bonding - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - bond0 - u/u my-sw1 int 23 and 24 - bond0.10 192.168.0.1/24 u/u office-net - bond0.100 10.10.10.1/24 u/u management-net - - -.. opcmd:: show interfaces bonding <interface> - - Show detailed interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces bonding bond5 - bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000 - link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff - inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 0 0 0 0 0 0 - -.. opcmd:: show interfaces bonding <interface> detail - - Show detailed information about the 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 diff --git a/docs/configuration/interfaces/rst-bridge.rst b/docs/configuration/interfaces/rst-bridge.rst deleted file mode 100644 index a1710804..00000000 --- a/docs/configuration/interfaces/rst-bridge.rst +++ /dev/null @@ -1,424 +0,0 @@ -:lastproofread: 2025-12-22 - -.. _bridge-interface: - -###### -Bridge -###### - -VyOS bridges connect Ethernet segments by grouping multiple interfaces into a -single bridge interface, which acts as a virtual software switch. Unlike -routers, which forward traffic based on Layer 3 IP addresses, bridges operate -at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2, -bridges are protocol-agnostic and transparently forward all Ethernet- -encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial -protocols. - -This implementation utilizes the Linux bridge subsystem to support a subset of -the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning. - -.. note:: :abbr:`STP (Spanning Tree Protocol)` is disabled by default in VyOS - and must be explicitly enabled if required. See :ref:`stp` for details. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: bridge - :var1: br0 - -Member interfaces -================= - -.. cfgcmd:: set interfaces bridge <interface> member interface <member> - - **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 <interface> member interface <member> - priority <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 <interface> member interface <member> - cost <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 <interface> member interface <member> - 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 <interface> aging <time> - - **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 <interface> max-age <time> - - **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 <interface> 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 <interface> 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 <interface> stp - - Enable :abbr:`STP (Spanning Tree Protocol)` on the bridge interface. - -.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <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 <interface> hello-time <interval> - - **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 <interface> 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 <interface> 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 ------------------- - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: bridge - :var1: br0 - -.. cfgcmd:: set interfaces bridge <interface> member interface <member> - native-vlan <vlan-id> - - **Configure the native VLAN ID for a specific member interface within a - VLAN-aware bridge.** - - This assigns the specified ``<vlan-id>`` 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 <interface> member interface <member> - allowed-vlan <vlan-id> - - **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 -=================== -.. cmdinclude:: ../../_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). - -.. code-block:: none - - set interfaces bridge br100 address 192.0.2.1/24 - set interfaces bridge br100 address 2001:db8::ffff/64 - set interfaces bridge br100 member interface eth1 - set interfaces bridge br100 member interface eth2.10 - set interfaces bridge br100 stp - -Verify the configuration: - -.. code-block:: none - - vyos@vyos# show interfaces bridge br100 - address 192.0.2.1/24 - address 2001:db8::ffff/64 - member { - interface eth1 { - } - interface eth2.10 { - } - } - stp - - -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). - -.. code-block:: none - - set interfaces bridge br100 enable-vlan - set interfaces bridge br100 member interface eth1 allowed-vlan 10 - set interfaces bridge br100 member interface eth2 native-vlan 10 - set interfaces bridge br100 vif 10 address 192.0.2.1/24 - set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 - set interfaces bridge br100 stp - -Verify the configuration: - -.. code-block:: none - - vyos@vyos# show interfaces bridge br100 - enable-vlan - member { - interface eth1 { - allowed-vlan 10 - } - interface eth2 { - native-vlan 10 - } - } - stp - vif 10 { - address 192.0.2.1/24 - address 2001:db8::ffff/64 - } - - -Operation -========= - -.. opcmd:: show bridge - - Show the status of member interfaces for all configured bridges. - - .. code-block:: none - - vyos@vyos:~$ show bridge - 3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding - priority 32 cost 100 - 4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding - priority 32 cost 100 - -.. opcmd:: show bridge <name> fdb - - Show 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 <name> 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 <name> 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 diff --git a/docs/configuration/interfaces/rst-dummy.rst b/docs/configuration/interfaces/rst-dummy.rst deleted file mode 100644 index 55c134e3..00000000 --- a/docs/configuration/interfaces/rst-dummy.rst +++ /dev/null @@ -1,87 +0,0 @@ -:lastproofread: 2026-01-23 - -.. _dummy-interface: - -##### -Dummy -##### - -A dummy interface is a virtual network interface that operates like the -loopback interface, accepting traffic and routing it back to the local host. -Unlike the loopback interface, which is limited to one per system and reserved -for internal system use, multiple dummy interfaces can be created, removed, and -managed without impacting core operations. - -As a software-based interface, the dummy interface does not depend on physical -link state and remains active as long as the operating system is running. - -Dummy interfaces are commonly used in environments with multiple redundant -uplinks (e.g., a server connected to two different switches), where assigning a -management IP address to a specific physical interface is risky. If that -interface fails, the management IP address becomes unreachable. - -Assigning the management IP address to a dummy interface and advertising it -over all available physical links ensures the address remains reachable as long -as at least one physical path is active. - -Dummy interfaces are also used for testing and simulation purposes. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address.txt - :var0: dummy - :var1: dum0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: dummy - :var1: dum0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: dummy - :var1: dum0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: dummy - :var1: dum0 - -********* -Operation -********* - -.. opcmd:: show interfaces dummy - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces dummy - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - dum0 172.18.254.201/32 u/u - -.. opcmd:: show interfaces dummy <interface> - - Show detailed interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces dummy dum0 - dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 - link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff - inet 172.18.254.201/32 scope global dum0 - valid_lft forever preferred_lft forever - inet6 fe80::247c:8eff:febc:fcf5/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 1369707 4267 0 0 0 0 - - diff --git a/docs/configuration/interfaces/rst-ethernet.rst b/docs/configuration/interfaces/rst-ethernet.rst deleted file mode 100644 index e6c385e7..00000000 --- a/docs/configuration/interfaces/rst-ethernet.rst +++ /dev/null @@ -1,468 +0,0 @@ -:lastproofread: 2026-01-19 - -.. _ethernet-interface: - -######## -Ethernet -######## - -Ethernet interfaces (e.g., ``eth0``, ``eth1``) represent the host's physical -or virtual network ports. - -They are the most common interface type, serving as the base layer upon which -IP addresses, VLANs, and tunnels are configured to carry traffic across both -LANs and WANs. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: ethernet - :var1: eth0 - -.. cfgcmd:: set interfaces ethernet <interface> 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 <interface> duplex <auto | full | half> - - **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 <interface> speed <auto | 10 | 100 | 1000 | - 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000> - - **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 <interface> ring-buffer rx <value> - - **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: - -.. code-block:: none - - ethtool -g <interface> - -.. cfgcmd:: set interfaces ethernet <interface> ring-buffer tx <value> - - **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: - -.. code-block:: none - - ethtool -g <interface> - -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 <interface>`` - to verify which settings are supported by your hardware and driver. - -**Basic adaptive coalescing** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing adaptive-rx -.. cfgcmd:: set interfaces ethernet <interface> 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 <interface> interrupt-coalescing rx-usecs <0-16384> -.. cfgcmd:: set interfaces ethernet <interface> 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 <interface> interrupt-coalescing rx-frames <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-frames <number> - - Generate an RX/TX interrupt only after the specified number of packets - have been received or transmitted. - -**IRQ-specific coalescing** - -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-usecs-irq <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-frames-irq <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-usecs-irq <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-frames-irq <number> - - 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 <interface> interrupt-coalescing pkt-rate-low <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing pkt-rate-high <number> - - 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 <interface> interrupt-coalescing rx-usecs-low <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-frame-low <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-usecs-low <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-frame-low <number> - - 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 <interface> interrupt-coalescing rx-usecs-high <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing rx-frame-high <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-usecs-high <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-frame-high <number> - - 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 <interface> interrupt-coalescing stats-block-usecs <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing sample-interval <number> - - 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 <interface> interrupt-coalescing cqe-mode-rx -.. cfgcmd:: set interfaces ethernet <interface> 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 <interface> interrupt-coalescing tx-aggr-max-bytes <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-aggr-max-frames <number> -.. cfgcmd:: set interfaces ethernet <interface> interrupt-coalescing tx-aggr-time-usecs <number> - - 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 <interface> offload <lro | tso | gso | - gro | rps | sg > - - **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 ------------------------------ - -.. cmdinclude:: /_include/interface-eapol.txt - :var0: ethernet - :var1: eth0 - -EVPN Multihoming ----------------- - -Uplink/core tracking. - -.. cmdinclude:: /_include/interface-evpn-uplink.txt - :var0: ethernet - :var1: eth0 - -VLAN -==== - -Regular VLANs (802.1q) ----------------------- - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: ethernet - :var1: eth0 - -802.1ad (QinQ) --------------- - -.. cmdinclude:: /_include/interface-vlan-8021ad.txt - :var0: ethernet - :var1: eth0 - -SPAN port mirroring -=================== -.. cmdinclude:: ../../_include/interface-mirror.txt - :var0: ethernet - :var1: eth1 - :var2: eth3 - -********* -Operation -********* - -.. opcmd:: show interfaces ethernet - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces ethernet - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 172.18.201.10/24 u/u LAN - eth1 172.18.202.11/24 u/u WAN - eth2 - u/D - -.. opcmd:: show interfaces ethernet <interface> - - Show detailed interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 - eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 - link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff - inet6 fe80::250:44ff:fe00:f5c9/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 56735451 179841 0 0 0 142380 - TX: bytes packets errors dropped carrier collisions - 5601460 62595 0 0 0 0 - -.. stop_vyoslinter - -.. opcmd:: show interfaces ethernet <interface> physical - - Show 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 - -.. start_vyoslinter - -.. opcmd:: show interfaces ethernet <interface> 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 <interface> 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 diff --git a/docs/configuration/interfaces/rst-geneve.rst b/docs/configuration/interfaces/rst-geneve.rst deleted file mode 100644 index bcd6c591..00000000 --- a/docs/configuration/interfaces/rst-geneve.rst +++ /dev/null @@ -1,100 +0,0 @@ -:lastproofread: 2026-02-02 - -.. _geneve-interface: - -###### -Geneve -###### - -:abbr:`Geneve (Generic Network Virtualization Encapsulation)` interfaces -operate as virtual network ports. Administrators can apply standard network -configurations on them, such as IP addressing, bridging, or firewall rules, -just as they would on physical Ethernet ports. - -The Geneve protocol encapsulates Layer 2 Ethernet frames originating from -endpoints such as virtual machines, containers, or physical servers inside UDP -packets. It unifies the features of earlier encapsulation protocols, including -VXLAN, NVGRE, and STT, and addresses their limitations, such as fixed header -structures and a lack of metadata support. Because of its extensibility, Geneve -may eventually replace those older protocols. - -Geneve tunnels are used to connect virtual switches residing within -hypervisors, physical switches, middleboxes, and other network appliances. - -Geneve tunnels operate over any standard IP network. In larger deployments, -the underlying network (underlay) is often built using a **Clos** topology, -also known as a *leaf-and-spine* or *fat-tree* topology. - -Geneve header: - -.. code-block:: none - - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |Ver| Opt Len |O|C| Rsvd. | Protocol Type | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Virtual Network Identifier (VNI) | Reserved | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Variable Length Options | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-mac.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-ip.txt - :var0: geneve - :var1: gnv0 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: geneve - :var1: gnv0 - -Geneve options -============== - -.. cfgcmd:: set interfaces geneve gnv0 remote <address> - - Configure the remote endpoint IP address for the Geneve tunnel. - -.. cfgcmd:: set interfaces geneve gnv0 vni <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 <interface> port <port> - - **Configure the destination UDP port for the remote Geneve tunnel endpoint.** - - Ensure the remote peer is configured to listen on this specific port. - - diff --git a/docs/configuration/interfaces/rst-index.rst b/docs/configuration/interfaces/rst-index.rst deleted file mode 100644 index 46d521b0..00000000 --- a/docs/configuration/interfaces/rst-index.rst +++ /dev/null @@ -1,28 +0,0 @@ -########## -Interfaces -########## - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - bonding - bridge - dummy - ethernet - geneve - l2tpv3 - loopback - macsec - openvpn - wireguard - pppoe - pseudo-ethernet - sstp-client - tunnel - virtual-ethernet - vti - vxlan - wireless - wwan diff --git a/docs/configuration/interfaces/rst-l2tpv3.rst b/docs/configuration/interfaces/rst-l2tpv3.rst deleted file mode 100644 index 692dff93..00000000 --- a/docs/configuration/interfaces/rst-l2tpv3.rst +++ /dev/null @@ -1,167 +0,0 @@ -:lastproofread: 2026-02-05 - -.. _l2tpv3-interface: - -###### -L2TPv3 -###### - -:abbr:`L2TPv3 (Layer 2 Tunneling Protocol version 3)` interfaces let you -establish L2TPv3 tunnels to transport Layer 2 traffic over IP networks. - -The L2TPv3 protocol (defined in RFC 3931) wraps Layer 2 frames (e.g., Ethernet, -Frame Relay, HDLC) within IP packets, allowing them to traverse the underlying -IP infrastructure. - -Unlike L2TPv2, which strictly requires UDP encapsulation, the L2TPv3 protocol -is more flexible and supports two encapsulation types: - - * **Direct IP:** Tunnel data is encapsulated directly inside IP packets - (Protocol 115) for lower overhead. - * **UDP:** Tunnel data is encapsulated inside a UDP datagram. This allows the - tunnel to traverse NAT more easily. - -L2TPv3 tunnels connect geographically separated sites, serving as a simpler -alternative to :ref:`mpls` by operating over basic IP connectivity rather than -requiring a full MPLS infrastructure. - -L2TPv3 tunnels can be established over both IPv4 and IPv6 underlying networks. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_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 <interface> encapsulation <udp | ip> - - **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 <interface> source-address <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 <interface> remote <address> - - **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 <interface> session-id <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 <interface> peer-session-id <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 <interface> tunnel-id <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 <interface> peer-tunnel-id <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: - -.. code-block:: none - - # show interfaces l2tpv3 - l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - encapsulation ip - source-address 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote 203.0.113.24 - session-id 100 - tunnel-id 200 - } - -The inverse configuration 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. - -.. code-block:: none - - # show interfaces l2tpv3 - l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - destination-port 9001 - encapsulation udp - source-address 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote 203.0.113.24 - session-id 100 - source-port 9000 - tunnel-id 200 - } diff --git a/docs/configuration/interfaces/rst-loopback.rst b/docs/configuration/interfaces/rst-loopback.rst deleted file mode 100644 index 68158111..00000000 --- a/docs/configuration/interfaces/rst-loopback.rst +++ /dev/null @@ -1,65 +0,0 @@ -:lastproofread: 2026-01-23 - -.. _loopback-interface: - -######## -Loopback -######## - -The loopback interface is a virtual, software-based network interface. All -traffic sent to it loops back and only targets services on the local host. - -.. note:: Only one loopback ``lo`` interface is allowed per operating system. - If you require multiple virtual interfaces, use the :ref:`dummy-interface` - interface type. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address.txt - :var0: loopback - :var1: lo - -.. cmdinclude:: /_include/interface-description.txt - :var0: loopback - :var1: lo - -********* -Operation -********* - -.. opcmd:: show interfaces loopback - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces loopback - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - lo 127.0.0.1/8 u/u - ::1/128 - -.. opcmd:: show interfaces loopback lo - - Show detailed interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces loopback lo - lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 - link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 - inet 127.0.0.1/8 scope host lo - valid_lft forever preferred_lft forever - inet6 ::1/128 scope host - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 300 6 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 300 6 0 0 0 0 diff --git a/docs/configuration/interfaces/rst-macsec.rst b/docs/configuration/interfaces/rst-macsec.rst deleted file mode 100644 index 2a893943..00000000 --- a/docs/configuration/interfaces/rst-macsec.rst +++ /dev/null @@ -1,322 +0,0 @@ -:lastproofread: 2026-02-13 - -.. _macsec-interface: - -###### -MACsec -###### - -MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in -2006. It enables protocol-independent connectivity between two hosts, providing -data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec -operates at the Ethernet layer as a Layer 2 protocol and secures traffic within -Layer 2 networks, including DHCP and ARP requests. It does not compete with -other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each -addresses distinct use cases. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: macsec - :var1: macsec0 - -MACsec options -============== - -.. cfgcmd:: set interfaces macsec <interface> security cipher <gcm-aes-128|gcm-aes-256> - - **Configure the cipher suite for the MACsec interface.** - - This configuration parameter is mandatory. - -.. cfgcmd:: set interfaces macsec <interface> 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 <interface> source-interface <physical-source> - - **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 <interface> security static key <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 <interface> security static peer <peer> mac <mac address> - - **Configure the MAC address associated with the MACsec peer.** - -.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> key <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 <interface> security static peer <peer> disable - - Disable the specific MACsec peer. - - -**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 <interface> security mka cak <key> - - **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 <interface> security mka ckn <key> - - Configure the :abbr:`CKN (MACsec Connectivity Association Key Name)` for the - MACsec interface. - -.. cfgcmd:: set interfaces macsec <interface> security mka priority <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 <interface> security replay-window <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 <gcm-aes-128|gcm-aes-256> - - 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 <interface> - - 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** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.1/24' - set interfaces macsec macsec1 address '2001:db8::1/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' - set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' - set interfaces macsec macsec1 source-interface 'eth1' - -**R2** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.2/24' - set interfaces macsec macsec1 address '2001:db8::2/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' - set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' - set interfaces macsec macsec1 source-interface 'eth1' - -Pinging (IPv6) the other host and intercepting traffic on ``eth1`` confirm that -the content is encrypted. - -.. code-block:: none - - 17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: - 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... - 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df - 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. - 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... - 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. - 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; - 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i - 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... - 0x0080: 6b30 92a5 7ccc 720b k0..|.r. - -Disabling encryption on the MACsec interface by removing the ``security -encrypt`` option shows the unencrypted but authenticated content. - -.. code-block:: none - - 17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: - 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... - 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ - 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ - 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. - 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ - 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ - 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ - 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ - 0x0080: a282 c842 5254 ef28 ...BRT.( - -**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** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.1/24' - set interfaces macsec macsec1 address '2001:db8::1/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02 - set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 source-interface 'eth1' - -**R2** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.2/24' - set interfaces macsec macsec1 address '2001:db8::2/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 security static peer 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** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.1/24' - set interfaces macsec macsec1 address '2001:db8::1/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02' - set interfaces macsec macsec1 source-interface 'vxlan1' - set interfaces vxlan vxlan1 mac '00:11:22:33:44:01' - set interfaces vxlan vxlan1 remote '10.1.3.3' - set interfaces vxlan vxlan1 source-address '172.16.100.1' - set interfaces vxlan vxlan1 vni '10' - set protocols static route 10.1.3.3/32 next-hop 172.16.100.2 - -**R2 MACsec02** - -.. code-block:: none - - set interfaces macsec macsec1 address '192.0.2.2/24' - set interfaces macsec macsec1 address '2001:db8::2/64' - set interfaces macsec macsec1 security cipher 'gcm-aes-128' - set interfaces macsec macsec1 security encrypt - set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' - set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' - set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01' - set interfaces macsec macsec1 source-interface 'vxlan1' - set interfaces vxlan vxlan1 mac '00:11:22:33:44:02' - set interfaces vxlan vxlan1 remote '10.1.2.2' - set interfaces vxlan vxlan1 source-address '172.16.100.2' - set interfaces vxlan vxlan1 vni '10' - set protocols static route 10.1.2.2/32 next-hop 172.16.100.1 diff --git a/docs/configuration/interfaces/rst-openvpn-examples.rst b/docs/configuration/interfaces/rst-openvpn-examples.rst deleted file mode 100644 index 6e746e46..00000000 --- a/docs/configuration/interfaces/rst-openvpn-examples.rst +++ /dev/null @@ -1,929 +0,0 @@ - -############ -Site-to-site -############ - -.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd - directives for command coverage tracking. - -OpenVPN is popular for client-server setups, but its site-to-site mode is less -common and often not supported by router appliances. Despite limited support, -it is effective for quickly establishing tunnels between routers. - -As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or -x.509 certificates. - -Pre-shared key mode is now deprecated and will be removed from future OpenVPN -versions. VyOS will also discontinue support for this option because pre-shared -keys are significantly less secure than TLS. - -We will configure OpenVPN with self-signed certificates, and then discuss the -legacy pre-shared key mode. - -In both cases, we will use the following settings: - -* The public IP address of the local VPN endpoint is 198.51.100.10. -* The public IP address of the remote VPN endpoint is 203.0.113.11. -* The tunnel uses 10.255.1.1 for the local IP address and 10.255.1.2 for the - remote IP address. -* The local site has a subnet of 10.0.0.0/16. -* The remote site has a subnet of 10.1.0.0/16. -* The official OpenVPN port 1194 is reserved for client VPN. For site-to-site - VPN, port 1195 is used. -* The ``persistent-tunnel`` directive allows us to configure tunnel-related - attributes, such as firewall policy, as we would on any standard network - interface. -* If known, the remote router's IP address can be configured using the - ``remote-host`` directive. If unknown, it can be omitted. We assume - the remote router has a dynamic IP address. - - -.. figure:: /_static/images/openvpn_site2site_diagram.* - -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 <name>``. This adds the -certificate to the configuration session's ``pki`` subtree. Review and commit -the changes. - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos# run generate pki certificate self-signed install openvpn-local - Enter private key type: [rsa, dsa, ec] (Default: rsa) ec - Enter private key bits: (Default: 256) - Enter country code: (Default: GB) - Enter state: (Default: Some-State) - Enter locality: (Default: Some-City) - Enter organization name: (Default: VyOS) - Enter common name: (Default: vyos.io) - Do you want to configure Subject Alternative Names? [y/N] - Enter how many days certificate will be valid: (Default: 365) - Enter certificate type: (client, server) (Default: server) - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - - vyos@vyos# compare - [pki] - + certificate openvpn-local { - + certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" - + private { - + key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" - + } - + } - - [edit] - - vyos@vyos# commit - -.. start_vyoslinter - -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: - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 - 5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 - -.. start_vyoslinter - -.. 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: - -.. stop_vyoslinter - -.. code-block:: none - - Configure the tunnel: - - set interfaces openvpn vtun1 mode site-to-site - set interfaces openvpn vtun1 protocol udp - set interfaces openvpn vtun1 persistent-tunnel - set interfaces openvpn vtun1 remote-host '203.0.113.11' # Public IP of the other side - set interfaces openvpn vtun1 local-port '1195' - set interfaces openvpn vtun1 remote-port '1195' - set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface - set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface - set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate - set interfaces openvpn vtun1 tls peer-fingerprint <remote cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256' on the remote router - set interfaces openvpn vtun1 tls role active - -Remote configuration: - -.. code-block:: none - - set interfaces openvpn vtun1 mode site-to-site - set interfaces openvpn vtun1 protocol udp - set interfaces openvpn vtun1 persistent-tunnel - set interfaces openvpn vtun1 remote-host '198.51.100.10' # Pub IP of other site - set interfaces openvpn vtun1 local-port '1195' - set interfaces openvpn vtun1 remote-port '1195' - set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface - set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface - set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate - set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 on the local router - set interfaces openvpn vtun1 tls role passive - -.. start_vyoslinter - -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 <name>`` in configuration mode. You can use any name; in this example, -we use ``s2s``. - -.. stop_vyoslinter - -.. code-block:: none - - vyos@local# run generate pki openvpn shared-secret install s2s - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - vyos@local# compare - [pki openvpn shared-secret] - + s2s { - + key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" - + version "1" - + } - - [edit] - - vyos@local# commit - [edit] - -.. start_vyoslinter - -Next, install the key on the remote router: - -.. code-block:: none - - vyos@remote# set pki openvpn shared-secret s2s key <generated key string> - -Finally, configure the key in your OpenVPN interface settings: - -.. code-block:: 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: - -.. stop_vyoslinter - -.. code-block:: none - - set firewall ipv4 name OUTSIDE_LOCAL rule 10 action 'accept' - set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' - set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'established' - 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' - -.. start_vyoslinter - -Apply the OUTSIDE_LOCAL firewall group to the WAN interface and to the input -filter for traffic destined for the router itself: - -.. code-block:: 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: - -.. code-block:: none - - set protocols static route 10.1.0.0/16 interface vtun1 - -Remote configuration: - -.. code-block:: none - - set protocols static route 10.0.0.0/16 interface vtun1 - -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. - -.. stop_vyoslinter - -.. code-block:: 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 - -.. start_vyoslinter - -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): - -.. stop_vyoslinter - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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==' - -.. start_vyoslinter - -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: - -.. code-block:: 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. - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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: - -.. stop_vyoslinter - -.. code-block:: 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 - -.. start_vyoslinter - -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: - -.. code-block:: none - - set interfaces bridge br10 member interface eth1.10 - set interfaces bridge br10 member interface vtun10 - set interfaces openvpn vtun10 device-type 'tap' - set interfaces openvpn vtun10 encryption data-ciphers 'aes192' - set interfaces openvpn vtun10 hash 'sha256' - set interfaces openvpn vtun10 local-host '172.18.201.10' - set interfaces openvpn vtun10 local-port '1194' - set interfaces openvpn vtun10 mode 'server' - set interfaces openvpn vtun10 server bridge gateway '10.10.0.1' - set interfaces openvpn vtun10 server bridge start '10.10.0.100' - set interfaces openvpn vtun10 server bridge stop '10.10.0.200' - set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' - set interfaces openvpn vtun10 server topology 'subnet' - set interfaces openvpn vtun10 tls ca-certificate 'ca-1' - set interfaces openvpn vtun10 tls certificate 'srv-1' - set interfaces openvpn vtun10 tls dh-params 'dh-1' - -Client side: - -.. code-block:: none - - set interfaces openvpn vtun10 device-type 'tap' - set interfaces openvpn vtun10 encryption data-ciphers 'aes192' - set interfaces openvpn vtun10 hash 'sha256' - set interfaces openvpn vtun10 mode 'client' - set interfaces openvpn vtun10 protocol 'udp' - set interfaces openvpn vtun10 remote-host '172.18.201.10' - set interfaces openvpn vtun10 remote-port '1194' - set interfaces openvpn vtun10 tls ca-certificate 'ca-1' - set interfaces openvpn vtun10 tls certificate 'client-1' - - - -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. - -.. stop_vyoslinter - -.. code-block:: none - - set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" - -.. start_vyoslinter - -A sample configuration file is shown below: - -.. code-block:: none - - <LDAP> - # LDAP server URL - URL ldap://ldap.example.com - # Bind DN (If your LDAP server doesn't support anonymous binds) - BindDN cn=LDAPUser,dc=example,dc=com - # Bind Password password - Password S3cr3t - # Network timeout (in seconds) - Timeout 15 - </LDAP> - - <Authorization> - # Base DN - BaseDN "ou=people,dc=example,dc=com" - # User Search Filter - SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" - # Require Group Membership - allow all users - RequireGroup false - </Authorization> - -Active Directory -^^^^^^^^^^^^^^^^ - -A sample configuration file is shown below: - -.. stop_vyoslinter - -.. code-block:: none - - <LDAP> - # LDAP server URL - URL ldap://dc01.example.com - # Bind DN (If your LDAP server doesn’t support anonymous binds) - BindDN CN=LDAPUser,DC=example,DC=com - # Bind Password - Password mysecretpassword - # Network timeout (in seconds) - Timeout 15 - # Enable Start TLS - TLSEnable no - # Follow LDAP Referrals (anonymously) - FollowReferrals no - </LDAP> - - <Authorization> - # Base DN - BaseDN "DC=example,DC=com" - # User Search Filter, user must be a member of the VPN AD group - SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" - # Require Group Membership - RequireGroup false # already handled by SearchFilter - <Group> - BaseDN "OU=Groups,DC=example,DC=com" - SearchFilter "(|(cn=VPN))" - MemberAttribute memberOf - </Group> - </Authorization> - -.. start_vyoslinter - -If you only want to check that the user account is enabled and can -authenticate (against the primary group), the following snippet is -sufficient: - -.. code-block:: none - - <LDAP> - URL ldap://dc01.example.com - BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com - Password ThisIsTopSecret - Timeout 15 - TLSEnable no - FollowReferrals no - </LDAP> - - <Authorization> - BaseDN "DC=example,DC=com" - SearchFilter "sAMAccountName=%u" - RequireGroup false - </Authorization> - -A complete example of an LDAP authentication configuration for OpenVPN -is shown below: - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos# show interfaces openvpn - openvpn vtun0 { - mode server - openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" - openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" - openvpn-option "--push redirect-gateway" - openvpn-option --duplicate-cn - openvpn-option "--verify-client-cert none" - openvpn-option --comp-lzo - openvpn-option --persist-key - openvpn-option --persist-tun - server { - domain-name example.com - max-connections 5 - name-server 203.0.113.0.10 - name-server 198.51.100.3 - subnet 172.18.100.128/29 - } - tls { - ca-certificate ca.crt - certificate server.crt - dh-params dh1024.pem - } - } - -.. start_vyoslinter - -.. stop_vyoslinter - -For a detailed example, refer to -:doc:`OpenVPN with LDAP</configexamples/autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP>`. - -.. start_vyoslinter - -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 ------------ - -.. code-block:: none - - set interfaces openvpn vtun20 encryption cipher 'aes256' - set interfaces openvpn vtun20 hash 'sha512' - set interfaces openvpn vtun20 mode 'server' - set interfaces openvpn vtun20 persistent-tunnel - set interfaces openvpn vtun20 server client user1 - set interfaces openvpn vtun20 server mfa totp challenge 'disable' - set interfaces openvpn vtun20 server subnet '10.10.2.0/24' - set interfaces openvpn vtun20 server topology 'subnet' - set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' - set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' - set interfaces openvpn vtun20 tls dh-params 'dh-pem' - -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: - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode - █████████████████████████████████████ - █████████████████████████████████████ - ████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ - ████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ - ████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ - ████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ - ████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ - ████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ - ████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ - ████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ - ████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ - ████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ - ████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ - ████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ - ████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ - ████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ - ████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ - █████████████████████████████████████ - █████████████████████████████████████ - -.. start_vyoslinter - -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 --------------------- - -.. stop_vyoslinter - -.. code-block:: 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' - -.. start_vyoslinter - -The /config/auth/check_user.sh example includes two test users: - -.. code-block:: 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: - -.. stop_vyoslinter - -.. code-block:: none - - vyos@vyos:~$ generate openvpn client-config interface vtun10 ca ca-1 certificate client1 - -.. start_vyoslinter - -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. - -.. code-block:: 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 - - - <ca> - -----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----- - - </ca> - - <cert> - -----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----- - - </cert> - - <key> - -----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----- - - </key> - -When prompted, log in with the username and password. diff --git a/docs/configuration/interfaces/rst-openvpn.rst b/docs/configuration/interfaces/rst-openvpn.rst deleted file mode 100644 index 85877d48..00000000 --- a/docs/configuration/interfaces/rst-openvpn.rst +++ /dev/null @@ -1,521 +0,0 @@ -.. _openvpn: - -####### -OpenVPN -####### - -Traditionally, hardware routers use IPsec exclusively because it is easy to -implement in hardware, and their CPUs lack sufficient power for software-based -encryption. This limitation is less relevant for VyOS, as it is a software -router. - -OpenVPN has been widely used on UNIX platforms for a long time and is a popular -choice for remote-access VPNs. It also supports site-to-site connections. - -OpenVPN offers the following advantages: - -* It uses a single TCP or UDP connection and does not rely on packet source - addresses, so it works even through double NAT. This makes it well-suited for - public hotspots. - -* It is easy to set up and offers very flexible split tunneling. - -* A variety of client GUI frontends are available for any platform. - -Disadvantages include: - -* It is slower than IPsec due to higher protocol overhead and because it runs - in user mode, while IPsec on Linux runs in kernel mode. - -* No operating system includes OpenVPN client software by default. - -In the VyOS CLI, OpenVPN is configured as a network interface using ``set -interfaces openvpn`` rather than ``set vpn``, which is often overlooked. - -************* -Configuration -************* - -.. cfgcmd:: set interfaces openvpn <interface> authentication password <text> - - **Configure the password for the** ``auth-user-pass`` **authentication method.** - - This option applies only to OpenVPN clients. - -.. cfgcmd:: set interfaces openvpn <interface> authentication username <text> - - **Configure the username for the** ``auth-user-pass`` **authentication method.** - - This option applies only to OpenVPN clients. - -.. cfgcmd:: set interfaces openvpn <interface> description <description> - - Configure the description for the OpenVPN interface. - -.. cfgcmd:: set interfaces openvpn <interface> device-type <tap | tun> - - **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 <interface> disable - - Disable the specific OpenVPN interface. - -.. cfgcmd:: set interfaces openvpn <interface> 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 <interface> 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 <interface> 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 <interface> hash <md5 | sha1 | sha256 | ...> - - Configure the hashing algorithm for the OpenVPN interface. - -.. cmdinclude:: /_include/interface-ip.txt - :var0: openvpn - :var1: vtun0 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: openvpn - :var1: vtun0 - -.. cfgcmd:: set interfaces openvpn <interface> keep-alive failure-count <value> - - **Configure the number of tolerated keepalive packet failures.** - - Default: 60 consecutive failures. - -.. cfgcmd:: set interfaces openvpn <interface> keep-alive interval <value> - - **Configure the frequency, in seconds, at which keepalive packets are sent.** - - Default: 10 seconds. - -.. cfgcmd:: set interfaces openvpn <interface> local-address <address> - - Configure the local tunnel IP address for ``site-to-site`` mode. - -.. cfgcmd:: set interfaces openvpn <interface> local-host <address> - - **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 <interface> local-port <port> - - Configure the local port to accept connections. - -.. cfgcmd:: set interfaces openvpn <interface> mirror egress <monitor-interface> - - Configure mirroring of outgoing traffic from this OpenVPN interface to the - designated monitor interface. - -.. cfgcmd:: set interfaces openvpn <interface> mirror ingress <monitor-interface> - - Configure mirroring of incoming traffic from this OpenVPN interface to the - designated monitor interface. - -.. cfgcmd:: set interfaces openvpn <interface> mode <site-to-site | server | client> - - **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: - - https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features - - * :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 <interface> 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 <interface> openvpn-option <text> - - **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 :ref:`issues_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 <interface> 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 <interface> protocol <udp | tcp-passive | tcp-active > - - **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 <interface> redirect <interface> - - Enable redirection of incoming packets to the specified interface. - -.. cfgcmd:: set interfaces openvpn <interface> remote-address <address> - - Configure the remote tunnel IP address for site-to-site mode. - -.. cfgcmd:: set interfaces openvpn <interface> remote-host <address | 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 <interface> remote-port <port> - - Configure the remote port to connect to the server. - -.. cfgcmd:: set interfaces openvpn <interface> replace-default-route - - Configure the OpenVPN tunnel as the default route. - -.. cfgcmd:: set interfaces openvpn <interface> server bridge disable - - Disable the given instance. - -.. cfgcmd:: set interfaces openvpn <interface> server bridge gateway <ipv4 address> - - Configure the gateway IP address. - -.. cfgcmd:: set interfaces openvpn <interface> server bridge start <ipv4 address> - - Configure the first IP address in the pool to allocate to connecting clients. - -.. cfgcmd:: set interfaces openvpn <interface> server bridge stop <ipv4 address> - - Configure the last IP address in the pool to allocate to connecting clients. - -.. cfgcmd:: set interfaces openvpn <interface> server bridge subnet-mask <ipv4 subnet mask> - - Configure the subnet mask pushed to dynamic clients. - -.. cfgcmd:: set interfaces openvpn <interface> server client <name> - - Configure the Common Name (CN) specified in the client certificate. - -.. cfgcmd:: set interfaces openvpn <interface> server client <name> disable - - Disable the client connection. - -.. cfgcmd:: set interfaces openvpn <interface> server client <name> ip <address> - - Configure the IPv4/IPv6 address for the client. - -.. cfgcmd:: set interfaces openvpn <interface> server client <name> push-route <subnet> - - Configure a route to be pushed to the specific client. - -.. cfgcmd:: set interfaces openvpn <interface> server client <name> subnet <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 <interface> server client-ip-pool start <address> - - Configure the first IP address in the subnet's IPv4 pool to be dynamically - allocated to connecting clients. - -.. cfgcmd:: set interfaces openvpn <interface> server client-ip-pool stop <address> - - Configure the last IP address in the subnet's IPv4 pool to be dynamically - allocated to connecting clients. - -.. cfgcmd:: set interfaces openvpn <interface> server client-ip-pool subnet <netmask> - - **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 <interface> server client-ipv6-pool base <ipv6addr/bits> - - Configure the IPv6 address pool for dynamic assignment to clients. - -.. cfgcmd:: set interfaces openvpn <interface> server domain-name <name> - - Configure the DNS suffix to be pushed to all clients. - -.. cfgcmd:: set interfaces openvpn <interface> server max-connections <1-4096> - - Configure the maximum number of client connections. - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp challenge <enable | disable> - - If enabled, openvpn-otp expects a password as a result of the challenge/ - response protocol. - -.. cfgcmd:: set interfaces openvpn <interface> 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 <interface> server mfa totp drift <1-65535> - - **Configure the time drift in seconds.** - - Default: 0. - -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp slop <1-65535> - - **Configure the allowed clock slop in seconds.** - - Default: 180. - -.. cfgcmd:: set interfaces openvpn <interface> 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 <interface> server name-server <address> - - Define the client DNS configuration to be used with the connection. - -.. cfgcmd:: set interfaces openvpn <interface> server push-route <subnet> - - Configure the route to be pushed to all clients. - -.. cfgcmd:: set interfaces openvpn <interface> server reject-unconfigured-client - - Reject connections from clients that are not explicitly configured. - -.. cfgcmd:: set interfaces openvpn <interface> server subnet <subnet> - - **Configure the IPv4 or IPv6 network.** - - This parameter is mandatory when operating in server mode. - -.. cfgcmd:: set interfaces openvpn <interface> 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 <interface> shared-secret-key <key> - - Configure the static secret key for a site-to-site OpenVPN connection. - -.. cfgcmd:: set interfaces openvpn <interface> tls auth-key <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 <name>`` to generate - the key. - -.. cfgcmd:: set interfaces openvpn <interface> tls ca-certificate <name> - - Configure the Certificate Authority chain in the PKI configuration. - -.. cfgcmd:: set interfaces openvpn <interface> tls certificate <name> - - Configure the certificate name in the PKI configuration. - -.. cfgcmd:: set interfaces openvpn <interface> 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 <interface> tls dh-params - - Configure Diffie-Hellman parameters for server mode. - -.. cfgcmd:: set interfaces openvpn <interface> tls peer-fingerprint <text> - - Configure the peer certificate SHA256 fingerprint for site-to-site mode. - -.. cfgcmd:: set interfaces openvpn <interface> tls role <active | passive> - - **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 <interface> 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 <interface> use-lzo-compression - - Configure fast LZO compression on this TUN/TAP interface. - -.. cfgcmd:: set interfaces openvpn <interface> vrf <name> - - 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 <interface> - - Show logs for the specific OpenVPN interface. - -.. opcmd:: reset openvpn client <text> - - Reset the specified OpenVPN client. - -.. opcmd:: reset openvpn interface <interface> - - Reset the OpenVPN process on the specified interface. - -.. opcmd:: generate openvpn client-config interface <interface> ca <name> certificate <name> - - 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:: - :maxdepth: 1 - :includehidden: - - openvpn-examples - -.. include:: /_include/common-references.txt diff --git a/docs/configuration/interfaces/rst-pppoe.rst b/docs/configuration/interfaces/rst-pppoe.rst deleted file mode 100644 index d2f8271c..00000000 --- a/docs/configuration/interfaces/rst-pppoe.rst +++ /dev/null @@ -1,391 +0,0 @@ -:lastproofread: 2026-03-03 - -.. _pppoe-interface: - -##### -PPPoE -##### - -:abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol -that encapsulates PPP frames within Ethernet frames. -It's often used for connecting ISP clients to a broadband access server. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-description.txt - :var0: pppoe - :var1: pppoe0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: pppoe - :var1: pppoe0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: pppoe - :var1: pppoe0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: pppoe - :var1: pppoe0 - -PPPoE options -============= - -.. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> - - **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 <interface> authentication username <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 <interface> authentication password <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 <interface> 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 <interface> 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 <interface> default-route-distance <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 <interface> mru <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 <interface> idle-timeout <time> - - **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 <interface> holdoff <time> - - **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 <interface> local-address <address> - - **Configure the local endpoint IP address for PPPoE sessions.** - - By default, this IP address is negotiated. - -.. cfgcmd:: set interfaces pppoe <interface> no-peer-dns - - Disable the installation of advertised DNS nameservers on the local system. - -.. cfgcmd:: set interfaces pppoe <interface> remote-address <address> - - **Configure the remote endpoint IP address for PPPoE sessions.** - - By default, this IP address is negotiated. - -.. cfgcmd:: set interfaces pppoe <interface> service-name <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 <interface> source-interface <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 <interface> ip adjust-mss <mss | clamp-mss-to-pmtu> - - **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 <name> adjust-mss <value>`` syntax. - -.. cfgcmd:: set interfaces pppoe <interface> 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 <interface> ip source-validation <strict | loose | disable> - - **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 <interface> ipv6 address autoconf - - Enable IPv6 address assignment via :abbr:`SLAAC (Stateless Address - Auto-Configuration)` on this interface. - -.. cfgcmd:: set interfaces pppoe <interface> ipv6 adjust-mss <mss | clamp-mss-to-pmtu> - - **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 <name> adjust-mss <value>`` syntax. - - -.. cfgcmd:: set interfaces pppoe <interface> 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. - -.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt - :var0: pppoe - :var1: pppoe0 - -********* -Operation -********* - -.. opcmd:: show interfaces pppoe <interface> - - Show detailed information about a specific PPPoE interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces pppoe pppoe0 - pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 - link/ppp - inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 7002658233 5064967 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 533822843 1620173 0 0 0 0 - -.. opcmd:: show interfaces pppoe <interface> queue - - 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 <interface> - - Disconnect the specified interface. - -.. opcmd:: connect interface <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. - - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: none - - set interfaces pppoe pppoe0 authentication username 'userid' - set interfaces pppoe pppoe0 authentication password 'secret' - set interfaces pppoe pppoe0 source-interface 'eth0.7' - - -IPv6 DHCPv6 prefix delegation ------------------------------ - -.. stop_vyoslinter - -**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 ``<prefix>::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. - -.. start_vyoslinter - -.. code-block:: none - - set interfaces pppoe pppoe0 authentication username vyos - set interfaces pppoe pppoe0 authentication password vyos - set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' - set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' - set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' - set interfaces pppoe pppoe0 ipv6 address autoconf - set interfaces pppoe pppoe0 source-interface eth1 - - set service router-advert interface eth0 prefix ::/64 diff --git a/docs/configuration/interfaces/rst-pseudo-ethernet.rst b/docs/configuration/interfaces/rst-pseudo-ethernet.rst deleted file mode 100644 index cb42fafc..00000000 --- a/docs/configuration/interfaces/rst-pseudo-ethernet.rst +++ /dev/null @@ -1,54 +0,0 @@ -:lastproofread: 2026-03-05 - -.. _pseudo-ethernet-interface: - -######################### -MACVLAN (pseudo-Ethernet) -######################### - -MACVLAN, or pseudo-Ethernet interfaces, operate as logical subinterfaces of -standard Ethernet interfaces. Each subinterface has a unique MAC address but -shares a single physical Ethernet port. -That allows the user to send packets from different source IPv4 or IPv6 addresses -using a different MAC address. - - -Pseudo-Ethernet interfaces behave like physical Ethernet interfaces. They -support IPv4 and IPv6 addressing, can obtain IP addresses through DHCP or -DHCPv6, and are mapped to a physical Ethernet port. They inherit -characteristics such as speed and duplex from their parent interface and can -be referenced like standard Ethernet interfaces once created. - - -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 -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: pseudo-ethernet - :var1: peth0 - -MACVLAN (pseudo-Ethernet) options -================================= - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> - - Assign a physical Ethernet interface to the specified pseudo-Ethernet interface. - -VLAN -==== - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: pseudo-ethernet - :var1: peth0 diff --git a/docs/configuration/interfaces/rst-sstp-client.rst b/docs/configuration/interfaces/rst-sstp-client.rst deleted file mode 100644 index 9c6c6e9b..00000000 --- a/docs/configuration/interfaces/rst-sstp-client.rst +++ /dev/null @@ -1,158 +0,0 @@ -:lastproofread: 2026-03-16 - -.. _sstp-client-interface: - -########### -SSTP client -########### - -:abbr:`SSTP (Secure Socket Tunneling Protocol)` transports PPP traffic over an -SSL/TLS channel, providing transport-level security through key negotiation, -encryption, and traffic integrity checking. The use of SSL/TLS over TCP port -443 (by default, the port can be changed) allows SSTP to pass through virtually -all firewalls and proxy servers, except for authenticated web proxies. - -.. note:: VyOS includes a built-in SSTP server. For more information, see - :ref:`sstp`. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-description.txt - :var0: sstpc - :var1: sstpc0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: sstpc - :var1: sstpc0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: sstpc - :var1: sstpc0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: sstpc - :var1: sstpc0 - -SSTP client options -=================== - -.. cfgcmd:: set interfaces sstpc <interface> no-default-route - - 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 <interface> default-route-distance <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 <interface> no-peer-dns - - Disable the installation of advertised DNS nameservers on the local system. - -.. cfgcmd:: set interfaces sstpc <interface> server <address> - - **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 <interface> ip adjust-mss <mss | clamp-mss-to-pmtu> - - **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 <name> adjust-mss <value>`` syntax. - -.. cfgcmd:: set interfaces sstpc <interface> 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 <interface> ip source-validation <strict | loose | disable> - - **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 <interface> - - Show detailed information about the specified interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces sstpc sstpc10 - sstpc10: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3 - link/ppp - inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10 - valid_lft forever preferred_lft forever - inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 215 9 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 539 14 0 0 0 0 - - -Connect/disconnect -================== - -.. opcmd:: disconnect interface <interface> - - Disconnect the specified interface. - -.. opcmd:: connect interface <interface> - - Initiate a session on the specified interface. diff --git a/docs/configuration/interfaces/rst-tunnel.rst b/docs/configuration/interfaces/rst-tunnel.rst deleted file mode 100644 index f1376cdf..00000000 --- a/docs/configuration/interfaces/rst-tunnel.rst +++ /dev/null @@ -1,308 +0,0 @@ -:lastproofread: 2026-01-23 - -.. _tunnel-interface: - -###### -Tunnel -###### - -Tunnel interfaces are virtual links that transmit encapsulated traffic between -private networks or hosts across public infrastructure, such as the Internet. -They operate using encapsulation protocols to wrap original traffic for -transport. The supported protocols include :abbr:`GRE (Generic Routing -Encapsulation)`, IPIP, IPIP6, IP6IP6, and 6in4 (SIT). - -While :abbr:`GRE (Generic Routing Encapsulation)` is often the preferred -one-size-fits-all solution due to its versatility, other encapsulation -protocols may be better suited for specific use cases. - -VyOS uses a single tunnel interface type for all of these protocols. There are -no separate :abbr:`GRE (Generic Routing Encapsulation)`, IPIP, or IP6IP6 -interface types; instead, the desired encapsulation protocol is selected within -the ``set interfaces tunnel`` configuration. - -Configuration options for each protocol are described below. - -.. warning:: Do not change the encapsulation type for already configured tunnel - interfaces, as this may break their dependent configurations. - -Common interface configuration ------------------------------- - -.. cmdinclude:: /_include/interface-address.txt - :var0: tunnel - :var1: tun0 - -.. cmdinclude:: /_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: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation ipip - set interfaces tunnel tun0 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 203.0.113.20 - set interfaces tunnel tun0 address 192.168.100.200/24 - -IP6IP6 ------- - -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: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation ip6ip6 - set interfaces tunnel tun0 source-address 2001:db8:aa::1 - set interfaces tunnel tun0 remote 2001:db8:aa::2 - set interfaces tunnel tun0 address 2001:db8:bb::1/64 - -IPIP6 ------ - -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: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation ipip6 - set interfaces tunnel tun0 source-address 2001:db8:aa::1 - set interfaces tunnel tun0 remote 2001:db8:aa::2 - set interfaces tunnel tun0 address 192.168.70.80/24 - -6in4 (SIT) ----------- - -6in4, 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: - -.. code-block:: none - - set interfaces tunnel tun0 encapsulation sit - set interfaces tunnel tun0 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 192.0.2.20 - set interfaces tunnel tun0 address 2001:db8:bb::1/64 - -.. seealso:: For a practical configuration example, see the - :ref:`Tunnelbroker.net (IPv6) <examples-tunnelbroker-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:** - -.. code-block:: none - - set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' - set interfaces tunnel tun101 address '192.168.5.1/30' - set interfaces tunnel tun101 encapsulation 'ip6gre' - set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3' - set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5' - -**Linux** ``systemd-networkd``: - -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. - -.. code-block:: none - - # cat /etc/systemd/network/gre-example.netdev - [NetDev] - Name=gre-example - Kind=ip6gre - MTUBytes=14180 - - [Tunnel] - Remote=2001:db8:babe:face::3afe:3 - - - # cat /etc/systemd/network/gre-example.network - [Match] - Name=gre-example - - [Network] - Address=2001:db8:feed:beef::2/126 - - [Address] - Address=192.168.5.2/30 - -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: - -.. code-block:: none - - set interfaces tunnel tun0 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 192.0.2.20 - set interfaces tunnel tun0 address 10.40.50.60/24 - set interfaces tunnel tun0 parameters ip key 10 - -.. code-block:: none - - set interfaces tunnel 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: - -.. code-block:: none - - set interfaces bridge br0 member interface eth0 - set interfaces bridge br0 member interface tun0 - set interfaces tunnel tun0 encapsulation gretap - set interfaces tunnel tun0 source-address 198.51.100.2 - set interfaces tunnel tun0 remote 203.0.113.10 - - -Troubleshooting -^^^^^^^^^^^^^^^ - -GRE is a 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. - -.. code-block:: none - - vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 - PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. - 64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms - 64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms - 64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms - 64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms - - --- 203.0.113.10 ping statistics --- - 4 packets transmitted, 4 received, 0% packet loss, time 3007ms - rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms - -2. Verify that the tunnel interface is correctly configured (with the link type -set to GRE) and is actively processing traffic. - -.. code-block:: none - - vyos@vyos:~$ show interfaces tunnel tun100 - tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 - link/gre 198.51.100.2 peer 203.0.113.10 - inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 - valid_lft forever preferred_lft forever - inet6 fe80::5efe:c612:2/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 2183 27 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 836 9 0 0 0 0 - -3. Test the connection through the tunnel using the private IP addresses -assigned to each tunnel endpoint. - -.. code-block:: none - - vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 - PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. - 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms - 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms - 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms - 64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms - - --- 10.0.0.2 ping statistics --- - 4 packets transmitted, 4 received, 0% packet loss, time 3008ms - rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms - -.. _`other proposals`: https://www.isc.org/othersoftware/ -.. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/configuration/interfaces/rst-virtual-ethernet.rst b/docs/configuration/interfaces/rst-virtual-ethernet.rst deleted file mode 100644 index 5df7e962..00000000 --- a/docs/configuration/interfaces/rst-virtual-ethernet.rst +++ /dev/null @@ -1,117 +0,0 @@ -:lastproofread: 2026-01-26 - -.. _virtual-ethernet: - -################ -Virtual Ethernet -################ - -Virtual Ethernet (veth) interfaces are software-based interfaces that operate -in pairs, creating a tunnel between each other. Traffic transmitted into one -interface of the pair (e.g., ``veth0``) is delivered directly to its peer -interface (e.g., ``veth1``). - -Veth interfaces are commonly used to connect network namespaces or VRFs, but -they can also function as standalone virtual network interfaces. - -.. note:: Veth interfaces must be created in pairs, where each interface acts - as the peer of the other. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address-with-dhcp.txt - :var0: virtual-ethernet - :var1: veth0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: virtual-ethernet - :var1: veth0 - -VLAN -==== - -Regular VLANs (802.1q) ----------------------- -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: virtual-ethernet - :var1: veth0 - -802.1ad (QinQ) --------------- - -.. cmdinclude:: /_include/interface-vlan-8021ad.txt - :var0: virtual-ethernet - :var1: veth0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: virtual-ethernet - :var1: veth0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: virtual-ethernet - :var1: veth0 - -********* -Operation -********* - -.. opcmd:: show interfaces virtual-ethernet - - Show brief interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces virtual-ethernet - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - veth10 100.64.0.0/31 u/u - veth11 100.64.0.1/31 u/u - -.. opcmd:: show interfaces virtual-ethernet <interface> - - Show detailed interface information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces virtual-ethernet veth11 - 10: veth11@veth10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP group default qlen 1000 - link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff - inet 100.64.0.1/31 scope global veth11 - valid_lft forever preferred_lft forever - inet6 fe80::b07b:dfff:fe47:e911/64 scope link - valid_lft forever preferred_lft forever - - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 1369707 4267 0 0 0 0 - -******* -Example -******* - -The following example shows how to connect the global VRF to VRF ‘red ‘ using -the ``veth10`` and ``veth11`` veth pair. - -.. code-block:: none - - set interfaces virtual-ethernet veth10 address '100.64.0.0/31' - set interfaces virtual-ethernet veth10 peer-name 'veth11' - set interfaces virtual-ethernet veth11 address '100.64.0.1/31' - set interfaces virtual-ethernet veth11 peer-name 'veth10' - set interfaces virtual-ethernet veth11 vrf 'red' - set vrf name red table '1000' - - vyos@vyos:~$ ping 100.64.0.1 - PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. - 64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms - 64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms - - diff --git a/docs/configuration/interfaces/rst-vti.rst b/docs/configuration/interfaces/rst-vti.rst deleted file mode 100644 index e45c17d9..00000000 --- a/docs/configuration/interfaces/rst-vti.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. _vti-interface: - -############################## -VTI (virtual tunnel interface) -############################## - -:abbr:`VTIs (virtual tunnel interfaces)` let you create secure, encrypted -tunnels between private networks or hosts across public infrastructure, such as -the Internet. They operate alongside an underlying IPsec tunnel, which handles -encapsulation and encryption, while VTIs function exclusively as routing -interfaces. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address.txt - :var0: vti - :var1: vti0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: vti - :var1: vti0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: vti - :var1: vti0 - -.. cmdinclude:: /_include/interface-ip.txt - :var0: vti - :var1: vti0 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: vti - :var1: vti0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: vti - :var1: vti0 - -.. cfgcmd:: set interfaces vti <interface> mirror egress <monitor-interface> - - Configure mirroring of outgoing traffic from the specified VTI to the - designated monitor interface. - -.. cfgcmd:: set interfaces vti <interface> mirror ingress <monitor-interface> - - Configure mirroring of incoming traffic from the specified VTI to the - designated monitor interface. - -.. cfgcmd:: set interfaces vti <interface> redirect <interface> - - Enable redirection of incoming packets to the specified interface. - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: vti - :var1: vti0 - -********* -Operation -********* - -.. opcmd:: show interfaces vti <vtiX> - - Show the operational status and traffic statistics for the specified VTI. - -.. opcmd:: show interfaces vti <vtiX> 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: - -.. code-block:: 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: - -.. code-block:: none - - vyos@vyos# show interfaces vti - vti vti0 { - address 192.168.2.249/30 - address 2001:db8:2::249/64 - description "Description" - } - -.. warning:: When configuring site-to-site IPsec with VTIs, ensure that route - autoinstall is disabled. - -.. code-block:: 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: -https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july. - -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/rst-vxlan.rst b/docs/configuration/interfaces/rst-vxlan.rst deleted file mode 100644 index 0d357e9b..00000000 --- a/docs/configuration/interfaces/rst-vxlan.rst +++ /dev/null @@ -1,358 +0,0 @@ -:lastproofread: 2026-03-16 - -.. _vxlan-interface: - -##### -VXLAN -##### - -:abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology -that addresses scalability challenges in large cloud computing environments. -It encapsulates Ethernet frames (Layer 2) within UDP datagrams (Layer 4), which -are then transmitted via UDP port 4789, as assigned by IANA. VXLAN endpoints, -called :abbr:`VTEPs (VXLAN tunnel endpoints)`, terminate VXLAN tunnels and can -be either virtual or physical switch ports. - -VXLAN supports up to 16 million logical networks and enables Layer 2 adjacency -across Layer 3 IP networks. It uses multicast or unicast with head-end -replication (HER) to flood broadcast, unknown unicast, and multicast (BUM) -traffic. - -The VXLAN specification was initially developed by VMware, Arista Networks, and -Cisco. Other supporters include Huawei, Broadcom, Citrix, Pica8, Big Switch -Networks, Cumulus Networks, Dell EMC, Ericsson, Mellanox, FreeBSD, OpenBSD, Red -Hat, Joyent, and Juniper Networks. - -VXLAN is officially documented by the IETF in :rfc:`7348`. - -When configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing -(Hyper-V) or Forged Transmits (ESX) are permitted. Otherwise, the hypervisor -may block forwarded frames. - -.. note:: Although the IANA-assigned VXLAN port is **4789**, VyOS uses the - Linux default UDP port **8472** for VXLAN interfaces. To ensure compatibility - with other vendors, set the port to the IANA standard **4789**. - -Configuration -============= - -Common interface configuration ------------------------------- - -.. cmdinclude:: /_include/interface-common-without-dhcp.txt - :var0: vxlan - :var1: vxlan0 - -VXLAN-specific options ------------------------ - -.. cfgcmd:: set interfaces vxlan <interface> vni <number> - - **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 <interface> port <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 <interface> source-address <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 <interface> 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 <interface> 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 <interface> 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 <interface> parameters nolearning - - Disable :abbr:`SLLA (Source Link-Layer Address)` and IP address learning on - the VXLAN interface. - -.. cfgcmd:: set interfaces vxlan <interface> 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 <interface> remote <address> - - **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 <interface> source-interface <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 <interface> group <address> - - **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 <interface> vlan-to-vni <vlan> 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. - -.. code-block:: none - - Spine1: - fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 - fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 - - Leaf2: - Eth0 towards Spine1, IP-address: 10.1.2.2/24 - Eth1 towards a VLAN-aware switch - - Leaf3: - Eth0 towards Spine1, IP-address 10.1.3.3/24 - Eth1 towards a VLAN-aware switch - -**Spine1 configuration:** - -.. code-block:: none - - conf t - ip multicast-routing - ! - interface fastethernet0/2 - ip address 10.1.2.1 255.255.255.0 - ip pim sparse-dense-mode - ! - interface fastethernet0/3 - ip address 10.1.3.1 255.255.255.0 - ip pim sparse-dense-mode - ! - router ospf 1 - network 10.0.0.0 0.255.255.255 area 0 - -Multicast routing is required for 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:** - -.. code-block:: 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:** - -.. code-block:: 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. - -.. code-block:: 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``. - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: none - - set interfaces vxlan vxlan241 vni '241' - -This command configures the unique ID for the VXLAN interface. - -.. code-block:: 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: - -.. code-block:: 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 <vxlanN> port <port>``. - diff --git a/docs/configuration/interfaces/rst-wireguard.rst b/docs/configuration/interfaces/rst-wireguard.rst deleted file mode 100644 index bc53b388..00000000 --- a/docs/configuration/interfaces/rst-wireguard.rst +++ /dev/null @@ -1,439 +0,0 @@ -:lastproofread: 2026-03-02 - -.. _wireguard: - -######### -WireGuard -######### - -WireGuard is an extremely simple, fast, and modern VPN that utilizes -state-of-the-art cryptography. See https://www.wireguard.com for more -information. - -**************** -Site-to-site VPN -**************** - -The following diagram illustrates a site-to-site VPN setup. - -.. figure:: /_static/images/wireguard_site2site_diagram.* - -******** -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 <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 <interface> 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= - - -.. stop_vyoslinter - -.. opcmd:: generate pki wireguard preshared-key install interface <interface> peer <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. - -.. start_vyoslinter - - -*********************** -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`` - -.. code-block:: none - - set interfaces wireguard wg01 address '10.1.0.1/30' - set interfaces wireguard wg01 description 'VPN-to-wg02' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' - set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' - set interfaces wireguard wg01 peer to-wg02 port '51820' - set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' - set interfaces wireguard wg01 port '51820' - - set protocols static route 192.168.2.0/24 interface wg01 - -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 <interface> private-key <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`. - -.. cmdinclude:: /_include/interface-per-client-thread.txt - :var0: wireguard - :var1: wg01 - -**Remote side configuration** - -.. code-block:: none - - set interfaces wireguard wg01 address '10.1.0.2/30' - set interfaces wireguard wg01 description 'VPN-to-wg01' - set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' - set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' - set interfaces wireguard wg01 peer to-wg01 port '51820' - set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' - set interfaces wireguard wg01 port '51820' - set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=' - - set protocols static route 192.168.1.0/24 interface wg01 - -******************* -Firewall exceptions -******************* - -To allow WireGuard traffic through the WAN interface, create a firewall -exception: - -.. code-block:: none - - set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept - set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' - set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable - set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable - set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept - set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN - set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 - set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable - set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp - -Ensure that the OUTSIDE_LOCAL firewall group is applied to the WAN interface -and in an input (local) direction. - -.. code-block:: none - - set firewall ipv4 input filter rule 10 action jump - set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' - set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' - -Verify that your firewall rules permit traffic. If so, your WireGuard VPN -should be operational. - -.. code-block:: none - - wg01# ping 192.168.1.1 - PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. - 64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms - 64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms - - wg02# ping 192.168.2.1 - PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. - 64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms - 64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms - -An additional layer of symmetric-key cryptography can be used on top of the -asymmetric cryptography. This is optional. - -.. code-block:: none - - vyos@vyos:~$ generate pki wireguard preshared-key - Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= - -Copy the key, as it is not stored locally. Since it is a symmetric key, only -you and your peer should know its contents. Distribute the key securely. - -.. code-block:: none - - wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' - wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' - - -**************************** -Remote access (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. - -.. code-block:: none - - wireguard wg01 { - address 10.172.24.1/24 - address 2001:db8:470:22::1/64 - description RoadWarrior - peer MacBook { - allowed-ips 10.172.24.30/32 - allowed-ips 2001:db8:470:22::30/128 - persistent-keepalive 15 - 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. - -.. code-block:: none - - [Interface] - PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= - Address = 10.172.24.20/24, 2001:db8:470:22::20/64 - DNS = 10.0.0.53, 10.0.0.54 - - [Peer] - PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= - AllowedIPs = 0.0.0.0/0, ::/0 - Endpoint = 192.0.2.1:2224 - PersistentKeepalive = 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. - -.. code-block:: none - - [Interface] - PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= - Address = 10.172.24.30/24, 2001:db8:470:22::30/64 - - [Peer] - PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= - AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64 - Endpoint = 192.0.2.1:2224 - PersistentKeepalive = 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: <peer pubkey> - endpoint: <peer public IP> - allowed ips: 10.69.69.2/32 - latest handshake: 23 hours, 45 minutes, 26 seconds ago - transfer: 1.26 MiB received, 6.47 MiB sent - -.. opcmd:: show interfaces wireguard - - 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 <interface> - - 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 <name> interface <interface> server - <ip|fqdn> address <client-ip> - - **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 ``<name>`` 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.* - :alt: WireGuard Client QR code - -.. _`WireGuard mailing list`: - https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html diff --git a/docs/configuration/interfaces/rst-wireless.rst b/docs/configuration/interfaces/rst-wireless.rst deleted file mode 100644 index 728783b2..00000000 --- a/docs/configuration/interfaces/rst-wireless.rst +++ /dev/null @@ -1,931 +0,0 @@ -:lastproofread: 2026-03-23 - -.. _wireless-interface: - -#################### -Wireless LAN / Wi-Fi -#################### - -:abbr:`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless -connectivity, referred to as Wi-Fi, and operate in one of the following -modes: - -* :abbr:`WAP (Wireless Access-Point)` mode provides network access to connecting - stations if the physical hardware supports acting as a WAP - -* Station mode acts as a Wi-Fi client accessing the network through an available - WAP - -* Monitor mode lets the system passively monitor wireless traffic - -If the system detects an unconfigured wireless device, it will be automatically -added to the configuration tree, specifying any detected settings (for example, -its MAC address) and configured to run in monitor mode. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-common-with-dhcp.txt - :var0: wireless - :var1: wlan0 - -System-wide configuration -========================= - -.. cfgcmd:: set system wireless country-code <cc> - - Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed - to indicate country in which device is operating. This can limit available - channels and transmit power. - - .. note:: This option is mandatory in ``access-point`` mode. - -Wireless options -================ - -.. cfgcmd:: set interfaces wireless <interface> channel <number> - - 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 <interface> disable-broadcast-ssid - - Send empty SSID in beacons and ignore probe request frames that do not specify - full SSID, i.e., require stations to know the SSID. - -.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations - - Disassociate stations based on excessive transmission failures or other - indications of connection loss. - - This depends on the driver capabilities and may not be available with all - drivers. - -.. cfgcmd:: set interfaces wireless <interface> isolate-stations - - Client isolation can be used to prevent low-level bridging of frames between - associated stations in the BSS. - - By default, this bridging is allowed. - -.. cfgcmd:: set interfaces wireless <interface> max-stations <count> - - Maximum number of stations allowed in station table. New stations will be - rejected after the station table is full. IEEE 802.11 has a limit of 2007 - different association IDs, so this number should not be larger than that. - - This defaults to 2007. - -.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection - - Management Frame Protection (MFP) according to IEEE 802.11w - - .. note:: :abbr:`MFP (Management Frame Protection)` is required for WPA3. - -.. cfgcmd:: set interfaces wireless <interface> 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 <interface> mode <a | b | g | n | ac | ax> - - 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 <interface> physical-device <device> - - Wireless hardware device used as underlay radio. - - This defaults to phy0. - -.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> - - 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 <interface> ssid <ssid> - - SSID to be used in IEEE 802.11 management frames - -.. cfgcmd:: set interfaces wireless <interface> type - <access-point | station | monitor> - - Wireless device type for this interface - - * ``access-point``: Forwards packets between other nodes. - * ``station``: Connects to another :abbr:`AP (Access Point)`. - * ``monitor``: Passively monitors all packets on the frequency/channel. - -.. cmdinclude:: /_include/interface-per-client-thread.txt - :var0: wireless - :var1: wlan0 - -PPDU ----- - -.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht - -.. cfgcmd:: set interfaces wireless <interface> capabilities require-vht - -.. cfgcmd:: set interfaces wireless <interface> 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 <interface> capabilities ht 40mhz-incapable - - Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave - - WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - channel-set-width <ht20 | ht40+ | ht40-> - - Supported channel width set. - - * ``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 <interface> capabilities ht - delayed-block-ack - - Enable HT-delayed Block Ack ``[DELAYED-BA]`` - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40 - - DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield - - This enables the greenfield option which sets the ``[GF]`` option - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc - - Enable LDPC coding capability - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection - - Enable L-SIG TXOP protection capability - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu - <3839 | 7935> - - Maximum A-MSDU length 3839 (default) or 7935 octets - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - short-gi <20 | 40> - - Short GI capabilities for 20 and 40 MHz - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht - smps <static | dynamic> - - Spatial Multiplexing Power Save (SMPS) settings - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num> - - Enable receiving PPDU using STBC (Space Time Block Coding) - -.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx - - Enable sending PPDU using STBC (Space Time Block Coding) - -VHT (Very High Throughput) capabilities (802.11ac) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. stop_vyoslinter - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count <count> - -.. start_vyoslinter - - Number of antennas on this card - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - antenna-pattern-fixed - - Set if antenna pattern does not change during the lifetime of an association - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform - <single-user-beamformer | single-user-beamformee | multi-user-beamformer | - multi-user-beamformee> - - Beamforming capabilities: - - * ``single-user-beamformer`` - Support for operation as - single user beamformer - * ``single-user-beamformee`` - Support for operation as - single user beamformee - * ``multi-user-beamformer`` - Support for operation as - multi user beamformer - * ``multi-user-beamformee`` - Support for operation as - multi user beamformee - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - center-channel-freq <freq-1 | freq-2> <number> - - VHT operating channel center frequency - center freq 1 - (for use with 80, 80+80 and 160 modes) - - VHT operating channel center frequency - center freq 2 - (for use with the 80+80 mode) - - <number> must be from 34 - 173. For 80 MHz channels it should be channel + 6. - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - channel-set-width <0 | 1 | 2 | 3> - - * ``0`` - 20 or 40 MHz channel width (default) - * ``1`` - 80 MHz channel width - * ``2`` - 160 MHz channel width - * ``3`` - 80+80 MHz channel width - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc - - Enable LDPC (Low Density Parity Check) coding capability - -.. cfgcmd:: set interfaces wireless <interface> - capabilities vht link-adaptation - - VHT link adaptation capabilities - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - max-mpdu <value> - - Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - max-mpdu-exp <value> - - Set the maximum length of A-MPDU pre-EOF padding that the station can - receive - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht - short-gi <80 | 160> - - Short GI capabilities - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num> - - Enable receiving PPDU using STBC (Space Time Block Coding) - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx - - Enable sending PPDU using STBC (Space Time Block Coding) - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave - - Enable VHT TXOP Power Save Mode - -.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf - - Station supports receiving VHT variant HT Control field - -HE (High Efficiency) capabilities (802.11ax) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. cfgcmd:: set interfaces wireless <interface> - 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 <interface> capabilities he beamform - <single-user-beamformer | single-user-beamformee | multi-user-beamformer> - - 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 <interface> - capabilities he bss-color <number> - - BSS coloring helps to prevent channel jamming when multiple APs use - the same channels. - - Valid values are 1..63 - -.. cfgcmd:: set interfaces wireless <interface> capabilities he - center-channel-freq <freq-1 | freq-2> <number> - - 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) - - <number> 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 <interface> - capabilities he channel-set-width <number> - - <number> 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 <interface> - capabilities he coding-scheme <number> - - 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. - - <number> 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. - -.. code-block:: 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: - -.. code-block:: 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`` - -.. stop_vyoslinter -.. code-block:: 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 - -.. start_vyoslinter - -Resulting configuration: - -.. code-block:: 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) ----------------------- - -.. cmdinclude:: /_include/interface-vlan-8021q.txt - :var0: wireless - :var1: wlan0 - -QinQ (802.1ad) --------------- - -.. cmdinclude:: /_include/interface-vlan-8021ad.txt - :var0: wireless - :var1: wlan0 - -********* -Operation -********* - -.. opcmd:: show interfaces wireless info - -Use this command to view operational status and wireless-specific information -about all wireless interfaces. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless info - Interface Type SSID Channel - wlan0 access-point VyOS-TEST-0 1 - -.. opcmd:: show interfaces wireless detail - -Show the operational status and detailed wireless-specific -information about all wireless interfaces. - -.. stop_vyoslinter -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless detail - wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.99.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 66072 282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 83413 430 0 0 0 0 - - wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.100.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 166072 5282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 183413 5430 0 0 0 0 - -.. start_vyoslinter - -.. opcmd:: show interfaces wireless <wlanX> - -This command shows both status and statistics on the specified wireless -interface. The wireless interface identifier can range from wlan0 to wlan999. - -.. stop_vyoslinter -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 - wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.99.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 66072 282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 83413 430 0 0 0 0 - -.. start_vyoslinter - - -.. opcmd:: show interfaces wireless <wlanX> brief - -This command gives a brief status overview of a specified wireless interface. -The wireless interface identifier can range from wlan0 to wlan999. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 brief - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - wlan0 192.168.2.254/24 u/u - - -.. opcmd:: show interfaces wireless <wlanX> queue - -Use this command to view wireless interface queue information. -The wireless interface identifier can range from wlan0 to wlan999. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 queue - qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 - Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) - rate 0bit 0pps backlog 0b 0p requeues 0 - - -.. opcmd:: show interfaces wireless <wlanX> scan - -This command is used to retrieve information about WAP within the range of your -wireless interface. This command is useful on wireless interfaces configured -in station mode. - -.. note:: Scanning is not supported on all wireless drivers and wireless - hardware. Refer to your driver and wireless hardware documentation for - further details. - -.. code-block:: none - - vyos@vyos:~$ show interfaces wireless wlan0 scan - Address SSID Channel Signal (dbm) - 00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 - 00:53:3b:88:6e:da Telekom_FON 1 -64.00 - 00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 - 00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 - 00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 - 00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 - 00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 - 00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 - 00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 - 00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 - 00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 - 00:53:86:40:30:da Telekom_FON 1 -86.00 - 00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 - 00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 - - -******** -Examples -******** - -The following example creates a WAP. When configuring multiple WAP interfaces, -you must specify unique IP addresses, channels, Network IDs commonly referred -to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses. - -The WAP in this example has the following characteristics: - -* IP address ``192.168.2.1/24`` -* Network ID (SSID) ``TEST`` -* WPA passphrase ``12345678`` -* Use 802.11n protocol -* Wireless channel ``1`` - -.. code-block:: none - - set 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: - -.. code-block:: 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. - -.. stop_vyoslinter - -.. code-block:: 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 - -.. start_vyoslinter - -Resulting configuration: - -.. code-block:: 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. - -.. stop_vyoslinter - -.. code-block:: 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 - -.. start_vyoslinter - -Resulting configuration: - -.. code-block:: 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: - -.. stop_vyoslinter -.. code-block:: 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' - -.. start_vyoslinter diff --git a/docs/configuration/interfaces/rst-wwan.rst b/docs/configuration/interfaces/rst-wwan.rst deleted file mode 100644 index 7ab3ac74..00000000 --- a/docs/configuration/interfaces/rst-wwan.rst +++ /dev/null @@ -1,342 +0,0 @@ -:lastproofread: 2026-03-30 - -.. _wwan-interface: - -#### -WWAN -#### - -:abbr:`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular -networks via a cellular modem or card. - -Configure these interfaces under the ``interfaces wwan`` node. - -************* -Configuration -************* - -Common interface configuration -============================== - -.. cmdinclude:: /_include/interface-address-with-dhcp.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-description.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-disable.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-disable-link-detect.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-mtu.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-ip.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-ipv6.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-vrf.txt - :var0: wwan - :var1: wwan0 - -**DHCP(v6)** - -.. cmdinclude:: /_include/interface-dhcp-options.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-dhcpv6-options.txt - :var0: wwan - :var1: wwan0 - -.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt - :var0: wwan - :var1: wwan0 - -WWAN options -============ - -.. cfgcmd:: set interfaces wwan <interface> apn <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 <interface> - - Show the operational status and traffic statistics for the specified WWAN - interface. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 - wwan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 - link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff - inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0 - valid_lft 7012sec preferred_lft 7012sec - inet6 fe80::c2:f3ff:fe00:0102/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 640 2 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 3229 16 0 0 0 0 - -.. opcmd:: show interfaces wwan <interface> summary - - Show 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 <interface> 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 <interface> 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 <interface> imei - - Show WWAN module IMEI. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 imei - ESN: '0' - IMEI: '358xxxxxxxxxxxx' - MEID: 'unknown' - -.. opcmd:: show interfaces wwan <interface> imsi - - Show the IMSI of the associated SIM card. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 imsi - IMSI: '262xxxxxxxxxxxx' - -.. opcmd:: show interfaces wwan <interface> model - - Show WWAN module model. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 model - Model: 'MC7710' - -.. opcmd:: show interfaces wwan <interface> msisdn - - Show the MSISDN of the associated SIM card. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 msisdn - MSISDN: '4917xxxxxxxx' - -.. opcmd:: show interfaces wwan <interface> revision - - Show WWAN module hardware revision. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 revision - Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' - -.. opcmd:: show interfaces wwan <interface> signal - - Show 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 <interface> sim - - Show WWAN module SIM card information. - - .. code-block:: none - - vyos@vyos:~$ show interfaces wwan wwan0 sim - Provisioning applications: - Primary GW: slot '1', application '1' - Primary 1X: session doesn't exist - Secondary GW: session doesn't exist - Secondary 1X: session doesn't exist - Slot [1]: - Card state: 'present' - UPIN state: 'not-initialized' - UPIN retries: '0' - UPUK retries: '0' - Application [1]: - Application type: 'usim (2)' - Application state: 'ready' - Application ID: - A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00 - Personalization state: 'ready' - UPIN replaces PIN1: 'no' - PIN1 state: 'disabled' - PIN1 retries: '3' - PUK1 retries: '10' - PIN2 state: 'enabled-not-verified' - PIN2 retries: '3' - PUK2 retries: '10' - -******* -Example -******* - -The following example 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`. - -.. code-block:: 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. - -.. code-block:: bash - - $ sudo qmi-firmware-update --update -d 1199:68a2 \ - 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe |