From 038b3a3a2ad91f67f074ba05a35d800c3dac2c07 Mon Sep 17 00:00:00 2001
From: Yuriy Andamasov <yuriy@vyos.io>
Date: Sat, 2 May 2026 21:13:13 +0300
Subject: feat(swap-circinus): add incremental RST-to-MyST swap mechanism
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Backport of the swap mechanism from feat/incremental-myst-swap onto
the circinus release branch. Built directly on top of origin/circinus,
so the underlying RST tree is circinus's (not current's).

Mechanism:
- scripts/import_myst.py — import md from myst/* with md- prefix
- scripts/swap_sources.py — rename md-{name}.md → {name}.md before
  Sphinx builds, restore after; writes _build/_swap_state.json and
  _build/_swap_exclude.txt
- docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build →
  trap restore; explicit `swap` and `restore` targets too
- docs/conf.py — MyST extensions enabled; swap exclude_patterns
  loader; _prefer_webp builder hook so html prefers webp over png

Content (all from origin/myst/circinus):
- 253 md-prefixed pages alongside each {name}.rst counterpart
- 1 plain MyST-only page kept at canonical name (docs/copyright.md,
  no .rst counterpart)
- 182 .webp images added (circinus release previously had only
  PNG/JPG; this PR brings webp into circinus alongside the originals)
- docs/_swap.txt populated with all 253 stems → MyST is served by
  default; revert a page by removing its stem from _swap.txt

🤖 Generated by [robots](https://vyos.io)
---
 docs/configuration/interfaces/md-bonding.md        |  753 +++++++++++++++
 docs/configuration/interfaces/md-bridge.md         |  431 +++++++++
 docs/configuration/interfaces/md-dummy.md          |   87 ++
 docs/configuration/interfaces/md-ethernet.md       |  515 ++++++++++
 docs/configuration/interfaces/md-geneve.md         |  105 ++
 docs/configuration/interfaces/md-index.md          |   26 +
 docs/configuration/interfaces/md-l2tpv3.md         |  170 ++++
 docs/configuration/interfaces/md-loopback.md       |   67 ++
 docs/configuration/interfaces/md-macsec.md         |  319 ++++++
 .../interfaces/md-openvpn-examples.md              |  855 +++++++++++++++++
 docs/configuration/interfaces/md-openvpn.md        |  614 ++++++++++++
 docs/configuration/interfaces/md-pppoe.md          |  419 ++++++++
 .../configuration/interfaces/md-pseudo-ethernet.md |   52 +
 docs/configuration/interfaces/md-sstp-client.md    |  170 ++++
 docs/configuration/interfaces/md-tunnel.md         |  304 ++++++
 .../interfaces/md-virtual-ethernet.md              |  119 +++
 docs/configuration/interfaces/md-vti.md            |   53 +
 docs/configuration/interfaces/md-vxlan.md          |  373 ++++++++
 docs/configuration/interfaces/md-wireguard.md      |  441 +++++++++
 docs/configuration/interfaces/md-wireless.md       | 1012 ++++++++++++++++++++
 docs/configuration/interfaces/md-wwan.md           |  355 +++++++
 21 files changed, 7240 insertions(+)
 create mode 100644 docs/configuration/interfaces/md-bonding.md
 create mode 100644 docs/configuration/interfaces/md-bridge.md
 create mode 100644 docs/configuration/interfaces/md-dummy.md
 create mode 100644 docs/configuration/interfaces/md-ethernet.md
 create mode 100644 docs/configuration/interfaces/md-geneve.md
 create mode 100644 docs/configuration/interfaces/md-index.md
 create mode 100644 docs/configuration/interfaces/md-l2tpv3.md
 create mode 100644 docs/configuration/interfaces/md-loopback.md
 create mode 100644 docs/configuration/interfaces/md-macsec.md
 create mode 100644 docs/configuration/interfaces/md-openvpn-examples.md
 create mode 100644 docs/configuration/interfaces/md-openvpn.md
 create mode 100644 docs/configuration/interfaces/md-pppoe.md
 create mode 100644 docs/configuration/interfaces/md-pseudo-ethernet.md
 create mode 100644 docs/configuration/interfaces/md-sstp-client.md
 create mode 100644 docs/configuration/interfaces/md-tunnel.md
 create mode 100644 docs/configuration/interfaces/md-virtual-ethernet.md
 create mode 100644 docs/configuration/interfaces/md-vti.md
 create mode 100644 docs/configuration/interfaces/md-vxlan.md
 create mode 100644 docs/configuration/interfaces/md-wireguard.md
 create mode 100644 docs/configuration/interfaces/md-wireless.md
 create mode 100644 docs/configuration/interfaces/md-wwan.md

(limited to 'docs/configuration/interfaces')

diff --git a/docs/configuration/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md
new file mode 100644
index 00000000..4538b145
--- /dev/null
+++ b/docs/configuration/interfaces/md-bonding.md
@@ -0,0 +1,753 @@
+---
+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
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: bonding
+   :var1: bond0
+```
+
+### Member interfaces
+
+```{eval-rst}
+.. 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:
+```
+
+```none
+set interfaces bonding bond0 member interface eth0
+set interfaces bonding bond0 member interface eth1
+```
+
+### Bond modes
+
+```{eval-rst}
+.. 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)`.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. 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.
+
+```
+
+```{eval-rst}
+.. 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.
+
+```
+
+```{eval-rst}
+.. 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``.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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)`
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: bonding
+   :var1: bond0
+```
+
+### SPAN port mirroring
+
+```{eval-rst}
+.. cmdincludemd:: ../../_include/interface-mirror.txt
+   :var0: bonding
+   :var1: bond1
+   :var2: eth3
+```
+
+#### EVPN multihoming
+
+EVPN multihoming (EVPN-MH) is a standards-based solution (RFC 7432, RFC 8365)
+that enables Customer Edge (CE) devices, such as servers, to connect to two
+or more Provider Edge (PE) devices for redundancy and load balancing.
+
+EVPN-MH is often used as a modern, standards-based alternative to
+{abbr}`MLAG (Multi-Chassis Link Aggregation)` and {abbr}`VTEPs (Virtual
+Tunnel Endpoints)`.
+
+**Ethernet Segment (ES) and Ethernet Segment Identifier (ESI)**
+
+Physical links that connect a CE device to PE devices are bundled using link
+aggregation. This logical bundle is called an Ethernet Segment (ES) and is
+uniquely identified by an Ethernet Segment Identifier (ESI) within the
+EVPN domain.
+
+To enable EVPN-MH, configure the same ESI on the bonding interfaces of all
+PE devices connected to a single CE device.
+
+An ESI is configured by specifying either a system MAC address and a local
+discriminator, or an Ethernet Segment Identifier Name (ESINAME).
+
+The following two commands generate a 10-byte Type-3 ESI by combining the
+system MAC and local discriminator:
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> evpn es-id <1-16777215|10-byte ID>
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-evpn-uplink.txt
+   :var0: bonding
+   :var1: bond0
+```
+
+## Example
+
+The following configuration example applies to all listed third-party vendors.
+It creates a bonding interface with two member interfaces, defines VLANs 10
+and 100 on the bonding interface, and assigns an IPv4 address to each VLAN
+subinterface.
+
+```none
+# Create the bonding interface bond0 with 802.3ad LACP
+set interfaces bonding bond0 hash-policy 'layer2'
+set interfaces bonding bond0 mode '802.3ad'
+
+# Add the required VLANs and IPv4 addresses on them
+set interfaces bonding bond0 vif 10 address 192.168.0.1/24
+set interfaces bonding bond0 vif 100 address 10.10.10.1/24
+
+# Add the member interfaces to the bonding interface
+set interfaces bonding bond0 member interface eth1
+set interfaces bonding bond0 member interface eth2
+```
+
+:::{note}
+If you are running this configuration in a virtual environment like
+EVE-NG, ensure the e1000 driver is chosen for your VyOS NIC. The default
+drivers, such as `virtio-net-pci` or `vmxnet3`, are incompatible with
+this configuration. Specifically, ICMP messages will not be processed correctly.
+
+To check your NIC driver, use the following command: {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:
+
+```none
+interface GigabitEthernet1/0/23
+ description VyOS eth1
+ channel-group 1 mode active
+!
+interface GigabitEthernet1/0/24
+ description VyOS eth2
+ channel-group 1 mode active
+!
+```
+
+A new interface, `Port-channel1`, becomes available; all configuration,
+such as allowed VLAN interfaces and STP, is applied here.
+
+```none
+interface Port-channel1
+ description LACP Channel for VyOS
+ switchport trunk encapsulation dot1q
+ switchport trunk allowed vlan 10,100
+ switchport mode trunk
+ spanning-tree portfast trunk
+!
+```
+
+### Juniper EX Switch configuration
+
+Configure a Juniper EX Series switch to integrate with a two-member VyOS bonding
+interface.
+
+```none
+# Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s
+set interfaces ae0 aggregated-ether-options link-speed 10g
+set interfaces ae0 aggregated-ether-options lacp active
+
+# Create layer 2 on the aggregated ethernet device with trunking for our VLANs
+set interfaces ae0 unit 0 family ethernet-switching port-mode trunk
+
+# Add the required vlans to the device
+set interfaces ae0 unit 0 family ethernet-switching vlan members 10
+set interfaces ae0 unit 0 family ethernet-switching vlan members 100
+
+# Add the two interfaces to the aggregated ethernet device, in this setup both
+# ports are on the same switch (switch 0, module 1, port 0 and 1)
+set interfaces xe-0/1/0 ether-options 802.3ad ae0
+set interfaces xe-0/1/1 ether-options 802.3ad ae0
+
+# But this can also be done with multiple switches in a stack, a virtual
+# chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches)
+set interfaces xe-0/1/0 ether-options 802.3ad ae0
+set interfaces xe-1/1/0 ether-options 802.3ad ae0
+```
+
+### Aruba/HP configuration
+
+Configure an Aruba/HP 2510G switch to integrate with a two-member VyOS bonding
+interface.
+
+```none
+# Create trunk with 2 member interfaces (interface 1 and 2) and LACP
+trunk 1-2 Trk1 LACP
+
+# Add the required VLANs to the trunk
+vlan 10 tagged Trk1
+vlan 100 tagged Trk1
+```
+
+### Arista EOS configuration
+
+When deploying VyOS in environments with Arista switches, use the following
+blueprint as an initial setup to configure an operational LACP port-channel
+between the two devices.
+
+Let's assume the following topology:
+
+:::{figure} /_static/images/vyos_arista_bond_lacp.webp
+:alt: VyOS Arista EOS setup
+:::
+
+**R1**
+
+```none
+interfaces {
+    bonding bond10 {
+        hash-policy layer3+4
+        member {
+            interface eth1
+            interface eth2
+        }
+        mode 802.3ad
+        vif 100 {
+            address 192.0.2.1/30
+            address 2001:db8::1/64
+        }
+    }
+```
+
+**R2**
+
+```none
+interfaces {
+    bonding bond10 {
+        hash-policy layer3+4
+        member {
+            interface eth1
+            interface eth2
+        }
+        mode 802.3ad
+        vif 100 {
+            address 192.0.2.2/30
+            address 2001:db8::2/64
+        }
+    }
+```
+
+**SW1**
+
+```none
+!
+vlan 100
+   name FOO
+!
+interface Port-Channel10
+   switchport trunk allowed vlan 100
+   switchport mode trunk
+   spanning-tree portfast
+!
+interface Port-Channel20
+   switchport mode trunk
+   no spanning-tree portfast auto
+   spanning-tree portfast network
+!
+interface Ethernet1
+   channel-group 10 mode active
+!
+interface Ethernet2
+   channel-group 10 mode active
+!
+interface Ethernet3
+   channel-group 20 mode active
+!
+interface Ethernet4
+   channel-group 20 mode active
+!
+```
+
+**SW2**
+
+```none
+!
+vlan 100
+   name FOO
+!
+interface Port-Channel10
+   switchport trunk allowed vlan 100
+   switchport mode trunk
+   spanning-tree portfast
+!
+interface Port-Channel20
+   switchport mode trunk
+   no spanning-tree portfast auto
+   spanning-tree portfast network
+!
+interface Ethernet1
+   channel-group 10 mode active
+!
+interface Ethernet2
+   channel-group 10 mode active
+!
+interface Ethernet3
+   channel-group 20 mode active
+!
+interface Ethernet4
+   channel-group 20 mode active
+!
+```
+
+:::{note}
+When testing this environment in EVE-NG, ensure the e1000 driver
+is chosen for your VyOS network interfaces. If the default virtio driver
+is used, VyOS will not transmit LACP PDUs, preventing the port-channel
+from ever becoming active.
+:::
+
+## Operation
+
+```{eval-rst}
+.. 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
+
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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/md-bridge.md b/docs/configuration/interfaces/md-bridge.md
new file mode 100644
index 00000000..77775767
--- /dev/null
+++ b/docs/configuration/interfaces/md-bridge.md
@@ -0,0 +1,431 @@
+---
+lastproofread: '2025-12-22'
+---
+
+(bridge-interface)=
+
+# Bridge
+
+VyOS bridges connect Ethernet segments by grouping multiple interfaces into a
+single bridge interface, which acts as a virtual software switch. Unlike
+routers, which forward traffic based on Layer 3 IP addresses, bridges operate
+at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2,
+bridges are protocol-agnostic and transparently forward all Ethernet-
+encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial
+protocols.
+
+This implementation utilizes the Linux bridge subsystem to support a subset of
+the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning.
+
+:::{note}
+{abbr}`STP (Spanning Tree Protocol)` is disabled by default in VyOS
+and must be explicitly enabled if required. See {ref}`stp` for details.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: bridge
+:var1: br0
+```
+
+
+### Member interfaces
+
+```{cfgcmd} set interfaces bridge \<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
+
+```{cmdincludemd} /_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
+
+```{cmdincludemd} ../../_include/interface-mirror.txt
+:var0: bridge
+:var1: br1
+:var2: eth3
+```
+
+
+## Examples
+
+### Configure a standard bridge
+
+The following example creates a bridge named br100 with {abbr}`STP (Spanning
+Tree Protocol)` enabled.
+
+Configuration requirements:
+- **Bridge name:** `br100`
+- **Member interfaces:** Physical interface `eth1` and VLAN interface `eth2.10`.
+- **STP:** Enabled.
+- **Bridge IP addresses:** `192.0.2.1/24` (IPv4) and `2001:db8::ffff/64` (IPv6).
+
+```none
+set interfaces bridge br100 address 192.0.2.1/24
+set interfaces bridge br100 address 2001:db8::ffff/64
+set interfaces bridge br100 member interface eth1
+set interfaces bridge br100 member interface eth2.10
+set interfaces bridge br100 stp
+```
+
+Verify the configuration:
+
+```none
+vyos@vyos# show interfaces bridge br100
+ address 192.0.2.1/24
+ address 2001:db8::ffff/64
+ member {
+     interface eth1 {
+     }
+     interface eth2.10 {
+     }
+ }
+ stp
+```
+
+
+### Configure a VLAN-aware bridge
+
+The following example creates a VLAN-aware bridge named br100. In this setup,
+one member interface is configured as a trunk port, and the other as an access
+port. The VLAN interface is configured with IP addresses.
+
+**Configuration requirements:**
+- **Bridge name:** `br100`.
+- **Trunk port** (`eth1`): Handles **tagged** traffic for VLAN 10.
+- **Access port** (`eth2`): Handles **untagged** traffic (assigned to native
+  VLAN 10).
+- **STP:** Enabled.
+- **VLAN IP addresses** (`vif 10`): `192.0.2.1/24` (IPv4) and
+  `2001:db8::ffff/64` (IPv6).
+
+```none
+set interfaces bridge br100 enable-vlan
+set interfaces bridge br100 member interface eth1 allowed-vlan 10
+set interfaces bridge br100 member interface eth2 native-vlan 10
+set interfaces bridge br100 vif 10 address 192.0.2.1/24
+set interfaces bridge br100 vif 10 address 2001:db8::ffff/64
+set interfaces bridge br100 stp
+```
+
+Verify the configuration:
+
+```none
+vyos@vyos# show interfaces bridge br100
+ enable-vlan
+ member {
+     interface eth1 {
+         allowed-vlan 10
+     }
+     interface eth2 {
+         native-vlan 10
+     }
+ }
+ stp
+ vif 10 {
+     address 192.0.2.1/24
+     address 2001:db8::ffff/64
+ }
+```
+
+
+### Operation
+
+```{opcmd} show bridge
+
+Show the status of member interfaces for all configured bridges.
+
+:::{code-block} none
+vyos@vyos:~$ show bridge
+3: eth1: <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
+:::
+```
\ No newline at end of file
diff --git a/docs/configuration/interfaces/md-dummy.md b/docs/configuration/interfaces/md-dummy.md
new file mode 100644
index 00000000..d2d27c5d
--- /dev/null
+++ b/docs/configuration/interfaces/md-dummy.md
@@ -0,0 +1,87 @@
+---
+lastproofread: '2026-01-23'
+---
+
+(dummy-interface)=
+
+# Dummy
+
+A dummy interface is a virtual network interface that operates like the
+loopback interface, accepting traffic and routing it back to the local host.
+Unlike the loopback interface, which is limited to one per system and reserved
+for internal system use, multiple dummy interfaces can be created, removed, and
+managed without impacting core operations.
+
+As a software-based interface, the dummy interface does not depend on physical
+link state and remains active as long as the operating system is running.
+
+Dummy interfaces are commonly used in environments with multiple redundant
+uplinks (e.g., a server connected to two different switches), where assigning a
+management IP address to a specific physical interface is risky. If that
+interface fails, the management IP address becomes unreachable.
+
+Assigning the management IP address to a dummy interface and advertising it
+over all available physical links ensures the address remains reachable as long
+as at least one physical path is active.
+
+Dummy interfaces are also used for testing and simulation purposes.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address.txt
+:var0: dummy
+:var1: dum0
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: dummy
+:var1: dum0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: dummy
+:var1: dum0
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: dummy
+:var1: dum0
+```
+
+
+## Operation
+
+```{opcmd} show interfaces dummy
+
+Show brief interface information.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces dummy
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+dum0             172.18.254.201/32                 u/u
+:::
+```
+
+```{opcmd} show interfaces dummy \<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
+:::
+```
\ No newline at end of file
diff --git a/docs/configuration/interfaces/md-ethernet.md b/docs/configuration/interfaces/md-ethernet.md
new file mode 100644
index 00000000..eac0b443
--- /dev/null
+++ b/docs/configuration/interfaces/md-ethernet.md
@@ -0,0 +1,515 @@
+---
+lastproofread: '2026-01-19'
+---
+
+(ethernet-interface)=
+
+# Ethernet
+
+Ethernet interfaces (e.g., `eth0`, `eth1`) represent the host's physical
+or virtual network ports.
+
+They are the most common interface type, serving as the base layer upon which
+IP addresses, VLANs, and tunnels are configured to carry traffic across both
+LANs and WANs.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: ethernet
+:var1: eth0
+```
+
+```{cfgcmd} set interfaces ethernet \<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:
+```
+
+```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:
+```
+
+```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
+
+```{cmdincludemd} /_include/interface-eapol.txt
+:var0: ethernet
+:var1: eth0
+```
+
+#### EVPN Multihoming
+
+Uplink/core tracking.
+
+```{cmdincludemd} /_include/interface-evpn-uplink.txt
+:var0: ethernet
+:var1: eth0
+```
+
+### VLAN
+#### Regular VLANs (802.1q)
+
+```{cmdincludemd} /_include/interface-vlan-8021q.txt
+:var0: ethernet
+:var1: eth0
+```
+
+#### 802.1ad (QinQ)
+
+```{cmdincludemd} /_include/interface-vlan-8021ad.txt
+:var0: ethernet
+:var1: eth0
+```
+
+### SPAN port mirroring
+
+```{cmdincludemd} ../../_include/interface-mirror.txt
+:var0: ethernet
+:var1: eth1
+:var2: eth3
+```
+
+## Operation
+
+```{opcmd} show interfaces ethernet
+
+Show brief interface information.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces ethernet
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+eth0             172.18.201.10/24                  u/u  LAN
+eth1             172.18.202.11/24                  u/u  WAN
+eth2             -                                 u/D
+:::
+```
+
+```{opcmd} show interfaces ethernet \<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
+:::
+```
+
+```{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
+:::
+```
+
+```{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
+:::
+```
\ No newline at end of file
diff --git a/docs/configuration/interfaces/md-geneve.md b/docs/configuration/interfaces/md-geneve.md
new file mode 100644
index 00000000..1fce1119
--- /dev/null
+++ b/docs/configuration/interfaces/md-geneve.md
@@ -0,0 +1,105 @@
+---
+lastproofread: '2026-02-02'
+---
+
+(geneve-interface)=
+
+# Geneve
+
+{abbr}`Geneve (Generic Network Virtualization Encapsulation)` interfaces
+operate as virtual network ports. Administrators can apply standard network
+configurations on them, such as IP addressing, bridging, or firewall rules,
+just as they would on physical Ethernet ports.
+
+The Geneve protocol encapsulates Layer 2 Ethernet frames originating from
+endpoints such as virtual machines, containers, or physical servers inside UDP
+packets. It unifies the features of earlier encapsulation protocols, including
+VXLAN, NVGRE, and STT, and addresses their limitations, such as fixed header
+structures and a lack of metadata support. Because of its extensibility, Geneve
+may eventually replace those older protocols.
+
+Geneve tunnels are used to connect virtual switches residing within
+hypervisors, physical switches, middleboxes, and other network appliances.
+
+Geneve tunnels operate over any standard IP network. In larger deployments,
+the underlying network (underlay) is often built using a **Clos** topology,
+also known as a *leaf-and-spine* or *fat-tree* topology.
+
+Geneve header:
+
+```none
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|Ver|  Opt Len  |O|C|    Rsvd.  |          Protocol Type        |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|        Virtual Network Identifier (VNI)       |    Reserved   |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                    Variable Length Options                    |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-mac.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-mtu.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-ip.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-ipv6.txt
+:var0: geneve
+:var1: gnv0
+```
+
+
+### Geneve options
+
+```{cfgcmd} set interfaces geneve gnv0 remote \<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.
+```
\ No newline at end of file
diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md
new file mode 100644
index 00000000..9082cd80
--- /dev/null
+++ b/docs/configuration/interfaces/md-index.md
@@ -0,0 +1,26 @@
+# Interfaces
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+bonding
+bridge
+dummy
+ethernet
+geneve
+l2tpv3
+loopback
+macsec
+openvpn
+wireguard
+pppoe
+pseudo-ethernet
+sstp-client
+tunnel
+virtual-ethernet
+vti
+vxlan
+wireless
+wwan
+```
diff --git a/docs/configuration/interfaces/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md
new file mode 100644
index 00000000..324840fa
--- /dev/null
+++ b/docs/configuration/interfaces/md-l2tpv3.md
@@ -0,0 +1,170 @@
+---
+lastproofread: '2026-02-05'
+---
+
+(l2tpv3-interface)=
+
+# L2TPv3
+
+{abbr}`L2TPv3 (Layer 2 Tunneling Protocol version 3)` interfaces let you
+establish L2TPv3 tunnels to transport Layer 2 traffic over IP networks.
+
+The L2TPv3 protocol (defined in RFC 3931) wraps Layer 2 frames (e.g., Ethernet,
+Frame Relay, HDLC) within IP packets, allowing them to traverse the underlying
+IP infrastructure.
+
+Unlike L2TPv2, which strictly requires UDP encapsulation, the L2TPv3 protocol
+is more flexible and supports two encapsulation types:
+
+> - **Direct IP:** Tunnel data is encapsulated directly inside IP packets
+>   (Protocol 115) for lower overhead.
+> - **UDP:** Tunnel data is encapsulated inside a UDP datagram. This allows the
+>   tunnel to traverse NAT more easily.
+
+L2TPv3 tunnels connect geographically separated sites, serving as a simpler
+alternative to {ref}`mpls` by operating over basic IP connectivity rather than
+requiring a full MPLS infrastructure.
+
+L2TPv3 tunnels can be established over both IPv4 and IPv6 underlying networks.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-without-dhcp.txt
+:var0: l2tpv3
+:var1: l2tpeth0
+```
+
+
+### L2TPv3 options
+
+Use the following commands to configure the L2TPv3 tunnel's specific parameters.
+
+```{cfgcmd} set interfaces l2tpv3 \<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:
+
+```none
+# show interfaces l2tpv3
+l2tpv3 l2tpeth10 {
+    address 192.168.37.1/27
+    encapsulation ip
+    source-address 192.0.2.1
+    peer-session-id 100
+    peer-tunnel-id 200
+    remote 203.0.113.24
+    session-id 100
+    tunnel-id 200
+}
+```
+
+The inverse configuration must be applied to the remote peer.
+
+### L2TPv3 tunnel with UDP encapsulation
+
+The following example shows the configuration of an L2TPv3 tunnel using UDP
+encapsulation.
+
+This setup is recommended when the tunnel traverses NAT devices.
+
+Configuration notes:
+- Use a local LAN IP address as the `source-address`.
+- Configure a forwarding rule to allow tunnel traffic on the specified UDP port
+  on the upstream NAT device.
+- Use a distinct UDP port for each individual tunnel.
+
+```none
+# show interfaces l2tpv3
+l2tpv3 l2tpeth10 {
+    address 192.168.37.1/27
+    destination-port 9001
+    encapsulation udp
+    source-address 192.0.2.1
+    peer-session-id 100
+    peer-tunnel-id 200
+    remote 203.0.113.24
+    session-id 100
+    source-port 9000
+    tunnel-id 200
+}
+```
diff --git a/docs/configuration/interfaces/md-loopback.md b/docs/configuration/interfaces/md-loopback.md
new file mode 100644
index 00000000..72f14c16
--- /dev/null
+++ b/docs/configuration/interfaces/md-loopback.md
@@ -0,0 +1,67 @@
+---
+lastproofread: '2026-01-23'
+---
+
+(loopback-interface)=
+
+# Loopback
+
+The loopback interface is a virtual, software-based network interface. All
+traffic sent to it loops back and only targets services on the local host.
+
+:::{note}
+Only one loopback `lo` interface is allowed per operating system.
+If you require multiple virtual interfaces, use the {ref}`dummy-interface`
+interface type.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address.txt
+:var0: loopback
+:var1: lo
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: loopback
+:var1: lo
+```
+
+
+## Operation
+
+```{opcmd} show interfaces loopback
+
+Show brief interface information.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces loopback
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+lo               127.0.0.1/8                       u/u
+                 ::1/128
+:::
+```
+
+```{opcmd} show interfaces loopback lo
+
+Show detailed interface information.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces loopback lo
+lo: <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
+:::
+```
\ No newline at end of file
diff --git a/docs/configuration/interfaces/md-macsec.md b/docs/configuration/interfaces/md-macsec.md
new file mode 100644
index 00000000..b3c70362
--- /dev/null
+++ b/docs/configuration/interfaces/md-macsec.md
@@ -0,0 +1,319 @@
+---
+lastproofread: '2026-02-13'
+---
+
+(macsec-interface)=
+
+# MACsec
+
+MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in
+2006\. It enables protocol-independent connectivity between two hosts, providing
+data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec
+operates at the Ethernet layer as a Layer 2 protocol and secures traffic within
+Layer 2 networks, including DHCP and ARP requests. It does not compete with
+other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each
+addresses distinct use cases.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: macsec
+:var1: macsec0
+```
+
+
+### MACsec options
+
+```{cfgcmd} set interfaces macsec \<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
+```
+
+**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**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.1/24'
+set interfaces macsec macsec1 address '2001:db8::1/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4'
+set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836'
+set interfaces macsec macsec1 source-interface 'eth1'
+```
+
+**R2**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.2/24'
+set interfaces macsec macsec1 address '2001:db8::2/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4'
+set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836'
+set interfaces macsec macsec1 source-interface 'eth1'
+```
+
+Pinging (IPv6) the other host and intercepting traffic on `eth1` confirm that
+the content is encrypted.
+
+```none
+17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150:
+        0x0000:  2c00 0000 000a 0050 56bf efaa 0001 d9fb  ,......PV.......
+        0x0010:  920a 8b8d 68ed 9609 29dd e767 25a4 4466  ....h...)..g%.Df
+        0x0020:  5293 487b 9990 8517 3b15 22c7 ea5c ac83  R.H{....;."..\..
+        0x0030:  4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09  Ln...C..,NiN....
+        0x0040:  0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb  .w]S.u..T..Z.f..
+        0x0050:  c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b  ..n#..m.2..X...;
+        0x0060:  4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669  M..X...../..1..i
+        0x0070:  e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e  .:.8.b..(Wj.....
+        0x0080:  6b30 92a5 7ccc 720b                      k0..|.r.
+```
+
+Disabling encryption on the MACsec interface by removing the `security
+encrypt` option shows the unencrypted but authenticated content.
+
+```none
+17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150:
+        0x0000:  2000 0000 0009 0050 56bf efaa 0001 86dd  .......PV.......
+        0x0010:  6009 86f3 0040 3a40 2001 0db8 0000 0000  `....@:@........
+        0x0020:  0000 0000 0000 0001 2001 0db8 0000 0000  ................
+        0x0030:  0000 0000 0000 0002 8100 d977 0f30 0003  ...........w.0..
+        0x0040:  1ca0 c65e 0000 0000 8d93 0b00 0000 0000  ...^............
+        0x0050:  1011 1213 1415 1617 1819 1a1b 1c1d 1e1f  ................
+        0x0060:  2021 2223 2425 2627 2829 2a2b 2c2d 2e2f  .!"#$%&'()*+,-./
+        0x0070:  3031 3233 3435 3637 87d5 eed3 3a39 d52b  01234567....:9.+
+        0x0080:  a282 c842 5254 ef28                      ...BRT.(
+```
+
+**Site-to-site MACsec with static SAK over an untrusted network**
+
+This example uses the same topology as above, but applies static SAK mode to
+the MACsec interface configuration.
+
+**R1**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.1/24'
+set interfaces macsec macsec1 address '2001:db8::1/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02
+set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
+set interfaces macsec macsec1 source-interface 'eth1'
+```
+
+**R2**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.2/24'
+set interfaces macsec macsec1 address '2001:db8::2/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
+set interfaces macsec macsec1 security static peer R1 mac 00:11:22:33:44:01
+set interfaces macsec macsec1 security static peer R1 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+set interfaces macsec macsec1 source-interface 'eth1'
+```
+
+## MACsec over WAN
+
+MACsec offers an alternative to traditional tunneling solutions by securing
+Layer 2 with integrity, origin authentication, and optional encryption.
+
+While typically deployed between hosts and access switches, MACsec can also
+secure traffic over a WAN. In the following example, we combine VXLAN (for
+transport) and MACsec (for security) to create a secure tunnel between two
+sites.
+
+**R1 MACsec01**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.1/24'
+set interfaces macsec macsec1 address '2001:db8::1/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
+set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02'
+set interfaces macsec macsec1 source-interface 'vxlan1'
+set interfaces vxlan vxlan1 mac '00:11:22:33:44:01'
+set interfaces vxlan vxlan1 remote '10.1.3.3'
+set interfaces vxlan vxlan1 source-address '172.16.100.1'
+set interfaces vxlan vxlan1 vni '10'
+set protocols static route 10.1.3.3/32 next-hop 172.16.100.2
+```
+
+**R2 MACsec02**
+
+```none
+set interfaces macsec macsec1 address '192.0.2.2/24'
+set interfaces macsec macsec1 address '2001:db8::2/64'
+set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+set interfaces macsec macsec1 security encrypt
+set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
+set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01'
+set interfaces macsec macsec1 source-interface 'vxlan1'
+set interfaces vxlan vxlan1 mac '00:11:22:33:44:02'
+set interfaces vxlan vxlan1 remote '10.1.2.2'
+set interfaces vxlan vxlan1 source-address '172.16.100.2'
+set interfaces vxlan vxlan1 vni '10'
+set protocols static route 10.1.2.2/32 next-hop 172.16.100.1
+```
diff --git a/docs/configuration/interfaces/md-openvpn-examples.md b/docs/configuration/interfaces/md-openvpn-examples.md
new file mode 100644
index 00000000..1eb697c4
--- /dev/null
+++ b/docs/configuration/interfaces/md-openvpn-examples.md
@@ -0,0 +1,855 @@
+# Site-to-site
+
+<div class="todo">
+
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+
+</div>
+
+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>
+<img src="/_static/images/openvpn_site2site_diagram.webp" />
+</figure>
+
+## 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.
+
+``` none
+vyos@vyos# run generate pki certificate self-signed install openvpn-local
+Enter private key type: [rsa, dsa, ec] (Default: rsa) ec
+Enter private key bits: (Default: 256)
+Enter country code: (Default: GB)
+Enter state: (Default: Some-State)
+Enter locality: (Default: Some-City)
+Enter organization name: (Default: VyOS)
+Enter common name: (Default: vyos.io)
+Do you want to configure Subject Alternative Names? [y/N]
+Enter how many days certificate will be valid: (Default: 365)
+Enter certificate type: (client, server) (Default: server)
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N]
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+
+vyos@vyos# compare
+[pki]
++ certificate openvpn-local {
++     certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg=="
++     private {
++         key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW"
++     }
++ }
+
+[edit]
+
+vyos@vyos# commit
+```
+
+You do **not** need to copy the certificate to the other router. Instead,
+retrieve its SHA-256 fingerprint. Since OpenVPN currently supports only SHA-256
+fingerprints, use the following command:
+
+``` none
+vyos@vyos# run show pki certificate openvpn-local fingerprint sha256
+5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79
+```
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+Certificate names are arbitrary. While `openvpn-local` and
+`openvpn-remote` are used here, you may choose any names.
+
+</div>
+
+Repeat the procedure on the other router.
+
+## Set up site-to-site OpenVPN
+
+Local configuration:
+
+``` none
+Configure the tunnel:
+
+set interfaces openvpn vtun1 mode site-to-site
+set interfaces openvpn vtun1 protocol udp
+set interfaces openvpn vtun1 persistent-tunnel
+set interfaces openvpn vtun1 remote-host '203.0.113.11'                         # Public IP of the other side
+set interfaces openvpn vtun1 local-port '1195'
+set interfaces openvpn vtun1 remote-port '1195'
+set interfaces openvpn vtun1 local-address '10.255.1.1'                         # Local IP of vtun interface
+set interfaces openvpn vtun1 remote-address '10.255.1.2'                        # Remote IP of vtun interface
+set interfaces openvpn vtun1 tls certificate 'openvpn-local'                    # The self-signed certificate
+set interfaces openvpn vtun1 tls peer-fingerprint <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:
+
+``` 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
+```
+
+## 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`.
+
+``` none
+vyos@local# run generate pki openvpn shared-secret install s2s
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+vyos@local# compare
+[pki openvpn shared-secret]
++ s2s {
++     key   "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3"
++     version "1"
++ }
+
+[edit]
+
+vyos@local# commit
+[edit]
+```
+
+Next, install the key on the remote router:
+
+``` none
+vyos@remote# set pki openvpn shared-secret s2s key <generated key string>
+```
+
+Finally, configure the key in your OpenVPN interface settings:
+
+``` none
+set interfaces openvpn vtun1 shared-secret-key s2s
+```
+
+## Set up firewall exceptions
+
+To allow OpenVPN traffic to pass through the WAN interface, create a firewall
+exception:
+
+``` none
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 action 'accept'
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related'
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'established'
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'related'
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 action 'accept'
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 description 'OpenVPN_IN'
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port '1195'
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 log
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol 'udp'
+```
+
+Apply the OUTSIDE_LOCAL firewall group to the WAN interface and to the input
+filter for traffic destined for the router itself:
+
+``` none
+set firewall ipv4 input filter rule 10 action 'jump'
+set firewall ipv4 input filter rule 10 inbound-interface name eth0
+set firewall ipv4 input filter rule 10 jump-target OUTSIDE_LOCAL
+```
+
+Static routing:
+
+Configure static routes by referencing the tunnel interface. For example, if
+the local router's network is `10.0.0.0/16` and the remote router's network
+is `10.1.0.0/16`, define the routes as follows:
+
+Local configuration:
+
+``` none
+set protocols static route 10.1.0.0/16 interface vtun1
+```
+
+Remote configuration:
+
+``` none
+set protocols static route 10.0.0.0/16 interface vtun1
+```
+
+As with standard Ethernet interfaces, you can apply firewall policies to the
+tunnel interface for input, output, and forward directions.
+
+If you use multiple tunnels, OpenVPN must distinguish between them beyond just
+the pre-shared key. To achieve this, assign either unique IP addresses or
+unique ports to each tunnel.
+
+Verify OpenVPN status using the show openvpn operational commands.
+
+``` none
+vyos@vyos:~$ show openvpn site-to-site
+
+OpenVPN status on vtun1
+
+Client CN    Remote Host        Tunnel IP    Local Host    TX bytes    RX bytes    Connected Since
+-----------  -----------------  -----------  ------------  ----------  ----------  -----------------
+N/A          10.110.12.54:1195  N/A          N/A           504.0 B     656.0 B     N/A
+```
+
+# Server-client
+
+In OpenVPN’s server-client mode, the server acts as a central hub, allowing
+multiple clients to connect and securely route their traffic or access a
+private network. Multi-client server is the most popular OpenVPN mode for
+routers.
+
+## Set up server-client certificates
+
+Server-client mode always uses x.509 authentication and therefore requires a
+PKI setup. The PKI utility now simplifies the creation of Certificate
+Authorities (CAs), server and client certificates, and Diffie-Hellman keys
+directly in VyOS using configuration or operational mode commands.
+
+On the server, generate all certificates by running the following commands in
+configuration mode. The certificates will be added to the configuration
+session's PKI subtree.
+
+Certificate Authority (CA):
+
+``` none
+vyos@vyos# run generate pki ca install ca-1
+Enter private key type: [rsa, dsa, ec] (Default: rsa)
+Enter private key bits: (Default: 2048)
+Enter country code: (Default: GB)
+Enter state: (Default: Some-State)
+Enter locality: (Default: Some-City)
+Enter organization name: (Default: VyOS)
+Enter common name: (Default: vyos.io) ca-1
+Enter how many days certificate will be valid: (Default: 1825)
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N]
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+vyos@vyos# compare
+[pki]
++ ca ca-1 {
++     certificate "MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4EFgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZzph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHwY6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZWXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyxzRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55YmtmctGO2o+NBCFi0="
++     private {
++         key "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAECggEAZdykF6wV8Z4n8NsoG4j8E/ZJbWEhWjO3x1y3JNutJw735LhmmysMSsreToXtxGfgYRTgNwt5l7oHoqmGHCsLxO1NBb5A7JBllIkIwUYqn31syOJofg0NsJpuwZ2zVLfvWe5mGg4tV2lvVPNEWXWwbp+Ow2KLcFWXkA+H8tFuW6F2mH3ntYlIi/WiCNjsEotNx8Kk7OVwt43DbkN/rbF5lxquuLedaSspOHuhIAOfZB5ZySfqohQalSAaguVD66rGPMrerZ2Vc7B1iJ6Mn/KZrSaQeHwyWrwDDHdzVwG9waydevtGTVO0dvH4etWnRypDx8p1FPJJKD4XVcsl3rR6oQKBgQD497Ep2RJcbNnKVj+kNXGriSGmyRSp6CL61KotepzgucK0RtGMeFJge56/otMHMAxIOcDMX6vRn2MB2pqVqwqUBQy6JfLrSemdpIjMN9xlX6Dw3BWP39SdewZ896/Eo0Q1ythMj1ORp+u3PqOlSa14Cy9aPwDWmNy2deD68YDnsQKBgQDpZE/T84BMQ0FzL6NRijZRzR6Dc775hRfmmSTYI0KqpG0gXNSc5UgrWSLN5H7fnx36mT01P7UkgXCInV0AlJOfkt4a8QTqM1Fh/rZbLLWpQE55S6Fs28GDiFYl2kvZT/TtxhA/E0POf/YXl/8KITS7ZVAZxE8rxBe1hVUfDbnlCwKBgQDeWUguGaGeTdCMNk8MNnbYPdaCAB+mRp3G6ls51sF4qi5Lltva2jKn3H/AoohZaP3vGzUm0WLACdsAct2QQXtnCsN9FBtJK2+qzKEn0dPR7X/s3IGdRse6BX+b6BFgSnfGmuxmI7L86L1JoHXCTnTQOx0FOjNjdI3ZnplZRIpdYQKBgFJacASU9l9yl+SiGZnLEDG7FBpEPE3lVbKrtSGDB6IY1NzHhMo76URKdop6Jv6XMcfcTIm+ihdwiRnblRaAVrrG4xJUm2xcYUoXy5bOZudq5oXMVxCHVngoImXG6l6q5P0Fl3P6Q0HZSye2HWsgnm/FZwdAisMhtU/61TdY65BTAoGBAM4jKeImiXta5lz1RgNiW/TPhft3UbOLj3TbzchNCNAamqCv4Tmh9YKB2d/mz2hNxbnAGe2cYn4iRYKcjJLMZ0UfBL2WxlrgQYQPPGzSD0fH1pLIXPohpBZpsGqNR3Nc8Jd+Uw3IiIJ2oxPCOPTOJsklNB0Xf1AlUUagB16bhhZZ"
++     }
++ }
+
+[edit]
+vyos@vyos# commit
+```
+
+Server certificate:
+
+``` none
+vyos@vyos# run generate pki certificate sign ca-1 install srv-1
+Do you already have a certificate request? [y/N] N
+Enter private key type: [rsa, dsa, ec] (Default: rsa)
+Enter private key bits: (Default: 2048)
+Enter country code: (Default: GB)
+Enter state: (Default: Some-State)
+Enter locality: (Default: Some-City)
+Enter organization name: (Default: VyOS)
+Enter common name: (Default: vyos.io) srv-1
+Do you want to configure Subject Alternative Names? [y/N]
+Enter how many days certificate will be valid: (Default: 365)
+Enter certificate type: (client, server) (Default: server) server
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N]
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+vyos@vyos# compare
+[pki certificate]
++ srv-1 {
++     certificate "MIIDrDCCApSgAwIBAgIULpu+qZjfG01kUI58XNmqXbQC3qQwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTMxMDJaFw0yNjA2MTExMTMxMDJaMFUxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDjAMBgNVBAMMBXNydi0xMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAysTrMfVH63aVidJT7bIf+zLwkLse07nGsv4aliGEbufr239RBHV4Jn8LbQ+nB/8mhYGjNY4OnZ7NYz3FU/iglo8qFtaZ26mWtPWpv2xW1F8JAEK7l5BAg42cBucxiIZFeRm+jkE6VN1bcNU0utnn3sbCwZMyH6pS9k08G1qrrFLA7ZFhv5AmgJcODmO8sigSAu7rRS/6O3eO6ICnVjvIfHLb+9DKKUEffHzFV8RrkqVCGmgisz9fF+j1Rvg9s+ylNc2lZJTbb1XnzixvSRro4t9I3uIWdpJ0iOu09YiTXGQgH9ER6V3rFiX00RdSiSXf+MJCV64hC1msg+8V3Nrw9QIDAQABo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUzH0h4vBxma89HF9rUQ+DW052c5swHwYDVR0jBBgwFoAUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAI/Cyd0y7AJ7wY3yRssCud2iJAl9/ZjgxzXOUo6ibawYIYOnSf9tS3eD4CIH4BgppDXoJZ/qEA4WvIsLx3yvnyOxiqyk3TQmKIZ27VJH+yQkgzPeiKrHn1pCXBKEb1/jlT8Ozu4Lmn/oFwDH6nk8toxI8DM+qsTxqUFlTA3ea9yaRtxeNPMWJdaxZSUYGVSZL0wVKw5ZuQ1Gn7vGVApWlYDKYbMozCuZUG1q8wMzFBRa7x0anvh5hM4bksLz+Y1ujCS8f8b4Xtb8KIdFrZtTvtl97crv62bN05VueAcbwtYbIBNWNoT/CvmqV7k3uPg95GYSNddFqEMbQHoyd8hdDCo="
++     private {
++         key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDKxOsx9UfrdpWJ0lPtsh/7MvCQux7Tucay/hqWIYRu5+vbf1EEdXgmfwttD6cH/yaFgaM1jg6dns1jPcVT+KCWjyoW1pnbqZa09am/bFbUXwkAQruXkECDjZwG5zGIhkV5Gb6OQTpU3Vtw1TS62efexsLBkzIfqlL2TTwbWqusUsDtkWG/kCaAlw4OY7yyKBIC7utFL/o7d47ogKdWO8h8ctv70MopQR98fMVXxGuSpUIaaCKzP18X6PVG+D2z7KU1zaVklNtvVefOLG9JGuji30je4hZ2knSI67T1iJNcZCAf0RHpXesWJfTRF1KJJd/4wkJXriELWayD7xXc2vD1AgMBAAECggEACsUk3PVzSX11+ekTDigM7NHK11UpEQPoGu/GR70mBKIK9BCyI/N9W0YaPEO9kn4p9KNrINgXzKV3sVLBnXEyTmzyRl5Fs9YxLBF0X7eIcSVPHBVvU2CVHKez5uX2ypKfNAx7A6FRUNqlFbwtXdNfLoUOKSwBWI86ctytWaKaRb/TTSGQkaP/z/cwIsXOLfG9m6iFkw98ShUzalrUWNo/4fJKlO1+DvXVYE9sv9rjD8J7DtAbr5KykQ5n0AAlZTCWQ7jwMybSnjjY9ypZUms0l17raJrfhrdbWayc6xMDvtrmNIDebkF+J7cHU06aEV+yQXV/7yjyZgUSM2ANcHMdzQKBgQDmTi5tUeaj1JUSl9lAP/XUzcElw2tcU1B8qpX69J4ofjTNgj5okLWQZVIy1UyAfLOI3LJbHTBUtSvedhH0VaMulq99NXs5qnbPGG3//RBAc0wKhJknB5Qv0D3FxMI14kMO6jzPly+aIGEk4dTtHvZuHbbVHbKSZ5MMouLyT+SS7wKBgQDhZETARZ0MazeWRaPJwdkjlfNcqqcsnDicdcppCkcDCjeLxkVPZc8ej37rshOvw2Pf1D0PddGyOhJoWCWA8QE2LQoDHLaDnQ0L6aQ3yjN5Gxx9RCDFi3Zuat/mPcv3tFO7uUmeYvRC5fGYrghq29NADmUefOopAc06Izd4A3iqWwKBgQC1uPrpR7a1jwgRo7/I8q8HO1MseQY903+u3ut5GYuyZ+NCRYL4/zZEua4ibivvNnZzh7E0M9PvAwWag4+nO+uG11+hbJHO7rLQtnYVh5lLQa6+neI66cAD+kzDwH1+BwriufFB3Amzk9kTQR7B+6x3NvsNLmG5JADj96Mbj+7MAQKBgFIevEXplyzdK6WevexWqoyip8aNjtdcG+w1pofa7MCYymAs3zfseihCVBYADdguModsxsqJPNvY+Lf31cJDDRP2GP3FSmJtqEE84U5KZ7KqRBkH54DSLVZRrj4vKc+YbiGpgr8ogqKVMQ9V6U81xKREGmefT5mdRG74Qc+CREadAoGAFtdsH5js1yFEeGFad4BZJ69grEavD3pNCfIe9oIPtXvvFdzxd+QbKgqFf3JMJp/HYi8A0iv/i4mzf00KXzF4JU7bIJYrUVlk/w8x77gzDRIphsPqpMBJkTI0jisQHZKWNEe7IbmM/dWW2S4jvCkrhB7F5Szf72Q+j/lPbfx2g/8="
++     }
++ }
+
+[edit]
+vyos@vyos# commit
+```
+
+Diffie-Hellman key:
+
+``` none
+vyos@vyos# run generate pki dh install dh-1
+Enter DH parameters key size: (Default: 2048)
+Generating parameters...
+1 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+vyos@vyos# compare
+[pki]
++ dh dh-1 {
++     parameters "MIIBCAKCAQEAp25kxwZeLZ7wcbRii5E5RD4uWCUOBxarzKEE0msa84omh5nZ9dv/4bfJw4gIXlA2+sGc2lLV/jajZminMryiSwJdisyVuUdOB7sJWZwrzHBAY0qFbNyaRMVJBar2xVm+XcKd3A2eNTEgn10G7rPPvf6CJ5isUKFaKT8ymUv+mI0upLneYdGs8/yS3sAojzeulCf49fa5SiaGCcZZkdOI3Nby1u/ZG4okqJ2wE2c2hRVLs1k5qrrono0OF4Dh0B91ihnywRfp1xPYeqpiln+OPh+PPgTuBxkz4VxwRDoQ+NhVr/LOCb3vbhnyFisxI0w4r3109cA3QiDmo1L14aKl1wIBAg=="
++ }
+
+[edit]
+vyos@vyos# commit
+```
+
+Client certificate:
+
+``` none
+vyos@vyos:~$  generate pki certificate sign ca-1 install client1
+Do you already have a certificate request? [y/N] N
+Enter private key type: [rsa, dsa, ec] (Default: rsa)
+Enter private key bits: (Default: 2048)
+Enter country code: (Default: GB)
+Enter state: (Default: Some-State)
+Enter locality: (Default: Some-City)
+Enter organization name: (Default: VyOS)
+Enter common name: (Default: vyos.io) client1
+Do you want to configure Subject Alternative Names? [y/N]
+Enter how many days certificate will be valid: (Default: 365)
+Enter certificate type: (client, server) (Default: server) client
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N]
+You are not in configure mode, commands to install manually from configure mode:
+set pki certificate client1 certificate 'MIIDrjCCApagAwIBAgIUPvtffeYTdoOiHxu++wdrjHwwVX4wDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTQxMDlaFw0yNjA2MTExMTQxMDlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQnUyqEzG+AqZzsdSud5MDqsOxiXTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTANBgkqhkiG9w0BAQsFAAOCAQEAplItvZpoX/joG3QREu9tHVKwDTmXB2lwUM5G8iKPgd6D6oOILZMe2KuvWt12dcdEzUCGfJwJJ8M8R2WD0OmcLdFqvM/8UM1hYzUP2BCnFCLtElVD+b4wMlQNpdHqNbdckw8J4MLQlhUgu9rZAZ0XjWCprr+U50bX++vYRw7Un3Ds6ETEvjflm5WAPb2e0V1hhISPl8K+VXO7RAwxy0DHcDuR+YaD+hnNgMsJV3/QwA17Iy8x86RpOgqmesbt0U7e9Rmo81aVgiy/V4OCV7u6bPX03fmZNS8UwwJuRUlxkjO+epHNYB2cnOcjSkUxaIJ9Hv3tMWHQEtbVZsNYSOZozw=='
+set pki certificate client1 private key 'MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAECggEAPS/Fhtt5k2BgFivZW3FcVc+OS0keGwV8hkFsGoXTZIKEIzSFWIn/mX0CUY90C0Rn9MRwiqB4PwssOAsHY6QQjdRK8irRbVK8l2ZeydHC7DfVUdXtKR0YnxTaePML3nTV/TqPF14Rx6EINtHrkLeBbu2DhGsKfhoHIoTVbvUiKLHa2TkGJOkhvjsyMSPKzUXa1AzLmu+UBIhRYpEPHj0SQUUJJnKgIb7mTR2fhJScHcKwsrPq6S8OpChvsYZ6zatgrTFz9tuhD4IjL7NBiYP45BwGaLIaQjph8yAJwwHWoOP+TTj5WYflkW6Uu8F9gC0ve6dPGPNEi2TUdirvAe4LYQKBgQD0UfAPm6tQg8pdkvfMBvYc21fk8zqmgcA4OtvDi60aXuv5jI5+faISvOG2JLuFhKIDOb5ZerzGvkN+LvWgzr9H7YdGZNNtwKgpS/MGqcuuHncTxWBAwYgKhf26a/tqFZRNurJ6GowxDiAcQEc1mWnmdngRa+dvvCwNbXvGVqfVEQKBgQDGKi447TqD76QfvRPn/fRSjM+QE1duk+XorEJ0HHIha5HV9kCrZdV/olGRjDLwPJO6JW7iE2FUsS9SsIrccFE/9P2ZUqfYP2wL5vNO5kAmoLLUl0gwqg1WnBTPJfXeKReTj2uGmOdEuuMPXpL/49hDuPViiE2Q4MGe2Z+oEYN/EwKBgHfQMuTEl2e9qaDn8OM6SrluC5V4fjunh6dLnfgwaCx1fk1702lOnQuJWzsiml9o4raoO6PP4AGqzphz2PsKSJ2ya1NnIJRDFXRjDYQoAn2Z7RViBsja36chfINObxXgDUFtHBdrK3LnFXIlR4aOfHOLh2grvWx7IDNZjIiAeH+xAoGAJlmFZnjqiRv4bDgAQTZRcSRVCvHjSsAOj0++8I+MutEBgSHN9B2aCsBT/tHeDcX7ZNvXsKLFhElh+iO2S+DkqHb2GRT47I2hkFAaqBtBMPiKgz/ftaNDP46nLEuRYHQdXu4zhfHTV+a/CHtqAWGLuddyjaYJNM96SQ6eqjzxcMcCgYAzdxOF2e27hIgo2ttjsROMGqW0/0r/HsKGKPnao7xHQNCAswTnBT+QGugPCe0NXjuxbySP7V1GeWMWF+WV5khtteWerT1/ELAC48NSDpaMxVa4GP8Q/0w6+ZyJty3UGbCYQzZZue81dU+42LUIaVJ4NAc2tYj3jD780udasawS6w=='
+```
+
+Manually copy the CA, client certificate, and Diffie-Hellman key to the client
+device, then commit them before configuring the OpenVPN interface.
+
+For more options, refer to `configuration/pki/index:pki`.
+
+## Set up server-client OpenVPN
+
+The following example demonstrates the most complicated scenario: each client
+acts as a router with its own subnet (e.g., an HQ and multiple branch offices).
+Simpler setups are subsets of it.
+
+In this scenario, the 10.23.1.0/24 network is used for client tunnel endpoints,
+and all client subnets belong to 10.23.0.0/20. Each client needs access to the
+192.168.0.0/16 network.
+
+Server configuration:
+
+``` none
+set interfaces openvpn vtun10 encryption data-ciphers 'aes256'
+set interfaces openvpn vtun10 hash 'sha512'
+set interfaces openvpn vtun10 local-host '172.18.201.10'
+set interfaces openvpn vtun10 local-port '1194'
+set interfaces openvpn vtun10 mode 'server'
+set interfaces openvpn vtun10 persistent-tunnel
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 server client client1 ip '10.23.1.10'
+set interfaces openvpn vtun10 server client client1 subnet '10.23.2.0/25'
+set interfaces openvpn vtun10 server domain-name 'vyos.net'
+set interfaces openvpn vtun10 server max-connections '250'
+set interfaces openvpn vtun10 server name-server '172.16.254.30'
+set interfaces openvpn vtun10 server subnet '10.23.1.0/24'
+set interfaces openvpn vtun10 server topology 'subnet'
+set interfaces openvpn vtun10 tls ca-certificate ca-1
+set interfaces openvpn vtun10 tls certificate srv-1
+set interfaces openvpn vtun10 tls dh-params dh-1
+```
+
+The configuration above uses the default 1194/UDP port, 256-bit AES encryption,
+SHA-512 for HMAC authentication, and the persistent-tunnel option.
+Persistent-tunnel is recommended as it keeps the TUN/TAP device active during
+connection resets or daemon reloads. Clients are identified by the CN attribute
+in their SSL certificates.
+
+To grant clients access to a specific network behind the router, use the
+push-route option to automatically install the appropriate route on each client.
+
+``` none
+set interfaces openvpn vtun10 server push-route 192.168.0.0/16
+```
+
+OpenVPN does not automatically create kernel routes for client subnets when
+clients connect; it only uses client-subnet association internally. Therefore,
+you must manually create a route to the 10.23.0.0/20 network:
+
+``` none
+set protocols static route 10.23.0.0/20 interface vtun10
+```
+
+## Set up OpenVPN client
+
+VyOS can operate not only as an OpenVPN site-to-site peer or a server for
+multiple clients, but also as an OpenVPN client. Any VyOS OpenVPN interface
+can be configured to connect to another VyOS or third-party OpenVPN server.
+
+Client configuration:
+
+``` none
+set interfaces openvpn vtun10 encryption data-ciphers 'aes256'
+set interfaces openvpn vtun10 hash 'sha512'
+set interfaces openvpn vtun10 mode 'client'
+set interfaces openvpn vtun10 persistent-tunnel
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 remote-host '172.18.201.10'
+set interfaces openvpn vtun10 remote-port '1194'
+set interfaces openvpn vtun10 tls ca-certificate ca-1
+set interfaces openvpn vtun10 tls certificate client1
+```
+
+## Verification
+
+Check the tunnel status:
+
+``` none
+vyos@vyos:~$ show openvpn server
+
+OpenVPN status on vtun10
+
+Client CN    Remote Host         Tunnel IP    Local Host        TX bytes    RX bytes    Connected Since
+-----------  ------------------  -----------  ----------------  ----------  ----------  -------------------
+client1      172.16.12.54:33166  10.23.1.10   172.18.201.10:1194  3.4 KB      3.4 KB      2024-06-11 12:07:25
+```
+
+# Server bridge
+
+In Ethernet bridging configurations, an OpenVPN interface operating in server
+mode with the device type set to TAP can be added to a bridge. By encapsulating
+entire Ethernet frames (up to 1514 bytes) rather than just IP packets (up to
+1500 bytes), this setup enables clients to transmit Layer 2 frames through the
+OpenVPN tunnel.
+
+The following is a basic configuration example:
+
+Server side:
+
+``` none
+set interfaces bridge br10 member interface eth1.10
+set interfaces bridge br10 member interface vtun10
+set interfaces openvpn vtun10 device-type 'tap'
+set interfaces openvpn vtun10 encryption data-ciphers 'aes192'
+set interfaces openvpn vtun10 hash 'sha256'
+set interfaces openvpn vtun10 local-host '172.18.201.10'
+set interfaces openvpn vtun10 local-port '1194'
+set interfaces openvpn vtun10 mode 'server'
+set interfaces openvpn vtun10 server bridge gateway '10.10.0.1'
+set interfaces openvpn vtun10 server bridge start '10.10.0.100'
+set interfaces openvpn vtun10 server bridge stop '10.10.0.200'
+set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0'
+set interfaces openvpn vtun10 server topology 'subnet'
+set interfaces openvpn vtun10 tls ca-certificate 'ca-1'
+set interfaces openvpn vtun10 tls certificate 'srv-1'
+set interfaces openvpn vtun10 tls dh-params 'dh-1'
+```
+
+Client side:
+
+``` none
+set interfaces openvpn vtun10 device-type 'tap'
+set interfaces openvpn vtun10 encryption data-ciphers 'aes192'
+set interfaces openvpn vtun10 hash 'sha256'
+set interfaces openvpn vtun10 mode 'client'
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 remote-host '172.18.201.10'
+set interfaces openvpn vtun10 remote-port '1194'
+set interfaces openvpn vtun10 tls ca-certificate 'ca-1'
+set interfaces openvpn vtun10 tls certificate 'client-1'
+```
+
+# Server LDAP authentication
+
+## LDAP
+
+Enterprise installations usually include a directory service to centralize
+employee password management. VyOS and OpenVPN support using LDAP and Active
+Directory as a single user backend.
+
+Authentication is performed by the `openvpn-auth-ldap.so` plugin, included
+with every VyOS installation. To use it, you must create a dedicated
+configuration file.
+
+**Best practice:** Store the configuration file in the `/config` directory
+to ensure it is preserved after image updates.
+
+``` none
+set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config"
+```
+
+A sample configuration file is shown below:
+
+``` none
+<LDAP>
+# 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:
+
+``` none
+<LDAP>
+  # LDAP server URL
+  URL ldap://dc01.example.com
+  # Bind DN (If your LDAP server doesn’t support anonymous binds)
+  BindDN CN=LDAPUser,DC=example,DC=com
+  # Bind Password
+  Password mysecretpassword
+  # Network timeout (in seconds)
+  Timeout  15
+  # Enable Start TLS
+  TLSEnable no
+  # Follow LDAP Referrals (anonymously)
+  FollowReferrals no
+</LDAP>
+
+<Authorization>
+  # Base DN
+  BaseDN        "DC=example,DC=com"
+  # User Search Filter, user must be a member of the VPN AD group
+  SearchFilter  "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))"
+  # Require Group Membership
+  RequireGroup    false # already handled by SearchFilter
+  <Group>
+    BaseDN        "OU=Groups,DC=example,DC=com"
+    SearchFilter  "(|(cn=VPN))"
+    MemberAttribute  memberOf
+  </Group>
+</Authorization>
+```
+
+If you only want to check that the user account is enabled and can authenticate
+(against the primary group), the following snippet is sufficient:
+
+``` 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:
+
+``` none
+vyos@vyos# show interfaces openvpn
+ openvpn vtun0 {
+     mode server
+     openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix"
+     openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config"
+     openvpn-option "--push redirect-gateway"
+     openvpn-option --duplicate-cn
+     openvpn-option "--verify-client-cert none"
+     openvpn-option --comp-lzo
+     openvpn-option --persist-key
+     openvpn-option --persist-tun
+     server {
+         domain-name example.com
+         max-connections 5
+         name-server 203.0.113.0.10
+         name-server 198.51.100.3
+         subnet 172.18.100.128/29
+     }
+     tls {
+         ca-certificate ca.crt
+         certificate server.crt
+         dh-params dh1024.pem
+     }
+ }
+```
+
+For a detailed example, refer to `OpenVPN with LDAP </configexamples/autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP>`.
+
+# Multi-factor authentication
+
+VyOS supports multi-factor authentication (MFA) or two-factor authentication
+using Time-based One-Time Passwords (TOTP). It is compatible with Google
+Authenticator and other software tokens.
+
+## Server side
+
+``` none
+set interfaces openvpn vtun20 encryption cipher 'aes256'
+set interfaces openvpn vtun20 hash 'sha512'
+set interfaces openvpn vtun20 mode 'server'
+set interfaces openvpn vtun20 persistent-tunnel
+set interfaces openvpn vtun20 server client user1
+set interfaces openvpn vtun20 server mfa totp challenge 'disable'
+set interfaces openvpn vtun20 server subnet '10.10.2.0/24'
+set interfaces openvpn vtun20 server topology 'subnet'
+set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20'
+set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20'
+set interfaces openvpn vtun20 tls dh-params 'dh-pem'
+```
+
+A TOTP secret is created for each client in the OpenVPN server configuration.
+To display authentication information, use the following command:
+`show interfaces openvpn vtun20 user user1 mfa qrcode`.
+
+Example:
+
+``` none
+vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode
+█████████████████████████████████████
+█████████████████████████████████████
+████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████
+████ █   █ █▀▀▄ █▀▀▀█▀██ █ █   █ ████
+████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████
+████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████
+████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████
+████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████
+████ ▄█▀▀▄▄  ▄█▀  ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████
+████▄█ ▀▄▄▄▀  ▀ ▄█ ▄ █▄█▀ █▀  █▀█████
+████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀  ▀ ▀ ▄█▀████
+████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█  █▀██▀████
+████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████
+████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀  █▄█ ██▀█████
+████ █   █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄   ████
+████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████
+████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████
+█████████████████████████████████████
+█████████████████████████████████████
+```
+
+Scan the QR code to add the user account to Google Authenticator. On the client
+side, use the generated OTP as the password.
+
+# Authentication with username/password
+
+An OpenVPN server can securely obtain a username and password from a connecting
+client and use this information for authentication.
+
+First, configure the server to use an authentication plugin or script. The
+server calls this plugin every time a client tries to connect, passing it the
+client's credentials.
+
+In the following example, the `--auth-user-pass-verify` directive is used
+with the via-env method and a specified script path to validate the client's
+username and password.
+
+## Server configuration
+
+``` none
+set interfaces openvpn vtun10 local-port '1194'
+set interfaces openvpn vtun10 mode 'server'
+set interfaces openvpn vtun10 openvpn-option '--auth-user-pass-verify /config/auth/check_user.sh via-env'
+set interfaces openvpn vtun10 openvpn-option '--script-security 3'
+set interfaces openvpn vtun10 persistent-tunnel
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 server client client-1 ip '10.10.10.55'
+set interfaces openvpn vtun10 server push-route 192.0.2.0/24
+set interfaces openvpn vtun10 server subnet '10.10.10.0/24'
+set interfaces openvpn vtun10 server topology 'subnet'
+set interfaces openvpn vtun10 tls ca-certificate 'ca-1'
+set interfaces openvpn vtun10 tls certificate 'srv-1'
+set interfaces openvpn vtun10 tls dh-params 'dh-1'
+```
+
+The /config/auth/check_user.sh example includes two test users:
+
+``` none
+#!/bin/bash
+USERNAME="$username"
+PASSWORD="$password"
+
+# Replace this with real user checking logic or use getent
+if [[ "$USERNAME" == "client1" && "$PASSWORD" == "pass123" ]]; then
+    exit 0
+elif [[ "$USERNAME" == "peter" && "$PASSWORD" == "qwerty" ]]; then
+    exit 0
+else
+    exit 1
+fi
+```
+
+## Client configuration
+
+Storing the client certificate locally lets you generate the OpenVPN client
+configuration file. Use the following command:
+
+``` none
+vyos@vyos:~$ generate openvpn client-config interface vtun10 ca ca-1 certificate client1
+```
+
+Copy the output and save it as a .ovpn file. Add the `auth-user-pass`
+directive to the file. This instructs the OpenVPN client to prompt the user
+for a username and password, which are then sent to the server over the TLS
+channel. You can now import this file into any OpenVPN client application.
+
+``` none
+client
+dev tun
+proto udp
+remote 192.168.77.10 1194
+
+remote-cert-tls server
+proto udp
+dev tun
+dev-type tun
+persist-key
+persist-tun
+verb 3
+auth-user-pass
+
+
+<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/md-openvpn.md b/docs/configuration/interfaces/md-openvpn.md
new file mode 100644
index 00000000..170c585d
--- /dev/null
+++ b/docs/configuration/interfaces/md-openvpn.md
@@ -0,0 +1,614 @@
+(openvpn)=
+
+# OpenVPN
+
+Traditionally, hardware routers use IPsec exclusively because it is easy to
+implement in hardware, and their CPUs lack sufficient power for software-based
+encryption. This limitation is less relevant for VyOS, as it is a software
+router.
+
+OpenVPN has been widely used on UNIX platforms for a long time and is a popular
+choice for remote-access VPNs. It also supports site-to-site connections.
+
+OpenVPN offers the following advantages:
+
+- It uses a single TCP or UDP connection and does not rely on packet source
+  addresses, so it works even through double NAT. This makes it well-suited for
+  public hotspots.
+- It is easy to set up and offers very flexible split tunneling.
+- A variety of client GUI frontends are available for any platform.
+
+Disadvantages include:
+
+- It is slower than IPsec due to higher protocol overhead and because it runs
+  in user mode, while IPsec on Linux runs in kernel mode.
+- No operating system includes OpenVPN client software by default.
+
+In the VyOS CLI, OpenVPN is configured as a network interface using `set
+interfaces openvpn` rather than `set vpn`, which is often overlooked.
+
+## Configuration
+
+```{cfgcmd} set interfaces openvpn \<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.
+```
+
+
+```{cmdincludemd} /_include/interface-ip.txt
+:var0: openvpn
+:var1: vtun0
+```
+
+
+```{cmdincludemd} /_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 Contributing/Issues and Features).
+
+Alternatively, use ``openvpn-option`` to pass raw OpenVPN configuration options
+to the openvpn.conf file.
+
+:::{warning}
+Use this option only as a last resort. Invalid options or syntax
+may prevent OpenVPN from starting. Check system logs for errors after applying
+changes.
+:::
+Example:
+
+:::{code-block} none
+set interfaces openvpn vtun0 openvpn-option 'persist-key'
+:::
+This command adds ``persist-key`` to the configuration file. This solves the
+problem by persisting keys across resets, so they do not need to be re-read.
+
+:::{code-block} none
+set interfaces openvpn vtun0 openvpn-option 'route-up &quot;/config/auth/tun_up.sh arg1&quot;'
+:::
+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}
+:includehidden: true
+:maxdepth: 1
+
+openvpn-examples
+```
+
diff --git a/docs/configuration/interfaces/md-pppoe.md b/docs/configuration/interfaces/md-pppoe.md
new file mode 100644
index 00000000..b79f41a2
--- /dev/null
+++ b/docs/configuration/interfaces/md-pppoe.md
@@ -0,0 +1,419 @@
+---
+lastproofread: '2026-03-03'
+---
+
+(pppoe-interface)=
+
+# PPPoE
+
+{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol
+that encapsulates PPP frames within Ethernet frames.
+It's often used for connecting ISP clients to a broadband access server.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: pppoe
+:var1: pppoe0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: pppoe
+:var1: pppoe0
+```
+
+```{cmdincludemd} /_include/interface-mtu.txt
+:var0: pppoe
+:var1: pppoe0
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: pppoe
+:var1: pppoe0
+```
+
+
+### PPPoE options
+
+```{cfgcmd} set interfaces pppoe \<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.
+```
+
+```{cmdincludemd} /_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.
+:::
+
+```none
+set interfaces pppoe pppoe0 authentication username 'userid'
+set interfaces pppoe pppoe0 authentication password 'secret'
+set interfaces pppoe pppoe0 source-interface 'eth0'
+```
+
+Secure your setup by creating rules matching the `pppoe0` interface in the
+firewall chains:
+
+```none
+set firewall ipv4 input filter rule 10 inbound-interface name 'pppoe0'
+set firewall ipv4 forward filter rule 10 inbound-interface name 'pppoe0'
+```
+
+
+### PPPoE over VLAN
+
+Some ISPs require PPPoE connections to be
+established over a VLAN interface. This specific topology is fully supported by
+VyOS.
+
+The following configuration establishes the PPPoE connection through VLAN 7,
+which is the default VLAN for Deutsche Telekom:
+
+```none
+set interfaces pppoe pppoe0 authentication username 'userid'
+set interfaces pppoe pppoe0 authentication password 'secret'
+set interfaces pppoe pppoe0 source-interface 'eth0.7'
+```
+
+
+#### IPv6 DHCPv6 prefix delegation
+
+**Configuration scenario:**
+
+The following configuration establishes a PPPoE session on the `eth1`
+interface, requests a `/56` IPv6 prefix delegation from the ISP, and assigns
+a `/64` subnet from that delegation to the `eth0` interface.
+
+**Configuration notes:**
+
+- The IPv6 address assigned to `eth0` is `<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.
+
+```none
+set interfaces pppoe pppoe0 authentication username vyos
+set interfaces pppoe pppoe0 authentication password vyos
+set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1'
+set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0'
+set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56'
+set interfaces pppoe pppoe0 ipv6 address autoconf
+set interfaces pppoe pppoe0 source-interface eth1
+
+set service router-advert interface eth0 prefix ::/64
+```
diff --git a/docs/configuration/interfaces/md-pseudo-ethernet.md b/docs/configuration/interfaces/md-pseudo-ethernet.md
new file mode 100644
index 00000000..fc8833eb
--- /dev/null
+++ b/docs/configuration/interfaces/md-pseudo-ethernet.md
@@ -0,0 +1,52 @@
+---
+lastproofread: '2026-03-05'
+---
+
+(pseudo-ethernet-interface)=
+
+# MACVLAN (pseudo-Ethernet)
+
+MACVLAN, or pseudo-Ethernet interfaces, operate as logical subinterfaces of
+standard Ethernet interfaces. Each subinterface has a unique MAC address but
+shares a single physical Ethernet port.
+That allows the user to send packets from different source IPv4 or IPv6 addresses
+using a different MAC address.
+
+Pseudo-Ethernet interfaces behave like physical Ethernet interfaces. They
+support IPv4 and IPv6 addressing, can obtain IP addresses through DHCP or
+DHCPv6, and are mapped to a physical Ethernet port. They inherit
+characteristics such as speed and duplex from their parent interface and can
+be referenced like standard Ethernet interfaces once created.
+
+```{eval-rst}
+Pseudo-Ethernet interfaces may not work in environments that require a
+   :abbr:`NIC (Network Interface Card)` to have only one MAC address.
+   This includes:
+
+   * VMware machines with default settings.
+   * Network switches that permit only a single MAC address.
+   * xDSL modems that learn the NIC's MAC address.
+```
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: pseudo-ethernet
+:var1: peth0
+```
+
+### MACVLAN (pseudo-Ethernet) options
+
+```{cfgcmd} set interfaces pseudo-ethernet \<interface\> source-interface \<ethX\>
+
+Assign a physical Ethernet interface to the specified pseudo-Ethernet interface.
+```
+
+### VLAN
+
+```{cmdincludemd} /_include/interface-vlan-8021q.txt
+:var0: pseudo-ethernet
+:var1: peth0
+```
\ No newline at end of file
diff --git a/docs/configuration/interfaces/md-sstp-client.md b/docs/configuration/interfaces/md-sstp-client.md
new file mode 100644
index 00000000..da98aecd
--- /dev/null
+++ b/docs/configuration/interfaces/md-sstp-client.md
@@ -0,0 +1,170 @@
+---
+lastproofread: '2026-03-16'
+---
+
+(sstp-client-interface)=
+
+# SSTP client
+
+{abbr}`SSTP (Secure Socket Tunneling Protocol)` transports PPP traffic over an
+SSL/TLS channel, providing transport-level security through key negotiation,
+encryption, and traffic integrity checking. The use of SSL/TLS over TCP port
+443 (by default, the port can be changed) allows SSTP to pass through virtually
+all firewalls and proxy servers, except for authenticated web proxies.
+
+:::{note}
+VyOS includes a built-in SSTP server. For more information, see
+{ref}`sstp`.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: sstpc
+:var1: sstpc0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: sstpc
+:var1: sstpc0
+```
+
+```{cmdincludemd} /_include/interface-mtu.txt
+:var0: sstpc
+:var1: sstpc0
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: sstpc
+:var1: sstpc0
+```
+
+
+### SSTP client options
+
+```{cfgcmd} set interfaces sstpc \<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.
+```
\ No newline at end of file
diff --git a/docs/configuration/interfaces/md-tunnel.md b/docs/configuration/interfaces/md-tunnel.md
new file mode 100644
index 00000000..6b50a924
--- /dev/null
+++ b/docs/configuration/interfaces/md-tunnel.md
@@ -0,0 +1,304 @@
+---
+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
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address.txt
+   :var0: tunnel
+   :var1: tun0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-without-mac.txt
+   :var0: tunnel
+   :var1: tun0
+```
+
+## IPIP
+
+IPIP is a straightforward encapsulation protocol defined in RFC 2003. It
+encapsulates one IPv4 packet inside another IPv4 packet.
+
+Tunnels with IPIP encapsulation do not have protocol-specific configuration
+options except for explicitly defining the encapsulation type as IPIP (see
+the example below).
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation ipip
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 203.0.113.20
+set interfaces tunnel tun0 address 192.168.100.200/24
+```
+
+## IP6IP6
+
+IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside
+another IPv6 packet.
+
+Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not
+have protocol-specific configuration options except for explicitly defining
+the encapsulation type as IP6IP6.
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation ip6ip6
+set interfaces tunnel tun0 source-address 2001:db8:aa::1
+set interfaces tunnel tun0 remote 2001:db8:aa::2
+set interfaces tunnel tun0 address 2001:db8:bb::1/64
+```
+
+## IPIP6
+
+IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets.
+
+Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with
+IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6.
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation ipip6
+set interfaces tunnel tun0 source-address 2001:db8:aa::1
+set interfaces tunnel tun0 remote 2001:db8:aa::2
+set interfaces tunnel tun0 address 192.168.70.80/24
+```
+
+## 6in4 (SIT)
+
+6in4, also known as {abbr}`SIT (Simple Internet Transition)`, is an
+encapsulation protocol defined in {rfc}`4213` that wraps IPv6 packets
+inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41,
+which is reserved exclusively for IPv6 encapsulation.
+
+The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet.
+Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes
+over an underlying network with a standard MTU of 1500 bytes without
+fragmentation.
+
+6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as
+[Hurricane Electric]) to connect isolated IPv6 networks or individual hosts to
+the IPv6 internet.
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation sit
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 192.0.2.20
+set interfaces tunnel tun0 address 2001:db8:bb::1/64
+```
+
+```{eval-rst}
+.. 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:**
+
+```none
+set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126'
+set interfaces tunnel tun101 address '192.168.5.1/30'
+set interfaces tunnel tun101 encapsulation 'ip6gre'
+set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3'
+set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5'
+```
+
+**Linux** `systemd-networkd`:
+
+The `systemd-networkd` setup requires two configuration files: `xxx.netdev`
+to create the {abbr}`GRE (Generic Routing Encapsulation)` tunnel interface, and
+`xxx.network` to assign IP addresses to it.
+
+```none
+# cat /etc/systemd/network/gre-example.netdev
+[NetDev]
+Name=gre-example
+Kind=ip6gre
+MTUBytes=14180
+
+[Tunnel]
+Remote=2001:db8:babe:face::3afe:3
+
+
+# cat /etc/systemd/network/gre-example.network
+[Match]
+Name=gre-example
+
+[Network]
+Address=2001:db8:feed:beef::2/126
+
+[Address]
+Address=192.168.5.2/30
+```
+
+### GRE keys
+
+A GRE key is an optional 32-bit field in the GRE header that allows multiple
+GRE tunnels to operate between the same source and destination endpoints. When
+a packet arrives, the receiver checks the GRE key to determine which tunnel
+interface should process it.
+
+Although it may sound security-related, the GRE key is only an identifier and
+provides no encryption or data protection.
+
+Example:
+
+```none
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 192.0.2.20
+set interfaces tunnel tun0 address 10.40.50.60/24
+set interfaces tunnel tun0 parameters ip key 10
+```
+
+```none
+set interfaces tunnel tun1 source-address 192.0.2.10
+set interfaces tunnel tun1 remote 192.0.2.20
+set interfaces tunnel tun1 address 172.16.17.18/24
+set interfaces tunnel tun1 parameters ip key 20
+```
+
+### GRETAP
+
+Unlike GRE, which encapsulates only Layer 3 (IP) traffic, GRETAP encapsulates
+Layer 2 (Ethernet) frames.
+
+That means that GRETAP tunnel interfaces can be members of a bridge interface.
+This allows two geographically distant sites to connect as if they were on the
+same LAN.
+
+GRETAP tunnels can be established over both IPv4 and IPv6 transport networks.
+
+Example:
+
+```none
+set interfaces bridge br0 member interface eth0
+set interfaces bridge br0 member interface tun0
+set interfaces tunnel tun0 encapsulation gretap
+set interfaces tunnel tun0 source-address 198.51.100.2
+set interfaces tunnel tun0 remote 203.0.113.10
+```
+
+### Troubleshooting
+
+GRE is a standardized tunneling protocol used in many network environments.
+
+Although the GRE tunnel setup is straightforward, connectivity failures
+frequently occur because ACLs or firewall rules block IP protocol 47 or
+prevent direct communication between the tunnel endpoints.
+
+If your GRE tunnel fails to establish, perform these diagnostic steps:
+
+1\. Verify that the remote peer is reachable from the configured
+`source-address`.
+
+This ensures that the underlying physical path between the two endpoints is
+functional.
+
+```none
+vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4
+PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data.
+64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms
+64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms
+64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms
+64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms
+
+--- 203.0.113.10 ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 3007ms
+rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms
+```
+
+2\. Verify that the tunnel interface is correctly configured (with the link type
+set to GRE) and is actively processing traffic.
+
+```none
+vyos@vyos:~$ show interfaces tunnel tun100
+tun100@NONE: <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.
+
+```none
+vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4
+PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data.
+64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms
+64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms
+64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms
+64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms
+
+--- 10.0.0.2 ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 3008ms
+rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms
+```
+
+[hurricane electric]: https://tunnelbroker.net/
+[other proposals]: https://www.isc.org/othersoftware/
diff --git a/docs/configuration/interfaces/md-virtual-ethernet.md b/docs/configuration/interfaces/md-virtual-ethernet.md
new file mode 100644
index 00000000..dee1b332
--- /dev/null
+++ b/docs/configuration/interfaces/md-virtual-ethernet.md
@@ -0,0 +1,119 @@
+---
+lastproofread: '2026-01-26'
+---
+
+(virtual-ethernet)=
+
+# Virtual Ethernet
+
+Virtual Ethernet (veth) interfaces are software-based interfaces that operate
+in pairs, creating a tunnel between each other. Traffic transmitted into one
+interface of the pair (e.g., `veth0`) is delivered directly to its peer
+interface (e.g., `veth1`).
+
+Veth interfaces are commonly used to connect network namespaces or VRFs, but
+they can also function as standalone virtual network interfaces.
+
+:::{note}
+Veth interfaces must be created in pairs, where each interface acts
+as the peer of the other.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address-with-dhcp.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+
+### VLAN
+
+#### Regular VLANs (802.1q)
+
+```{cmdincludemd} /_include/interface-vlan-8021q.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+
+#### 802.1ad (QinQ)
+
+```{cmdincludemd} /_include/interface-vlan-8021ad.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+
+## Operation
+
+```{opcmd} show interfaces virtual-ethernet
+
+Show brief interface information.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces virtual-ethernet
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+veth10           100.64.0.0/31                     u/u
+veth11           100.64.0.1/31                     u/u
+:::
+```
+
+```{opcmd} show interfaces virtual-ethernet \<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.
+
+```none
+set interfaces virtual-ethernet veth10 address '100.64.0.0/31'
+set interfaces virtual-ethernet veth10 peer-name 'veth11'
+set interfaces virtual-ethernet veth11 address '100.64.0.1/31'
+set interfaces virtual-ethernet veth11 peer-name 'veth10'
+set interfaces virtual-ethernet veth11 vrf 'red'
+set vrf name red table '1000'
+
+vyos@vyos:~$ ping 100.64.0.1
+PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data.
+64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms
+64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms
+```
diff --git a/docs/configuration/interfaces/md-vti.md b/docs/configuration/interfaces/md-vti.md
new file mode 100644
index 00000000..461a3388
--- /dev/null
+++ b/docs/configuration/interfaces/md-vti.md
@@ -0,0 +1,53 @@
+# VTI - Virtual Tunnel Interface
+
+<div class="todo">
+
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+
+</div>
+
+Set Virtual Tunnel Interface
+
+``` none
+set interfaces vti vti0 address 192.168.2.249/30
+set interfaces vti vti0 address 2001:db8:2::249/64
+```
+
+Results in:
+
+``` none
+vyos@vyos# show interfaces vti
+vti vti0 {
+    address 192.168.2.249/30
+    address 2001:db8:2::249/64
+    description "Description"
+}
+```
+
+<div class="warning">
+
+<div class="title">
+
+Warning
+
+</div>
+
+When using site-to-site IPsec with VTI interfaces,
+be sure to disable route autoinstall
+
+</div>
+
+``` none
+set vpn ipsec options disable-route-autoinstall
+```
+
+More details about the IPsec and VTI issue and option disable-route-autoinstall
+<https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july>
+
+The root cause of the problem is that for VTI tunnels to work, their traffic
+selectors have to be set to 0.0.0.0/0 for traffic to match the tunnel, even
+though actual routing decision is made according to netfilter marks. Unless
+route insertion is disabled entirely, StrongSWAN thus mistakenly inserts a
+default route through the VTI peer address, which makes all traffic routed
+to nowhere.
diff --git a/docs/configuration/interfaces/md-vxlan.md b/docs/configuration/interfaces/md-vxlan.md
new file mode 100644
index 00000000..8dae75ff
--- /dev/null
+++ b/docs/configuration/interfaces/md-vxlan.md
@@ -0,0 +1,373 @@
+---
+lastproofread: '2026-03-16'
+---
+
+(vxlan-interface)=
+
+# VXLAN
+
+{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology
+that addresses scalability challenges in large cloud computing environments.
+It encapsulates Ethernet frames (Layer 2) within UDP datagrams (Layer 4), which
+are then transmitted via UDP port 4789, as assigned by IANA. VXLAN endpoints,
+called {abbr}`VTEPs (VXLAN tunnel endpoints)`, terminate VXLAN tunnels and can
+be either virtual or physical switch ports.
+
+VXLAN supports up to 16 million logical networks and enables Layer 2 adjacency
+across Layer 3 IP networks. It uses multicast or unicast with head-end
+replication (HER) to flood broadcast, unknown unicast, and multicast (BUM)
+traffic.
+
+The VXLAN specification was initially developed by VMware, Arista Networks, and
+Cisco. Other supporters include Huawei, Broadcom, Citrix, Pica8, Big Switch
+Networks, Cumulus Networks, Dell EMC, Ericsson, Mellanox, FreeBSD, OpenBSD, Red
+Hat, Joyent, and Juniper Networks.
+
+VXLAN is officially documented by the IETF in {rfc}`7348`.
+
+When configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing
+(Hyper-V) or Forged Transmits (ESX) are permitted. Otherwise, the hypervisor
+may block forwarded frames.
+
+:::{note}
+Although the IANA-assigned VXLAN port is **4789**, VyOS uses the
+Linux default UDP port **8472** for VXLAN interfaces. To ensure compatibility
+with other vendors, set the port to the IANA standard **4789**.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-without-dhcp.txt
+:var0: vxlan
+:var1: vxlan0
+```
+
+
+### VXLAN-specific options
+
+```{cfgcmd} set interfaces vxlan \<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.
+
+```none
+Spine1:
+fa0/2 towards Leaf2, IP-address: 10.1.2.1/24
+fa0/3 towards Leaf3, IP-address: 10.1.3.1/24
+
+Leaf2:
+Eth0 towards Spine1, IP-address: 10.1.2.2/24
+Eth1 towards a VLAN-aware switch
+
+Leaf3:
+Eth0 towards Spine1, IP-address 10.1.3.3/24
+Eth1 towards a VLAN-aware switch
+```
+
+**Spine1 configuration:**
+
+```none
+conf t
+ip multicast-routing
+!
+interface fastethernet0/2
+ ip address 10.1.2.1 255.255.255.0
+ ip pim sparse-dense-mode
+!
+interface fastethernet0/3
+ ip address 10.1.3.1 255.255.255.0
+ ip pim sparse-dense-mode
+!
+router ospf 1
+ network 10.0.0.0 0.255.255.255 area 0
+```
+
+Multicast routing is required for scalable traffic forwarding between leaves.
+{abbr}`PIM (Protocol Independent Multicast)` must be enabled towards the leaves
+so the spine can learn from which multicast groups each leaf expects traffic.
+
+**Leaf2 configuration:**
+
+```none
+set interfaces ethernet eth0 address '10.1.2.2/24'
+set protocols ospf area 0 network '10.0.0.0/8'
+
+! First VXLAN interface
+set interfaces bridge br241 address '172.16.241.1/24'
+set interfaces bridge br241 member interface 'eth1.241'
+set interfaces bridge br241 member interface 'vxlan241'
+
+set interfaces vxlan vxlan241 group '239.0.0.241'
+set interfaces vxlan vxlan241 source-interface 'eth0'
+set interfaces vxlan vxlan241 vni '241'
+
+! Second VXLAN interface
+set interfaces bridge br242 address '172.16.242.1/24'
+set interfaces bridge br242 member interface 'eth1.242'
+set interfaces bridge br242 member interface 'vxlan242'
+
+set interfaces vxlan vxlan242 group '239.0.0.242'
+set interfaces vxlan vxlan242 source-interface 'eth0'
+set interfaces vxlan vxlan242 vni '242'
+```
+
+**Leaf3 configuration:**
+
+```none
+set interfaces ethernet eth0 address '10.1.3.3/24'
+set protocols ospf area 0 network '10.0.0.0/8'
+
+! First VXLAN interface
+set interfaces bridge br241 address '172.16.241.1/24'
+set interfaces bridge br241 member interface 'eth1.241'
+set interfaces bridge br241 member interface 'vxlan241'
+
+set interfaces vxlan vxlan241 group '239.0.0.241'
+set interfaces vxlan vxlan241 source-interface 'eth0'
+set interfaces vxlan vxlan241 vni '241'
+
+! Second VXLAN interface
+set interfaces bridge br242 address '172.16.242.1/24'
+set interfaces bridge br242 member interface 'eth1.242'
+set interfaces bridge br242 member interface 'vxlan242'
+
+set interfaces vxlan vxlan242 group '239.0.0.242'
+set interfaces vxlan vxlan242 source-interface 'eth0'
+set interfaces vxlan vxlan242 vni '242'
+```
+
+The configurations for Leaf2 and Leaf3 are nearly identical. Detailed
+explanations for each command are provided below.
+
+```none
+set interfaces bridge br241 address '172.16.241.1/24'
+```
+
+This command creates a bridge to bind traffic on `eth1` VLAN 241 with the
+`vxlan241` interface. The IP address is optional. If configured, it can serve
+as the default gateway for each leaf, allowing devices on the VLAN to reach
+other subnets. Subnets must be redistributed by {abbr}`OSPF (Open Shortest Path
+First)` so the spine can learn how to reach them. To advertise `172.16/12`
+networks, change the {abbr}`OSPF (Open Shortest Path First)` network from
+`10.0.0.0/8` to `0.0.0.0/0`.
+
+```none
+set interfaces bridge br241 member interface 'eth1.241'
+set interfaces bridge br241 member interface 'vxlan241'
+```
+
+These commands bind `eth1.241` and `vxlan241` as member interfaces of the
+same bridge.
+
+```none
+set interfaces vxlan vxlan241 group '239.0.0.241'
+```
+
+This command configures the multicast group used by all leaves for this VLAN
+extension. It must be the same on all leaves that have this interface.
+
+```none
+set interfaces vxlan vxlan241 source-interface 'eth0'
+```
+
+This command configures the interface that listens for multicast packets. It
+can also be a loopback interface.
+
+```none
+set interfaces vxlan vxlan241 vni '241'
+```
+
+This command configures the unique ID for the VXLAN interface.
+
+```none
+set interfaces vxlan vxlan241 port 12345
+```
+
+VyOS uses the Linux default UDP port **8472** for VXLAN interfaces. This
+command allows you to configure a different UDP port.
+
+## Unicast VXLAN
+
+As an alternative to multicast, you can configure the VXLAN tunnel by
+specifying the remote IPv4 address directly. The following updates the previous
+multicast example:
+
+```none
+# leaf2 and leaf3
+delete interfaces vxlan vxlan241 group '239.0.0.241'
+delete interfaces vxlan vxlan241 source-interface 'eth0'
+
+# leaf2
+set interfaces vxlan vxlan241 remote 10.1.3.3
+
+# leaf3
+set interfaces vxlan vxlan241 remote 10.1.2.2
+```
+
+The default UDP port is 8472. To configure a different port, use `set
+interfaces vxlan <vxlanN> port <port>`.
diff --git a/docs/configuration/interfaces/md-wireguard.md b/docs/configuration/interfaces/md-wireguard.md
new file mode 100644
index 00000000..27003282
--- /dev/null
+++ b/docs/configuration/interfaces/md-wireguard.md
@@ -0,0 +1,441 @@
+---
+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.webp
+:::
+
+## Keypairs
+
+WireGuard requires a keypair, which includes a **private** key
+to decrypt incoming traffic, and a **public** key for peer(s) to encrypt
+outgoing traffic.
+
+### Generate keypair
+
+```{eval-rst}
+.. 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=
+```
+
+```{eval-rst}
+.. 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=
+     +}
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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=
+
+```
+
+```{eval-rst}
+.. 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.
+
+```
+
+## Interface configuration
+
+The next step is to configure your local WireGuard interface and define the
+networks you want to tunnel (`allowed-ips`).
+
+If your system only initiates connections, specifying the listen port is
+optional. If your system accepts incoming connections, you must define a port
+for peers to connect to. Otherwise, WireGuard selects a random port at each
+reboot, and that may break your peers' ability to connect if that port is not enabled in your firewall rules.
+
+To configure a WireGuard tunnel, you also need your peer's public key.
+
+:::{note}
+The public key specified in the peer configuration block is always
+the **remote** peer's public key, never your local one.
+:::
+
+**Local side configuration**
+
+The local side is configured with the following parameters:
+
+- Local WireGuard interface IP: `10.1.0.1/30`
+- Local listen port: `51820`
+- Remote peer name: `to-wg02`
+- Remote peer endpoint: `192.0.2.1` on port `51820`
+- Remote peer public key: `XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=`
+- Allowed networks: `192.168.2.0/24`
+
+```none
+set interfaces wireguard wg01 address '10.1.0.1/30'
+set interfaces wireguard wg01 description 'VPN-to-wg02'
+set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24'
+set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1'
+set interfaces wireguard wg01 peer to-wg02 port '51820'
+set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI='
+set interfaces wireguard wg01 port '51820'
+
+set protocols static route 192.168.2.0/24 interface wg01
+```
+
+To send traffic destined for `192.168.2.0/24` through the WireGuard interface
+(`wg01`), configure a static route. Multiple IP addresses or networks can be
+defined and routed. The final check is performed against `allowed-ips`, which
+either permits or drops the traffic.
+
+:::{warning}
+You cannot assign the same `allowed-ips` to multiple WireGuard
+peers. This is a strict design restriction. For more information, check the
+[WireGuard mailing list].
+:::
+
+```{eval-rst}
+.. 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`.
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-per-client-thread.txt
+   :var0: wireguard
+   :var1: wg01
+```
+
+**Remote side configuration**
+
+```none
+set interfaces wireguard wg01 address '10.1.0.2/30'
+set interfaces wireguard wg01 description 'VPN-to-wg01'
+set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24'
+set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2'
+set interfaces wireguard wg01 peer to-wg01 port '51820'
+set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw='
+set interfaces wireguard wg01 port '51820'
+set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU='
+
+set protocols static route 192.168.1.0/24 interface wg01
+```
+
+## Firewall exceptions
+
+To allow WireGuard traffic through the WAN interface, create a firewall
+exception:
+
+```none
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related'
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp
+```
+
+Ensure that the OUTSIDE_LOCAL firewall group is applied to the WAN interface
+and in an input (local) direction.
+
+```none
+set firewall ipv4 input filter rule 10 action jump
+set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL'
+set firewall ipv4 input filter rule 10 inbound-interface name 'eth0'
+```
+
+Verify that your firewall rules permit traffic. If so, your WireGuard VPN
+should be operational.
+
+```none
+wg01# ping 192.168.1.1
+PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data.
+64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms
+64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms
+
+wg02# ping 192.168.2.1
+PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data.
+64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms
+64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms
+```
+
+An additional layer of symmetric-key cryptography can be used on top of the
+asymmetric cryptography. This is optional.
+
+```none
+vyos@vyos:~$ generate pki wireguard preshared-key
+Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=
+```
+
+Copy the key, as it is not stored locally. Since it is a symmetric key, only
+you and your peer should know its contents. Distribute the key securely.
+
+```none
+wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
+wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
+```
+
+## Remote access (road warrior)
+
+With WireGuard, a road warrior VPN configuration is similar to a site-to-site
+VPN. It just omits the `address` and `port` statements.
+
+In the following example, the IP addresses for remote clients are defined
+within each peer configuration. This allows peers to communicate with each
+other.
+
+Additionally, this setup uses a `persistent-keepalive` flag set to 15 seconds
+to keep the connection alive. This setting is mainly relevant if a peer is
+behind NAT and cannot be reached if the connection is lost. For effectiveness,
+the value should be lower than the UDP timeout.
+
+```none
+wireguard wg01 {
+    address 10.172.24.1/24
+    address 2001:db8:470:22::1/64
+    description RoadWarrior
+    peer MacBook {
+        allowed-ips 10.172.24.30/32
+        allowed-ips 2001:db8:470:22::30/128
+        persistent-keepalive 15
+        pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc=
+    }
+    peer iPhone {
+        allowed-ips 10.172.24.20/32
+        allowed-ips 2001:db8:470:22::20/128
+        persistent-keepalive 15
+        pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00=
+    }
+    port 2224
+    private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=
+}
+```
+
+Below is the configuration for the iPhone peer. The `AllowedIPs` wildcard
+setting directs all IPv4 and IPv6 traffic through the VPN connection.
+
+```none
+[Interface]
+PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf=
+Address = 10.172.24.20/24, 2001:db8:470:22::20/64
+DNS = 10.0.0.53, 10.0.0.54
+
+[Peer]
+PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc=
+AllowedIPs = 0.0.0.0/0, ::/0
+Endpoint = 192.0.2.1:2224
+PersistentKeepalive = 15
+```
+
+To enable split tunneling, specify the remote subnets. This ensures that only
+traffic destined for the remote site is sent through the tunnel, while all
+other traffic remains unaffected.
+
+```none
+[Interface]
+PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go=
+Address = 10.172.24.30/24, 2001:db8:470:22::30/64
+
+[Peer]
+PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc=
+AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64
+Endpoint = 192.0.2.1:2224
+PersistentKeepalive = 15
+```
+
+## Operational commands
+
+### Status
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+
+```
+
+```{eval-rst}
+.. 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.
+:::
+
+```{eval-rst}
+.. 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.webp
+     :alt: WireGuard Client QR code
+```
+
+
+
+[wireguard mailing list]: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html
diff --git a/docs/configuration/interfaces/md-wireless.md b/docs/configuration/interfaces/md-wireless.md
new file mode 100644
index 00000000..d2fd4d49
--- /dev/null
+++ b/docs/configuration/interfaces/md-wireless.md
@@ -0,0 +1,1012 @@
+---
+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
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+### System-wide configuration
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> physical-device <device>
+
+  Wireless hardware device used as underlay radio.
+
+  This defaults to phy0.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> ssid <ssid>
+
+  SSID to be used in IEEE 802.11 management frames
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-per-client-thread.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+#### PPDU
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities require-vht
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable
+
+  Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]``
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave
+
+  WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD]
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   delayed-block-ack
+
+  Enable HT-delayed Block Ack ``[DELAYED-BA]``
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40
+
+  DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]``
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield
+
+  This enables the greenfield option which sets the ``[GF]`` option
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc
+
+  Enable LDPC coding capability
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection
+
+  Enable L-SIG TXOP protection capability
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu
+   <3839 | 7935>
+
+  Maximum A-MSDU length 3839 (default) or 7935 octets
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   short-gi <20 | 40>
+
+  Short GI capabilities for 20 and 40 MHz
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   smps <static | dynamic>
+
+  Spatial Multiplexing Power Save (SMPS) settings
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num>
+
+  Enable receiving PPDU using STBC (Space Time Block Coding)
+```
+
+```{eval-rst}
+.. 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)
+
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count <count>
+```
+
+%
+% Number of antennas on this card
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   antenna-pattern-fixed
+
+  Set if antenna pattern does not change during the lifetime of an association
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc
+
+  Enable LDPC (Low Density Parity Check) coding capability
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface>
+  capabilities vht link-adaptation
+
+  VHT link adaptation capabilities
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   max-mpdu <value>
+
+  Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets)
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   short-gi <80 | 160>
+
+  Short GI capabilities
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num>
+
+  Enable receiving PPDU using STBC (Space Time Block Coding)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx
+
+  Enable sending PPDU using STBC (Space Time Block Coding)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave
+
+  Enable VHT TXOP Power Save Mode
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf
+
+  Station supports receiving VHT variant HT Control field
+```
+
+##### HE (High Efficiency) capabilities (802.11ax)
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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)
+```
+
+```{eval-rst}
+.. 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.
+
+```none
+set system wireless country-code de
+set interfaces wireless wlan0 type station
+set interfaces wireless wlan0 address dhcp
+set interfaces wireless wlan0 ssid 'TEST'
+set interfaces wireless wlan0 security wpa passphrase '12345678'
+```
+
+Resulting configuration:
+
+```none
+system {
+  wireless {
+    country-code de
+  }
+}
+interfaces {
+  wireless wlan0 {
+    address dhcp
+    security {
+      wpa {
+        passphrase "12345678"
+      }
+    }
+    ssid TEST
+    type station
+  }
+```
+
+### Security
+
+{abbr}`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in
+combination with 802.1X based authentication can be used to authenticate
+users or computers in a domain.
+
+The wireless client (supplicant) authenticates against the RADIUS server
+(authentication server) using an {abbr}`EAP (Extensible Authentication
+Protocol)` method configured on the RADIUS server. The WAP (also referred
+to as authenticator) role is to send all authentication messages between the
+supplicant and the configured authentication server, thus the RADIUS server
+is responsible for authenticating the users.
+
+The WAP in this example has the following characteristics:
+
+- IP address `192.168.2.1/24`
+- Network ID (SSID) `Enterprise-TEST`
+- WPA passphrase `12345678`
+- Use 802.11n protocol
+- Wireless channel `1`
+- RADIUS server at `192.168.3.10` with shared-secret `VyOSPassword`
+
+
+```none
+set system wireless country-code de
+set interfaces wireless wlan0 address '192.168.2.1/24'
+set interfaces wireless wlan0 type access-point
+set interfaces wireless wlan0 channel 1
+set interfaces wireless wlan0 mode n
+set interfaces wireless wlan0 ssid 'Enterprise-TEST'
+set interfaces wireless wlan0 security wpa mode wpa2
+set interfaces wireless wlan0 security wpa cipher CCMP
+set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword'
+set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812
+```
+
+
+Resulting configuration:
+
+```none
+system {
+  wireless {
+    country-code de
+  }
+}
+interfaces {
+  [...]
+  wireless wlan0 {
+        address 192.168.2.1/24
+        channel 1
+        mode n
+        security {
+            wpa {
+                cipher CCMP
+                mode wpa2
+                radius {
+                    server 192.168.3.10 {
+                        key 'VyOSPassword'
+                        port 1812
+                    }
+                }
+            }
+        }
+        ssid "Enterprise-TEST"
+        type access-point
+    }
+}
+```
+
+### VLAN
+
+#### Regular VLANs (802.1q)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+#### QinQ (802.1ad)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021ad.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless info
+```
+
+Use this command to view operational status and wireless-specific information
+about all wireless interfaces.
+
+```none
+vyos@vyos:~$ show interfaces wireless info
+Interface  Type          SSID                         Channel
+wlan0      access-point  VyOS-TEST-0                        1
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless detail
+```
+
+Show the operational status and detailed wireless-specific
+information about all wireless interfaces.
+
+
+```none
+vyos@vyos:~$ show interfaces wireless detail
+wlan0: <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
+```
+
+
+```{eval-rst}
+.. 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.
+
+
+```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
+```
+
+
+```{eval-rst}
+.. 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.
+
+```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
+```
+
+```{eval-rst}
+.. 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.
+
+```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
+```
+
+```{eval-rst}
+.. 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.
+:::
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0 scan
+Address            SSID                          Channel  Signal (dbm)
+00:53:3b:88:6e:d8  WLAN-576405                         1  -64.00
+00:53:3b:88:6e:da  Telekom_FON                         1  -64.00
+00:53:00:f2:c2:a4  BabyView_F2C2A4                     6  -60.00
+00:53:3b:88:6e:d6  Telekom_FON                       100  -72.00
+00:53:3b:88:6e:d4  WLAN-576405                       100  -71.00
+00:53:44:a4:96:ec  KabelBox-4DC8                      56  -81.00
+00:53:d9:7a:67:c2  WLAN-741980                         1  -75.00
+00:53:7c:99:ce:76  Vodafone Homespot                   1  -86.00
+00:53:44:a4:97:21  KabelBox-4DC8                       1  -78.00
+00:53:44:a4:97:21  Vodafone Hotspot                    1  -79.00
+00:53:44:a4:97:21  Vodafone Homespot                   1  -79.00
+00:53:86:40:30:da  Telekom_FON                         1  -86.00
+00:53:7c:99:ce:76  Vodafone Hotspot                    1  -86.00
+00:53:44:46:d2:0b  Vodafone Hotspot                    1  -87.00
+```
+
+## Examples
+
+The following example creates a WAP. When configuring multiple WAP interfaces,
+you must specify unique IP addresses, channels, Network IDs commonly referred
+to as {abbr}`SSID (Service Set Identifier)`, and MAC addresses.
+
+The WAP in this example has the following characteristics:
+
+- IP address `192.168.2.1/24`
+- Network ID (SSID) `TEST`
+- WPA passphrase `12345678`
+- Use 802.11n protocol
+- Wireless channel `1`
+
+```none
+set system wireless country-code de
+set interfaces wireless wlan0 address '192.168.2.1/24'
+set interfaces wireless wlan0 type access-point
+set interfaces wireless wlan0 channel 1
+set interfaces wireless wlan0 mode n
+set interfaces wireless wlan0 ssid 'TEST'
+set interfaces wireless wlan0 security wpa mode wpa2
+set interfaces wireless wlan0 security wpa cipher CCMP
+set interfaces wireless wlan0 security wpa passphrase '12345678'
+```
+
+Resulting configuration:
+
+```none
+system {
+  wireless {
+    country-code de
+  }
+}
+interfaces {
+  [...]
+  wireless wlan0 {
+        address 192.168.2.1/24
+        channel 1
+        mode n
+        security {
+            wpa {
+                cipher CCMP
+                mode wpa2
+                passphrase "12345678"
+            }
+        }
+        ssid "TEST"
+        type access-point
+    }
+}
+```
+
+To enable access point functionality, configure a DHCP server for this
+interface's network, or add the interface to an existing local bridge
+(see {ref}`bridge-interface` for details).
+
+### Wi-Fi 6/6E (802.11ax)
+
+The following examples configure Wi-Fi 6 (2.4 GHz) and Wi-Fi 6E (6 GHz)
+{abbr}`APs (Access Points)` with the following parameters:
+
+- Network ID (SSID): `test.ax`
+- WPA passphrase: `super-dooper-secure-passphrase`
+- Protocol: 802.11ax
+- Wireless channel for 2.4 GHz: `11`
+- Wireless channel for 6 GHz: `5`
+
+#### Example configuration: Wi-Fi 6 at 2.4 GHz
+
+You may expect real throughput around 10 MB/s or higher in crowded areas.
+
+
+```none
+set system wireless country-code de
+set interfaces wireless wlan0 capabilities he antenna-pattern-fixed
+set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer
+set interfaces wireless wlan0 capabilities he beamform single-user-beamformee
+set interfaces wireless wlan0 capabilities he beamform single-user-beamformer
+set interfaces wireless wlan0 capabilities he bss-color 13
+set interfaces wireless wlan0 capabilities he channel-set-width 81
+set interfaces wireless wlan0 capabilities ht 40mhz-incapable
+set interfaces wireless wlan0 capabilities ht channel-set-width ht20
+set interfaces wireless wlan0 capabilities ht channel-set-width ht40+
+set interfaces wireless wlan0 capabilities ht channel-set-width ht40-
+set interfaces wireless wlan0 capabilities ht short-gi 20
+set interfaces wireless wlan0 capabilities ht short-gi 40
+set interfaces wireless wlan0 capabilities ht stbc rx 2
+set interfaces wireless wlan0 capabilities ht stbc tx
+set interfaces wireless wlan0 channel 11
+set interfaces wireless wlan0 description "802.11ax 2.4GHz"
+set interfaces wireless wlan0 mode ax
+set interfaces wireless wlan0 security wpa cipher CCMP
+set interfaces wireless wlan0 security wpa cipher CCMP-256
+set interfaces wireless wlan0 security wpa cipher GCMP-256
+set interfaces wireless wlan0 security wpa cipher GCMP
+set interfaces wireless wlan0 security wpa mode wpa2
+set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase
+set interfaces wireless wlan0 ssid test.ax
+set interfaces wireless wlan0 type access-point
+commit
+```
+
+
+Resulting configuration:
+
+```none
+system {
+  wireless {
+    country-code de
+  }
+}
+interfaces {
+  [...]
+  wireless wlan0 {
+        capabilities {
+            he {
+                antenna-pattern-fixed
+                beamform {
+                    multi-user-beamformer
+                    single-user-beamformee
+                    single-user-beamformer
+                }
+                bss-color 13
+                channel-set-width 81
+            }
+            ht {
+                40mhz-incapable
+                channel-set-width ht20
+                channel-set-width ht40+
+                channel-set-width ht40-
+                short-gi 20
+                short-gi 40
+                stbc {
+                    rx 2
+                    tx
+                }
+            }
+        }
+        channel 11
+        description "802.11ax 2.4GHz"
+        hw-id [...]
+        mode ax
+        physical-device phy0
+        security {
+            wpa {
+                cipher CCMP
+                cipher CCMP-256
+                cipher GCMP-256
+                cipher GCMP
+                mode wpa2
+                passphrase super-dooper-secure-passphrase
+            }
+        }
+        ssid test.ax
+        type access-point
+    }
+}
+```
+
+#### Example configuration: Wi-Fi 6E at 6 GHz
+
+You may expect real throughput between 50 MB/s and 150 MB/s, depending on
+obstructions from walls, water, metal, or other materials
+with high electromagnetic damping at 6 GHz. Best results are achieved
+with the AP being in the same room and in line-of-sight.
+
+
+```none
+set system wireless country-code de
+set interfaces wireless wlan0 capabilities he antenna-pattern-fixed
+set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer
+set interfaces wireless wlan0 capabilities he beamform single-user-beamformee
+set interfaces wireless wlan0 capabilities he beamform single-user-beamformer
+set interfaces wireless wlan0 capabilities he bss-color 13
+set interfaces wireless wlan0 capabilities he channel-set-width 134
+set interfaces wireless wlan0 capabilities he center-channel-freq freq-1 15
+set interfaces wireless wlan0 channel 5
+set interfaces wireless wlan0 description "802.11ax 6GHz"
+set interfaces wireless wlan0 mode ax
+set interfaces wireless wlan0 security wpa cipher CCMP
+set interfaces wireless wlan0 security wpa cipher CCMP-256
+set interfaces wireless wlan0 security wpa cipher GCMP-256
+set interfaces wireless wlan0 security wpa cipher GCMP
+set interfaces wireless wlan0 security wpa mode wpa3
+set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase
+set interfaces wireless wlan0 mgmt-frame-protection required
+set interfaces wireless wlan0 enable-bf-protection
+set interfaces wireless wlan0 ssid test.ax
+set interfaces wireless wlan0 type access-point
+set interfaces wireless wlan0 stationary-ap
+commit
+```
+
+
+Resulting configuration:
+
+```none
+system {
+  wireless {
+    country-code de
+  }
+}
+interfaces {
+  [...]
+  wireless wlan0 {
+        capabilities {
+            he {
+                antenna-pattern-fixed
+                beamform {
+                    multi-user-beamformer
+                    single-user-beamformee
+                    single-user-beamformer
+                }
+                bss-color 13
+                center-channel-freq {
+                    freq-1 15
+                }
+                channel-set-width 134
+            }
+        }
+        channel 5
+        description "802.11ax 6GHz"
+        enable-bf-protection
+        hw-id [...]
+        mgmt-frame-protection required
+        mode ax
+        physical-device phy0
+        security {
+            wpa {
+                cipher CCMP
+                cipher CCMP-256
+                cipher GCMP-256
+                cipher GCMP
+                mode wpa3
+                passphrase super-dooper-secure-passphrase
+            }
+        }
+        ssid test.ax
+        stationary-ap
+        type access-point
+    }
+}
+```
+
+(wireless-interface-intel-ax200)=
+
+### Intel AX200
+
+The Intel AX200 card does not work out of the box in AP mode. You can
+still put this card into AP mode using the following configuration:
+
+
+```none
+set system wireless country-code 'us'
+set interfaces wireless wlan0 channel '1'
+set interfaces wireless wlan0 mode 'n'
+set interfaces wireless wlan0 physical-device 'phy0'
+set interfaces wireless wlan0 ssid 'VyOS'
+set interfaces wireless wlan0 type 'access-point'
+```
+
diff --git a/docs/configuration/interfaces/md-wwan.md b/docs/configuration/interfaces/md-wwan.md
new file mode 100644
index 00000000..e8121f28
--- /dev/null
+++ b/docs/configuration/interfaces/md-wwan.md
@@ -0,0 +1,355 @@
+---
+lastproofread: '2026-03-30'
+---
+
+(wwan-interface)=
+
+# WWAN
+
+{abbr}`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular
+networks via a cellular modem or card.
+
+Configure these interfaces under the `interfaces wwan` node.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address-with-dhcp.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-disable-link-detect.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-mtu.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-ip.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-ipv6.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: wwan
+:var1: wwan0
+```
+
+**DHCP(v6)**
+
+```{cmdincludemd} /_include/interface-dhcp-options.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-dhcpv6-options.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt
+:var0: wwan
+:var1: wwan0
+```
+
+
+### WWAN options
+
+```{cfgcmd} set interfaces wwan \<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`.
+
+```none
+set interfaces wwan wwan0 apn 'internet.telekom'
+set interfaces wwan wwan0 address 'dhcp'
+```
+
+
+## Supported hardware
+
+The following WWAN modules have been successfully tested with a
+{ref}`pc-engines-apu4` board:
+- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE)
+- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE)
+- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE)
+- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE)
+- Huawei ME909u-521 miniPCIe card (LTE)
+- Huawei ME909s-120 miniPCIe card (LTE)
+- HP LT4120 Snapdragon X5 LTE
+
+## Firmware update
+
+WWAN modules include reprogrammable firmware, and most vendors regularly
+provide updates for it.
+
+Since VyOS communicates with these devices via the QMI interface, you can
+update firmware directly within the system using the `qmi-firmware-update`
+utility.
+
+The following example shows how to update the firmware for a Sierra Wireless
+MC7710 module using the provided .cwe file.
+
+```bash
+$ sudo qmi-firmware-update --update -d 1199:68a2 \
+   9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe
+```
-- 
cgit v1.2.3