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>

10 files changed, 887 insertions, 0 deletions

diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png
deleted file mode 100644
index 952b664b..00000000
--- a/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png
+++ /dev/null
diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md
new file mode 100644
index 00000000..1633b349
--- /dev/null
+++ b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md
@@ -0,0 +1,89 @@
+# DHCP Relay through GRE-Bridge
+
+```{eval-rst}
+| Testdate: 2023-05-11
+| Version: 1.4-rolling-202305100734
+```
+
+This simple structure shows how to configure a DHCP Relay over a GRE Bridge
+interface.
+
+## Topology
+
+The topology has 3 VyOS routers and one client. Between the DHCP Server and
+the DHCP Relay is a GRE tunnel. The `transport` VyOS represent a large
+Network.
+
+```{image} _include/topology.webp
+:alt: Ansible Example topology image
+```
+
+
+## Configuration
+
+First, we configure the transport network and the Tunnel interface.
+
+Transport:
+
+```{literalinclude} _include/transport.conf
+:language: none
+```
+
+DHCP-Server
+
+```{literalinclude} _include/dhcp-server.conf
+:language: none
+:lines: 1-8
+```
+
+DHCP-Relay
+
+```{literalinclude} _include/dhcp-relay.conf
+:language: none
+:lines: 1-8
+```
+
+After this, we need the DHCP-Server and Relay configuration.
+To get a testable result, we just have one IP in the DHCP range.
+Expand it as you need it.
+
+DHCP-Server
+
+```{literalinclude} _include/dhcp-server.conf
+:language: none
+:lines: 9-13
+```
+
+DHCP-Relay
+
+```{literalinclude} _include/dhcp-relay.conf
+:language: none
+:lines: 9-10
+```
+
+
+## Test the result
+
+Ping the Client from the DHCP Server.
+
+```none
+vyos@dhcp-server:~$ ping 192.168.0.30 count 4
+PING 192.168.0.30 (192.168.0.30) 56(84) bytes of data.
+64 bytes from 192.168.0.30: icmp_seq=1 ttl=63 time=1.02 ms
+64 bytes from 192.168.0.30: icmp_seq=2 ttl=63 time=1.06 ms
+64 bytes from 192.168.0.30: icmp_seq=3 ttl=63 time=1.21 ms
+64 bytes from 192.168.0.30: icmp_seq=4 ttl=63 time=1.16 ms
+
+--- 192.168.0.30 ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 3004ms
+rtt min/avg/max/mdev = 1.016/1.112/1.214/0.077 ms
+```
+
+And show all DHCP Leases
+
+```none
+vyos@dhcp-server:~$ show dhcp server leases
+IP Address    MAC address        State    Lease start          Lease expiration     Remaining    Pool        Hostname
+------------  -----------------  -------  -------------------  -------------------  -----------  ----------  ----------
+192.168.0.30  00:50:79:66:68:05  active   2023/05/11 13:08:50  2023/05/12 13:08:50  23:59:16     DHCPTun100  VPCS
+```
diff --git a/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png
deleted file mode 100644
index 18ecaabb..00000000
--- a/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png
+++ /dev/null
diff --git a/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md
new file mode 100644
index 00000000..b74452e1
--- /dev/null
+++ b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md
@@ -0,0 +1,246 @@
+# L3VPN EVPN with VyOS
+
+```{eval-rst}
+| Testdate: 2023-05-11
+| Version: 1.4-rolling-202305100734
+```
+
+I spun up a new lab in EVE-NG, which represents this as the
+"Foo Bar - Service Provider Inc." that has 3 points of presence (PoP) in random
+datacenters/sites named PE1, PE2, and PE3. Each PoP aggregates at least two
+customers.
+
+I named the customers blue, red and green which is common practice in
+VRF (Virtual Routing and Forwarding) documentation scenarios.
+
+- PE1 is located in an industrial area that holds multiple office buildings.
+  All customers have a site in this area.
+- PE2 is located in a smaller area where by coincidence two customers
+  (blue and red) share an office building.
+- PE3 is located in a smaller area where by coincidence two customers
+  (blue and green) are located.
+
+## Management VRF
+
+A brief excursion into VRFs: This has been one of the longest-standing feature
+requests of VyOS (dating back to 2016) which can be described as
+"a VLAN for layer 2 is what a VRF is for layer 3".
+With VRFs, a router/system can hold multiple, isolated routing tables on the
+same system. If you wonder what's the difference between multiple tables that
+people used for policy-based routing since forever, it's that a VRF also
+isolates connected routes rather than just static and dynamically learned
+routes, so it allows NICs in different VRFs to use conflicting network
+ranges without issues.
+
+VyOS 1.3 added initial support for VRFs (including IPv4/IPv6 static routing)
+and VyOS 1.4 now enables full dynamic routing protocol support for
+OSPF, IS-IS, and BGP for individual VRFs.
+
+The lab I built is using a VRF (called **mgmt**) to provide out-of-band
+SSH access to the PE (Provider Edge) routers.
+
+```{literalinclude} _include/PE1.conf
+:language: none
+:lines: 1-6
+```
+
+
+## Topology
+
+We use the following network topology in this example:
+
+```{image} _include/topology.webp
+:alt: L3VPN EVPN with VyOS topology image
+```
+
+
+## Core network
+
+I chose to run OSPF as the IGP (Interior Gateway Protocol).
+All required BGP sessions are established via a dummy interfaces
+(similar to the loopback, but in Linux you can have only one loopback,
+while there can be many dummy interfaces) on the PE routers. In case of a link
+failure, traffic is diverted in the other direction in this triangle setup and
+BGP sessions will not go down. One could even enable
+BFD (Bidirectional Forwarding Detection) on the links for a faster
+failover and resilience in the network.
+
+Regular VyOS users will notice that the BGP syntax has changed in VyOS 1.4 from
+even the prior post about this subject. This is due to T1711, where it was
+finally decided to get rid of the redundant BGP ASN (Autonomous System Number)
+specification on the CLI and move it to a single leaf node
+(set protocols bgp local-as).
+
+It's important to note that all your existing configurations will be migrated
+automatically on image upgrade. Nothing to do on your side.
+
+PE1
+
+```{literalinclude} _include/PE1.conf
+:language: none
+:lines: 8-38
+```
+
+PE2
+
+```{literalinclude} _include/PE2.conf
+:language: none
+:lines: 8-38
+```
+
+PE3
+
+```{literalinclude} _include/PE3.conf
+:language: none
+:lines: 8-38
+```
+
+
+## Tenant networks (VRFs)
+
+Once all routers can be safely remotely managed and the core network is
+operational, we can now setup the tenant networks.
+
+Every tenant is assigned an individual VRF that would support overlapping
+address ranges for customers blue, red and green. In our example,
+we do not use overlapping ranges to make it easier when showing debug commands.
+
+Thus you can easily match it to one of the devices/networks below.
+
+Every router that provides access to a customer network needs to have the
+customer network (VRF + VNI) configured. To make our own lives easier,
+we utilize the same VRF table id (local routing table number) and
+VNI (Virtual Network Identifier) per tenant on all our routers.
+
+- blue uses local routing table id and VNI 2000
+- red uses local routing table id and VNI 3000
+- green uses local routing table id and VNI 4000
+
+PE1
+
+```{literalinclude} _include/PE1.conf
+:language: none
+:lines: 40-96
+```
+
+PE2
+
+```{literalinclude} _include/PE2.conf
+:language: none
+:lines: 40-89
+```
+
+PE3
+
+```{literalinclude} _include/PE3.conf
+:language: none
+:lines: 40-89
+```
+
+
+## Testing and debugging
+
+You managed to come this far, now we want to see the network and routing
+tables in action.
+
+Show routes for all VRFs
+
+```none
+vyos@PE1:~$ show ip route vrf all
+Codes: K - kernel route, C - connected, S - static, R - RIP,
+       O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,
+       T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR,
+       f - OpenFabric,
+       > - selected route, * - FIB route, q - queued, r - rejected, b - backup
+       t - trapped, o - offload failure
+
+VRF blue:
+C>* 10.1.1.0/24 is directly connected, br2000, 00:01:13
+B>* 10.1.2.0/24 [200/0] via 172.29.255.2, br2000 onlink, weight 1, 00:00:49
+B>* 10.1.3.0/24 [200/0] via 172.29.255.3, br2000 onlink, weight 1, 00:00:49
+
+VRF default:
+O   172.29.0.2/31 [110/1] is directly connected, eth1, weight 1, 00:01:09
+C>* 172.29.0.2/31 is directly connected, eth1, 00:01:12
+O>* 172.29.0.4/31 [110/2] via 172.29.0.3, eth1, weight 1, 00:00:46
+  *                       via 172.29.0.7, eth3, weight 1, 00:00:46
+O   172.29.0.6/31 [110/1] is directly connected, eth3, weight 1, 00:01:09
+C>* 172.29.0.6/31 is directly connected, eth3, 00:01:12
+C>* 172.29.255.1/32 is directly connected, dum0, 00:01:14
+O>* 172.29.255.2/32 [110/20] via 172.29.0.3, eth1, weight 1, 00:00:50
+O>* 172.29.255.3/32 [110/20] via 172.29.0.7, eth3, weight 1, 00:00:45
+
+VRF green:
+C>* 10.3.1.0/24 is directly connected, br4000, 00:01:13
+B>* 10.3.3.0/24 [200/0] via 172.29.255.3, br4000 onlink, weight 1, 00:00:49
+
+VRF mgmt:
+S>* 0.0.0.0/0 [210/0] via 10.100.0.1, eth0, weight 1, 00:01:45
+C>* 10.100.0.0/24 is directly connected, eth0, 00:01:45
+
+VRF red:
+C>* 10.2.1.0/24 is directly connected, br3000, 00:01:13
+B>* 10.2.2.0/24 [200/0] via 172.29.255.2, br3000 onlink, weight 1, 00:00:49
+```
+
+Information about Ethernet Virtual Private Networks
+
+```none
+vyos@PE1:~$ show bgp l2vpn evpn
+BGP table version is 1, local router ID is 172.29.255.1
+Status codes: s suppressed, d damped, h history, * valid, > best, i - internal
+Origin codes: i - IGP, e - EGP, ? - incomplete
+EVPN type-1 prefix: [1]:[EthTag]:[ESI]:[IPlen]:[VTEP-IP]:[Frag-id]
+EVPN type-2 prefix: [2]:[EthTag]:[MAClen]:[MAC]:[IPlen]:[IP]
+EVPN type-3 prefix: [3]:[EthTag]:[IPlen]:[OrigIP]
+EVPN type-4 prefix: [4]:[ESI]:[IPlen]:[OrigIP]
+EVPN type-5 prefix: [5]:[EthTag]:[IPlen]:[IP]
+
+   Network          Next Hop            Metric LocPrf Weight Path
+Route Distinguisher: 10.1.1.1:5
+*> [5]:[0]:[24]:[10.1.1.0]
+                    172.29.255.1             0         32768 ?
+                    ET:8 RT:100:2000 Rmac:4e:bb:3c:ba:bd:a6
+Route Distinguisher: 10.1.2.1:4
+*>i[5]:[0]:[24]:[10.1.2.0]
+                    172.29.255.2             0    100      0 ?
+                    RT:100:2000 ET:8 Rmac:26:07:da:eb:fc:ea
+Route Distinguisher: 10.1.3.1:4
+*>i[5]:[0]:[24]:[10.1.3.0]
+                    172.29.255.3             0    100      0 ?
+                    RT:100:2000 ET:8 Rmac:26:98:28:24:6e:54
+Route Distinguisher: 10.2.1.1:6
+*> [5]:[0]:[24]:[10.2.1.0]
+                    172.29.255.1             0         32768 ?
+                    ET:8 RT:100:3000 Rmac:50:00:00:01:00:05
+Route Distinguisher: 10.2.2.1:5
+*>i[5]:[0]:[24]:[10.2.2.0]
+                    172.29.255.2             0    100      0 ?
+                    RT:100:3000 ET:8 Rmac:50:00:00:02:00:05
+Route Distinguisher: 10.3.1.1:7
+*> [5]:[0]:[24]:[10.3.1.0]
+                    172.29.255.1             0         32768 ?
+                    ET:8 RT:100:4000 Rmac:50:00:00:01:00:06
+Route Distinguisher: 10.3.3.1:6
+*>i[5]:[0]:[24]:[10.3.3.0]
+                    172.29.255.3             0    100      0 ?
+                    RT:100:4000 ET:8 Rmac:06:32:9d:22:55:8a
+
+Displayed 7 out of 7 total prefixes
+```
+
+If we need to retrieve information about a specific host/network inside
+the EVPN network we need to run
+
+```none
+vyos@PE2:~$ show bgp l2vpn evpn 10.3.1.10
+BGP routing table entry for 10.3.1.1:7:[5]:[0]:[24]:[10.3.1.0]
+Paths: (1 available, best #1)
+  Not advertised to any peer
+  Route [5]:[0]:[24]:[10.3.1.0] VNI 4000
+  Local
+    172.29.255.1 (metric 20) from 172.29.255.1 (172.29.255.1)
+      Origin incomplete, metric 0, localpref 100, valid, internal, best (First path received)
+      Extended Community: RT:100:4000 ET:8 Rmac:50:00:00:01:00:06
+      Last update: Thu May 11 13:31:13 2023
+```
diff --git a/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png
deleted file mode 100644
index 382e44f6..00000000
--- a/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png
+++ /dev/null
diff --git a/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md
new file mode 100644
index 00000000..bd1ccfc4
--- /dev/null
+++ b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md
@@ -0,0 +1,238 @@
+(examples-openvpn-with-ldap)=
+
+# OpenVPN with LDAP
+
+```{eval-rst}
+| Testdate: 2023-05-11
+| Version: 1.4-rolling-202305100734
+```
+
+This LAB shows how to use OpenVPN with a Active Directory authentication method.
+
+Topology consists of:
+: - Windows Server 2019 with a running Active Directory
+  - VyOS as a OpenVPN Server
+  - VyOS as Client
+
+```{image} _include/topology.webp
+:alt: OpenVPN with LDAP topology image
+```
+
+
+## Active Directory on Windows server
+
+The lab assumes a full running Active Directory on the Windows Server.
+Here are some PowerShell commands to quickly add a Test Active Directory.
+
+```powershell
+# install the Active Directory Server role
+Install-WindowsFeature AD-Domain-Services -IncludeManagementTools
+
+# install the Active Directory Server role
+Install-ADDSForest -DomainName "vyos.local" -DomainNetBiosName "VYOS" -InstallDns:$true -NoRebootCompletion:$true
+
+# create test user01 and binduser
+New-ADUser binduser -AccountPassword(Read-Host -AsSecureString "Input Password") -Enabled $true
+New-ADUser user01 -AccountPassword(Read-Host -AsSecureString "Input Password") -Enabled $true
+```
+
+
+## Configure VyOS as OpenVPN Server
+
+In this example OpenVPN will be setup with a client certificate and username / password authentication.
+
+First a CA, a signed server and client ceftificate and a Diffie-Hellman parameter musst be generated and installed.
+Please look {ref}`here <configuration/pki/index:pki>` for more information.
+
+```{eval-rst}
+| Add the LDAP plugin configuration file `/config/auth/ldap-auth.config`
+```
+
+```{eval-rst}
+| Check all possible settings `here <https://github.com/threerings/openvpn-auth-ldap/blob/master/auth-ldap.conf>`_.
+```
+
+```{literalinclude} _include/ldap-auth.config
+:language: none
+```
+
+Now generate all required certificates on the ovpn-server:
+
+First the CA
+
+```none
+vyos@ovpn-server# run generate pki ca install OVPN-CA
+```
+
+after this create a signed server and a client certificate
+
+```none
+vyos@ovpn-server# run generate pki certificate sign OVPN-CA install SRV
+vyos@ovpn-server# run generate pki certificate sign OVPN-CA install CLIENT
+```
+
+and last the DH Key
+
+```none
+vyos@ovpn-server# run generate pki dh install DH
+```
+
+after all these steps the config look like this:
+
+```none
+set pki ca OVPN-CA certificate 'MIIFnTCCA4WgAwIBAgIUIPFIXvCxYdavCnSPFNjr6lUtlsswDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MjJaFw0zMzA1MDgxMjM4MjJaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88zCIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SAsJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tLc6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BGoewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7Ou5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABo2EwXzAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwHQYDVR0OBBYEFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0GCSqGSIb3DQEBCwUAA4ICAQDEqpF2ibwYFxsF1XDIPS5/Gs0sZTZBuByNm5d2+jTyO7d5alZUdbvobbwhxZOhWasmFNyPLr4TYmZm5zF+efFsiOxjyRuEoVU+Fe8rZmpRIF/+6+nYX5r9vMI4QxGjeeyP20OHJ85Kvz182CTsITrM15Vw/kVVjAVzFI5Gm/QolalAoFQza9rAL4kDqaUszjHjPbysvDpGF+NLPjiYDHXcty/BC48bnuzAeEM60SGZ7EXvf8l0X8YsO7z39w6780A/3rbZvFhCYMKp/+p5xBRDjnX91dM6DJw73RwYQ1KHbHk9wWUwnL1giL71jzp/y4Oj6SSK2PQv+OnO80J6Zg06WIQx9xYcxr108Xh9FotUrlG7GYPI3Udf95t6SjuydDhULAVD0lMBxlDe9DHW1k1q1pOXaHZg926tY66xx/lda6dcuwJjA2Dx5JI6L0u9ureQmQAtxvnoTCtf+hR1iX/IkskZCKs34SjNiCnBuw/DNfdOpfaABm7y+tWiXBwnu5l/K8poXcQYQByyZj6YMmpgsbVPr5KNsLWOgRA81M6IPof8qxvnFrkazhiQWh1YHSjnaHtA3z5/BdgwHVICuFyrIOlbkKyJOjKcKBsDdMwIV0tsnpnyli2xEPZKu1tAQFAavXrK/RGYYhOZ3e0aRSV8hlP8i/mf7p0I45cJiBCqPg=='
+set pki ca OVPN-CA private key '<REDACTED>'
+set pki certificate SRV certificate 'MIIFtTCCA52gAwIBAgIUeZnSAMPohIvKL/1Fy/pW2cV73HkwDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MzFaFw0zMzA1MDgxMjM4MzFaMFsxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxFDASBgNVBAMMC292cG4tc2VydmVyMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEApDWzTcB5LFM/tacaRHvpchBKLigJ5FlqNNfJ2vnP87KfCmTA5tkWF7MtuY990tHZtl1vQ3Pim4d6XBOngiQmaw7tZeWAIrv1L2/VBjORUrLrQhkkg9nSpcYFxoyUQzukTY75PcwhYLkS6ZO/vPPSBuh97f3XR645Aauf7ZIk2NsUidP2uGZz/Sr5VC7ovH2l3zz1kIHPCinfvpPEVb5oTt7qEffk4vnKjy9RY+H1hZowvcAp1zfLaOt/dXaK6vfNutbmwDHbYAlIals0EcjtTr+63ymxmupn7RBjgWtK7MgocGZnt6HKJ4J6teP3WgiSd+I9pdFG4wHZOSVL3axf3rBx7q09DMn/Snvfbly+SlhXw9Ebk368J6j6rhNUkxo/M9fbfgxS0JnNjHInRNAvRQW5CgQfT9KyUdxR63BeSnngk2XYX+bDinb0ig+VDpZcr6PgOBR8aNFsCPbXRwDy0bmuFnFYMzs/7ZmFQhzE6rQykHvVvAsyv7FYrlW0E02H4+Xe6bEVpE1fLcH8OCGY2cfuTfq1Ax6R4r+tdHYW1kzFLjwdh3uqTLF11zcbkAwd78E/ItrfEadvgxrYR9gfhX79AkK0VHmZ/hzrLFeGznnVcqoTKgq21dfMfQG2P13QvqS7tCE5swM9N09ASVrifyVDuoL6jaW96wgeqR6eHMECAwEAAaN1MHMwDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwEwHQYDVR0OBBYEFE1U3Zamfuv6ocYiF9q7H//U8h+AMB8GA1UdIwQYMBaAFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0GCSqGSIb3DQEBCwUAA4ICAQBZwHvGj/jziNFwXS2W1Q11I12YANmVhISP39AA7DNhXR+E1hXFs+U52ehurZoLTi5YTjd8PD0KcE58mw8CLsFQB/+pni9EwJuAhpMb6XsmYEp0PeOH7C/q5eOc4TB/NBsvEa5IdTmUoewmjubKeJ8OHdRBMI77Me53lSC6iskc9DGyixSLqQogQW4aiTposFJOW/YugBy7kiuygmFNJv4luDbyRBb9131zH0qSSishLT4Bp5lXQNYWI4AU0JeyQcYaSHWCr0h6H9GN3QOf/emc3/2Tee40FcEMsszJBRnQ3IISzU5xVLlfU02SJMpjvFT2MGfHAs7obrNbwiFeoLZ6fQeGLe53aOQ5M9XeW5bdIeR2ZrLoO1hW33x5jYI8nLnU0FnqpMMY14r7LZE/mjwfdrTsGChFzsLasB0Tj++mGMOXw3DSusppub17AE2bO2uO6J9XMlbkOC8EmDCF1Hetija4D3aunhtu6jRBOcR8DHVBqNae2YgUk1ALqGrNUGFH4bEioTjDDx2GieOtp9rUwJMlkAyUEe0k/wzcBLjZaO8KBCtrmTdr1wMXizPT+XcjAlzRNXvHiZFq0NG5Rnim+LH9tp90EHzO7EeVXV+LegnIKQqboIrY3KOw5Qx8ska+t1WrWHpyzpwsA0WjA6sDTyWthgNYSxb1ikNGO8STCA=='
+set pki certificate SRV private key '<REDACTED>'
+set pki certificate CLIENT certificate 'MIIFsDCCA5igAwIBAgIUSzQgwzGsfJFecGxCwLXVsGCLMkAwDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MzlaFw0zMzA1MDgxMjM4MzlaMFYxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDzANBgNVBAMMBmNsaWVudDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBANHNJOSwcDbRqziL1gXYnHIq7P7vEUFvS8d/XLYJ1xIpcYTRXTut2CTGRar7fZZicu7x0yoK4TzrHvGVf1o4NC4NSGV5RX6kwRdrfWBmvpIkjSLGtCREFyhb+PHDpnsIS7cfN9udC0vocqVlx/xM/sfcP6Vja/uFp+9TQcneJIxYw34zkF+TtOVbE3pP5VxU7ZAj8F5/q1ONhTMdzG4Ol4/0nBqZfdYA3LVDeSSNIJNF5jlaKXXFHz1EJRemTYDx+f5bfCVcK2Qs8fU9jCFBlATjMu9O5rgk6nMLRwEnJZuZ1gj2tWQvz4e9yo5yUqf1PUhOrn3c81MRliUNHKr+CkxgQJal6P3Ar3q4iftJih3K+/j4o194mQ/Dt/Et+/Qn/DUFk2FB0rTMcQwJLTEAzxtTdmBJeJpipIPDR0u7UMZLNh/raQ8s3FsbY4uYORt2f5YQlCVHbth4dRa9xa+oRbm7eomNACIbWfkLh5Bzud1+qIfdBMZKaZbnf0HEeuH0J5LBJeova8EPxWbYMJPrRHzu5gowkIKl+uIxcy8IiNTA9YEoJVonCjmlr8NEtYShrIVbicdMNSI3pOQR60MFhkHwBjSU2l/z+4wwLxtzq/c2xKw9yrOZ46ZVLwGDFq8rPwp7/P9r6mDKsbn6jIvGOeH71dMZvoc4lCaClw+hKIzLAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBS6j30FmL6kZW7rDH8QjRMoWoA/njAfBgNVHSMEGDAWgBT+TQ2nP8gvpkJmk6WQ1L/RmTBjATANBgkqhkiG9w0BAQsFAAOCAgEANW2Y4bgaB9oexEjj6rkGvePtQmXRkF/adVQREY9iZDGTe72ePybVzrfMkZHjse3o7JvXWRIVVztWSzEpv5noIOX7lAioGG3wsFTHotTFR0zrYJHXHBcV2Neq4Kx2Ta/TZwD8QnZHAAxEQ1pYb4fxwN/A60VElAZoz9zYsbrJyVrfuHDL9queQxPFzqis+7W1BiVIcv4rn0DMQ560jTGh4t4rImOSu5gUsUrQaih85XDdOBPxViSNwfVdZJIgbvamudpfEaKsIun/uCjcxpNnzIp0rhyYmDeqVat4GnTV7Sy48e/Uvcq71ZWbBYJF4+yW4pylIU2Sh/Uy2sAz4C2M71FlFB7qsmcnPRsFFHf+r1NyD1lkVI9k2371fTG/Kub9V0rOz4pvKz4Em5b4MUPdDbZOqJ8hQ+atGE3ovFJIovA3NFb0OtnyC4l+kG7dfjqFudOnmDa+Qsya+2YOxBZBIRfuhlXhb6Y6Smsk9R6x0jBmcQTPS5ZmvKaTxQCFc53xMdQNAswjiI2L9rw4BcqQfVmf/vpoN+VusD/XEv2V0Ixm10YybA7BI/tixh9vwj3fdQXVLy3jSYjVBd5WOFPizbQZeD10ElvlLqZZyWrP/Wre7Nmi/gEOnhBXXmo034fFF/vXf0JRpQsd2oDs24+4XwZYb8mbM31j7Nx8YvhR+64='
+set pki certificate CLIENT private key '<REDACTED>'
+set pki dh DH parameters 'MIIBCAKCAQEAzPOQWrWaIX2qt4sbV6bRbUnFx4jmeE+WXC8GIvulnC4pIr1nt2Gc/7uNfEPjDZ4X6csD3X6zAWxtSuWeNuml9Yuy+tS8gI7d0FlbQRAFO/9GIlRuVdMcbCtEhg8ja7Y0g3fQjOSQJ9mqFo7sRoXyYQALD+MDEJOxhnV7neCrgDi1pqnN4xZLoR9DLARp0ad30VIvnv0ay55wxFWAKh2iwNRwyeXIEOtUDBkfcLGSNNfK0kQsos/J8Q+7YXmk4cN9tiVX4xR92edVO4z/vhMkjsGKLSDm/E6EMusX+N0UhQ3dv7qDgeSS8vDsqBm8XJonumNZLvFbYt2ARGRZYL6DUwIBAg=='
+```
+
+Once all the required certificates and keys are installed, the remaining
+OpenVPN Server configuration can be carried out.
+
+```{literalinclude} _include/ovpn-server.conf
+:language: none
+```
+
+
+## Client configuration
+
+One advantage of having the client certificate stored is the ability to create the client configuration.
+
+```none
+vyos@ovpn-server:~$ generate openvpn client-config interface vtun10 ca OVPN-CA certificate CLIENT
+```
+
+save the output to a file and import it in nearly all openvpn clients.
+
+```none
+client
+nobind
+remote 198.51.100.254 1194
+remote-cert-tls server
+proto udp
+dev tun
+dev-type tun
+persist-key
+persist-tun
+verb 3
+
+# Encryption options
+
+keysize 256
+comp-lzo no
+
+<ca>
+-----BEGIN CERTIFICATE-----
+MIIFnTCCA4WgAwIBAgIUIPFIXvCxYdavCnSPFNjr6lUtlsswDQYJKoZIhvcNAQEL
+BQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM
+CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0y
+MzA1MTExMjM4MjJaFw0zMzA1MDgxMjM4MjJaMFcxCzAJBgNVBAYTAkdCMRMwEQYD
+VQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5
+T1MxEDAOBgNVBAMMB3Z5b3MuaW8wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIK
+AoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8
+gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88z
+CIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SA
+sJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU
+5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tL
+c6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BG
+oewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC
+8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1
+cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00
+uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7O
+u5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABo2EwXzAP
+BgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEF
+BQcDAgYIKwYBBQUHAwEwHQYDVR0OBBYEFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0G
+CSqGSIb3DQEBCwUAA4ICAQDEqpF2ibwYFxsF1XDIPS5/Gs0sZTZBuByNm5d2+jTy
+O7d5alZUdbvobbwhxZOhWasmFNyPLr4TYmZm5zF+efFsiOxjyRuEoVU+Fe8rZmpR
+IF/+6+nYX5r9vMI4QxGjeeyP20OHJ85Kvz182CTsITrM15Vw/kVVjAVzFI5Gm/Qo
+lalAoFQza9rAL4kDqaUszjHjPbysvDpGF+NLPjiYDHXcty/BC48bnuzAeEM60SGZ
+7EXvf8l0X8YsO7z39w6780A/3rbZvFhCYMKp/+p5xBRDjnX91dM6DJw73RwYQ1KH
+bHk9wWUwnL1giL71jzp/y4Oj6SSK2PQv+OnO80J6Zg06WIQx9xYcxr108Xh9FotU
+rlG7GYPI3Udf95t6SjuydDhULAVD0lMBxlDe9DHW1k1q1pOXaHZg926tY66xx/ld
+a6dcuwJjA2Dx5JI6L0u9ureQmQAtxvnoTCtf+hR1iX/IkskZCKs34SjNiCnBuw/D
+NfdOpfaABm7y+tWiXBwnu5l/K8poXcQYQByyZj6YMmpgsbVPr5KNsLWOgRA81M6I
+Pof8qxvnFrkazhiQWh1YHSjnaHtA3z5/BdgwHVICuFyrIOlbkKyJOjKcKBsDdMwI
+V0tsnpnyli2xEPZKu1tAQFAavXrK/RGYYhOZ3e0aRSV8hlP8i/mf7p0I45cJiBCq
+Pg==
+-----END CERTIFICATE-----
+
+</ca>
+
+<cert>
+-----BEGIN CERTIFICATE-----
+MIIFsDCCA5igAwIBAgIUSzQgwzGsfJFecGxCwLXVsGCLMkAwDQYJKoZIhvcNAQEL
+BQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM
+CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0y
+MzA1MTExMjM4MzlaFw0zMzA1MDgxMjM4MzlaMFYxCzAJBgNVBAYTAkdCMRMwEQYD
+VQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5
+T1MxDzANBgNVBAMMBmNsaWVudDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoC
+ggIBANHNJOSwcDbRqziL1gXYnHIq7P7vEUFvS8d/XLYJ1xIpcYTRXTut2CTGRar7
+fZZicu7x0yoK4TzrHvGVf1o4NC4NSGV5RX6kwRdrfWBmvpIkjSLGtCREFyhb+PHD
+pnsIS7cfN9udC0vocqVlx/xM/sfcP6Vja/uFp+9TQcneJIxYw34zkF+TtOVbE3pP
+5VxU7ZAj8F5/q1ONhTMdzG4Ol4/0nBqZfdYA3LVDeSSNIJNF5jlaKXXFHz1EJRem
+TYDx+f5bfCVcK2Qs8fU9jCFBlATjMu9O5rgk6nMLRwEnJZuZ1gj2tWQvz4e9yo5y
+Uqf1PUhOrn3c81MRliUNHKr+CkxgQJal6P3Ar3q4iftJih3K+/j4o194mQ/Dt/Et
++/Qn/DUFk2FB0rTMcQwJLTEAzxtTdmBJeJpipIPDR0u7UMZLNh/raQ8s3FsbY4uY
+ORt2f5YQlCVHbth4dRa9xa+oRbm7eomNACIbWfkLh5Bzud1+qIfdBMZKaZbnf0HE
+euH0J5LBJeova8EPxWbYMJPrRHzu5gowkIKl+uIxcy8IiNTA9YEoJVonCjmlr8NE
+tYShrIVbicdMNSI3pOQR60MFhkHwBjSU2l/z+4wwLxtzq/c2xKw9yrOZ46ZVLwGD
+Fq8rPwp7/P9r6mDKsbn6jIvGOeH71dMZvoc4lCaClw+hKIzLAgMBAAGjdTBzMAwG
+A1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMC
+MB0GA1UdDgQWBBS6j30FmL6kZW7rDH8QjRMoWoA/njAfBgNVHSMEGDAWgBT+TQ2n
+P8gvpkJmk6WQ1L/RmTBjATANBgkqhkiG9w0BAQsFAAOCAgEANW2Y4bgaB9oexEjj
+6rkGvePtQmXRkF/adVQREY9iZDGTe72ePybVzrfMkZHjse3o7JvXWRIVVztWSzEp
+v5noIOX7lAioGG3wsFTHotTFR0zrYJHXHBcV2Neq4Kx2Ta/TZwD8QnZHAAxEQ1pY
+b4fxwN/A60VElAZoz9zYsbrJyVrfuHDL9queQxPFzqis+7W1BiVIcv4rn0DMQ560
+jTGh4t4rImOSu5gUsUrQaih85XDdOBPxViSNwfVdZJIgbvamudpfEaKsIun/uCjc
+xpNnzIp0rhyYmDeqVat4GnTV7Sy48e/Uvcq71ZWbBYJF4+yW4pylIU2Sh/Uy2sAz
+4C2M71FlFB7qsmcnPRsFFHf+r1NyD1lkVI9k2371fTG/Kub9V0rOz4pvKz4Em5b4
+MUPdDbZOqJ8hQ+atGE3ovFJIovA3NFb0OtnyC4l+kG7dfjqFudOnmDa+Qsya+2YO
+xBZBIRfuhlXhb6Y6Smsk9R6x0jBmcQTPS5ZmvKaTxQCFc53xMdQNAswjiI2L9rw4
+BcqQfVmf/vpoN+VusD/XEv2V0Ixm10YybA7BI/tixh9vwj3fdQXVLy3jSYjVBd5W
+OFPizbQZeD10ElvlLqZZyWrP/Wre7Nmi/gEOnhBXXmo034fFF/vXf0JRpQsd2oDs
+24+4XwZYb8mbM31j7Nx8YvhR+64=
+-----END CERTIFICATE-----
+
+</cert>
+
+<key>
+-----BEGIN PRIVATE KEY-----
+...REDACTED...
+-----END PRIVATE KEY-----
+
+</key>
+```
+
+
+### Configure VyOS as client
+
+```none
+set interfaces openvpn vtun10 authentication username 'user01'
+set interfaces openvpn vtun10 authentication password '$ecret'
+set interfaces openvpn vtun10 encryption cipher '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 '198.51.100.254'
+set interfaces openvpn vtun10 remote-port '1194'
+set interfaces openvpn vtun10 tls ca-certificate 'OVPN-CA'
+set interfaces openvpn vtun10 tls certificate 'CLIENT'
+```
+
+
+## Monitoring
+
+If the client is connected successfully you can check the status
+
+```none
+vyos@ovpn-server:~$ show openvpn server
+OpenVPN status on vtun10
+
+Client CN    Remote Host         Tunnel IP    Local Host           TX bytes    RX bytes    Connected Since
+-----------  ------------------  -----------  -------------------  ----------  ----------  -------------------
+client       198.51.100.1:55150  10.23.1.6    198.51.100.254:1194  4.7 KB      4.7 KB      2023-05-11 12:47:11
+```
diff --git a/docs/configexamples/autotest/Wireguard/_include/topology.png b/docs/configexamples/autotest/Wireguard/_include/topology.png
deleted file mode 100644
index 43c0018e..00000000
--- a/docs/configexamples/autotest/Wireguard/_include/topology.png
+++ /dev/null
diff --git a/docs/configexamples/autotest/Wireguard/md-Wireguard.md b/docs/configexamples/autotest/Wireguard/md-Wireguard.md
new file mode 100644
index 00000000..7bbf4c55
--- /dev/null
+++ b/docs/configexamples/autotest/Wireguard/md-Wireguard.md
@@ -0,0 +1,108 @@
+# Wireguard
+
+```{eval-rst}
+| Testdate: 2024-01-13
+| Version: 1.5-rolling-202401121239
+```
+
+This simple structure show how to connect two offices. One remote branch and the
+central office.
+
+## Topology
+
+The topology have a central and a branch VyOS router and one client, to
+test, in each site.
+
+```{image} _include/topology.webp
+:alt: Ansible Example topology image
+```
+
+
+## Configuration
+
+Set the local subnet on eth2 and the public ip address eth1 on each site.
+
+Central
+
+```{literalinclude} _include/central.conf
+:language: none
+:lines: 1-2
+```
+
+Branch
+
+```{literalinclude} _include/branch.conf
+:language: none
+:lines: 1-2
+```
+
+Next thing to do, is to create a wireguard keypair on each side.
+After this, the public key can be displayed, to save for later.
+
+```none
+vyos@central:~$ generate pki wireguard
+Private key: wHQS+ib3eMIp2DxRiAeXfFVaSCMMP1YHBaKfSR1xfV8=
+Public key: RCMy6BAER0uEcPvspUb3K38MHyHJpK5kiV5IOX943HI=
+```
+
+After you have each public key. The wireguard interfaces can be setup.
+
+Central
+
+```{literalinclude} _include/central.conf
+:language: none
+:lines: 4-12
+```
+
+Branch
+
+```{literalinclude} _include/branch.conf
+:language: none
+:lines: 4-12
+```
+
+To reach the network, a route must be set on each VyOS host.
+In this structure, a static interface route will fit the requirements.
+
+Central
+
+```{literalinclude} _include/central.conf
+:language: none
+:lines: 14
+```
+
+Branch
+
+```{literalinclude} _include/branch.conf
+:language: none
+:lines: 14
+```
+
+
+## Testing and debugging
+
+After all is done and commit, let's take a look if the Wireguard interface is
+up and running.
+
+```none
+vyos@central:~$ show interfaces wireguard
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+wg01             192.168.0.1/24                    u/u  VPN-to-Branch
+```
+
+And ping the Branch PC from your central router to check the response.
+
+```none
+vyos@central:~$ ping 10.0.2.100 count 4
+PING 10.0.2.100 (10.0.2.100) 56(84) bytes of data.
+64 bytes from 10.0.2.100: icmp_seq=1 ttl=63 time=0.894 ms
+64 bytes from 10.0.2.100: icmp_seq=2 ttl=63 time=0.869 ms
+64 bytes from 10.0.2.100: icmp_seq=3 ttl=63 time=0.966 ms
+64 bytes from 10.0.2.100: icmp_seq=4 ttl=63 time=0.998 ms
+
+--- 10.0.2.100 ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 3004ms
+rtt min/avg/max/mdev = 0.869/0.931/0.998/0.052 ms
+```
diff --git a/docs/configexamples/autotest/tunnelbroker/_include/topology.png b/docs/configexamples/autotest/tunnelbroker/_include/topology.png
deleted file mode 100644
index e70d55bc..00000000
--- a/docs/configexamples/autotest/tunnelbroker/_include/topology.png
+++ /dev/null
diff --git a/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md
new file mode 100644
index 00000000..6c59a491
--- /dev/null
+++ b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md
@@ -0,0 +1,206 @@
+(examples-tunnelbroker-ipv6)=
+
+# Tunnelbroker.net (IPv6)
+
+```{eval-rst}
+| Testdate: 2024-01-13
+| Version: 1.5-rolling-202401121239
+```
+
+This guide walks through the setup of <https://www.tunnelbroker.net/> for an
+IPv6 Tunnel.
+
+## Prerequisites
+
+- A public, routable IPv4 address. This does not necessarily need to be static,
+  but you will need to update the tunnel endpoint when/if your IP address
+  changes, which can be done with a script and a scheduled task.
+- Account at <https://www.tunnelbroker.net/>
+- Requested a "Regular Tunnel". You want to choose a location that is closest
+  to your physical location for the best response time.
+
+### Topology
+
+The example topology has 2 VyOS routers. One as the WAN router and one as a
+client, to test a single LAN setup
+
+```{image} _include/topology.webp
+:alt: Tunnelbroker topology image
+```
+
+
+### Configuration
+
+First, we configure the `vyos-wan` interface to get a DHCP address.
+
+```{literalinclude} _include/vyos-wan.conf
+:language: none
+```
+
+Now we are able to setup the tunnel interface.
+
+```{literalinclude} _include/vyos-wan_tun0.conf
+:language: none
+:lines: 1-5
+```
+
+:::{note}
+The `source-address` is the Tunnelbroker client IPv4
+address or if there is NAT the current WAN interface address.
+
+If `source-address` is dynamic, the tunnel will cease working once
+the address changes. To avoid having to manually update
+`source-address` each time the dynamic IP changes, an address of
+'0.0.0.0' can be specified.
+:::
+
+Setup the IPv6 default route to the tunnel interface
+
+```{literalinclude} _include/vyos-wan_tun0.conf
+:language: none
+:lines: 7
+```
+
+Now you should be able to ping a public IPv6 Address
+
+```none
+vyos@vyos-wan:~$ ping 2001:470:20::2 count 4
+PING 2001:470:20::2(2001:470:20::2) 56 data bytes
+64 bytes from 2001:470:20::2: icmp_seq=1 ttl=64 time=33.8 ms
+64 bytes from 2001:470:20::2: icmp_seq=2 ttl=64 time=43.9 ms
+64 bytes from 2001:470:20::2: icmp_seq=3 ttl=64 time=43.4 ms
+64 bytes from 2001:470:20::2: icmp_seq=4 ttl=64 time=42.5 ms
+
+--- 2001:470:20::2 ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 2999ms
+rtt min/avg/max/mdev = 33.802/40.920/43.924/4.139 ms
+```
+
+Assuming the pings are successful, you need to add some DNS servers.
+Some options:
+
+```{literalinclude} _include/vyos-wan_tun0.conf
+:language: none
+:lines: 13
+```
+
+You should now be able to ping something by IPv6 DNS name:
+
+```none
+vyos@vyos-wan:~$ ping tunnelbroker.net count 4
+PING tunnelbroker.net(tunnelbroker.net (2001:470:0:63::2)) 56 data bytes
+64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=1 ttl=48 time=285 ms
+64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=2 ttl=48 time=186 ms
+64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=3 ttl=48 time=178 ms
+64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=4 ttl=48 time=177 ms
+
+--- tunnelbroker.net ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 3002ms
+rtt min/avg/max/mdev = 176.707/206.638/285.128/45.457 ms
+```
+
+
+### LAN Configuration
+
+At this point, your VyOS install should have full IPv6, but now your LAN devices
+need access.
+
+With Tunnelbroker.net, you have two options:
+
+- Routed /64. This is the default assignment. In IPv6-land, it's good for a
+  single "LAN", and is somewhat equivalent to a /24.
+- Routed /48. This is something you can request by clicking the "Assign /48"
+  link in the Tunnelbroker.net tunnel config. It allows you to have up to 65k
+
+Unlike IPv4, IPv6 is really not designed to be broken up smaller than /64. So
+if you ever want to have multiple LANs, VLANs, DMZ, etc, you'll want to ignore
+the assigned /64, and request the /48 and use that.
+
+## Single LAN Setup
+
+Single LAN setup where eth2 is your LAN interface. Use the Tunnelbroker
+Routed /64 prefix:
+
+```{literalinclude} _include/vyos-wan_tun0.conf
+:language: none
+:lines: 9-11
+```
+
+Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default,
+'valid-lifetime' and 'preferred-lifetime' are set to default values of
+30 days and 4 hours respectively.
+
+And the `client` to receive an IPv6 address with stateless autoconfig.
+
+```{literalinclude} _include/client.conf
+:language: none
+```
+
+This accomplishes a few things:
+- Sets your LAN interface's IP address
+- Enables router advertisements. This is an IPv6 alternative for DHCP (though
+  DHCPv6 can still be used). With RAs, Your devices will automatically find the
+  information they need for routing and DNS.
+
+Now the Client is able to ping a public IPv6 address
+
+```none
+vyos@client:~$ ping 2001:470:20::2 count 4
+PING 2001:470:20::2(2001:470:20::2) 56 data bytes
+64 bytes from 2001:470:20::2: icmp_seq=1 ttl=63 time=32.1 ms
+64 bytes from 2001:470:20::2: icmp_seq=2 ttl=63 time=41.8 ms
+64 bytes from 2001:470:20::2: icmp_seq=3 ttl=63 time=41.7 ms
+64 bytes from 2001:470:20::2: icmp_seq=4 ttl=63 time=47.1 ms
+
+--- 2001:470:20::2 ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 3005ms
+rtt min/avg/max/mdev = 32.128/40.688/47.107/5.403 ms
+```
+
+
+## Multiple LAN/DMZ Setup
+
+That's how you can expand the example above.
+Use the `Routed /48` information. This allows you to assign a
+different /64 to every interface, LAN, or even device. Or you could break your
+network into smaller chunks like /56 or /60.
+
+The format of these addresses:
+- `2001:470:xxxx::/48`: The whole subnet. xxxx should come from Tunnelbroker.
+- `2001:470:xxxx:1::/64`: A subnet suitable for a LAN
+- `2001:470:xxxx:2::/64`: Another subnet
+- `2001:470:xxxx:ffff::/64`: The last usable /64 subnet.
+
+In the above examples, 1,2,ffff are all chosen by you. You can use 1-ffff
+(1-65535).
+
+So, when your LAN is eth1, your DMZ is eth2, your cameras are on eth3, etc:
+
+```none
+set interfaces ethernet eth1 address '2001:470:xxxx:1::1/64'
+set service router-advert interface eth1 name-server '2001:470:20::2'
+set service router-advert interface eth1 prefix 2001:470:xxxx:1::/64
+
+set interfaces ethernet eth2 address '2001:470:xxxx:2::1/64'
+set service router-advert interface eth2 name-server '2001:470:20::2'
+set service router-advert interface eth2 prefix 2001:470:xxxx:2::/64
+
+set interfaces ethernet eth3 address '2001:470:xxxx:3::1/64'
+set service router-advert interface eth3 name-server '2001:470:20::2'
+set service router-advert interface eth3 prefix 2001:470:xxxx:3::/64
+```
+
+Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default,
+'valid-lifetime' and 'preferred-lifetime' are set to default values of
+30 days and 4 hours respectively.
+
+## Firewall
+
+Finally, don't forget the
+{ref}`Firewall <configuration/firewall/index:Firewall>`. The usage is
+identical, except instead of `set firewall ipv4 name NAME`, you would
+use `set firewall ipv6 name NAME`.
+
+Similarly, to attach the firewall, you would use
+`set firewall ipv6 name NAME rule N inbound-interface name eth0` or
+`set firewall zone LOCAL from WAN firewall ipv6-name`.