Add incremental RST-to-MyST swap mechanism (#1857)

* feat: add swap_sources.py for incremental RST-to-MyST migration

Pre-build swap/restore script that renames md-{name}.md → {name}.md
before Sphinx builds and restores after. Includes state tracking,
exclude file generation, collision detection, and partial-failure
rollback. 10 tests cover all specified behaviors plus rollback path.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat: add import_myst.py for importing MyST files from myst/* branches

Adds scripts/import_myst.py with import_page, git_show, list_myst_files,
list_rst_files, and do_import. Imported files are written as md-{name}.md
alongside existing RST files; importing is decoupled from swap activation.

Adds tests/test_import_myst.py covering single-page write, identical-skip,
warn-on-different-without-force, force-overwrite, and nested-path creation.
All 5 tests pass on Python 3.9.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat: add MyST swap exclude patterns and directive config to conf.py

🤖 Generated by [robots](https://vyos.io)

* feat: add swap-wrapped rendering targets to Makefile

🤖 Generated by [robots](https://vyos.io)

* feat: add swap pre/post build hooks for ReadTheDocs

🤖 Generated by [robots](https://vyos.io)

* feat: add empty _swap.txt, remove atexit from swap script

The atexit handler in --swap mode caused immediate restore on process
exit, breaking standalone usage. Makefile trap and RTD post_build
handle restore reliably.

🤖 Generated by [robots](https://vyos.io)

* feat: activate quick-start as MyST canary via swap mechanism

Imports docs/md-quick-start.md from origin/myst/current and adds
quick-start to docs/_swap.txt. Validates the swap pipeline end-to-end
on one page: import_myst pulls the MD via git show, swap_sources
renames md-quick-start.md to quick-start.md, sphinx-build renders
quick-start.html with zero MD-specific warnings, and restore reverses
the rename cleanly.

🤖 Generated by [robots](https://vyos.io)

* feat: activate 106 visual-validated canaries via swap

Imports 105 MD files (plus quick-start already present) from
origin/myst/current and adds them to docs/_swap.txt. The selection
is the BackstopJS visual-passers cohort: pages with <5% rendered
diff vs the live RST docs at docs.vyos.io/en/latest/, filtered to
those with an RST counterpart on current and no cmdincludemd usage
(template-format reconciliation pending).

Local sphinx-build with all 106 swapped: succeeded with 100
warnings (vs 95 baseline). The 5 new warnings are all undefined
cross-reference labels, not build failures:
- contributing/development.md (missing 'coding-guidelines')
- operation/upgrade-recovery.md (3 missing 'how_it_works' /
  'cancelling_recovery')
- vpp/configuration/dataplane/{buffers,memory,unix}.md (missing
  'vpp_config_dataplane_*' labels)

Source list: ~/.claude/projects/-Users-vybot-GitHub-vyos-documentation/docs/2026-04-29-myst-conversion-audit/visual-passers-under-5pct.txt
BackstopJS report: claude/gifted-hertz-74b9f9 worktree
(visual-compare/), 2026-04-23 vs vyos--1838.org.readthedocs.build.

🤖 Generated by [robots](https://vyos.io)

* fix: re-import 4 canary md-*.md files with xref label fixes

Re-imports the dash-form-corrected versions of:
- contributing/md-development.md (added (coding-guidelines)= anchor)
- operation/md-upgrade-recovery.md (3 ref renames: how_it_works /
  cancelling_recovery -> dash form)
- vpp/configuration/dataplane/md-buffers.md (vpp_config_dataplane_physmem
  -> vpp-config-dataplane-physmem)
- vpp/configuration/dataplane/md-unix.md
  (vpp_config_dataplane_interface_rx_mode
  -> vpp-config-dataplane-interface-rx-mode)

Source: origin/myst/current commit 59fbe3ea. Verified locally: clean
swap-build no longer reports any of the 5 target labels (1 of 6 —
vpp-config-hugepages — remains because system.md isn't in the canary
swap list; that anchor lives there).

🤖 Generated by [robots](https://vyos.io)

* fix: re-add 4 canary md-*.md files deleted by 242b334a

Commit 242b334a accidentally staged deletions instead of modifications
because the working tree had unprefixed *.md files left over from an
incomplete swap-restore cycle. Re-imports the same 4 files from
origin/myst/current with the xref label fixes applied:

- contributing/md-development.md       — (coding-guidelines)= anchor
- operation/md-upgrade-recovery.md     — how_it_works → how-it-works,
                                         cancelling_recovery → cancelling-recovery
- vpp/configuration/dataplane/md-buffers.md — vpp_config_dataplane_physmem
                                              → vpp-config-dataplane-physmem
- vpp/configuration/dataplane/md-unix.md   — vpp_config_dataplane_interface_rx_mode
                                              → vpp-config-dataplane-interface-rx-mode

Source: origin/myst/current commit 59fbe3ea.

🤖 Generated by [robots](https://vyos.io)

* fix: resolve remaining xref label gaps in swap-active build

Three small additions clear the cross-reference warnings tied to
underscore-vs-dash label form mismatches and the vpp-config-hugepages
reference that previously needed system.md in the canary set.

- system.rst: add .. _vpp-config-hugepages: alongside the existing
  underscore label so memory.md references resolve regardless of
  whether system.md is swap-active.
- md-lcp.md: add (vpp_config_dataplane_lcp_ignore-kernel-routes)=
  alongside dash form (carries upstream from myst/current 079fa786).
- md-memory.md: add (vpp_config_dataplane_memory)= alongside dash
  form (also from myst/current 079fa786).

Local clean swap-build with 106 canaries:
  before: 305 warnings, 8 undefined-label entries in our scope
  after:  300 warnings, 0 undefined-label entries in our scope

Remaining undefined-label warnings (release-notes, prepare_commit)
are in documentation.rst and unrelated to the canary swap mechanism.

🤖 Generated by [robots](https://vyos.io)

* fix: re-add md-lcp.md and md-memory.md (deleted by 870c9e7e)

Same disaster pattern as 242b334a: a swap-restore cycle left
unprefixed *.md files in the working tree, and the subsequent
git add staged deletions instead of modifications. Restoring the
two affected md-*.md files from origin/myst/current 079fa786
(which has the dual underscore+dash anchors needed for the
swap-active build).

🤖 Generated by [robots](https://vyos.io)

* feat: expand canaries to 114; refresh 3 with cfgcmd body fix

Adds 8 new visual-validated canaries from the post-cfgcmd-fix
BackstopJS run (2026-04-29):

- configuration/policy/as-path-list
- configuration/policy/community-list
- configuration/policy/extcommunity-list
- configuration/policy/large-community-list
- configuration/policy/local-route
- configuration/policy/prefix-list
- configuration/service/salt-minion
- configuration/system/updates

Refreshes 3 existing canaries whose MD content changed via the
cfgcmd/opcmd single-line body fix on myst/current fc19ab5c:

- configuration/firewall/global-options
- configuration/firewall/groups
- configuration/policy/route

All 11 sourced from origin/myst/current. Net: 106 -> 114 canaries.

🤖 Generated by [robots](https://vyos.io)

* fix: re-import md-cloud-init.md (block 3 fix from myst/current)

🤖 Generated by [robots](https://vyos.io)

* feat(swap): import .md files and webp transition from myst/current

Selective import from origin/myst/current (cf9c9b34):
- Add/update 255 .md files (full MyST conversion plus webp ref updates)
- Delete 175 PNG/JPG from docs/_static/images (webp twins already present)
- Delete 5 autotest topology.png (webp twins already present)

Preserved on swap (untouched):
- All .rst files (incremental swap pattern)
- conf.py, _ext/, _include/*.txt, .gitignore
- 115 canary md-*.md files
- 7 superpowers/specs/*.md design docs
- Logos vyos-logo.png / vyos-logo-icon.png (referenced by conf.py)

🤖 Generated by [robots](https://vyos.io)

* chore(swap): remove canary md-*.md files and docs/superpowers

- Remove 115 canary md-*.md files (incremental swap helpers no longer needed)
- Remove 8 files under docs/superpowers (project planning/design docs that
  shouldn't ship in the documentation tree)

🤖 Generated by [robots](https://vyos.io)

* docs: address Copilot review feedback on imported MyST pages

Fix issues flagged by Copilot review on PR #1857 (the same content lives
in myst/current as the canonical source):

Real bugs:
- site-2-site-cisco.md: replace curly quote (U+2019) with ASCII apostrophe
- rsa-keys.md: fix typo "key-pair nam>>" → "key-pair name>"
- vmware.md: lowercase admonition directive (:::{NOTE} → :::{note})
- vpp/configuration/nat/index.md: remove blank line inside {include} fence

Grammar:
- vpp/configuration/interfaces/loopback.md: "bounded" → "bound"
- vpp/configuration/sflow.md: "VyOS support" → "VyOS supports"
- vpp/requirements.md: "bypass" → "bypasses"
- vpp/configuration/dataplane/interface.md: "configures" → "configure"

CI linter (IP addresses):
- nmp.md: wrap 8.8.8.8 example with stop/start_vyoslinter
- lac-lns.md: wrap LNS config block (contains 8.8.8.8)
- wan-load-balancing.md: wrap whole file (illustrative non-RFC IPs)
- policy/examples.md: replace 192.0.1.1 with RFC 5737 192.0.2.1

🤖 Generated by [robots](https://vyos.io)

* fix(swap): address Copilot review feedback on swap infrastructure

Category D — drop obsolete canary mechanism settings:
- conf.py: remove '**/md-*.md' from exclude_patterns (no canaries left)
- Makefile: replace malformed '*/_build/*' with '$(BUILDDIR)/**' and drop
  the '*/md-*' ignore (canary files no longer exist)

Category C — script robustness:
- import_myst.py:
  * list_myst_files() now raises SystemExit on git ls-tree failure instead
    of silently returning [] (would have masked typo'd --source refs)
  * list_rst_files() skips _build/ when scanning for .rst stems
  * import_page() rejects stems containing '..' or absolute paths and
    re-checks that the resolved destination stays under docs_dir
  * --dry-run uses a separate "would_import" counter; summary line now
    distinguishes dry-run from actual imports
- swap_sources.py:
  * parse_swap_list() reads with explicit encoding='utf-8'
  * do_restore() validates state file version + entry shape before
    renaming files; raises with actionable message on corruption
  * State file reads/writes use explicit encoding='utf-8' throughout

_swap.txt:
- Wrap long comment line to satisfy 80-character doc-linter limit

🤖 Generated by [robots](https://vyos.io)

* refactor(swap): rename imported .md files to md- prefix for swap mechanism

Restore the canary file naming convention that swap_sources.py expects:
the imported MyST pages now live as docs/<dir>/md-<name>.md alongside
the existing docs/<dir>/<name>.rst, so swap_sources.py --swap can rename
them into place at build time.

- 254 .md files renamed (every page with a matching .rst counterpart)
- 2 MyST-only pages left at their final names (no .rst exists, no swap
  needed): docs/copyright.md, docs/automation/terraform/terraformvyos.md

All 114 stems listed in docs/_swap.txt now have a corresponding
md-<name>.md source file ready to swap in.

🤖 Generated by [robots](https://vyos.io)

* docs: address CodeRabbit review feedback on imported MyST pages

Fix issues flagged by CodeRabbit on PR #1857. All issues are pre-existing
in the upstream RST docs and inherited by the MyST conversion.

Real bugs:
- inter-vrf-routing-vrf-lite.md: invalid IPv6 next-hop "2001:db8::*" →
  "2001:db8::1"
- ipsec-pa-route-based.md: vendor mislabel "Cisco" → "Palo Alto"
  (header on line 39 and "Monitoring on Cisco side" section heading)
- bgp-ipv6-unnumbered.md: AS number mismatch between configuration and
  verification output for both routers (Router A: 65020 → 64496;
  Router B: 65021 → 64499)
- qos.md: class 30 used "match ADDRESS20" instead of ADDRESS30 — broke
  the documented pattern (classes 10/20/30 → ADDRESS10/20/30)

Security:
- OpenVPN_with_LDAP.md: redact full PEM private key material from the
  three "set pki ... private key '...'" lines and from the embedded
  OpenVPN client <key> block; replace with <REDACTED> / ...REDACTED...
  placeholders. Public certificates retained.

🤖 Generated by [robots](https://vyos.io)

* feat(swap): default to serving MyST for all swapped pages

Replace the previously-curated 114-stem _swap.txt with the full set of
254 imported md-prefixed pages, so MD is served by default at build
time. To revert any specific page back to RST, remove its stem from
_swap.txt (or comment it out).

🤖 Generated by [robots](https://vyos.io)

* fix(ext): handle RST fallback in CmdInclude when _renderer absent

`cmdincludemd` is in `myst_fence_as_directive`, so MyST routes
fence blocks through `render_fence → render_restructuredtext →
MockRSTParser`. In that path `self.state` is a plain docutils Body
with no `_renderer`, crashing the build.

Fall back to `nested_parse` when `_renderer` is unavailable so the
directive works in both MyST and RST/MockRSTParser contexts.

🤖 Generated by [robots](https://vyos.io)

* feat(conf): copy .md sources into HTML output for plain-text serving

Adds a build-finished hook that mirrors every .md file from the Sphinx
source tree into the HTML output directory verbatim, making unrendered
MyST sources accessible alongside HTML renders at the same URL path.

🤖 Generated by [robots](https://vyos.io)

* docs: address review feedback from PR #1857

Fix conversion artifacts, typos, grammar errors, and technical
inaccuracies flagged by automated code review (Copilot + CodeRabbit).

Infrastructure: add root-level md-*.md exclusion to conf.py,
fix sphinx-autobuild ignore globs in Makefile.

Content: fix curly quotes, invalid Go panic() calls, shell quoting
in cURL examples, incorrect firewall command paths, typos across
22 documentation files, remove duplicate sections.

🤖 Generated by [robots](https://vyos.io)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

21 files changed, 7142 insertions, 0 deletions

diff --git a/docs/configuration/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md
new file mode 100644
index 00000000..7a07a27c
--- /dev/null
+++ b/docs/configuration/interfaces/md-bonding.md
@@ -0,0 +1,764 @@
+---
+lastproofread: '2025-12-09'
+---
+
+(bond-interface)=
+
+# Bond / link aggregation
+
+A **bonding interface** aggregates multiple network interfaces into a single
+logical interface (referred to as a bond, {abbr}`LAG (Link Aggregation Group)`,
+EtherChannel, or port-channel).
+
+The behavior of a bonding interface depends on the selected mode. Modes provide
+either fault tolerance or a combination of load balancing and fault tolerance.
+Additionally, the bonding interface can be configured for link integrity
+monitoring.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: bonding
+:var1: bond0
+```
+
+### Member interfaces
+
+```{cfgcmd} set interfaces bonding \<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
+
+````{cfgcmd} set interfaces bonding \<interface\> mode \<802.3ad | active-backup | broadcast | round-robin | transmit-load-balance | adaptive-load-balance | xor-hash\>
+
+```{eval-rst}
+**Configure the bonding mode on the interface. The default mode is**
+``802.3ad``.
+
+The available modes are:
+
+* ``802.3ad``
+
+.. list-table::
+   :widths: 20 80
+
+   * - **Description:**
+     - IEEE 802.3ad Dynamic Link Aggregation. Groups only member
+       interfaces with the same speed (e.g., 1 Gbps) and duplex
+       settings. Member interfaces with different speed and duplex
+       settings are not included in the active bond.
+
+       Provides load balancing and fault tolerance. Uses the
+       :abbr:`LACP (Link Aggregation Control Protocol)` to
+       negotiate the bond with the switch.
+   * - **Traffic distribution:**
+     - Traffic is distributed according to the **transmit hash
+       policy** (default: XOR).
+
+       The bonding driver applies an XOR operation to specific
+       packet header fields, generating a hash value that maps to
+       a particular member interface. This ensures the same network
+       flow is consistently transmitted over the same member
+       interface.
+
+       The transmit hash policy is configured via the ``hash-policy`` option.
+   * - **Failover:**
+     - If a member interface fails, the hash is recalculated to distribute
+       traffic among the remaining active member interfaces.
+
+.. note:: Not all transmit hash policies comply with 802.3ad, particularly
+   section 43.2.4. Using a non-compliant policy may result in out-of-order
+   packet delivery.
+
+* ``active-backup``
+
+.. list-table::
+   :widths: 20 80
+
+   * - **Description:**
+     - Provides fault tolerance. Only one member interface is active
+       at a time. Other member interfaces remain in a standby mode.
+   * - **Traffic distribution:**
+     - All traffic (incoming and outgoing) is routed via one active
+       member interface.
+   * - **Failover:**
+     - If the designated member interface fails, all traffic is
+       routed to another member interface. The bonding driver sends
+       a Gratuitous ARP to update the peer's MAC address table,
+       linking the bond's MAC address to another physical port.
+
+* ``broadcast``
+
+.. list-table::
+   :widths: 20 80
+
+   * - **Description:**
+     - Provides maximum fault tolerance by duplicating traffic.
+   * - **Traffic distribution:**
+     - Every packet is duplicated and transmitted on **all** member
+       interfaces.
+   * - **Failover:**
+     - Traffic flow is not interrupted as long as at least one
+       member interface remains active.
+
+* ``round-robin``
+
+.. list-table::
+   :widths: 20 80
+
+   * - **Description:**
+     - Provides load balancing and fault tolerance.
+   * - **Traffic distribution:**
+     - Packets are transmitted in sequential order across the member
+       interfaces (e.g., packet 1 > interface A, packet 2 >
+       interface B, etc.).
+   * - **Failover:**
+     - If a member interface fails, the sequence skips the failed
+       interface and continues with the remaining active members.
+
+* ``transmit-load-balance``
+
+.. list-table::
+   :widths: 20 80
+
+   * - **Description:**
+     - Provides adaptive transmit load balancing and fault tolerance.
+   * - **Traffic distribution:**
+     - **Outgoing:** Distributed across all active member interfaces
+       based on the current load.
+
+       **Incoming:** Received by a designated member interface
+       (active receiver).
+   * - **Failover:**
+     - If the active receiver fails, another member interface takes
+       over as the new active receiver.
+
+* ``adaptive-load-balance``
+
+.. list-table::
+   :widths: 20 80
+
+   * - **Description:**
+     - Provides adaptive transmit load balancing identical to
+       ``transmit-load-balance``, receive load balancing for IPv4
+       traffic, and fault tolerance for both incoming and outgoing
+       traffic.
+   * - **Traffic distribution:**
+     - **Outgoing:** Identical to ``transmit-load-balance``.
+
+       **Incoming:** Distributed based on ARP manipulation. For
+       both local and remote connections, the bonding driver
+       intercepts ARP traffic and changes the source MAC address
+       to the MAC address of the least loaded member interface.
+
+       All traffic from that peer is then routed to the chosen
+       member interface.
+   * - **Failover:**
+     - If a member interface's state changes (fails, recovers, is
+       added, or excluded), the traffic is redistributed among all
+       active member interfaces.
+
+* ``xor-hash``: Provides load balancing and fault tolerance
+  based on a hash formula. Distributes traffic and handles
+  failover identically to ``802.3ad``, but operates without
+  the :abbr:`LACP (Link Aggregation Control Protocol)`.
+```
+
+````
+
+```{cfgcmd} set interfaces bonding \<interface\> min-links \<0-16\>
+
+**Configure how many member interfaces must be active (in the
+link-up state) to mark the bonding interface UP (carrier
+asserted).**
+
+This command applies only when the bonding interface is configured
+in 802.3ad mode and functions like the Cisco EtherChannel min-links
+feature. It ensures that a bonding interface is marked UP (carrier
+asserted) only when a specified number of member interfaces are
+active (in the link-up state). This helps guarantee a minimum level
+of bandwidth for higher-level services (such as clustering) relying
+on the bonding interface.
+
+The default value is 0. This marks the bonding interface UP
+(carrier asserted) whenever an active LACP aggregator exists,
+regardless of the number of member interfaces in that aggregator.
+
+:::{note}
+In 802.3ad mode, a bond cannot be active without at least one active
+member interface. Therefore, setting min-links to 0 or 1 has the same result:
+the bonding interface is marked UP (carrier asserted).
+:::
+```
+
+```{cfgcmd} set interfaces bonding \<interface\> lacp-rate \<slow|fast\>
+
+**Configure the rate at which the bonding interface requests its link
+partner to send** {abbr}`LACPDUs (Link Aggregation Control Protocol Data
+Units)` **in 802.3ad mode.**
+
+This command applies only when the bonding interface is configured in
+802.3ad mode.
+
+The following options are available:
+
+* **slow (default):** Requests the link partner to transmit LACPDUs every 30 seconds.
+
+* **fast:** Requests the link partner to transmit LACPDUs every 1 second.
+```
+```{cfgcmd} set interfaces bonding \<interface\> system-mac \<mac address\>
+
+**Configure a specific MAC address for the bonding interface.**
+
+This sets the 802.3ad system MAC address, which is used for {abbr}`LACPDU (Link
+Aggregation Control Protocol Data Unit)` exchanges with the link partner.
+You can assign a fixed MAC address or generate a random one for these
+{abbr}`LACPDU (Link Aggregation Control Protocol Data Unit)` exchanges.
+```
+```{cfgcmd} set interfaces bonding \<interface\> hash-policy \<policy\>
+
+**Configure which transmit hash policy to use for distributing traffic across
+member interfaces.**
+
+The following policies are available:
+
+* ``layer2``
+
+**Description:** Routes all traffic destined for a specific network peer through
+the same member interface. The policy is 802.3ad-compliant.
+
+**Hash inputs:** Source MAC address, destination MAC address, and Ethernet packet
+type ID.
+
+**Formula:**
+
+:::{code-block} none
+hash = source MAC address XOR destination MAC address XOR packet type ID
+member interface number = hash modulo member interface count
+:::
+
+* ``layer2+3``
+
+**Description:** Similar to ``layer2``, routes all traffic destined for a specific
+network peer through the same member interface and is IEEE 802.3ad-compliant. Uses
+both Layer 2 and Layer 3 information to provide a more balanced traffic distribution.
+
+**Hash inputs:**
+* Source MAC address, destination MAC address, and Ethernet packet type ID.
+* Source IP address, destination IP address. IPv6 addresses are first hashed
+  using ``IPv6_addr_hash``.
+
+**Formula:**
+
+:::{code-block} none
+hash = source MAC address XOR destination MAC address XOR packet type ID
+hash = hash XOR source IP address XOR destination IP address
+hash = hash XOR (hash RSHIFT 16)
+hash = hash XOR (hash RSHIFT 8)
+member interface number = hash modulo member interface count
+:::
+
+For non-IP traffic, the formula is the same as for ``layer2``.
+
+* ``layer3+4``
+
+**Description:** Routes different connections (flows) destined for a specific
+network peer through multiple member interfaces, but ensures each individual
+flow is routed through only one member interface.
+
+:::{note}
+This policy is not fully 802.3ad-compliant. When a single TCP or UDP flow
+contains both fragmented and unfragmented packets, the algorithm may distribute
+them across different member interfaces. This may result in out-of-order packet
+delivery, violating the 802.3ad standard.
+:::
+
+**Hash inputs:**
+* Source port, destination port (if available).
+* Source IP address, destination IP address. IPv6 addresses are first hashed
+  using ``IPv6_addr_hash``.
+
+**Formula:**
+
+:::{code-block} none
+hash = source port, destination port (as in the header)
+hash = hash XOR source IP address XOR destination IP address
+hash = hash XOR (hash RSHIFT 16)
+hash = hash XOR (hash RSHIFT 8)
+member interface number = hash modulo member interface count
+:::
+
+For fragmented TCP or UDP packets and all other IPv4 and IPv6 traffic, the
+source and destination port information is omitted.
+
+For non-IP traffic, the formula is the same as for ``layer2``.
+```
+
+
+```{cfgcmd} set interfaces bonding \<interface\> primary \<interface\>
+
+**Configure the primary member interface in the bond.**
+
+The primary member interface remains active as long as it is operational;
+alternative member interfaces are used only if it fails.
+
+Use this configuration when a specific member interface is preferred,
+such as one with higher throughput.
+
+This command applies only to ``active-backup``, ``transmit-load-balance``, and
+``adaptive-load-balance`` modes.
+```
+
+
+```{cfgcmd} set interfaces bonding \<interface\> arp-monitor interval \<time\>
+
+**Configure the ARP monitoring interval, in seconds, for the bonding interface.**
+
+ARP monitoring periodically assesses the health of each member interface by
+checking whether it has recently sent or received traffic (this criterion
+varies depending on the bonding mode and the member interface’s state). ARP
+probes are sent to the IP addresses specified with the arp-monitor target option.
+
+When ARP monitoring is used with EtherChannel-compatible modes (such as
+``round-robin`` or ``xor-hash``), the switch should be configured to distribute
+traffic across all member interfaces. If the switch distributes traffic using
+an XOR-based policy, all ARP replies will be received on one member interface,
+causing other member interfaces to be incorrectly marked as failed.
+
+Setting this value to 0 disables ARP monitoring.
+
+The default value is 0.
+```
+
+
+```{cfgcmd} set interfaces bonding \<interface\> arp-monitor target \<address\>
+
+**Configure the IP addresses for ARP monitoring requests.**
+
+The bonding driver sends ARP requests to these IP addresses to check the
+state of member interfaces.
+
+To enable ARP monitoring, configure at least one IP address (up to 16 per
+bonding interface).
+
+By default, no IP addresses are configured.
+```
+
+### {abbr}`VLAN (Virtual Local Area Network)`
+
+```{cmdincludemd} /_include/interface-vlan-8021q.txt
+:var0: bonding
+:var1: bond0
+```
+
+### SPAN port mirroring
+
+```{cmdincludemd} ../../_include/interface-mirror.txt
+:var0: bonding
+:var1: bond1
+:var2: eth3
+```
+
+#### EVPN multihoming
+
+
+EVPN multihoming (EVPN-MH) is a standards-based solution (RFC 7432, RFC 8365)
+that enables Customer Edge (CE) devices, such as servers, to connect to two
+or more Provider Edge (PE) devices for redundancy and load balancing.
+
+
+EVPN-MH is often used as a modern, standards-based alternative to
+{abbr}`MLAG (Multi-Chassis Link Aggregation)` and {abbr}`VTEPs (Virtual
+Tunnel Endpoints)`.
+
+
+**Ethernet Segment (ES) and Ethernet Segment Identifier (ESI)**
+
+
+Physical links that connect a CE device to PE devices are bundled using link
+aggregation. This logical bundle is called an Ethernet Segment (ES) and is
+uniquely identified by an Ethernet Segment Identifier (ESI) within the
+EVPN domain.
+
+
+To enable EVPN-MH, configure the same ESI on the bonding interfaces of all
+PE devices connected to a single CE device.
+
+
+An ESI is configured by specifying either a system MAC address and a local
+discriminator, or an Ethernet Segment Identifier Name (ESINAME).
+
+
+The following two commands generate a 10-byte Type-3 ESI by combining the
+system MAC and local discriminator:
+
+```{cfgcmd} set interfaces bonding \<interface\> evpn es-id \<1-16777215|10-byte ID\>
+
+```
+```{cfgcmd} set interfaces bonding \<interface\> evpn es-sys-mac \<xx:xx:xx:xx:xx:xx\>
+
+Alternatively, assign an ESINAME directly as a 10-byte Type-0 ESI using the
+following format: 00:AA:BB:CC:DD:EE:FF:GG:HH:II.
+
+**BGP-EVPN route usage**
+
+EVPN-MH uses BGP-EVPN route types 1 and 2 for ES discovery and MAC-IP
+synchronization:
+
+* **Type 1 (EAD-per-ES and EAD-per-EVI)** routes advertise the locally
+attached ESs and discover remote ESs in the network.
+* **Type 2 (MAC-IP advertisement)** routes are advertised with a
+destination ESI, enabling MAC-IP synchronization between ES peers.
+```
+
+```{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.
+```
+
+```{cmdincludemd} /_include/interface-evpn-uplink.txt
+:var0: bonding
+:var1: bond0
+```
+
+## Example
+
+
+The following configuration example applies to all listed third-party vendors.
+It creates a bonding interface with two member interfaces, defines VLANs 10
+and 100 on the bonding interface, and assigns an IPv4 address to each VLAN
+subinterface.
+
+```none
+# Create the bonding interface bond0 with 802.3ad LACP
+set interfaces bonding bond0 hash-policy 'layer2'
+set interfaces bonding bond0 mode '802.3ad'
+
+# Add the required VLANs and IPv4 addresses on them
+set interfaces bonding bond0 vif 10 address 192.168.0.1/24
+set interfaces bonding bond0 vif 100 address 10.10.10.1/24
+
+# Add the member interfaces to the bonding interface
+set interfaces bonding bond0 member interface eth1
+set interfaces bonding bond0 member interface eth2
+```
+:::{note}
+If you are running this configuration in a virtual environment like
+EVE-NG, ensure the e1000 driver is chosen for your VyOS NIC. The default
+drivers, such as ``virtio-net-pci`` or ``vmxnet3``, are incompatible with
+this configuration. Specifically, ICMP messages will not be processed
+correctly.
+
+To check your NIC driver, use the following command:
+``show interfaces ethernet eth0 physical | grep -i driver``
+:::
+
+
+### Cisco Catalyst configuration
+
+
+Configure a Cisco Catalyst switch to integrate with a two-member VyOS bonding
+interface.
+
+
+Assign member interfaces to PortChannel:
+
+```none
+interface GigabitEthernet1/0/23
+ description VyOS eth1
+ channel-group 1 mode active
+!
+interface GigabitEthernet1/0/24
+ description VyOS eth2
+ channel-group 1 mode active
+!
+```
+
+A new interface, `Port-channel1`, becomes available; all configuration,
+such as allowed VLAN interfaces and STP, is applied here.
+
+```none
+interface Port-channel1
+ description LACP Channel for VyOS
+ switchport trunk encapsulation dot1q
+ switchport trunk allowed vlan 10,100
+ switchport mode trunk
+ spanning-tree portfast trunk
+!
+```
+
+### Juniper EX Switch configuration
+
+
+Configure a Juniper EX Series switch to integrate with a two-member VyOS bonding
+interface.
+
+```none
+# Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s
+set interfaces ae0 aggregated-ether-options link-speed 10g
+set interfaces ae0 aggregated-ether-options lacp active
+
+# Create layer 2 on the aggregated ethernet device with trunking for our VLANs
+set interfaces ae0 unit 0 family ethernet-switching port-mode trunk
+
+# Add the required vlans to the device
+set interfaces ae0 unit 0 family ethernet-switching vlan members 10
+set interfaces ae0 unit 0 family ethernet-switching vlan members 100
+
+# Add the two interfaces to the aggregated ethernet device, in this setup both
+# ports are on the same switch (switch 0, module 1, port 0 and 1)
+set interfaces xe-0/1/0 ether-options 802.3ad ae0
+set interfaces xe-0/1/1 ether-options 802.3ad ae0
+
+# But this can also be done with multiple switches in a stack, a virtual
+# chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches)
+set interfaces xe-0/1/0 ether-options 802.3ad ae0
+set interfaces xe-1/1/0 ether-options 802.3ad ae0
+```
+
+### Aruba/HP configuration
+
+
+Configure an Aruba/HP 2510G switch to integrate with a two-member VyOS bonding
+interface.
+
+```none
+# Create trunk with 2 member interfaces (interface 1 and 2) and LACP
+trunk 1-2 Trk1 LACP
+
+# Add the required VLANs to the trunk
+vlan 10 tagged Trk1
+vlan 100 tagged Trk1
+```
+
+### Arista EOS configuration
+
+
+When deploying VyOS in environments with Arista switches, use the following
+blueprint as an initial setup to configure an operational LACP port-channel
+between the two devices.
+
+
+Let's assume the following topology:
+
+
+```{eval-rst}
+.. figure:: /_static/images/vyos_arista_bond_lacp.webp
+   :alt: VyOS Arista EOS setup
+```
+
+
+**R1**
+
+```none
+interfaces {
+    bonding bond10 {
+        hash-policy layer3+4
+        member {
+            interface eth1
+            interface eth2
+        }
+        mode 802.3ad
+        vif 100 {
+            address 192.0.2.1/30
+            address 2001:db8::1/64
+        }
+    }
+```
+**R2**
+
+
+
+```none
+interfaces {
+    bonding bond10 {
+        hash-policy layer3+4
+        member {
+            interface eth1
+            interface eth2
+        }
+        mode 802.3ad
+        vif 100 {
+            address 192.0.2.2/30
+            address 2001:db8::2/64
+        }
+    }
+```
+**SW1**
+
+```none
+!
+vlan 100
+   name FOO
+!
+interface Port-Channel10
+   switchport trunk allowed vlan 100
+   switchport mode trunk
+   spanning-tree portfast
+!
+interface Port-Channel20
+   switchport mode trunk
+   no spanning-tree portfast auto
+   spanning-tree portfast network
+!
+interface Ethernet1
+   channel-group 10 mode active
+!
+interface Ethernet2
+   channel-group 10 mode active
+!
+interface Ethernet3
+   channel-group 20 mode active
+!
+interface Ethernet4
+   channel-group 20 mode active
+!
+```
+**SW2**
+
+
+
+```none
+!
+vlan 100
+   name FOO
+!
+interface Port-Channel10
+   switchport trunk allowed vlan 100
+   switchport mode trunk
+   spanning-tree portfast
+!
+interface Port-Channel20
+   switchport mode trunk
+   no spanning-tree portfast auto
+   spanning-tree portfast network
+!
+interface Ethernet1
+   channel-group 10 mode active
+!
+interface Ethernet2
+   channel-group 10 mode active
+!
+interface Ethernet3
+   channel-group 20 mode active
+!
+interface Ethernet4
+   channel-group 20 mode active
+!
+```
+:::{note}
+When testing this environment in EVE-NG, ensure the e1000 driver
+is chosen for your VyOS network interfaces. If the default virtio driver
+is used, VyOS will not transmit LACP PDUs, preventing the port-channel
+from ever becoming active.
+:::
+
+
+(operation)=
+
+## Operation
+
+```{opcmd} show interfaces bonding
+
+Show brief interface information.
+
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces bonding
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+bond0            -                                 u/u  my-sw1 int 23 and 24
+bond0.10         192.168.0.1/24                    u/u  office-net
+bond0.100        10.10.10.1/24                     u/u  management-net
+:::
+```
+```{opcmd} show interfaces bonding \<interface\>
+
+Show detailed interface information.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces bonding bond5
+bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000
+    link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff
+    inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative
+       valid_lft forever preferred_lft forever
+
+    RX:  bytes  packets  errors  dropped  overrun       mcast
+             0        0       0        0        0           0
+    TX:  bytes  packets  errors  dropped  carrier  collisions
+             0        0       0        0        0           0
+:::
+```
+```{opcmd} show interfaces bonding \<interface\> detail
+
+Show detailed information about the underlying physical links on the given
+bonding interface.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces bonding bond5 detail
+Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011)
+Bonding Mode: IEEE 802.3ad Dynamic link aggregation
+Transmit Hash Policy: layer2 (0)
+MII Status: down
+MII Polling Interval (ms): 100
+Up Delay (ms): 0
+Down Delay (ms): 0
+802.3ad info
+LACP rate: slow
+Min links: 0
+Aggregator selection policy (ad_select): stable
+Slave Interface: eth1
+MII Status: down
+Speed: Unknown
+Duplex: Unknown
+Link Failure Count: 0
+Permanent HW addr: 00:50:56:bf:ef:aa
+Slave queue ID: 0
+Aggregator ID: 1
+Actor Churn State: churned
+Partner Churn State: churned
+Actor Churned Count: 1
+Partner Churned Count: 1
+Slave Interface: eth2
+MII Status: down
+Speed: Unknown
+Duplex: Unknown
+Link Failure Count: 0
+Permanent HW addr: 00:50:56:bf:19:26
+Slave queue ID: 0
+Aggregator ID: 2
+Actor Churn State: churned
+Partner Churn State: churned
+Actor Churned Count: 1
+Partner Churned Count: 1
+:::
+```
\ No newline at end of file
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..817e6868
--- /dev/null
+++ b/docs/configuration/interfaces/md-openvpn-examples.md
@@ -0,0 +1,769 @@
+# Site-to-site
+
+:::{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd directives for command coverage tracking.
+:::
+
+OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, it is effective for quickly establishing tunnels between routers.
+
+As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates.
+
+Pre-shared key mode is now deprecated and will be removed from future OpenVPN versions. VyOS will also discontinue support for this option because pre-shared keys are significantly less secure than TLS.
+
+We will configure OpenVPN with self-signed certificates, and then discuss the legacy pre-shared key mode.
+
+In both cases, we will use the following settings:
+
+- The public IP address of the local VPN endpoint is 198.51.100.10.
+- The public IP address of the remote VPN endpoint is 203.0.113.11.
+- The tunnel uses 10.255.1.1 for the local IP address and 10.255.1.2 for the remote IP address.
+- The local site has a subnet of 10.0.0.0/16.
+- The remote site has a subnet of 10.1.0.0/16.
+- The official OpenVPN port 1194 is reserved for client VPN. For site-to-site VPN, port 1195 is used.
+- The `persistent-tunnel` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface.
+- If known, the remote router\'s IP address can be configured using the `remote-host` directive. If unknown, it can be omitted. We assume the remote router has a dynamic IP address.
+
+![](/_static/images/openvpn_site2site_diagram.webp)
+
+## Set up site-to-site certificates
+
+Deploying a complete Public Key Infrastructure (PKI) with a Certificate Authority (CA) would overcomplicate site-to-site OpenVPN setups, which are primarily designed for simplicity. To keep their configuration simple without compromising security, VyOS 1.4 and later lets you verify self-signed certificates using certificate fingerprints.
+
+Generate a self-signed certificate on each router, preferably using the Elliptic Curve (EC) type. In configuration mode, run the following command: `run generate pki certificate self-signed install <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
+```
+
+::::{note}
+Certificate names are arbitrary. While `openvpn-local` and `openvpn-remote` are used here, you may choose any names.
+::::
+
+Repeat the procedure on the other router.
+
+## Set up site-to-site OpenVPN
+
+Local configuration:
+
+``` none
+Configure the tunnel:
+
+set interfaces openvpn vtun1 mode site-to-site
+set interfaces openvpn vtun1 protocol udp
+set interfaces openvpn vtun1 persistent-tunnel
+set interfaces openvpn vtun1 remote-host '203.0.113.11'                         # Public IP of the other side
+set interfaces openvpn vtun1 local-port '1195'
+set interfaces openvpn vtun1 remote-port '1195'
+set interfaces openvpn vtun1 local-address '10.255.1.1'                         # Local IP of vtun interface
+set interfaces openvpn vtun1 remote-address '10.255.1.2'                        # Remote IP of vtun interface
+set interfaces openvpn vtun1 tls certificate 'openvpn-local'                    # The self-signed certificate
+set interfaces openvpn vtun1 tls peer-fingerprint <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 {ref}`configuration/pki/index:pki`.
+
+## Set up server-client OpenVPN
+
+The following example demonstrates the most complicated scenario: each client acts as a router with its own subnet (e.g., an HQ and multiple branch offices). Simpler setups are subsets of it.
+
+In this scenario, the 10.23.1.0/24 network is used for client tunnel endpoints, and all client subnets belong to 10.23.0.0/20. Each client needs access to the 192.168.0.0/16 network.
+
+Server configuration:
+
+``` none
+set interfaces openvpn vtun10 encryption data-ciphers 'aes256'
+set interfaces openvpn vtun10 hash 'sha512'
+set interfaces openvpn vtun10 local-host '172.18.201.10'
+set interfaces openvpn vtun10 local-port '1194'
+set interfaces openvpn vtun10 mode 'server'
+set interfaces openvpn vtun10 persistent-tunnel
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 server client client1 ip '10.23.1.10'
+set interfaces openvpn vtun10 server client client1 subnet '10.23.2.0/25'
+set interfaces openvpn vtun10 server domain-name 'vyos.net'
+set interfaces openvpn vtun10 server max-connections '250'
+set interfaces openvpn vtun10 server name-server '172.16.254.30'
+set interfaces openvpn vtun10 server subnet '10.23.1.0/24'
+set interfaces openvpn vtun10 server topology 'subnet'
+set interfaces openvpn vtun10 tls ca-certificate ca-1
+set interfaces openvpn vtun10 tls certificate srv-1
+set interfaces openvpn vtun10 tls dh-params dh-1
+```
+
+The configuration above uses the default 1194/UDP port, 256-bit AES encryption, SHA-512 for HMAC authentication, and the persistent-tunnel option. Persistent-tunnel is recommended as it keeps the TUN/TAP device active during connection resets or daemon reloads. Clients are identified by the CN attribute in their SSL certificates.
+
+To grant clients access to a specific network behind the router, use the push-route option to automatically install the appropriate route on each client.
+
+``` none
+set interfaces openvpn vtun10 server push-route 192.168.0.0/16
+```
+
+OpenVPN does not automatically create kernel routes for client subnets when clients connect; it only uses client-subnet association internally. Therefore, you must manually create a route to the 10.23.0.0/20 network:
+
+``` none
+set protocols static route 10.23.0.0/20 interface vtun10
+```
+
+
+## Set up OpenVPN client
+
+VyOS can operate not only as an OpenVPN site-to-site peer or a server for multiple clients, but also as an OpenVPN client. Any VyOS OpenVPN interface can be configured to connect to another VyOS or third-party OpenVPN server.
+
+Client configuration:
+
+``` none
+set interfaces openvpn vtun10 encryption data-ciphers 'aes256'
+set interfaces openvpn vtun10 hash 'sha512'
+set interfaces openvpn vtun10 mode 'client'
+set interfaces openvpn vtun10 persistent-tunnel
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 remote-host '172.18.201.10'
+set interfaces openvpn vtun10 remote-port '1194'
+set interfaces openvpn vtun10 tls ca-certificate ca-1
+set interfaces openvpn vtun10 tls certificate client1
+```
+
+
+## Verification
+
+Check the tunnel status:
+
+``` none
+vyos@vyos:~$ show openvpn server
+
+OpenVPN status on vtun10
+
+Client CN    Remote Host         Tunnel IP    Local Host        TX bytes    RX bytes    Connected Since
+-----------  ------------------  -----------  ----------------  ----------  ----------  -------------------
+client1      172.16.12.54:33166  10.23.1.10   172.18.201.10:1194  3.4 KB      3.4 KB      2024-06-11 12:07:25
+```
+
+
+### Server bridge
+
+In Ethernet bridging configurations, an OpenVPN interface operating in server mode with the device type set to TAP can be added to a bridge. By encapsulating entire Ethernet frames (up to 1514 bytes) rather than just IP packets (up to 1500 bytes), this setup enables clients to transmit Layer 2 frames through the OpenVPN tunnel.
+
+The following is a basic configuration example:
+
+Server side:
+
+``` none
+set interfaces bridge br10 member interface eth1.10
+set interfaces bridge br10 member interface vtun10
+set interfaces openvpn vtun10 device-type 'tap'
+set interfaces openvpn vtun10 encryption data-ciphers 'aes192'
+set interfaces openvpn vtun10 hash 'sha256'
+set interfaces openvpn vtun10 local-host '172.18.201.10'
+set interfaces openvpn vtun10 local-port '1194'
+set interfaces openvpn vtun10 mode 'server'
+set interfaces openvpn vtun10 server bridge gateway '10.10.0.1'
+set interfaces openvpn vtun10 server bridge start '10.10.0.100'
+set interfaces openvpn vtun10 server bridge stop '10.10.0.200'
+set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0'
+set interfaces openvpn vtun10 server topology 'subnet'
+set interfaces openvpn vtun10 tls ca-certificate 'ca-1'
+set interfaces openvpn vtun10 tls certificate 'srv-1'
+set interfaces openvpn vtun10 tls dh-params 'dh-1'
+```
+
+Client side:
+
+``` none
+set interfaces openvpn vtun10 device-type 'tap'
+set interfaces openvpn vtun10 encryption data-ciphers 'aes192'
+set interfaces openvpn vtun10 hash 'sha256'
+set interfaces openvpn vtun10 mode 'client'
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 remote-host '172.18.201.10'
+set interfaces openvpn vtun10 remote-port '1194'
+set interfaces openvpn vtun10 tls ca-certificate 'ca-1'
+set interfaces openvpn vtun10 tls certificate 'client-1'
+```
+
+
+### Server LDAP authentication
+
+## LDAP
+
+Enterprise installations usually include a directory service to centralize employee password management. VyOS and OpenVPN support using LDAP and Active Directory as a single user backend.
+
+Authentication is performed by the `openvpn-auth-ldap.so` plugin, included with every VyOS installation. To use it, you must create a dedicated configuration file.
+**Best practice:** Store the configuration file in the `/config` directory to ensure it is preserved after image updates.
+
+``` none
+set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config"
+```
+
+A sample configuration file is shown below:
+
+``` none
+<LDAP>
+# 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 {doc}`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..9c9885d2
--- /dev/null
+++ b/docs/configuration/interfaces/md-tunnel.md
@@ -0,0 +1,309 @@
+---
+lastproofread: '2026-01-23'
+---
+
+(tunnel-interface)=
+
+# Tunnel
+
+Tunnel interfaces are virtual links that transmit encapsulated traffic between
+private networks or hosts across public infrastructure, such as the Internet.
+They operate using encapsulation protocols to wrap original traffic for
+transport. The supported protocols include {abbr}`GRE (Generic Routing
+Encapsulation)`, IPIP, IPIP6, IP6IP6, and 6in4 (SIT).
+
+While {abbr}`GRE (Generic Routing Encapsulation)` is often the preferred
+one-size-fits-all solution due to its versatility, other encapsulation
+protocols may be better suited for specific use cases.
+
+VyOS uses a single tunnel interface type for all of these protocols. There are
+no separate {abbr}`GRE (Generic Routing Encapsulation)`, IPIP, or IP6IP6
+interface types; instead, the desired encapsulation protocol is selected within
+the `set interfaces tunnel` configuration.
+
+Configuration options for each protocol are described below.
+
+:::{warning}
+Do not change the encapsulation type for already configured tunnel
+interfaces, as this may break their dependent configurations.
+:::
+
+## Common interface configuration
+
+```{cmdincludemd} /_include/interface-address.txt
+:var0: tunnel
+:var1: tun0
+```
+
+```{cmdincludemd} /_include/interface-common-without-mac.txt
+:var0: tunnel
+:var1: tun0
+```
+
+
+## IPIP
+
+IPIP is a straightforward encapsulation protocol defined in RFC 2003. It
+encapsulates one IPv4 packet inside another IPv4 packet.
+
+Tunnels with IPIP encapsulation do not have protocol-specific configuration
+options except for explicitly defining the encapsulation type as IPIP (see
+the example below).
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation ipip
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 203.0.113.20
+set interfaces tunnel tun0 address 192.168.100.200/24
+```
+
+
+## IP6IP6
+
+IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside
+another IPv6 packet.
+
+Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not
+have protocol-specific configuration options except for explicitly defining
+the encapsulation type as IP6IP6.
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation ip6ip6
+set interfaces tunnel tun0 source-address 2001:db8:aa::1
+set interfaces tunnel tun0 remote 2001:db8:aa::2
+set interfaces tunnel tun0 address 2001:db8:bb::1/64
+```
+
+
+## IPIP6
+
+IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets.
+
+Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with
+IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6.
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation ipip6
+set interfaces tunnel tun0 source-address 2001:db8:aa::1
+set interfaces tunnel tun0 remote 2001:db8:aa::2
+set interfaces tunnel tun0 address 192.168.70.80/24
+```
+
+
+## 6in4 (SIT)
+
+6in4, also known as {abbr}`SIT (Simple Internet Transition)`, is an
+encapsulation protocol defined in {rfc}`4213` that wraps IPv6 packets
+inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41,
+which is reserved exclusively for IPv6 encapsulation.
+
+The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet.
+Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes
+over an underlying network with a standard MTU of 1500 bytes without
+fragmentation.
+
+6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as
+[Hurricane Electric]) to connect isolated IPv6 networks or individual hosts to
+the IPv6 internet.
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation sit
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 192.0.2.20
+set interfaces tunnel tun0 address 2001:db8:bb::1/64
+```
+
+:::{seealso}
+For a practical configuration example, see the
+{ref}`Tunnelbroker.net (IPv6) <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..dbd2c88c
--- /dev/null
+++ b/docs/configuration/interfaces/md-vti.md
@@ -0,0 +1,121 @@
+(vti-interface)=
+
+# VTI (virtual tunnel interface)
+
+{abbr}`VTIs (virtual tunnel interfaces)` let you create secure, encrypted
+tunnels between private networks or hosts across public infrastructure, such as
+the Internet. They operate alongside an underlying IPsec tunnel, which handles
+encapsulation and encryption, while VTIs function exclusively as routing
+interfaces.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cmdincludemd} /_include/interface-ip.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cmdincludemd} /_include/interface-ipv6.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cmdincludemd} /_include/interface-mtu.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cfgcmd} set interfaces vti \<interface\> mirror egress \<monitor-interface\>
+
+Configure mirroring of outgoing traffic from the specified VTI to the
+designated monitor interface.
+```
+
+```{cfgcmd} set interfaces vti \<interface\> mirror ingress \<monitor-interface\>
+
+Configure mirroring of incoming traffic from the specified VTI to the
+designated monitor interface.
+```
+
+```{cfgcmd} set interfaces vti \<interface\> redirect \<interface\>
+
+Enable redirection of incoming packets to the specified interface.
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: vti
+:var1: vti0
+```
+
+
+## Operation
+
+```{opcmd} show interfaces vti \<vtiX\>
+
+Show the operational status and traffic statistics for the specified VTI.
+```
+
+```{opcmd} show interfaces vti \<vtiX\> brief
+
+Show a brief operational status summary for the specified VTI.
+```
+
+
+## Example
+
+**Configure a VTI**
+
+Assign IPv4 and IPv6 addresses to the VTI, along with a brief description:
+
+```none
+set interfaces vti vti0 address 192.168.2.249/30
+set interfaces vti vti0 address 2001:db8:2::249/64
+set interfaces vti vti0 description "Description"
+```
+
+Resulting configuration:
+
+```none
+vyos@vyos# show interfaces vti
+vti vti0 {
+    address 192.168.2.249/30
+    address 2001:db8:2::249/64
+    description "Description"
+}
+```
+
+:::{warning}
+When configuring site-to-site IPsec with VTIs, ensure that route
+autoinstall is disabled.
+:::
+
+```none
+set vpn ipsec options disable-route-autoinstall
+```
+
+For more information about the IPsec and VTI issue, as well as the
+`disable-route-autoinstall` option, see:
+<https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july.>
+
+The root cause of the problem is that VTI tunnels require their traffic
+selectors to be set to `0.0.0.0/0` for traffic to match the tunnel, even
+though routing decisions are based on netfilter marks. Unless route insertion
+is explicitly disabled, strongSWAN incorrectly inserts a default route through
+the VTI peer address, causing all traffic to be misrouted.
diff --git a/docs/configuration/interfaces/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..121d1df0
--- /dev/null
+++ b/docs/configuration/interfaces/md-wireguard.md
@@ -0,0 +1,434 @@
+---
+lastproofread: '2026-03-02'
+---
+
+(wireguard)=
+
+# WireGuard
+
+WireGuard is an extremely simple, fast, and modern VPN that utilizes
+state-of-the-art cryptography. See <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
+
+```{opcmd} generate pki wireguard key-pair
+
+Generate a keypair: a public and a private key.
+
+:::{note}
+This command only outputs the keys to your console. It neither stores
+them in the system nor applies them to the system configuration.
+:::
+
+:::{code-block} none
+vyos@vyos:~$ generate pki wireguard key-pair
+Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=
+Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=
+:::
+```
+
+
+```{opcmd} generate pki wireguard key-pair install interface \<interface\>
+
+Generate a keypair and output the private key assignment command for the
+specified interface.
+
+:::{code-block} none
+vyos@vyos:~$ generate pki wireguard key-pair install interface wg10
+"generate" CLI command executed from operational level.
+Generated private key is not automatically added to the VyOS configuration, use the following configuration mode commands to install key:
+
+set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0='
+
+Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro='
+:::
+
+:::{note}
+If you invoke this command from configuration mode with the ``run``
+prefix, the generated private key is automatically assigned to the specified
+interface.
+:::
+
+:::{code-block} none
+vyos@vyos# run generate pki wireguard key-pair install interface wg10
+"generate" CLI command executed from config session.
+Generated private-key was imported to CLI!
+
+Use the following command to verify: show interfaces wireguard wg10
+Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8='
+
+vyos@vyos# compare
+[edit interfaces]
++wireguard wg10 {
++    private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc=
++}
+:::
+```
+
+
+```{opcmd} show interfaces wireguard \<interface\> public-key
+
+Show the public key assigned to the interface.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces wireguard wg01 public-key
+EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=
+:::
+```
+
+#### Optional
+
+```{opcmd} generate pki wireguard preshared-key
+
+Generate a pre-shared key.
+
+The pre-shared key is optional. It adds an additional layer of symmetric-key
+cryptography on top of the asymmetric cryptography.
+
+:::{code-block} none
+vyos@vyos:~$ generate pki wireguard preshared-key
+Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs=
+:::
+```
+
+```{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].
+:::
+
+```{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`.
+```
+
+
+```{cmdincludemd} /_include/interface-per-client-thread.txt
+:var0: wireguard
+:var1: wg01
+```
+
+**Remote side configuration**
+
+```none
+set interfaces wireguard wg01 address '10.1.0.2/30'
+set interfaces wireguard wg01 description 'VPN-to-wg01'
+set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24'
+set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2'
+set interfaces wireguard wg01 peer to-wg01 port '51820'
+set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw='
+set interfaces wireguard wg01 port '51820'
+set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU='
+
+set protocols static route 192.168.1.0/24 interface wg01
+```
+
+## Firewall exceptions
+
+
+To allow WireGuard traffic through the WAN interface, create a firewall
+exception:
+
+```none
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related'
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable
+set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable
+set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp
+```
+
+Ensure that the OUTSIDE_LOCAL firewall group is applied to the WAN interface
+and in an input (local) direction.
+
+```none
+set firewall ipv4 input filter rule 10 action jump
+set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL'
+set firewall ipv4 input filter rule 10 inbound-interface name 'eth0'
+```
+
+Verify that your firewall rules permit traffic. If so, your WireGuard VPN
+should be operational.
+
+```none
+wg01# ping 192.168.1.1
+PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data.
+64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms
+64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms
+
+wg02# ping 192.168.2.1
+PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data.
+64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms
+64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms
+```
+
+An additional layer of symmetric-key cryptography can be used on top of the
+asymmetric cryptography. This is optional.
+
+```none
+vyos@vyos:~$ generate pki wireguard preshared-key
+Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=
+```
+
+Copy the key, as it is not stored locally. Since it is a symmetric key, only
+you and your peer should know its contents. Distribute the key securely.
+
+```none
+wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
+wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
+```
+
+## Remote access (road warrior)
+
+
+With WireGuard, a road warrior VPN configuration is similar to a site-to-site
+VPN. It just omits the `address` and `port` statements.
+
+
+In the following example, the IP addresses for remote clients are defined
+within each peer configuration. This allows peers to communicate with each
+other.
+
+
+Additionally, this setup uses a `persistent-keepalive` flag set to 15 seconds
+to keep the connection alive. This setting is mainly relevant if a peer is
+behind NAT and cannot be reached if the connection is lost. For effectiveness,
+the value should be lower than the UDP timeout.
+
+```none
+wireguard wg01 {
+    address 10.172.24.1/24
+    address 2001:db8:470:22::1/64
+    description RoadWarrior
+    peer MacBook {
+        allowed-ips 10.172.24.30/32
+        allowed-ips 2001:db8:470:22::30/128
+        persistent-keepalive 15
+        pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc=
+    }
+    peer iPhone {
+        allowed-ips 10.172.24.20/32
+        allowed-ips 2001:db8:470:22::20/128
+        persistent-keepalive 15
+        pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00=
+    }
+    port 2224
+    private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=
+}
+```
+
+Below is the configuration for the iPhone peer. The `AllowedIPs` wildcard
+setting directs all IPv4 and IPv6 traffic through the VPN connection.
+
+```none
+[Interface]
+PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf=
+Address = 10.172.24.20/24, 2001:db8:470:22::20/64
+DNS = 10.0.0.53, 10.0.0.54
+
+[Peer]
+PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc=
+AllowedIPs = 0.0.0.0/0, ::/0
+Endpoint = 192.0.2.1:2224
+PersistentKeepalive = 15
+```
+
+To enable split tunneling, specify the remote subnets. This ensures that only
+traffic destined for the remote site is sent through the tunnel, while all
+other traffic remains unaffected.
+
+```none
+[Interface]
+PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go=
+Address = 10.172.24.30/24, 2001:db8:470:22::30/64
+
+[Peer]
+PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc=
+AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64
+Endpoint = 192.0.2.1:2224
+PersistentKeepalive = 15
+```
+
+## Operational commands
+
+
+### Status
+
+```{opcmd} show interfaces wireguard wg01 summary
+
+Show information about the WireGuard service, including the latest handshake.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces wireguard wg01 summary
+interface: wg01
+public key:
+private key: (hidden)
+listening port: 51820
+
+peer: <peer pubkey>
+endpoint: <peer public IP>
+allowed ips: 10.69.69.2/32
+latest handshake: 23 hours, 45 minutes, 26 seconds ago
+transfer: 1.26 MiB received, 6.47 MiB sent
+:::
+```
+
+
+```{opcmd} show interfaces wireguard
+
+Show a list of all WireGuard interfaces.
+
+:::{code-block} none
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+wg01             10.0.0.1/24                       u/u
+:::
+```
+
+```{opcmd} show interfaces wireguard \<interface\>
+
+Show general information about a specific WireGuard interface.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces wireguard wg01
+interface: wg01
+address: 10.0.0.1/24
+public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE=
+private key: (hidden)
+listening port: 41751
+RX:  bytes  packets  errors  dropped  overrun       mcast
+0        0       0        0        0           0
+TX:  bytes  packets  errors  dropped  carrier  collisions
+0        0       0        0        0           0
+:::
+```
+
+## Remote access (road warrior) clients
+
+Some users connect mobile devices to their VyOS router using WireGuard. To
+simplify deployment, generate a per-mobile configuration from the VyOS CLI.
+
+:::{warning}
+From a security perspective, it is not recommended to let a third
+party create and share the private key for a secure connection. You should
+create the private portion yourself and hand out only the public key.
+:::
+
+```{opcmd} generate wireguard client-config \<name\> interface \<interface\> server \<ip|fqdn\> address \<client-ip\>
+
+**Generate a client configuration file that establishes a connection to the
+specified interface.**
+
+The public key from the specified interface is automatically included in the
+configuration file.
+
+The command also generates a configuration snippet that can be copied into the
+VyOS CLI. The ``<name>`` you provide will be used as the peer name in the
+snippet.
+
+You must also specify the IP address or FQDN of the server the client connects
+to. The address parameter can be used twice to assign both an IPv4 (/32) and
+an IPv6 (/128) address to the client.
+
+:::{figure} /_static/images/wireguard_qrcode.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..9e6b7c99
--- /dev/null
+++ b/docs/configuration/interfaces/md-wireless.md
@@ -0,0 +1,923 @@
+---
+lastproofread: '2026-03-23'
+---
+
+(wireless-interface)=
+
+# Wireless LAN / Wi-Fi
+
+{abbr}`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless
+connectivity, referred to as Wi-Fi, and operate in one of the following
+modes:
+
+- {abbr}`WAP (Wireless Access-Point)` mode provides network access to connecting
+  stations if the physical hardware supports acting as a WAP
+- Station mode acts as a Wi-Fi client accessing the network through an available
+  WAP
+- Monitor mode lets the system passively monitor wireless traffic
+
+If the system detects an unconfigured wireless device, it will be automatically
+added to the configuration tree, specifying any detected settings (for example,
+its MAC address) and configured to run in monitor mode.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: wireless
+:var1: wlan0
+```
+
+
+### System-wide configuration
+
+```{cfgcmd} set system wireless country-code \<cc\>
+
+Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed
+to indicate country in which device is operating. This can limit available
+channels and transmit power.
+
+:::{note}
+This option is mandatory in ``access-point`` mode.
+:::
+```
+
+
+### Wireless options
+
+```{cfgcmd} set interfaces wireless \<interface\> channel \<number\>
+
+Configure the IEEE 802.11 wireless radio channel for the interface.
+Channel allocation depends on the frequency band:
+* **2.4 GHz** (802.11b/g/n/ax): Channels range from 1 to 14.
+* **5 GHz** (802.11a/h/j/n/ac/ax): Channels range from 34 to 177.
+* **6 GHz** (802.11ax): Channels range from 1 to 233.
+* **Automatic channel selection:** 0.
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> disable-broadcast-ssid
+
+Send empty SSID in beacons and ignore probe request frames that do not specify
+full SSID, i.e., require stations to know the SSID.
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> expunge-failing-stations
+
+Disassociate stations based on excessive transmission failures or other
+indications of connection loss.
+
+This depends on the driver capabilities and may not be available with all
+drivers.
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> isolate-stations
+
+Client isolation can be used to prevent low-level bridging of frames between
+associated stations in the BSS.
+
+By default, this bridging is allowed.
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> max-stations \<count\>
+
+Maximum number of stations allowed in station table. New stations will be
+rejected after the station table is full. IEEE 802.11 has a limit of 2007
+different association IDs, so this number should not be larger than that.
+
+This defaults to 2007.
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> mgmt-frame-protection
+
+Management Frame Protection (MFP) according to IEEE 802.11w
+
+:::{note}
+{abbr}`MFP (Management Frame Protection)` is required for WPA3.
+:::
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> enable-bf-protection
+
+Beacon Protection: management frame protection for Beacon frames.
+
+:::{note}
+This option requires {abbr}`MFP (Management Frame Protection)`
+to be enabled.
+:::
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> mode \<a | b | g | n | ac | ax\>
+
+Operation mode of wireless radio.
+* ``a`` - 802.11a - 54 Mbits/sec
+* ``b`` - 802.11b - 11 Mbits/sec
+* ``g`` - 802.11g - 54 Mbits/sec (default)
+* ``n`` - 802.11n - 600 Mbits/sec
+* ``ac`` - 802.11ac - 1300 Mbits/sec
+* ``ax`` - 802.11ax - exceeds 1GBit/sec
+
+:::{note}
+In VyOS, 802.11ax is only implemented for 2.4GHz and 6GHz.
+:::
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> physical-device \<device\>
+
+Wireless hardware device used as underlay radio.
+
+This defaults to phy0.
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> reduce-transmit-power \<number\>
+
+Adds the Power Constraint information element to Beacon and Probe Response
+frames.
+
+This option adds the Power Constraint information element when applicable
+and the Country information element is configured. The Power Constraint
+element is required by Transmit Power Control.
+
+Valid values are 0..255.
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> ssid \<ssid\>
+
+SSID to be used in IEEE 802.11 management frames
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> type \<access-point | station | monitor\>
+
+Wireless device type for this interface
+* ``access-point``: Forwards packets between other nodes.
+* ``station``: Connects to another {abbr}`AP (Access Point)`.
+* ``monitor``: Passively monitors all packets on the frequency/channel.
+```
+
+```{cmdincludemd} /_include/interface-per-client-thread.txt
+:var0: wireless
+:var1: wlan0
+```
+
+
+#### PPDU
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities require-ht
+
+```
+```{cfgcmd} set interfaces wireless \<interface\> capabilities require-vht
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities require-he
+```
+
+##### HT (High Throughput) capabilities (802.11n)
+
+> Configuring HT mode options is required when using 802.11n or
+> 802.11ax at 2.4GHz.
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht 40mhz-incapable
+
+Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]``
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht auto-powersave
+
+WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD]
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht channel-set-width \<ht20 | ht40+ | ht40-\>
+
+Supported channel width set.
+* ``ht20`` - 20 MHz channel width
+* ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary
+channel
+* ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary
+channel
+
+:::{note}
+Channel availability for HT40- and HT40+ is limited. The following
+table lists channels permitted for HT40- and HT40+ according to IEEE
+802.11n Annex J. Channel availability may vary by location.
+
+ ::::{code-block} none
+ freq              HT40-           HT40+
+ 2.4 GHz           5-13            1-7 (1-9 in Europe/Japan)
+ 5 GHz             40,48,56,64     36,44,52,60
+ ::::
+:::
+
+:::{note}
+40 MHz channels may switch their primary and secondary channels if
+needed or creation of 40 MHz channel may be rejected based on overlapping
+BSSes. These changes are done automatically when hostapd is setting up the
+40 MHz channel.
+:::
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht delayed-block-ack
+
+Enable HT-delayed Block Ack ``[DELAYED-BA]``
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht dsss-cck-40
+
+DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]``
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht greenfield
+
+This enables the greenfield option which sets the ``[GF]`` option
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht ldpc
+
+Enable LDPC coding capability
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht lsig-protection
+
+Enable L-SIG TXOP protection capability
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht max-amsdu \<3839 | 7935\>
+
+Maximum A-MSDU length 3839 (default) or 7935 octets
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht short-gi \<20 | 40\>
+
+Short GI capabilities for 20 and 40 MHz
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht smps \<static | dynamic\>
+
+Spatial Multiplexing Power Save (SMPS) settings
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht stbc rx \<num\>
+
+Enable receiving PPDU using STBC (Space Time Block Coding)
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities ht stbc tx
+
+Enable sending PPDU using STBC (Space Time Block Coding)
+```
+
+##### VHT (Very High Throughput) capabilities (802.11ac)
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht antenna-count \<count\>
+```
+
+%
+% Number of antennas on this card
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht antenna-pattern-fixed
+
+Set if antenna pattern does not change during the lifetime of an association
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht beamform \<single-user-beamformer | single-user-beamformee | multi-user-beamformer | multi-user-beamformee>
+
+Beamforming capabilities:
+* ``single-user-beamformer`` - Support for operation as
+single user beamformer
+* ``single-user-beamformee`` - Support for operation as
+single user beamformee
+* ``multi-user-beamformer`` - Support for operation as
+multi user beamformer
+* ``multi-user-beamformee`` - Support for operation as
+multi user beamformee
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht center-channel-freq \<freq-1 | freq-2\> \<number\>
+
+VHT operating channel center frequency - center freq 1
+(for use with 80, 80+80 and 160 modes)
+
+VHT operating channel center frequency - center freq 2
+(for use with the 80+80 mode)
+
+\<number\> must be from 34 - 173. For 80 MHz channels it should be channel + 6.
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht channel-set-width \<0 | 1 | 2 | 3\>
+
+* ``0`` - 20 or 40 MHz channel width (default)
+* ``1`` - 80 MHz channel width
+* ``2`` - 160 MHz channel width
+* ``3`` - 80+80 MHz channel width
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht ldpc
+
+Enable LDPC (Low Density Parity Check) coding capability
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht link-adaptation
+
+VHT link adaptation capabilities
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht max-mpdu \<value\>
+
+Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets)
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht max-mpdu-exp \<value\>
+
+Set the maximum length of A-MPDU pre-EOF padding that the station can
+receive
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht short-gi \<80 | 160\>
+
+Short GI capabilities
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht stbc rx \<num\>
+
+Enable receiving PPDU using STBC (Space Time Block Coding)
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht stbc tx
+
+Enable sending PPDU using STBC (Space Time Block Coding)
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht tx-powersave
+
+Enable VHT TXOP Power Save Mode
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities vht vht-cf
+
+Station supports receiving VHT variant HT Control field
+```
+
+##### HE (High Efficiency) capabilities (802.11ax)
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities he antenna-pattern-fixed
+
+Tell the AP that antenna positions are fixed and will not change
+during the lifetime of an association.
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities he beamform \<single-user-beamformer | single-user-beamformee | multi-user-beamformer\>
+
+Beamforming capabilities:
+* ``single-user-beamformer`` - Support for operation as
+single user beamformer
+* ``single-user-beamformee`` - Support for operation as
+single user beamformee
+* ``multi-user-beamformer`` - Support for operation as multi
+user beamformer
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities he bss-color \<number\>
+
+BSS coloring helps to prevent channel jamming when multiple APs use
+the same channels.
+
+Valid values are 1..63
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities he center-channel-freq \<freq-1 | freq-2\> \<number\>
+
+HE operating channel center frequency - center freq 1
+(for use with 80, 80+80 and 160 modes)
+
+HE operating channel center frequency - center freq 2
+(for use with the 80+80 mode)
+
+\<number\> must be within 1..233. For 80 MHz channels it should be
+channel + 6 and for 160 MHz channels, it should be channel + 14.
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities he channel-set-width \<number\>
+
+\<number\> must be one of:
+
+* ``81`` - 20 MHz channel width (2.4GHz)
+* ``83`` - 40 MHz channel width, secondary 20MHz channel above primary
+channel (2.4GHz)
+* ``84`` - 40 MHz channel width, secondary 20MHz channel below primary
+channel (2.4GHz)
+* ``131`` - 20 MHz channel width (6GHz)
+* ``132`` - 40 MHz channel width (6GHz)
+* ``133`` - 80 MHz channel width (6GHz)
+* ``134`` - 160 MHz channel width (6GHz)
+* ``135`` - 80+80 MHz channel width (6GHz)
+```
+
+```{cfgcmd} set interfaces wireless \<interface\> capabilities he coding-scheme \<number\>
+
+This setting configures Spatial Stream and Modulation Coding Scheme
+settings for HE mode (HE-MCS). It is usually not needed to set this
+explicitly, but it might help with some WiFi adapters.
+
+\<number\> must be one of:
+* ``0`` - HE-MCS 0-7
+* ``1`` - HE-MCS 0-9
+* ``2`` - HE-MCS 0-11
+* ``3`` - HE-MCS is not supported
+```
+
+### Wireless options (Station/Client)
+
+The example creates a wireless station (commonly referred to as Wi-Fi client)
+that accesses the network through the WAP defined in the above example. The
+default physical device (`phy0`) is used.
+
+```none
+set system wireless country-code de
+set interfaces wireless wlan0 type station
+set interfaces wireless wlan0 address dhcp
+set interfaces wireless wlan0 ssid 'TEST'
+set interfaces wireless wlan0 security wpa passphrase '12345678'
+```
+
+Resulting configuration:
+
+```none
+system {
+  wireless {
+    country-code de
+  }
+}
+interfaces {
+  wireless wlan0 {
+    address dhcp
+    security {
+      wpa {
+        passphrase "12345678"
+      }
+    }
+    ssid TEST
+    type station
+  }
+```
+
+### Security
+
+{abbr}`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in
+combination with 802.1X based authentication can be used to authenticate
+users or computers in a domain.
+
+The wireless client (supplicant) authenticates against the RADIUS server
+(authentication server) using an {abbr}`EAP (Extensible Authentication
+Protocol)` method configured on the RADIUS server. The WAP (also referred
+to as authenticator) role is to send all authentication messages between the
+supplicant and the configured authentication server, thus the RADIUS server
+is responsible for authenticating the users.
+
+The WAP in this example has the following characteristics:
+- IP address `192.168.2.1/24`
+- Network ID (SSID) `Enterprise-TEST`
+- WPA passphrase `12345678`
+- Use 802.11n protocol
+- Wireless channel `1`
+- RADIUS server at `192.168.3.10` with shared-secret `VyOSPassword`
+
+```none
+set system wireless country-code de
+set interfaces wireless wlan0 address '192.168.2.1/24'
+set interfaces wireless wlan0 type access-point
+set interfaces wireless wlan0 channel 1
+set interfaces wireless wlan0 mode n
+set interfaces wireless wlan0 ssid 'Enterprise-TEST'
+set interfaces wireless wlan0 security wpa mode wpa2
+set interfaces wireless wlan0 security wpa cipher CCMP
+set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword'
+set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812
+```
+
+Resulting configuration:
+
+```none
+system {
+  wireless {
+    country-code de
+  }
+}
+interfaces {
+  [...]
+  wireless wlan0 {
+        address 192.168.2.1/24
+        channel 1
+        mode n
+        security {
+            wpa {
+                cipher CCMP
+                mode wpa2
+                radius {
+                    server 192.168.3.10 {
+                        key 'VyOSPassword'
+                        port 1812
+                    }
+                }
+            }
+        }
+        ssid "Enterprise-TEST"
+        type access-point
+    }
+}
+```
+
+### VLAN
+#### Regular VLANs (802.1q)
+
+```{cmdincludemd} /_include/interface-vlan-8021q.txt
+:var0: wireless
+:var1: wlan0
+```
+
+#### QinQ (802.1ad)
+
+```{cmdincludemd} /_include/interface-vlan-8021ad.txt
+:var0: wireless
+:var1: wlan0
+```
+
+## Operation
+
+```{opcmd} show interfaces wireless info
+```
+
+Use this command to view operational status and wireless-specific information
+about all wireless interfaces.
+
+```none
+vyos@vyos:~$ show interfaces wireless info
+Interface  Type          SSID                         Channel
+wlan0      access-point  VyOS-TEST-0                        1
+```
+
+```{opcmd} show interfaces wireless detail
+```
+
+Show the operational status and detailed wireless-specific
+information about all wireless interfaces.
+
+```none
+vyos@vyos:~$ show interfaces wireless detail
+wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+    link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+    inet xxx.xxx.99.254/24 scope global wlan0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link
+       valid_lft forever preferred_lft forever
+
+    RX:  bytes    packets     errors    dropped    overrun      mcast
+         66072        282          0          0          0          0
+    TX:  bytes    packets     errors    dropped    carrier collisions
+         83413        430          0          0          0          0
+
+wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+    link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+    inet xxx.xxx.100.254/24 scope global wlan0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link
+       valid_lft forever preferred_lft forever
+
+    RX:  bytes    packets     errors    dropped    overrun      mcast
+         166072      5282          0          0          0          0
+    TX:  bytes    packets     errors    dropped    carrier collisions
+         183413      5430          0          0          0          0
+```
+
+```{opcmd} show interfaces wireless \<wlanX\>
+```
+
+This command shows both status and statistics on the specified wireless
+interface. The wireless interface identifier can range from wlan0 to wlan999.
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0
+wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+    link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+    inet xxx.xxx.99.254/24 scope global wlan0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link
+       valid_lft forever preferred_lft forever
+
+    RX:  bytes    packets     errors    dropped    overrun      mcast
+         66072        282          0          0          0          0
+    TX:  bytes    packets     errors    dropped    carrier collisions
+         83413        430          0          0          0          0
+```
+
+```{opcmd} show interfaces wireless \<wlanX\> brief
+```
+
+This command gives a brief status overview of a specified wireless interface.
+The wireless interface identifier can range from wlan0 to wlan999.
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0 brief
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+wlan0            192.168.2.254/24                    u/u
+```
+
+```{opcmd} show interfaces wireless \<wlanX\> queue
+```
+
+Use this command to view wireless interface queue information.
+The wireless interface identifier can range from wlan0 to wlan999.
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0 queue
+qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1
+ Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0)
+ rate 0bit 0pps backlog 0b 0p requeues 0
+```
+
+```{opcmd} show interfaces wireless \<wlanX\> scan
+```
+
+This command is used to retrieve information about WAP within the range of your
+wireless interface. This command is useful on wireless interfaces configured
+in station mode.
+
+:::{note}
+Scanning is not supported on all wireless drivers and wireless
+hardware. Refer to your driver and wireless hardware documentation for
+further details.
+:::
+```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
+```