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)

130 files changed, 40182 insertions, 0 deletions

diff --git a/docs/configuration/container/index.md b/docs/configuration/container/index.md
new file mode 100644
index 00000000..6cb64225
--- /dev/null
+++ b/docs/configuration/container/index.md
@@ -0,0 +1,479 @@
+---
+lastproofread: '2024-07-03'
+---
+
+# Container
+
+The VyOS container implementation is based on [Podman](https://podman.io/) as
+a deamonless container engine.
+
+## Configuration
+
+```{cfgcmd} set container name \<name\> image
+
+Sets the image name in the hub registry
+
+:::{code-block} none
+set container name mysql-server image mysql:8.0
+:::
+
+If a registry is not specified, Docker.io will be used as the container
+registry unless an alternative registry is specified using
+`set container registry <name>` or the registry is included
+in the image name
+
+:::{code-block} none
+set container name mysql-server image quay.io/mysql:8.0
+:::
+```
+
+
+```{cfgcmd} set container name \<name\> entrypoint \<entrypoint\>
+
+Override the default entrypoint from the image for a container.
+```
+
+
+```{cfgcmd} set container name \<name\> command \<command\>
+
+Override the default command from the image for a container.
+```
+
+
+```{cfgcmd} set container name \<name\> arguments \<arguments\>
+
+Set the command arguments for a container.
+```
+
+
+```{cfgcmd} set container name \<name\> host-name \<hostname\>
+
+Set the host name for a container.
+```
+
+
+```{cfgcmd} set container name \<name\> allow-host-pid
+
+The container and the host share the same process namespace.
+This means that processes running on the host are visible inside the
+container, and processes inside the container are visible on the host.
+
+The command translates to "--pid host" when the container is created.
+```
+
+
+```{cfgcmd} set container name \<name\> allow-host-networks
+
+Allow host networking in a container. The network stack of the container is
+not isolated from the host and will use the host IP.
+
+The command translates to "--net host" when the container is created.
+
+:::{note}
+**allow-host-networks** cannot be used with **network**
+:::
+```
+
+
+```{cfgcmd} set container name \<name\> network \<networkname\>
+
+Attaches user-defined network to a container.
+Only one network must be specified and must already exist.
+```
+
+
+```{cfgcmd} set container name \<name\> network \<networkname\> address \<address\>
+
+Optionally set a specific static IPv4 or IPv6 address for the container.
+This address must be within the named network prefix.
+
+:::{note}
+The first IP in the container network is reserved by the
+engine and cannot be used
+:::
+```
+
+
+```{cfgcmd} set container name \<name\> name-server \<address\>
+
+Optionally set a custom name server.
+If a container network is used with DNS enabled,
+this setting will not have any effect.
+```
+
+
+```{cfgcmd} set container name \<name\> description \<text\>
+
+Set a container description
+```
+
+
+```{cfgcmd} set container name \<name\> environment \<key\> value \<value\>
+
+Add custom environment variables.
+Multiple environment variables are allowed.
+The following commands translate to "-e key=value" when the container
+is created.
+
+:::{code-block} none
+set container name mysql-server environment MYSQL_DATABASE value 'zabbix'
+set container name mysql-server environment MYSQL_USER value 'zabbix'
+set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd'
+set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd'
+:::
+```
+
+
+```{cfgcmd} set container name \<name\> port \<portname\> source \<portnumber\>
+
+```
+```{cfgcmd} set container name \<name\> port \<portname\> destination \<portnumber\>
+```
+
+```{cfgcmd} set container name \<name\> port \<portname\> protocol \<tcp | udp\>
+
+Publish a port for the container.
+
+:::{code-block} none
+set container name zabbix-web-nginx-mysql port http source 80
+set container name zabbix-web-nginx-mysql port http destination 8080
+set container name zabbix-web-nginx-mysql port http protocol tcp
+:::
+```
+:::{note}
+Port publishing cannot be used with **network**. For this purpose, a workaround
+using destination NAT and static IP assignment for the container is available.
+:::
+```{cfgcmd} set container name \<name\> volume \<volumename\> source \<path\>
+```
+
+```{cfgcmd} set container name \<name\> volume \<volumename\> destination \<path\>
+
+Mount a volume into the container
+
+:::{code-block} none
+set container name coredns volume 'corefile' source /config/coredns/Corefile
+set container name coredns volume 'corefile' destination /etc/Corefile
+:::
+```
+
+```{cfgcmd} set container name \<name\> volume \<volumename\> mode \<ro | rw\>
+
+Volume is either mounted as rw (read-write - default) or ro (read-only)
+```
+
+```{cfgcmd} set container name \<name\> tmpfs \<tmpfsname\> destination \<path\>
+
+Mount a tmpfs *(ramdisk)* filesystem to the given path within the container.
+```
+
+```{cfgcmd} set container name \<name\> tmpfs \<tmpfsname\> size \<MB\>
+
+Size in MB for tmpfs filesystem, maximum size is 64GB or 50% of the
+systems total available memory.
+```
+
+```{cfgcmd} set container name \<name\> uid \<number\>
+```
+
+```{cfgcmd} set container name \<name\> gid \<number\>
+
+Set the User ID or Group ID of the container
+```
+
+```{cfgcmd} set container name \<name\> restart [no | on-failure | always]
+
+Set the restart behavior of the container.
+
+- **no**: Do not restart containers on exit
+- **on-failure**: Restart containers when they exit with a non-zero
+exit code, retrying indefinitely (default)
+- **always**: Restart containers when they exit, regardless of status,
+retrying indefinitely
+```
+
+```{cfgcmd} set container name \<name\> cpu-quota \<num\>
+
+This specifies the number of CPU resources the container can use.
+
+Default is 0 for unlimited.
+For example, 1.25 limits the container to use up to 1.25 cores
+worth of CPU time.
+This can be a decimal number with up to three decimal places.
+
+The command translates to "--cpus=\<num\>" when the container is created.
+```
+
+```{cfgcmd} set container name \<name\> memory \<MB\>
+
+Constrain the memory available to the container.
+
+Default is 512 MB. Use 0 MB for unlimited memory.
+```
+
+```{cfgcmd} set container name \<name\> device \<devicename\> source \<path\>
+```
+
+```{cfgcmd} set container name \<name\> device \<devicename\> destination \<path\>
+
+Add a host device to the container.
+```
+
+```{cfgcmd} set container name \<name\> capability \<text\>
+
+Set container capabilities or permissions.
+
+- **net-admin**: Network operations (interface, firewall, routing tables)
+- **net-bind-service**: Bind a socket to privileged ports
+(port numbers less than 1024)
+- **net-raw**: Permission to create raw network sockets
+- **setpcap**: Capability sets (from bounded or inherited set)
+- **sys-admin**: Administration operations (quotactl, mount, sethostname,
+setdomainame)
+- **sys-time**: Permission to set system clock
+```
+
+```{cfgcmd} set container name \<name\> sysctl parameter \<parameter\> value \<value\>
+
+Set container sysctl values.
+
+The subset of possible parameters are:
+
+- Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem,
+kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
+- Parameters beginning with fs.mqueue.*
+- Parameters beginning with net.* (only if user-defined network is used)
+```
+
+```{cfgcmd} set container name \<name\> label \<label\> value \<value\>
+
+Add metadata label for this container.
+```
+
+```{cfgcmd} set container name \<name\> disable
+
+Disable a container.
+```
+
+### Container Health checks
+
+
+By default, no health checks are run, even when defined by the image.
+
+```{cfgcmd} set container name \<name\> health-check
+
+Default health check is run for the container if defined by the image.
+```
+
+```{cfgcmd} set container name \<name\> health-check command \<command\>
+
+Override the default health check command from the image for a container.
+```
+
+```{cfgcmd} set container name \<name\> health check interval \<interval\>
+
+Override the default health-check interval. For example: `60`
+```
+
+```{cfgcmd} set container name \<name\> health check timeout \<timeout\>
+
+Override the default health-check timeout. For example: `10`
+```
+
+```{cfgcmd} set container name \<name\> health check retries \<retries\>
+
+Number of health check retries before container is considered unhealthy. For example: `1`
+```
+
+### Container Networks
+
+```{cfgcmd} set container network \<name\>
+
+Creates a named container network
+```
+
+```{cfgcmd} set container network \<name\> description
+
+A brief description what this network is all about.
+```
+
+```{cfgcmd} set container network \<name\> prefix \<ipv4|ipv6\>
+
+Define IPv4 and/or IPv6 prefix for a given network name.
+Both IPv4 and IPv6 can be used in parallel.
+```
+
+```{cfgcmd} set container network \<name\> mtu \<number\>
+
+Configure {abbr}`MTU (Maximum Transmission Unit)` for a given network. It
+is the size (in bytes) of the largest ethernet frame sent on this link.
+```
+
+```{cfgcmd} set container network \<name\> no-name-server
+
+Disable Domain Name System (DNS) plugin for this network.
+```
+
+```{cfgcmd} set container network \<name\> vrf \<nme\>
+
+Bind container network to a given VRF instance.
+```
+
+### Container Registry
+
+```{cfgcmd} set container registry \<name\>
+
+Adds registry to list of unqualified-search-registries. By default, for any
+image that does not include the registry in the image name, VyOS will use
+docker.io and quay.io as the container registry.
+```
+
+```{cfgcmd} set container registry \<name\> disable
+
+Disable a given container registry
+```
+
+```{cfgcmd} set container registry \<name\> authentication username
+```
+
+```{cfgcmd} set container registry \<name\> authentication password
+
+Some container registries require credentials to be used.
+
+Credentials can be defined here and will only be used when adding a
+container image to the system.
+```
+
+```{cfgcmd} set container registry \<name\> insecure
+
+Allow registry access over unencrypted HTTP or TLS connections with
+untrusted certificates.
+```
+
+```{cfgcmd} set container registry \<name\> mirror address \<address\>
+```
+
+```{cfgcmd} set container registry \<name\> mirror host-name \<host-name\>
+```
+
+```{cfgcmd} set container registry \<name\> mirror port \<port\>
+```
+
+```{cfgcmd} set container registry \<name\> mirror path \<path\>
+
+Registry mirror, use ``(host-name|address)[:port][/path]``.
+
+If you have mirror http://192.168.1.1:8080 for docker.io, you can use ``docker.io/some/repo`` or run ``podman pull docker.io/some/repo``
+
+:::{code-block} none
+set container registry docker.io mirror address 192.168.1.1
+set container registry docker.io mirror port 8080
+set container registry docker.io insecure
+:::
+If http://192.168.1.1:8080 is your own registry, you can use ``192.168.1.1:8080/some/repo`` or run ``podman pull 192.168.1.1:8080/some/repo``
+
+:::{code-block} none
+set container registry 192.168.1.1:8080 insecure
+:::
+```
+
+### Log Configuration
+
+```{cfgcmd} set container name \<name\> log-driver [k8s-file | journald | none]
+
+Set the default log driver for containers.
+
+- **k8s-file**: Log to a plain text file in Kubernetes-style format.
+- **journald**: Log to the system journal
+- **none**: Disable logging for the container
+
+Current default is journald.
+
+```
+
+## Operation Commands
+
+```{opcmd} add container image \<containername\>
+
+Pull a new image for container
+```
+```{opcmd} show container
+
+Show the list of all active containers.
+```
+```{opcmd} show container image
+
+Show the local container images.
+```
+```{opcmd} show container log \<containername\>
+
+Show logs from a given container
+```
+```{opcmd} show container network
+
+Show a list available container networks
+```
+```{opcmd} restart container \<containername\>
+
+Restart a given container
+```
+```{opcmd} update container image \<containername\>
+
+Update container image
+```
+```{opcmd} delete container image \<image id|all\> [force]
+
+Delete a particular container image based on it's image ID.
+You can also delete all container images at once.
+
+You can not delete a container image if it has more then one tag
+assigned, this is why there is a `force` option to pass down to
+the container image to also remove those images.
+```
+
+## Example Configuration
+
+For the sake of demonstration, [example #1 in the official documentation](https://www.zabbix.com/documentation/current/manual/installation/containers)
+to the declarative VyOS CLI syntax.
+
+```none
+set container network zabbix prefix 172.20.0.0/16
+set container network zabbix description 'Network for Zabbix component containers'
+
+set container name mysql-server image mysql:8.0
+set container name mysql-server network zabbix
+
+set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix'
+set container name mysql-server environment 'MYSQL_USER' value 'zabbix'
+set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd'
+set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd'
+
+set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest
+set container name zabbix-java-gateway network zabbix
+
+set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest
+set container name zabbix-server-mysql network zabbix
+
+set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server'
+set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix'
+set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix'
+set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd'
+set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd'
+set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway'
+
+set container name zabbix-server-mysql port zabbix source 10051
+set container name zabbix-server-mysql port zabbix destination 10051
+
+set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest
+set container name zabbix-web-nginx-mysql network zabbix
+
+set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix'
+set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql'
+set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server'
+set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix'
+set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd'
+set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd'
+
+set container name zabbix-web-nginx-mysql port http source 80
+set container name zabbix-web-nginx-mysql port http destination 8080
+```
diff --git a/docs/configuration/firewall/bridge.md b/docs/configuration/firewall/bridge.md
new file mode 100644
index 00000000..58acd531
--- /dev/null
+++ b/docs/configuration/firewall/bridge.md
@@ -0,0 +1,685 @@
+---
+lastproofread: '2026-03-28'
+---
+
+(firewall-configuration)=
+
+# Bridge Firewall Configuration
+
+## Overview
+
+Learn more about bridge firewall configuration
+and related op-mode commands.
+
+The following commands are covered in this section:
+
+```{cfgcmd} set firewall bridge \<options\>
+```
+
+From the main structure defined in
+{doc}`Firewall Overview</configuration/firewall/index>`
+in this section you can find detailed information only for the next part
+of the general structure:
+
+```none
+- set firewall
+    * bridge
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+         - prerouting
+            + filter
+         - name
+            + custom_name
+```
+
+Traffic that is received by the router on an interface that is a member of a
+bridge is processed on the **Bridge Layer**. Before the bridge decision is
+made, all packets are analyzed at **Prerouting**. First filters can be applied
+here, and also rules for ignoring connection tracking system can be configured.
+The relevant configuration that acts in **prerouting** is:
+
+
+- `set firewall bridge prerouting filter ...`.
+
+
+For traffic that needs to be switched internally by the bridge, the base
+chain is **forward**, and its base command for filtering is `set firewall
+bridge forward filter ...`, which happens in stage 4, highlighted with red
+color.
+
+
+:::{figure} /_static/images/firewall-bridge-forward.webp
+:::
+
+
+For traffic destined to the router itself or that needs to be routed
+(assuming a layer3 bridge is configured), the base chain is **input**, and the
+base command is `set firewall bridge input filter ...` and the path is:
+
+
+:::{figure} /_static/images/firewall-bridge-input.webp
+:::
+
+
+If it's not dropped, then the packet is sent to **IP Layer**, and will be
+processed by the **IP Layer** firewall: IPv4 or IPv6 ruleset. Check once again
+the {doc}`general packet flow diagram</configuration/firewall/index>` if
+needed.
+
+
+For traffic that originates from the bridge itself, the base chain is
+**output**, and the base command is `set firewall bridge output filter
+...`, and the path is:
+
+
+:::{figure} /_static/images/firewall-bridge-output.webp
+:::
+
+
+Custom bridge firewall chains can be created with the command `set firewall
+bridge name <name> ...`. To use such a custom chain, a rule with action jump
+and the appropriate target must be defined in a base chain.
+
+
+## Bridge Rules
+
+
+For firewall filtering, firewall rules need to be created. Each rule is
+numbered, has an action to apply if the rule is matched, and the ability
+to specify multiple matching criteria. Data packets go through the rules
+from 1 - 999999, so order is crucial. At the first match the action of the
+rule will be executed.
+
+
+### Actions
+
+
+If a rule is defined, an action must also be defined for it. This tells the
+firewall what to do if all matching criteria in the rule are met.
+
+
+In firewall bridge rules, the action can be:
+
+
+- `accept`: accept the packet.
+- `continue`: continue parsing next rule.
+- `drop`: drop the packet.
+- `jump`: jump to another custom chain.
+- `return`: Return from the current chain and continue at the next rule
+  of the last chain.
+- `queue`: Enqueue packet to userspace.
+- `notrack`: ignore connection tracking system. This action is only
+  available in prerouting chain.
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return]
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return]
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return]
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> action [accept | continue | drop | jump | notrack | queue | return]
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> action [accept | continue | drop | jump | queue | return]
+
+This required setting defines the action of the current rule. If action is
+set to jump, then jump-target is also needed.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> jump-target \<text\>
+
+If action is set to ``queue``, use next command to specify the queue
+target. Range is also supported:
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> queue \<0-65535\>
+
+Also, if action is set to ``queue``, use next command to specify the queue
+options. Possible options are ``bypass`` and ``fanout``:
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> queue-options fanout
+```
+
+Also, **default-action** is an action that takes place whenever a packet does
+not match any rule in its chain. For base chains, possible options for
+**default-action** are **accept** or **drop**.
+
+```{cfgcmd} set firewall bridge forward filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall bridge input filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall bridge output filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall bridge prerouting filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall bridge name \<name\> default-action [accept | continue | drop | jump | reject | return]
+
+This sets the default action of the rule-set if a packet does not match
+any of the rules in that chain. If default-action is set to ``jump``, then
+``default-jump-target`` is also needed. Note that for base chains, default
+action can only be set to ``accept`` or ``drop``, while on custom chains
+more actions are available.
+```
+
+```{cfgcmd} set firewall bridge name \<name\> default-jump-target \<text\>
+
+To be used only when ``default-action`` is set to ``jump``. Use this
+command to specify jump target for default rule.
+```
+:::{note}
+**Important note about default-actions:**
+If the default action for any base chain is not defined, then the default
+action is set to **accept** for that chain. For custom chains, if the
+default action is not defined, then the default-action is set to **drop**.
+:::
+
+
+### Firewall Logs
+
+
+You can enable logging for every firewall rule. If enabled, other log options
+can be configured.
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log
+
+Enable logging for the matched packet. If this configuration command is not
+present, then the log is not enabled.
+```
+
+```{cfgcmd} set firewall bridge forward filter default-log
+```
+
+```{cfgcmd} set firewall bridge input filter default-log
+```
+
+```{cfgcmd} set firewall bridge output filter default-log
+```
+
+```{cfgcmd} set firewall bridge prerouting filter default-log
+```
+
+```{cfgcmd} set firewall bridge name \<name\> default-log
+
+Use this command to enable the logging of the default action on
+the specified chain.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+
+Define log-level. Only applicable if rule log is enabled.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options group \<0-65535\>
+
+Define the log group to send messages to. Only applicable if rule log is
+enabled.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options snapshot-length \<0-9000\>
+
+Define length of packet payload to include in netlink message. Only
+applicable if rule log is enabled and the log group is defined.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options queue-threshold \<0-65535\>
+
+Define the number of packets to queue inside the kernel before sending them
+to userspace. Only applicable if rule log is enabled and the log group is
+defined.
+```
+
+### Firewall Description
+
+
+You can define a description for reference for every custom chain.
+
+```{cfgcmd} set firewall bridge name \<name\> description \<text\>
+
+Provide a rule-set description to a custom firewall chain.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> description \<text\>
+
+Provide a description for each rule.
+```
+
+### Rule Status
+
+
+By default, when you define a rule, it is enabled. In some cases, it is
+useful to disable the rule instead of removing it.
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> disable
+
+Command for disabling a rule but keep it in the configuration.
+```
+
+### Matching criteria
+
+
+There are many matching criteria against which a packet can be tested. Refer
+to {doc}`IPv4</configuration/firewall/ipv4>` and
+{doc}`IPv6</configuration/firewall/ipv6>` matching criteria for more details.
+
+
+Since bridges operate at layer 2, both matchers for IPv4 and IPv6 are
+supported in bridge firewall configuration. Same applies to firewall groups.
+
+
+Same specific matching criteria that can be used in bridge firewall are
+described in this section:
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+
+Match based on the Ethernet type of the packet.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+
+Match based on the Ethernet type of the packet when it is VLAN tagged.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan id \<0-4096\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan id \<0-4096\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan id \<0-4096\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan id \<0-4096\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> vlan id \<0-4096\>
+
+Match based on VLAN identifier. Range is also supported.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan priority \<0-7\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan priority \<0-7\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan priority \<0-7\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan priority \<0-7\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> vlan priority \<0-7\>
+
+Match based on VLAN priority (Priority Code Point - PCP). Range is also
+supported.
+```
+
+### Packet Modifications
+
+
+Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify
+packets before they are sent out. This feaure provides more flexibility in
+packet handling.
+
+```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set dscp \<0-63\>
+
+Set a specific value of Differentiated Services Codepoint (DSCP).
+```
+
+```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set mark \<1-2147483647\>
+
+Set a specific packet mark value.
+```
+
+```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set tcp-mss \<500-1460\>
+
+Set the TCP-MSS (TCP maximum segment size) for the connection.
+```
+
+```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set ttl \<0-255\>
+
+Set the TTL (Time to Live) value.
+```
+
+```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set hop-limit \<0-255\>
+
+Set hop limit value.
+```
+
+```{cfgcmd} set firewall bridge [forward | output] filter rule \<1-999999\> set connection-mark \<0-2147483647\>
+
+Set connection mark value.
+```
+
+### Use IP firewall
+
+By default, for switched traffic, only the rules defined under `set firewall
+bridge` are applied. There are two global-options that can be configured in
+order to force deeper analysis of the packet on the IP layer. These options
+are:
+
+```{cfgcmd} set firewall global-options apply-to-bridged-traffic ipv4
+
+This command enables the IPv4 firewall for bridged traffic. If this option
+is used, packets are also parsed by rules defined in ``set firewall ipv4
+...``
+```
+
+```{cfgcmd} set firewall global-options apply-to-bridged-traffic ipv6
+
+This command enables the IPv6 firewall for bridged traffic. If this option
+is used, packets are also parsed by rules defined in ``set firewall ipv6
+...``
+```
+
+## Operation-mode Firewall
+### Rule-set overview
+
+In this section you can find all useful firewall op-mode commands.
+General commands for firewall configuration, counter and statistics:
+
+```{opcmd} show firewall
+```
+
+```{opcmd} show firewall summary
+```
+
+```{opcmd} show firewall statistics
+```
+
+And, to print only bridge firewall information:
+
+```{opcmd} show firewall bridge
+```
+
+```{opcmd} show firewall bridge forward filter
+```
+
+```{opcmd} show firewall bridge forward filter rule \<rule\>
+```
+
+```{opcmd} show firewall bridge name \<name\>
+```
+
+```{opcmd} show firewall bridge name \<name\> rule \<rule\>
+```
+
+### Show Firewall log
+
+```{opcmd} show log firewall
+```
+
+```{opcmd} show log firewall bridge
+```
+
+```{opcmd} show log firewall bridge forward
+```
+
+```{opcmd} show log firewall bridge forward filter
+```
+
+```{opcmd} show log firewall bridge name \<name\>
+```
+
+```{opcmd} show log firewall bridge forward filter rule \<rule\>
+```
+
+```{opcmd} show log firewall bridge name \<name\> rule \<rule\>
+
+Show the logs of all firewall; show all bridge firewall logs; show all logs
+for forward hook; show all logs for forward hook and priority filter; show
+all logs for particular custom chain; show logs for specific Rule-Set.
+```
+
+### Example
+
+Configuration example:
+
+```none
+set firewall bridge forward filter default-action 'drop'
+set firewall bridge forward filter default-log
+set firewall bridge forward filter rule 10 action 'continue'
+set firewall bridge forward filter rule 10 inbound-interface name 'eth2'
+set firewall bridge forward filter rule 10 vlan id '22'
+set firewall bridge forward filter rule 20 action 'drop'
+set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT'
+set firewall bridge forward filter rule 20 vlan id '60'
+set firewall bridge forward filter rule 30 action 'jump'
+set firewall bridge forward filter rule 30 jump-target 'TEST'
+set firewall bridge forward filter rule 30 outbound-interface name '!eth1'
+set firewall bridge forward filter rule 35 action 'accept'
+set firewall bridge forward filter rule 35 vlan id '11'
+set firewall bridge forward filter rule 40 action 'continue'
+set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11'
+set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66'
+set firewall bridge name TEST default-action 'accept'
+set firewall bridge name TEST default-log
+set firewall bridge name TEST rule 10 action 'continue'
+set firewall bridge name TEST rule 10 log
+set firewall bridge name TEST rule 10 vlan priority '0'
+```
+
+And op-mode commands:
+
+```none
+vyos@BRI:~$ show firewall bridge
+Rulesets bridge Information
+
+---------------------------------
+bridge Firewall "forward filter"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  ---------------------------------------------------------------------
+10       continue  all                 0        0  iifname "eth2" vlan id 22  continue
+20       drop      all                 0        0  iifname @I_TRUNK-RIGHT vlan id 60
+30       jump      all              2130   170688  oifname != "eth1"  jump NAME_TEST
+35       accept    all              2080   168616  vlan id 11  accept
+40       continue  all                 0        0  ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66  continue
+default  drop      all                 0        0
+
+---------------------------------
+bridge Firewall "name TEST"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  --------------------------------------------------
+10       continue  all              2130   170688  vlan pcp 0  prefix "[bri-NAM-TEST-10-C]"  continue
+default  accept    all              2130   170688
+
+vyos@BRI:~$
+vyos@BRI:~$ show firewall bridge name TEST
+Ruleset Information
+
+---------------------------------
+bridge Firewall "name TEST"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  --------------------------------------------------
+10       continue  all              2130   170688  vlan pcp 0  prefix "[bri-NAM-TEST-10-C]"  continue
+default  accept    all              2130   170688
+
+vyos@BRI:~$
+```
+
+Inspect logs:
+
+```none
+vyos@BRI:~$ show log firewall bridge
+Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102
+Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102
+Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102
+...
+vyos@BRI:~$ show log firewall bridge forward filter
+Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0
+Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0
+```
diff --git a/docs/configuration/firewall/flowtables.md b/docs/configuration/firewall/flowtables.md
new file mode 100644
index 00000000..24d0675e
--- /dev/null
+++ b/docs/configuration/firewall/flowtables.md
@@ -0,0 +1,176 @@
+---
+lastproofread: '2026-03-30'
+---
+
+(firewall-flowtables-configuration)=
+
+# Flowtables Firewall Configuration
+
+```{include} /_include/need_improvement.txt
+```
+
+
+## Overview
+
+This section provides information on firewall configuration for flowtables.
+
+```{cfgcmd} set firewall flowtable ...
+```
+
+To learn about the general traffic flow in VyOS firewalls,
+see {doc}`Firewall </configuration/firewall/index>`.
+
+```none
+- set firewall
+    * flowtable
+         - custom_flow_table
+            + ...
+```
+
+Flowtables let you define a fastpath through the flowtable datapath.
+Flowtables support layer 3 (IPv4 and IPv6) and layer 4 (TCP and UDP)
+protocols.
+
+:::{figure} /_static/images/firewall-flowtable-packet-flow.webp
+:::
+
+After the first packet successfully traverses the IP forwarding path (black
+circles path), you can offload subsequent packets to the flowtable through your
+ruleset. You specify when to add a flow to the flowtable during forward
+filtering (red circle number 6).
+
+When a packet finds a matching entry in the flowtable (flowtable hit), the
+system transmits it to the output netdevice. This means packets bypass the
+classic IP forwarding path and use the **Fast Path** (orange circles path).
+As a result, you do not see these packets from any Netfilter hooks after
+ingress. If no matching entry exists in the flowtable (flowtable miss), the
+packet traverses the classic IP forwarding path.
+
+:::{note}
+**Flowtable Reference:**
+<https://docs.kernel.org/networking/nf_flowtable.html>
+:::
+
+## Flowtable Configuration
+
+To use flowtables, you need to configure the following:
+> - Create a flowtable that includes the interfaces
+>   that are going to be used by the flowtable.
+> - Create a firewall rule. Set the action to
+>   `offload` and use your desired flowtable for `offload-target`.
+
+Creating a flow table:
+
+```{cfgcmd} set firewall flowtable \<flow_table_name\> interface \<iface\>
+
+Specify interfaces to use in the flowtable.
+```
+
+```{cfgcmd} set firewall flowtable \<flow_table_name\> description \<text\>
+```
+
+Provide a description for the flow table.
+
+```{cfgcmd} set firewall flowtable \<flow_table_name\> offload \<hardware | software\>
+
+Specify the offload type the flowtable uses: ``hardware`` or
+``software``. The default is ``software`` offload.
+```
+:::{note}
+**Hardware offload**: Make sure your network interface controller
+(NIC) supports hardware offloading and that you have the necessary drivers
+> installed before enabling this option.
+:::
+
+Creating rules for using flow tables:
+
+```{cfgcmd} set firewall [ipv4 | ipv6] forward filter rule \<1-999999\> action offload
+
+Create a firewall rule in the forward chain with the action set to
+``offload``.
+```
+
+```{cfgcmd} set firewall [ipv4 | ipv6] forward filter rule \<1-999999\> offload-target \<flowtable\>
+
+Create a firewall rule in the forward chain and specify which flowtable
+to use. Only applicable if the action is ``offload``.
+```
+
+## Configuration Example
+
+Consider the following in this setup:
+> - This example uses two interfaces in the flowtables: `eth0` and `eth1`.
+> - The example provides a minimal firewall ruleset with filtering rules
+>   and rules for using flowtable offload capabilities.
+
+The first packet is evaluated by the firewall path, so a
+desired connection should be explicitly accepted.
+The same should occur for traffic in reverse order.
+In most cases, state policies are
+used to accept a connection in the reverse path.
+
+In the following example only traffic coming from interface `eth0`,
+TCP protocol, and destination port 1122 is accepted.
+All other traffic to the router is dropped.
+
+### Commands
+
+```none
+set firewall flowtable FT01 interface 'eth0'
+set firewall flowtable FT01 interface 'eth1'
+set firewall ipv4 forward filter default-action 'drop'
+set firewall ipv4 forward filter rule 10 action 'offload'
+set firewall ipv4 forward filter rule 10 offload-target 'FT01'
+set firewall ipv4 forward filter rule 10 state 'established'
+set firewall ipv4 forward filter rule 10 state 'related'
+set firewall ipv4 forward filter rule 20 action 'accept'
+set firewall ipv4 forward filter rule 20 state 'established'
+set firewall ipv4 forward filter rule 20 state 'related'
+set firewall ipv4 forward filter rule 110 action 'accept'
+set firewall ipv4 forward filter rule 110 destination address '192.0.2.100'
+set firewall ipv4 forward filter rule 110 destination port '1122'
+set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0'
+set firewall ipv4 forward filter rule 110 protocol 'tcp'
+```
+
+### Explanation
+
+Here's what happens for a desired connection:
+> 1. A packet arrives on `eth0` with destination address `192.0.2.100`, TCP
+>    protocol, and destination port 1122. Assume this address is reachable
+>    through interface `eth1`.
+> 2. For this first packet, the connection state is **new**. Neither rule 10
+>    nor rule 20 applies.
+> 3. Rule 110 matches, so the connection is accepted.
+> 4. When the server 192.0.2.100 replies, the connection state becomes
+>    **established**, and rule 20 accepts the reply.
+> 5. The router receives the second packet for this connection. Because the
+>    connection state is **established**, rule 10 matches and adds a new
+>    entry in the flowtable FT01 for this connection.
+> 6. Subsequent packets skip the traditional path and use the **Fast Path**
+>    for offloading.
+
+### Checks
+
+Check the conntrack table to verify that the system accepted and properly
+offloaded connections.
+
+```none
+vyos@FlowTables:~$ show firewall ipv4 forward filter
+Ruleset Information
+
+---------------------------------
+ipv4 Firewall "forward filter"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  ----------------------------------------------------------------
+10       offload   all                 8      468  ct state { established, related }  flow add @VYOS_FLOWTABLE_FT01
+20       accept    all                 8      468  ct state { established, related }  accept
+110      accept    tcp                 2      120  ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0"  accept
+default  drop      all                 7      420
+
+vyos@FlowTables:~$ sudo conntrack -L | grep tcp
+conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown.
+tcp      6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2
+vyos@FlowTables:~$
+```
diff --git a/docs/configuration/firewall/global-options.md b/docs/configuration/firewall/global-options.md
new file mode 100644
index 00000000..0f6d91ac
--- /dev/null
+++ b/docs/configuration/firewall/global-options.md
@@ -0,0 +1,186 @@
+---
+lastproofread: '2026-03-30'
+---
+
+(firewall-global-options-configuration)=
+
+# Global Options Firewall Configuration
+
+## Overview
+
+Some firewall settings are global and affect the entire system. This section
+provides information about these global options that you can configure using
+the VyOS CLI.
+
+Configuration commands covered in this section:
+
+```{cfgcmd} set firewall global-options ...
+```
+
+## Configuration
+
+```{cfgcmd} set firewall global-options all-ping [enable | disable]
+
+By default, when VyOS receives an ICMP echo request packet destined for
+itself, it answers with an ICMP echo reply, unless your firewall prevents
+it.
+
+You can set firewall rules to accept, drop, or reject ICMP in, out, or
+local traffic. You can also use the **firewall global-options all-ping**
+command. This command affects only LOCAL traffic (packets destined for your
+VyOS system), not IN or OUT traffic.
+
+:::{note}
+**firewall global-options all-ping** affects only LOCAL traffic
+and always behaves in the most restrictive way
+:::
+:::{code-block} none
+set firewall global-options all-ping enable
+:::
+When you set this command, VyOS answers every ICMP echo request addressed
+to itself, but that response occurs only if no other rule drops or rejects
+local echo requests. In case of conflict, VyOS does not answer ICMP echo
+requests.
+
+:::{code-block} none
+set firewall global-options all-ping disable
+:::
+When you set this command, VyOS answers no ICMP echo requests addressed to
+itself, regardless of where they come from or what specific rules accept
+them.
+```
+
+```{cfgcmd} set firewall global-options apply-to-bridged-traffic [ipv4 | ipv6]
+
+Apply IPv4 or IPv6 firewall rules to bridged traffic.
+```
+
+```{cfgcmd} set firewall global-options broadcast-ping [enable | disable]
+
+Enable or disable the response to ICMP broadcast messages. The system
+alters the following parameter:
+* ``net.ipv4.icmp_echo_ignore_broadcasts``
+```
+
+```{cfgcmd} set firewall global-options ip-src-route [enable | disable]
+```
+
+```{cfgcmd} set firewall global-options ipv6-src-route [enable | disable]
+
+Set whether VyOS accepts packets with a source route option.
+The following sysctl parameters will be changed:
+* ``net.ipv4.conf.all.accept_source_route``
+* ``net.ipv6.conf.all.accept_source_route``
+```
+
+```{cfgcmd} set firewall global-options receive-redirects [enable | disable]
+```
+
+```{cfgcmd} set firewall global-options ipv6-receive-redirects [enable | disable]
+
+Allow VyOS to accept ICMPv4 and ICMPv6 redirect messages.
+The following sysctl parameters will be changed:
+* ``net.ipv4.conf.all.accept_redirects``
+* ``net.ipv6.conf.all.accept_redirects``
+```
+
+```{cfgcmd} set firewall global-options send-redirects [enable | disable]
+
+Allow VyOS to send ICMPv4 redirect messages.
+The following sysctl parameter will be changed:
+* ``net.ipv4.conf.all.send_redirects``
+```
+
+```{cfgcmd} set firewall global-options log-martians [enable | disable]
+
+Allow VyOS to log martian IPv4 packets.
+The following sysctl parameter will be changed:
+* ``net.ipv4.conf.all.log_martians``
+```
+
+```{cfgcmd} set firewall global-options source-validation [strict | loose | disable]
+
+Set the IPv4 source validation mode.
+The following sysctl parameter will be changed:
+* ``net.ipv4.conf.all.rp_filter``
+```
+
+```{cfgcmd} set firewall global-options syn-cookies [enable | disable]
+
+Allow VyOS to use IPv4 TCP SYN Cookies.
+The following sysctl parameter will be changed:
+* ``net.ipv4.tcp_syncookies``
+```
+
+```{cfgcmd} set firewall global-options twa-hazards-protection [enable | disable]
+
+Enable or disable VyOS {rfc}`1337` conformance.
+The following sysctl parameter will be changed:
+* ``net.ipv4.tcp_rfc1337``
+```
+
+```{cfgcmd} set firewall global-options state-policy established action [accept | drop | reject]
+```
+
+```{cfgcmd} set firewall global-options state-policy established log
+```
+
+```{cfgcmd} set firewall global-options state-policy established log-level [emerg | alert | crit | err | warn | notice | info | debug]
+
+Set the global setting for an established connection.
+```
+
+```{cfgcmd} set firewall global-options state-policy invalid action [accept | drop | reject]
+```
+
+```{cfgcmd} set firewall global-options state-policy invalid log
+```
+
+```{cfgcmd} set firewall global-options state-policy invalid log-level [emerg | alert | crit | err | warn | notice | info | debug]
+
+Set the global setting for invalid packets.
+```
+
+```{cfgcmd} set firewall global-options state-policy related action [accept | drop | reject]
+```
+
+```{cfgcmd} set firewall global-options state-policy related log
+```
+
+```{cfgcmd} set firewall global-options state-policy related log-level [emerg | alert | crit | err | warn | notice | info | debug]
+
+Set the global setting for related connections.
+```
+
+VyOS supports setting timeouts for connections by connection type. You can
+set timeout values for generic connections, ICMP connections, UDP
+connections, or TCP connections in various states.
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options timeout icmp <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout other <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout tcp close <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout tcp close-wait <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout tcp established <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout tcp fin-wait <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout tcp last-ack <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout tcp syn-recv <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout tcp syn-sent <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout tcp time-wait <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout udp other <1-21474836>
+    :defaultvalue:
+.. cfgcmd:: set firewall global-options timeout udp stream <1-21474836>
+    :defaultvalue:
+
+    Set the timeout in seconds for a protocol or state.
+```
\ No newline at end of file
diff --git a/docs/configuration/firewall/groups.md b/docs/configuration/firewall/groups.md
new file mode 100644
index 00000000..817f610e
--- /dev/null
+++ b/docs/configuration/firewall/groups.md
@@ -0,0 +1,477 @@
+---
+lastproofread: '2026-03-30'
+---
+
+(firewall-groups-configuration)=
+
+# Firewall groups
+
+## Configuration
+
+Firewall groups represent collections of IP addresses, networks, ports,
+MAC addresses, domains, or interfaces. You can reference a group in firewall,
+NAT, and policy route rules as either a source or destination matcher, and/or
+as inbound or outbound in the case of interface groups.
+
+### Address Groups
+
+An **address group** contains a single IP address or IP address range.
+
+```{cfgcmd} set firewall group address-group \<name\> address [address | address range]
+
+```
+```{cfgcmd} set firewall group ipv6-address-group \<name\> address \<address\>
+
+Define an IPv4 or IPv6 address group.
+
+:::{code-block} none
+set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1
+set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8
+set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1
+:::
+```
+
+```{cfgcmd} set firewall group address-group \<name\> description \<text\>
+```
+
+```{cfgcmd} set firewall group ipv6-address-group \<name\> description \<text\>
+
+Provide an IPv4 or IPv6 address group description.
+```
+
+### Remote Groups
+
+A **remote-group** uses a URL that hosts a newline-delimited list of IPv4
+and/or IPv6 addresses, CIDRs, and ranges. VyOS pulls this list periodically
+according to the frequency you define in the firewall **resolver-interval**
+and loads matching entries into the group for use in rules. The list is cached
+in persistent storage, so rules continue to function if updates fail.
+
+```{cfgcmd} set firewall group remote-group \<name\> url \<http(s) url\>
+
+Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs
+to fetch.
+```
+
+```{cfgcmd} set firewall group remote-group \<name\> description \<text\>
+
+Set a description for a remote group.
+```
+
+The remote list format is flexible. VyOS attempts to parse the first word of
+each line as an entry and skips lines it cannot match. Lines that begin with
+an alphanumeric character but do not match valid IPv4 or IPv6 addresses,
+ranges, or CIDRs are logged to the system log. The following examples show
+acceptable formats that VyOS parses correctly:
+
+```none
+127.0.0.1
+127.0.0.0/24
+127.0.0.1-127.0.0.254
+2001:db8::1
+2001:db8:cafe::/48
+2001:db8:cafe::1-2001:db8:cafe::ffff
+```
+
+### Network Groups
+
+**Network groups** accept IP networks in CIDR notation. You can add specific
+IP addresses as a 32-bit prefix. If you need to add a mix of addresses and
+networks, use a network group.
+
+```{cfgcmd} set firewall group network-group \<name\> network \<CIDR\>
+```
+
+```{cfgcmd} set firewall group ipv6-network-group \<name\> network \<CIDR\>
+
+Define an IPv4 or IPv6 network group.
+
+:::{code-block} none
+set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24
+set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24
+set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64
+:::
+```
+
+```{cfgcmd} set firewall group network-group \<name\> description \<text\>
+```
+
+```{cfgcmd} set firewall group ipv6-network-group \<name\> description \<text\>
+
+Provide an IPv4 or IPv6 network group description.
+```
+
+### Interface Groups
+
+An **interface group** represents a collection of interfaces.
+
+```{cfgcmd} set firewall group interface-group \<name\> interface \<text\>
+
+Define an interface group.
+Wildcard ``*`` is supported. For example: ``eth3*``.
+Prepend the character ``!`` to invert the criteria. For example: ``!eth2``.
+```
+
+```none
+set firewall group interface-group LAN interface bond1001
+set firewall group interface-group LAN interface eth3*
+```
+
+```{cfgcmd} set firewall group interface-group \<name\> description \<text\>
+
+Provide an interface group description.
+```
+
+### Port Groups
+
+A **port group** represents only port numbers, not the protocol. You can
+reference port groups for either TCP or UDP. Create TCP and UDP groups
+separately to avoid accidentally filtering unnecessary ports. Specify port
+ranges by using `-`.
+
+```{cfgcmd} set firewall group port-group \<name\> port [portname | portnumber | startport-endport]
+
+Define a port group. A port name can be any name defined in
+/etc/services. For example, ``http``.
+
+:::{code-block} none
+set firewall group port-group PORT-TCP-SERVER1 port http
+set firewall group port-group PORT-TCP-SERVER1 port 443
+set firewall group port-group PORT-TCP-SERVER1 port 5000-5010
+:::
+```
+
+```{cfgcmd} set firewall group port-group \<name\> description \<text\>
+
+Provide a port group description.
+```
+
+### MAC Groups
+
+A **mac group** represents a collection of mac addresses.
+
+```{cfgcmd} set firewall group mac-group \<name\> mac-address \<mac-address\>
+
+Define a mac group.
+```
+
+```none
+set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f
+set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81
+```
+
+```{cfgcmd} set firewall group mac-group \<name\> description \<text\>
+
+Provide a MAC group description.
+```
+
+### Domain Groups
+
+A **domain group** represents a collection of domains.
+
+```{cfgcmd} set firewall group domain-group \<name\> address \<domain\>
+
+Define a domain group.
+```
+
+```none
+set firewall group domain-group DOM address example.com
+```
+
+```{cfgcmd} set firewall group domain-group \<name\> description \<text\>
+
+Provide a domain group description.
+```
+
+### Dynamic Groups
+
+Firewall dynamic groups differ from other groups because you can use them as
+source/destination in firewall rules, and members are not defined statically
+in VyOS configuration. Instead, firewall rules dynamically add members to
+these groups.
+
+#### Defining Dynamic Address Groups
+
+Dynamic address groups support both IPv4 and IPv6 families. Use these
+commands to define dynamic IPv4 and IPv6 address groups:
+
+```{cfgcmd} set firewall group dynamic-group address-group \<name\>
+```
+
+```{cfgcmd} set firewall group dynamic-group ipv6-address-group \<name\>
+```
+
+Add description to firewall groups:
+
+```{cfgcmd} set firewall group dynamic-group address-group \<name\> description \<text\>
+```
+
+```{cfgcmd} set firewall group dynamic-group ipv6-address-group \<name\> description \<text\>
+```
+
+#### Adding elements to Dynamic Firewall Groups
+
+After you define dynamic firewall groups, use them in firewall rules to
+dynamically add elements to them.
+
+Commands used for this task are:
+- Add destination IP address of the connection to a dynamic address group:
+
+```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group destination-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group destination-address address-group \<name\>
+```
+
+- Add source IP address of the connection to a dynamic address group:
+
+```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group source-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group source-address address-group \<name\>
+```
+
+You can define specific timeouts per rule. When a rule matches, the source or
+destination address is added to the group, and the element remains in the group
+until the timeout expires. If you do not define a timeout, the element remains
+in the group until the next reboot or until you commit firewall configuration
+changes.
+
+```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\>
+```
+
+```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\>
+```
+
+Timeout can be defined using seconds, minutes, hours or days:
+
+```none
+set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout
+Possible completions:
+<number>s            Timeout value in seconds
+<number>m            Timeout value in minutes
+<number>h            Timeout value in hours
+<number>d            Timeout value in days
+```
+
+#### Using Dynamic Firewall Groups
+
+Like other firewall groups, you can use dynamic firewall groups in firewall
+rules as matching options. For example:
+
+```none
+set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO
+set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR
+```
+
+## Examples
+
+### General example
+
+After you create firewall groups, you can reference them in firewall, NAT,
+NAT66, and/or policy-route rules. The following example creates multiple
+groups:
+
+```{eval-rst}
+   .. code-block:: none
+
+      set firewall group address-group SERVERS address 198.51.100.101
+      set firewall group address-group SERVERS address 198.51.100.102
+      set firewall group network-group TRUSTEDv4 network 192.0.2.0/30
+      set firewall group network-group TRUSTEDv4 network 203.0.113.128/25
+      set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64
+      set firewall group interface-group LAN interface eth2.2001
+      set firewall group interface-group LAN interface bon0
+      set firewall group port-group PORT-SERVERS port http
+      set firewall group port-group PORT-SERVERS port 443
+      set firewall group port-group PORT-SERVERS port 5000-5010
+```
+
+And next, some configuration example where groups are used:
+
+```{eval-rst}
+   .. code-block:: none
+
+      set firewall ipv4 output filter rule 10 action accept
+      set firewall ipv4 output filter rule 10 outbound-interface group !LAN
+      set firewall ipv4 forward filter rule 20 action accept
+      set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4
+      set firewall ipv6 input filter rule 10 action accept
+      set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6
+      set nat destination rule 101 inbound-interface group LAN
+      set nat destination rule 101 destination group address-group SERVERS
+      set nat destination rule 101 protocol tcp
+      set nat destination rule 101 destination group port-group PORT-SERVERS
+      set nat destination rule 101 translation address 203.0.113.250
+      set policy route PBR rule 201 destination group port-group PORT-SERVERS
+      set policy route PBR rule 201 protocol tcp
+      set policy route PBR rule 201 set table 15
+```
+
+### Port knocking example
+
+You can use dynamic firewall groups with port knocking to secure access to
+the router or any other device. The following example shows a 4-step port
+knocking configuration:
+
+```{eval-rst}
+   .. code-block:: none
+
+      set firewall global-options state-policy established action 'accept'
+      set firewall global-options state-policy invalid action 'drop'
+      set firewall global-options state-policy related action 'accept'
+      set firewall group dynamic-group address-group ALLOWED
+      set firewall group dynamic-group address-group PN_01
+      set firewall group dynamic-group address-group PN_02
+      set firewall ipv4 input filter default-action 'drop'
+      set firewall ipv4 input filter rule 5 action 'accept'
+      set firewall ipv4 input filter rule 5 protocol 'icmp'
+      set firewall ipv4 input filter rule 10 action 'drop'
+      set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01'
+      set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m'
+      set firewall ipv4 input filter rule 10 description 'Port_nock 01'
+      set firewall ipv4 input filter rule 10 destination port '9990'
+      set firewall ipv4 input filter rule 10 protocol 'tcp'
+      set firewall ipv4 input filter rule 20 action 'drop'
+      set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02'
+      set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m'
+      set firewall ipv4 input filter rule 20 description 'Port_nock 02'
+      set firewall ipv4 input filter rule 20 destination port '9991'
+      set firewall ipv4 input filter rule 20 protocol 'tcp'
+      set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01'
+      set firewall ipv4 input filter rule 30 action 'drop'
+      set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED'
+      set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h'
+      set firewall ipv4 input filter rule 30 description 'Port_nock 03'
+      set firewall ipv4 input filter rule 30 destination port '9992'
+      set firewall ipv4 input filter rule 30 protocol 'tcp'
+      set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02'
+      set firewall ipv4 input filter rule 99 action 'accept'
+      set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh'
+      set firewall ipv4 input filter rule 99 destination port '22'
+      set firewall ipv4 input filter rule 99 protocol 'tcp'
+      set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED'
+```
+
+Before testing, we can check the members of firewall groups:
+
+```none
+vyos@vyos# run show firewall group
+Firewall Groups
+
+Name     Type                    References            Members        Timeout    Expires
+-------  ----------------------  --------------------  -------------  ---------  ---------
+ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+PN_01    address_group(dynamic)  ipv4-input-filter-10  N/D            N/D        N/D
+PN_02    address_group(dynamic)  ipv4-input-filter-20  N/D            N/D        N/D
+[edit]
+vyos@vyos#
+```
+
+With this configuration, to gain SSH access to the router, the user must:
+
+1. Create a new TCP connection to destination port 9990. A new entry is added
+   to dynamic firewall group `PN_01`.
+
+   ```none
+   vyos@vyos# run show firewall group
+   Firewall Groups
+
+   Name     Type                    References            Members        Timeout    Expires
+   -------  ----------------------  --------------------  -------------  ---------  ---------
+   ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+   PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31  120        119
+   PN_02    address_group(dynamic)  ipv4-input-filter-20  N/D            N/D        N/D
+   [edit]
+   vyos@vyos#
+   ```
+
+2. Create a new TCP connection to destination port 9991. A new entry is added
+   to dynamic firewall group `PN_02`.
+
+   ```none
+   vyos@vyos# run show firewall group
+   Firewall Groups
+
+   Name     Type                    References            Members        Timeout    Expires
+   -------  ----------------------  --------------------  -------------  ---------  ---------
+   ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+   PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31  120        106
+   PN_02    address_group(dynamic)  ipv4-input-filter-20  192.168.89.31  180        179
+   [edit]
+   vyos@vyos#
+   ```
+
+3. Create a new TCP connection to destination port 9992. A new entry is added
+   to dynamic firewall group `ALLOWED`.
+
+   ```none
+   vyos@vyos# run show firewall group
+   Firewall Groups
+
+   Name     Type                    References            Members        Timeout    Expires
+   -------  ----------------------  --------------------  -------------  ---------  ---------
+   ALLOWED  address_group(dynamic)  ipv4-input-filter-30  192.168.89.31       7200       7199
+   PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31        120         89
+   PN_02    address_group(dynamic)  ipv4-input-filter-20  192.168.89.31        180        170
+   [edit]
+   vyos@vyos#
+   ```
+
+4. Now you can connect via SSH to the router (assuming SSH is
+   configured).
+
+## Operation-mode
+
+```{opcmd} show firewall group
+```
+
+```{opcmd} show firewall group \<name\>
+
+Display an overview of defined groups, including the firewall group name,
+type, references (where the group is used), members, timeout, and
+expiration (the last two only apply to dynamic firewall groups).
+```
+
+Here is an example of such command:
+
+```none
+vyos@vyos:~$ show firewall group
+Firewall Groups
+
+Name          Type                    References              Members             Timeout    Expires
+------------  ----------------------  ----------------------  ----------------  ---------  ---------
+SERVERS       address_group           nat-destination-101     198.51.100.101
+                                                              198.51.100.102
+ALLOWED       address_group(dynamic)  ipv4-input-filter-30    192.168.77.39          7200       7174
+PN_01         address_group(dynamic)  ipv4-input-filter-10    192.168.0.245           120        112
+                                                              192.168.77.39           120         85
+PN_02         address_group(dynamic)  ipv4-input-filter-20    192.168.77.39           180        151
+LAN           interface_group         ipv4-output-filter-10   bon0
+                                      nat-destination-101     eth2.2001
+TRUSTEDv6     ipv6_network_group      ipv6-input-filter-10    2001:db8::/64
+TRUSTEDv4     network_group           ipv4-forward-filter-20  192.0.2.0/30
+                                                              203.0.113.128/25
+PORT-SERVERS  port_group              route-PBR-201           443
+                                      route-PBR-201           5000-5010
+                                      nat-destination-101     http
+vyos@vyos:~$
+```
diff --git a/docs/configuration/firewall/index.md b/docs/configuration/firewall/index.md
new file mode 100644
index 00000000..81699154
--- /dev/null
+++ b/docs/configuration/firewall/index.md
@@ -0,0 +1,278 @@
+---
+lastproofread: '2026-03-30'
+---
+
+# Firewall
+
+:::{warning}
+Due to a boot-time race condition, all interfaces initialize
+before the firewall. This temporarily leaves the system open to all traffic
+and poses a security risk.
+:::
+
+VyOS uses Netfilter. The Netfilter
+project developed `iptables` and its successor `nftables` for the Linux
+kernel to process packet data flows directly. This extends the concept of
+zone-based security to let you manipulate data at multiple stages after the
+network interface and driver accept it, and before sending it to its
+destination (for example, a web server or another device).
+
+The following is a simplified traffic flow diagram based on Netfilter
+packet flow.
+This diagram provides an overview of how packets are processed and the
+possible paths traffic can take.
+
+:::{figure} /_static/images/firewall-gral-packet-flow.webp
+:::
+
+The main points regarding packet flow and terminology in VyOS firewall
+are:
+
+- **Bridge Port?**: Choose the appropriate path based on whether the
+  interface where the packet was received is part of a bridge.
+
+If the interface where the packet was received is not part of a bridge, the
+packet is processed at the **IP Layer**:
+
+```{eval-rst}
+   * **Prerouting**: The router processes all packets in this stage,
+     regardless of the destination. You can perform several actions in
+     this stage, and these actions are also defined in different parts of the
+     VyOS configuration. Order is important. The relevant configuration that
+     applies in this stage includes:
+
+      * **Firewall prerouting**: Rules you define under ``set firewall
+        [ipv4 | ipv6] prerouting raw...``. The system processes all rules in
+        this section before the connection tracking subsystem.
+
+      * **Conntrack Ignore**: Rules you define under ``set system conntrack
+        ignore [ipv4 | ipv6] ...``. You can configure this section with
+        ``firewall [ipv4 | ipv6] prerouting ...``. For compatibility reasons,
+        this feature is supported, but will be deprecated in the future.
+
+      * **Policy Route**: Rules you define under ``set policy [route |
+        route6] ...``.
+
+      * **Destination NAT**: Rules you define under ``set [nat | nat66]
+        destination...``.
+
+   * **Destination is the router?**: Choose the appropriate path based on the
+     destination IP address. Transit traffic continues to **forward**, while
+     traffic destined for the router continues to **input**.
+
+   * **Input**: The stage where you filter and control traffic destined for
+     the router itself. This is where you enforce all rules for securing the
+     router. This includes IPv4 and IPv6 filtering rules, defined in:
+
+     * ``set firewall ipv4 input filter ...``.
+
+     * ``set firewall ipv6 input filter ...``.
+
+   * **Forward**: The stage where you filter and control transit traffic.
+     This includes IPv4 and IPv6 filtering rules, defined in:
+
+     * ``set firewall ipv4 forward filter ...``.
+
+     * ``set firewall ipv6 forward filter ...``.
+
+   * **Output**: The stage where you filter and control traffic that the
+     router originates. Note that this traffic comes from either a new
+     connection that an internal process on the VyOS router (such as NTP)
+     originates or a response to traffic the router receives externally through
+     **input** (for example, a response to an SSH login attempt). This includes
+     IPv4 and IPv6 rules, and two different sections apply:
+
+     * **Output Prerouting**: ``set firewall [ipv4 | ipv6] output
+       filter ...``. As described in **Prerouting**, the system processes
+       rules in this section before the connection tracking subsystem.
+
+     * **Output Filter**: ``set firewall [ipv4 | ipv6] output filter ...``.
+
+   * **Postrouting**: As in **Prerouting**, you can perform several actions
+     defined in different parts of VyOS configuration in this stage. This
+     includes:
+
+     * **Source NAT**: Rules you define under ``set [nat | nat66]
+       destination...``.
+```
+
+If the interface where the packet was received is part of a bridge, the
+packet is processed at the **Bridge Layer**:
+
+```{eval-rst}
+   * **Prerouting (Bridge)**: The bridge processes all packets it receives in
+     this stage, regardless of the destination. First, you can apply filters
+     here, or you can configure rules that ignore the connection tracking
+     system. The relevant configuration that applies:
+
+     * ``set firewall bridge prerouting filter ...``.
+
+   * **Forward (Bridge)**: The stage where you filter and control traffic
+     that passes through the bridge:
+
+     * ``set firewall bridge forward filter ...``.
+
+   * **Input (Bridge)**: The stage where you filter and control traffic
+     destined for the bridge itself:
+
+     * ``set firewall bridge input filter ...``.
+
+   * **Output (Bridge)**: The stage where you filter and control traffic that
+     the bridge originates:
+
+     * ``set firewall bridge output filter ...``.
+```
+
+The following is the overall structure of the VyOS firewall CLI:
+
+```none
+- set firewall
+    * bridge
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+         - prerouting
+            + filter
+         - name
+            + custom_name
+    * flowtable
+         - custom_flow_table
+            + ...
+    * global-options
+         + all-ping
+         + broadcast-ping
+         + ...
+    * group
+         - address-group
+         - ipv6-address-group
+         - network-group
+         - ipv6-network-group
+         - interface-group
+         - mac-group
+         - port-group
+         - domain-group
+    * ipv4
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+            + raw
+         - prerouting
+            + raw
+         - name
+            + custom_name
+    * ipv6
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+            + raw
+         - prerouting
+            + raw
+         - ipv6-name
+            + custom_name
+    * zone
+         - custom_zone_name
+            + ...
+```
+
+Here is a list of VyOS firewall CLI subcommands and their
+corresponding pages in the documentation:
+
+```{cfgcmd} set firewall bridge ...
+
+Configure bridge firewall rules for traffic at the bridge layer.
+See the Bridge Firewall Configuration page for detailed information.
+```
+
+```{cfgcmd} set firewall flowtable ...
+
+Configure firewall flowtables for stateful connection tracking and rules.
+See the Flowtables Firewall Configuration page for detailed information.
+```
+
+```{cfgcmd} set firewall global-options ...
+
+Configure global firewall options such as ``all-ping``, ``broadcast-ping``,
+``syn-cookies``, and other system-wide firewall settings.
+See the Global Firewall Options page for detailed information.
+```
+
+```{cfgcmd} set firewall group ...
+
+Organize firewall rules by creating reusable address, network, interface,
+MAC, port, and domain groups. Use groups in multiple rules to simplify
+configuration and maintenance.
+See the Firewall Groups page for detailed information.
+```
+
+```{cfgcmd} set firewall ipv4 ...
+
+Configure IPv4-specific firewall rules.
+See the IPv4 Firewall Configuration page for detailed information.
+```
+
+```{cfgcmd} set firewall ipv6 ...
+
+Configure IPv6-specific firewall rules.
+See the IPv6 Firewall Configuration page for detailed information.
+```
+
+```{cfgcmd} set firewall zone ...
+
+Configure zone-based firewall policies for controlling traffic between
+different network zones.
+See the Zone-Based Firewall Configuration page for detailed information.
+```
+
+For more information on firewall configuration, see the following pages:
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+global-options
+groups
+bridge
+ipv4
+ipv6
+flowtables
+```
+
+:::{note}
+For more information on Netfilter hooks and Linux networking packet flows,
+see the [Netfilter-Hooks](<https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks>)
+documentation.
+:::
+
+## Zone-Based firewall
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+zone
+```
+
+With zone-based firewalls, a new concept applies. In addition to the standard
+in and out traffic flows, a local flow enables traffic originating from and
+destined to the router itself. This means you must configure additional rules to
+secure the firewall from the network, in addition to the existing inbound and
+outbound rules.
+
+To configure VyOS with zone-based firewall, see
+{doc}`Zone-Based Firewall Configuration </configuration/firewall/zone>`.
+
+As the following example image shows, you must configure rules to allow or block
+traffic to or from the services running on the device that have open
+connections on that interface.
+
+:::{figure} /_static/images/firewall-zonebased.webp
+:::
diff --git a/docs/configuration/firewall/ipv4.md b/docs/configuration/firewall/ipv4.md
new file mode 100644
index 00000000..04c4fc70
--- /dev/null
+++ b/docs/configuration/firewall/ipv4.md
@@ -0,0 +1,1544 @@
+---
+lastproofread: '2026-03-30'
+---
+
+(firewall-ipv4-configuration)=
+
+# IPv4 Firewall Configuration
+
+## Overview
+
+This section provides information on IPv4 firewall configuration and
+appropriate operation-mode commands. This section covers the following
+configuration commands:
+
+```{cfgcmd} set firewall ipv4 ...
+```
+
+To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall </configuration/firewall/index>`.
+
+```none
+- set firewall
+    * ipv4
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+            + raw
+         - prerouting
+            + raw
+         - name
+            + custom_name
+```
+
+First, the router receives all traffic and processes it in the **prerouting**
+stage.
+
+This stage includes:
+
+- **Firewall Prerouting**: commands found under `set firewall ipv4
+  prerouting raw ...`
+- {doc}`Conntrack Ignore</configuration/system/conntrack>`: `set system
+  conntrack ignore ipv4...`
+- {doc}`Policy Route</configuration/policy/route>`: commands found under
+  `set policy route ...`
+- {doc}`Destination NAT</configuration/nat/nat44>`: commands found under
+  `set nat destination ...`
+
+For transit traffic, which is received by the router and forwarded, the base
+chain is **forward**. The following is a simplified packet flow diagram for
+transit traffic:
+
+:::{figure} /_static/images/firewall-fwd-packet-flow.webp
+:::
+
+The base firewall chain for configuring filtering rules for transit traffic is
+`set firewall ipv4 forward filter ...`, which occurs in stage 5, highlighted
+in red.
+
+For traffic to the router itself, the base chain is **input**. For traffic
+the router originates, the base chain is **output**. A simplified packet flow
+diagram is shown next, which shows the path for traffic destined to the router
+itself and traffic the router generates (starting from circle number 6):
+
+:::{figure} /_static/images/firewall-input-packet-flow.webp
+:::
+
+The base chain for traffic towards the router is
+`set firewall ipv4 input filter ...`
+
+The base chain for traffic the router generates is `set firewall ipv4
+output ...`, where two sub-chains are available: **filter** and **raw**:
+
+- **Output Prerouting**: `set firewall ipv4 output raw ...`. As described
+  in **Prerouting**, the system processes rules in this section before the
+  connection tracking subsystem.
+- **Output Filter**: `set firewall ipv4 output filter ...`. The system
+  processes rules in this section after the connection tracking subsystem.
+
+:::{note}
+**Important note about default-actions:**
+If you do not define a default action for a base chain, the system sets
+the default action to **accept** for that chain. For custom chains, if you
+do not define a default action, the system sets the default-action to
+**drop**.
+:::
+
+You can create custom firewall chains using the following commands:
+`set firewall ipv4 name <name> ...`. To use a custom chain, you must define
+a rule with the **action jump** and the appropriate **target** in a base
+chain.
+
+## Firewall - IPv4 Rules
+
+Each firewall rule has a
+number, an action to apply if the rule matches, and the ability to specify
+multiple matching criteria. Packets traverse rules numbered 1-999999, so order
+is crucial. The system executes the rule action at the first match.
+
+### Actions
+
+If you define a rule, you must define an action for it. The action tells the
+firewall what to do if all the criteria you define for that rule are met.
+
+The action can be:
+
+- `accept`: Accept the packet.
+- `continue`: Continue parsing the next rule.
+- `drop`: Drop the packet.
+- `reject`: Reject the packet.
+- `jump`: Jump to another custom chain.
+- `return`: Return from the current chain and continue at the next rule
+  of the last chain.
+- `queue`: Enqueue packet to userspace.
+- `synproxy`: Synproxy the packet.
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return]
+
+This required setting defines the action of the current rule. If you set
+the action to jump, you must also specify a jump-target.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> jump-target \<text\>
+
+Use this command only when the action is set to ``jump``. Specify the
+jump target.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> queue \<0-65535\>
+
+Use this command only when the action is set to ``queue``. Specify the
+queue target to use. Queue range is also supported.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> queue-options bypass
+
+Use this command only when the action is set to ``queue``. Allow the packet
+to pass through the firewall when no userspace software is connected to the
+queue.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> queue-options fanout
+
+Use this command only when the action is set to ``queue``. Distribute
+packets between several queues.
+```
+
+Also, **default-action** is an action that applies when a packet does not
+match any rule in its chain. For base chains, possible options for
+**default-action** are **accept** or **drop**.
+
+```{cfgcmd} set firewall ipv4 forward filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall ipv4 input filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall ipv4 output filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> default-action [accept | drop | jump | queue | reject | return]
+
+This command sets the default action of the rule-set if a packet does not
+match the criteria of any rule. If you set the default-action to ``jump``,
+you must also specify ``default-jump-target``. Note that for base chains,
+you can set the default action only to ``accept`` or ``drop``, while on
+custom chains, more actions are available.
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> default-jump-target \<text\>
+
+Use this command only when you set ``default-action`` to ``jump``. Specify
+the jump target for the default rule.
+```
+:::{note}
+**Important note about default-actions:**
+If you do not define a default action for a base chain, the system sets
+the default action to **accept** for that chain. For custom chains, if you
+do not define a default action, the system sets the default-action to
+**drop**.
+:::
+
+### Firewall Logs
+
+You can enable logging for every single firewall rule. If you enable logging,
+you can define other log options.
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> log
+
+Enable logging for the matched packet. If this command is not present, then
+logging is not enabled.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter default-log
+```
+
+```{cfgcmd} set firewall ipv4 input filter default-log
+```
+
+```{cfgcmd} set firewall ipv4 output filter default-log
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> default-log
+
+Use this command to enable logging of the default action on the specified
+chain.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+
+Define the log level. Only applicable if you enable rule logging.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> log-options group \<0-65535\>
+
+Define the log group to send messages to. Only applicable if you enable rule
+logging.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> log-options snapshot-length \<0-9000\>
+
+Define the length of packet payload to include in a netlink message. Only
+applicable if you enable rule logging and define the log group.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> log-options queue-threshold \<0-65535\>
+
+Define the number of packets to queue inside the kernel before sending them
+to userspace. Only applicable if you enable rule logging and define the log
+group.
+```
+
+### Firewall Description
+
+You can add a description for reference for every single rule and for every
+defined custom chain.
+
+```{cfgcmd} set firewall ipv4 name \<name\> description \<text\>
+
+Provide a rule-set description for a custom firewall chain.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> description \<text\>
+
+Provide a description for each rule.
+```
+
+### Rule Status
+
+When you define a rule, it is enabled by default. In some cases, it is useful
+to disable the rule rather than removing it.
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> disable
+
+Command for disabling a rule but keeping it in the configuration.
+```
+
+### Matching criteria
+
+There are a lot of matching criteria against which the packet can be tested.
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> connection-status nat [destination | source]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> connection-status nat [destination | source]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> connection-status nat [destination | source]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> connection-status nat [destination | source]
+
+Match based on nat connection status.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> connection-mark \<1-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> connection-mark \<1-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> connection-mark \<1-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> connection-mark \<1-2147483647\>
+
+Match based on connection mark.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> conntrack-helper \<module\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> conntrack-helper \<module\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> conntrack-helper \<module\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> conntrack-helper \<module\>
+
+Match based on connection tracking protocol helper module to secure use of
+that helper module. See below for possible completions \<module\>.
+
+:::{code-block} none
+Possible completions:
+ftp                  Related traffic from FTP helper
+h323                 Related traffic from H.323 helper
+pptp                 Related traffic from PPTP helper
+nfs                  Related traffic from NFS helper
+sip                  Related traffic from SIP helper
+tftp                 Related traffic from TFTP helper
+sqlnet               Related traffic from SQLNet helper
+:::
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination address [address | addressrange | CIDR]
+
+Match criteria based on source and/or destination address. This is similar
+to the network groups part, but here you are able to negate the matching
+addresses.
+
+:::{code-block} none
+set firewall ipv4 name FOO rule 50 source address 192.0.2.10-192.0.2.11
+# with a '!' the rule match everything except the specified subnet
+set firewall ipv4 input filter FOO rule 51 source address !203.0.113.0/24
+:::
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination address-mask [address]
+
+An arbitrary netmask can be applied to mask addresses to only match against
+a specific portion.
+
+This functions for both individual addresses and address groups.
+
+:::{code-block} none
+# Match any IPv4 address with `11` as the 2nd octet and `13` as the forth octet
+set firewall ipv4 name FOO rule 100 destination address 0.11.0.13
+set firewall ipv4 name FOO rule 100 destination address-mask 0.255.0.255
+:::
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination fqdn \<fqdn\>
+
+Specify a Fully Qualified Domain Name as source/destination to match. Ensure
+that the router is able to resolve this dns query.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination geoip inverse-match
+
+Match IP addresses based on its geolocation. More info: geoip matching.
+Use inverse-match to match anything except the given country-codes.
+```
+
+Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required,
+permits redistribution so we can include a database in images(~3MB
+compressed). Includes cron script (manually callable by op-mode update
+geoip) to keep database and rules updated.
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source mac-address \<mac-address\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source mac-address \<mac-address\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source mac-address \<mac-address\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source mac-address \<mac-address\>
+
+You can only specify a source mac-address to match.
+
+:::{code-block} none
+set firewall ipv4 input filter rule 100 source mac-address 00:53:00:11:22:33
+set firewall ipv4 input filter rule 101 source mac-address !00:53:00:aa:12:34
+:::
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination port [1-65535 | portname | start-end]
+
+A port can be set by number or name as defined in ``/etc/services``.
+
+:::{code-block} none
+set firewall ipv4 forward filter rule 10 source port '22'
+set firewall ipv4 forward filter rule 11 source port '!http'
+set firewall ipv4 forward filter rule 12 source port 'https'
+:::
+Multiple source ports can be specified as a comma-separated list.
+The whole list can also be "negated" using ``!``. For example:
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group address-group \<name | !name\>
+
+Use a specific address-group. Prepending the character ``!`` to invert the
+criteria to match is also supported.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group dynamic-address-group \<name | !name\>
+
+Use a specific dynamic-address-group. Prepending the character ``!`` to
+invert the criteria to match is also supported.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group network-group \<name | !name\>
+
+Use a specific network-group. Prepending the character ``!`` to invert the
+criteria to match is also supported.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group port-group \<name | !name\>
+
+Use a specific port-group. Prepending the character ``!`` to invert the
+criteria to match is also supported.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group domain-group \<name | !name\>
+
+Use a specific domain-group. Prepending the character ``!`` to invert the
+criteria to match is also supported.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group mac-group \<name | !name\>
+
+Use a specific mac-group. Prepending the character ``!`` to invert the
+criteria to match is also supported.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> dscp-exclude [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> dscp-exclude [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> dscp-exclude [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> dscp-exclude [0-63 | start-end]
+
+Match based on dscp value.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> fragment [match-frag | match-non-frag]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> fragment [match-frag | match-non-frag]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> fragment [match-frag | match-non-frag]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> fragment [match-frag | match-non-frag]
+
+Match based on fragmentation.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> icmp [code | type] \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> icmp [code | type] \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> icmp [code | type] \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> icmp [code | type] \<0-255\>
+
+Match based on icmp code and type.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> icmp type-name \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> icmp type-name \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> icmp type-name \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> icmp type-name \<text\>
+
+Match based on icmp type-name. Use tab for information
+about what **type-name** criteria are supported.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> inbound-interface name \<iface\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> inbound-interface name \<iface\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> inbound-interface name \<iface\>
+
+Match based on inbound interface. Wildcard ``*`` is supported. For example:
+``eth2*``. Prepend the character ``!`` to invert the criteria. For example:
+``!eth2``
+```
+:::{note}
+If an interface is attached to a non-default vrf, when using
+**inbound-interface**, the vrf name must be used. For example `set firewall
+ipv4 forward filter rule 10 inbound-interface name MGMT`
+:::
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> inbound-interface group \<iface_group\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> inbound-interface group \<iface_group\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> inbound-interface group \<iface_group\>
+
+Match based on the inbound interface group. Prepend the character ``!`` to
+invert the criteria. For example, ``!IFACE_GROUP``
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> outbound-interface name \<iface\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> outbound-interface name \<iface\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> outbound-interface name \<iface\>
+
+Match based on outbound interface. Wildcard ``*`` is supported. For example:
+``eth2*``. Prepend the character ``!`` to invert the criteria. For example:
+``!eth2``
+```
+:::{note}
+If an interface is attached to a non-default vrf, when using
+**outbound-interface**, the real interface name must be used. For example
+`set firewall ipv4 forward filter rule 10 outbound-interface name eth0`
+:::
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> outbound-interface group \<iface_group\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> outbound-interface group \<iface_group\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> outbound-interface group \<iface_group\>
+
+Match based on outbound interface group. Prepend the character ``!`` to
+invert the criteria. For example: ``!IFACE_GROUP``
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> ipsec [match-ipsec-in | match-none-in]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> ipsec [match-ipsec-out | match-none-out]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out]
+
+Match based on ipsec.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> limit burst \<0-4294967295\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> limit burst \<0-4294967295\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> limit burst \<0-4294967295\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> limit burst \<0-4294967295\>
+
+Match based on the maximum number of packets to allow in excess of rate.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> limit rate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> limit rate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> limit rate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> limit rate \<text\>
+
+Specify the maximum average rate as **integer/unit**. For example:
+**5/minutes**
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-length \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-length \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-length \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> packet-length \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-length-exclude \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-length-exclude \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-length-exclude \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> packet-length-exclude \<text\>
+
+Match based on packet length. Specify multiple values from 1 to 65535 and
+ranges.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+
+Match based on the packet type.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp]
+
+Match based on protocol number or name as defined in ``/etc/protocols``.
+Special names are ``all`` for all protocols and ``tcp_udp`` for TCP and UDP
+based packets. The ``!`` character negates the selected protocol.
+
+:::{code-block} none
+set firewall ipv4 forward filter rule 10 protocol tcp_udp
+set firewall ipv4 forward filter rule 11 protocol !tcp_udp
+:::
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> recent time [second | minute | hour]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent time [second | minute | hour]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent time [second | minute | hour]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> recent time [second | minute | hour]
+
+Match based on recently seen sources.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> tcp flags [not] \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> tcp flags [not] \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> tcp flags [not] \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> tcp flags [not] \<text\>
+
+Specify TCP flags. Allowed values are ``ack``, ``cwr``, ``ecn``, ``fin``,
+``psh``, ``rst``, ``syn``, and ``urg``. Specify multiple values, and use
+``not`` for inverted selection, as shown in the example.
+
+:::{code-block} none
+set firewall ipv4 input filter rule 10 tcp flags 'ack'
+set firewall ipv4 input filter rule 12 tcp flags 'syn'
+set firewall ipv4 input filter rule 13 tcp flags not 'fin'
+:::
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> state [established | invalid | new | related]
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> state [established | invalid | new | related]
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> state [established | invalid | new | related]
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> state [established | invalid | new | related]
+
+Match against the state of a packet.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time startdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time startdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time startdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> time startdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time starttime \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time starttime \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time starttime \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> time starttime \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time stopdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time stopdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time stopdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> time stopdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time stoptime \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time stoptime \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time stoptime \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> time stoptime \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time weekdays \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time weekdays \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time weekdays \<text\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> time weekdays \<text\>
+
+Time to match the defined rule.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> ttl \<eq | gt | lt\> \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> ttl \<eq | gt | lt\> \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> ttl \<eq | gt | lt\> \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> ttl \<eq | gt | lt\> \<0-255\>
+
+Match the time to live parameter, where 'eq' means 'equal', 'gt' means
+'greater than', and 'lt' means 'less than'.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> recent time \<second | minute | hour\>
+```
+
+```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent time \<second | minute | hour\>
+```
+
+```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent time \<second | minute | hour\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> recent time \<second | minute | hour\>
+
+Match when 'count' amount of connections appear within 'time'. Use these
+matching criteria to block brute-force attempts.
+```
+
+### Packet Modifications
+
+Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify
+packets before sending them out. This feature provides more flexibility in
+packet handling.
+
+```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set dscp \<0-63\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set dscp \<0-63\>
+```
+
+```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set dscp \<0-63\>
+
+Set a specific value of Differentiated Services Codepoint (DSCP).
+```
+
+```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set mark \<1-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set mark \<1-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set mark \<1-2147483647\>
+
+Set a specific packet mark value.
+```
+
+```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set tcp-mss \<500-1460\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set tcp-mss \<500-1460\>
+```
+
+```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set tcp-mss \<500-1460\>
+
+Set the TCP-MSS (TCP maximum segment size) for the connection.
+```
+
+```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set ttl \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set ttl \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set ttl \<0-255\>
+
+Set the TTL (Time to Live) value.
+```
+
+```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set connection-mark \<0-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set connection-mark \<0-2147483647\>
+
+Set connection mark value.
+```
+
+## Synproxy
+
+Synproxy connections
+
+```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> action synproxy
+```
+
+```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> protocol tcp
+```
+
+```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> synproxy tcp mss \<501-65535\>
+
+ Set the TCP-MSS (maximum segment size) for the connection
+```
+
+```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> synproxy tcp window-scale \<1-14\>
+
+ Set the window scale factor for TCP window scaling
+```
+
+### Example synproxy
+
+Requirements to enable synproxy:
+
+- Traffic must be symmetric.
+- Synproxy relies on syncookies and TCP timestamps, ensure these are enabled.
+- Disable conntrack loose track option.
+
+```none
+set system sysctl parameter net.ipv4.tcp_timestamps value '1'
+
+set system conntrack tcp loose disable
+
+set system conntrack ignore ipv4 rule 10 destination port '8080'
+
+set system conntrack ignore ipv4 rule 10 protocol 'tcp'
+
+set system conntrack ignore ipv4 rule 10 tcp flags syn
+
+set firewall global-options syn-cookies 'enable'
+
+set firewall ipv4 input filter rule 10 action 'synproxy'
+
+set firewall ipv4 input filter rule 10 destination port '8080'
+
+set firewall ipv4 input filter rule 10 inbound-interface name 'eth1'
+
+set firewall ipv4 input filter rule 10 protocol 'tcp'
+
+set firewall ipv4 input filter rule 10 synproxy tcp mss '1460'
+
+set firewall ipv4 input filter rule 10 synproxy tcp window-scale '7'
+
+set firewall ipv4 input filter rule 1000 action 'drop'
+
+set firewall ipv4 input filter rule 1000 state invalid
+
+```
+
+## Operation-mode Firewall
+
+### Rule-set overview
+
+```{opcmd} show firewall
+
+This will show you a basic firewall overview, for all rule-sets, not
+only for IPv4.
+
+:::{code-block} none
+vyos@vyos:~$ show firewall
+Rulesets Information
+
+---------------------------------
+ipv4 Firewall "forward filter"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  -----------------------------
+20       accept    all                 0        0  ip saddr @N_TRUSTEDv4  accept
+21       jump      all                 0        0  jump NAME_AUX
+default  accept    all                 0        0
+
+---------------------------------
+ipv4 Firewall "input filter"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  -------------------------
+10       accept    all               156    14377  iifname != @I_LAN  accept
+default  accept    all                 0        0
+
+---------------------------------
+ipv4 Firewall "name AUX"
+
+Rule  Action    Protocol      Packets    Bytes  Conditions
+------  --------  ----------  ---------  -------  --------------------------------------------
+10  accept    icmp                0        0  meta l4proto icmp  accept
+20  accept    udp                 0        0  meta l4proto udp ip saddr @A_SERVERS  accept
+30  drop      all                 0        0  ip saddr != @A_SERVERS iifname "eth2"
+
+---------------------------------
+ipv4 Firewall "output filter"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  ----------------------------------------
+10       reject    all                 0        0  oifname @I_LAN
+20       accept    icmp                2      168  meta l4proto icmp oifname "eth0"  accept
+default  accept    all                72     9258
+
+---------------------------------
+ipv6 Firewall "input filter"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  -------------------------------
+10       accept    all                 0        0  ip6 saddr @N6_TRUSTEDv6  accept
+default  accept    all                 2      112
+
+vyos@vyos:~$
+:::
+```
+
+```{opcmd} show firewall summary
+
+This shows you a summary of rule-sets and groups.
+
+:::{code-block} none
+vyos@vyos:~$ show firewall summary
+Ruleset Summary
+
+IPv6 Ruleset:
+
+Ruleset Hook    Ruleset Priority      Description
+--------------  --------------------  -------------------------
+forward         filter
+input           filter
+ipv6_name       IPV6-VyOS_MANAGEMENT
+ipv6_name       IPV6-WAN_IN           PUBLIC_INTERNET
+
+IPv4 Ruleset:
+
+Ruleset Hook    Ruleset Priority    Description
+--------------  ------------------  -------------------------
+forward         filter
+input           filter
+name            VyOS_MANAGEMENT
+name            WAN_IN              PUBLIC_INTERNET
+
+Firewall Groups
+
+Name                     Type                References               Members
+-----------------------  ------------------  -----------------------  ----------------
+PBX                      address_group       WAN_IN-100               198.51.100.77
+SERVERS                  address_group       WAN_IN-110               192.0.2.10
+WAN_IN-111               192.0.2.11
+WAN_IN-112               192.0.2.12
+WAN_IN-120
+WAN_IN-121
+WAN_IN-122
+SUPPORT                  address_group       VyOS_MANAGEMENT-20       192.168.1.2
+WAN_IN-20
+PHONE_VPN_SERVERS        address_group       WAN_IN-160               10.6.32.2
+PINGABLE_ADRESSES        address_group       WAN_IN-170               192.168.5.2
+WAN_IN-171
+PBX                      ipv6_address_group  IPV6-WAN_IN-100          2001:db8::1
+SERVERS                  ipv6_address_group  IPV6-WAN_IN-110          2001:db8::2
+IPV6-WAN_IN-111          2001:db8::3
+IPV6-WAN_IN-112          2001:db8::4
+IPV6-WAN_IN-120
+IPV6-WAN_IN-121
+IPV6-WAN_IN-122
+SUPPORT                  ipv6_address_group  IPV6-VyOS_MANAGEMENT-20  2001:db8::5
+IPV6-WAN_IN-20
+:::
+```
+
+```{opcmd} show firewall ipv4 [forward | input | output] filter
+```
+
+```{opcmd} show firewall ipv4 name \<name\>
+
+This command will give an overview of a single rule-set.
+
+:::{code-block} none
+vyos@vyos:~$ show firewall ipv4 input filter
+Ruleset Information
+---------------------------------
+IPv4 Firewall "input filter"
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  -----------------------------------------
+5        jump      all                 0        0  iifname "eth2"  jump NAME_VyOS_MANAGEMENT
+default  accept    all
+:::
+```
+
+```{opcmd} show firewall ipv4 [forward | input | output] filter rule \<1-999999\>
+```
+
+```{opcmd} show firewall ipv4 name \<name\> rule \<1-999999\>
+
+This command gives an overview of a rule in a single rule-set, plus
+information for default action.
+```
+```none
+vyos@vyos:~$show firewall ipv4 output filter rule 20
+Rule Information
+
+---------------------------------
+ipv4 Firewall "output filter"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  ----------------------------------------
+20       accept    icmp                2      168  meta l4proto icmp oifname "eth0"  accept
+default  accept    all               286    47614
+
+vyos@vyos:~$
+```
+
+```{opcmd} show firewall statistics
+
+This will show you statistics of all rule-sets since the last boot.
+```
+
+### Show Firewall log
+
+```{opcmd} show log firewall
+
+```
+```{opcmd} show log firewall ipv4
+```
+
+```{opcmd} show log firewall ipv4 [forward | input | output | name]
+```
+
+```{opcmd} show log firewall ipv4 [forward | input | output] filter
+```
+
+```{opcmd} show log firewall ipv4 name \<name\>
+```
+
+```{opcmd} show log firewall ipv4 [forward | input | output] filter rule \<rule\>
+```
+
+```{opcmd} show log firewall ipv4 name \<name\> rule \<rule\>
+
+Show the logs of all firewall; show all IPv4 firewall logs; show all logs
+for particular hook; show all logs for particular hook and priority;
+show all logs for particular custom chain; show logs for specific rule-set.
+```
+
+### Example Partial Config
+
+```none
+firewall {
+    group {
+        network-group BAD-NETWORKS {
+            network 198.51.100.0/24
+            network 203.0.113.0/24
+        }
+        network-group GOOD-NETWORKS {
+            network 192.0.2.0/24
+        }
+        port-group BAD-PORTS {
+            port 65535
+        }
+    }
+    ipv4 {
+        forward {
+            filter {
+                default-action accept
+                rule 5 {
+                    action accept
+                    source {
+                        group {
+                            network-group GOOD-NETWORKS
+                        }
+                    }
+                }
+                rule 10 {
+                    action drop
+                    description "Bad Networks"
+                    protocol all
+                    source {
+                        group {
+                            network-group BAD-NETWORKS
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+### Update geoip database
+
+```{opcmd} update geoip
+
+Command to update GeoIP database and firewall sets.
+```
\ No newline at end of file
diff --git a/docs/configuration/firewall/ipv6.md b/docs/configuration/firewall/ipv6.md
new file mode 100644
index 00000000..0ba30110
--- /dev/null
+++ b/docs/configuration/firewall/ipv6.md
@@ -0,0 +1,1567 @@
+---
+lastproofread: '2026-04-01'
+---
+
+(firewall-ipv6-configuration)=
+
+# IPv6 Firewall Configuration
+
+## Overview
+
+This section covers useful information about IPv6 firewall configuration and
+appropriate operation-mode commands.
+
+This section describes the following configuration commands:
+
+```{cfgcmd} set firewall ipv6 ...
+```
+
+To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall </configuration/firewall/index>`.
+
+```none
+- set firewall
+    * ipv6
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+            + raw
+         - prerouting
+            + raw
+         - name
+            + custom_name
+```
+
+The router first receives all traffic and processes it in the **prerouting**
+section.
+
+
+This stage includes:
+
+
+- **Firewall Prerouting**: commands found under `set firewall ipv6
+  prerouting raw ...`
+- {doc}`Conntrack Ignore</configuration/system/conntrack>`: `set system
+  conntrack ignore ipv6...`
+- {doc}`Policy Route</configuration/policy/route>`: commands found under
+  `set policy route6 ...`
+- {doc}`Destination NAT</configuration/nat/nat44>`: commands found under
+  `set nat66 destination ...`
+
+
+For transit traffic that the router receives and forwards, the base chain is
+**forward**. The following diagram shows a simplified packet flow for transit
+traffic:
+
+
+:::{figure} /_static/images/firewall-fwd-packet-flow.webp
+:::
+
+
+Use `set firewall ipv6 forward filter ...` to configure filtering rules for
+transit traffic. This command corresponds to stage 5 and is highlighted in red
+in the diagram.
+
+
+For traffic destined to the router, use the **input** chain. For traffic the
+router generates, use the **output** chain. The following diagram shows the
+packet flow for traffic destined to the router and traffic generated by the
+router (starting from circle number 6):
+
+
+:::{figure} /_static/images/firewall-input-packet-flow.webp
+:::
+
+
+Use `set firewall ipv6 input filter ...` to configure traffic destined to
+the router.
+
+
+Use `set firewall ipv6 output ...` to configure traffic the router generates.
+Two sub-chains are available: **filter** and **raw**:
+
+
+- **Output Prerouting**: `set firewall ipv6 output raw ...`.
+  As described in **Prerouting**, the firewall processes rules in this
+  section before the connection tracking subsystem.
+- **Output Filter**: `set firewall ipv6 output filter ...`. The firewall
+  processes rules in this section after the connection tracking subsystem.
+
+
+:::{note}
+**Important note about default-actions:**
+If you do not define a default action for a base chain, the system sets
+the default action to **accept** for that chain. For custom chains, if you
+do not define a default action, the system sets the default-action to
+**drop**
+:::
+
+
+Create custom firewall chains using the commands
+`set firewall ipv6 name <name> ...`. To use the custom chain, define a
+rule with **action jump** and the appropriate **target** in a base chain.
+
+
+## Firewall - IPv6 Rules
+
+
+Create firewall rules for firewall filtering. Each rule is numbered and has
+an action to apply when the rule is matched. You can specify multiple matching
+criteria. Packets go through rules from 1 - 999999, so order is crucial. The
+firewall executes the action of the first matching rule.
+
+
+### Actions
+
+
+If you define a rule, you must define an action for it. The action tells the
+firewall what to do when all criteria for that rule are met.
+
+
+The action can be :
+
+
+- `accept`: accept the packet.
+- `continue`: continue parsing next rule.
+- `drop`: drop the packet.
+- `reject`: reject the packet.
+- `jump`: jump to another custom chain.
+- `return`: Return from the current chain and continue at the next rule
+  of the last chain.
+- `queue`: Enqueue packet to userspace.
+- `synproxy`: synproxy the packet.
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return]
+
+This required setting defines the action of the current rule. If you set
+the action to jump, you must also define a jump-target.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> jump-target \<text\>
+
+Use this command only when action is set to ``jump``. Specify the jump
+target.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> queue \<0-65535\>
+
+Use this command only when action is set to ``queue``. Specify the queue
+target. Queue ranges are also supported.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> queue-options bypass
+
+Use this command only when action is set to ``queue``. This command allows
+the packet to go through the firewall when no userspace software is connected
+to the queue.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> queue-options fanout
+
+Use this command only when action is set to ``queue``. This command
+distributes packets among multiple queues.
+```
+
+Also, **default-action** is an action that takes place whenever a packet does
+not match any rule in its chain. For base chains, possible options for
+**default-action** are **accept** or **drop**.
+
+```{cfgcmd} set firewall ipv6 forward filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall ipv6 input filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall ipv6 output filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> default-action [accept | drop | jump | queue | reject | return]
+
+Set the default action of the rule-set if a packet does not match any rule
+criteria. If you set default-action to ``jump``, you must also define
+``default-jump-target``. For base chains, you can only set the default
+action to ``accept`` or ``drop``. For custom chains, more actions are
+available.
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> default-jump-target \<text\>
+
+To be used only when ``default-action`` is set to ``jump``. Use this
+command to specify the jump target for the default rule.
+```
+:::{note}
+**Important note about default-actions:**
+If you do not define the default action for a base chain, the system sets
+the default action to **accept** for that chain. For custom chains, if you
+do not define a default action, the system sets the default-action to
+**drop**.
+:::
+
+
+### Firewall Logs
+
+
+You can enable logging for each firewall rule. When enabled, you can also
+define other log options.
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log
+
+Enable logging for matched packets. If this configuration command is not
+present, logging is disabled.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter default-log
+```
+
+```{cfgcmd} set firewall ipv6 input filter default-log
+```
+
+```{cfgcmd} set firewall ipv6 output filter default-log
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> default-log
+
+Use this command to enable the logging of the default action on
+the specified chain.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+
+Define log-level. Only applicable if rule log is enabled.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options group \<0-65535\>
+
+Define the log group to send messages to. Only applicable if rule log is
+enabled.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options snapshot-length \<0-9000\>
+
+Define the length of packet payload to include in a netlink message. Only
+applicable when rule logging is enabled and log group is defined.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options queue-threshold \<0-65535\>
+
+Define the number of packets to queue inside the kernel before sending them
+to userspace. Only applicable when rule logging is enabled and log group is
+defined.
+```
+
+### Firewall Description
+
+
+For reference, you can define descriptions on every rule and custom chain.
+
+```{cfgcmd} set firewall ipv6 name \<name\> description \<text\>
+
+Provide a rule-set description to a custom firewall chain.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> description \<text\>
+
+Provide a description for each rule.
+```
+
+### Rule Status
+
+
+New rules are enabled by default. In some cases, you may want to disable a
+rule rather than remove it.
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> disable
+
+Command for disabling a rule but keep it in the configuration.
+```
+
+### Matching criteria
+
+
+There are a lot of matching criteria against which the packet can be tested.
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-status nat [destination | source]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-status nat [destination | source]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-status nat [destination | source]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> connection-status nat [destination | source]
+
+Match packets based on NAT connection status.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-mark \<1-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-mark \<1-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-mark \<1-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> connection-mark \<1-2147483647\>
+
+Match packets based on connection mark.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination address [address | addressrange | CIDR]
+
+Match based on source or destination address. This is similar to network
+groups, but you can negate the matching addresses here.
+
+:::{code-block} none
+set firewall ipv6 name FOO rule 100 source address 2001:db8::202
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination address-mask [address]
+
+Apply an arbitrary netmask to mask addresses and match only a specific
+portion. This is useful for IPv6 because rules remain valid when the IPv6
+prefix changes if the host portion of the system's IPv6 address is static.
+Examples include SLAAC and tokenised IPv6 addresses
+
+This function works for both individual addresses and address groups.
+
+
+:::{code-block} none
+# Match any IPv6 address with the suffix ::0000:0000:0000:beef
+set firewall ipv6 forward filter rule 100 destination address ::beef
+set firewall ipv6 forward filter rule 100 destination address-mask ::ffff:ffff:ffff:ffff
+# Address groups
+set firewall group ipv6-address-group WEBSERVERS address ::1000
+set firewall group ipv6-address-group WEBSERVERS address ::2000
+set firewall ipv6 forward filter rule 200 source group address-group WEBSERVERS
+set firewall ipv6 forward filter rule 200 source address-mask ::ffff:ffff:ffff:ffff
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination fqdn \<fqdn\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination fqdn \<fqdn\>
+
+Specify a Fully Qualified Domain Name as source or destination to match.
+Ensure that the router can resolve the DNS query.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination geoip country-code \<country\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination geoip inverse-match
+
+Match IP addresses based on their geolocation. For more information, see
+GeoIP matching.
+Use inverse-match to match anything except the specified country codes.
+```
+
+DB-IP.com provides data under CC-BY-4.0 license. Attribution is required and
+redistribution is permitted, allowing VyOS to include a database in images
+(approximately 3 MB compressed). The package includes a cron script that you
+can manually call through op-mode update geoip to keep the database and rules
+updated.
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source mac-address \<mac-address\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source mac-address \<mac-address\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source mac-address \<mac-address\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source mac-address \<mac-address\>
+
+You can specify only a source MAC address to match.
+
+:::{code-block} none
+set firewall ipv6 input filter rule 100 source mac-address 00:53:00:11:22:33
+set firewall ipv6 input filter rule 101 source mac-address !00:53:00:aa:12:34
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination port [1-65535 | portname | start-end]
+
+Specify a port by number or by name as defined in ``/etc/services``.
+
+:::{code-block} none
+set firewall ipv6 forward filter rule 10 source port '22'
+set firewall ipv6 forward filter rule 11 source port '!http'
+set firewall ipv6 forward filter rule 12 source port 'https'
+:::
+Multiple source ports can be specified as a comma-separated list.
+The whole list can also be "negated" using ``!``. For example:
+
+:::{code-block} none
+set firewall ipv6 forward filter rule 10 source port '!22,https,3333-3338'
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group address-group \<name | !name\>
+
+Specify an address group. You can prepend the character ``!`` to invert the
+matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group dynamic-address-group \<name | !name\>
+
+Specify a dynamic address group. You can prepend the character ``!`` to
+invert the matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group network-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group network-group \<name | !name\>
+
+Specify a network group. You can prepend the character ``!`` to invert the
+matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group port-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group port-group \<name | !name\>
+
+Specify a port group. You can prepend the character ``!`` to invert the
+matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group domain-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group domain-group \<name | !name\>
+
+Specify a domain group. You can prepend the character ``!`` to invert the
+matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group mac-group \<name | !name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group mac-group \<name | !name\>
+
+Specify a MAC group. You can prepend the character ``!`` to invert the
+matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp-exclude [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp-exclude [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp-exclude [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> dscp-exclude [0-63 | start-end]
+
+Match based on dscp value.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> fragment [match-frag | match-non-frag]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> fragment [match-frag | match-non-frag]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> fragment [match-frag | match-non-frag]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> fragment [match-frag | match-non-frag]
+
+Match packets based on fragmentation.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 [code | type] \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 [code | type] \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 [code | type] \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> icmpv6 [code | type] \<0-255\>
+
+Match packets based on ICMP or ICMPv6 code and type.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 type-name \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 type-name \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 type-name \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> icmpv6 type-name \<text\>
+
+Match based on ICMPv6 type-name. Press **Tab** for information about
+supported **type-name** criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface name \<iface\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface name \<iface\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> inbound-interface name \<iface\>
+
+Match based on inbound interface. You can use the wildcard ``*``. For
+example: ``eth2*``. You can prepend the character ``!`` to invert the
+matching criteria. For example ``!eth2``
+```
+:::{note}
+If an interface is attached to a non-default VRF, when using
+**inbound-interface**, use the VRF name. For example:
+`set firewall ipv6 forward filter rule 10 inbound-interface name MGMT`
+:::
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface group \<iface_group\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface group \<iface_group\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> inbound-interface group \<iface_group\>
+
+Match based on the inbound interface group. You can prepend the character
+``!`` to invert the matching criteria. For example ``!IFACE_GROUP``
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface name \<iface\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface name \<iface\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> outbound-interface name \<iface\>
+
+Match based on outbound interface. You can use the wildcard ``*``. For
+example: ``eth2*``. You can prepend the character ``!`` to invert the
+matching criteria. For example ``!eth2``
+```
+:::{note}
+If an interface is attached to a non-default VRF, when using
+**outbound-interface**, use the physical interface name. For example:
+`set firewall ipv6 forward filter rule 10 outbound-interface name eth0`
+:::
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface group \<iface_group\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface group \<iface_group\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> outbound-interface group \<iface_group\>
+
+Match based on outbound interface group. You can prepend the character ``!``
+to invert the matching criteria. For example ``!IFACE_GROUP``
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> ipsec [match-ipsec-in | match-none-in]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> ipsec [match-ipsec-out | match-none-out]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out]
+
+Match packets based on IPsec.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit burst \<0-4294967295\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit burst \<0-4294967295\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit burst \<0-4294967295\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> limit burst \<0-4294967295\>
+
+Match based on the maximum number of packets allowed to exceed the rate
+limit.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit rate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit rate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit rate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> limit rate \<text\>
+
+Match based on the maximum average rate, specified as ``integer/unit``.
+For example, specify ``5/minutes``.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> packet-length \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length-exclude \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length-exclude \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length-exclude \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> packet-length-exclude \<text\>
+
+Match based on packet length. You can specify multiple values from 1 to
+65535 and ranges.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+
+Match based on packet type.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp]
+
+Match based on protocol number or name as defined in ``/etc/protocols``.
+Specify ``all`` for all protocols and ``tcp_udp`` for TCP and UDP packets.
+Prepend ``!`` to negate the protocol selection.
+
+:::{code-block} none
+set firewall ipv6 input filter rule 10 protocol tcp
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time [second | minute | hour]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time [second | minute | hour]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time [second | minute | hour]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent time [second | minute | hour]
+
+Match packets based on recently seen sources.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> tcp flags [not] \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> tcp flags [not] \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> tcp flags [not] \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> tcp flags [not] \<text\>
+
+Allowed values for TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``,
+``rst``, ``syn``, and ``urg``. You can specify multiple values. To invert
+the selection, use ``not``, as shown in the following example.
+
+:::{code-block} none
+set firewall ipv6 input filter rule 10 tcp flags 'ack'
+set firewall ipv6 input filter rule 12 tcp flags 'syn'
+set firewall ipv6 input filter rule 13 tcp flags not 'fin'
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> state [established | invalid | new | related]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> state [established | invalid | new | related]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> state [established | invalid | new | related]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> state [established | invalid | new | related]
+
+Match based on packet state.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time startdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time startdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time startdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time startdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time starttime \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time starttime \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time starttime \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time starttime \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stopdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stopdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stopdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time stopdate \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stoptime \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stoptime \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stoptime \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time stoptime \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time weekdays \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time weekdays \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time weekdays \<text\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time weekdays \<text\>
+
+Match packets based on time criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> hop-limit \<eq | gt | lt\> \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> hop-limit \<eq | gt | lt\> \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> hop-limit \<eq | gt | lt\> \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> hop-limit \<eq | gt | lt\> \<0-255\>
+
+Match the hop-limit parameter. Use ``eq`` for equal, ``gt`` for greater than,
+and ``lt`` for less than.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent count \<1-255\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time \<second | minute | hour\>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time \<second | minute | hour\>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time \<second | minute | hour\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent time \<second | minute | hour\>
+
+Match when the specified number of connections occur within the specified
+time period. Use these criteria to block brute-force attempts.
+```
+
+### Packet Modifications
+
+
+The firewall can modify packets before sending them.
+This feature provides more flexibility for packet handling.
+
+```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set dscp \<0-63\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set dscp \<0-63\>
+```
+
+```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set dscp \<0-63\>
+
+Set a specific value of Differentiated Services Codepoint (DSCP).
+```
+
+```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set mark \<1-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set mark \<1-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set mark \<1-2147483647\>
+
+Set a specific packet mark value.
+```
+
+```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set tcp-mss \<500-1460\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set tcp-mss \<500-1460\>
+```
+
+```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set tcp-mss \<500-1460\>
+
+Set the TCP-MSS (TCP maximum segment size) for the connection.
+```
+
+```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set hop-limit \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set hop-limit \<0-255\>
+```
+
+```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set hop-limit \<0-255\>
+
+Set hop limit value.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set connection-mark \<0-2147483647\>
+```
+
+```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set connection-mark \<0-2147483647\>
+
+Set connection mark value.
+```
+
+## Synproxy
+
+
+Synproxy connections
+
+```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> action synproxy
+```
+
+```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> protocol tcp
+```
+
+```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp mss \<501-65535\>
+
+ Set the TCP MSS (maximum segment size) for the connection.
+```
+
+```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp window-scale \<1-14\>
+
+ Set the window scale factor for TCP window scaling.
+```
+
+### Example synproxy
+
+
+Requirements to enable synproxy:
+
+
+- Traffic must be symmetric
+- Synproxy relies on syncookies and TCP timestamps, ensure these are enabled
+- Disable conntrack loose track option
+
+```none
+set system sysctl parameter net.ipv4.tcp_timestamps value '1'
+
+
+set system conntrack tcp loose disable
+
+set system conntrack ignore ipv6 rule 10 destination port '8080'
+
+set system conntrack ignore ipv6 rule 10 protocol 'tcp'
+
+set system conntrack ignore ipv6 rule 10 tcp flags syn
+
+
+set firewall global-options syn-cookies 'enable'
+
+set firewall ipv6 input filter rule 10 action 'synproxy'
+
+set firewall ipv6 input filter rule 10 destination port '8080'
+
+set firewall ipv6 input filter rule 10 inbound-interface name 'eth1'
+
+set firewall ipv6 input filter rule 10 protocol 'tcp'
+
+set firewall ipv6 input filter rule 10 synproxy tcp mss '1460'
+
+set firewall ipv6 input filter rule 10 synproxy tcp window-scale '7'
+
+set firewall ipv6 input filter rule 1000 action 'drop'
+
+set firewall ipv6 input filter rule 1000 state invalid
+
+```
+
+## Operation-mode Firewall
+
+
+### Rule-set overview
+
+```{opcmd} show firewall
+
+Show a basic firewall overview for all rule-sets, not only for IPv6:
+
+:::{code-block} none
+vyos@vyos:~$ show firewall
+Rulesets Information
+
+---------------------------------
+IPv4 Firewall "forward filter"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  -----------------------------------------
+5        jump      all                 0        0  iifname "eth1"  jump NAME_VyOS_MANAGEMENT
+10       jump      all                 0        0  oifname "eth1"  jump NAME_WAN_IN
+15       jump      all                 0        0  iifname "eth3"  jump NAME_WAN_IN
+default  accept    all
+
+---------------------------------
+IPv4 Firewall "name VyOS_MANAGEMENT"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  --------------------------------
+5        accept    all                 0        0  ct state established  accept
+10       drop      all                 0        0  ct state invalid
+20       accept    all                 0        0  ip saddr @A_GOOD_GUYS  accept
+30       accept    all                 0        0  ip saddr @N_ENTIRE_RANGE  accept
+40       accept    all                 0        0  ip saddr @A_VyOS_SERVERS  accept
+50       accept    icmp                0        0  meta l4proto icmp  accept
+default  drop      all                 0        0
+
+---------------------------------
+IPv6 Firewall "forward filter"
+
+Rule     Action    Protocol
+-------  --------  ----------
+5        jump      all
+10       jump      all
+15       jump      all
+default  accept    all
+
+---------------------------------
+IPv6 Firewall "input filter"
+
+Rule     Action    Protocol
+-------  --------  ----------
+5        jump      all
+default  accept    all
+
+---------------------------------
+IPv6 Firewall "ipv6_name IPV6-VyOS_MANAGEMENT"
+
+Rule     Action    Protocol
+-------  --------  ----------
+5        accept    all
+10       drop      all
+20       accept    all
+30       accept    all
+40       accept    all
+50       accept    ipv6-icmp
+default  drop      all
+:::
+```
+
+```{opcmd} show firewall summary
+
+This will show you a summary of rule-sets and groups
+
+:::{code-block} none
+vyos@vyos:~$ show firewall summary
+Ruleset Summary
+
+IPv6 Ruleset:
+
+Ruleset Hook    Ruleset Priority      Description
+--------------  --------------------  -------------------------
+forward         filter
+input           filter
+ipv6_name       IPV6-VyOS_MANAGEMENT
+ipv6_name       IPV6-WAN_IN           PUBLIC_INTERNET
+
+IPv4 Ruleset:
+
+Ruleset Hook    Ruleset Priority    Description
+--------------  ------------------  -------------------------
+forward         filter
+input           filter
+name            VyOS_MANAGEMENT
+name            WAN_IN              PUBLIC_INTERNET
+
+Firewall Groups
+
+Name                     Type                References               Members
+-----------------------  ------------------  -----------------------  ----------------
+PBX                      address_group       WAN_IN-100               198.51.100.77
+SERVERS                  address_group       WAN_IN-110               192.0.2.10
+WAN_IN-111               192.0.2.11
+WAN_IN-112               192.0.2.12
+WAN_IN-120
+WAN_IN-121
+WAN_IN-122
+SUPPORT                  address_group       VyOS_MANAGEMENT-20       192.168.1.2
+WAN_IN-20
+PHONE_VPN_SERVERS        address_group       WAN_IN-160               10.6.32.2
+PINGABLE_ADRESSES        address_group       WAN_IN-170               192.168.5.2
+WAN_IN-171
+PBX                      ipv6_address_group  IPV6-WAN_IN-100          2001:db8::1
+SERVERS                  ipv6_address_group  IPV6-WAN_IN-110          2001:db8::2
+IPV6-WAN_IN-111          2001:db8::3
+IPV6-WAN_IN-112          2001:db8::4
+IPV6-WAN_IN-120
+IPV6-WAN_IN-121
+IPV6-WAN_IN-122
+SUPPORT                  ipv6_address_group  IPV6-VyOS_MANAGEMENT-20  2001:db8::5
+IPV6-WAN_IN-20
+:::
+```
+
+```{opcmd} show firewall ipv6 [forward | input | output] filter
+```
+
+```{opcmd} show firewall ipv6 ipv6-name \<name\>
+
+This command will give an overview of a single rule-set.
+
+:::{code-block} none
+vyos@vyos:~$ show firewall ipv6 input filter
+Ruleset Information
+
+---------------------------------
+ipv6 Firewall "input filter"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  ------------------------------------------------------------------------------
+10       jump      all                13     1456  iifname "eth1"  jump NAME6_INP-ETH1
+20       accept    ipv6-icmp          10     1112  meta l4proto ipv6-icmp iifname "eth0"  prefix "[ipv6-INP-filter-20-A]"  accept
+default  accept    all                14     1584
+
+vyos@vyos:~$
+:::
+```
+
+```{opcmd} show firewall ipv6 [forward | input | output] filter rule \<1-999999\>
+```
+
+```{opcmd} show firewall ipv6 name \<name\> rule \<1-999999\>
+```
+
+```{opcmd} show firewall ipv6 ipv6-name \<name\> rule \<1-999999\>
+
+This command will give an overview of a rule in a single rule-set
+```
+
+```{opcmd} show firewall group \<name\>
+
+Show an overview of defined groups, including the type, members, and where
+the group is used.
+
+:::{code-block} none
+vyos@vyos:~$ show firewall group LAN
+Firewall Groups
+
+Name          Type                References               Members
+------------  ------------------  -----------------------  ----------------
+LAN           ipv6_network_group  IPV6-VyOS_MANAGEMENT-30  2001:db8::0/64
+IPV6-WAN_IN-30
+LAN           network_group       VyOS_MANAGEMENT-30       192.168.200.0/24
+WAN_IN-30
+:::
+```
+
+```{opcmd} show firewall statistics
+
+Show statistics of all rule-sets since the last boot.
+```
+
+### Show Firewall log
+
+```{opcmd} show log firewall
+```
+
+```{opcmd} show log firewall ipv6
+```
+
+```{opcmd} show log firewall ipv6 [forward | input | output | name]
+```
+
+```{opcmd} show log firewall ipv6 [forward | input | output] filter
+```
+
+```{opcmd} show log firewall ipv6 name \<name\>
+```
+
+```{opcmd} show log firewall ipv6 [forward | input | output] filter rule \<rule\>
+```
+
+```{opcmd} show log firewall ipv6 name \<name\> rule \<rule\>
+
+Show firewall logs for all firewalls, all IPv6 firewalls, specific hooks,
+specific priorities, specific custom chains, or specific rule-sets.
+```
+
+### Example Partial Config
+
+```none
+firewall {
+    ipv6 {
+        input {
+            filter {
+                rule 10 {
+                    action jump
+                    inbound-interface {
+                        name eth1
+                    }
+                    jump-target INP-ETH1
+                }
+                rule 20 {
+                    action accept
+                    inbound-interface {
+                        name eth0
+                    }
+                    log
+                    protocol ipv6-icmp
+                }
+            }
+        }
+        name INP-ETH1 {
+            default-action drop
+            default-log
+            rule 10 {
+                action accept
+                protocol tcp_udp
+            }
+        }
+    }
+}
+```
+
+### Update geoip database
+
+```{opcmd} update geoip
+
+Command used to update GeoIP database and firewall sets.
+```
\ No newline at end of file
diff --git a/docs/configuration/firewall/zone.md b/docs/configuration/firewall/zone.md
new file mode 100644
index 00000000..bbb93993
--- /dev/null
+++ b/docs/configuration/firewall/zone.md
@@ -0,0 +1,201 @@
+---
+lastproofread: '2026-03-30'
+---
+
+(firewall-zone)=
+
+# Zone-Based Firewall
+
+## Overview
+
+:::{note}
+All VyOS versions built after 2023-10-22 (VyOS 1.4 and 1.5) support
+this feature.
+:::
+
+This section provides information on firewall configuration for the
+zone-based firewall. This section covers the following configuration
+commands:
+
+```{cfgcmd} set firewall zone ...
+```
+
+To learn about the general traffic flow in VyOS firewalls,
+see {doc}`Firewall </configuration/firewall/index>`.
+
+```none
+- set firewall
+    * zone
+         - custom_zone_name
+            + ...
+```
+
+In zone-based policy, you assign interfaces to zones and apply inspection
+policy to traffic moving between zones. The firewall acts on traffic
+according to rules. A zone is a group of interfaces that have similar
+functions or features. It establishes the security borders of a network.
+A zone defines a boundary where the system subjects traffic to policy
+restrictions as it crosses to another region of a network.
+
+Key Points:
+- A zone must be configured before you assign an interface to it, and you
+  can assign an interface to only a single zone.
+- All traffic to and from an interface within a zone flows freely.
+- Existing policies affect all traffic between zones.
+- Traffic cannot flow between a zone member interface and any interface that
+  is not a zone member.
+- You must define 2 separate firewalls to define traffic: one for each
+  direction.
+
+:::{note}
+In {vytask}`T2199` the syntax of the zone configuration was changed.
+The zone configuration moved from ``zone-policy zone <name>`` to
+``firewall zone <name>``.
+:::
+
+## Configuration
+
+As an alternative to applying policy to an interface directly, you can
+create a zone-based firewall to simplify configuration when multiple
+interfaces belong to the same security zone. Instead of applying rule-sets
+to interfaces, you apply them to source-destination zone pairs.
+
+You can find a basic introduction to zone-based firewalls in the
+[VyOS Knowledge Base](https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall),
+and an example at {ref}`examples-zone-policy`.
+
+The following steps are required to create a zone-based firewall:
+1. Define both the source and destination zones
+2. Define the rule-set
+3. Apply the rule-set to the zones
+
+### Define a Zone
+
+To define a zone, set up either one with interfaces or as the local zone.
+
+```{cfgcmd} set firewall zone \<name\> interface \<interface\>
+
+Assign interfaces as a member of a zone.
+
+:::{note}
+* An interface can only be a member of one zone.
+* You can have multiple interfaces in a zone. Traffic between
+interfaces in the same zone follows the intra-zone-filtering
+policy (allowed by default).
+:::
+```
+
+```{cfgcmd} set firewall zone \<name\> local-zone
+
+Define the zone as the local zone for traffic that originates from or is
+destined to the router itself.
+
+:::{note}
+* A local zone cannot have any member interfaces
+* You cannot have multiple local zones
+:::
+```
+
+```{cfgcmd} set firewall zone \<name\> default-action [drop | reject]
+
+Modify the zone default-action, which applies to traffic destined to this
+zone that does not match any of the source zone rulesets applied.
+```
+
+```{cfgcmd} set firewall zone \<name\> default-log
+
+Enable logging of packets that match this zone's default-action (disabled
+by default).
+```
+
+```{cfgcmd} set firewall zone \<name\> description
+
+Add a meaningful description.
+```
+
+### Defining a Rule-Set
+
+Zone-based firewall rule-sets define traffic from a *Source Zone* to a
+*Destination Zone*.
+
+You create rule-sets as a custom firewall chain using the commands below
+(refer to the firewall IPv4/IPv6 sections for the full syntax):
+- For {ref}`IPv4<configuration/firewall/ipv4:Firewall - IPv4 Rules>`:
+  `set firewall ipv4 name <name> ...`
+- For {ref}`IPv6<configuration/firewall/ipv6:Firewall - IPv6 Rules>`:
+  `set firewall ipv6 name <name> ...`
+
+It is helpful to name the rule-sets in the format
+`<Source Zone>-<Destination Zone>-<v4 | v6>` to make them easily
+identifiable.
+
+### Applying a Rule-Set to a Zone
+
+After you define a rule-set, apply it to the source and destination zones.
+The configuration syntax anchors to the destination zone, with each of the
+source zone rule-sets listed against the destination.
+
+```{cfgcmd} set firewall zone \<Destination Zone\> from \<Source Zone\> firewall name \<ipv4-rule-set-name\>
+```
+
+```{cfgcmd} set firewall zone \<Destination Zone\> from \<Source Zone\> firewall ipv6-name \<ipv6-rule-set-name\>
+```
+
+You should create two rule-sets for each source-destination zone
+pair.
+
+```none
+set firewall zone DMZ from LAN firewall name LAN-DMZ-v4
+set firewall zone LAN from DMZ firewall name DMZ-LAN-v4
+```
+
+### Applying a Default Rule-Set to a Zone
+
+When a destination zone shares a common rule-set for multiple source zones,
+or when you require a complex set of default policies, you can apply an
+optional default rule-set. The default rule-set applies to all zones that do
+not have a rule-set configured as defined in
+{ref}`IPv4<configuration/firewall/zone:Applying a Rule-Set to a Zone>`
+
+```{cfgcmd} set firewall zone \<Destination Zone\> default-firewall name \<ipv4-rule-set-name\>
+```
+
+```{cfgcmd} set firewall zone \<Destination Zone\> default-firewall ipv6-name \<ipv6-rule-set-name\>
+```
+
+## Operation-mode
+
+```{opcmd} show firewall zone-policy
+
+Display a basic summary of the zone configuration.
+
+:::{code-block} none
+vyos@vyos:~$ show firewall zone-policy
+Zone    Interfaces    From Zone    Firewall IPv4    Firewall IPv6
+------  ------------  -----------  ---------------  ---------------
+LAN     eth1          WAN          WAN-LAN-v4
+eth2
+LOCAL   LOCAL         LAN          LAN-LOCAL-v4
+WAN          WAN-LOCAL-v4     WAN-LOCAL-v6
+WAN     eth3          LAN          LAN-WAN-v4
+eth0          LOCAL        LOCAL-WAN-v4
+:::
+```
+
+```{opcmd} show firewall zone-policy zone \<zone\>
+
+Display a basic summary of a particular zone.
+
+:::{code-block} none
+vyos@vyos:~$ show firewall zone-policy zone WAN
+Zone    Interfaces    From Zone    Firewall IPv4    Firewall IPv6
+------  ------------  -----------  ---------------  ---------------
+WAN     eth3          LAN          LAN-WAN-v4
+eth0          LOCAL        LOCAL-WAN-v4
+vyos@vyos:~$ show firewall zone-policy zone LOCAL
+Zone    Interfaces    From Zone    Firewall IPv4    Firewall IPv6
+------  ------------  -----------  ---------------  ---------------
+LOCAL   LOCAL         LAN          LAN-LOCAL-v4
+WAN          WAN-LOCAL-v4     WAN-LOCAL-v6
+:::
+```
\ No newline at end of file
diff --git a/docs/configuration/highavailability/index.md b/docs/configuration/highavailability/index.md
new file mode 100644
index 00000000..e26f5791
--- /dev/null
+++ b/docs/configuration/highavailability/index.md
@@ -0,0 +1,561 @@
+---
+lastproofread: '2021-06-30'
+---
+
+(high-availability)=
+
+# High availability
+
+VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for
+routers. Every VRRP router has a physical IP/IPv6 address, and a virtual
+address. On startup, routers elect the master, and the router with the highest
+priority becomes the master and assigns the virtual address to its interface.
+All routers with lower priorities become backup routers. The master then starts
+sending keepalive packets to notify other routers that it's available. If the
+master fails and stops sending keepalive packets, the router with the next
+highest priority becomes the new master and takes over the virtual address.
+
+VRRP keepalive packets use multicast, and VRRP setups are limited to a single
+datalink layer segment. You can setup multiple VRRP groups
+(also called virtual routers). Virtual routers are identified by a
+VRID (Virtual Router IDentifier). If you setup multiple groups on the same
+interface, their VRIDs must be unique if they use the same address family,
+but it's possible (even if not recommended for readability reasons) to use
+duplicate VRIDs on different interfaces.
+
+## Basic setup
+
+VRRP groups are created with the
+`set high-availability vrrp group $GROUP_NAME` commands. The required
+parameters are interface, vrid, and address.
+
+minimal config
+
+```none
+set high-availability vrrp group Foo vrid 10
+set high-availability vrrp group Foo interface eth0
+set high-availability vrrp group Foo address 192.0.2.1/24
+```
+
+You can verify your VRRP group status with the operational mode
+`run show vrrp` command:
+
+```none
+vyos@vyos# run show vrrp
+Name        Interface      VRID  State    Last Transition
+----------  -----------  ------  -------  -----------------
+Foo         eth1             10  MASTER   2s
+```
+
+## IPv6 support
+
+The `address` parameter can be either an IPv4 or IPv6 address, but you can
+not mix IPv4 and IPv6 in the same group, and will need to create groups with
+different VRIDs specially for IPv4 and IPv6.
+If you want to use IPv4 + IPv6 address you can use option `excluded-address`
+
+## Address
+
+The `address` can be configured either on the VRRP interface or on not VRRP
+interface.
+
+```none
+set high-availability vrrp group Foo address 192.0.2.1/24
+set high-availability vrrp group Foo address 203.0.113.22/24 interface eth2
+set high-availability vrrp group Foo address 198.51.100.33/24 interface eth3
+```
+
+## Disabling a VRRP group
+
+You can disable a VRRP group with `disable` option:
+
+```none
+set high-availability vrrp group Foo disable
+```
+
+A disabled group will be removed from the VRRP process and your router will not
+participate in VRRP for that VRID. It will disappear from operational mode
+commands output, rather than enter the backup state.
+
+## Exclude address
+
+Exclude IP addresses from `VRRP packets`. This option `excluded-address` is
+used when you want to set IPv4 + IPv6 addresses on the same virtual interface
+or when used more than 20 IP addresses.
+
+```none
+set high-availability vrrp group Foo excluded-address '203.0.113.254/24'
+set high-availability vrrp group Foo excluded-address '2001:db8:aa::1/64'
+set high-availability vrrp group Foo excluded-address '2001:db8:22::1/64'
+```
+
+## Setting VRRP group priority
+
+VRRP priority can be set with `priority` option:
+
+```none
+set high-availability vrrp group Foo priority 200
+```
+
+The priority must be an integer number from 1 to 255. Higher priority value
+increases router's precedence in the master elections.
+
+## Sync groups
+
+A sync group allows VRRP groups to transition together.
+
+```none
+edit high-availability vrrp
+set sync-group MAIN member VLAN9
+set sync-group MAIN member VLAN20
+```
+
+In the following example, when VLAN9 transitions, VLAN20 will also transition:
+
+```none
+vrrp {
+    group VLAN9 {
+        interface eth0.9
+        address 10.9.1.1/24
+        priority 200
+        vrid 9
+    }
+    group VLAN20 {
+        interface eth0.20
+        priority 200
+        address 10.20.20.1/24
+        vrid 20
+    }
+    sync-group MAIN {
+        member VLAN20
+        member VLAN9
+    }
+}
+```
+
+:::{warning}
+All items in a sync group should be similarly configured.
+If one VRRP group is set to a different preemption delay or priority,
+it would result in an endless transition loop.
+:::
+
+## Preemption
+
+VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode,
+if a router with a higher priority fails and then comes back, routers with lower
+priority will give up their master status. In non-preemptive mode, the newly
+elected master will keep the master status and the virtual address indefinitely.
+
+By default VRRP uses preemption. You can disable it with the "no-preempt"
+option:
+
+```none
+set high-availability vrrp group Foo no-preempt
+```
+
+You can also configure the time interval for preemption with the "preempt-delay"
+option. For example, to set the higher priority router to take over in 180
+seconds, use:
+
+```none
+set high-availability vrrp group Foo preempt-delay 180
+```
+
+## Track
+
+Track option to track non VRRP interface states. VRRP changes status to
+`FAULT` if one of the track interfaces in state `down`.
+
+```none
+set high-availability vrrp group Foo track interface eth0
+set high-availability vrrp group Foo track interface eth1
+```
+
+Ignore VRRP main interface faults
+
+```none
+set high-availability vrrp group Foo track exclude-vrrp-interface
+```
+
+## Unicast VRRP
+
+By default VRRP uses multicast packets. If your network does not support
+multicast for whatever reason, you can make VRRP use unicast communication
+instead.
+
+```none
+set high-availability vrrp group Foo peer-address 192.0.2.10
+set high-availability vrrp group Foo hello-source-address 192.0.2.15
+```
+
+## rfc3768-compatibility
+
+RFC 3768 defines a virtual MAC address to each VRRP virtual router.
+This virtual router MAC address will be used as the source in all periodic VRRP
+messages sent by the active node. When the rfc3768-compatibility option is set,
+a new VRRP interface is created, to which the MAC address and the virtual IP
+address is automatically assigned.
+
+```none
+set high-availability vrrp group Foo rfc3768-compatibility
+```
+
+Verification
+
+```none
+$show interfaces ethernet eth0v10
+eth0v10@eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue
+state UP group default qlen 1000
+link/ether 00:00:5e:00:01:0a brd ff:ff:ff:ff:ff:ff
+inet 172.25.0.247/16 scope global eth0v10
+valid_lft forever preferred_lft forever
+```
+
+:::{warning}
+RFC 3768 creates a virtual interface. If you want to apply
+the destination NAT rule to the traffic sent to the virtual MAC, set
+the created virtual interface as `inbound-interface`.
+:::
+
+## Global options
+
+On most scenarios, there's no need to change specific parameters, and using
+default configuration is enough. But there are cases were extra configuration
+is needed.
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp global-parameters startup_delay <1-600>
+
+   This option specifies a delay in seconds before vrrp instances start up
+   after keepalived starts.
+```
+
+## Gratuitous ARP
+
+These configuration is not mandatory and in most cases there's no
+need to configure it. But if necessary, Gratuitous ARP can be configured in
+`global-parameters` and/or in `group` section.
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp global-parameters garp interval
+   <0.000-1000>
+```
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp group <name> garp interval <0.000-1000>
+
+   Set delay between gratuitous ARP messages sent on an interface.
+
+   0 if not defined.
+```
+
+% stop_vyoslinter
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255>
+```
+
+% start_vyoslinter
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp group <name> garp master-delay <1-255>
+
+   Set delay for second set of gratuitous ARPs after transition to MASTER.
+
+   5 if not defined.
+```
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp global-parameters garp master-refresh
+   <1-600>
+```
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp group <name> garp master-refresh
+   <1-600>
+
+   Set minimum time interval for refreshing gratuitous ARPs while MASTER.
+
+   0 if not defined, which means no refreshing.
+```
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp global-parameters garp
+   master-refresh-repeat <1-600>
+```
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp group <name> garp
+   master-refresh-repeat <1-600>
+
+   Set number of gratuitous ARP messages to send at a time while MASTER.
+
+   1 if not defined.
+```
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp global-parameters garp master-repeat
+   <1-600>
+```
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp group <name> garp master-repeat
+   <1-600>
+
+   Set number of gratuitous ARP messages to send at a time after transition to
+   MASTER.
+
+   5 if not defined.
+```
+
+## Version
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp global-parameters version 2|3
+
+   Set the default VRRP version to use. This defaults to 2, but IPv6 instances
+   will always use version 3.
+```
+
+## Scripting
+
+VRRP functionality can be extended with scripts. VyOS supports two kinds of
+scripts: health check scripts and transition scripts. Health check scripts
+execute custom checks in addition to the master router reachability. Transition
+scripts are executed when VRRP state changes from master to backup or fault and
+vice versa and can be used to enable or disable certain services, for example.
+
+:::{note}
+Simply placing script files in `/config/scripts/` does not mean the
+system can execute them. To make custom scripts executable, grant them
+**execute permissions**. Use the following command:
+
+```none
+chmod +x /config/scripts/script-name.sh
+```
+:::
+
+:::{warning}
+It is not recommended to change VRRP configuration
+inside health-check and transition scripts.
+:::
+
+### Health check scripts
+
+There is the ability to run an arbitrary script at regular intervals
+according to health-check parameters. If a script returns 0, it
+indicates success. If a script returns anything else, it will indicate
+that the VRRP instance should enter the FAULT state.
+
+This setup will make the VRRP process execute the
+`/config/scripts/vrrp-check.sh script` every 60 seconds, and transition the
+group to the fault state if it fails (i.e. exits with non-zero status) three
+times:
+
+% stop_vyoslinter
+
+```none
+set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh
+set high-availability vrrp group Foo health-check interval 60
+set high-availability vrrp group Foo health-check failure-count 3
+```
+
+% start_vyoslinter
+
+An optional `timeout` can be set to define the maximum number of seconds the
+script is allowed to run. This is useful for scripts that may hang or take
+longer than expected — setting the timeout higher than the interval allows
+longer-running scripts to complete before being considered failed.
+
+% stop_vyoslinter
+
+```none
+set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh
+set high-availability vrrp group Foo health-check interval 20
+set high-availability vrrp group Foo health-check failure-count 3
+set high-availability vrrp group Foo health-check timeout 40
+```
+
+% start_vyoslinter
+
+When the vrrp group is a member of the sync group will use only
+the sync group health check script.
+This example shows how to configure it for the sync group:
+
+% stop_vyoslinter
+
+```none
+set high-availability vrrp sync-group Bar health-check script /config/scripts/vrrp-check.sh
+set high-availability vrrp sync-group Bar health-check interval 60
+set high-availability vrrp sync-group Bar health-check failure-count 3
+```
+
+% start_vyoslinter
+
+### Transition scripts
+
+Transition scripts can help you implement various fixups, such as starting and
+stopping services, or even modifying the VyOS config on VRRP transition.
+This setup will make the VRRP process execute the
+`/config/scripts/vrrp-fail.sh` with argument `Foo` when VRRP fails,
+and the `/config/scripts/vrrp-master.sh` when the router becomes the master:
+
+% stop_vyoslinter
+
+```none
+set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo"
+set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo"
+set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo"
+```
+
+% start_vyoslinter
+
+To know more about scripting, check the {ref}`command-scripting` section.
+
+## Virtual-server
+
+```{eval-rst}
+.. include:: /_include/need_improvement.txt
+```
+
+Virtual Server allows to Load-balance traffic destination virtual-address:port
+between several real servers.
+
+### Algorithm
+
+Load-balancing schedule algorithm:
+
+- round-robin
+- weighted-round-robin
+- least-connection
+- weighted-least-connection
+- source-hashing
+- destination-hashing
+- locality-based-least-connection
+
+```none
+set high-availability virtual-server 203.0.113.1 algorithm 'least-connection'
+```
+
+### Forward method
+
+- NAT
+- direct
+- tunnel
+
+```none
+set high-availability virtual-server 203.0.113.1 forward-method 'nat'
+```
+
+### Health-check
+
+Custom health-check script allows checking real-server availability
+
+% stop_vyoslinter
+
+```none
+set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script <path-to-script>
+```
+
+% start_vyoslinter
+
+### Fwmark
+
+Firewall mark. It possible to loadbalancing traffic based on `fwmark` value
+
+```none
+set high-availability virtual-server 203.0.113.1 fwmark '111'
+```
+
+### Real server
+
+Real server IP address and port
+
+% stop_vyoslinter
+
+```none
+set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80'
+```
+
+% start_vyoslinter
+
+### Example
+
+Virtual-server can be configured with VRRP virtual address or without VRRP.
+
+In the next example all traffic destined to `203.0.113.1` and port `8280`
+protocol TCP is balanced between 2 real servers `192.0.2.11` and
+`192.0.2.12` to port `80`
+
+Real server is auto-excluded if port check with this server fail.
+
+% stop_vyoslinter
+
+```none
+set interfaces ethernet eth0 address '203.0.113.11/24'
+set interfaces ethernet eth1 address '192.0.2.1/24'
+set high-availability vrrp group FOO interface 'eth0'
+set high-availability vrrp group FOO no-preempt
+set high-availability vrrp group FOO priority '150'
+set high-availability vrrp group FOO address '203.0.113.1/24'
+set high-availability vrrp group FOO vrid '10'
+
+set high-availability virtual-server 203.0.113.1 algorithm 'source-hashing'
+set high-availability virtual-server 203.0.113.1 delay-loop '10'
+set high-availability virtual-server 203.0.113.1 forward-method 'nat'
+set high-availability virtual-server 203.0.113.1 persistence-timeout '180'
+set high-availability virtual-server 203.0.113.1 port '8280'
+set high-availability virtual-server 203.0.113.1 protocol 'tcp'
+set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80'
+set high-availability virtual-server 203.0.113.1 real-server 192.0.2.12 port '80'
+```
+
+% start_vyoslinter
+
+A firewall mark `fwmark` allows using multiple ports for high-availability
+virtual-server.
+It uses fwmark value.
+
+In this example all traffic destined to ports "80, 2222, 8888" protocol TCP
+marks to fwmark "111" and balanced between 2 real servers.
+Port "0" is required if multiple ports are used.
+
+% stop_vyoslinter
+
+```none
+set interfaces ethernet eth0 address 'dhcp'
+set interfaces ethernet eth0 description 'WAN'
+set interfaces ethernet eth1 address '192.0.2.1/24'
+set interfaces ethernet eth1 description 'LAN'
+
+set policy route PR interface 'eth0'
+set policy route PR rule 10 destination port '80,2222,8888'
+set policy route PR rule 10 protocol 'tcp'
+set policy route PR rule 10 set mark '111'
+
+set high-availability virtual-server vyos fwmark '111'
+set high-availability virtual-server vyos protocol 'tcp'
+set high-availability virtual-server vyos real-server 192.0.2.11 health-check script '/config/scripts/check-real-server-first.sh'
+set high-availability virtual-server vyos real-server 192.0.2.11 port '0'
+set high-availability virtual-server vyos real-server 192.0.2.12 health-check script '/config/scripts/check-real-server-second.sh'
+set high-availability virtual-server vyos real-server 192.0.2.12 port '0'
+
+set nat source rule 100 outbound-interface name 'eth0'
+set nat source rule 100 source address '192.0.2.0/24'
+set nat source rule 100 translation address 'masquerade'
+```
+
+% start_vyoslinter
+
+Op-mode check virtual-server status
+
+```none
+vyos@r14:~$ run show virtual-server
+IP Virtual Server version 1.2.1 (size=4096)
+Prot LocalAddress:Port Scheduler Flags
+  -> RemoteAddress:Port           Forward Weight ActiveConn InActConn
+FWM  111 lc persistent 300
+  -> 192.0.2.11:0                 Masq    1      0          0
+  -> 192.0.2.12:0                 Masq    1      1          0
+```
+
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
new file mode 100644
index 00000000..3e215502
--- /dev/null
+++ b/docs/configuration/index.md
@@ -0,0 +1,23 @@
+# Configuration Guide
+
+The following structure represents the CLI structure.
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+container/index
+firewall/index
+highavailability/index
+interfaces/index
+loadbalancing/index
+nat/index
+policy/index
+pki/index
+protocols/index
+service/index
+system/index
+trafficpolicy/index
+vpn/index
+vrf/index
+```
diff --git a/docs/configuration/interfaces/bonding.md b/docs/configuration/interfaces/bonding.md
new file mode 100644
index 00000000..7a07a27c
--- /dev/null
+++ b/docs/configuration/interfaces/bonding.md
@@ -0,0 +1,764 @@
+---
+lastproofread: '2025-12-09'
+---
+
+(bond-interface)=
+
+# Bond / link aggregation
+
+A **bonding interface** aggregates multiple network interfaces into a single
+logical interface (referred to as a bond, {abbr}`LAG (Link Aggregation Group)`,
+EtherChannel, or port-channel).
+
+The behavior of a bonding interface depends on the selected mode. Modes provide
+either fault tolerance or a combination of load balancing and fault tolerance.
+Additionally, the bonding interface can be configured for link integrity
+monitoring.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: bonding
+:var1: bond0
+```
+
+### Member interfaces
+
+```{cfgcmd} set interfaces bonding \<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/bridge.md b/docs/configuration/interfaces/bridge.md
new file mode 100644
index 00000000..77775767
--- /dev/null
+++ b/docs/configuration/interfaces/bridge.md
@@ -0,0 +1,431 @@
+---
+lastproofread: '2025-12-22'
+---
+
+(bridge-interface)=
+
+# Bridge
+
+VyOS bridges connect Ethernet segments by grouping multiple interfaces into a
+single bridge interface, which acts as a virtual software switch. Unlike
+routers, which forward traffic based on Layer 3 IP addresses, bridges operate
+at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2,
+bridges are protocol-agnostic and transparently forward all Ethernet-
+encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial
+protocols.
+
+This implementation utilizes the Linux bridge subsystem to support a subset of
+the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning.
+
+:::{note}
+{abbr}`STP (Spanning Tree Protocol)` is disabled by default in VyOS
+and must be explicitly enabled if required. See {ref}`stp` for details.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: bridge
+:var1: br0
+```
+
+
+### Member interfaces
+
+```{cfgcmd} set interfaces bridge \<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/dummy.md b/docs/configuration/interfaces/dummy.md
new file mode 100644
index 00000000..d2d27c5d
--- /dev/null
+++ b/docs/configuration/interfaces/dummy.md
@@ -0,0 +1,87 @@
+---
+lastproofread: '2026-01-23'
+---
+
+(dummy-interface)=
+
+# Dummy
+
+A dummy interface is a virtual network interface that operates like the
+loopback interface, accepting traffic and routing it back to the local host.
+Unlike the loopback interface, which is limited to one per system and reserved
+for internal system use, multiple dummy interfaces can be created, removed, and
+managed without impacting core operations.
+
+As a software-based interface, the dummy interface does not depend on physical
+link state and remains active as long as the operating system is running.
+
+Dummy interfaces are commonly used in environments with multiple redundant
+uplinks (e.g., a server connected to two different switches), where assigning a
+management IP address to a specific physical interface is risky. If that
+interface fails, the management IP address becomes unreachable.
+
+Assigning the management IP address to a dummy interface and advertising it
+over all available physical links ensures the address remains reachable as long
+as at least one physical path is active.
+
+Dummy interfaces are also used for testing and simulation purposes.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address.txt
+:var0: dummy
+:var1: dum0
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: dummy
+:var1: dum0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: dummy
+:var1: dum0
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: dummy
+:var1: dum0
+```
+
+
+## Operation
+
+```{opcmd} show interfaces dummy
+
+Show brief interface information.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces dummy
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+dum0             172.18.254.201/32                 u/u
+:::
+```
+
+```{opcmd} show interfaces dummy \<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/ethernet.md b/docs/configuration/interfaces/ethernet.md
new file mode 100644
index 00000000..eac0b443
--- /dev/null
+++ b/docs/configuration/interfaces/ethernet.md
@@ -0,0 +1,515 @@
+---
+lastproofread: '2026-01-19'
+---
+
+(ethernet-interface)=
+
+# Ethernet
+
+Ethernet interfaces (e.g., `eth0`, `eth1`) represent the host's physical
+or virtual network ports.
+
+They are the most common interface type, serving as the base layer upon which
+IP addresses, VLANs, and tunnels are configured to carry traffic across both
+LANs and WANs.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: ethernet
+:var1: eth0
+```
+
+```{cfgcmd} set interfaces ethernet \<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/geneve.md b/docs/configuration/interfaces/geneve.md
new file mode 100644
index 00000000..1fce1119
--- /dev/null
+++ b/docs/configuration/interfaces/geneve.md
@@ -0,0 +1,105 @@
+---
+lastproofread: '2026-02-02'
+---
+
+(geneve-interface)=
+
+# Geneve
+
+{abbr}`Geneve (Generic Network Virtualization Encapsulation)` interfaces
+operate as virtual network ports. Administrators can apply standard network
+configurations on them, such as IP addressing, bridging, or firewall rules,
+just as they would on physical Ethernet ports.
+
+The Geneve protocol encapsulates Layer 2 Ethernet frames originating from
+endpoints such as virtual machines, containers, or physical servers inside UDP
+packets. It unifies the features of earlier encapsulation protocols, including
+VXLAN, NVGRE, and STT, and addresses their limitations, such as fixed header
+structures and a lack of metadata support. Because of its extensibility, Geneve
+may eventually replace those older protocols.
+
+Geneve tunnels are used to connect virtual switches residing within
+hypervisors, physical switches, middleboxes, and other network appliances.
+
+Geneve tunnels operate over any standard IP network. In larger deployments,
+the underlying network (underlay) is often built using a **Clos** topology,
+also known as a *leaf-and-spine* or *fat-tree* topology.
+
+Geneve header:
+
+```none
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|Ver|  Opt Len  |O|C|    Rsvd.  |          Protocol Type        |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|        Virtual Network Identifier (VNI)       |    Reserved   |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                    Variable Length Options                    |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-mac.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-mtu.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-ip.txt
+:var0: geneve
+:var1: gnv0
+```
+
+```{cmdincludemd} /_include/interface-ipv6.txt
+:var0: geneve
+:var1: gnv0
+```
+
+
+### Geneve options
+
+```{cfgcmd} set interfaces geneve gnv0 remote \<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/index.md b/docs/configuration/interfaces/index.md
new file mode 100644
index 00000000..9082cd80
--- /dev/null
+++ b/docs/configuration/interfaces/index.md
@@ -0,0 +1,26 @@
+# Interfaces
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+bonding
+bridge
+dummy
+ethernet
+geneve
+l2tpv3
+loopback
+macsec
+openvpn
+wireguard
+pppoe
+pseudo-ethernet
+sstp-client
+tunnel
+virtual-ethernet
+vti
+vxlan
+wireless
+wwan
+```
diff --git a/docs/configuration/interfaces/l2tpv3.md b/docs/configuration/interfaces/l2tpv3.md
new file mode 100644
index 00000000..324840fa
--- /dev/null
+++ b/docs/configuration/interfaces/l2tpv3.md
@@ -0,0 +1,170 @@
+---
+lastproofread: '2026-02-05'
+---
+
+(l2tpv3-interface)=
+
+# L2TPv3
+
+{abbr}`L2TPv3 (Layer 2 Tunneling Protocol version 3)` interfaces let you
+establish L2TPv3 tunnels to transport Layer 2 traffic over IP networks.
+
+The L2TPv3 protocol (defined in RFC 3931) wraps Layer 2 frames (e.g., Ethernet,
+Frame Relay, HDLC) within IP packets, allowing them to traverse the underlying
+IP infrastructure.
+
+Unlike L2TPv2, which strictly requires UDP encapsulation, the L2TPv3 protocol
+is more flexible and supports two encapsulation types:
+
+> - **Direct IP:** Tunnel data is encapsulated directly inside IP packets
+>   (Protocol 115) for lower overhead.
+> - **UDP:** Tunnel data is encapsulated inside a UDP datagram. This allows the
+>   tunnel to traverse NAT more easily.
+
+L2TPv3 tunnels connect geographically separated sites, serving as a simpler
+alternative to {ref}`mpls` by operating over basic IP connectivity rather than
+requiring a full MPLS infrastructure.
+
+L2TPv3 tunnels can be established over both IPv4 and IPv6 underlying networks.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-without-dhcp.txt
+:var0: l2tpv3
+:var1: l2tpeth0
+```
+
+
+### L2TPv3 options
+
+Use the following commands to configure the L2TPv3 tunnel's specific parameters.
+
+```{cfgcmd} set interfaces l2tpv3 \<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/loopback.md b/docs/configuration/interfaces/loopback.md
new file mode 100644
index 00000000..72f14c16
--- /dev/null
+++ b/docs/configuration/interfaces/loopback.md
@@ -0,0 +1,67 @@
+---
+lastproofread: '2026-01-23'
+---
+
+(loopback-interface)=
+
+# Loopback
+
+The loopback interface is a virtual, software-based network interface. All
+traffic sent to it loops back and only targets services on the local host.
+
+:::{note}
+Only one loopback `lo` interface is allowed per operating system.
+If you require multiple virtual interfaces, use the {ref}`dummy-interface`
+interface type.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address.txt
+:var0: loopback
+:var1: lo
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: loopback
+:var1: lo
+```
+
+
+## Operation
+
+```{opcmd} show interfaces loopback
+
+Show brief interface information.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces loopback
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+lo               127.0.0.1/8                       u/u
+                 ::1/128
+:::
+```
+
+```{opcmd} show interfaces loopback lo
+
+Show detailed interface information.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces loopback lo
+lo: <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/macsec.md b/docs/configuration/interfaces/macsec.md
new file mode 100644
index 00000000..b3c70362
--- /dev/null
+++ b/docs/configuration/interfaces/macsec.md
@@ -0,0 +1,319 @@
+---
+lastproofread: '2026-02-13'
+---
+
+(macsec-interface)=
+
+# MACsec
+
+MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in
+2006\. It enables protocol-independent connectivity between two hosts, providing
+data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec
+operates at the Ethernet layer as a Layer 2 protocol and secures traffic within
+Layer 2 networks, including DHCP and ARP requests. It does not compete with
+other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each
+addresses distinct use cases.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: macsec
+:var1: macsec0
+```
+
+
+### MACsec options
+
+```{cfgcmd} set interfaces macsec \<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/openvpn-examples.md b/docs/configuration/interfaces/openvpn-examples.md
new file mode 100644
index 00000000..817e6868
--- /dev/null
+++ b/docs/configuration/interfaces/openvpn-examples.md
@@ -0,0 +1,769 @@
+# Site-to-site
+
+:::{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd directives for command coverage tracking.
+:::
+
+OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, it is effective for quickly establishing tunnels between routers.
+
+As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates.
+
+Pre-shared key mode is now deprecated and will be removed from future OpenVPN versions. VyOS will also discontinue support for this option because pre-shared keys are significantly less secure than TLS.
+
+We will configure OpenVPN with self-signed certificates, and then discuss the legacy pre-shared key mode.
+
+In both cases, we will use the following settings:
+
+- The public IP address of the local VPN endpoint is 198.51.100.10.
+- The public IP address of the remote VPN endpoint is 203.0.113.11.
+- The tunnel uses 10.255.1.1 for the local IP address and 10.255.1.2 for the remote IP address.
+- The local site has a subnet of 10.0.0.0/16.
+- The remote site has a subnet of 10.1.0.0/16.
+- The official OpenVPN port 1194 is reserved for client VPN. For site-to-site VPN, port 1195 is used.
+- The `persistent-tunnel` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface.
+- If known, the remote router\'s IP address can be configured using the `remote-host` directive. If unknown, it can be omitted. We assume the remote router has a dynamic IP address.
+
+![](/_static/images/openvpn_site2site_diagram.webp)
+
+## Set up site-to-site certificates
+
+Deploying a complete Public Key Infrastructure (PKI) with a Certificate Authority (CA) would overcomplicate site-to-site OpenVPN setups, which are primarily designed for simplicity. To keep their configuration simple without compromising security, VyOS 1.4 and later lets you verify self-signed certificates using certificate fingerprints.
+
+Generate a self-signed certificate on each router, preferably using the Elliptic Curve (EC) type. In configuration mode, run the following command: `run generate pki certificate self-signed install <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/openvpn.md b/docs/configuration/interfaces/openvpn.md
new file mode 100644
index 00000000..170c585d
--- /dev/null
+++ b/docs/configuration/interfaces/openvpn.md
@@ -0,0 +1,614 @@
+(openvpn)=
+
+# OpenVPN
+
+Traditionally, hardware routers use IPsec exclusively because it is easy to
+implement in hardware, and their CPUs lack sufficient power for software-based
+encryption. This limitation is less relevant for VyOS, as it is a software
+router.
+
+OpenVPN has been widely used on UNIX platforms for a long time and is a popular
+choice for remote-access VPNs. It also supports site-to-site connections.
+
+OpenVPN offers the following advantages:
+
+- It uses a single TCP or UDP connection and does not rely on packet source
+  addresses, so it works even through double NAT. This makes it well-suited for
+  public hotspots.
+- It is easy to set up and offers very flexible split tunneling.
+- A variety of client GUI frontends are available for any platform.
+
+Disadvantages include:
+
+- It is slower than IPsec due to higher protocol overhead and because it runs
+  in user mode, while IPsec on Linux runs in kernel mode.
+- No operating system includes OpenVPN client software by default.
+
+In the VyOS CLI, OpenVPN is configured as a network interface using `set
+interfaces openvpn` rather than `set vpn`, which is often overlooked.
+
+## Configuration
+
+```{cfgcmd} set interfaces openvpn \<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/pppoe.md b/docs/configuration/interfaces/pppoe.md
new file mode 100644
index 00000000..b79f41a2
--- /dev/null
+++ b/docs/configuration/interfaces/pppoe.md
@@ -0,0 +1,419 @@
+---
+lastproofread: '2026-03-03'
+---
+
+(pppoe-interface)=
+
+# PPPoE
+
+{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol
+that encapsulates PPP frames within Ethernet frames.
+It's often used for connecting ISP clients to a broadband access server.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: pppoe
+:var1: pppoe0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: pppoe
+:var1: pppoe0
+```
+
+```{cmdincludemd} /_include/interface-mtu.txt
+:var0: pppoe
+:var1: pppoe0
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: pppoe
+:var1: pppoe0
+```
+
+
+### PPPoE options
+
+```{cfgcmd} set interfaces pppoe \<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/pseudo-ethernet.md b/docs/configuration/interfaces/pseudo-ethernet.md
new file mode 100644
index 00000000..fc8833eb
--- /dev/null
+++ b/docs/configuration/interfaces/pseudo-ethernet.md
@@ -0,0 +1,52 @@
+---
+lastproofread: '2026-03-05'
+---
+
+(pseudo-ethernet-interface)=
+
+# MACVLAN (pseudo-Ethernet)
+
+MACVLAN, or pseudo-Ethernet interfaces, operate as logical subinterfaces of
+standard Ethernet interfaces. Each subinterface has a unique MAC address but
+shares a single physical Ethernet port.
+That allows the user to send packets from different source IPv4 or IPv6 addresses
+using a different MAC address.
+
+Pseudo-Ethernet interfaces behave like physical Ethernet interfaces. They
+support IPv4 and IPv6 addressing, can obtain IP addresses through DHCP or
+DHCPv6, and are mapped to a physical Ethernet port. They inherit
+characteristics such as speed and duplex from their parent interface and can
+be referenced like standard Ethernet interfaces once created.
+
+```{eval-rst}
+Pseudo-Ethernet interfaces may not work in environments that require a
+   :abbr:`NIC (Network Interface Card)` to have only one MAC address.
+   This includes:
+
+   * VMware machines with default settings.
+   * Network switches that permit only a single MAC address.
+   * xDSL modems that learn the NIC's MAC address.
+```
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: pseudo-ethernet
+:var1: peth0
+```
+
+### MACVLAN (pseudo-Ethernet) options
+
+```{cfgcmd} set interfaces pseudo-ethernet \<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/sstp-client.md b/docs/configuration/interfaces/sstp-client.md
new file mode 100644
index 00000000..da98aecd
--- /dev/null
+++ b/docs/configuration/interfaces/sstp-client.md
@@ -0,0 +1,170 @@
+---
+lastproofread: '2026-03-16'
+---
+
+(sstp-client-interface)=
+
+# SSTP client
+
+{abbr}`SSTP (Secure Socket Tunneling Protocol)` transports PPP traffic over an
+SSL/TLS channel, providing transport-level security through key negotiation,
+encryption, and traffic integrity checking. The use of SSL/TLS over TCP port
+443 (by default, the port can be changed) allows SSTP to pass through virtually
+all firewalls and proxy servers, except for authenticated web proxies.
+
+:::{note}
+VyOS includes a built-in SSTP server. For more information, see
+{ref}`sstp`.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: sstpc
+:var1: sstpc0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: sstpc
+:var1: sstpc0
+```
+
+```{cmdincludemd} /_include/interface-mtu.txt
+:var0: sstpc
+:var1: sstpc0
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: sstpc
+:var1: sstpc0
+```
+
+
+### SSTP client options
+
+```{cfgcmd} set interfaces sstpc \<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/tunnel.md b/docs/configuration/interfaces/tunnel.md
new file mode 100644
index 00000000..9c9885d2
--- /dev/null
+++ b/docs/configuration/interfaces/tunnel.md
@@ -0,0 +1,309 @@
+---
+lastproofread: '2026-01-23'
+---
+
+(tunnel-interface)=
+
+# Tunnel
+
+Tunnel interfaces are virtual links that transmit encapsulated traffic between
+private networks or hosts across public infrastructure, such as the Internet.
+They operate using encapsulation protocols to wrap original traffic for
+transport. The supported protocols include {abbr}`GRE (Generic Routing
+Encapsulation)`, IPIP, IPIP6, IP6IP6, and 6in4 (SIT).
+
+While {abbr}`GRE (Generic Routing Encapsulation)` is often the preferred
+one-size-fits-all solution due to its versatility, other encapsulation
+protocols may be better suited for specific use cases.
+
+VyOS uses a single tunnel interface type for all of these protocols. There are
+no separate {abbr}`GRE (Generic Routing Encapsulation)`, IPIP, or IP6IP6
+interface types; instead, the desired encapsulation protocol is selected within
+the `set interfaces tunnel` configuration.
+
+Configuration options for each protocol are described below.
+
+:::{warning}
+Do not change the encapsulation type for already configured tunnel
+interfaces, as this may break their dependent configurations.
+:::
+
+## Common interface configuration
+
+```{cmdincludemd} /_include/interface-address.txt
+:var0: tunnel
+:var1: tun0
+```
+
+```{cmdincludemd} /_include/interface-common-without-mac.txt
+:var0: tunnel
+:var1: tun0
+```
+
+
+## IPIP
+
+IPIP is a straightforward encapsulation protocol defined in RFC 2003. It
+encapsulates one IPv4 packet inside another IPv4 packet.
+
+Tunnels with IPIP encapsulation do not have protocol-specific configuration
+options except for explicitly defining the encapsulation type as IPIP (see
+the example below).
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation ipip
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 203.0.113.20
+set interfaces tunnel tun0 address 192.168.100.200/24
+```
+
+
+## IP6IP6
+
+IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside
+another IPv6 packet.
+
+Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not
+have protocol-specific configuration options except for explicitly defining
+the encapsulation type as IP6IP6.
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation ip6ip6
+set interfaces tunnel tun0 source-address 2001:db8:aa::1
+set interfaces tunnel tun0 remote 2001:db8:aa::2
+set interfaces tunnel tun0 address 2001:db8:bb::1/64
+```
+
+
+## IPIP6
+
+IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets.
+
+Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with
+IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6.
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation ipip6
+set interfaces tunnel tun0 source-address 2001:db8:aa::1
+set interfaces tunnel tun0 remote 2001:db8:aa::2
+set interfaces tunnel tun0 address 192.168.70.80/24
+```
+
+
+## 6in4 (SIT)
+
+6in4, also known as {abbr}`SIT (Simple Internet Transition)`, is an
+encapsulation protocol defined in {rfc}`4213` that wraps IPv6 packets
+inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41,
+which is reserved exclusively for IPv6 encapsulation.
+
+The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet.
+Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes
+over an underlying network with a standard MTU of 1500 bytes without
+fragmentation.
+
+6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as
+[Hurricane Electric]) to connect isolated IPv6 networks or individual hosts to
+the IPv6 internet.
+
+Example:
+
+```none
+set interfaces tunnel tun0 encapsulation sit
+set interfaces tunnel tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 192.0.2.20
+set interfaces tunnel tun0 address 2001:db8:bb::1/64
+```
+
+:::{seealso}
+For a practical configuration example, see the
+{ref}`Tunnelbroker.net (IPv6) <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/virtual-ethernet.md b/docs/configuration/interfaces/virtual-ethernet.md
new file mode 100644
index 00000000..dee1b332
--- /dev/null
+++ b/docs/configuration/interfaces/virtual-ethernet.md
@@ -0,0 +1,119 @@
+---
+lastproofread: '2026-01-26'
+---
+
+(virtual-ethernet)=
+
+# Virtual Ethernet
+
+Virtual Ethernet (veth) interfaces are software-based interfaces that operate
+in pairs, creating a tunnel between each other. Traffic transmitted into one
+interface of the pair (e.g., `veth0`) is delivered directly to its peer
+interface (e.g., `veth1`).
+
+Veth interfaces are commonly used to connect network namespaces or VRFs, but
+they can also function as standalone virtual network interfaces.
+
+:::{note}
+Veth interfaces must be created in pairs, where each interface acts
+as the peer of the other.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address-with-dhcp.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+
+### VLAN
+
+#### Regular VLANs (802.1q)
+
+```{cmdincludemd} /_include/interface-vlan-8021q.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+
+#### 802.1ad (QinQ)
+
+```{cmdincludemd} /_include/interface-vlan-8021ad.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: virtual-ethernet
+:var1: veth0
+```
+
+
+## Operation
+
+```{opcmd} show interfaces virtual-ethernet
+
+Show brief interface information.
+
+:::{code-block} none
+vyos@vyos:~$ show interfaces virtual-ethernet
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+veth10           100.64.0.0/31                     u/u
+veth11           100.64.0.1/31                     u/u
+:::
+```
+
+```{opcmd} show interfaces virtual-ethernet \<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/vti.md b/docs/configuration/interfaces/vti.md
new file mode 100644
index 00000000..dbd2c88c
--- /dev/null
+++ b/docs/configuration/interfaces/vti.md
@@ -0,0 +1,121 @@
+(vti-interface)=
+
+# VTI (virtual tunnel interface)
+
+{abbr}`VTIs (virtual tunnel interfaces)` let you create secure, encrypted
+tunnels between private networks or hosts across public infrastructure, such as
+the Internet. They operate alongside an underlying IPsec tunnel, which handles
+encapsulation and encryption, while VTIs function exclusively as routing
+interfaces.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cmdincludemd} /_include/interface-ip.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cmdincludemd} /_include/interface-ipv6.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cmdincludemd} /_include/interface-mtu.txt
+:var0: vti
+:var1: vti0
+```
+
+```{cfgcmd} set interfaces vti \<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/vxlan.md b/docs/configuration/interfaces/vxlan.md
new file mode 100644
index 00000000..8dae75ff
--- /dev/null
+++ b/docs/configuration/interfaces/vxlan.md
@@ -0,0 +1,373 @@
+---
+lastproofread: '2026-03-16'
+---
+
+(vxlan-interface)=
+
+# VXLAN
+
+{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology
+that addresses scalability challenges in large cloud computing environments.
+It encapsulates Ethernet frames (Layer 2) within UDP datagrams (Layer 4), which
+are then transmitted via UDP port 4789, as assigned by IANA. VXLAN endpoints,
+called {abbr}`VTEPs (VXLAN tunnel endpoints)`, terminate VXLAN tunnels and can
+be either virtual or physical switch ports.
+
+VXLAN supports up to 16 million logical networks and enables Layer 2 adjacency
+across Layer 3 IP networks. It uses multicast or unicast with head-end
+replication (HER) to flood broadcast, unknown unicast, and multicast (BUM)
+traffic.
+
+The VXLAN specification was initially developed by VMware, Arista Networks, and
+Cisco. Other supporters include Huawei, Broadcom, Citrix, Pica8, Big Switch
+Networks, Cumulus Networks, Dell EMC, Ericsson, Mellanox, FreeBSD, OpenBSD, Red
+Hat, Joyent, and Juniper Networks.
+
+VXLAN is officially documented by the IETF in {rfc}`7348`.
+
+When configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing
+(Hyper-V) or Forged Transmits (ESX) are permitted. Otherwise, the hypervisor
+may block forwarded frames.
+
+:::{note}
+Although the IANA-assigned VXLAN port is **4789**, VyOS uses the
+Linux default UDP port **8472** for VXLAN interfaces. To ensure compatibility
+with other vendors, set the port to the IANA standard **4789**.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-without-dhcp.txt
+:var0: vxlan
+:var1: vxlan0
+```
+
+
+### VXLAN-specific options
+
+```{cfgcmd} set interfaces vxlan \<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/wireguard.md b/docs/configuration/interfaces/wireguard.md
new file mode 100644
index 00000000..121d1df0
--- /dev/null
+++ b/docs/configuration/interfaces/wireguard.md
@@ -0,0 +1,434 @@
+---
+lastproofread: '2026-03-02'
+---
+
+(wireguard)=
+
+# WireGuard
+
+WireGuard is an extremely simple, fast, and modern VPN that utilizes
+state-of-the-art cryptography. See <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/wireless.md b/docs/configuration/interfaces/wireless.md
new file mode 100644
index 00000000..9e6b7c99
--- /dev/null
+++ b/docs/configuration/interfaces/wireless.md
@@ -0,0 +1,923 @@
+---
+lastproofread: '2026-03-23'
+---
+
+(wireless-interface)=
+
+# Wireless LAN / Wi-Fi
+
+{abbr}`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless
+connectivity, referred to as Wi-Fi, and operate in one of the following
+modes:
+
+- {abbr}`WAP (Wireless Access-Point)` mode provides network access to connecting
+  stations if the physical hardware supports acting as a WAP
+- Station mode acts as a Wi-Fi client accessing the network through an available
+  WAP
+- Monitor mode lets the system passively monitor wireless traffic
+
+If the system detects an unconfigured wireless device, it will be automatically
+added to the configuration tree, specifying any detected settings (for example,
+its MAC address) and configured to run in monitor mode.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-common-with-dhcp.txt
+:var0: wireless
+:var1: wlan0
+```
+
+
+### System-wide configuration
+
+```{cfgcmd} set system wireless country-code \<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/wwan.md b/docs/configuration/interfaces/wwan.md
new file mode 100644
index 00000000..e8121f28
--- /dev/null
+++ b/docs/configuration/interfaces/wwan.md
@@ -0,0 +1,355 @@
+---
+lastproofread: '2026-03-30'
+---
+
+(wwan-interface)=
+
+# WWAN
+
+{abbr}`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular
+networks via a cellular modem or card.
+
+Configure these interfaces under the `interfaces wwan` node.
+
+## Configuration
+
+### Common interface configuration
+
+```{cmdincludemd} /_include/interface-address-with-dhcp.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-description.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-disable.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-disable-link-detect.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-mtu.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-ip.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-ipv6.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-vrf.txt
+:var0: wwan
+:var1: wwan0
+```
+
+**DHCP(v6)**
+
+```{cmdincludemd} /_include/interface-dhcp-options.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-dhcpv6-options.txt
+:var0: wwan
+:var1: wwan0
+```
+
+```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt
+:var0: wwan
+:var1: wwan0
+```
+
+
+### WWAN options
+
+```{cfgcmd} set interfaces wwan \<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
+```
diff --git a/docs/configuration/loadbalancing/haproxy.md b/docs/configuration/loadbalancing/haproxy.md
new file mode 100644
index 00000000..d60c5248
--- /dev/null
+++ b/docs/configuration/loadbalancing/haproxy.md
@@ -0,0 +1,510 @@
+---
+lastproofread: '2026-04-06'
+---
+
+# HAproxy
+
+```{include} /_include/need_improvement.txt
+```
+
+HAProxy is a load balancer and proxy server that provides
+high-availability, load balancing, and proxying for TCP (level 4) and
+HTTP-based (level 7) applications.
+
+## Configuration
+
+Service configuration specifies the port to bind to. Backend
+configuration defines the load balancing method and specifies the backend
+servers.
+
+### Service
+
+```{cfgcmd} set load-balancing haproxy service \<name\> listen-address \<address\>
+
+Set the IP address for the service to bind to. By default, the service
+listens on all IPv4 and IPv6 addresses.
+```
+
+```{cfgcmd} set load-balancing haproxy service \<name\> port \<port\>
+
+Create service *<name>* to listen on \<port\>
+```
+
+```{cfgcmd} set load-balancing haproxy service \<name\> mode \<tcp|http\>
+
+Configure service *<name>* mode TCP or HTTP
+```
+
+```{cfgcmd} set load-balancing haproxy service \<name\> backend \<name\>
+
+Configure service *<name>* to use the backend \<name\>
+```
+
+```{cfgcmd} set load-balancing haproxy service \<name\> ssl certificate \<name\>
+
+Set the SSL certificate \<name\> for service \<name\>. You can define
+multiple certificates.
+```
+
+```{cfgcmd} set load-balancing haproxy service \<name\> http-response-headers \<header-name\> value \<header-value\>
+
+Set custom HTTP headers to include in all responses.
+```
+
+```{cfgcmd} set load-balancing haproxy service \<name\> logging facility \<facility\> level \<level\>
+
+Specify facility and level for logging.
+For an explanation on {ref}`syslog_facilities` and
+{ref}`syslog_severity_level`,
+see tables in the syslog configuration section.
+```
+
+```{cfgcmd} set load-balancing haproxy service \<name\> timeout client \<seconds\>
+
+Set the maximum inactivity time on the client side for this service.
+Value range 1-3600 seconds.
+```
+
+```{cfgcmd} set load-balancing haproxy service \<name\> http-compression algorithm \<gzip | deflate | identity | raw-deflate\>
+
+Set the compression algorithm to be used when compressing HTTP responses.
+```
+
+```{cfgcmd} set load-balancing haproxy service \<name\> http-compression mime-type \<mime-type\>
+
+Set the list of HTTP response MIME types which haproxy will attempt to
+compress, if received uncompressed from backend server.
+```
+
+#### Rules
+
+Rules control and route incoming traffic to specific backends based on
+predefined conditions. Rules define matching criteria and specify actions
+to perform.
+
+```{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> domain-name \<name\>
+
+Match domain name
+```
+
+````{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> ssl \<sni\>
+
+```{eval-rst}
+SSL match Server Name Indication (SNI) option:
+ * ``req-ssl-sni`` SSL Server Name Indication (SNI) request match
+ * ``ssl-fc-sni`` SSL frontend connection Server Name Indication match
+ * ``ssl-fc-sni-end`` SSL frontend match end of connection Server Name
+
+    Indication
+```
+````
+
+````{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> url-path \<match\> \<url\>
+
+Define URL path matching rules for a specific service. Use this command
+to specify how to match the URL path against incoming requests.
+
+```{eval-rst}
+The available options for <match> are:
+ * ``begin`` Matches the beginning of the URL path
+ * ``end`` Matches the end of the URL path.
+ * ``exact`` Matches the URL path exactly.
+```
+````
+
+```{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> set backend \<name\>
+
+Assign a specific backend to a rule
+```
+
+```{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> redirect-location \<url\>
+
+Redirect URL to a new location.
+```
+
+### Backend
+
+````{cfgcmd} set load-balancing haproxy backend \<name\> balance \<balance\>
+
+Specify the load balancing algorithm for distributing requests among
+available servers.
+
+```{eval-rst}
+Balance algorithms:
+ * ``source-address`` Distributes requests based on the source IP address
+   of the client.
+ * ``round-robin`` Distributes requests in a circular manner,
+   sequentially sending each request to the next server in line.
+ * ``least-connection`` Distributes requests to the server with the fewest
+   active connections.
+```
+````
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> mode \<mode\>
+
+Configure backend *<name>* mode TCP or HTTP.
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> address \<x.x.x.x\>
+
+Set the address of the backend server that receives incoming traffic.
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> port \<port\>
+
+Set the address of the backend port.
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> check
+
+Active health check backend server.
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> check port \<port\>
+
+Set an alternative port number for health checks.
+Overrides the default server port used for TCP/HTTP checks.
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> send-proxy
+
+Send a Proxy Protocol version 1 header (text format).
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> send-proxy-v2
+
+Send a Proxy Protocol version 2 header (binary format).
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> ssl ca-certificate \<ca-certificate\>
+
+Use SSL encryption for backend requests and authenticate the backend
+against ``<ca-certificate>``.
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> ssl no-verify
+
+Use SSL encryption for backend requests without validating the server
+certificate.
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> http-response-headers \<header-name\> value \<header-value\>
+
+Set custom HTTP headers to include in all responses from the backend.
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> logging facility \<facility\> level \<level\>
+
+Specify facility and level for logging.
+For an explanation on {ref}`syslog_facilities` and
+{ref}`syslog_severity_level`,
+see tables in the syslog configuration section.
+```
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> timeout check \<seconds\>
+
+Set the timeout in seconds for established connections.
+Value range 1-3600 seconds.
+```
+```{cfgcmd} set load-balancing haproxy backend \<name\> timeout connect \<seconds\>
+
+Set the maximum time to wait for a connection attempt to a server to succeed.
+Value range 1-3600 seconds.
+```
+
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> timeout server \<seconds\>
+
+Set the maximum inactivity time on the server side.
+Value range 1-3600 seconds.
+```
+
+### Global
+
+Global configuration parameters:
+
+```{cfgcmd} set load-balancing haproxy global-parameters max-connections \<num\>
+
+Limit maximum number of connections
+```
+
+
+```{cfgcmd} set load-balancing haproxy global-parameters ssl-bind-ciphers \<ciphers\>
+
+Limit the cipher algorithms allowed during SSL/TLS handshake.
+```
+
+
+```{cfgcmd} set load-balancing haproxy global-parameters tls-version-min \<version\>
+
+Specify the minimum required TLS version 1.2 or 1.3
+```
+
+
+```{cfgcmd} set load-balancing haproxy global-parameters logging facility \<facility\> level \<level\>
+
+Specify facility and level for logging.
+For an explanation on {ref}`syslog_facilities` and
+{ref}`syslog_severity_level`,
+see tables in the syslog configuration section.
+```
+
+
+```{cfgcmd} set load-balancing haproxy timeout check \<seconds\>
+
+Set the timeout in seconds for established connections.
+Value range 1-3600 seconds. Default is 5 seconds.
+```
+
+
+```{cfgcmd} set load-balancing haproxy timeout client \<seconds\>
+
+Set the maximum inactivity time on the client side.
+Value range 1-3600 seconds. Default is 50 seconds.
+```
+
+
+```{cfgcmd} set load-balancing haproxy timeout connect \<seconds\>
+
+Set the maximum time to wait for a connection attempt to a server to succeed.
+Value range 1-3600 seconds. Default is 10 seconds.
+```
+
+
+```{cfgcmd} set load-balancing haproxy timeout server \<seconds\>
+
+Set the maximum inactivity time on the server side.
+Value range 1-3600 seconds. Default is 50 seconds.
+```
+
+## Health checks
+
+
+### HTTP checks
+
+
+Use HTTP health checks to monitor web applications that provide health status
+information and determine their availability.
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> http-check
+
+Enables HTTP health checks using OPTION HTTP requests against '/' and
+expecting a successful response code in the 200-399 range.
+```
+
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> http-check method \<method\>
+
+Set the HTTP method: ``OPTION``, ``GET``, ``POST``, or ``PUT``.
+```
+
+
+```{cfgcmd} set load-balancing haproxy backend \<name\> http-check uri \<path\>
+
+Set the endpoint to use for health checks.
+```
+
+
+````{cfgcmd} set load-balancing haproxy backend \<name\> http-check expect \<condition\>
+
+Set the expected result condition for a server to be considered healthy.
+
+```{eval-rst}
+Some possible examples are:
+ * ``status 200`` Expecting a 200 response code
+ * ``status 200-399`` Expecting a non-failure response code
+ * ``string success`` Expecting the string success in the response body
+```
+````
+
+### TCP checks
+
+Configure health checks for TCP mode backends. You can configure protocol-aware
+checks for a range of Layer 7 protocols:
+
+````{cfgcmd} set load-balancing haproxy backend \<name\> health-check \<protocol\>
+
+```{eval-rst}
+Available health check protocols:
+ * ``ldap`` LDAP protocol check.
+ * ``redis`` Redis protocol check.
+ * ``mysql`` MySQL protocol check.
+ * ``pgsql`` PostgreSQL protocol check.
+ * ``smtp`` SMTP protocol check.
+```
+````
+
+:::{note}
+If you specify a server to check but do not configure a
+protocol, HAProxy performs a basic TCP health check. A server is online if
+it responds to a connection attempt with a valid `SYN/ACK` packet.
+:::
+## Redirect HTTP to HTTPS
+
+Configure a HAProxy service for HTTP that listens on port 80 and redirects
+incoming requests to HTTPS:
+
+```none
+set load-balancing haproxy service http port '80'
+set load-balancing haproxy service http redirect-http-to-https
+```
+
+You can use a different service name; in this example, `http` is just for
+convenience.
+
+## Examples
+### Level 4 balancing
+
+This configuration enables the TCP reverse proxy for the `my-tcp-api`
+service. Incoming TCP connections on port 8888 are load balanced across the
+backend servers (srv01 and srv02) using the round-robin load balancing
+algorithm.
+
+```none
+set load-balancing haproxy service my-tcp-api backend 'bk-01'
+set load-balancing haproxy service my-tcp-api mode 'tcp'
+set load-balancing haproxy service my-tcp-api port '8888'
+
+set load-balancing haproxy backend bk-01 balance 'round-robin'
+set load-balancing haproxy backend bk-01 mode 'tcp'
+
+set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11'
+set load-balancing haproxy backend bk-01 server srv01 port '8881'
+set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12'
+set load-balancing haproxy backend bk-01 server srv02 port '8882'
+```
+
+### Balancing based on domain name
+
+The following configuration demonstrates how to use VyOS
+to achieve load balancing based on the domain name:
+
+The HTTP service listens on TCP port 80.
+
+Rule 10 matches requests with the domain name `node1.example.com` and
+forwards them to the backend `bk-api-01`.
+
+Rule 20 matches requests with the domain name `node2.example.com` and
+forwards them to the backend `bk-api-02`.
+
+```none
+set load-balancing haproxy service http description 'bind app listen on 443 port'
+set load-balancing haproxy service http mode 'tcp'
+set load-balancing haproxy service http port '80'
+
+set load-balancing haproxy service http rule 10 domain-name 'node1.example.com'
+set load-balancing haproxy service http rule 10 set backend 'bk-api-01'
+set load-balancing haproxy service http rule 20 domain-name 'node2.example.com'
+set load-balancing haproxy service http rule 20 set backend 'bk-api-02'
+
+set load-balancing haproxy backend bk-api-01 description 'My API-1'
+set load-balancing haproxy backend bk-api-01 mode 'tcp'
+set load-balancing haproxy backend bk-api-01 server api01 address '127.0.0.1'
+set load-balancing haproxy backend bk-api-01 server api01 port '4431'
+set load-balancing haproxy backend bk-api-02 description 'My API-2'
+set load-balancing haproxy backend bk-api-02 mode 'tcp'
+set load-balancing haproxy backend bk-api-02 server api01 address '127.0.0.2'
+set load-balancing haproxy backend bk-api-02 server api01 port '4432'
+```
+
+### Terminate SSL
+
+The following configuration terminates SSL on the router.
+
+The `http` service listens on port 80 and redirects HTTP requests to
+HTTPS.
+
+The `https` service listens on port 443 with the `bk-default` backend
+and handles HTTPS traffic using the `cert` certificate for SSL termination.
+The HSTS header is set with a 1-year expiry to tell browsers to always use
+SSL for the site.
+
+Rule 10 matches requests with the exact URL path `/.well-known/xxx` and
+redirects them to `/certs/`.
+
+Rule 20 matches requests with URL paths ending in `/mail` or the exact
+path `/email/bar` and redirects them to `/postfix/`.
+
+Global parameters include a maximum connection limit of 4000 and a minimum
+TLS version of 1.3.
+
+```none
+set load-balancing haproxy service http description 'Force redirect to HTTPS'
+set load-balancing haproxy service http port '80'
+set load-balancing haproxy service http redirect-http-to-https
+
+set load-balancing haproxy service https backend 'bk-default'
+set load-balancing haproxy service https description 'listen on 443 port'
+set load-balancing haproxy service https mode 'http'
+set load-balancing haproxy service https port '443'
+set load-balancing haproxy service https ssl certificate 'cert'
+set load-balancing haproxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000'
+
+set load-balancing haproxy service https rule 10 url-path exact '/.well-known/xxx'
+set load-balancing haproxy service https rule 10 set redirect-location '/certs/'
+set load-balancing haproxy service https rule 20 url-path end '/mail'
+set load-balancing haproxy service https rule 20 url-path exact '/email/bar'
+set load-balancing haproxy service https rule 20 set redirect-location '/postfix/'
+
+set load-balancing haproxy backend bk-default description 'Default backend'
+set load-balancing haproxy backend bk-default mode 'http'
+set load-balancing haproxy backend bk-default server sr01 address '192.0.2.23'
+set load-balancing haproxy backend bk-default server sr01 port '80'
+
+set load-balancing haproxy global-parameters max-connections '4000'
+set load-balancing haproxy global-parameters tls-version-min '1.3'
+```
+
+### SSL Bridging
+
+The following configuration terminates incoming HTTPS traffic on the router,
+then re-encrypts the traffic and sends it to the backend server via HTTPS.
+Use this when encryption is required for both paths but you do not want to
+install publicly trusted certificates on each backend server.
+
+Backend service certificates are checked against the certificate authority
+specified in the configuration, which could be an internal CA.
+
+The `https` service listens on port 443 with backend `bk-bridge-ssl` to
+handle HTTPS traffic. It uses certificate named `cert` for SSL termination.
+
+The `bk-bridge-ssl` backend connects to `sr01` server on port 443 via HTTPS
+and checks backend server has a valid certificate trusted by CA `cacert`
+
+```none
+set load-balancing haproxy service https backend 'bk-bridge-ssl'
+set load-balancing haproxy service https description 'listen on 443 port'
+set load-balancing haproxy service https mode 'http'
+set load-balancing haproxy service https port '443'
+set load-balancing haproxy service https ssl certificate 'cert'
+
+set load-balancing haproxy backend bk-bridge-ssl description 'SSL backend'
+set load-balancing haproxy backend bk-bridge-ssl mode 'http'
+set load-balancing haproxy backend bk-bridge-ssl ssl ca-certificate 'cacert'
+set load-balancing haproxy backend bk-bridge-ssl server sr01 address '192.0.2.23'
+set load-balancing haproxy backend bk-bridge-ssl server sr01 port '443'
+```
+
+### Balancing with HTTP health checks
+
+This configuration enables HTTP health checks for backend servers.
+
+```none
+set load-balancing haproxy service my-tcp-api backend 'bk-01'
+set load-balancing haproxy service my-tcp-api mode 'tcp'
+set load-balancing haproxy service my-tcp-api port '8888'
+
+set load-balancing haproxy backend bk-01 balance 'round-robin'
+set load-balancing haproxy backend bk-01 mode 'tcp'
+
+set load-balancing haproxy backend bk-01 http-check method 'get'
+set load-balancing haproxy backend bk-01 http-check uri '/health'
+set load-balancing haproxy backend bk-01 http-check expect 'status 200'
+
+set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11'
+set load-balancing haproxy backend bk-01 server srv01 port '8881'
+set load-balancing haproxy backend bk-01 server srv01 check
+set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12'
+set load-balancing haproxy backend bk-01 server srv02 port '8882'
+set load-balancing haproxy backend bk-01 server srv02 check port '8892'
+```
diff --git a/docs/configuration/loadbalancing/index.md b/docs/configuration/loadbalancing/index.md
new file mode 100644
index 00000000..3241edb7
--- /dev/null
+++ b/docs/configuration/loadbalancing/index.md
@@ -0,0 +1,15 @@
+---
+lastproofread: '2026-04-06'
+---
+
+(load-balancing)=
+
+# Load-balancing
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+wan
+haproxy
+```
diff --git a/docs/configuration/loadbalancing/wan.md b/docs/configuration/loadbalancing/wan.md
new file mode 100644
index 00000000..a19bbfae
--- /dev/null
+++ b/docs/configuration/loadbalancing/wan.md
@@ -0,0 +1,306 @@
+---
+lastproofread: '2026-04-06'
+---
+
+# WAN load balancing
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+The load balancer distributes outbound traffic across two or more
+interfaces. If a path fails, the load balancer balances traffic across the
+remaining healthy paths. When a path recovers, it is automatically added back
+to the routing table. The load balancer adds routes for each path and
+distributes traffic based on interface health and weight.
+
+In a minimal configuration, the following must be provided:
+> - An interface with a `nexthop`.
+> - One rule with a LAN (inbound-interface) and the WAN (interface).
+
+The following examples uses two DHCP WAN interfaces and one LAN (`eth2`):
+
+```none
+set load-balancing wan interface-health eth0 nexthop 'dhcp'
+set load-balancing wan interface-health eth1 nexthop 'dhcp'
+set load-balancing wan rule 1 inbound-interface 'eth2'
+set load-balancing wan rule 1 interface eth0
+set load-balancing wan rule 1 interface eth1
+```
+
+:::{note}
+Do not use WAN load balancing with dynamic routing protocols. This
+feature creates customized routing tables and firewall rules that are
+incompatible with routing protocols.
+:::
+
+## Load balancing rules
+
+You define interfaces, their weight, and the traffic type to balance in
+numbered rule sets. The load balancer executes rules in numerical order
+against outgoing packets. When a packet matches a rule, it is sent through the
+specified interface. Packets that do not match any rule use the system routing
+table. You cannot change rule numbers.
+
+Create a load balancing rule, it can be a number between 1 and 9999:
+
+```none
+vyos@vyos# set load-balancing wan rule 1
+Possible completions:
+description             Description for this rule
+> destination           Destination
+exclude                 Exclude packets matching this rule from wan load balance
+failover                Enable failover for packets matching this rule from wan load balance
+inbound-interface       Inbound interface name (e.g., "eth0") [REQUIRED]
++> interface            Interface name [REQUIRED]
+> limit                 Enable packet limit for this rule
+per-packet-balancing    Option to match traffic per-packet instead of the default, per-flow
+protocol                Protocol to match
+> source                Source information
+```
+
+
+### Interface weight
+
+By default, the load balancer distributes outbound
+traffic randomly across available interfaces. You can assign weights to
+interfaces to influence the distribution. If `eth0` has more bandwidth
+than `eth1`, you can assign a higher weight to `eth0` to send more
+traffic through it:
+
+```none
+set load-balancing wan rule 1 interface eth0 weight 2
+set load-balancing wan rule 1 interface eth1 weight 1
+```
+
+In this example,\`\`eth0\`\` receives 66% of traffic, and `eth1` receives
+33% of traffic.
+
+### Rate limit
+
+Set a packet rate limit for a rule to apply it to traffic above or below a
+specified threshold. To configure rate limiting, use:
+
+```none
+set load-balancing wan rule <rule> limit <parameter>
+```
+
+- `burst`: Number of packets allowed to overshoot the limit within `period`.
+  Default 5.
+- `period`: Time window for rate calculation. Possible values:
+  `second` (one second), `minute` (one minute), `hour` (one hour).
+  Default is `second`.
+- `rate`: Number of packets. Default: `5`.
+- `threshold`: `below` or `above` the specified rate limit.
+
+### Flow and packet-based balancing
+
+The load balancer balances outgoing traffic by flow. A connection tracking
+table tracks flows by source address, destination address, and port. Each
+flow is assigned to an interface based on the balancing rules, and subsequent
+packets use the same interface. This ensures packets arrive in order when links
+have different speeds.
+
+Packet-based balancing can improve balance across interfaces when packet
+order is not critical. Enable per-packet balancing for a rule with:
+
+```none
+set load-balancing wan rule <rule> per-packet-balancing
+```
+
+
+### Exclude traffic
+
+To exclude traffic from load balancing, traffic matching an exclude rule
+bypasses load balancing and uses the system routing table instead:
+
+```none
+set load-balancing wan rule <rule> exclude
+```
+
+
+## Health checks
+
+The load balancer periodically checks the health of interfaces and paths by
+sending ICMP packets (ping) to remote destinations, performing TTL tests, or
+executing a user-defined script. If an interface fails the health check, the
+load balancer removes it from its interface pool.
+To enable health checking for an interface:
+
+```none
+vyos@vyos# set load-balancing wan interface-health <interface>
+Possible completions:
+failure-count    Failure count
+nexthop          Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED]
+success-count    Success count
++> test          Rule number
+```
+
+Specify the nexthop on the path to the destination. You can set
+`ipv4-address` to `dhcp`.
+
+```none
+set load-balancing wan interface-health <interface> nexthop <ipv4-address>
+```
+
+Set the number of health check failures before the load balancer marks an
+interface as unavailable (range 1-10, default 1). Or set the number of
+successful health checks before adding an interface back to the pool
+(range 1-10, default 1).
+
+```none
+set load-balancing wan interface-health <interface> failure-count <number>
+set load-balancing wan interface-health <interface> success-count <number>
+```
+
+Configure each health check in its own test. Tests are numbered and processed
+in numeric order. You can define multiple tests for multi-target health
+checking:
+
+```none
+vyos@vyos# set load-balancing wan interface-health eth1 test 0
+Possible completions:
+resp-time    Ping response time (seconds)
+target       Health target address
+test-script  Path to user defined script
+ttl-limit    Ttl limit (hop count)
+type         WLB test type
+```
+
+- `resp-time`: The maximum response time for ping in seconds. Range
+  1-30, default `5`.
+- `target`: The target to receive ICMP packets. The address can be an IPv4
+  address or hostname.
+- `test-script`: A user-defined script must return 0 to succeed and
+  non-zero to fail. Scripts reside in `/config/scripts`. For other locations,
+  provide the full path.
+- `ttl-limit`: For the UDP TTL limit test, specify the hop count limit.
+  The limit must be shorter than the path length. The test succeeds when an
+  ICMP time-expired message is returned. Default `1`.
+- `type`: Specify the test type: `ping`, `ttl`, or a user-defined
+  script.
+
+## Source NAT rules
+
+By default, interfaces in a load balancing pool replace the source IP of
+each outgoing packet with their own address to ensure replies arrive on the
+same interface. The load balancer handles this through automatically generated
+Source NAT (SNAT) rules applied only to balanced traffic. To disable the
+automatic generation of SNAT rules when this behavior is not desired, use:
+
+```none
+set load-balancing wan disable-source-nat
+```
+
+
+## Sticky connections
+
+Inbound connections to a WAN interface can be improperly handled when
+replies are sent back to the client.
+
+```{image} /_static/images/sticky-connections.webp
+:align: center
+:width: 80%
+```
+
+When responding to an incoming packet, you may want to ensure the response
+leaves from the same interface as the incoming packet. Enable sticky
+connections in the load balancer to do this:
+
+```none
+set load-balancing wan sticky-connections inbound
+```
+
+
+## Failover
+
+In failover mode, one interface is primary and other interfaces are
+secondary or spare. The load balancer uses only the primary interface. If it
+fails, a secondary interface from the available pool takes over. The load
+balancer selects the primary interface based on its weight and health. Other
+interfaces become secondary. Secondary interfaces are chosen based on their
+weight and health. You can also select interface roles based on rule order by
+including interfaces in balancing rules and ordering those rules accordingly.
+To enable failover mode, create a failover rule:
+
+```none
+set load-balancing wan rule <number> failover
+```
+
+Existing sessions do not automatically fail over to a new path. Flush the
+session table on each connection state change to enable failover:
+
+```none
+set load-balancing wan flush-connections
+```
+
+:::{warning}
+Flushing the session table causes other connections to revert from
+flow-based to packet-based balancing until each flow is reestablished.
+:::
+
+## Script execution
+
+Run a script when an interface state changes. Scripts run from the
+`/config/scripts` directory. To use a script in another location,
+specify the full path:
+
+```none
+set load-balancing wan hook script-name
+```
+
+Two environment variables are available:
+- `WLB_INTERFACE_NAME=[interfacename]`: Interface to be monitored
+- `WLB_INTERFACE_STATE=[ACTIVE|FAILED]`: Interface state
+
+:::{warning}
+Blocking call with no timeout: VyOS becomes unresponsive if the
+script does not return.
+:::
+
+## Handling and monitoring
+
+The following command shows WAN load balancer information including test
+types and targets. The character at the start of each line indicates the test
+state:
+- `+` successful.
+- `-` failed.
+- A blank indicates that no test has been carried out.
+
+```none
+vyos@vyos:~$ show wan-load-balance
+Interface:  eth0
+Status:  failed
+Last Status Change:  Tue Jun 11 20:12:19 2019
+-Test:  ping  Target:
+    Last Interface Success:  55s
+    Last Interface Failure:  0s
+    # Interface Failure(s):  5
+
+Interface:  eth1
+Status:  active
+Last Status Change:  Tue Jun 11 20:06:42 2019
++Test:  ping  Target:
+    Last Interface Success:  0s
+    Last Interface Failure:  6m26s
+    # Interface Failure(s):  0
+```
+
+Show connection data of load balanced traffic:
+
+```none
+vyos@vyos:~$ show wan-load-balance connection
+conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown.
+Type    State           Src                     Dst                     Packets Bytes
+tcp     TIME_WAIT       10.1.1.13:38040         203.0.113.2:80          203.0.113.2  192.168.188.71
+udp                     10.1.1.13:41891         198.51.100.3:53         198.51.100.3 192.168.188.71
+udp                     10.1.1.13:55437         198.51.100.3:53         198.51.100.3 192.168.188.71
+```
+
+
+### Restart
+
+```none
+restart wan-load-balance
+```
diff --git a/docs/configuration/nat/cgnat.md b/docs/configuration/nat/cgnat.md
new file mode 100644
index 00000000..914a466b
--- /dev/null
+++ b/docs/configuration/nat/cgnat.md
@@ -0,0 +1,200 @@
+(cgnat)=
+
+# CGNAT
+
+{abbr}`CGNAT (Carrier-Grade Network Address Translation)` , also known as
+Large-Scale NAT (LSN), is a type of network address translation used by
+Internet Service Providers (ISPs) to enable multiple private IP addresses to
+share a single public IP address. This technique helps to conserve the limited
+IPv4 address space.
+The 100.64.0.0/10 address block is reserved for use in carrier-grade NAT
+
+## Overview
+
+CGNAT works by placing a NAT device within the ISP's network. This device
+translates private IP addresses from customer networks to a limited pool of
+public IP addresses assigned to the ISP. This allows many customers to share a
+smaller number of public IP addresses.
+
+Not all {rfc}`6888` requirements are implemented in CGNAT.
+
+Implemented the following {rfc}`6888` requirements:
+
+- REQ 2: A CGN must have a default "IP address pooling" behavior of "Paired".
+  CGN must use the same external IP address mapping for all sessions associated
+  with the same internal IP address, be they TCP, UDP, ICMP, something else,
+  or a mix of different protocols.
+- REQ 3: The CGN function should not have any limitations on the size or the
+  contiguity of the external address pool.
+- REQ 4: A CGN must support limiting the number of external ports (or,
+  equivalently, "identifiers" for ICMP) that are assigned per subscriber
+
+### Advantages of CGNAT
+
+- **IPv4 Address Conservation**: CGNAT helps mitigate the exhaustion of IPv4 addresses by allowing multiple customers to share a single public IP address.
+- **Scalability**: ISPs can support more customers without needing a proportional increase in public IP addresses.
+- **Cost-Effective**: Reduces the cost associated with acquiring additional public IPv4 addresses.
+
+### Considerations
+
+- **Traceability Issues**: Since multiple users share the same public IP address, tracking individual users for security and legal purposes can be challenging.
+- **Performance Overheads**: The translation process can introduce latency and potential performance bottlenecks, especially under high load.
+- **Application Compatibility**: Some applications and protocols may not work well with CGNAT due to their reliance on unique public IP addresses.
+- **Port Allocation Limits**: Each public IP address has a limited number of ports, which can be exhausted, affecting the ability to establish new connections.
+- **Port Control Protocol**: PCP is not implemented.
+
+## Port calculation
+
+When implementing CGNAT, ensuring that there are enough ports allocated per subscriber is critical. Below is a summary based on RFC 6888.
+
+1. **Total Ports Available**:
+
+   - Total Ports: 65536 (0 to 65535)
+   - Reserved Ports: Assume 1024 ports are reserved for well-known services and administrative purposes.
+   - Usable Ports: 65536 - 1024 = 64512
+
+2. **Estimate Ports Needed per Subscriber**:
+
+   - Example: A household might need 1000 ports to ensure smooth operation for multiple devices and applications.
+
+3. **Calculate the Number of Subscribers per Public IP**:
+
+   - Usable Ports / Ports per Subscriber
+   - 64512 / 1000 ≈ 64 subscribers per public IP
+
+## Configuration
+
+```{cfgcmd} set nat cgnat pool external \<pool-name\> external-port-range \<port-range\>
+
+Set an external port-range for the external pool, the default range is
+1024-65535. Multiple entries can be added to the same pool.
+```
+
+
+```{cfgcmd} set nat cgnat pool external \<pool-name\> per-user-limit port \<num\>
+
+Set external source port limits that will be allocated to each subscriber
+individually. The default value is 2000.
+```
+
+
+```{cfgcmd} set nat cgnat pool external \<pool-name\> range [address | address range | network] [seq]
+
+Set the range of external IP addresses for the CGNAT pool.
+The sequence is optional; if set, a lower value means higher priority.
+```
+
+
+```{cfgcmd} set nat cgnat pool internal \<pool-name\> range [address range | network]
+
+Set the range of internal IP addresses for the CGNAT pool.
+```
+
+
+```{cfgcmd} set nat cgnat rule \<num\> source pool \<internal-pool-name\>
+
+Set the rule for the source pool.
+```
+
+
+```{cfgcmd} set nat cgnat rule \<num\> translation pool \<external-pool-name\>
+
+Set the rule for the translation pool.
+```
+
+
+```{cfgcmd} set nat cgnat log-allocation
+
+Enable logging of IP address and ports allocations.
+```
+
+
+## Configuration Examples
+
+### Single external address
+
+Example of setting up a basic CGNAT configuration:
+In the following example, we define an external pool named `ext-1` with one
+external IP address.
+
+Each subscriber will be allocated a maximum of 2000 ports from the external pool.
+
+```none
+set nat cgnat pool external ext1 external-port-range '1024-65535'
+set nat cgnat pool external ext1 per-user-limit port '2000'
+set nat cgnat pool external ext1 range '192.0.2.222/32'
+set nat cgnat pool internal int1 range '100.64.0.0/28'
+set nat cgnat rule 10 source pool 'int1'
+set nat cgnat rule 10 translation pool 'ext1'
+```
+
+
+### Multiple external addresses
+
+```none
+set nat cgnat pool external ext1 external-port-range '1024-65535'
+set nat cgnat pool external ext1 per-user-limit port '8000'
+set nat cgnat pool external ext1 range '192.0.2.1-192.0.2.2'
+set nat cgnat pool external ext1 range '203.0.113.253-203.0.113.254'
+set nat cgnat pool internal int1 range '100.64.0.1-100.64.0.32'
+set nat cgnat rule 10 source pool 'int1'
+set nat cgnat rule 10 translation pool 'ext1'
+```
+
+
+### External address sequences
+
+```none
+set nat cgnat pool external ext-01 per-user-limit port '16000'
+set nat cgnat pool external ext-01 range 203.0.113.1/32 seq '10'
+set nat cgnat pool external ext-01 range 192.0.2.1/32 seq '20'
+set nat cgnat pool internal int-01 range '100.64.0.0/29'
+set nat cgnat rule 10 source pool 'int-01'
+set nat cgnat rule 10 translation pool 'ext-01'
+```
+
+
+## Operation commands
+
+```{opcmd} show nat cgnat allocation
+
+Show address and port allocations
+```
+
+```{opcmd} show nat cgnat allocation external-address \<address\>
+
+Show all allocations for an external IP address
+```
+
+```{opcmd} show nat cgnat allocation internal-address \<address\>
+
+Show all allocations for an internal IP address
+```
+
+
+### Show CGNAT allocations
+
+```none
+vyos@vyos:~$ show nat cgnat allocation
+Internal IP    External IP    Port range
+-------------  -------------  ------------
+100.64.0.0     203.0.113.1    1024-17023
+100.64.0.1     203.0.113.1    17024-33023
+100.64.0.2     203.0.113.1    33024-49023
+100.64.0.3     203.0.113.1    49024-65023
+100.64.0.4     192.0.2.1      1024-17023
+100.64.0.5     192.0.2.1      17024-33023
+100.64.0.6     192.0.2.1      33024-49023
+100.64.0.7     192.0.2.1      49024-65023
+
+vyos@vyos:~$ show nat cgnat allocation internal-address 100.64.0.4
+Internal IP    External IP    Port range
+-------------  -------------  ------------
+100.64.0.4     192.0.2.1      1024-17023
+```
+
+
+## Further Reading
+
+- {rfc}`6598` - IANA-Reserved IPv4 Prefix for Shared Address Space
+- {rfc}`6888` - Requirements for CGNAT
diff --git a/docs/configuration/nat/index.md b/docs/configuration/nat/index.md
new file mode 100644
index 00000000..35e5d32b
--- /dev/null
+++ b/docs/configuration/nat/index.md
@@ -0,0 +1,13 @@
+(nat)=
+
+# NAT
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+nat44
+nat64
+nat66
+cgnat
+```
diff --git a/docs/configuration/nat/nat44.md b/docs/configuration/nat/nat44.md
new file mode 100644
index 00000000..4f5bd580
--- /dev/null
+++ b/docs/configuration/nat/nat44.md
@@ -0,0 +1,788 @@
+(nat44)=
+
+# NAT44
+
+{abbr}`NAT (Network Address Translation)` is a common method of
+remapping one IP address space into another by modifying network address
+information in the IP header of packets while they are in transit across
+a traffic routing device. The technique was originally used as a
+shortcut to avoid the need to readdress every host when a network was
+moved. It has become a popular and essential tool in conserving global
+address space in the face of IPv4 address exhaustion. One
+Internet-routable IP address of a NAT gateway can be used for an entire
+private network.
+
+IP masquerading is a technique that hides an entire IP address space,
+usually consisting of private IP addresses, behind a single IP address
+in another, usually public address space. The hidden addresses are
+changed into a single (public) IP address as the source address of the
+outgoing IP packets so they appear as originating not from the hidden
+host but from the routing device itself. Because of the popularity of
+this technique to conserve IPv4 address space, the term NAT has become
+virtually synonymous with IP masquerading.
+
+As network address translation modifies the IP address information in
+packets, NAT implementations may vary in their specific behavior in
+various addressing cases and their effect on network traffic. The
+specifics of NAT behavior are not commonly documented by vendors of
+equipment containing NAT implementations.
+
+The computers on an internal network can use any of the addresses set
+aside by the {abbr}`IANA (Internet Assigned Numbers Authority)` for
+private addressing (see {rfc}`1918`). These reserved IP addresses are
+not in use on the Internet, so an external machine will not directly
+route to them. The following addresses are reserved for private use:
+
+- 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8)
+- 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12)
+- 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16)
+
+If an ISP deploys a {abbr}`CGN (Carrier-grade NAT)`, and uses
+{rfc}`1918` address space to number customer gateways, the risk of
+address collision, and therefore routing failures, arises when the
+customer network already uses an {rfc}`1918` address space.
+
+This prompted some ISPs to develop a policy within the {abbr}`ARIN
+(American Registry for Internet Numbers)` to allocate new private
+address space for CGNs, but ARIN deferred to the IETF before
+implementing the policy indicating that the matter was not a typical
+allocation issue but a reservation of addresses for technical purposes
+(per {rfc}`2860`).
+
+IETF published {rfc}`6598`, detailing a shared address space for use in
+ISP CGN deployments that can handle the same network prefixes occurring
+both on inbound and outbound interfaces. ARIN returned address space to
+the {abbr}`IANA (Internet Assigned Numbers Authority)` for this
+allocation.
+
+The allocated address block is 100.64.0.0/10.
+
+Devices evaluating whether an IPv4 address is public must be updated to
+recognize the new address space. Allocating more private IPv4 address
+space for NAT devices might prolong the transition to IPv6.
+
+## Overview
+
+### Different NAT Types
+
+(source-nat)=
+
+#### SNAT
+
+{abbr}`SNAT (Source Network Address Translation)` is the most common
+form of {abbr}`NAT (Network Address Translation)` and is typically
+referred to simply as NAT. To be more correct, what most people refer
+to as {abbr}`NAT (Network Address Translation)` is actually the process
+of {abbr}`PAT (Port Address Translation)`, or NAT overload. SNAT is
+typically used by internal users/private hosts to access the Internet
+\- the source address is translated and thus kept private.
+
+(destination-nat)=
+
+#### DNAT
+
+{abbr}`DNAT (Destination Network Address Translation)` changes the
+destination address of packets passing through the router, while
+{ref}`source-nat` changes the source address of packets. DNAT is
+typically used when an external (public) host needs to initiate a
+session with an internal (private) host. A customer needs to access a
+private service behind the routers public IP. A connection is
+established with the routers public IP address on a well known port and
+thus all traffic for this port is rewritten to address the internal
+(private) host.
+
+(bidirectional-nat)=
+
+#### Bidirectional NAT
+
+This is a common scenario where both {ref}`source-nat` and
+{ref}`destination-nat` are configured at the same time. It's commonly
+used when internal (private) hosts need to establish a connection with
+external resources and external systems need to access internal
+(private) resources.
+
+### NAT, Routing, Firewall Interaction
+
+There is a very nice picture/explanation in the Vyatta documentation
+which should be rewritten here.
+
+### NAT Ruleset
+
+{abbr}`NAT (Network Address Translation)` is configured entirely on a
+series of so called *rules*. Rules are numbered and evaluated by the
+underlying OS in numerical order! The rule numbers can be changes by
+utilizing the {cfgcmd}`rename` and {cfgcmd}`copy` commands.
+
+:::{note}
+Changes to the NAT system only affect newly established
+connections. Already established connections are not affected.
+:::
+
+:::{hint}
+When designing your NAT ruleset leave some space between
+consecutive rules for later extension. Your ruleset could start with
+numbers 10, 20, 30. You thus can later extend the ruleset and place
+new rules between existing ones.
+:::
+
+Rules will be created for both {ref}`source-nat` and
+{ref}`destination-nat`.
+
+For {ref}`bidirectional-nat` a rule for both {ref}`source-nat` and
+{ref}`destination-nat` needs to be created.
+
+(traffic-filters)=
+
+### Traffic Filters
+
+Traffic Filters are used to control which packets will have the defined
+NAT rules applied. Five different filters can be applied within a NAT
+rule.
+
+- **outbound-interface** - applicable only to {ref}`source-nat`. It
+  configures the interface which is used for the outside traffic that
+  this translation rule applies to. Interface groups, inverted
+  selection and wildcard, are also supported.
+
+  Examples:
+
+  ```none
+  set nat source rule 20 outbound-interface name eth0
+  set nat source rule 30 outbound-interface name bond1*
+  set nat source rule 20 outbound-interface name !vtun2
+  set nat source rule 20 outbound-interface group GROUP1
+  set nat source rule 20 outbound-interface group !GROUP2
+  ```
+
+- **inbound-interface** - applicable only to {ref}`destination-nat`. It
+  configures the interface which is used for the inside traffic the
+  translation rule applies to. Interface groups, inverted
+  selection and wildcard, are also supported.
+
+  Example:
+
+  ```none
+  set nat destination rule 20 inbound-interface name eth0
+  set nat destination rule 30 inbound-interface name bond1*
+  set nat destination rule 20 inbound-interface name !vtun2
+  set nat destination rule 20 inbound-interface group GROUP1
+  set nat destination rule 20 inbound-interface group !GROUP2
+  ```
+
+- **protocol** - specify which types of protocols this translation rule
+  applies to. Only packets matching the specified protocol are NATed.
+  By default this applies to *all* protocols.
+
+  Example:
+
+  - Set SNAT rule 20 to only NAT TCP and UDP packets
+  - Set DNAT rule 20 to only NAT UDP packets
+
+  ```none
+  set nat source rule 20 protocol tcp_udp
+  set nat destination rule 20 protocol udp
+  ```
+
+- **source** - specifies which packets the NAT translation rule applies
+  to based on the packets source IP address and/or source port. Only
+  matching packets are considered for NAT.
+
+  Example:
+
+  - Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24
+    network
+  - Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.0/24
+    network with a source port of 80 and 443
+
+  ```none
+  set nat source rule 20 source address 192.0.2.0/24
+  set nat source rule 30 source address 203.0.113.0/24
+  set nat source rule 30 source port 80,443
+  ```
+
+- **destination** - specify which packets the translation will be
+  applied to, only based on the destination address and/or port number
+  configured.
+
+  :::{note}
+  If no destination is specified the rule will match on any
+  destination address and port.
+  :::
+
+  Example:
+
+  - Configure SNAT rule (40) to only NAT packets with a destination
+    address of 192.0.2.1.
+
+  ```none
+  set nat source rule 40 destination address 192.0.2.1
+  ```
+
+### Address Conversion
+
+Every NAT rule has a translation command defined. The address defined
+for the translation is the address used when the address information in
+a packet is replaced.
+
+#### Source Address
+
+For {ref}`source-nat` rules the packets source address will be replaced
+with the address specified in the translation command. A port
+translation can also be specified and is part of the translation
+address.
+
+:::{note}
+The translation address must be set to one of the available
+addresses on the configured *outbound-interface* or it must be set to
+*masquerade* which will use the primary IP address of the
+*outbound-interface* as its translation address.
+:::
+
+:::{note}
+When using NAT for a large number of host systems it
+recommended that a minimum of 1 IP address is used to NAT every 256
+private host systems. This is due to the limit of 65,000 port numbers
+available for unique translations and a reserving an average of
+200-300 sessions per host system.
+:::
+
+Example:
+
+- Define a discrete source IP address of 100.64.0.1 for SNAT rule 20
+- Use address *masquerade* (the interfaces primary address) on rule 30
+- For a large amount of private machines behind the NAT your address
+  pool might to be bigger. Use any address in the range 100.64.0.10 -
+  100.64.0.20 on SNAT rule 40 when doing the translation
+
+```none
+set nat source rule 20 translation address 100.64.0.1
+set nat source rule 30 translation address 'masquerade'
+set nat source rule 40 translation address 100.64.0.10-100.64.0.20
+```
+
+#### Destination Address
+
+For {ref}`destination-nat` rules the packets destination address will be
+replaced by the specified address in the *translation address* command.
+
+Example:
+
+- DNAT rule 10 replaces the destination address of an inbound packet
+  with 192.0.2.10
+
+```none
+set nat destination rule 10 translation address 192.0.2.10
+```
+
+Also, in {ref}`destination-nat`, redirection to localhost is supported.
+The redirect statement is a special form of dnat which always translates
+the destination address to the local host’s one.
+
+Example of redirection:
+
+```none
+set nat destination rule 10 translation redirect port 22
+```
+
+### NAT Load Balance
+
+Advanced configuration can be used in order to apply source or destination NAT,
+and within a single rule, be able to define multiple translated addresses,
+so NAT balances the translations among them.
+
+NAT Load Balance uses an algorithm that generates a hash and based on it, then
+it applies corresponding translation. This hash can be generated randomly, or
+can use data from the ip header: source-address, destination-address,
+source-port and/or destination-port. By default, it will generate the hash
+randomly.
+
+When defining the translated address, called `backends`, a `weight` must
+be configured. This lets the user define load balance distribution according
+to their needs. Them sum of all the weights defined for the backends should
+be equal to 100. In oder words, the weight defined for the backend is the
+percentage of the connections that will receive such backend.
+
+```{cfgcmd} set nat [source | destination] rule \<rule\> load-balance hash [source-address | destination-address | source-port | destination-port | random]
+```
+
+```{cfgcmd} set nat [source | destination] rule \<rule\> load-balance backend \<x.x.x.x\> weight \<1-100\>
+```
+
+## Configuration Examples
+
+To setup SNAT, we need to know:
+- The internal IP addresses we want to translate
+- The outgoing interface to perform the translation on
+- The external IP address to translate to
+
+In the example used for the Quick Start configuration above, we
+demonstrate the following configuration:
+
+```none
+set nat source rule 100 outbound-interface name 'eth0'
+set nat source rule 100 source address '192.168.0.0/24'
+set nat source rule 100 translation address 'masquerade'
+```
+
+Which generates the following configuration:
+
+```none
+rule 100 {
+    outbound-interface {
+        name eth0
+    }
+    source {
+        address 192.168.0.0/24
+    }
+    translation {
+        address masquerade
+    }
+}
+```
+
+In this example, we use **masquerade** as the translation address
+instead of an IP address. The **masquerade** target is effectively an
+alias to say "use whatever IP address is on the outgoing interface",
+rather than a statically configured IP address. This is useful if you
+use DHCP for your outgoing interface and do not know what the external
+address will be.
+
+When using NAT for a large number of host systems it recommended that a
+minimum of 1 IP address is used to NAT every 256 host systems. This is
+due to the limit of 65,000 port numbers available for unique
+translations and a reserving an average of 200-300 sessions per host
+system.
+
+Example: For an ~8,000 host network a source NAT pool of 32 IP addresses
+is recommended.
+
+A pool of addresses can be defined by using a hyphen between two IP
+addresses:
+
+```none
+set nat source rule 100 translation address '203.0.113.32-203.0.113.63'
+```
+
+(avoidng-leaky-nat)=
+
+### Avoiding "leaky" NAT
+
+Linux netfilter will not NAT traffic marked as INVALID. This often
+confuses people into thinking that Linux (or specifically VyOS) has a
+broken NAT implementation because non-NATed traffic is seen leaving an
+external interface. This is actually working as intended, and a packet
+capture of the "leaky" traffic should reveal that the traffic is either
+an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems
+after Linux netfilter considers the connection closed. The most common
+is the additional TCP RST some host implementations send after
+terminating a connection (which is implementation-specific).
+
+In other words, connection tracking has already observed the connection
+be closed and has transition the flow to INVALID to prevent attacks from
+attempting to reuse the connection.
+
+You can avoid the "leaky" behavior by using a firewall policy that drops
+"invalid" state packets.
+
+Having control over the matching of INVALID state traffic, e.g. the
+ability to selectively log, is an important troubleshooting tool for
+observing broken protocol behavior. For this reason, VyOS does not
+globally drop invalid state traffic, instead allowing the operator to
+make the determination on how the traffic is handled.
+
+(hairpin-nat-reflection)=
+
+### Hairpin NAT/NAT Reflection
+
+A typical problem with using NAT and hosting public servers is the
+ability for internal systems to reach an internal server using it's
+external IP address. The solution to this is usually the use of
+split-DNS to correctly point host systems to the internal address when
+requests are made internally. Because many smaller networks lack DNS
+infrastructure, a work-around is commonly deployed to facilitate the
+traffic by NATing the request from internal hosts to the source address
+of the internal interface on the firewall.
+
+This technique is commonly referred to as NAT Reflection or Hairpin NAT.
+
+Example:
+
+- Redirect Microsoft RDP traffic from the outside (WAN, external) world
+  via {ref}`destination-nat` in rule 100 to the internal, private host
+  192.0.2.40.
+- Redirect Microsoft RDP traffic from the internal (LAN, private)
+  network via {ref}`destination-nat` in rule 110 to the internal,
+  private host 192.0.2.40. We also need a {ref}`source-nat` rule 110 for
+  the reverse path of the traffic. The internal network 192.0.2.0/24 is
+  reachable via interface *eth0.10*.
+
+```none
+set nat destination rule 100 description 'Regular destination NAT from external'
+set nat destination rule 100 destination port '3389'
+set nat destination rule 100 inbound-interface name 'pppoe0'
+set nat destination rule 100 protocol 'tcp'
+set nat destination rule 100 translation address '192.0.2.40'
+
+set nat destination rule 110 description 'NAT Reflection: INSIDE'
+set nat destination rule 110 destination port '3389'
+set nat destination rule 110 inbound-interface name 'eth0.10'
+set nat destination rule 110 protocol 'tcp'
+set nat destination rule 110 translation address '192.0.2.40'
+
+set nat source rule 110 description 'NAT Reflection: INSIDE'
+set nat source rule 110 destination address '192.0.2.0/24'
+set nat source rule 110 outbound-interface name 'eth0.10'
+set nat source rule 110 protocol 'tcp'
+set nat source rule 110 source address '192.0.2.0/24'
+set nat source rule 110 translation address 'masquerade'
+```
+
+Which results in a configuration of:
+
+```none
+vyos@vyos# show nat
+ destination {
+     rule 100 {
+         description "Regular destination NAT from external"
+         destination {
+             port 3389
+         }
+         inbound-interface {
+             name pppoe0
+         }
+         protocol tcp
+         translation {
+             address 192.0.2.40
+         }
+     }
+     rule 110 {
+         description "NAT Reflection: INSIDE"
+         destination {
+             port 3389
+         }
+         inbound-interface {
+             name eth0.10
+         }
+         protocol tcp
+         translation {
+             address 192.0.2.40
+         }
+     }
+ }
+ source {
+     rule 110 {
+         description "NAT Reflection: INSIDE"
+         destination {
+             address 192.0.2.0/24
+         }
+         outbound-interface {
+             name eth0.10
+         }
+         protocol tcp
+         source {
+             address 192.0.2.0/24
+         }
+         translation {
+             address masquerade
+         }
+     }
+ }
+```
+
+### Destination NAT
+
+DNAT is typically referred to as a **Port Forward**. When using VyOS as
+a NAT router and firewall, a common configuration task is to redirect
+incoming traffic to a system behind the firewall.
+
+In this example, we will be using the example Quick Start configuration
+above as a starting point.
+
+To setup a destination NAT rule we need to gather:
+- The interface traffic will be coming in on;
+- The protocol and port we wish to forward;
+- The IP address of the internal system we wish to forward traffic to.
+
+In our example, we will be forwarding web server traffic to an internal
+web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol
+on port 80. For other common port numbers, see:
+<https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers>
+
+Our configuration commands would be:
+
+```none
+set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100'
+set nat destination rule 10 destination port '80'
+set nat destination rule 10 inbound-interface name 'eth0'
+set nat destination rule 10 protocol 'tcp'
+set nat destination rule 10 translation address '192.168.0.100'
+```
+
+Which would generate the following NAT destination configuration:
+
+```none
+nat {
+    destination {
+        rule 10 {
+            description "Port Forward: HTTP to 192.168.0.100"
+            destination {
+                port 80
+            }
+            inbound-interface {
+                name eth0
+            }
+            protocol tcp
+            translation {
+                address 192.168.0.100
+            }
+        }
+    }
+}
+```
+:::{note}
+If forwarding traffic to a different port than it is arriving
+on, you may also configure the translation port using
+*set nat destination rule [n] translation port*.
+:::
+
+This establishes our Port Forward rule, but if we created a firewall
+policy it will likely block the traffic.
+
+#### Firewall rules for Destination NAT
+
+It is important to note that when creating firewall rules, the DNAT
+translation occurs **before** traffic traverses the firewall. In other
+words, the destination address has already been translated to
+192.168.0.100.
+
+So in our firewall ruleset, we want to allow traffic which previously matched
+a destination nat rule. In order to avoid creating many rules, one for each
+destination nat rule, we can accept all **'dnat'** connections with one simple
+rule, using `connection-status` matcher:
+
+```none
+set firewall ipv4 forward filter rule 10 action accept
+set firewall ipv4 forward filter rule 10 connection-status nat destination
+set firewall ipv4 forward filter rule 10 state new
+```
+
+This would generate the following configuration:
+
+```none
+ipv4 {
+    forward {
+        filter {
+            rule 10 {
+                action accept
+                connection-status {
+                    nat destination
+                }
+                state new
+            }
+        }
+    }
+}
+```
+
+### 1-to-1 NAT
+
+Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT
+configuration, both DNAT and SNAT are used to NAT all traffic from an
+external IP address to an internal IP address and vice-versa.
+
+Typically, a 1-to-1 NAT rule omits the destination port (all ports) and
+replaces the protocol with either **all** or **ip**.
+
+Then a corresponding SNAT rule is created to NAT outgoing traffic for
+the internal IP to a reserved external IP. This dedicates an external IP
+address to an internal IP address and is useful for protocols which
+don't have the notion of ports, such as GRE.
+
+Here's an extract of a simple 1-to-1 NAT configuration with one internal
+and one external interface:
+
+```none
+set interfaces ethernet eth0 address '192.168.1.1/24'
+set interfaces ethernet eth0 description 'Inside interface'
+set interfaces ethernet eth1 address '192.0.2.30/24'
+set interfaces ethernet eth1 description 'Outside interface'
+set nat destination rule 2000 description '1-to-1 NAT example'
+set nat destination rule 2000 destination address '192.0.2.30'
+set nat destination rule 2000 inbound-interface name 'eth1'
+set nat destination rule 2000 translation address '192.168.1.10'
+set nat source rule 2000 description '1-to-1 NAT example'
+set nat source rule 2000 outbound-interface name 'eth1'
+set nat source rule 2000 source address '192.168.1.10'
+set nat source rule 2000 translation address '192.0.2.30'
+```
+
+Firewall rules are written as normal, using the internal IP address as
+the source of outbound rules and the destination of inbound rules.
+
+### NAT before VPN
+
+Some application service providers (ASPs) operate a VPN gateway to
+provide access to their internal resources, and require that a
+connecting organisation translate all traffic to the service provider
+network to a source address provided by the ASP.
+
+### Load Balance
+
+Here we provide two examples on how to apply NAT Load Balance.
+
+First scenario: apply destination NAT for all HTTP traffic comming through
+interface eth0, and user 4 backends. First backend should received 30% of
+the request, second backend should get 20%, third 15% and the fourth 35%
+We will use source and destination address for hash generation.
+
+```none
+set nat destination rule 10 inbound-interface name eth0
+set nat destination rule 10 protocol tcp
+set nat destination rule 10 destination port 80
+set nat destination rule 10 load-balance hash source-address
+set nat destination rule 10 load-balance hash destination-address
+set nat destination rule 10 load-balance backend 198.51.100.101 weight 30
+set nat destination rule 10 load-balance backend 198.51.100.102 weight 20
+set nat destination rule 10 load-balance backend 198.51.100.103 weight 15
+set nat destination rule 10 load-balance backend 198.51.100.104 weight 35
+```
+
+Second scenario: apply source NAT for all outgoing connections from
+LAN 10.0.0.0/8, using 3 public addresses and equal distribution.
+We will generate the hash randomly.
+
+```none
+set nat source rule 10 outbound-interface name eth0
+set nat source rule 10 source address 10.0.0.0/8
+set nat source rule 10 load-balance hash random
+set nat source rule 10 load-balance backend 192.0.2.251 weight 33
+set nat source rule 10 load-balance backend 192.0.2.252 weight 33
+set nat source rule 10 load-balance backend 192.0.2.253 weight 34
+```
+
+#### Example Network
+
+Here's one example of a network environment for an ASP.
+The ASP requests that all connections from this company should come from
+172.29.41.89 - an address that is assigned by the ASP and not in use at
+the customer site.
+
+```{eval-rst}
+.. figure:: /_static/images/nat_before_vpn_topology.webp
+   :scale: 100 %
+   :alt: NAT before VPN Topology
+
+   NAT before VPN Topology
+```
+#### Configuration
+
+The required configuration can be broken down into 4 major pieces:
+- A dummy interface for the provider-assigned IP;
+- NAT (specifically, Source NAT);
+- IPSec IKE and ESP Groups;
+- IPSec VPN tunnels.
+
+##### Dummy interface
+
+The dummy interface allows us to have an equivalent of the Cisco IOS
+Loopback interface - a router-internal interface we can use for IP
+addresses the router must know about, but which are not actually
+assigned to a real network.
+
+We only need a single step for this interface:
+
+```none
+set interfaces dummy dum0 address '172.29.41.89/32'
+```
+
+##### NAT Configuration
+
+```none
+set nat source rule 110 description 'Internal to ASP'
+set nat source rule 110 destination address '172.27.1.0/24'
+set nat source rule 110 source address '192.168.43.0/24'
+set nat source rule 110 translation address '172.29.41.89'
+set nat source rule 120 description 'Internal to ASP'
+set nat source rule 120 destination address '10.125.0.0/16'
+set nat source rule 120 source address '192.168.43.0/24'
+set nat source rule 120 translation address '172.29.41.89'
+```
+
+##### IPSec IKE and ESP
+
+The ASP has documented their IPSec requirements:
+- IKE Phase:
+  - aes256 Encryption
+  - sha256 Hashes
+- ESP Phase:
+  - aes256 Encryption
+  - sha256 Hashes
+  - DH Group 14
+
+Additionally, we want to use VPNs only on our eth1 interface (the
+external interface in the image above)
+
+```none
+set vpn ipsec ike-group my-ike key-exchange 'ikev1'
+set vpn ipsec ike-group my-ike lifetime '7800'
+set vpn ipsec ike-group my-ike proposal 1 dh-group '14'
+set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256'
+set vpn ipsec ike-group my-ike proposal 1 hash 'sha256'
+
+set vpn ipsec esp-group my-esp lifetime '3600'
+set vpn ipsec esp-group my-esp mode 'tunnel'
+set vpn ipsec esp-group my-esp pfs 'disable'
+set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256'
+set vpn ipsec esp-group my-esp proposal 1 hash 'sha256'
+
+set vpn ipsec interface 'eth1'
+```
+
+##### IPSec VPN Tunnels
+
+We'll use the IKE and ESP groups created above for this VPN. Because we
+need access to 2 different subnets on the far side, we will need two
+different tunnels. If you changed the names of the ESP group and IKE
+group in the previous step, make sure you use the correct names here
+too.
+
+```none
+set vpn ipsec authentication psk vyos id '203.0.113.46'
+set vpn ipsec authentication psk vyos id '198.51.100.243'
+set vpn ipsec authentication psk vyos secret 'MYSECRETPASSWORD'
+set vpn ipsec site-to-site peer branch authentication local-id '203.0.113.46'
+set vpn ipsec site-to-site peer branch authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer branch authentication remote-id '198.51.100.243'
+set vpn ipsec site-to-site peer branch connection-type 'initiate'
+set vpn ipsec site-to-site peer branch default-esp-group 'my-esp'
+set vpn ipsec site-to-site peer branch ike-group 'my-ike'
+set vpn ipsec site-to-site peer branch ikev2-reauth 'inherit'
+set vpn ipsec site-to-site peer branch local-address '203.0.113.46'
+set vpn ipsec site-to-site peer branch remote-address '198.51.100.243'
+set vpn ipsec site-to-site peer branch tunnel 0 local prefix '172.29.41.89/32'
+set vpn ipsec site-to-site peer branch tunnel 0 remote prefix '172.27.1.0/24'
+set vpn ipsec site-to-site peer branch tunnel 1 local prefix '172.29.41.89/32'
+set vpn ipsec site-to-site peer branch tunnel 1 remote prefix '10.125.0.0/16'
+```
+
+##### Testing and Validation
+
+If you've completed all the above steps you no doubt want to see if it's
+all working.
+
+Start by checking for IPSec SAs (Security Associations) with:
+
+```none
+$ show vpn ipsec sa
+
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+198.51.100.243                          203.0.113.46
+
+    Tunnel  State  Bytes Out/In   Encrypt  Hash    NAT-T  A-Time  L-Time  Proto
+    ------  -----  -------------  -------  ----    -----  ------  ------  -----
+    0       up     0.0/0.0        aes256   sha256  no     1647    3600    all
+    1       up     0.0/0.0        aes256   sha256  no     865     3600    all
+```
+
+That looks good - we defined 2 tunnels and they're both up and running.
diff --git a/docs/configuration/nat/nat64.md b/docs/configuration/nat/nat64.md
new file mode 100644
index 00000000..c1b1c994
--- /dev/null
+++ b/docs/configuration/nat/nat64.md
@@ -0,0 +1,73 @@
+(nat64)=
+
+# NAT64
+
+{abbr}`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in
+modern networking, facilitating communication between IPv6 and IPv4 networks.
+This documentation outlines the setup, configuration, and usage of the NAT64
+feature in your project. Whether you are transitioning to IPv6 or need to
+seamlessly connect IPv4 and IPv6 devices.
+NAT64 is a stateful translation mechanism that translates IPv6 addresses to
+IPv4 addresses and IPv4 addresses to IPv6 addresses. NAT64 is used to enable
+IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP.
+
+## Overview
+
+### Different NAT Types
+
+(source-nat64)=
+
+#### SNAT64
+
+{abbr}`SNAT64 (IPv6-to-IPv4 Source Address Translation)` is a stateful
+translation mechanism that translates IPv6 addresses to IPv4 addresses.
+
+`64:ff9b::/96` is the well-known prefix for IPv4-embedded IPv6 addresses.
+The prefix is used to represent IPv4 addresses in an IPv6 address format.
+The IPv4 address is encoded in the low-order 32 bits of the IPv6 address.
+The high-order 32 bits are set to the well-known prefix 64:ff9b::/96.
+
+## Configuration Examples
+
+The following examples show how to configure NAT64 on a VyOS router.
+The 192.0.2.10 address is used as the IPv4 address for the translation pool.
+
+NAT64 server configuration:
+
+```none
+set interfaces ethernet eth0 address '192.0.2.1/24'
+set interfaces ethernet eth0 address '192.0.2.10/24'
+set interfaces ethernet eth0 description 'WAN'
+set interfaces ethernet eth1 address '2001:db8::1/64'
+set interfaces ethernet eth1 description 'LAN'
+
+set service dns forwarding allow-from '2001:db8::/64'
+set service dns forwarding dns64-prefix '64:ff9b::/96'
+set service dns forwarding listen-address '2001:db8::1'
+
+set nat64 source rule 100 source prefix '64:ff9b::/96'
+set nat64 source rule 100 translation pool 10 address '192.0.2.10'
+set nat64 source rule 100 translation pool 10 port '1-65535'
+```
+
+NAT64 client configuration:
+
+```none
+set interfaces ethernet eth1 address '2001:db8::2/64'
+set protocols static route6 64:ff9b::/96 next-hop 2001:db8::1
+set system name-server '2001:db8::1'
+```
+
+Test from the IPv6 only client:
+
+```none
+vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2
+PING 64:ff9b::192.0.2.1(64:ff9b::c000:201) 56 data bytes
+64 bytes from 64:ff9b::c000:201: icmp_seq=1 ttl=63 time=0.351 ms
+64 bytes from 64:ff9b::c000:201: icmp_seq=2 ttl=63 time=0.373 ms
+
+--- 64:ff9b::192.0.2.1 ping statistics ---
+2 packets transmitted, 2 received, 0% packet loss, time 1023ms
+rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms
+```
+
diff --git a/docs/configuration/nat/nat66.md b/docs/configuration/nat/nat66.md
new file mode 100644
index 00000000..1cbe3317
--- /dev/null
+++ b/docs/configuration/nat/nat66.md
@@ -0,0 +1,243 @@
+(nat66)=
+
+# NAT66(NPTv6)
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+{abbr}`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address
+translation technology based on IPv6 networks, used to convert an IPv6
+address prefix in an IPv6 message into another IPv6 address prefix.
+We call this address translation method NAT66. Devices that support the NAT66
+function are called NAT66 devices, which can provide NAT66 source
+and destination address translation functions.
+
+## Overview
+
+### Different NAT Types
+
+(source-nat66)=
+
+#### SNAT66
+
+{abbr}`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion
+function is mainly used in the following scenarios:
+- A single internal network and external network. Use the NAT66 device to
+  connect a single internal network and public network, and the hosts in
+  the internal network use IPv6 address prefixes that only support
+  routing within the local range. When a host in the internal network
+  accesses the external network, the source IPv6 address prefix in
+  the message will be converted into a global unicast IPv6 address
+  prefix by the NAT66 device.
+- Redundancy and load sharing. There are multiple NAT66 devices at the edge
+  of an IPv6 network to another IPv6 network. The path through the NAT66
+  device to another IPv6 network forms an equivalent route, and traffic
+  can be load-shared on these NAT66 devices. In this case, you
+  can configure the same source address translation rules on these
+  NAT66 devices, so that any NAT66 device can handle IPv6 traffic between
+  different sites.
+- Multi-homed. In a multi-homed network environment, the NAT66 device
+  connects to an internal network and simultaneously connects to
+  different external networks. Address translation can be configured
+  on each external network side interface of the NAT66 device to
+  convert the same internal network address into different external
+  network addresses, and realize the mapping of the same internal
+  address to multiple external addresses.
+(destination-nat66)=
+
+#### DNAT66
+
+The {abbr}`DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)`
+destination address translation function is used in scenarios where the
+server in the internal network provides services to the external network,
+such as providing Web services or FTP services to the external network.
+By configuring the mapping relationship between the internal server
+address and the external network address on the external network
+side interface of the NAT66 device, external network users can
+access the internal network server through the designated
+external network address.
+
+### Prefix Conversion
+
+#### Source Prefix
+
+Every SNAT66 rule has a translation command defined. The prefix defined
+for the translation is the prefix used when the address information in
+a packet is replaced.、
+
+The {ref}`source-nat66` rule replaces the source address of the packet
+and calculates the converted address using the prefix specified in the rule.
+
+Example:
+- Convert the address prefix of a single `fc01::/64` network to `fc00::/64`
+- Output from `eth0` network interface
+
+```none
+set nat66 source rule 1 outbound-interface name 'eth0'
+set nat66 source rule 1 source prefix 'fc01::/64'
+set nat66 source rule 1 translation address 'fc00::/64'
+```
+
+
+#### Destination Prefix
+
+For the {ref}`destination-nat66` rule, the destination address of
+the packet isreplaced by the address calculated from the specified
+address or prefix in the `translation address` command
+
+Example:
+- Convert the address prefix of a single `fc00::/64` network
+  to `fc01::/64`
+- Input from `eth0` network interface
+
+```none
+set nat66 destination rule 1 inbound-interface name 'eth0'
+set nat66 destination rule 1 destination address 'fc00::/64'
+set nat66 destination rule 1 translation address 'fc01::/64'
+```
+
+For the destination, groups can also be used instead of an address.
+
+Example:
+
+```none
+set firewall group ipv6-address-group ADR-INSIDE-v6 address fc00::1
+
+set nat66 destination rule 1 inbound-interface name 'eth0'
+set nat66 destination rule 1 destination group address-group ADR-INSIDE-v6
+set nat66 destination rule 1 translation address 'fc01::/64'
+```
+
+
+## Configuration Examples
+
+Use the following topology to build a nat66 based isolated
+network between internal and external networks (dynamic prefix is
+not supported):
+
+:::{figure} /_static/images/vyos_1_4_nat66_simple.webp
+:alt: VyOS NAT66 Simple Configure
+:::
+
+R1:
+
+```none
+set interfaces ethernet eth0 ipv6 address autoconf
+set interfaces ethernet eth1 address 'fc01::1/64'
+set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64'
+set nat66 destination rule 1 inbound-interface name 'eth0'
+set nat66 destination rule 1 translation address 'fc01::/64'
+set nat66 source rule 1 outbound-interface name 'eth0'
+set nat66 source rule 1 source prefix 'fc01::/64'
+set nat66 source rule 1 translation address 'fc00:470:f1cd:101::/64'
+```
+
+R2:
+
+```none
+set interfaces bridge br1 address 'fc01::2/64'
+set interfaces bridge br1 member interface eth0
+set interfaces bridge br1 member interface eth1
+set protocols static route6 ::/0 next-hop fc01::1
+set service router-advert interface br1 prefix ::/0
+```
+
+Use the following topology to translate internal user local addresses
+(`fc::/7`) to DHCPv6-PD provided prefixes from an ISP connected to
+a VyOS HA pair.
+
+:::{figure} /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp
+:alt: VyOS NAT66 DHCPv6 using a dummy interface
+:::
+
+Configure both routers (a and b) for DHCPv6-PD via dummy interface:
+
+```none
+set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy'
+set interfaces bonding bond0 vif 20 dhcpv6-options pd 0 interface dum1 address '0'
+set interfaces bonding bond0 vif 20 dhcpv6-options pd 1 interface dum1 address '0'
+set interfaces bonding bond0 vif 20 dhcpv6-options pd 2 interface dum1 address '0'
+set interfaces bonding bond0 vif 20 dhcpv6-options pd 3 interface dum1 address '0'
+set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit
+commit
+```
+
+Get the DHCPv6-PD prefixes from both routers:
+
+```none
+trae@cr01a-vyos# run show interfaces dummy dum1 br
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+dum1             2001:db8:123:b008::/64           u/u  DHCPv6-PD NPT dummy
+                 2001:db8:123:b00a::/64
+                 2001:db8:123:b00b::/64
+                 2001:db8:123:b009::/64
+
+trae@cr01b-vyos# run show int dummy dum1 brief
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+dum1             2001:db8:123:b00d::/64           u/u  DHCPv6-PD NPT dummy
+                 2001:db8:123:b00c::/64
+                 2001:db8:123:b00e::/64
+                 2001:db8:123:b00f::/64
+```
+
+Configure the A-side router for NPTv6 using the prefixes above:
+
+```none
+set nat66 source rule 10 description 'NPT to VLAN 10'
+set nat66 source rule 10 outbound-interface name 'bond0.20'
+set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64'
+set nat66 source rule 10 translation address '2001:db8:123:b008::/64'
+set nat66 source rule 20 description 'NPT to VLAN 70'
+set nat66 source rule 20 outbound-interface name 'bond0.20'
+set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64'
+set nat66 source rule 20 translation address '2001:db8:123:b009::/64'
+set nat66 source rule 30 description 'NPT to VLAN 200'
+set nat66 source rule 30 outbound-interface name 'bond0.20'
+set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64'
+set nat66 source rule 30 translation address '2001:db8:123:b00a::/64'
+set nat66 source rule 40 description 'NPT to VLAN 240'
+set nat66 source rule 40 outbound-interface name 'bond0.20'
+set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64'
+set nat66 source rule 40 translation address '2001:db8:123:b00b::/64'
+commit
+```
+
+Configure the B-side router for NPTv6 using the prefixes above:
+
+```none
+set nat66 source rule 10 description 'NPT to VLAN 10'
+set nat66 source rule 10 outbound-interface name 'bond0.20'
+set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64'
+set nat66 source rule 10 translation address '2001:db8:123:b00c::/64'
+set nat66 source rule 20 description 'NPT to VLAN 70'
+set nat66 source rule 20 outbound-interface name 'bond0.20'
+set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64'
+set nat66 source rule 20 translation address '2001:db8:123:b00d::/64'
+set nat66 source rule 30 description 'NPT to VLAN 200'
+set nat66 source rule 30 outbound-interface name 'bond0.20'
+set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64'
+set nat66 source rule 30 translation address '2001:db8:123:b00e::/64'
+set nat66 source rule 40 description 'NPT to VLAN 240'
+set nat66 source rule 40 outbound-interface name 'bond0.20'
+set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64'
+set nat66 source rule 40 translation address '2001:db8:123:b00f::/64'
+commit
+```
+
+Verify that connections are hitting the rule on both sides:
+
+```none
+trae@cr01a-vyos# run show nat66 source statistics
+Rule    Packets    Bytes    Interface
+------  ---------  -------  -----------
+10      1          104      bond0.20
+20      1          104      bond0.20
+30      8093       669445   bond0.20
+40      2446       216912   bond0.20
+```
diff --git a/docs/configuration/pki/index.md b/docs/configuration/pki/index.md
new file mode 100644
index 00000000..e7d793de
--- /dev/null
+++ b/docs/configuration/pki/index.md
@@ -0,0 +1,583 @@
+---
+lastproofread: '2024-01-05'
+---
+
+```{include} /_include/need_improvement.txt
+```
+
+(pki)=
+
+# PKI
+
+VyOS 1.4 changed the way in how encryption keys or certificates are stored on the
+system. In the pre VyOS 1.4 era, certificates got stored under /config and every
+service referenced a file. That made copying a running configuration from system
+A to system B a bit harder, as you had to copy the files and their permissions
+by hand.
+
+{vytask}`T3642` describes a new CLI subsystem that serves as a "certstore" to
+all services requiring any kind of encryption key(s). In short, public and
+private certificates are now stored in PKCS#8 format in the regular VyOS CLI.
+Keys can now be added, edited, and deleted using the regular set/edit/delete
+CLI commands.
+
+VyOS not only can now manage certificates issued by 3rd party Certificate
+Authorities, it can also act as a CA on its own. You can create your own root
+CA and sign keys with it by making use of some simple op-mode commands.
+
+Don't be afraid that you need to re-do your configuration. Key transformation is
+handled, as always, by our migration scripts, so this will be a smooth transition
+for you!
+
+## Key Generation
+
+### Certificate Authority (CA)
+
+VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other
+keypairs from an easy to access operational level command.
+
+```{opcmd} generate pki ca
+
+Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and
+private key on the console.
+```
+
+```{opcmd} generate pki ca install \<name\>
+
+Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and
+private key on the console.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+
+```{opcmd} generate pki ca sign \<ca-name\>
+
+Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using
+the private key referenced by ca-name.
+```
+
+```{opcmd} generate pki ca sign \<ca-name\> install \<name\>
+
+Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using
+the private key referenced by `name`.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+
+### Certificates
+
+```{opcmd} generate pki certificate
+
+Create a new public/private keypair and output the certificate on the console.
+```
+
+```{opcmd} generate pki certificate install \<name\>
+
+Create a new public/private keypair and output the certificate on the console.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+
+```{opcmd} generate pki certificate self-signed
+
+Create a new self-signed certificate. The public/private is then shown on the
+console.
+```
+
+```{opcmd} generate pki certificate self-signed install \<name\>
+
+Create a new self-signed certificate. The public/private is then shown on the
+console.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+
+```{opcmd} generate pki certificate sign \<ca-name\>
+
+Create a new public/private keypair which is signed by the CA referenced by
+ca-name. The signed certificate is then output to the console.
+```
+
+```{opcmd} generate pki certificate sign \<ca-name\> install \<name\>
+
+Create a new public/private keypair which is signed by the CA referenced by
+ca-name. The signed certificate is then output to the console.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+
+### Diffie-Hellman parameters
+
+```{opcmd} generate pki dh
+
+Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size
+is requested by the CLI and defaults to 2048 bit.
+
+The generated parameters are then output to the console.
+```
+
+```{opcmd} generate pki dh install \<name\>
+
+Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size
+is requested by the CLI and defaults to 2048 bit.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+
+### OpenVPN
+
+```{opcmd} generate pki openvpn shared-secret
+
+Generate a new OpenVPN shared secret. The generated secret is the output to
+the console.
+```
+
+```{opcmd} generate pki openvpn shared-secret install \<name\>
+
+Generate a new OpenVPN shared secret. The generated secret is the output to
+the console.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+
+### WireGuard
+
+```{opcmd} generate pki wireguard key-pair
+
+Generate a new WireGuard public/private key portion and output the result to
+the console.
+```
+
+```{opcmd} generate pki wireguard key-pair install \<interface\>
+
+Generate a new WireGuard public/private key portion and output the result to
+the console.
+
+:::{note}
+In addition to the command above, the output is in a format which can
+be used to directly import the key into the VyOS CLI by simply copy-pasting
+the output from op-mode into configuration mode.
+
+``interface`` is used for the VyOS CLI command to identify the WireGuard
+interface where this private key is to be used.
+:::
+```
+
+```{opcmd} generate pki wireguard preshared-key
+
+Generate a WireGuard pre-shared secret used for peers to communicate.
+```
+
+```{opcmd} generate pki wireguard preshared-key install \<peer\>
+
+Generate a WireGuard pre-shared secret used for peers to communicate.
+
+:::{note}
+In addition to the command above, the output is in a format which can
+be used to directly import the key into the VyOS CLI by simply copy-pasting
+the output from op-mode into configuration mode.
+
+``peer`` is used for the VyOS CLI command to identify the WireGuard peer where
+this secret is to be used.
+:::
+```
+
+## Key usage (CLI)
+### CA (Certificate Authority)
+
+```{cfgcmd} set pki ca \<name\> certificate
+
+Add the public CA certificate for the CA named `name` to the VyOS CLI.
+
+:::{note}
+When loading the certificate you need to manually strip the
+``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags.
+Also, the certificate/key needs to be presented in a single line without
+line breaks (``\n``), this can be done using the following shell command:
+
+``$ tail -n +2 ca.pem | head -n -1 | tr -d '\n'``
+:::
+```
+
+```{cfgcmd} set pki ca \<name\> crl
+
+Certificate revocation list in PEM format.
+```
+
+```{cfgcmd} set pki ca \<name\> description
+
+A human readable description what this CA is about.
+```
+
+```{cfgcmd} set pki ca \<name\> private key
+
+Add the CAs private key to the VyOS CLI. This should never leave the system,
+and is only required if you use VyOS as your certificate generator as
+mentioned above.
+
+:::{note}
+When loading the certificate you need to manually strip the
+``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the
+certificate/key needs to be presented in a single line without line
+breaks (``\n``), this can be done using the following shell command:
+
+``$ tail -n +2 ca.key | head -n -1 | tr -d '\n'``
+:::
+```
+
+```{cfgcmd} set pki ca \<name\> private password-protected
+
+Mark the CAs private key as password protected. User is asked for the password
+when the key is referenced.
+```
+
+### Server Certificate
+
+After we have imported the CA certificate(s) we can now import and add
+certificates used by services on this router.
+
+```{cfgcmd} set pki certificate \<name\> certificate
+
+Add public key portion for the certificate named `name` to the VyOS CLI.
+
+:::{note}
+When loading the certificate you need to manually strip the
+``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags.
+Also, the certificate/key needs to be presented in a single line without
+line breaks (``\n``), this can be done using the following shell command:
+
+``$ tail -n +2 cert.pem | head -n -1 | tr -d '\n'``
+:::
+```
+
+```{cfgcmd} set pki certificate \<name\> description
+
+A human readable description what this certificate is about.
+```
+
+```{cfgcmd} set pki certificate \<name\> private key
+
+Add the private key portion of this certificate to the CLI. This should never
+leave the system as it is used to decrypt the data.
+
+:::{note}
+When loading the certificate you need to manually strip the
+``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the
+certificate/key needs to be presented in a single line without line
+breaks (``\n``), this can be done using the following shell command:
+
+``$ tail -n +2 cert.key | head -n -1 | tr -d '\n'``
+:::
+```
+
+```{cfgcmd} set pki certificate \<name\> private password-protected
+
+Mark the private key as password protected. User is asked for the password
+when the key is referenced.
+```
+
+```{cfgcmd} set pki certificate \<name\> revoke
+
+If CA is present, this certificate will be included in generated CRLs
+```
+
+### Import files to PKI format
+
+VyOS provides this utility to import existing certificates/key files directly
+into PKI from op-mode. Previous to VyOS 1.4, certificates were stored under the
+/config folder permanently and will be retained post upgrade.
+
+```{opcmd} import pki ca \<name\> file \<Path to CA certificate file\>
+
+Import the public CA certificate from the defined file to VyOS CLI.
+```
+
+```{opcmd} import pki ca \<name\> key-file \<Path to private key file\>
+
+Import the CAs private key portion to the CLI. This should never leave the
+system as it is used to decrypt the data. The key is required if you use
+VyOS as your certificate generator.
+```
+
+```{opcmd} import pki certificate \<name\> file \<path to certificate\>
+
+Import the certificate from the file to VyOS CLI.
+```
+
+```{opcmd} import pki certificate \<name\> key-file \<path to private key\>
+
+Import the private key of the certificate to the VyOS CLI. This should never
+leave the system as it is used to decrypt the data.
+```
+
+```{opcmd} import pki openvpn shared-secret \<name\> file \<path to OpenVPN secret key\>
+
+Import the OpenVPN shared secret stored in file to the VyOS CLI.
+```
+
+#### ACME
+
+The VyOS PKI subsystem can also be used to automatically retrieve Certificates
+using the {abbr}`ACME (Automatic Certificate Management Environment)` protocol.
+
+```{cfgcmd} set pki certificate \<name\> acme domain-name \<name\>
+
+Domain names to apply, multiple domain-names can be specified.
+
+This is a mandatory option
+```
+
+```{cfgcmd} set pki certificate \<name\> acme email \<address\>
+
+Email used for registration and recovery contact.
+
+This is a mandatory option
+```
+
+```{cfgcmd} set pki certificate \<name\> acme listen-address \<address\>
+
+The address the server listens to during http-01 challenge
+```
+
+```{cfgcmd} set pki certificate \<name\> acme rsa-key-size \<2048 | 3072 | 4096\>
+
+Size of the RSA key.
+
+This options defaults to 2048
+```
+
+```{cfgcmd} set pki certificate \<name\> acme url \<url\>
+
+ACME Directory Resource URI.
+
+This defaults to https://acme-v02.api.letsencrypt.org/directory
+
+:::{note}
+During initial deployment we recommend using the staging API
+of LetsEncrypt to prevent and blacklisting of your system. The API
+endpoint is https://acme-staging-v02.api.letsencrypt.org/directory
+:::
+```
+
+## Operation
+
+VyOS operational mode commands are not only available for generating keys but
+also to display them.
+
+```{opcmd} show pki ca
+
+Show a list of installed {abbr}`CA (Certificate Authority)` certificates.
+
+:::{code-block} none
+vyos@vyos:~$ show pki ca
+Certificate Authorities:
+Name            Subject                                                  Issuer CN          Issued               Expiry               Private Key    Parent
+--------------  -------------------------------------------------------  -----------------  -------------------  -------------------  -------------  --------------
+DST_Root_CA_X3  CN=ISRG Root X1,O=Internet Security Research Group,C=US  CN=DST Root CA X3  2021-01-20 19:14:03  2024-09-30 18:14:03  No             N/A
+R3              CN=R3,O=Let's Encrypt,C=US                               CN=ISRG Root X1    2020-09-04 00:00:00  2025-09-15 16:00:00  No             DST_Root_CA_X3
+vyos_rw         CN=VyOS RW CA,O=VyOS,L=Some-City,ST=Some-State,C=GB      CN=VyOS RW CA      2021-07-05 13:46:03  2026-07-04 13:46:03  Yes            N/A
+:::
+```
+
+```{opcmd} show pki ca \<name\>
+
+Show only information for specified Certificate Authority.
+```
+
+```{opcmd} show pki certificate
+
+Show a list of installed certificates
+
+:::{code-block} none
+vyos@vyos:~$ show pki certificate
+Certificates:
+Name       Type    Subject CN             Issuer CN      Issued               Expiry               Revoked    Private Key    CA Present
+---------  ------  ---------------------  -------------  -------------------  -------------------  ---------  -------------  -------------
+ac2        Server  CN=ac2.vyos.net        CN=R3          2021-07-05 07:29:59  2021-10-03 07:29:58  No         Yes            Yes (R3)
+rw_server  Server  CN=VyOS RW             CN=VyOS RW CA  2021-07-05 13:48:02  2022-07-05 13:48:02  No         Yes            Yes (vyos_rw)
+:::
+```
+
+```{opcmd} show pki certificate \<name\>
+
+Show only information for specified certificate.
+```
+
+```{opcmd} show pki crl
+
+Show a list of installed {abbr}`CRLs (Certificate Revocation List)`.
+```
+
+```{opcmd} renew certbot
+
+Manually trigger certificate renewal. This will be done twice a day.
+```
+
+## Examples
+
+### Create a CA chain and leaf certificates
+
+This configuration generates & installs into the VyOS PKI system a root
+certificate authority, alongside two intermediary certificate authorities for
+client & server certificates. These CAs are then used to generate a server
+certificate for the router, and a client certificate for a user.
+- `vyos_root_ca` is the root certificate authority.
+- `vyos_client_ca` and `vyos_server_ca` are intermediary certificate authorities,
+  which are signed by the root CA.
+- `vyos_cert` is a leaf server certificate used to identify the VyOS router,
+  signed by the server intermediary CA.
+- `vyos_example_user` is a leaf client certificate used to identify a user,
+  signed by client intermediary CA.
+
+First, we create the root certificate authority.
+
+```none
+[edit]
+vyos@vyos# run generate pki ca install vyos_root_ca
+Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa
+Enter private key bits: (Default: 2048) 2048
+Enter country code: (Default: GB) GB
+Enter state: (Default: Some-State) Some-State
+Enter locality: (Default: Some-City) Some-City
+Enter organization name: (Default: VyOS) VyOS
+Enter common name: (Default: vyos.io) VyOS Root CA
+Enter how many days certificate will be valid: (Default: 1825) 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] n
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+```
+
+Secondly, we create the intermediary certificate authorities, which are used to
+sign the leaf certificates.
+
+```none
+[edit]
+vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_server_ca
+Do you already have a certificate request? [y/N] n
+Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa
+Enter private key bits: (Default: 2048) 2048
+Enter country code: (Default: GB) GB
+Enter state: (Default: Some-State) Some-State
+Enter locality: (Default: Some-City) Some-City
+Enter organization name: (Default: VyOS) VyOS
+Enter common name: (Default: vyos.io) VyOS Intermediary Server CA
+Enter how many days certificate will be valid: (Default: 1825) 1095
+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] n
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+
+
+[edit]
+vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_client_ca
+Do you already have a certificate request? [y/N] n
+Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa
+Enter private key bits: (Default: 2048) 2048
+Enter country code: (Default: GB) GB
+Enter state: (Default: Some-State) Some-State
+Enter locality: (Default: Some-City) Some-City
+Enter organization name: (Default: VyOS) VyOS
+Enter common name: (Default: vyos.io) VyOS Intermediary Client CA
+Enter how many days certificate will be valid: (Default: 1825) 1095
+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] n
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+```
+
+Lastly, we can create the leaf certificates that devices and users will utilise.
+
+```none
+[edit]
+vyos@vyos# run generate pki certificate sign vyos_server_ca install vyos_cert
+Do you already have a certificate request? [y/N] n
+Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa
+Enter private key bits: (Default: 2048) 2048
+Enter country code: (Default: GB) GB
+Enter state: (Default: Some-State) Some-State
+Enter locality: (Default: Some-City) Some-City
+Enter organization name: (Default: VyOS) VyOS
+Enter common name: (Default: vyos.io) vyos.net
+Do you want to configure Subject Alternative Names? [y/N] y
+Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net
+Enter Subject Alternative Names: dns:vyos.net,dns:www.vyos.net
+Enter how many days certificate will be valid: (Default: 365) 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] n
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+
+
+[edit]
+vyos@vyos# run generate pki certificate sign vyos_client_ca install vyos_example_user
+Do you already have a certificate request? [y/N] n
+Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa
+Enter private key bits: (Default: 2048) 2048
+Enter country code: (Default: GB) GB
+Enter state: (Default: Some-State) Some-State
+Enter locality: (Default: Some-City) Some-City
+Enter organization name: (Default: VyOS) VyOS
+Enter common name: (Default: vyos.io) Example User
+Do you want to configure Subject Alternative Names? [y/N] y
+Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net,rfc822:user@vyos.net
+Enter Subject Alternative Names: rfc822:example.user@vyos.net
+Enter how many days certificate will be valid: (Default: 365) 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] n
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+```
diff --git a/docs/configuration/policy/access-list.md b/docs/configuration/policy/access-list.md
new file mode 100644
index 00000000..c3a92e56
--- /dev/null
+++ b/docs/configuration/policy/access-list.md
@@ -0,0 +1,70 @@
+# Access List Policy
+
+Filtering is used for both input and output of the routing information. Once
+filtering is defined, it can be applied in any direction. VyOS makes filtering
+possible using acls and prefix lists.
+
+Basic filtering can be done using access-list and access-list6.
+
+## Configuration
+
+### Access Lists
+
+```{cfgcmd} set policy access-list \<acl_number\>
+
+This command creates the new access list policy, where `<acl_number>` must be
+a number from 1 to 2699.
+```
+
+```{cfgcmd} set policy access-list \<acl_number\> description \<text\>
+
+Set description for the access list.
+```
+
+```{cfgcmd} set policy access-list \<acl_number\> rule \<1-65535\> action \<permit|deny\>
+
+This command creates a new rule in the access list and defines an action.
+```
+
+```{cfgcmd} set policy access-list \<acl_number\> rule \<1-65535\> \<destination|source\> \<any|host|inverse-mask|network\>
+
+This command defines matching parameters for access list rule. Matching
+criteria could be applied to destination or source parameters:
+
+* any: any IP address to match.
+* host: single host IP address to match.
+* inverse-match: network/netmask to match (requires network be defined).
+* network: network/netmask to match (requires inverse-match be defined).
+```
+
+
+### IPv6 Access List
+
+Basic filtering could also be applied to IPv6 traffic.
+
+```{cfgcmd} set policy access-list6 \<text\>
+
+This command creates the new IPv6 access list, identified by `<text>`
+```
+
+```{cfgcmd} set policy access-list6 \<text\> description \<text\>
+
+Set description for the IPv6 access list.
+```
+
+```{cfgcmd} set policy access-list6 \<text\> rule \<1-65535\> action \<permit|deny\>
+
+This command creates a new rule in the IPv6 access list and defines an
+action.
+```
+
+```{cfgcmd} set policy access-list6 \<text\> rule \<1-65535\> source \<any|exact-match|network\>
+
+This command defines matching parameters for IPv6 access list rule. Matching
+criteria could be applied to source parameters:
+
+* any: any IPv6 address to match.
+* exact-match: exact match of the network prefixes.
+* network: network/netmask to match (requires inverse-match be defined) BUG,
+NO invert-match option in access-list6
+```
\ No newline at end of file
diff --git a/docs/configuration/policy/as-path-list.md b/docs/configuration/policy/as-path-list.md
new file mode 100644
index 00000000..1fcece91
--- /dev/null
+++ b/docs/configuration/policy/as-path-list.md
@@ -0,0 +1,29 @@
+# BGP - AS Path Policy
+
+VyOS provides policies commands exclusively for BGP traffic filtering and
+manipulation: **as-path-list** is one of them.
+
+## Configuration
+
+### policy as-path-list
+
+```{cfgcmd} set policy as-path-list \<text\>
+
+Create as-path-policy identified by name `<text>`.
+```
+```{cfgcmd} set policy as-path-list \<text\> description \<text\>
+
+Set description for as-path-list policy.
+```
+```{cfgcmd} set policy as-path-list \<text\> rule \<1-65535\> action \<permit|deny\>
+
+Set action to take on entries matching this rule.
+```
+```{cfgcmd} set policy as-path-list \<text\> rule \<1-65535\> description \<text\>
+
+Set description for rule.
+```
+```{cfgcmd} set policy as-path-list \<text\> rule \<1-65535\> regex \<text\>
+
+Regular expression to match against an AS path. For example "64501 64502".
+```
\ No newline at end of file
diff --git a/docs/configuration/policy/community-list.md b/docs/configuration/policy/community-list.md
new file mode 100644
index 00000000..bdcf4140
--- /dev/null
+++ b/docs/configuration/policy/community-list.md
@@ -0,0 +1,29 @@
+# BGP - Community List
+
+VyOS provides policies commands exclusively for BGP traffic filtering and
+manipulation: **community-list** is one of them.
+
+## Configuration
+
+### policy community-list
+
+```{cfgcmd} set policy community-list \<text\>
+
+Creat community-list policy identified by name `<text>`.
+```
+```{cfgcmd} set policy community-list \<text\> description \<text\>
+
+Set description for community-list policy.
+```
+```{cfgcmd} set policy community-list \<text\> rule \<1-65535\> action \<permit|deny\>
+
+Set action to take on entries matching this rule.
+```
+```{cfgcmd} set policy community-list \<text\> rule \<1-65535\> description \<text\>
+
+Set description for rule.
+```
+```{cfgcmd} set policy community-list \<text\> rule \<1-65535\> regex \<aa:nn|local-AS|no-advertise|no-export|additive\>
+
+Regular expression to match against a community-list.
+```
\ No newline at end of file
diff --git a/docs/configuration/policy/examples.md b/docs/configuration/policy/examples.md
new file mode 100644
index 00000000..86aba9a9
--- /dev/null
+++ b/docs/configuration/policy/examples.md
@@ -0,0 +1,205 @@
+# BGP Example
+
+**Policy definition:**
+
+```none
+# Create policy
+set policy route-map setmet rule 2 action 'permit'
+set policy route-map setmet rule 2 set as-path prepend '2 2 2'
+
+# Apply policy to BGP
+set protocols bgp system-as 1
+set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet'
+set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound'
+```
+
+Using 'soft-reconfiguration' we get the policy update without bouncing the
+neighbor.
+
+**Routes learned before routing policy applied:**
+
+```none
+vyos@vos1:~$ show ip bgp
+BGP table version is 0, local router ID is 192.168.56.101
+Status codes: s suppressed, d damped, h history, * valid, > best, i - internal,
+              r RIB-failure, S Stale, R Removed
+Origin codes: i - IGP, e - EGP, ? - incomplete
+
+   Network          Next Hop            Metric LocPrf Weight Path
+*> 198.51.100.3/32   203.0.113.2           1             0 2 i  < Path
+
+Total number of prefixes 1
+```
+
+**Routes learned after routing policy applied:**
+
+```none
+vyos@vos1:~$ show ip bgp
+BGP table version is 0, local router ID is 192.168.56.101
+Status codes: s suppressed, d damped, h history, * valid, > best, i - internal,
+              r RIB-failure, S Stale, R Removed
+Origin codes: i - IGP, e - EGP, ? - incomplete
+
+   Network          Next Hop            Metric LocPrf Weight Path
+*> 198.51.100.3/32   203.0.113.2           1             0 2 2 2 2 i
+
+Total number of prefixes 1
+vyos@vos1:~$
+```
+
+You now see the longer AS path.
+
+# Transparent Proxy
+
+The following example will show how VyOS can be used to redirect web
+traffic to an external transparent proxy:
+
+```none
+set policy route FILTER-WEB rule 1000 destination port 80
+set policy route FILTER-WEB rule 1000 protocol tcp
+set policy route FILTER-WEB rule 1000 set table 100
+```
+
+This creates a route policy called FILTER-WEB with one rule to set the
+routing table for matching traffic (TCP port 80) to table ID 100
+instead of the default routing table.
+
+To create routing table 100 and add a new default gateway to be used by
+traffic matching our route policy:
+
+```none
+set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2
+```
+
+This can be confirmed using the `show ip route table 100` operational
+command.
+
+Finally, to apply the policy route to ingress traffic on our LAN
+interface, we use:
+
+```none
+set policy route FILTER-WEB interface eth1
+```
+
+
+# Multiple Uplinks
+
+VyOS Policy-Based Routing (PBR) works by matching source IP address
+ranges and forwarding the traffic using different routing tables.
+
+Routing tables that will be used in this example are:
+
+- `table 10` Routing table used for VLAN 10 (192.168.188.0/24)
+- `table 11` Routing table used for VLAN 11 (192.168.189.0/24)
+- `main` Routing table used by VyOS and other interfaces not
+  participating in PBR
+
+:::{figure} /_static/images/pbr_example_1.webp
+:alt: PBR multiple uplinks
+:scale: 80 %
+
+Policy-Based Routing with multiple ISP uplinks
+(source ./draw.io/pbr_example_1.drawio)
+:::
+
+Add default routes for routing `table 10` and `table 11`
+
+```none
+set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.1.1
+set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2
+```
+
+Add policy route matching VLAN source addresses
+
+```none
+set policy route PBR rule 20 set table '10'
+set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10'
+set policy route PBR rule 20 source address '192.168.188.0/24'
+
+set policy route PBR rule 30 set table '11'
+set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11'
+set policy route PBR rule 30 source address '192.168.189.0/24'
+```
+
+Apply routing policy to **inbound** direction of out VLAN interfaces
+
+```none
+set policy route 'PBR' interface eth0.10
+set policy route 'PBR' interface eth0.11
+```
+
+**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11)
+from PBR
+
+```none
+set firewall group network-group VLANS-GR description 'VLANs networks'
+set firewall group network-group VLANS-GR network '192.168.188.0/24'
+set firewall group network-group VLANS-GR network '192.168.189.0/24'
+
+set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut'
+set policy route PBR rule 10 destination group network-group 'VLANS-GR'
+set policy route PBR rule 10 set table 'main'
+```
+
+These commands allow the VLAN10 and VLAN11 hosts to communicate with
+each other using the main routing table.
+
+## Local route
+
+The following example allows VyOS to use {abbr}`PBR (Policy-Based Routing)`
+for traffic, which originated from the router itself. That solution for multiple
+ISP's and VyOS router will respond from the same interface that the packet was
+received. Also, it used, if we want that one VPN tunnel to be through one
+provider, and the second through another.
+
+- `203.0.113.254` IP addreess on VyOS eth1 from ISP1
+- `192.168.2.254` IP addreess on VyOS eth2 from ISP2
+- `table 10` Routing table used for ISP1
+- `table 11` Routing table used for ISP2
+
+```none
+set policy local-route rule 101 set table '10'
+set policy local-route rule 101 source address '203.0.113.254'
+set policy local-route rule 102 set table '11'
+set policy local-route rule 102 source address '192.0.2.254'
+set protocols static table 10 route 0.0.0.0/0 next-hop '203.0.113.1'
+set protocols static table 11 route 0.0.0.0/0 next-hop '192.0.2.2'
+```
+
+Add multiple source IP in one rule with same priority
+
+```none
+set policy local-route rule 101 set table '10'
+set policy local-route rule 101 source address '203.0.113.254'
+set policy local-route rule 101 source address '203.0.113.253'
+set policy local-route rule 101 source address '198.51.100.0/24'
+```
+
+
+# Clamp MSS for a specific IP
+
+This example shows how to target an MSS clamp (in our example to 1360 bytes)
+to a specific destination IP.
+
+```none
+set policy route IP-MSS-CLAMP rule 10 description 'Clamp TCP session MSS to 1360 for 198.51.100.30'
+set policy route IP-MSS-CLAMP rule 10 destination address '198.51.100.30/32'
+set policy route IP-MSS-CLAMP rule 10 protocol 'tcp'
+set policy route IP-MSS-CLAMP rule 10 set tcp-mss '1360'
+set policy route IP-MSS-CLAMP rule 10 tcp flags 'SYN'
+```
+
+To apply this policy to the correct interface, configure it on the
+interface the inbound local host will send through to reach our
+destined target host (in our example eth1).
+
+```none
+set policy route IP-MSS-CLAMP interface eth1
+```
+
+You can view that the policy is being correctly (or incorrectly) utilised
+with the following command:
+
+```none
+show policy route statistics
+```
diff --git a/docs/configuration/policy/extcommunity-list.md b/docs/configuration/policy/extcommunity-list.md
new file mode 100644
index 00000000..5247c13c
--- /dev/null
+++ b/docs/configuration/policy/extcommunity-list.md
@@ -0,0 +1,33 @@
+# BGP - Extended Community List
+
+VyOS provides policies commands exclusively for BGP traffic filtering and
+manipulation: **extcommunity-list** is one of them.
+
+## Configuration
+
+### policy extcommunity-list
+
+```{cfgcmd} set policy extcommunity-list \<text\>
+
+Creat extcommunity-list policy identified by name \<text\>.
+```
+```{cfgcmd} set policy extcommunity-list \<text\> description \<text\>
+
+Set description for extcommunity-list policy.
+```
+```{cfgcmd} set policy extcommunity-list \<text\> rule \<1-65535\> action \<permit|deny\>
+
+Set action to take on entries matching this rule.
+```
+```{cfgcmd} set policy extcommunity-list \<text\> rule \<1-65535\> description \<text\>
+
+Set description for rule.
+```
+```{cfgcmd} set policy extcommunity-list \<text\> rule \<1-65535\> regex \<text\>
+
+Regular expression to match against an extended community list, where text
+could be:
+* \<aa:nn:nn\>: Extended community list regular expression.
+* \<rt aa:nn:nn\>: Route Target regular expression.
+* \<soo aa:nn:nn\>: Site of Origin regular expression.
+```
\ No newline at end of file
diff --git a/docs/configuration/policy/index.md b/docs/configuration/policy/index.md
new file mode 100644
index 00000000..f919e70a
--- /dev/null
+++ b/docs/configuration/policy/index.md
@@ -0,0 +1,53 @@
+---
+lastproofread: '2021-07-12'
+---
+
+```{include} /_include/need_improvement.txt
+```
+
+
+# Policy
+
+Policies are used for filtering and traffic management. With policies, network
+administrators could filter and treat traffic
+according to their needs.
+
+There could be a wide range of routing policies. Some examples are listed
+below:
+- Filter traffic based on source/destination address.
+- Set some metric to routes learned from a particular neighbor.
+- Set some attributes (like AS PATH or Community value) to advertised routes
+  to neighbors.
+- Prefer a specific routing protocol routes over another routing protocol
+  running on the same router.
+
+Policies, in VyOS, are implemented using FRR filtering and route maps. Detailed
+information of FRR could be found in <http://docs.frrouting.org/>
+
+## Policy Sections
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+access-list
+prefix-list
+route
+route-map
+local-route
+as-path-list
+community-list
+extcommunity-list
+large-community-list
+```
+
+## Examples
+
+Examples of policies usage:
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+examples
+```
diff --git a/docs/configuration/policy/large-community-list.md b/docs/configuration/policy/large-community-list.md
new file mode 100644
index 00000000..23b9a85a
--- /dev/null
+++ b/docs/configuration/policy/large-community-list.md
@@ -0,0 +1,29 @@
+# BGP - Large Community List
+
+VyOS provides policies commands exclusively for BGP traffic filtering and
+manipulation: **large-community-list** is one of them.
+
+## Configuration
+
+### policy large-community-list
+
+```{cfgcmd} set policy large-community-list \<text\>
+
+Create large-community-list policy identified by name `<text>`.
+```
+```{cfgcmd} set policy large-community-list \<text\> description \<text\>
+
+Set description for large-community-list policy.
+```
+```{cfgcmd} set policy large-community-list \<text\> rule \<1-65535\> action \<permit|deny\>
+
+Set action to take on entries matching this rule.
+```
+```{cfgcmd} set policy large-community-list \<text\> rule \<1-65535\> description \<text\>
+
+Set description for rule.
+```
+```{cfgcmd} set policy large-community-list \<text\> rule \<1-65535\> regex \<aa:nn:nn\>
+
+Regular expression to match against a large community list.
+```
\ No newline at end of file
diff --git a/docs/configuration/policy/local-route.md b/docs/configuration/policy/local-route.md
new file mode 100644
index 00000000..527a2380
--- /dev/null
+++ b/docs/configuration/policy/local-route.md
@@ -0,0 +1,100 @@
+# Local Route Policy
+
+Policies for local traffic are defined in this section.
+
+## Configuration
+
+### Local Route IPv4
+
+```{cfgcmd} set policy local-route rule \<1-32765\> set table \<1-200|main\>
+
+Set the routing table to use for forwarding matching packets.
+```
+
+```{cfgcmd} set policy local-route rule \<1-32765\> set vrf \<vrf|default\>
+
+Set the VRF to use for forwarding matching packets.
+```
+
+```{cfgcmd} set policy local-route rule \<1-32765\> protocol \<protocol\>
+
+Match specified protocol (name or number).
+```
+
+```{cfgcmd} set policy local-route rule \<1-32765\> fwmark \<1-2147483647\>
+
+Match specified firewall mark (fwmark).
+```
+
+```{cfgcmd} set policy local-route rule \<1-32765\> source address \<x.x.x.x|x.x.x.x/x\>
+
+Match specified source address or prefix.
+```
+
+```{cfgcmd} set policy local-route rule \<1-32765\> source port \<1-65535\>
+
+Match specified source port.
+```
+
+```{cfgcmd} set policy local-route rule \<1-32765\> destination address \<x.x.x.x|x.x.x.x/x\>
+
+Match specified destination address or prefix.
+```
+
+```{cfgcmd} set policy local-route rule \<1-32765\> destination port \<1-65535\>
+
+Match specified destination port.
+```
+
+```{cfgcmd} set policy local-route rule \<1-32765\> inbound-interface \<interface\>
+
+Match specified inbound interface.
+```
+
+
+### Local Route IPv6
+
+```{cfgcmd} set policy local-route6 rule \<1-32765\> set table \<1-200|main\>
+
+Set the routing table to use for forwarding matching packets.
+```
+
+```{cfgcmd} set policy local-route6 rule \<1-32765\> set vrf \<vrf|default\>
+
+Set the VRF to use for forwarding matching packets.
+```
+
+```{cfgcmd} set policy local-route6 rule \<1-32765\> protocol \<protocol\>
+
+Match specified protocol (name or number).
+```
+
+```{cfgcmd} set policy local-route6 rule \<1-32765\> fwmark \<1-2147483647\>
+
+Match specified firewall mark (fwmark).
+```
+
+```{cfgcmd} set policy local-route6 rule \<1-32765\> source address \<h:h:h:h:h:h:h:h|h:h:h:h:h:h:h:h/x\>
+
+Match specified source address or prefix.
+```
+
+```{cfgcmd} set policy local-route6 rule \<1-32765\> source port \<1-65535\>
+
+Match specified source port.
+```
+
+```{cfgcmd} set policy local-route6 rule \<1-32765\> destination address \<h:h:h:h:h:h:h:h|h:h:h:h:h:h:h:h/x\>
+
+Match specified destination address or prefix.
+```
+
+```{cfgcmd} set policy local-route6 rule \<1-32765\> destination port \<1-65535\>
+
+Match specified destination port.
+```
+
+```{cfgcmd} set policy local-route6 rule \<1-32765\> inbound-interface \<interface\>
+
+Match specified inbound interface.
+```
\ No newline at end of file
diff --git a/docs/configuration/policy/prefix-list.md b/docs/configuration/policy/prefix-list.md
new file mode 100644
index 00000000..eb827c77
--- /dev/null
+++ b/docs/configuration/policy/prefix-list.md
@@ -0,0 +1,152 @@
+# Prefix List Policy
+
+Prefix lists provides the most powerful prefix based filtering mechanism. In
+addition to access-list functionality, ip prefix-list has prefix length range
+specification.
+
+If no ip prefix list is specified, it acts as permit. If ip prefix list is
+defined, and no match is found, default deny is applied.
+
+Prefix filtering can be done using prefix-list and prefix-list6.
+
+## Configuration
+
+### IPv4 Prefix Lists (prefix-list)
+
+```{cfgcmd} set policy prefix-list \<text\>
+
+This command creates the new prefix-list policy, identified by `<text>`.
+```
+
+```{cfgcmd} set policy prefix-list \<text\> description \<text\>
+
+Set description for the prefix-list policy.
+```
+
+```{cfgcmd} set policy prefix-list \<text\> rule \<1-65535\> action \<permit|deny\>
+
+This command creates a new rule in the prefix-list and defines an action.
+```
+
+```{cfgcmd} set policy prefix-list \<text\> rule \<1-65535\> description \<text\>
+
+Set description for rule in the prefix-list.
+```
+
+```{cfgcmd} set policy prefix-list \<text\> rule \<1-65535\> prefix \<x.x.x.x/x\>
+
+Prefix to match against.
+```
+
+```{cfgcmd} set policy prefix-list \<text\> rule \<1-65535\> ge \<0-32\>
+
+Netmask greater than length.
+```
+
+```{cfgcmd} set policy prefix-list \<text\> rule \<1-65535\> le \<0-32\>
+
+Netmask less than length
+```
+
+
+### Example: IPv4 Prefix Lists (prefix-list)
+
+This example creates an IPv4 prefix-list named PL4-EXAMPLE-NAME, defines 3
+rules each with 1 prefix, and matches le (less than/equal to) /32.
+
+```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 action 'permit'
+
+```
+```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 le '32'
+```
+
+```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 prefix '192.0.2.0/24'
+```
+
+```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 action 'permit'
+```
+
+```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 le '32'
+```
+
+```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 prefix '198.51.100.0/24'
+```
+
+```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 action 'permit'
+```
+
+```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 le '32'
+```
+
+```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 prefix '203.0.113.0/24'
+```
+
+### IPv6 Prefix Lists (prefix-list6)
+
+```{cfgcmd} set policy prefix-list6 \<text\>
+
+This command creates the new IPv6 prefix-list policy, identified by `<text>`.
+```
+
+```{cfgcmd} set policy prefix-list6 \<text\> description \<text\>
+
+Set description for the IPv6 prefix-list policy.
+```
+
+```{cfgcmd} set policy prefix-list6 \<text\> rule \<1-65535\> action \<permit|deny\>
+
+This command creates a new rule in the IPv6 prefix-list and defines an
+action.
+```
+
+```{cfgcmd} set policy prefix-list6 \<text\> rule \<1-65535\> description \<text\>
+
+Set description for rule in IPv6 prefix-list.
+```
+
+```{cfgcmd} set policy prefix-list6 \<text\> rule \<1-65535\> prefix \<h:h:h:h:h:h:h:h/x\>
+
+IPv6 prefix.
+```
+
+```{cfgcmd} set policy prefix-list6 \<text\> rule \<1-65535\> ge \<0-128\>
+
+Netmask greater than length.
+```
+
+```{cfgcmd} set policy prefix-list6 \<text\> rule \<1-65535\> le \<0-128\>
+
+Netmask less than length
+```
+
+### Example: IPv6 Prefix Lists (prefix-list6)
+
+This example creates an IPv6 prefix-list6 named PL6-EXAMPLE-NAME, defines 3
+rules each with 1 prefix, and matches le (less than/equal to) /128.
+
+```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 action 'permit'
+```
+
+```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 le '128'
+```
+
+```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 prefix '2001:db8:0:0::/64'
+```
+
+```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 action 'permit'
+```
+
+```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 le '128'
+```
+
+```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 prefix '2001:db8:0:1::/64'
+```
+
+```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 action 'permit'
+```
+
+```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 le '128'
+```
+
+```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 prefix '2001:db8:0:2::/64'
+```
\ No newline at end of file
diff --git a/docs/configuration/policy/route-map.md b/docs/configuration/policy/route-map.md
new file mode 100644
index 00000000..624b542c
--- /dev/null
+++ b/docs/configuration/policy/route-map.md
@@ -0,0 +1,439 @@
+# Route Map Policy
+
+Route map is a powerfull command, that gives network administrators a very
+useful and flexible tool for traffic manipulation.
+
+## Configuration
+
+### Route Map
+
+```{cfgcmd} set policy route-map \<text\>
+
+   This command creates a new route-map policy, identified by \<text\>.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> description \<text\>
+
+Set description for the route-map policy.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> action \<permit|deny\>
+
+Set action for the route-map policy.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> call \<text\>
+
+Call another route-map policy on match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> continue \<1-65535\>
+
+Jump to a different rule in this route-map on a match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> description \<text\>
+
+Set description for the rule in the route-map policy.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match as-path \<text\>
+
+BGP as-path list to match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match community community-list \<text\>
+
+BGP community-list to match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match community exact-match
+
+Set BGP community-list to exactly match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match extcommunity \<text\>
+
+BGP extended community to match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match interface \<text\>
+
+First hop interface of a route to match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip address access-list \<1-2699\>
+
+IP address of route to match, based on access-list.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip address prefix-list \<text\>
+
+IP address of route to match, based on prefix-list.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip address prefix-len \<0-32\>
+
+IP address of route to match, based on specified prefix-length.
+Note that this can be used for kernel routes only.
+Do not apply to the routes of dynamic routing protocols (e.g. BGP,
+RIP, OSFP), as this can lead to unexpected results..
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip nexthop access-list \<1-2699\>
+
+IP next-hop of route to match, based on access-list.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip nexthop address \<x.x.x.x\>
+
+IP next-hop of route to match, based on ip address.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip nexthop prefix-len \<0-32\>
+
+IP next-hop of route to match, based on prefix length.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip nexthop prefix-list \<text\>
+
+IP next-hop of route to match, based on prefix-list.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip nexthop type \<blackhole\>
+
+IP next-hop of route to match, based on type.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip route-source access-list \<1-2699\>
+
+IP route source of route to match, based on access-list.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip route-source prefix-list \<text\>
+
+IP route source of route to match, based on prefix-list.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ipv6 address access-list \<text\>
+
+IPv6 address of route to match, based on IPv6 access-list.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ipv6 address prefix-list \<text\>
+
+IPv6 address of route to match, based on IPv6 prefix-list.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ipv6 address prefix-len \<0-128\>
+
+IPv6 address of route to match, based on specified prefix-length.
+Note that this can be used for kernel routes only.
+Do not apply to the routes of dynamic routing protocols (e.g. BGP,
+RIP, OSFP), as this can lead to unexpected results..
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ipv6 nexthop \<h:h:h:h:h:h:h:h\>
+
+Nexthop IPv6 address to match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match large-community large-community-list \<text\>
+
+Match BGP large communities.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match local-preference \<0-4294967295\>
+
+Match local preference.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match metric \<1-65535\>
+
+Match route metric.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match origin \<egp|igp|incomplete\>
+
+Boarder Gateway Protocol (BGP) origin code to match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match peer \<x.x.x.x\>
+
+Peer IP address to match.
+```
+
+
+````{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match protocol \<protocol\>
+
+```{eval-rst}
+Source protocol to match.
+ * ``babel`` - Babel routing protocol (Babel)
+ * ``bgp`` - Border Gateway Protocol (BGP)
+ * ``connected`` - Connected routes (directly attached subnet or host)
+ * ``isis`` - Intermediate System to Intermediate System (IS-IS)
+ * ``kernel`` - Kernel routes
+ * ``ospf`` - Open Shortest Path First (OSPFv2)
+ * ``ospfv3`` - Open Shortest Path First (IPv6) (OSPFv3)
+ * ``rip`` - Routing Information Protocol (RIP)
+ * ``ripng`` - Routing Information Protocol next-generation (IPv6) (RIPng)
+ * ``static`` - Statically configured routes
+ * ``table`` - Non-main Kernel Routing Table
+ * ``vnc`` - Virtual Network Control (VNC)
+```
+````
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match rpki \<invalid|notfound|valid\>
+
+Match RPKI validation result.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match source-vrf \<text\>
+
+Source VRF to match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match tag \<1-65535\>
+
+Route tag to match.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> on-match goto \<1-65535\>
+
+Exit policy on match: go to rule <1-65535>
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> on-match next
+
+Exit policy on match: go to next sequence number.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set aggregator \<as|ip\> \<1-4294967295|x.x.x.x\>
+
+BGP aggregator attribute: AS number or IP address of an aggregation.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set as-path exclude \<1-4294967295 | all\>
+
+Drop AS-NUMBER from the BGP AS path.
+
+If ``all`` is specified, remove all AS numbers from the AS_PATH of the BGP
+path's NLRI.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set as-path prepend \<1-4294967295\>
+
+Prepend the given string of AS numbers to the AS_PATH of the BGP path's NLRI.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set as-path prepend-last-as \<n\>
+
+Prepend the existing last AS number (the leftmost ASN) to the AS_PATH.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set atomic-aggregate
+
+BGP atomic aggregate attribute.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set community \<add|replace\> \<community\>
+
+Add or replace BGP community attribute in format ``<0-65535:0-65535>``
+or from well-known community list
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set community none
+
+Delete all BGP communities
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set community delete \<text\>
+
+Delete BGP communities matching the community-list.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set large-community \<add|replace\> \<GA:LDP1:LDP2\>
+
+Add or replace BGP large-community attribute in format
+``<0-4294967295:0-4294967295:0-4294967295>``
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set large-community none
+
+Delete all BGP large-communities
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set large-community delete \<text\>
+
+Delete BGP communities matching the large-community-list.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set extcommunity bandwidth \<1-25600|cumulative|num-multipaths\>
+
+Set extcommunity bandwidth
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set extcommunity bandwidth-non-transitive
+
+The link bandwidth extended community is encoded as non-transitive
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set extcommunity rt \<text\>
+
+Set route target value in format ``<0-65535:0-4294967295>`` or ``<IP:0-65535>``.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set extcommunity soo \<text\>
+
+Set site of origin value in format ``<0-65535:0-4294967295>`` or ``<IP:0-65535>``.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set extcommunity none
+
+Clear all BGP extcommunities.
+```
+
+
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set distance \<0-255\>
+
+Locally significant administrative distance.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set ip-next-hop \<x.x.x.x\>
+
+Nexthop IP address.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set ip-next-hop unchanged
+
+Set the next-hop as unchanged. Pass through the route-map without
+changing its value
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set ip-next-hop peer-address
+
+Set the BGP nexthop address to the address of the peer. For an incoming
+route-map this means the ip address of our peer is used. For an
+outgoing route-map this means the ip address of our self is used to
+establish the peering with our neighbor.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set ipv6-next-hop \<global|local\> \<h:h:h:h:h:h:h:h\>
+
+Nexthop IPv6 address.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set ipv6-next-hop peer-address
+
+Set the BGP nexthop address to the address of the peer. For an incoming
+route-map this means the ip address of our peer is used. For an
+outgoing route-map this means the ip address of our self is used to
+establish the peering with our neighbor.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set ipv6-next-hop prefer-global
+
+For Incoming and Import Route-maps if we receive a v6 global and v6 LL
+address for the route, then prefer to use the global address as the
+nexthop.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set local-preference \<0-4294967295\>
+
+Set BGP local preference attribute.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set metric \<+/-metric|0-4294967295|rtt|+rtt|-rtt\>
+
+Set the route metric. When used with BGP, set the BGP attribute MED
+to a specific value. Use ``+/-`` to add or subtract the specified value
+to/from the existing/MED. Use ``rtt`` to set the MED to the round trip
+time or ``+rtt/-rtt`` to add/subtract the round trip time to/from the MED.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set metric-type \<type-1|type-2\>
+
+Set OSPF external metric-type.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set origin \<igp|egp|incomplete\>
+
+Set BGP origin code.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set originator-id \<x.x.x.x\>
+
+Set BGP originator ID attribute.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set src \<x.x.x.x|h:h:h:h:h:h:h:h\>
+
+Set source IP/IPv6 address for route.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set table \<1-200\>
+
+Set prefixes to table.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set tag \<1-65535\>
+
+Set tag value for routing protocol.
+```
+```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set weight \<0-4294967295\>
+
+Set BGP weight attribute
+```
+
+### List of well-known communities
+
+> - `local-as` - Well-known communities value NO_EXPORT_SUBCONFED 0xFFFFFF03
+> - `no-advertise` - Well-known communities value NO_ADVERTISE 0xFFFFFF02
+> - `no-export` - Well-known communities value NO_EXPORT 0xFFFFFF01
+> - `graceful-shutdown` - Well-known communities value GRACEFUL_SHUTDOWN 0xFFFF0000
+> - `accept-own` - Well-known communities value ACCEPT_OWN 0xFFFF0001
+> - `route-filter-translated-v4` - Well-known communities value ROUTE_FILTER_TRANSLATED_v4 0xFFFF0002
+> - `route-filter-v4` - Well-known communities value ROUTE_FILTER_v4 0xFFFF0003
+> - `route-filter-translated-v6` - Well-known communities value ROUTE_FILTER_TRANSLATED_v6 0xFFFF0004
+> - `route-filter-v6` - Well-known communities value ROUTE_FILTER_v6 0xFFFF0005
+> - `llgr-stale` - Well-known communities value LLGR_STALE 0xFFFF0006
+> - `no-llgr` - Well-known communities value NO_LLGR 0xFFFF0007
+> - `accept-own-nexthop` - Well-known communities value accept-own-nexthop 0xFFFF0008
+> - `blackhole` - Well-known communities value BLACKHOLE 0xFFFF029A
+> - `no-peer` - Well-known communities value NOPEER 0xFFFFFF04
diff --git a/docs/configuration/policy/route.md b/docs/configuration/policy/route.md
new file mode 100644
index 00000000..828bd0f1
--- /dev/null
+++ b/docs/configuration/policy/route.md
@@ -0,0 +1,424 @@
+# Route and Route6 Policy
+
+IPv4 route and IPv6 route policies are defined in this section. These route
+policies can then be associated to interfaces.
+
+## Rule-Sets
+
+A rule-set is a named collection of rules that can be applied to an interface.
+Each rule is numbered, has an action to apply if the rule is matched, and the
+ability to specify the criteria to match. Data packets go through the rules
+from 1 - 999999, at the first match the action of the rule will be executed.
+
+```{cfgcmd} set policy route \<name\> description \<text\>
+
+```
+```{cfgcmd} set policy route6 \<name\> description \<text\>
+
+Provide a rule-set description.
+```
+
+```{cfgcmd} set policy route \<name\> default-log
+```
+
+```{cfgcmd} set policy route6 \<name\> default-log
+
+Option to log packets hitting default-action.
+```
+
+```{cfgcmd} set policy route \<name\> interface \<interface\>
+```
+
+```{cfgcmd} set policy route6 \<name\> interface \<interface\>
+
+Apply routing policy to interface
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> description \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> description \<text\>
+
+Provide a description for each rule.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> log \<enable|disable\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> log \<enable|disable\>
+
+Option to enable or disable log matching rule.
+```
+
+### Matching criteria
+
+There are a lot of matching criteria options available, both for
+`policy route` and `policy route6`. These options are listed
+in this section.
+
+```{cfgcmd} set policy route \<name\> rule \<n\> connection-mark \<1-2147483647\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> connection-mark \<1-2147483647\>
+
+Set match criteria based on connection mark.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> mark \<match_criteria\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> mark \<match_criteria\>
+
+Match based on the firewall mark (fwmark), where \<match_criteria\> can be:
+ * \<0-2147483647\> a single fwmark
+ * !\<0-2147483647\> everything except a single fwmark
+ * &lt;start-end&gt; a range of marks
+ * !&lt;start-end&gt; everything except the range of marks
+
+:::{note}
+When using the ``set table`` or ``set vrf`` commands the mark
+settings are ignored and overwritten with a table-specific mark that
+is set to 0x7FFFFFFF - the id of the table/VRF.
+:::
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> source address \<match_criteria\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> destination address \<match_criteria\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> source address \<match_criteria\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> destination address \<match_criteria\>
+
+Set match criteria based on source or destination ipv4|ipv6 address, where
+&lt;match_criteria&gt; could be:
+```
+
+For ipv4:
+: - \<x.x.x.x>: IP address to match.
+  - \<x.x.x.x/x>: Subnet to match.
+  - \<x.x.x.x>-\<x.x.x.x>: IP range to match.
+  - !\<x.x.x.x>: Match everything except the specified address.
+  - !\<x.x.x.x/x>: Match everything except the specified subnet.
+  - !\<x.x.x.x>-\<x.x.x.x>: Match everything except the specified range.
+
+And for ipv6:
+: - \<h:h:h:h:h:h:h:h>: IPv6 address to match.
+  - \<h:h:h:h:h:h:h:h/x>: IPv6 prefix to match.
+  - \<h:h:h:h:h:h:h:h>-\<h:h:h:h:h:h:h:h>: IPv6 range to match.
+  - !\<h:h:h:h:h:h:h:h>: Match everything except the specified address.
+  - !\<h:h:h:h:h:h:h:h/x>: Match everything except the specified prefix.
+  - !\<h:h:h:h:h:h:h:h>-\<h:h:h:h:h:h:h:h>: Match everything except the
+    specified range.
+
+```{cfgcmd} set policy route \<name\> rule \<n\> source group \<address-group|domain-group|mac-group|network-group|port-group\> \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> destination group \<address-group|domain-group|mac-group|network-group|port-group\> \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> source group \<address-group|domain-group|mac-group|network-group|port-group\> \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> destination group \<address-group|domain-group|mac-group|network-group|port-group\> \<text\>
+
+Set match criteria based on source or destination groups, where &lt;text&gt;
+would be the group name/identifier. Prepend character '!' for inverted
+matching criteria.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> destination port \<match_criteria\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> destination port \<match_criteria\>
+
+Set match criteria based on destination port, where \<match_criteria\> could
+be:
+* &lt;port name&gt;: Named port (any name in /etc/services, e.g., http).
+* \<1-65535\>: Numbered port.
+* &lt;start&gt;-&lt;end&gt;: Numbered port range (e.g., 1001-1005).
+
+Multiple destination ports can be specified as a comma-separated list. The
+whole list can also be "negated" using '!'. For example:
+'!22,telnet,http,123,1001-1005'
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> disable
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> disable
+
+Option to disable rule.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> dscp \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> dscp \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> dscp-exclude \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> dscp-exclude \<text\>
+
+Match based on dscp value criteria. Multiple values from 0 to 63
+and ranges are supported.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> fragment \<match-grag|match-non-frag\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> fragment \<match-grag|match-non-frag\>
+
+Set IP fragment match, where:
+* match-frag: Second and further fragments of fragmented packets.
+* match-non-frag: Head fragments or unfragmented packets.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> icmp \<code | type\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> icmpv6 \<code | type\>
+
+Match based on icmp|icmpv6 code and type.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> icmp type-name \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> icmpv6 type-name \<text\>
+
+Match based on icmp|icmpv6 type-name criteria. Use tab for information
+about what type-name criteria are supported.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> ipsec \<match-ipsec|match-none\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> ipsec \<match-ipsec|match-none\>
+
+Set IPSec inbound match criterias, where:
+* match-ipsec: match inbound IPsec packets.
+* match-none: match inbound non-IPsec packets.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> limit burst \<0-4294967295\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> limit burst \<0-4294967295\>
+
+Set maximum number of packets to alow in excess of rate.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> limit rate \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> limit rate \<text\>
+
+Set maximum average matching rate. Format for rate: integer/time_unit, where
+time_unit could be any one of second, minute, hour or day.For example
+1/second implies rule to be matched at an average of once per second.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> protocol \<text | 0-255 | tcp_udp | all \>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> protocol \<text | 0-255 | tcp_udp | all \>
+
+Match a protocol criteria. A protocol number or a name which is defined in:
+``/etc/protocols``. Special names are ``all`` for all protocols and
+``tcp_udp`` for tcp and udp based packets. The ``!`` negates the selected
+protocol.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> packet-length \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> packet-length \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> packet-length-exclude \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> packet-length-exclude \<text\>
+
+Match based on packet length criteria. Multiple values from 1 to 65535
+and ranges are supported.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> packet-type \[broadcast | host | multicast | other\]
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> packet-type \[broadcast | host | multicast | other\]
+
+Match based on packet type criteria.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> recent count \<1-255\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> recent count \<1-255\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> recent time \<1-4294967295\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> recent time \<1-4294967295\>
+
+Set parameters for matching recently seen sources. This match could be used
+by seeting count (source address seen more than <1-255> times) and/or time
+(source address seen in the last <0-4294967295> seconds).
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> state \<established | invalid | new | related\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> state \<established | invalid | new | related\>
+
+Set match criteria based on session state.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> tcp flags \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> tcp flags \<text\>
+
+Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK
+FIN RST URG PSH ALL. When specifying more than one flag, flags should be
+comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match
+packets with the SYN flag set, and the ACK, FIN and RST flags unset.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time monthdays \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time monthdays \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time startdate \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time startdate \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time starttime \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time starttime \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time stopdate \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time stopdate \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time stoptime \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time stoptime \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time weekdays \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time weekdays \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time utc
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time utc
+
+Time to match the defined rule.
+```
+
+```{cfgcmd} set policy route rule \<n\> ttl \<eq | gt | lt\> \<0-255\>
+
+Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for
+'greater than', and 'lt' stands for 'less than'.
+```
+
+```{cfgcmd} set policy route6 rule \<n\> hop-limit \<eq | gt | lt\> \<0-255\>
+
+Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for
+'greater than', and 'lt' stands for 'less than'.
+```
+
+### Actions
+
+When mathcing all patterns defined in a rule, then different actions can
+be made. This includes droping the packet, modifying certain data, or
+setting a different routing table.
+
+```{cfgcmd} set policy route \<name\> rule \<n\> action drop
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> action drop
+
+Set rule action to drop.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set connection-mark \<1-2147483647\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set connection-mark \<1-2147483647\>
+
+Set a specific connection mark.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set dscp \<0-63\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set dscp \<0-63\>
+
+Set packet modifications: Packet Differentiated Services Codepoint (DSCP)
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set mark \<1-2147483647\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set mark \<1-2147483647\>
+
+Set a specific packet mark.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set table \<main | 1-200\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set table \<main | 1-200\>
+
+Set the routing table to forward packet with.
+
+:::{note}
+When using the ``set table`` or ``set vrf`` commands matching
+against the mark is not possible, because it gets overwritten with a
+table-specific mark that is 0x7FFFFFFF - the id of the table/VRF.
+:::
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set tcp-mss \<500-1460\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set tcp-mss \<500-1460\>
+
+Set packet modifications: Explicitly set TCP Maximum segment size value.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set vrf \<default | text \>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set vrf \<default | text \>
+
+Set the VRF to forward packet with.
+
+:::{note}
+When using the ``set table`` or ``set vrf`` commands matching
+against the mark is not possible, because it gets overwritten with a
+table-specific mark that is 0x7FFFFFFF - the id of the table/VRF.
+:::
+```
\ No newline at end of file
diff --git a/docs/configuration/protocols/arp.md b/docs/configuration/protocols/arp.md
new file mode 100644
index 00000000..7d9bf4f9
--- /dev/null
+++ b/docs/configuration/protocols/arp.md
@@ -0,0 +1,72 @@
+```{eval-rst}
+.. meta::
+   :description: The Address Resolution Protocol (ARP) resolves
+                 network-layer addresses to link-layer MAC addresses.
+   :keywords: arp, network, protocol, mac, address, ipv4, static
+```
+
+(routing_static_arp)=
+
+# ARP
+
+The {abbr}`ARP (Address Resolution Protocol)` resolves IPv4 network layer addresses
+to link layer MAC addresses.
+addresses. This mapping is essential for communication within the Internet
+Protocol suite. ARP was standardized in 1982 by {rfc}`826` (STD 37).
+
+:::{note}
+In Internet Protocol version 6 (IPv6) networks, address resolution is
+performed by the Neighbor Discovery Protocol (NDP).
+:::
+
+Use the following commands to configure or view ARP table entries.
+
+## Configuration
+
+```{eval-rst}
+.. cfgcmd:: set protocols static arp interface <interface> address <host> mac <mac>
+
+   **Configure a static ARP entry on the specified interface.**
+
+   This creates a permanent mapping between an IP address and a MAC address
+   on the specified interface.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show protocols static arp
+
+   Show all ARP table entries across all interfaces.
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show protocols static arp
+      Address                  HWtype  HWaddress           Flags Mask     Iface
+      10.1.1.1                 ether   00:53:00:de:23:2e   C              eth1
+      10.1.1.100               ether   00:53:00:de:23:aa   CM             eth1
+```
+
+```{eval-rst}
+.. opcmd:: show protocols static arp interface <interface>
+
+   Show all ARP table entries for the specific interface.
+
+   Example for ``eth1``:
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show protocols static arp interface eth1
+      Address                  HWtype  HWaddress           Flags Mask     Iface
+      10.1.1.1                 ether   00:53:00:de:23:2e   C              eth1
+      10.1.1.100               ether   00:53:00:de:23:aa   CM             eth1
+```
+
+[arp]: https://en.wikipedia.org/wiki/Address_Resolution_Protocol
+
diff --git a/docs/configuration/protocols/babel.md b/docs/configuration/protocols/babel.md
new file mode 100644
index 00000000..b03e9fa4
--- /dev/null
+++ b/docs/configuration/protocols/babel.md
@@ -0,0 +1,296 @@
+```{eval-rst}
+.. meta::
+   :description: The Babel routing protocol provides robust and efficient
+                 routing for wired and wireless mesh networks.
+   :keywords: babel, routing, protocol, wireless, mesh, network, metric,
+              ipv4, ipv6
+```
+
+(babel)=
+
+# Babel
+
+The Babel protocol provides robust and efficient routing for both wired and
+wireless mesh networks. By default, Babel uses hop-count metrics on wired links
+and a variant of Expected Transmission Count (ETX) on wireless links.
+Administrators can configure Babel to account for radio diversity,
+automatically compute link latency, and include that latency in the routing
+metric. {rfc}`8966` defines the Babel protocol.
+
+Babel is a dual-stack protocol. A single Babel instance routes both IPv4 and
+IPv6 traffic simultaneously.
+
+## General configuration
+
+VyOS does not require a specific command to start the Babel process. The system
+automatically starts the routing process when you configure the first
+Babel-enabled interface.
+
+```{cfgcmd} set protocols babel interface \<interface\>
+
+**Enable Babel routing on the specified interface.**
+
+The system immediately begins sending and receiving Babel packets on this
+interface.
+```
+
+## Optional configuration
+
+```{cfgcmd} set protocols babel parameters diversity
+
+**Enable radio-frequency diversity routing for the Babel process.**
+
+Enabling this feature is highly recommended for networks with many
+wireless nodes.
+
+:::{note}
+When you enable diversity routing, you should also configure the
+``diversity-factor`` and ``channel`` parameters.
+:::
+```
+
+```{cfgcmd} set protocols babel parameters diversity-factor \<1-256\>
+
+**Configure the multiplicative factor for diversity routing, in units of
+1/256.**
+
+Lower multiplicative factors give greater weight to diversity in route
+selection. The default value is 256, which disables diversity routing.
+On nodes with multiple independent radios, configure a value of 128 or less.
+```
+
+```{cfgcmd} set protocols babel parameters resend-delay \<20-655340\>
+
+**Configure the delay in milliseconds before the system resends an
+important request or update.**
+
+The default value is 2000 ms.
+```
+
+```{cfgcmd} set protocols babel parameters smoothing-half-life \<0-65534\>
+
+**Configure the time constant, in seconds, for the smoothing algorithm used
+to implement hysteresis.**
+
+Higher values reduce route oscillation but slightly increase convergence
+time. A value of 0 disables hysteresis and is suitable for wired networks.
+The default is 4 seconds.
+```
+
+## Interfaces configuration
+
+```{cfgcmd} set protocols babel interface \<interface\> type \<auto|wired|wireless\>
+
+**Configure the network type for the Babel-enabled interface.**
+
+Choose from the following:
+
+* ``auto``: Babel automatically detects if an interface is wired or
+  wireless.
+* ``wired``: Babel enables optimizations for wired interfaces.
+* ``wireless``: Babel disables optimizations suitable only for wired
+  interfaces. Specifying wireless is always correct, but may cause slower
+  convergence and increased routing traffic.
+```
+
+```{cfgcmd} set protocols babel interface \<interface\> split-horizon \<default|disable|enable\>
+
+**Configure the split-horizon routing behavior for the specified
+interface.**
+
+Use one of the following options:
+
+* ``default``: Babel automatically enables split-horizon on wired
+  interfaces and disables it on wireless interfaces.
+* ``enable``: Babel enables split-horizon on the interface. This
+  optimization should be used only on symmetric, transitive (wired)
+  networks.
+* ``disable``: Babel disables split-horizon on the interface. Disabling
+  split-horizon is always safe and correct.
+```
+
+```{cfgcmd} set protocols babel interface \<interface\> hello-interval \<20-655340\>
+
+**Configure the interval, in milliseconds, between scheduled hello messages
+on the specified interface.**
+
+On wired links, Babel detects link failures within two hello intervals.
+On wireless links, link quality is reestimated at each interval. The
+default is 4000 ms.
+```
+
+```{cfgcmd} set protocols babel interface \<interface\> update-interval \<20-655340\>
+
+**Configure the interval, in milliseconds, between scheduled routing
+updates on the specified interface.**
+
+Because Babel uses triggered updates extensively, you can increase this
+value on reliable links with minimal packet loss. The default is 20000 ms.
+```
+
+```{cfgcmd} set protocols babel interface \<interface\> rxcost \<1-65534\>
+
+**Configure the base receive cost for the specified interface.**
+
+Babel applies this value based on the configured network type:
+
+* ``wired``: The value is the routing cost advertised to neighboring
+  routers.
+* ``wireless``: The value is a multiplier used to compute the ETX
+  (Expected Transmission Count) reception cost.
+
+The default value is 256.
+```
+
+```{cfgcmd} set protocols babel interface \<interface\> rtt-decay \<1-256\>
+
+**Configure the decay factor for the exponential moving average of RTT
+samples, in units of 1/256.**
+
+Higher values discard older samples faster. The default value is 42.
+```
+
+```{cfgcmd} set protocols babel interface \<interface\> rtt-min \<1-65535\>
+
+**Configure the minimum RTT, in milliseconds, at which the cost to a
+neighbor begins to increase.**
+
+The additional cost is linear in (rtt - rtt-min). The default value is 10 ms.
+```
+
+```{cfgcmd} set protocols babel interface \<interface\> rtt-max \<1-65535\>
+
+**Configure the maximum RTT, in milliseconds, above which the cost to a
+neighbor stops increasing.**
+
+The default value is 120 ms.
+```
+
+```{cfgcmd} set protocols babel interface \<interface\> max-rtt-penalty \<0-65535\>
+
+**Configure the maximum cost added to a neighbor when RTT meets or exceeds
+rtt-max.**
+
+Setting this value to 0 disables RTT-based costs. The default value is 150.
+```
+
+```{cfgcmd} set protocols babel interface \<interface\> enable-timestamps
+
+**Configure adding timestamps to each Hello and IHU message to calculate
+RTT values.**
+
+Enabling timestamps is recommended for tunnel interfaces.
+```
+
+```{cfgcmd} set protocols babel interface \<interface\> channel \<1-254|interfering|noninterfering\>
+
+**Configure the channel identifier that diversity routing uses for the
+specified interface.**
+
+Interfaces interfere with each other based on the assigned channel
+identifier:
+
+* ``1–254``: The interface interferes with interfaces sharing the same
+  channel number and with interfaces configured as ``interfering``.
+* ``interfering``: The interface interferes with all others except those
+  configured as ``noninterfering``.
+* ``noninterfering``: The interface interferes only with itself.
+```
+
+## Redistribution configuration
+
+```{cfgcmd} set protocols babel redistribute \<ipv4|ipv6\> \<route source\>
+
+**Configure the redistribution of routing information from the specified
+route source into the Babel process.**
+
+The following route sources are available:
+
+* **ipv4:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``,
+  ``nhrp``, ``ospf``, ``rip``, ``static``
+* **ipv6:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``,
+  ``nhrp``, ``ospfv3``, ``ripng``, ``static``
+```
+
+```{cfgcmd} set protocols babel distribute-list \<ipv4|ipv6\> access-list \<in|out\> \<number\>
+
+**Configure global Babel route filtering using an access list.**
+
+Specify the direction in which the access list is applied:
+
+* ``in``: Filters incoming routes.
+* ``out``: Filters outgoing routes.
+```
+
+```{cfgcmd} set protocols babel distribute-list \<ipv4|ipv6\> interface \<interface\> access-list \<in|out\> \<number\>
+
+**Configure Babel route filtering on the specified interface using an
+access list.**
+
+Specify the direction in which the access list is applied:
+
+* ``in``: Filters incoming routes.
+* ``out``: Filters outgoing routes.
+```
+
+```{cfgcmd} set protocols babel distribute-list \<ipv4|ipv6\> prefix-list \<in|out\> \<name\>
+
+**Configure global Babel route filtering using a prefix list.**
+
+Specify the direction in which the prefix list is applied:
+
+* ``in``: Filters incoming routes.
+* ``out``: Filters outgoing routes.
+```
+
+```{cfgcmd} set protocols babel distribute-list \<ipv4|ipv6\> interface \<interface\> prefix-list \<in|out\> \<name\>
+
+**Configure Babel route filtering on the specified interface using a
+prefix list.**
+
+Specify the direction in which the prefix list is applied:
+
+* ``in``: Filters incoming routes.
+* ``out``: Filters outgoing routes.
+```
+
+## Configuration example
+
+### Basic two-node babel network
+
+**Goal:** The following example connects two routers (Node 1 and Node 2) via
+their eth0 interfaces and uses the Babel routing protocol to advertise
+(redistribute) each router's locally configured networks (represented by
+loopback addresses) to one another.
+
+**Node 1:**
+
+```none
+# Configure the loopback (local networks) and physical (eth0) addresses
+set interfaces loopback lo address 10.1.1.1/32
+set interfaces loopback lo address fd12:3456:dead:beef::1/128
+set interfaces ethernet eth0 address 192.168.1.1/24
+
+# Enable Babel on the physical link
+set protocols babel interface eth0 type wired
+
+# Instruct Babel to advertise (redistribute) the locally configured networks
+set protocols babel redistribute ipv4 connected
+set protocols babel redistribute ipv6 connected
+```
+
+**Node 2:**
+
+```none
+# Configure the loopback (local networks) and physical (eth0) addresses
+set interfaces loopback lo address 10.2.2.2/32
+set interfaces loopback lo address fd12:3456:beef:dead::2/128
+set interfaces ethernet eth0 address 192.168.1.2/24
+
+# Enable Babel on the physical link
+set protocols babel interface eth0 type wired
+
+# Tell Babel to advertise (redistribute) the locally configured networks
+set protocols babel redistribute ipv4 connected
+set protocols babel redistribute ipv6 connected
+```
diff --git a/docs/configuration/protocols/bfd.md b/docs/configuration/protocols/bfd.md
new file mode 100644
index 00000000..59541abc
--- /dev/null
+++ b/docs/configuration/protocols/bfd.md
@@ -0,0 +1,205 @@
+---
+lastproofread: '2023-01-27'
+---
+
+```{include} /_include/need_improvement.txt
+```
+
+(routing-bfd)=
+
+# BFD
+
+{abbr}`BFD (Bidirectional Forwarding Detection)` is described and extended by
+the following RFCs: {rfc}`5880`, {rfc}`5881` and {rfc}`5883`.
+
+In the age of very fast networks, a second of unreachability may equal millions of lost packets.
+The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast.
+
+BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive.
+
+This allows avoiding the timers defined in BGP and OSPF protocol to expires.
+
+## Configure BFD
+
+```{cfgcmd} set protocols bfd peer \<address\>
+
+Set BFD peer IPv4 address or IPv6 address
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> echo-mode
+
+Enables the echo transmission mode
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> multihop
+
+Allow this BFD peer to not be directly connected
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> source [address \<address\> | interface \<interface\>]
+
+Bind listener to specific interface/address, mandatory for IPv6
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> interval echo-interval \<10-60000\>
+
+The minimal echo receive transmission interval that this system is
+capable of handling
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> interval multiplier \<2-255\>
+
+Remote transmission interval will be multiplied by this value
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> interval [receive | transmit] \<10-60000\>
+
+Interval in milliseconds
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> shutdown
+
+Disable a BFD peer
+```
+
+```{cfgcmd} set protocols bfd peer \<address\> minimum-ttl \<1-254\>
+
+For multi hop sessions only. Configure the minimum expected TTL for an
+incoming BFD control packet.
+
+This feature serves the purpose of thightening the packet validation
+requirements to avoid receiving BFD control packets from other sessions.
+```
+
+### Enable BFD in BGP
+
+```{cfgcmd} set protocols bgp neighbor \<neighbor\> bfd
+
+Enable BFD on a single BGP neighbor
+```
+
+```{cfgcmd} set protocols bgp peer-group \<neighbor\> bfd
+
+Enable BFD on a BGP peer group
+```
+
+### Enable BFD in OSPF
+
+```{cfgcmd} set protocols ospf interface \<interface\> bfd
+
+   Enable BFD for OSPF on an interface
+
+```
+
+```{cfgcmd} set protocols ospfv3 interface \<interface\> bfd
+
+Enable BFD for OSPFv3 on an interface
+```
+
+### Enable BFD in ISIS
+
+```{cfgcmd} set protocols isis \<name\> interface \<interface\> bfd
+
+Enable BFD for ISIS on an interface
+
+```
+
+## Operational Commands
+
+```{opcmd} show bfd peers
+
+   Show all BFD peers
+
+   :::{code-block} none
+   BFD Peers:
+        peer 198.51.100.33 vrf default interface eth4.100
+                ID: 4182341893
+                Remote ID: 12678929647
+                Status: up
+                Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s)
+                Diagnostics: ok
+                Remote diagnostics: ok
+                Local timers:
+                        Receive interval: 300ms
+                        Transmission interval: 300ms
+                        Echo transmission interval: 50ms
+                Remote timers:
+                        Receive interval: 300ms
+                        Transmission interval: 300ms
+                        Echo transmission interval: 0ms
+
+        peer 198.51.100.55 vrf default interface eth4.101
+                ID: 4618932327
+                Remote ID: 3312345688
+                Status: up
+                Uptime: 20 hour(s), 16 minute(s), 19 second(s)
+                Diagnostics: ok
+                Remote diagnostics: ok
+                Local timers:
+                        Receive interval: 300ms
+                        Transmission interval: 300ms
+                        Echo transmission interval: 50ms
+                Remote timers:
+                        Receive interval: 300ms
+                        Transmission interval: 300ms
+                        Echo transmission interval: 0ms
+   :::
+```
+
+## BFD Static Route Monitoring
+
+
+A monitored static route conditions the installation to the RIB on the BFD
+session running state: when BFD session is up the route is installed to RIB,
+but when the BFD session is down it is removed from the RIB.
+
+
+### Configuration
+
+```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd profile \<profile\>
+
+Configure a static route for \<subnet\> using gateway \<address\>
+and use the gateway address as BFD peer destination address.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd multi-hop source \<address\> profile \<profile\>
+
+Configure a static route for \<subnet\> using gateway \<address\>,
+use source address to indentify the peer when is multi-hop session
+and the gateway address as BFD peer destination address.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd profile \<profile\>
+
+Configure a static route for \<subnet\> using gateway \<address\>
+and use the gateway address as BFD peer destination address.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd multi-hop source \<address\> profile \<profile\>
+
+Configure a static route for \<subnet\> using gateway \<address\>,
+use source address to indentify the peer when is multi-hop session
+and the gateway address as BFD peer destination address.
+```
+
+(bfd-operational-commands)=
+
+## Operational Commands
+
+```{opcmd} show bfd static routes
+
+Showing BFD monitored static routes
+
+:::{code-block} none
+Showing BFD monitored static routes:
+
+  Next hops:
+    VRF default IPv4 Unicast:
+        10.10.13.3/32 peer 192.168.2.3 (status: installed)
+        172.16.10.3/32 peer 192.168.10.1 (status: uninstalled)
+
+    VRF default IPv4 Multicast:
+
+    VRF default IPv6 Unicast:
+:::
+```
\ No newline at end of file
diff --git a/docs/configuration/protocols/bgp.md b/docs/configuration/protocols/bgp.md
new file mode 100644
index 00000000..0af79f6e
--- /dev/null
+++ b/docs/configuration/protocols/bgp.md
@@ -0,0 +1,1414 @@
+(routing-bgp)=
+
+# BGP
+
+{abbr}`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols
+and the de facto standard interdomain routing protocol. The latest BGP version
+is 4. BGP-4 is described in {rfc}`1771` and updated by {rfc}`4271`. {rfc}`2858`
+adds multiprotocol support to BGP.
+
+VyOS makes use of {abbr}`FRR (Free Range Routing)` and we would like to thank
+them for their effort!
+
+## Basic Concepts
+
+(bgp-autonomous-systems)=
+
+### Autonomous Systems
+
+From {rfc}`1930`:
+
+> An AS is a connected group of one or more IP prefixes run by one or more
+> network operators which has a SINGLE and CLEARLY DEFINED routing policy.
+
+Each {abbr}`AS (Autonomous System)` has an identifying number associated with it
+called an {abbr}`ASN (Autonomous System Number)`. This is a two octet value
+ranging in value from 1 to 65535. The AS numbers 64512 through 65535 are defined
+as private AS numbers. Private AS numbers must not be advertised on the global
+Internet. The 2-byte AS number range has been exhausted. 4-byte AS numbers are
+specified in {rfc}`6793`, and provide a pool of 4294967296 AS numbers.
+
+The {abbr}`ASN (Autonomous System Number)` is one of the essential elements of
+BGP. BGP is a distance vector routing protocol, and the AS-Path framework
+provides distance vector metric and loop detection to BGP.
+
+```{cfgcmd} set protocols bgp system-as \<asn\>
+
+Set local {abbr}`ASN (Autonomous System Number)` that this router represents.
+This is a a mandatory option!
+```
+
+(bgp-address-families)=
+
+
+### Address Families
+
+
+Multiprotocol extensions enable BGP to carry routing information for multiple
+network layer protocols. BGP supports an Address Family Identifier (AFI) for
+IPv4 and IPv6.
+
+
+(bgp-route-selection)=
+
+
+### Route Selection
+
+
+The route selection process used by FRR's BGP implementation uses the following
+decision criterion, starting at the top of the list and going towards the
+bottom until one of the factors can be used.
+
+
+01. **Weight check**
+
+
+    Prefer higher local weight routes to lower routes.
+
+
+02. **Local preference check**
+
+
+    Prefer higher local preference routes to lower.
+
+
+03. **Local route check**
+
+
+    Prefer local routes (statics, aggregates, redistributed) to received routes.
+
+
+04. **AS path length check**
+
+
+    Prefer shortest hop-count AS_PATHs.
+
+
+05. **Origin check**
+
+
+    Prefer the lowest origin type route. That is, prefer IGP origin routes to
+    EGP, to Incomplete routes.
+
+
+06. **MED check**
+
+
+    Where routes with a MED were received from the same AS, prefer the route
+    with the lowest MED.
+
+
+07. **External check**
+
+
+    Prefer the route received from an external, eBGP peer over routes received
+    from other types of peers.
+
+
+08. **IGP cost check**
+
+
+    Prefer the route with the lower IGP cost.
+
+
+09. **Multi-path check**
+
+
+    If multi-pathing is enabled, then check whether the routes not yet
+    distinguished in preference may be considered equal. If
+    {cfgcmd}`bgp bestpath as-path multipath-relax` is set, all such routes are
+    considered equal, otherwise routes received via iBGP with identical AS_PATHs
+    or routes received from eBGP neighbours in the same AS are considered equal.
+
+
+10. **Already-selected external check**
+
+
+    Where both routes were received from eBGP peers, then prefer the route
+    which is already selected. Note that this check is not applied if
+    {cfgcmd}`bgp bestpath compare-routerid` is configured. This check can
+    prevent some cases of oscillation.
+
+
+11. **Router-ID check**
+
+
+    Prefer the route with the lowest router-ID. If the route has an
+    ORIGINATOR_ID attribute, through iBGP reflection, then that router ID is
+    used, otherwise the router-ID of the peer the route was received from is
+    used.
+
+
+12. **Cluster-List length check**
+
+
+    The route with the shortest cluster-list length is used. The cluster-list
+    reflects the iBGP reflection path the route has taken.
+
+
+13. **Peer address**
+
+
+    Prefer the route received from the peer with the higher transport layer
+    address, as a last-resort tie-breaker.
+
+
+(bgp-capability-negotiation)=
+
+
+### Capability Negotiation
+
+
+When adding IPv6 routing information exchange feature to BGP. There were some
+proposals. {abbr}`IETF (Internet Engineering Task Force)`
+{abbr}`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol
+Extension for BGP. The specification is described in {rfc}`2283`. The protocol
+does not define new protocols. It defines new attributes to existing BGP. When
+it is used exchanging IPv6 routing information it is called BGP-4+. When it is
+used for exchanging multicast routing information it is called MBGP.
+
+
+*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports
+the protocol, *bgpd* can exchange IPv6 and/or multicast routing information.
+
+
+Traditional BGP did not have the feature to detect a remote peer's
+capabilities, e.g. whether it can handle prefix types other than IPv4 unicast
+routes. This was a big problem using Multiprotocol Extension for BGP in an
+operational network. {rfc}`2842` adopted a feature called Capability
+Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's
+capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd*
+does not send these Capability Negotiation packets (at least not unless other
+optional BGP features require capability negotiation).
+
+
+By default, FRR will bring up peering with minimal common capability for the
+both sides. For example, if the local router has unicast and multicast
+capabilities and the remote router only has unicast capability the local router
+will establish the connection with unicast only capability. When there are no
+common capabilities, FRR sends Unsupported Capability error and then resets the
+connection.
+
+
+## Configuration
+
+
+(bgp-router-configuration)=
+
+
+### BGP Router Configuration
+
+
+First of all you must configure BGP router with the {abbr}`ASN (Autonomous
+System Number)`. The AS number is an identifier for the autonomous system.
+The BGP protocol uses the AS number for detecting whether the BGP connection
+is internal or external. VyOS does not have a special command to start the BGP
+process. The BGP process starts when the first neighbor is configured.
+
+```{cfgcmd} set protocols bgp system-as \<asn\>
+
+Set local autonomous system number that this router represents. This is a
+mandatory option!
+```
+
+#### Peers Configuration
+
+
+##### Defining Peers
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as \<asn\>
+
+This command creates a new neighbor whose remote-as is \<asn\>. The neighbor
+address can be an IPv4 address or an IPv6 address or an interface to use
+for the connection. The command is applicable for peer and peer group.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as internal
+
+Create a peer as you would when you specify an ASN, except that if the
+peers ASN is different than mine as specified under the {cfgcmd}`protocols
+bgp <asn>` command the connection will be denied.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as external
+
+Create a peer as you would when you specify an ASN, except that if the
+peers ASN is the same as mine as specified under the {cfgcmd}`protocols
+bgp <asn>` command the connection will be denied.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as auto
+
+Create a peer as you would when you specify an ASN, except that the peers
+remote ASN is detected automatically from the OPEN message.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> local-role \<role\> [strict]
+
+BGP roles are defined in RFC {rfc}`9234` and provide an easy way to
+add route leak prevention, detection and mitigation. The local Role
+value is negotiated with the new BGP Role capability which has a
+built-in check of the corresponding value. In case of a mismatch the
+new OPEN Roles Mismatch Notification <2, 11> would be sent.
+The correct Role pairs are:
+
+Provider - Customer
+
+Peer - Peer
+
+RS-Server - RS-Client
+
+If {cfgcmd}`strict` is set the BGP session won’t become established
+until the BGP neighbor sets local Role on its side. This
+configuration parameter is defined in RFC {rfc}`9234` and is used to
+enforce the corresponding configuration at your counter-parts side.
+
+Routes that are sent from provider, rs-server, or the peer local-role
+(or if received by customer, rs-client, or the peer local-role) will
+be marked with a new Only to Customer (OTC) attribute.
+
+Routes with this attribute can only be sent to your neighbor if your
+local-role is provider or rs-server. Routes with this attribute can
+be received only if your local-role is customer or rs-client.
+
+In case of peer-peer relationship routes can be received only if OTC
+value is equal to your neighbor AS number.
+
+All these rules with OTC will help to detect and mitigate route leaks
+and happen automatically if local-role is set.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> shutdown
+
+This command disable the peer or peer group. To reenable the peer use
+the delete form of this command.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> description \<text\>
+
+Set description of the peer or peer group.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> update-source \<address|interface\>
+
+Specify the IPv4 source address to use for the BGP session to this neighbor,
+may be specified as either an IPv4 address directly or as an interface name.
+```
+
+(bgp-capability-negotiation-1)=
+
+
+##### Capability Negotiation
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> capability dynamic
+
+This command would allow the dynamic update of capabilities over an
+established BGP session.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> capability extended-nexthop
+
+Allow bgp to negotiate the extended-nexthop capability with it’s peer.
+If you are peering over a IPv6 Link-Local address then this capability
+is turned on automatically. If you are peering over a IPv6 Global Address
+then turning on this command will allow BGP to install IPv4 routes with
+IPv6 nexthops if you do not have IPv4 configured on interfaces.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> disable-capability-negotiation
+
+Suppress sending Capability Negotiation as OPEN message optional
+parameter to the peer. This command only affects the peer is
+configured other than IPv4 unicast configuration.
+
+When remote peer does not have capability negotiation feature,
+remote peer will not send any capabilities at all. In that case,
+bgp configures the peer with configured capabilities.
+
+You may prefer locally configured capabilities more than the negotiated
+capabilities even though remote peer sends capabilities. If the peer is
+configured by {cfgcmd}`override-capability`, VyOS ignores received
+capabilities then override negotiated capabilities with configured values.
+
+Additionally you should keep in mind that this feature fundamentally
+disables the ability to use widely deployed BGP features. BGP unnumbered,
+hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities,
+and graceful restart.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> override-capability
+
+This command allow override the result of Capability Negotiation with
+local configuration. Ignore remote peer’s capability value.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> strict-capability-match
+
+This command forces strictly compare remote capabilities and local
+capabilities. If capabilities are different, send Unsupported Capability
+error then reset connection.
+
+You may want to disable sending Capability Negotiation OPEN message
+optional parameter to the peer when remote peer does not implement
+Capability Negotiation. Please use {cfgcmd}`disable-capability-negotiation`
+command to disable the feature.
+```
+
+##### Peer Parameters
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> allowas-in number \<number\>
+
+This command accept incoming routes with AS path containing AS
+number with the same value as the current system AS. This is
+used when you want to use the same AS number in your sites,
+but you can’t connect them directly.
+
+   The number parameter (1-10) configures the amount of accepted
+   occurences of the system AS number in AS path.
+
+   This command is only allowed for eBGP peers. It is not applicable
+   for peer groups.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> as-override
+
+This command override AS number of the originating router with
+the local AS number.
+
+Usually this configuration is used in PEs (Provider Edge) to
+replace the incoming customer AS number so the connected CE (
+Customer Edge) can use the same AS number as the other customer
+sites. This allows customers of the provider network to use the
+same AS number across their sites.
+
+This command is only allowed for eBGP peers.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> attribute-unchanged \<as-path|med|next-hop\>
+
+This command specifies attributes to be left unchanged for
+advertisements sent to a peer or peer group.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> maximum-prefix \<number\>
+
+This command specifies a maximum number of prefixes we can receive
+from a given peer. If this number is exceeded, the BGP session
+will be destroyed. The number range is 1 to 4294967295.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> nexthop-self
+
+This command forces the BGP speaker to report itself as the
+next hop for an advertised route it advertised to a neighbor.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> remove-private-as
+
+This command removes the private ASN of routes that are advertised
+to the configured peer. It removes only private ASNs on routes
+advertised to EBGP peers.
+
+If the AS-Path for the route has only private ASNs, the private
+ASNs are removed.
+
+If the AS-Path for the route has a private ASN between public
+ASNs, it is assumed that this is a design choice, and the
+private ASN is not removed.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> soft-reconfiguration inbound
+
+Changes in BGP policies require the BGP session to be cleared. Clearing has a
+large negative impact on network operations. Soft reconfiguration enables you
+to generate inbound updates from a neighbor, change and activate BGP policies
+without clearing the BGP session.
+
+This command specifies that route updates received from this neighbor will be
+stored unmodified, regardless of the inbound policy. When inbound soft
+reconfiguration is enabled, the stored updates are processed by the new
+policy configuration to create new inbound updates.
+
+:::{note}
+Storage of route updates uses memory. If you enable soft
+reconfiguration inbound for multiple neighbors, the amount of memory used
+can become significant.
+:::
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> weight \<number\>
+
+This command specifies a default weight value for the neighbor’s
+routes. The number range is 1 to 65535.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> advertisement-interval \<seconds\>
+
+This command specifies the minimum route advertisement interval for
+the peer. The interval value is 0 to 600 seconds, with the default
+advertisement interval being 0.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> disable-connected-check
+
+This command allows peerings between directly connected eBGP peers
+using loopback addresses without adjusting the default TTL of 1.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> disable-send-community \<extended|standard\>
+
+This command specifies that the community attribute should not be sent
+in route updates to a peer. By default community attribute is sent.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> ebgp-multihop \<number\>
+
+This command allows sessions to be established with eBGP neighbors
+when they are multiple hops away. When the neighbor is not directly
+connected and this knob is not enabled, the session will not establish.
+The number of hops range is 1 to 255. This command is mutually
+exclusive with {cfgcmd}`ttl-security hops`.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> local-as \<asn\> [no-prepend] [replace-as]
+
+Specify an alternate AS for this BGP process when interacting with
+the specified peer or peer group. With no modifiers, the specified
+local-as is prepended to the received AS_PATH when receiving routing
+updates from the peer, and prepended to the outgoing AS_PATH (after
+the process local AS) when transmitting local routes to the peer.
+
+If the {cfgcmd}`no-prepend` attribute is specified, then the supplied
+local-as is not prepended to the received AS_PATH.
+
+If the {cfgcmd}`replace-as` attribute is specified, then only the supplied
+local-as is prepended to the AS_PATH when transmitting local-route
+updates to this peer.
+
+:::{note}
+This command is only allowed for eBGP peers.
+:::
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> passive
+
+Configures the BGP speaker so that it only accepts inbound connections
+from, but does not initiate outbound connections to the peer or peer group.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> password \<text\>
+
+This command specifies a MD5 password to be used with the tcp socket that
+is being used to connect to the remote peer.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> ttl-security hops \<number\>
+
+This command enforces Generalized TTL Security Mechanism (GTSM),
+as specified in {rfc}`5082`. With this command, only neighbors
+that are specified number of hops away will be allowed to
+become neighbors. The number of hops range is 1 to 254. This
+command is mutually exclusive with {cfgcmd}`ebgp-multihop`.
+```
+
+##### Peer Groups
+
+Peer groups are used to help improve scaling by generating the same update
+information to all members of a peer group. Note that this means that the
+routes generated by a member of a peer group will be sent back to that
+originating peer with the originator identifier attribute set to indicated
+the originating peer. All peers not associated with a specific peer group
+are treated as belonging to a default peer group, and will share updates.
+
+```{cfgcmd} set protocols bgp peer-group \<name\>
+
+   This command defines a new peer group. You can specify to the group the same
+   parameters that you can specify for specific neighbors.
+
+   :::{note}
+   If you apply a parameter to an individual neighbor IP address, you
+   override the action defined for a peer group that includes that IP
+   address.
+   :::
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> peer-group \<name\>
+
+This command bind specific peer to peer group with a given name.
+```
+
+#### Network Advertisement Configuration
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> network \<prefix\>
+
+This command is used for advertising IPv4 or IPv6 networks.
+
+   :::{note}
+   By default, the BGP prefix is advertised even if it's not present
+   in the routing table. This behaviour differs from the implementation of
+   some vendors.
+   :::
+```
+
+
+```{cfgcmd} set protocols bgp parameters network-import-check
+
+This configuration modifies the behavior of the network statement. If you
+have this configured the underlying network must exist in the routing table.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> default-originate [route-map \<name\>]
+
+By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is
+in routing table. When you want to announce default routes to the peer, use
+this command. Using optional argument {cfgcmd}`route-map` you can inject the
+default route to given neighbor only if the conditions in the route map are
+met.
+```
+
+#### Route Aggregation Configuration
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> aggregate-address \<prefix\>
+
+This command specifies an aggregate address. The router will also
+announce longer-prefixes inside of the aggregate address.
+```
+
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> aggregate-address \<prefix\> as-set
+
+This command specifies an aggregate address with a mathematical set of
+autonomous systems. This command summarizes the AS_PATH attributes of
+all the individual routes.
+```
+
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> aggregate-address \<prefix\> summary-only
+
+This command specifies an aggregate address and provides that
+longer-prefixes inside of the aggregate address are suppressed
+before sending BGP updates out to peers.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> unsuppress-map \<name\>
+
+This command applies route-map to selectively unsuppress prefixes
+suppressed by summarisation.
+```
+
+#### Redistribution Configuration
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> redistribute <route source>
+
+This command redistributes routing information from the given route source
+to the BGP process. There are six modes available for route source:
+connected, kernel, ospf, rip, static, table.
+```
+
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> redistribute <route source> metric \<number\>
+
+This command specifies metric (MED) for redistributed routes. The
+metric range is 0 to 4294967295. There are six modes available for
+route source: connected, kernel, ospf, rip, static, table.
+```
+
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> redistribute <route source> route-map \<name\>
+
+This command allows to use route map to filter redistributed routes.
+There are six modes available for route source: connected, kernel,
+ospf, rip, static, table.
+```
+
+#### General Configuration
+##### Common parameters
+
+```{cfgcmd} set protocols bgp parameters allow-martian-nexthop
+
+   When a peer receives a martian nexthop as part of the NLRI for a route
+   permit the nexthop to be used as such, instead of rejecting and resetting
+   the connection.
+```
+
+
+```{cfgcmd} set protocols bgp parameters router-id \<id\>
+
+This command specifies the router-ID. If router ID is not specified it will
+use the highest interface IP address.
+```
+
+
+```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> maximum-paths \<ebgp|ibgp\> \<number\>
+
+This command defines the maximum number of parallel routes that
+the BGP can support. In order for BGP to use the second path, the
+following attributes have to match: Weight, Local Preference, AS
+Path (both AS number and AS path length), Origin code, MED, IGP
+metric. Also, the next hop address for each path must be different.
+```
+
+
+```{cfgcmd} set protocols bgp parameters no-hard-administrative-reset
+
+Do not send Hard Reset CEASE Notification for "Administrative Reset"
+events. When set and Graceful Restart Notification capability is exchanged
+between the peers, Graceful Restart procedures apply, and routes will be retained.
+```
+
+
+```{cfgcmd} set protocols bgp parameters log-neighbor-changes
+
+This command enable logging neighbor up/down changes and reset reason.
+```
+
+
+```{cfgcmd} set protocols bgp parameters no-client-to-client-reflection
+
+This command disables route reflection between route reflector clients.
+By default, the clients of a route reflector are not required to be
+fully meshed and the routes from a client are reflected to other clients.
+However, if the clients are fully meshed, route reflection is not required.
+In this case, use the {cfgcmd}`no-client-to-client-reflection` command
+to disable client-to-client reflection.
+```
+
+
+```{cfgcmd} set protocols bgp parameters no-fast-external-failover
+
+Disable immediate session reset if peer's connected link goes down.
+```
+
+
+```{cfgcmd} set protocols bgp parameters no-ipv6-auto-ra
+
+By default, FRR sends router advertisement packets when Extended Next Hop is
+on or when a connection is established directly using the device name (Unnumbered BGP).
+Setting this option prevents FRR from sending router advertisement packets, but could break Unnumbered BGP.
+```
+
+
+```{cfgcmd} set protocols bgp listen range \<prefix\> peer-group \<name\>
+
+This command is useful if one desires to loosen the requirement for BGP
+to have strictly defined neighbors. Specifically what is allowed is for
+the local router to listen to a range of IPv4 or IPv6 addresses defined
+by a prefix and to accept BGP open messages. When a TCP connection
+(and subsequently a BGP open message) from within this range tries to
+connect the local router then the local router will respond and connect
+with the parameters that are defined within the peer group. One must define
+a peer-group for each range that is listed. If no peer-group is defined
+then an error will keep you from committing the configuration.
+```
+
+
+```{cfgcmd} set protocols bgp listen limit \<number\>
+
+This command goes hand in hand with the listen range command to limit the
+amount of BGP neighbors that are allowed to connect to the local router.
+The limit range is 1 to 5000.
+```
+
+
+```{cfgcmd} set protocols bgp parameters ebgp-requires-policy
+
+This command changes the eBGP behavior of FRR. By default FRR enables
+{rfc}`8212` functionality which affects how eBGP routes are advertised,
+namely no routes are advertised across eBGP sessions without some
+sort of egress route-map/policy in place. In VyOS however we have this
+RFC functionality disabled by default so that we can preserve backwards
+compatibility with older versions of VyOS. With this option one can
+enable {rfc}`8212` functionality to operate.
+```
+
+
+```{cfgcmd} set protocols bgp parameters labeled-unicast \<explicit-null | ipv4-explicit-null | ipv6-explicit-null\>
+
+By default, locally advertised prefixes use the implicit-null label to
+encode in the outgoing NLRI.
+
+The following command uses the explicit-null label value for all the
+BGP instances.
+```
+
+##### Administrative Distance
+
+```{cfgcmd} set protocols bgp parameters distance global \<external|internal|local\> \<distance\>
+
+This command change distance value of BGP. The arguments are the distance
+values for external routes, internal routes and local routes respectively.
+The distance range is 1 to 255.
+```
+
+
+```{cfgcmd} set protocols bgp parameters distance prefix \<subnet\> distance \<distance\>
+
+This command sets the administrative distance for a particular route. The
+distance range is 1 to 255.
+
+:::{note}
+Routes with a distance of 255 are effectively disabled and not
+installed into the kernel.
+:::
+```
+
+##### Timers
+
+```{cfgcmd} set protocols bgp timers holdtime \<seconds\>
+
+   This command specifies hold-time in seconds. The timer range is
+   4 to 65535. The default value is 180 second. If you set value to 0
+   VyOS will not hold routes.
+```
+
+
+```{cfgcmd} set protocols bgp timers keepalive \<seconds\>
+
+This command specifies keep-alive time in seconds. The timer
+can range from 4 to 65535. The default value is 60 second.
+```
+
+##### Route Dampening
+
+When a route fails, a routing update is sent to withdraw the route from the
+network's routing tables. When the route is re-enabled, the change in
+availability is also advertised. A route that continually fails and returns
+requires a great deal of network traffic to update the network about the
+route's status.
+
+Route dampening wich described in {rfc}`2439` enables you to identify routes
+that repeatedly fail and return. If route dampening is enabled, an unstable
+route accumulates penalties each time the route fails and returns. If the
+accumulated penalties exceed a threshold, the route is no longer advertised.
+This is route suppression. Routes that have been suppressed are re-entered
+into the routing table only when the amount of their penalty falls below a
+threshold.
+
+A penalty of 1000 is assessed each time the route fails. When the penalties
+reach a predefined threshold (suppress-value), the router stops advertising
+the route.
+
+Once a route is assessed a penalty, the penalty is decreased by half each time
+a predefined amount of time elapses (half-life-time). When the accumulated
+penalties fall below a predefined threshold (reuse-value), the route is
+unsuppressed and added back into the BGP routing table.
+
+No route is suppressed indefinitely. Maximum-suppress-time defines the maximum
+time a route can be suppressed before it is re-advertised.
+
+```{cfgcmd} set protocols bgp parameters dampening half-life \<minutes\>
+
+This command defines the amount of time in minutes after
+which a penalty is reduced by half. The timer range is
+10 to 45 minutes.
+```
+
+
+```{cfgcmd} set protocols bgp parameters dampening re-use \<seconds\>
+
+This command defines the accumulated penalty amount at which the
+route is re-advertised. The penalty range is 1 to 20000.
+```
+
+
+```{cfgcmd} set protocols bgp parameters dampening start-suppress-time \<seconds\>
+
+This command defines the accumulated penalty amount at which the
+route is suppressed. The penalty range is 1 to 20000.
+```
+
+
+```{cfgcmd} set protocols bgp parameters dampening max-suppress-time \<seconds\>
+
+This command defines the maximum time in minutes that a route is
+suppressed. The timer range is 1 to 255 minutes.
+```
+
+#### Route Selection Configuration
+
+```{cfgcmd} set protocols bgp parameters always-compare-med
+
+   This command provides to compare the MED on routes, even when they were
+   received from different neighbouring ASes. Setting this option makes the
+   order of preference of routes more defined, and should eliminate MED
+   induced oscillations.
+```
+
+
+```{cfgcmd} set protocols bgp parameters bestpath as-path confed
+
+This command specifies that the length of confederation path sets and
+sequences should be taken into account during the BGP best path
+decision process.
+```
+
+
+```{cfgcmd} set protocols bgp parameters bestpath as-path multipath-relax
+
+This command specifies that BGP decision process should consider paths
+of equal AS_PATH length candidates for multipath computation. Without
+the knob, the entire AS_PATH must match for multipath computation.
+```
+
+
+```{cfgcmd} set protocols bgp parameters bestpath as-path ignore
+
+Ignore AS_PATH length when selecting a route
+```
+
+
+```{cfgcmd} set protocols bgp parameters bestpath compare-routerid
+
+Ensure that when comparing routes where both are equal on most metrics,
+including local-pref, AS_PATH length, IGP cost, MED, that the tie is
+broken based on router-ID.
+
+If this option is enabled, then the already-selected check, where
+already selected eBGP routes are preferred, is skipped.
+
+If a route has an ORIGINATOR_ID attribute because it has been reflected,
+that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer
+the route was received from will be used.
+
+The advantage of this is that the route-selection (at this point) will
+be more deterministic. The disadvantage is that a few or even one lowest-ID
+router may attract all traffic to otherwise-equal paths because of this
+check. It may increase the possibility of MED or IGP oscillation, unless
+other measures were taken to avoid these. The exact behaviour will be
+sensitive to the iBGP and reflection topology.
+```
+
+
+```{cfgcmd} set protocols bgp parameters bestpath med confed
+
+This command specifies that BGP considers the MED when comparing routes
+originated from different sub-ASs within the confederation to which this
+BGP speaker belongs. The default state, where the MED attribute is not
+considered.
+```
+
+
+```{cfgcmd} set protocols bgp parameters bestpath med missing-as-worst
+
+This command specifies that a route with a MED is always considered to be
+better than a route without a MED by causing the missing MED attribute to
+have a value of infinity. The default state, where the missing MED
+attribute is considered to have a value of zero.
+```
+
+
+```{cfgcmd} set protocols bgp parameters default local-pref <local-pref value>
+
+This command specifies the default local preference value. The local
+preference range is 0 to 4294967295.
+```
+
+
+```{cfgcmd} set protocols bgp parameters deterministic-med
+
+This command provides to compare different MED values that advertised by
+neighbours in the same AS for routes selection. When this command is
+enabled, routes from the same autonomous system are grouped together, and
+the best entries of each group are compared.
+```
+
+
+```{cfgcmd} set protocols bgp address-family ipv4-unicast network \<prefix\> backdoor
+
+This command allows the router to prefer route to specified prefix learned
+via IGP through backdoor link instead of a route to the same prefix learned
+via EBGP.
+```
+
+#### Route Filtering Configuration
+
+In order to control and modify routing information that is exchanged between
+peers you can use route-map, filter-list, prefix-list, distribute-list.
+
+For inbound updates the order of preference is:
+
+> - route-map
+> - filter-list
+> - prefix-list, distribute-list
+
+For outbound updates the order of preference is:
+> - prefix-list, distribute-list
+> - filter-list
+> - route-map
+>
+> :::{note}
+> The attributes {cfgcmd}`prefix-list` and {cfgcmd}`distribute-list`
+> are mutually exclusive, and only one command (distribute-list or
+> prefix-list) can be applied to each inbound or outbound direction for a
+> particular neighbor.
+> :::
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> distribute-list \<export|import\> \<number\>
+
+This command applies the access list filters named in \<number\> to the
+specified BGP neighbor to restrict the routing information that BGP learns
+and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import`
+specify the direction in which the access list are applied.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> prefix-list \<export|import\> \<name\>
+
+This command applies the prfefix list filters named in \<name\> to the
+specified BGP neighbor to restrict the routing information that BGP learns
+and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import`
+specify the direction in which the prefix list are applied.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> route-map \<export|import\> \<name\>
+
+This command applies the route map named in \<name\> to the specified BGP
+neighbor to control and modify routing information that is exchanged
+between peers. The arguments {cfgcmd}`export` and {cfgcmd}`import`
+specify the direction in which the route map are applied.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> filter-list \<export|import\> \<name\>
+
+This command applies the AS path access list filters named in \<name\> to the
+specified BGP neighbor to restrict the routing information that BGP learns
+and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import`
+specify the direction in which the AS path access list are applied.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> capability orf \<receive|send\>
+
+This command enables the ORF capability (described in {rfc}`5291`) on the
+local router, and enables ORF capability advertisement to the specified BGP
+peer. The {cfgcmd}`receive` keyword configures a router to advertise ORF
+receive capabilities. The {cfgcmd}`send` keyword configures a router to
+advertise ORF send capabilities. To advertise a filter from a sender, you
+must create an IP prefix list for the specified BGP peer applied in inbound
+derection.
+```
+
+
+```{cfgcmd} set protocols bgp neighbor \<address|interface\> solo
+
+This command prevents from sending back prefixes learned from the neighbor.
+```
+
+#### BGP Scaling Configuration
+
+
+BGP routers connected inside the same AS through BGP belong to an internal BGP
+session, or IBGP. In order to prevent routing table loops, IBGP speaker does
+not advertise IBGP-learned routes to other IBGP speaker (Split Horizon
+mechanism). As such, IBGP requires a full mesh of all peers. For large
+networks, this quickly becomes unscalable.
+
+
+There are two ways that help us to mitigate the BGPs full-mesh requirement in
+a network:
+
+
+> - Using BGP route-reflectors
+> - Using BGP confederation
+
+
+##### Route Reflector Configuration
+
+
+Introducing route reflectors removes the need for the full-mesh. When you
+configure a route reflector you have to tell the router whether the other IBGP
+router is a client or non-client. A client is an IBGP router that the route
+reflector will “reflect” routes to, the non-client is just a regular IBGP
+neighbor. Route reflectors mechanism is described in {rfc}`4456` and updated
+by {rfc}`7606`.
+
+```{cfgcmd} set protocols bgp neighbor \<address\> address-family \<ipv4-unicast|ipv6-unicast\> route-reflector-client
+
+This command specifies the given neighbor as route reflector client.
+```
+
+
+```{cfgcmd} set protocols bgp parameters cluster-id \<id\>
+
+This command specifies cluster ID which identifies a collection of route
+reflectors and their clients, and is used by route reflectors to avoid
+looping. By default cluster ID is set to the BGP router id value, but can be
+set to an arbitrary 32-bit value.
+```
+
+##### Confederation Configuration
+
+A BGP confederation divides our AS into sub-ASes to reduce the number of
+required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but
+between these sub-ASes we use something that looks like EBGP but behaves like
+IBGP (called confederation BGP). Confederation mechanism is described in
+{rfc}`5065`
+
+```{cfgcmd} set protocols bgp parameters confederation identifier \<asn\>
+
+This command specifies a BGP confederation identifier. \<asn\> is the number
+of the autonomous system that internally includes multiple sub-autonomous
+systems (a confederation).
+```
+
+
+```{cfgcmd} set protocols bgp parameters confederation peers \<nsubasn\>
+
+This command sets other confederations \<nsubasn\> as members of autonomous
+system specified by {cfgcmd}`confederation identifier <asn>`.
+```
+
+## Operational Mode Commands
+### Show
+
+```{opcmd} show bgp \<ipv4|ipv6\>
+
+   This command displays all entries in BGP routing table.
+```
+
+
+```none
+BGP table version is 10, local router ID is 10.0.35.3, vrf id 0
+Default local pref 100, local AS 65000
+Status codes:  s suppressed, d damped, h history, * valid, > best, = multipath,
+               i internal, r RIB-failure, S Stale, R Removed
+Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self
+Origin codes:  i - IGP, e - EGP, ? - incomplete
+RPKI validation codes: V valid, I invalid, N Not found
+
+   Network          Next Hop            Metric LocPrf Weight Path
+*> 198.51.100.0/24  10.0.34.4                0             0 65004 i
+*> 203.0.113.0/24   10.0.35.5                0             0 65005 i
+
+Displayed  2 routes and 2 total paths
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> \<address|prefix\>
+
+This command displays information about the particular entry in the BGP
+routing table.
+```
+
+
+```none
+BGP routing table entry for 198.51.100.0/24
+Paths: (1 available, best #1, table default)
+  Advertised to non peer-group peers:
+  10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5
+  65004
+    10.0.34.4 from 10.0.34.4 (10.0.34.4)
+      Origin IGP, metric 0, valid, external, best (First path received)
+      Last update: Wed Jan  6 12:18:53 2021
+```
+
+
+```{opcmd} show bgp cidr-only
+
+This command displays routes with classless interdomain routing (CIDR).
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> community \<value\>
+
+This command displays routes that belong to specified BGP communities.
+Valid value is a community number in the range from 1 to 4294967200,
+or AA:NN (autonomous system-community number/2-byte number), no-export,
+local-as, or no-advertise.
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> community-list \<name\>
+
+This command displays routes that are permitted by the BGP
+community list.
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> dampening dampened-paths
+
+This command displays BGP dampened routes.
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> dampening flap-statistics
+
+This command displays information about flapping BGP routes.
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> filter-list \<name\>
+
+This command displays BGP routes allowed by the specified AS Path
+access list.
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> advertised-routes
+
+This command displays BGP routes advertised to a neighbor.
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> received-routes
+
+This command displays BGP routes originating from the specified BGP
+neighbor before inbound policy is applied. To use this command inbound
+soft reconfiguration must be enabled.
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> routes
+
+This command displays BGP received-routes that are accepted after filtering.
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> dampened-routes
+
+This command displays dampened routes received from BGP neighbor.
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> regexp \<text\>
+
+This command displays information about BGP routes whose AS path
+matches the specified regular expression.
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> summary
+
+This command displays the status of all BGP connections.
+```
+
+
+```none
+IPv4 Unicast Summary:
+BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0
+BGP table version 11
+RIB entries 5, using 920 bytes of memory
+Peers 4, using 82 KiB of memory
+
+Neighbor        V         AS MsgRcvd MsgSent   TblVer  InQ OutQ  Up/Down State/PfxRcd
+10.0.13.1       4      65000     148     159        0    0    0 02:16:01            0
+10.0.23.2       4      65000     136     143        0    0    0 02:13:21            0
+10.0.34.4       4      65004     161     163        0    0    0 02:16:01            1
+10.0.35.5       4      65005     162     166        0    0    0 02:16:01            1
+
+Total number of neighbors 4
+```
+
+### Reset
+
+```{opcmd} reset bgp \<ipv4|ipv6\> \<address\> [soft [in|out]]
+
+This command resets BGP connections to the specified neighbor IP address.
+With argument {cfgcmd}`soft` this command initiates a soft reset. If
+you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both
+inbound and outbound soft reconfiguration are triggered.
+```
+
+
+```{opcmd} reset bgp all
+
+This command resets all BGP connections of given router.
+```
+
+
+```{opcmd} reset bgp \<ipv4|ipv6\> external
+
+This command resets all external BGP peers of given router.
+```
+
+
+```{opcmd} reset bgp \<ipv4|ipv6\> peer-group \<name\> [soft [in|out]]
+
+This command resets BGP connections to the specified peer group.
+With argument {cfgcmd}`soft` this command initiates a soft reset. If
+you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both
+inbound and outbound soft reconfiguration are triggered.
+```
+
+## Examples
+### IPv4 peering
+
+A simple eBGP configuration:
+
+**Node 1:**
+
+```none
+set protocols bgp system-as 65534
+set protocols bgp neighbor 192.168.0.2 ebgp-multihop '2'
+set protocols bgp neighbor 192.168.0.2 remote-as '65535'
+set protocols bgp neighbor 192.168.0.2 update-source '192.168.0.1'
+set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast
+set protocols bgp address-family ipv4-unicast network '172.16.0.0/16'
+set protocols bgp parameters router-id '192.168.0.1'
+```
+
+**Node 2:**
+
+```none
+set protocols bgp system-as 65535
+set protocols bgp neighbor 192.168.0.1 ebgp-multihop '2'
+set protocols bgp neighbor 192.168.0.1 remote-as '65534'
+set protocols bgp neighbor 192.168.0.1 update-source '192.168.0.2'
+set protocols bgp neighbor 192.168.0.1 address-family ipv4-unicast
+set protocols bgp address-family ipv4-unicast network '172.17.0.0/16'
+set protocols bgp parameters router-id '192.168.0.2'
+```
+
+Don't forget, the CIDR declared in the network statement MUST **exist in your
+routing table (dynamic or static), the best way to make sure that is true is
+creating a static route:**
+
+**Node 1:**
+
+```none
+set protocols static route 172.16.0.0/16 blackhole distance '254'
+```
+
+**Node 2:**
+
+```none
+set protocols static route 172.17.0.0/16 blackhole distance '254'
+```
+
+### IPv6 peering
+
+A simple BGP configuration via IPv6.
+
+**Node 1:**
+
+```none
+set protocols bgp system-as 65534
+set protocols bgp neighbor 2001:db8::2 ebgp-multihop '2'
+set protocols bgp neighbor 2001:db8::2 remote-as '65535'
+set protocols bgp neighbor 2001:db8::2 update-source '2001:db8::1'
+set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast
+set protocols bgp address-family ipv6-unicast network '2001:db8:1::/48'
+set protocols bgp parameters router-id '10.1.1.1'
+```
+
+**Node 2:**
+
+```none
+set protocols bgp system-as 65535
+set protocols bgp neighbor 2001:db8::1 ebgp-multihop '2'
+set protocols bgp neighbor 2001:db8::1 remote-as '65534'
+set protocols bgp neighbor 2001:db8::1 update-source '2001:db8::2'
+set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast
+set protocols bgp address-family ipv6-unicast network '2001:db8:2::/48'
+set protocols bgp parameters router-id '10.1.1.2'
+```
+
+Don't forget, the CIDR declared in the network statement **MUST exist in your
+routing table (dynamic or static), the best way to make sure that is true is
+creating a static route:**
+
+**Node 1:**
+
+```none
+set protocols static route6 2001:db8:1::/48 blackhole distance '254'
+```
+
+**Node 2:**
+
+```none
+set protocols static route6 2001:db8:2::/48 blackhole distance '254'
+```
+
+### Route Filtering
+
+Route filter can be applied using a route-map:
+
+**Node1:**
+
+```none
+set policy prefix-list AS65535-IN rule 10 action 'permit'
+set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16'
+set policy prefix-list AS65535-OUT rule 10 action 'deny'
+set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16'
+set policy prefix-list6 AS65535-IN rule 10 action 'permit'
+set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48'
+set policy prefix-list6 AS65535-OUT rule 10 action 'deny'
+set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48'
+
+set policy route-map AS65535-IN rule 10 action 'permit'
+set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN'
+set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN'
+set policy route-map AS65535-IN rule 20 action 'deny'
+set policy route-map AS65535-OUT rule 10 action 'deny'
+set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT'
+set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT'
+set policy route-map AS65535-OUT rule 20 action 'permit'
+
+set protocols bgp system-as 65534
+set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT'
+set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN'
+set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT'
+set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN'
+```
+
+**Node2:**
+
+```none
+set policy prefix-list AS65534-IN rule 10 action 'permit'
+set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16'
+set policy prefix-list AS65534-OUT rule 10 action 'deny'
+set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16'
+set policy prefix-list6 AS65534-IN rule 10 action 'permit'
+set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48'
+set policy prefix-list6 AS65534-OUT rule 10 action 'deny'
+set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48'
+
+set policy route-map AS65534-IN rule 10 action 'permit'
+set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN'
+set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN'
+set policy route-map AS65534-IN rule 20 action 'deny'
+set policy route-map AS65534-OUT rule 10 action 'deny'
+set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT'
+set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT'
+set policy route-map AS65534-OUT rule 20 action 'permit'
+
+set protocols bgp system-as 65535
+set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT'
+set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN'
+set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT'
+set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN'
+```
+
+We could expand on this and also deny link local and multicast in the rule 20
+action deny.
diff --git a/docs/configuration/protocols/failover.md b/docs/configuration/protocols/failover.md
new file mode 100644
index 00000000..96374d11
--- /dev/null
+++ b/docs/configuration/protocols/failover.md
@@ -0,0 +1,237 @@
+---
+description: |-
+  Failover routes are static routes that are installed in the routing
+  table only while a configured health-check target responds. VyOS uses them
+  to switch traffic to a backup path when the primary next hop becomes
+  unreachable, and to restore the primary path automatically once it recovers.
+keywords: |-
+  failover, failover route, static route, health check, icmp probe,
+  next hop, route metric
+---
+
+# Failover
+
+Failover routes are manually configured network paths used only while their
+health-check targets are reachable. If the target stops responding, VyOS
+removes the route from the routing table and reinstalls it once the target
+recovers.
+
+## Configuration
+
+Use the following commands to configure failover routes for a specific remote
+`<subnet>` reachable via next-hop `<address>`.
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check target <target-address>
+
+   **Configure the health check target IP address.**
+
+   This is typically a highly available host, either within the destination
+   subnet or on the public internet.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check target 8.8.8.8
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check timeout <timeout>
+
+   **Configure the timeout interval, in seconds, between target health checks.**
+
+   The valid range is 1 to 300 seconds. The default is 10 seconds.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check timeout 2
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check type <protocol>
+
+   **Configure the protocol to use for health checks.**
+
+   The following protocols are available:
+
+   * ``icmp``: VyOS sends two ICMP echo request packets with a 1-second
+     response timeout. The health check is successful if at least one response
+     is received.
+   * ``arp``: VyOS sends two ARP requests with a 1-second response timeout.
+     The health check is successful if at least one response is received.
+   * ``tcp``: VyOS verifies whether the destination TCP port is open. The
+     health check is successful if a TCP connection is successfully
+     established with the target port.
+
+   The default protocol is ``icmp``.
+
+   .. note::
+
+      When the check type is set to ``tcp``, you must also define the target
+      TCP port.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check type tcp
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check port <port>
+
+   **Configure the destination TCP port on the health check target.**
+
+   This parameter applies only when the check type is configured as ``tcp``.
+
+   The valid port range is 1 to 65535.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check port 443
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check policy <policy>
+
+   **Configure the health check success policy for multiple targets.**
+
+   The following policies are available:
+
+   * ``any-available``: The health check succeeds if at least one of the
+     configured targets responds successfully.
+   * ``all-available``: The health check succeeds only if every configured
+     target responds successfully.
+
+   The default policy is ``any-available``.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check policy all-available
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> interface <interface>
+
+   **Configure the local interface used to reach the next-hop address.**
+
+   This parameter is mandatory.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 interface eth0
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> metric <1-255>
+
+   **Configure the metric (cost) for the failover route.**
+
+   The metric defines the route priority. A lower metric value indicates a
+   more preferred route.
+
+   The default value is 1.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 metric 50
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> onlink
+
+   Configure the next-hop to be reachable via the assigned interface, even
+   when ``<address>`` is outside any subnet configured on that interface.
+
+   Example:
+
+   .. code-block:: none
+
+      set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 onlink
+```
+
+## Examples
+
+### Failover route with a single next-hop and ICMP health check
+
+The following example configures a failover route to `203.0.113.1/32`
+through next-hop `192.0.2.1` on `eth0`. The next-hop is monitored with
+ICMP probes to `192.0.2.1` every 5 seconds, and the route is installed with
+a metric of 10.
+
+```none
+set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1'
+set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5'
+set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp'
+set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0'
+set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10'
+```
+
+Verify the route:
+
+```none
+vyos@vyos:~$ show ip route 203.0.113.1
+Routing entry for 203.0.113.1/32
+  Known via "kernel", distance 0, metric 10, best
+  Last update 00:00:39 ago
+  Flags: Selected
+  Status: Installed
+  * 192.0.2.1, via eth0, weight 1
+```
+
+### Two failover routes with different metrics
+
+The following example configures two failover routes to `203.0.113.1/32`,
+each through a different next-hop. The primary next-hop `192.0.2.1` is
+reached on `eth0` with metric 10, and the backup next-hop `198.51.100.1`
+is reached on `eth2` with metric 20. Both next-hops are monitored with ICMP
+probes every 5 seconds.
+
+While both health checks succeed, the lower-metric route through `eth0` is
+preferred. If the primary target stops responding, its route is removed from
+the routing table, and traffic falls over to `198.51.100.1` via `eth2`.
+
+```none
+set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1'
+set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5'
+set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp'
+set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0'
+set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10'
+
+set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check target '198.51.100.99'
+set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check timeout '5'
+set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check type 'icmp'
+set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 interface 'eth2'
+set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 metric '20'
+```
+
+Verify routes:
+
+```none
+vyos@vyos:~$ show ip route 203.0.113.1
+Routing entry for 203.0.113.1/32
+  Known via "kernel", distance 0, metric 10, best
+  Last update 00:08:06 ago
+  Flags: Selected
+  Status: Installed
+  * 192.0.2.1, via eth0, weight 1
+
+Routing entry for 203.0.113.1/32
+  Known via "kernel", distance 0, metric 20
+  Last update 00:08:14 ago
+  Flags: None
+  Status: Installed
+  * 198.51.100.1, via eth2, weight 1
+```
+
diff --git a/docs/configuration/protocols/igmp-proxy.md b/docs/configuration/protocols/igmp-proxy.md
new file mode 100644
index 00000000..961f921b
--- /dev/null
+++ b/docs/configuration/protocols/igmp-proxy.md
@@ -0,0 +1,79 @@
+---
+lastproofread: '2023-11-13'
+---
+
+(igmp-proxy)=
+
+# IGMP Proxy
+
+{abbr}`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages
+on behalf of a connected client. The configuration must define one, and only one
+upstream interface, and one or more downstream interfaces.
+
+## Configuration
+
+```{cfgcmd} set protocols igmp-proxy interface \<interface\> role \<upstream | downstream\>
+
+* **upstream:** The upstream network interface is the outgoing interface
+which is responsible for communicating to available multicast data sources.
+There can only be one upstream interface.
+
+* **downstream:** Downstream network interfaces are the distribution
+interfaces to the destination networks, where multicast clients can join
+groups and receive multicast data. One or more downstream interfaces must
+be configured.
+```
+
+```{cfgcmd} set protocols igmp-proxy interface \<interface\> alt-subnet \<network\>
+
+Defines alternate sources for multicasting and IGMP data. The network address
+must be on the following format 'a.b.c.d/n'. By default, the router will
+accept data from sources on the same network as configured on an interface.
+If the multicast source lies on a remote network, one must define from where
+traffic should be accepted.
+
+This is especially useful for the upstream interface, since the source for
+multicast traffic is often from a remote location.
+
+This option can be supplied multiple times.
+```
+
+```{cfgcmd} set protocols igmp-proxy disable-quickleave
+
+Disables quickleave mode. In this mode the daemon will not send a Leave IGMP
+message upstream as soon as it receives a Leave message for any downstream
+interface. The daemon will not ask for Membership reports on the downstream
+interfaces, and if a report is received the group is not joined again the
+upstream.
+
+If it's vital that the daemon should act exactly like a real multicast client
+on the upstream interface, this function should be enabled.
+
+Enabling this function increases the risk of bandwidth saturation.
+```
+
+```{cfgcmd} set protocols igmp-proxy disable
+
+Disable this service.
+```
+
+(igmp-proxy-example)=
+
+### Example
+
+Interface eth1 LAN is behind NAT. In order to subscribe 10.0.0.0/23 subnet
+multicast which is in eth0 WAN we need to configure igmp-proxy.
+
+```none
+set protocols igmp-proxy interface eth0 role upstream
+set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23
+set protocols igmp-proxy interface eth1 role downstream
+```
+
+
+## Operation
+
+```{opcmd} restart igmp-proxy
+
+Restart the IGMP proxy process.
+```
\ No newline at end of file
diff --git a/docs/configuration/protocols/index.md b/docs/configuration/protocols/index.md
new file mode 100644
index 00000000..5f190ce1
--- /dev/null
+++ b/docs/configuration/protocols/index.md
@@ -0,0 +1,25 @@
+# Protocols
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+arp
+babel
+bfd
+bgp
+failover
+igmp-proxy
+isis
+mpls
+multicast
+segment-routing
+traffic-engineering
+openfabric
+ospf
+pim
+pim6
+rip
+rpki
+static
+```
diff --git a/docs/configuration/protocols/isis.md b/docs/configuration/protocols/isis.md
new file mode 100644
index 00000000..ac6db346
--- /dev/null
+++ b/docs/configuration/protocols/isis.md
@@ -0,0 +1,746 @@
+```{include} /_include/need_improvement.txt
+```
+
+(routing-isis)=
+
+# IS-IS
+
+{abbr}`IS-IS (Intermediate System to Intermediate System)` is a link-state
+interior gateway protocol (IGP) which is described in ISO10589,
+{rfc}`1195`, {rfc}`5308`. IS-IS runs the Dijkstra shortest-path first (SPF)
+algorithm to create a database of the network’s topology, and
+from that database to determine the best (that is, lowest cost) path to a
+destination. The intermediate systems (the name for routers) exchange topology
+information with their directly connected neighbors. IS-IS runs directly on
+the data link layer (Layer 2). IS-IS addresses are called
+{abbr}`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are
+generally 10 bytes long. The tree database that is created with IS-IS is
+similar to the one that is created with OSPF in that the paths chosen should
+be similar. Comparisons to OSPF are inevitable and often are reasonable ones
+to make in regards to the way a network will respond with either IGP.
+
+## General
+
+### Configuration
+
+#### Mandatory Settings
+
+For IS-IS top operate correctly, one must do the equivalent of a Router ID in
+CLNS. This Router ID is called the {abbr}`NET (Network Entity Title)`. This
+must be unique for each and every router that is operating in IS-IS. It also
+must not be duplicated otherwise the same issues that occur within OSPF will
+occur within IS-IS when it comes to said duplication.
+
+```{cfgcmd} set protocols isis net \<network-entity-title\>
+
+This command sets network entity title (NET) provided in ISO format.
+
+Here is an example {abbr}`NET (Network Entity Title)` value:
+
+:::{code-block} none
+49.0001.1921.6800.1002.00
+:::
+The CLNS address consists of the following parts:
+
+* {abbr}`AFI (Address family authority identifier)` - ``49`` The AFI value
+  49 is what IS-IS uses for private addressing.
+
+* Area identifier: ``0001`` IS-IS area number (numerical area ``1``)
+
+* System identifier: ``1921.6800.1002`` - for system identifiers we recommend
+  to use IP address or MAC address of the router itself. The way to construct
+  this is to keep all of the zeroes of the router IP address, and then change
+  the periods from being every three numbers to every four numbers. The
+  address that is listed here is ``192.168.1.2``, which if expanded will turn
+  into ``192.168.001.002``. Then all one has to do is move the dots to have
+  four numbers instead of three. This gives us ``1921.6800.1002``.
+
+* {abbr}`NET (Network Entity Title)` selector: ``00`` Must always be 00. This
+  setting indicates "this system" or "local system."
+
+```
+
+```{cfgcmd} set protocols isis interface \<interface\>
+
+This command enables IS-IS on this interface, and allows for
+adjacency to occur. Note that the name of IS-IS instance must be
+the same as the one used to configure the IS-IS process.
+```
+
+#### IS-IS Global Configuration
+
+```{cfgcmd} set protocols isis dynamic-hostname
+
+This command enables support for dynamic hostname TLV. Dynamic hostname
+mapping determined as described in {rfc}`2763`, Dynamic Hostname
+Exchange Mechanism for IS-IS.
+```
+
+```{cfgcmd} set protocols isis level \<level-1|level-1-2|level-2\>
+
+This command defines the IS-IS router behavior:
+
+* **level-1** - Act as a station (Level 1) router only.
+* **level-1-2** - Act as a station (Level 1) router and area (Level 2) router.
+* **level-2-only** - Act as an area (Level 2) router only.
+```
+
+```{cfgcmd} set protocols isis lsp-mtu \<size\>
+
+This command configures the maximum size of generated
+{abbr}`LSPs (Link State PDUs)`, in bytes. The size range is 128 to 4352.
+```
+
+```{cfgcmd} set protocols isis metric-style \<narrow|transition|wide\>
+
+This command sets old-style (ISO 10589) or new style packet formats:
+
+* **narrow** - Use old style of TLVs with narrow metric.
+* **transition** - Send and accept both styles of TLVs during transition.
+* **wide** - Use new style of TLVs to carry wider metric.
+```
+
+```{cfgcmd} set protocols isis purge-originator
+
+This command enables {rfc}`6232` purge originator identification. Enable
+purge originator identification (POI) by adding the type, length and value
+(TLV) with the Intermediate System (IS) identification to the LSPs that do
+not contain POI information. If an IS generates a purge, VyOS adds this TLV
+with the system ID of the IS to the purge.
+```
+
+```{cfgcmd} set protocols isis set-attached-bit
+
+This command sets ATT bit to 1 in Level1 LSPs. It is described in {rfc}`3787`.
+```
+
+```{cfgcmd} set protocols isis set-overload-bit
+
+This command sets overload bit to avoid any transit traffic through this
+router. It is described in {rfc}`3787`.
+```
+
+```{cfgcmd} set protocols isis default-information originate \<ipv4|ipv6\> level-1
+
+This command will generate a default-route in L1 database.
+```
+
+```{cfgcmd} set protocols isis default-information originate \<ipv4|ipv6\> level-2
+
+This command will generate a default-route in L2 database.
+```
+
+```{cfgcmd} set protocols isis ldp-sync
+
+This command will enable IGP-LDP synchronization globally for ISIS. This
+requires for LDP to be functional. This is described in {rfc}`5443`. By
+default all interfaces operational in IS-IS are enabled for synchronization.
+Loopbacks are exempt.
+
+```
+
+```{cfgcmd} set protocols isis ldp-sync holddown \<seconds\>
+
+This command will change the hold down value globally for IGP-LDP
+synchronization during convergence/interface flap events.
+```
+
+#### Interface Configuration
+
+```{cfgcmd} set protocols isis interface \<interface\> circuit-type \<level-1|level-1-2|level-2-only\>
+
+This command specifies circuit type for interface:
+
+* **level-1** - Level-1 only adjacencies are formed.
+* **level-1-2** - Level-1-2 adjacencies are formed
+* **level-2-only** - Level-2 only adjacencies are formed
+
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> hello-interval \<seconds\>
+
+This command sets hello interval in seconds on a given interface.
+The range is 1 to 600.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> hello-multiplier \<seconds\>
+
+This command sets multiplier for hello holding time on a given
+interface. The range is 2 to 100.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> hello-padding
+
+This command configures padding on hello packets to accommodate asymmetrical
+maximum transfer units (MTUs) from different hosts as described in
+{rfc}`3719`. This helps to prevent a premature adjacency Up state when one
+routing devices MTU does not meet the requirements to establish the adjacency.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> metric \<metric\>
+
+This command set default metric for circuit.
+
+The metric range is 1 to 16777215 (Max value depend if metric support narrow
+or wide value).
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> network point-to-point
+
+This command specifies network type to Point-to-Point. The default
+network type is broadcast.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> passive
+
+This command configures the passive mode for this interface.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> password plaintext-password \<text\>
+
+This command configures the authentication password for the interface.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> priority \<number\>
+
+This command sets priority for the interface for
+{abbr}`DIS (Designated Intermediate System)` election. The priority
+range is 0 to 127.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> psnp-interval \<number\>
+
+This command sets PSNP interval in seconds. The interval range is 0
+to 127.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> no-three-way-handshake
+
+This command disables Three-Way Handshake for P2P adjacencies which
+described in {rfc}`5303`. Three-Way Handshake is enabled by default.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> ldp-sync disable
+
+This command disables IGP-LDP sync for this specific interface.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> ldp-sync holddown \<seconds\>
+
+This command will change the hold down value for IGP-LDP synchronization
+during convergence/interface flap events, but for this interface only.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> fast-reroute lfa [level-1 | level-2] enable
+
+This command enables per-prefix local LFA fast reroute link protection.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> fast-reroute lfa [level-1 | level-2] exclude
+
+This command excludes an interface from the local LFA backup nexthop computation.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> fast-reroute remote-lfa [level-1 | level-2] tunnel mpls-ldp
+
+This command enables per-prefix Remote LFA fast reroute link protection.
+Note that other routers in the network need to be configured to accept LDP
+targeted hello messages in order for RLFA to work.
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> fast-reroute remote-lfa [level-1 | level-2] maximum-metric \<metric\>
+
+This command limits Remote LFA PQ node selection within the specified metric. Metric value range (1-16777215).
+```
+
+```{cfgcmd} set protocols isis interface \<interface\> fast-reroute ti-lfa [level-1|level-2] [node-protection [link-fallback]]
+
+This command enables per-prefix TI-LFA fast reroute link or node protection.
+When node protection is used, option link-fallback enables the computation
+and use of link-protecting LFAs for destinations unprotected by node
+protection.
+```
+
+#### Route Redistribution
+
+```{cfgcmd} set protocols isis redistribute ipv4 \<route source\> level-1
+
+This command redistributes routing information from the given route source
+into the ISIS database as Level-1. There are six modes available for route
+source: bgp, connected, kernel, ospf, rip, static.
+```
+
+```{cfgcmd} set protocols isis redistribute ipv4 \<route source\> level-2
+
+This command redistributes routing information from the given route source
+into the ISIS database as Level-2. There are six modes available for route
+source: bgp, connected, kernel, ospf, rip, static.
+```
+
+```{cfgcmd} set protocols isis redistribute ipv4 \<route source\> \<level-1|level-2\> metric \<number\>
+
+This command specifies metric for redistributed routes from the given route
+source. There are six modes available for route source: bgp, connected,
+kernel, ospf, rip, static. The metric range is 1 to 16777215.
+```
+
+```{cfgcmd} set protocols isis redistribute ipv4 \<route source\> \<level-1|level-2\> route-map \<name\>
+
+This command allows to use route map to filter redistributed routes from
+the given route source. There are six modes available for route source:
+bgp, connected, kernel, ospf, rip, static.
+```
+
+#### Timers
+
+```{cfgcmd} set protocols isis lsp-gen-interval \<seconds\>
+
+This command sets minimum interval in seconds between regenerating same
+LSP. The interval range is 1 to 120.
+```
+
+```{cfgcmd} set protocols isis lsp-refresh-interval \<seconds\>
+
+This command sets LSP refresh interval in seconds. IS-IS generates LSPs
+when the state of a link changes. However, to ensure that routing
+databases on all routers remain converged, LSPs in stable networks are
+generated on a regular basis even though there has been no change to
+the state of the links. The interval range is 1 to 65235. The default
+value is 900 seconds.
+```
+
+```{cfgcmd} set protocols isis max-lsp-lifetime \<seconds\>
+
+This command sets LSP maximum LSP lifetime in seconds. The interval range
+is 350 to 65535. LSPs remain in a database for 1200 seconds by default.
+If they are not refreshed by that time, they are deleted. You can change
+the LSP refresh interval or the LSP lifetime. The LSP refresh interval
+should be less than the LSP lifetime or else LSPs will time out before
+they are refreshed.
+```
+
+```{cfgcmd} set protocols isis spf-interval \<seconds\>
+
+This command sets minimum interval between consecutive SPF calculations in
+seconds.The interval range is 1 to 120.
+```
+
+```{cfgcmd} set protocols isis spf-delay-ietf holddown \<milliseconds\>
+```
+
+```{cfgcmd} set protocols isis spf-delay-ietf init-delay \<milliseconds\>
+```
+
+```{cfgcmd} set protocols isis spf-delay-ietf long-delay \<milliseconds\>
+```
+
+```{cfgcmd} set protocols isis spf-delay-ietf short-delay \<milliseconds\>
+```
+
+```{cfgcmd} set protocols isis spf-delay-ietf time-to-learn \<milliseconds\>
+
+This commands specifies the Finite State Machine (FSM) intended to
+control the timing of the execution of SPF calculations in response
+to IGP events. The process described in {rfc}`8405`.
+```
+
+#### Loop Free Alternate (LFA)
+
+```{cfgcmd} set protocols isis fast-reroute lfa remote prefix-list \<name\> \<level-1|level-2\>
+
+This command enables IP fast re-routing that is part of {rfc}`5286`.
+Specifically this is a prefix list which references a prefix in which
+will select eligible PQ nodes for remote LFA backups.
+```
+
+```{cfgcmd} set protocols isis fast-reroute lfa local load-sharing disable \<level-1|level-2\>
+
+This command disables the load sharing across multiple LFA backups.
+```
+
+```{cfgcmd} set protocols isis fast-reroute lfa local tiebreaker \<downstream|lowest-backup-metric|node-protecting\> index \<number\> \<level-1|level-2\>
+
+This command will configure a tie-breaker for multiple local LFA backups.
+The lower index numbers will be processed first.
+```
+
+```{cfgcmd} set protocols isis fast-reroute lfa local priority-limit \<medium|high|critical\> \<level-1|level-2\>
+
+This command will limit LFA backup computation up to the specified
+prefix priority.
+```
+
+#### Segment Routing over IPv6 (SRv6)
+
+```{cfgcmd} set protocols isis segment-routing srv6 interface \<interface\>
+
+The dummy interface used
+to install SRv6 SIDs into the Linux data plane. The interface must exist and
+must be present when configuring IS-IS with
+SRv6.
+```
+
+```{cfgcmd} set protocols isis segment-routing srv6 locator \<locator\>
+
+Specifies the SRv6 locator to use for IS-IS. IS-IS automatically allocates
+prefix and adjacency SIDs, creates local SID entries and advertises them
+into the IGP domain.
+```
+
+```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-end-d \<0-255\>
+
+The Maximum End D MSD Type specifies the maximum number of SIDs present in an
+SRH when performing decapsulation. As specified in {rfc}`8986`, the permitted
+SID types include, but are not limited to, End.DX6, End.DT4, End.DT46, End
+with USD, and End.X with USD.
+
+If the advertised value is zero or no value is advertised, then the router
+cannot apply any behavior that results in decapsulation and forwarding of the
+inner packet if the outer IPv6 header contains an SRH.
+
+Reference: {rfc}`9352`
+```
+
+```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-end-pop \<0-255\>
+
+The Maximum End Pop MSD Type signals the maximum number of SIDs in the SRH to
+which the router can apply "Penultimate Segment Pop (PSP) of the SRH" or
+"Ultimate Segment Pop (USP) of the SRH" behavior, as defined in "Flavors"
+(Section 4.16 of {rfc}`8986`).
+
+If the advertised value is zero or no value is advertised, then the router
+cannot apply PSP or USP flavors.
+
+Reference: {rfc}`9352`
+```
+
+```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-h-encaps \<0-255\>
+
+The Maximum H.Encaps MSD Type signals the maximum number of SIDs that can be
+added to the segment list of an SRH as part of the "H.Encaps" behavior, as
+defined in {rfc}`8986`.
+
+If the advertised value is zero or no value is advertised, then the headend
+can apply an SR Policy that only contains one segment without inserting any
+SRH header. A non-zero SRH Max H.encaps MSD indicates that the headend can
+insert an SRH up to the advertised number of SIDs.
+
+Reference: {rfc}`9352`
+```
+
+```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-segs-left \<0-255\>
+
+The Maximum Segments Left MSD Type signals the maximum value of the
+"Segments Left" field ({rfc}`8754`) in the SRH of a received packet before
+applying the Endpoint behavior associated with a SID.
+
+If no value is advertised, the supported value is 0.
+
+Reference: {rfc}`9352`
+```
+
+## Examples
+
+### Enable IS-IS
+
+**Node 1:**
+
+```none
+set interfaces loopback lo address '192.168.255.255/32'
+set interfaces ethernet eth1 address '192.0.2.1/24'
+
+set protocols isis interface eth1
+set protocols isis interface lo
+set protocols isis net '49.0001.1921.6825.5255.00'
+```
+
+**Node 2:**
+
+```none
+set interfaces ethernet eth1 address '192.0.2.2/24'
+
+set interfaces loopback lo address '192.168.255.254/32'
+set interfaces ethernet eth1 address '192.0.2.2/24'
+
+set protocols isis interface eth1
+set protocols isis interface lo
+set protocols isis net '49.0001.1921.6825.5254.00'
+```
+
+This gives us the following neighborships, Level 1 and Level 2:
+
+```none
+Node-1@vyos:~$ show isis neighbor
+Area VyOS:
+  System Id           Interface   L  State        Holdtime SNPA
+ vyos                eth1        1  Up            28       0c87.6c09.0001
+ vyos                eth1        2  Up            28       0c87.6c09.0001
+
+Node-2@vyos:~$ show isis neighbor
+Area VyOS:
+  System Id           Interface   L  State        Holdtime SNPA
+ vyos                eth1        1  Up            29       0c33.0280.0001
+ vyos                eth1        2  Up            28       0c33.0280.0001
+```
+
+Here's the IP routes that are populated. Just the loopback:
+
+```none
+Node-1@vyos:~$ show ip route isis
+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
+
+I   192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:02:22
+I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, weight 1, 00:02:22
+
+Node-2@vyos:~$ show ip route isis
+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
+
+I   192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:02:21
+I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, weight 1, 00:02:21
+```
+
+### Enable IS-IS and redistribute routes not natively in IS-IS
+
+**Node 1:**
+
+```none
+set interfaces dummy dum0 address '203.0.113.1/24'
+set interfaces ethernet eth1 address '192.0.2.1/24'
+
+set policy prefix-list EXPORT-ISIS rule 10 action 'permit'
+set policy prefix-list EXPORT-ISIS rule 10 prefix '203.0.113.0/24'
+set policy route-map EXPORT-ISIS rule 10 action 'permit'
+set policy route-map EXPORT-ISIS rule 10 match ip address prefix-list 'EXPORT-ISIS'
+
+set protocols isis interface eth1
+set protocols isis net '49.0001.1921.6800.1002.00'
+set protocols isis redistribute ipv4 connected level-2 route-map 'EXPORT-ISIS'
+```
+
+**Node 2:**
+
+```none
+set interfaces ethernet eth1 address '192.0.2.2/24'
+
+set protocols isis interface eth1
+set protocols isis net '49.0001.1921.6800.2002.00'
+```
+
+Routes on Node 2:
+
+```none
+Node-2@r2:~$ show ip route isis
+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, D - SHARP,
+       F - PBR, f - OpenFabric,
+       > - selected route, * - FIB route, q - queued route, r - rejected route
+
+I   203.0.113.0/24 [115/10] via 192.0.2.1, eth1, 00:03:42
+```
+
+### Enable IS-IS and IGP-LDP synchronization
+
+**Node 1:**
+
+```none
+set interfaces loopback lo address 192.168.255.255/32
+set interfaces ethernet eth0 address 192.0.2.1/24
+
+set protocols isis interface eth0
+set protocols isis interface lo passive
+set protocols isis ldp-sync
+set protocols isis net 49.0001.1921.6825.5255.00
+
+set protocols mpls interface eth0
+set protocols mpls ldp discovery transport-ipv4-address 192.168.255.255
+set protocols mpls ldp interface lo
+set protocols mpls ldp interface eth0
+set protocols mpls ldp parameters transport-prefer-ipv4
+set protocols mpls ldp router-id 192.168.255.255
+```
+
+This gives us IGP-LDP synchronization for all non-loopback interfaces with
+a holddown timer of zero seconds:
+
+```none
+Node-1@vyos:~$  show isis mpls ldp-sync
+eth0
+  LDP-IGP Synchronization enabled: yes
+  holddown timer in seconds: 0
+  State: Sync achieved
+```
+
+### Enable IS-IS with Segment Routing (Experimental)
+
+**Node 1:**
+
+```none
+set interfaces loopback lo address '192.168.255.255/32'
+set interfaces ethernet eth1 address '192.0.2.1/24'
+
+set protocols isis interface eth1
+set protocols isis interface lo
+set protocols isis net '49.0001.1921.6825.5255.00'
+set protocols isis segment-routing global-block high-label-value '599'
+set protocols isis segment-routing global-block low-label-value '550'
+set protocols isis segment-routing prefix 192.168.255.255/32 index value '1'
+set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null
+set protocols mpls interface 'eth1'
+```
+
+**Node 2:**
+
+```none
+set interfaces loopback lo address '192.168.255.254/32'
+set interfaces ethernet eth1 address '192.0.2.2/24'
+
+set protocols isis interface eth1
+set protocols isis interface lo
+set protocols isis net '49.0001.1921.6825.5254.00'
+set protocols isis segment-routing global-block high-label-value '599'
+set protocols isis segment-routing global-block low-label-value '550'
+set protocols isis segment-routing prefix 192.168.255.254/32 index value '2'
+set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null
+set protocols mpls interface 'eth1'
+```
+
+This gives us MPLS segment routing enabled and labels for far end loopbacks:
+
+```none
+Node-1@vyos:~$ show mpls table
+ Inbound Label  Type        Nexthop                Outbound Label
+ ----------------------------------------------------------------------
+ 552            SR (IS-IS)  192.0.2.2              IPv4 Explicit Null <-- Node-2 loopback learned on Node-1
+ 15000          SR (IS-IS)  192.0.2.2              implicit-null
+ 15001          SR (IS-IS)  fe80::e87:6cff:fe09:1  implicit-null
+ 15002          SR (IS-IS)  192.0.2.2              implicit-null
+ 15003          SR (IS-IS)  fe80::e87:6cff:fe09:1  implicit-null
+
+Node-2@vyos:~$ show mpls table
+ Inbound Label  Type        Nexthop               Outbound Label
+ ---------------------------------------------------------------------
+ 551            SR (IS-IS)  192.0.2.1             IPv4 Explicit Null <-- Node-1 loopback learned on Node-2
+ 15000          SR (IS-IS)  192.0.2.1             implicit-null
+ 15001          SR (IS-IS)  fe80::e33:2ff:fe80:1  implicit-null
+ 15002          SR (IS-IS)  192.0.2.1             implicit-null
+ 15003          SR (IS-IS)  fe80::e33:2ff:fe80:1  implicit-null
+```
+
+Here is the routing tables showing the MPLS segment routing label operations:
+
+```none
+Node-1@vyos:~$ show ip route isis
+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
+
+I   192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48
+I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39
+
+Node-2@vyos:~$ show ip route isis
+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
+
+I   192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46
+I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43
+```
+
+### Enable IS-IS with Segment Routing over IPv6 (Experimental)
+
+**Node 1:**
+
+```none
+set interfaces dummy dum6 description "SRv6 IS-IS"
+set interfaces ethernet eth1 address '192.0.2.1/24'
+set interfaces loopback lo address '192.168.255.255/32'
+
+set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/64
+set protocols segment-routing interface eth1
+
+set protocols isis interface eth1
+set protocols isis interface lo
+set protocols isis net '49.0001.1921.6825.5255.00'
+set protocols isis segment-routing srv6 locator MAIN
+set protocols isis segment-routing srv6 interface dum6
+```
+
+**Node 2:**
+
+```none
+set interfaces dummy dum6 description "SRv6 IS-IS"
+set interfaces ethernet eth1 address '192.0.2.2/24'
+set interfaces loopback lo address '192.168.255.254/32'
+
+set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/64
+set protocols segment-routing interface eth1
+
+set protocols isis interface eth1
+set protocols isis interface lo
+set protocols isis net '49.0001.1921.6825.5254.00'
+set protocols isis segment-routing srv6 locator MAIN
+set protocols isis segment-routing srv6 interface dum6
+```
+
+### Enable IS-IS with Segment Routing over IPv6 (uSID) (Experimental)
+
+**Node 1:**
+
+```none
+set interfaces dummy dum6 description "SRv6 IS-IS"
+set interfaces ethernet eth1 address '192.0.2.1/24'
+set interfaces loopback lo address '192.168.255.255/32'
+
+set protocols segment-routing interface eth1
+set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/48
+set protocols segment-routing srv6 locator MAIN behavior-usid
+set protocols segment-routing srv6 locator MAIN block-len 32
+set protocols segment-routing srv6 locator MAIN format usid-f3216
+set protocols segment-routing srv6 locator MAIN func-bits 16
+set protocols segment-routing srv6 locator MAIN node-len 16
+
+set protocols isis interface eth1
+set protocols isis interface lo
+set protocols isis net '49.0001.1921.6825.5255.00'
+set protocols isis segment-routing srv6 interface dum6
+set protocols isis segment-routing srv6 locator MAIN
+```
+
+**Node 2:**
+
+```none
+set interfaces dummy dum6 description "SRv6 IS-IS"
+set interfaces ethernet eth1 address '192.0.2.2/24'
+set interfaces loopback lo address '192.168.255.254/32'
+
+set protocols segment-routing interface eth1
+set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/48
+set protocols segment-routing srv6 locator MAIN behavior-usid
+set protocols segment-routing srv6 locator MAIN block-len 32
+set protocols segment-routing srv6 locator MAIN format usid-f3216
+set protocols segment-routing srv6 locator MAIN func-bits 16
+set protocols segment-routing srv6 locator MAIN node-len 16
+
+set protocols isis interface eth1
+set protocols isis interface lo
+set protocols isis net '49.0001.1921.6825.5254.00'
+set protocols isis segment-routing srv6 interface dum6
+set protocols isis segment-routing srv6 locator MAIN
+```
diff --git a/docs/configuration/protocols/mpls.md b/docs/configuration/protocols/mpls.md
new file mode 100644
index 00000000..71b14be2
--- /dev/null
+++ b/docs/configuration/protocols/mpls.md
@@ -0,0 +1,285 @@
+(mpls)=
+
+# MPLS
+
+{abbr}`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm
+which differs from regular IP forwarding. Instead of IP addresses being used to
+make the decision on finding the exit interface, a router will instead use an
+exact match on a 32 bit/4 byte header called the MPLS label. This label is
+inserted between the ethernet (layer 2) header and the IP (layer 3) header.
+One can statically or dynamically assign label allocations, but we will focus
+on dynamic allocation of labels using some sort of label distribution protocol
+(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation
+Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow
+for the creation of a unidirectional/unicast path called a labeled switched
+path (initialized as LSP) throughout the network that operates very much like
+a tunnel through the network. An easy way of thinking about how an MPLS LSP
+actually forwards traffic throughout a network is to think of a GRE tunnel.
+They are not the same in how they operate, but they are the same in how they
+handle the tunneled packet. It would be good to think of MPLS as a tunneling
+technology that can be used to transport many different types of packets, to
+aid in traffic engineering by allowing one to specify paths throughout the
+network (using RSVP or SR), and to generally allow for easier intra/inter
+network transport of data packets.
+
+For more information on how MPLS label switching works, please go visit
+[Wikipedia (MPLS)].
+
+:::{note}
+MPLS support in VyOS is not finished yet, and therefore its
+functionality is limited. Currently there is no support for MPLS enabled VPN
+services such as L2VPNs and mVPNs. RSVP support is also not present as the
+underlying routing stack (FRR) does not implement it. Currently VyOS
+implements LDP as described in RFC 5036; other LDP standard are the
+following ones: RFC 6720, RFC 6667, RFC 5919, RFC 5561, RFC 7552, RFC 4447.
+Because MPLS is already available (FRR also supports RFC 3031).
+:::
+
+## Label Distribution Protocol
+
+The {abbr}`MPLS (Multi-Protocol Label Switching)` architecture does not assume
+a single protocol to create MPLS paths. VyOS supports the Label Distribution
+Protocol (LDP) as implemented by FRR, based on {rfc}`5036`.
+
+{abbr}`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol
+that distributes labels creating MPLS label switched paths in a dynamic manner.
+LDP is not a routing protocol, as it relies on other routing protocols for
+forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said
+routing protocols for communication with other routers that use LDP.
+
+In order to allow for LDP on the local router to exchange label advertisements
+with other routers, a TCP session will be established between automatically
+discovered and statically assigned routers. LDP will try to establish a TCP
+session to the **transport address** of other routers. Therefore for LDP to
+function properly please make sure the transport address is shown in the
+routing table and reachable to traffic at all times.
+
+It is highly recommended to use the same address for both the LDP router-id and
+the discovery transport address, but for VyOS MPLS LDP to work both parameters
+must be explicitly set in the configuration.
+
+Another thing to keep in mind with LDP is that much like BGP, it is a protocol
+that runs on top of TCP. It however does not have an ability to do something
+like a refresh capability like BGPs route refresh capability. Therefore one
+might have to reset the neighbor for a capability change or a configuration
+change to work.
+
+## Configuration Options
+
+```{cfgcmd} set protocols mpls interface \<interface\>
+
+Use this command to enable MPLS processing on the interface you define.
+```
+
+
+```{cfgcmd} set protocols mpls ldp interface \<interface\>
+
+Use this command to enable LDP on the interface you define.
+```
+
+
+```{cfgcmd} set protocols mpls ldp router-id \<address\>
+
+Use this command to configure the IP address used as the LDP router-id of the
+local device.
+```
+
+
+```{cfgcmd} set protocols mpls ldp discovery transport-ipv4-address \<address\>
+
+```
+```{cfgcmd} set protocols mpls ldp discovery transport-ipv6-address \<address\>
+
+Use this command to set the IPv4 or IPv6 transport-address used by LDP.
+```
+
+```{cfgcmd} set protocols mpls ldp neighbor \<address\> password \<password\>
+
+Use this command to configure authentication for LDP peers. Set the
+IP address of the LDP peer and a password that should be shared in
+order to become neighbors.
+```
+
+```{cfgcmd} set protocols mpls ldp neighbor \<address\> session-holdtime \<seconds\>
+
+Use this command to configure a specific session hold time for LDP peers.
+Set the IP address of the LDP peer and a session hold time that should be
+configured for it. You may have to reset the neighbor for this to work.
+```
+
+```{cfgcmd} set protocols mpls ldp neighbor \<address\> ttl-security \<disable | hop count\>
+
+Use this command to enable, disable, or specify hop count for TTL security
+for LDP peers. By default the value is set to 255 (or max TTL).
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-interval <seconds>
+.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-holdtime <seconds>
+.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-interval <seconds>
+.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-holdtime <seconds>
+
+  Use these commands if you would like to set the discovery hello and hold time
+  parameters.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime <seconds>
+.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime <seconds>
+
+  Use this command if you would like to set the TCP session hold time intervals.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols mpls ldp import ipv4 import-filter filter-access-list
+   <access list number>
+.. cfgcmd:: set protocols mpls ldp import ipv6 import-filter filter-access-list6
+   <access list number>
+
+  Use these commands to control the importing of forwarding equivalence classes
+  (FECs) for LDP from neighbors. This would be useful for example on only
+  accepting the labeled routes that are needed and not ones that are not
+  needed, such as accepting loopback interfaces and rejecting all others.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols mpls ldp export ipv4 export-filter filter-access-list
+   <access list number>
+.. cfgcmd:: set protocols mpls ldp export ipv6 export-filter filter-access-list6
+   <access list number>
+
+  Use these commands to control the exporting of forwarding equivalence classes
+  (FECs) for LDP to neighbors. This would be useful for example on only
+  announcing the labeled routes that are needed and not ones that are not
+  needed, such as announcing loopback interfaces and no others.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null
+.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null
+
+  Use this command if you would like for the router to advertise FECs with a
+  label of 0 for explicit null operations.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols mpls ldp allocation ipv4 access-list <access list number>
+.. cfgcmd:: set protocols mpls ldp allocation ipv6 access-list6 <access list number>
+
+  Use this command if you would like to control the local FEC allocations for
+  LDP. A good example would be for your local router to not allocate a label for
+  everything. Just a label for what it's useful. A good example would be just a
+  loopback label.
+```
+
+```{cfgcmd} set protocols mpls ldp parameters cisco-interop-tlv
+
+Use this command to use a Cisco non-compliant format to send and interpret
+the Dual-Stack capability TLV for IPv6 LDP communications. This is related to
+{rfc}`7552`.
+```
+
+```{cfgcmd} set protocols mpls ldp parameters ordered-control
+
+Use this command to use ordered label distribution control mode. FRR
+by default uses independent label distribution control mode for label
+distribution.  This is related to {rfc}`5036`.
+```
+
+```{cfgcmd} set protocols mpls ldp parameters transport-prefer-ipv4
+
+Use this command to prefer IPv4 for TCP peer transport connection for LDP
+when both an IPv4 and IPv6 LDP address are configured on the same interface.
+```
+
+```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 enable
+```
+
+```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 enable
+
+Use this command to enable targeted LDP sessions to the local router. The
+router will then respond to any sessions that are trying to connect to it that
+are not a link local type of TCP connection.
+```
+
+```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 address \<address\>
+```
+
+```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 address \<address\>
+
+Use this command to enable the local router to try and connect with a targeted
+LDP session to another router.
+```
+
+```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime \<seconds\>
+```
+
+```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-interval \<seconds\>
+```
+
+```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime \<seconds\>
+```
+
+```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-interval \<seconds\>
+
+Use these commands if you would like to set the discovery hello and hold time
+parameters for the targeted LDP neighbors.
+```
+
+### Sample configuration to setup LDP on VyOS
+
+```none
+set protocols ospf area 0 network '192.168.255.252/32'                      <--- Routing for loopback
+set protocols ospf area 0 network '192.168.0.5/32'                          <--- Routing for an interface connecting to the network
+set protocols ospf parameters router-id '192.168.255.252'                   <--- Router ID setting for OSPF
+set protocols mpls interface 'eth1'                                         <--- Enable MPLS for an interface connecting to network
+set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252'   <--- Transport address for LDP for TCP sessions to connect to
+set protocols mpls ldp interface 'eth1'                                     <--- Enable LDP for an interface connecting to network
+set protocols mpls ldp interface 'lo'                                       <--- Enable LDP on loopback for future services connectivity
+set protocols mpls ldp router-id '192.168.255.252'                          <--- Router ID setting for LDP
+set interfaces ethernet eth1 address '192.168.0.5/31'                       <--- Interface IP for connecting to network
+set interfaces loopback lo address '192.168.255.252/32'                     <--- Interface loopback IP for router ID and other uses
+```
+
+## Operational Mode Commands
+
+When LDP is working, you will be able to see label information in the outcome
+of `show ip route`. Besides that information, there are also specific *show*
+commands for LDP:
+
+### Show
+
+```{opcmd} show mpls ldp binding
+
+Use this command to see the Label Information Base.
+
+```
+
+```{opcmd} show mpls ldp discovery
+
+Use this command to see discovery hello information
+```
+
+```{opcmd} show mpls ldp interface
+
+Use this command to see LDP interface information
+```
+
+```{opcmd} show mpls ldp neighbor
+
+Use this command to see LDP neighbor information
+```
+
+```{opcmd} show mpls ldp neighbor detail
+
+Use this command to see detailed LDP neighbor information
+```
+
+### Reset
+
+```{opcmd} reset mpls ldp neighbor \<IPv4 or IPv6 address\>
+
+Use this command to reset an LDP neighbor/TCP session that is established
+```
+
+[wikipedia (mpls)]: <https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching>
diff --git a/docs/configuration/protocols/multicast.md b/docs/configuration/protocols/multicast.md
new file mode 100644
index 00000000..27150a29
--- /dev/null
+++ b/docs/configuration/protocols/multicast.md
@@ -0,0 +1,31 @@
+(routing-static)=
+
+# Multicast
+
+In order to influence Multicast {abbr}`RPF (Reverse Path Forwarding)` lookup,
+it is possible to insert into zebra routes for the Multicast
+{abbr}`RIB (Routing Information Base)`. These routes are only used for RPF
+lookup and will not be used by ZEBRA for insertion into the kernel or for
+normal RIB processing. As such it is possible to create weird states with
+these commands.
+
+Use with caution. Most of the time this will not be necessary.
+
+```{cfgcmd} set protocols static mroute \<subnet\> next-hop \<address\> [distance \<distance\>]
+
+Insert into the Multicast RIB Route `<subnet>` with specified next-hop.
+The distance can be specified as well if desired.
+```
+```{cfgcmd} set protocols static mroute \<subnet\> next-hop \<address\> disable
+
+Do not install route for `<subnet>` into the Multicast RIB.
+```
+```{cfgcmd} set protocols static mroute \<subnet\> interface \<interface\> [distance \<distance\>]
+
+Insert into the Multicast RIB Route `<subnet>` with specified `<interface>`.
+The distance can be specified as well if desired.
+```
+```{cfgcmd} set protocols static mroute \<subnet\> interface \<interface\> disable
+
+Do not install route for `<subnet>` into the Multicast RIB.
+```
\ No newline at end of file
diff --git a/docs/configuration/protocols/openfabric.md b/docs/configuration/protocols/openfabric.md
new file mode 100644
index 00000000..09ff5900
--- /dev/null
+++ b/docs/configuration/protocols/openfabric.md
@@ -0,0 +1,242 @@
+(openfabric)=
+
+# OpenFabric
+
+OpenFabric, specified in [draft-white-openfabric-06.txt](https://datatracker.ietf.org/doc/html/draft-white-openfabric-06), is
+a routing protocol derived from IS-IS, providing link-state routing with
+efficient flooding for topologies like spine-leaf networks.
+
+OpenFabric a dual stack protocol.
+A single OpenFabric instance is able to perform routing for both IPv4 and IPv6.
+
+## General
+
+### Configuration
+
+#### Mandatory Settings
+
+For OpenFabric to operate correctly, one must do the equivalent of a Router ID
+in Connectionless Network Service (CLNS). This Router ID is called the
+{abbr}`NET (Network Entity Title)`. The system identifier must be unique within
+the network
+
+```{cfgcmd} set protocols openfabric net \<network-entity-title\>
+
+This command sets network entity title (NET) provided in ISO format.
+
+Here is an example {abbr}`NET (Network Entity Title)` value:
+
+:::{code-block} none
+49.0001.1921.6800.1002.00
+:::
+The CLNS address consists of the following parts:
+
+* {abbr}`AFI (Address family authority identifier)` - ``49`` The AFI value
+  49 is what OpenFabric uses for private addressing.
+
+* Area identifier: ``0001`` OpenFabric area number (numerical area ``1``)
+
+* System identifier: ``1921.6800.1002`` - for system identifiers we recommend
+  to use IP address or MAC address of the router itself. The way to construct
+  this is to keep all of the zeroes of the router IP address, and then change
+  the periods from being every three numbers to every four numbers. The
+  address that is listed here is ``192.168.1.2``, which if expanded will turn
+  into ``192.168.001.002``. Then all one has to do is move the dots to have
+  four numbers instead of three. This gives us ``1921.6800.1002``.
+
+* {abbr}`NET (Network Entity Title)` selector: ``00`` Must always be 00. This
+  setting indicates "this system" or "local system."
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> address-family \<ipv4|ipv6\>
+
+This command enables OpenFabric instance with \<NAME\> on this interface, and
+allows for adjacency to occur for address family (IPv4 or IPv6 or both).
+```
+
+#### OpenFabric Global Configuration
+
+```{cfgcmd} set protocols openfabric domain-password \<plaintext-password|md5\> \<password\>
+
+This command configures the authentication password for a routing domain,
+as clear text or md5 one.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> purge-originator
+
+This command enables {rfc}`6232` purge originator identification.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> set-overload-bit
+
+This command sets overload bit to avoid any transit traffic through this
+router.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> log-adjacency-changes
+
+Log changes in adjacency state.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> fabric-tier \<number\>
+
+This command sets a static tier number to advertise as location
+in the fabric.
+```
+
+#### Interface Configuration
+
+```{cfgcmd} set protocols openfabric interface \<interface\> hello-interval \<seconds\>
+
+This command sets hello interval in seconds on a given interface.
+The range is 1 to 600. Hello packets are used to establish and maintain
+adjacency between OpenFabric neighbors.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> hello-multiplier \<number\>
+
+This command sets multiplier for hello holding time on a given
+interface. The range is 2 to 100.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> metric \<metric\>
+
+This command sets default metric for circuit.
+The metric range is 1 to 16777215.
+```
+
+
+```{cfgcmd} set protocols openfabric interface \<interface\> passive
+
+This command enables the passive mode for this interface.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> password plaintext-password \<text\>
+
+This command sets the authentication password for the interface.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> csnp-interval \<seconds\>
+
+This command sets Complete Sequence Number Packets (CSNP) interval in seconds.
+The interval range is 1 to 600.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> psnp-interval \<number\>
+
+This command sets Partial Sequence Number Packets (PSNP) interval in seconds.
+The interval range is 1 to 120.
+```
+
+#### Timers
+
+```{cfgcmd} set protocols openfabric domain \<name\> lsp-gen-interval \<seconds\>
+
+This command sets minimum interval at which link-state packets (LSPs) are
+generated. The interval range is 1 to 120.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> lsp-refresh-interval \<seconds\>
+
+This command sets LSP refresh interval in seconds. The interval range
+is 1 to 65235.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> max-lsp-lifetime \<seconds\>
+
+This command sets LSP maximum LSP lifetime in seconds. The interval range
+is 360 to 65535. LSPs remain in a database for 1200 seconds by default.
+If they are not refreshed by that time, they are deleted. You can change
+the LSP refresh interval or the LSP lifetime. The LSP refresh interval
+should be less than the LSP lifetime or else LSPs will time out before
+they are refreshed.
+```
+
+
+```{cfgcmd} set protocols openfabric domain \<name\> spf-interval \<seconds\>
+
+This command sets minimum interval between consecutive shortest path first
+(SPF) calculations in seconds.The interval range is 1 to 120.
+```
+
+## Examples
+### Enable OpenFabric
+
+**Node 1:**
+
+```none
+set interfaces loopback lo address '192.168.255.255/32'
+set interfaces ethernet eth1 address '192.0.2.1/24'
+
+set protocols openfabric domain VyOS interface eth1 address-family ipv4
+set protocols openfabric domain VyOS interface lo address-family ipv4
+set protocols openfabric net '49.0001.1921.6825.5255.00'
+```
+
+**Node 2:**
+
+```none
+set interfaces loopback lo address '192.168.255.254/32'
+set interfaces ethernet eth1 address '192.0.2.2/24'
+
+set protocols openfabric domain VyOS interface eth1 address-family ipv4
+set protocols openfabric domain VyOS interface lo address-family ipv4
+set protocols openfabric net '49.0001.1921.6825.5254.00'
+```
+
+This gives us the following neighborships:
+
+```none
+Node-1@vyos:~$ show openfabric neighbor
+show openfabric neighbor
+Area VyOS:
+  System Id           Interface   L  State        Holdtime SNPA
+ vyos                eth1        2  Up            27       2020.2020.2020
+
+
+Node-2@vyos:~$ show openfabric neighbor
+show openfabric neighbor
+Area VyOS:
+  System Id           Interface   L  State        Holdtime SNPA
+ vyos                eth1        2  Up            30       2020.2020.2020
+```
+
+Here's the IP routes that are populated:
+
+```none
+Node-1@vyos:~$ show ip route openfabric
+show ip route openfabric
+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
+
+f   192.0.2.0/24 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10
+f>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10
+
+Node-2@vyos:~$ show ip route openfabric
+show ip route openfabric
+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
+
+f   192.0.2.0/24 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48
+f>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48
+```
diff --git a/docs/configuration/protocols/ospf.md b/docs/configuration/protocols/ospf.md
new file mode 100644
index 00000000..72fefb84
--- /dev/null
+++ b/docs/configuration/protocols/ospf.md
@@ -0,0 +1,1504 @@
+(routing-ospf)=
+
+# OSPF
+
+{abbr}`OSPF (Open Shortest Path First)` is a routing protocol for Internet
+Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls
+into the group of interior gateway protocols (IGPs), operating within a single
+autonomous system (AS). It is defined as OSPF Version 2 in {rfc}`2328` (1998)
+for IPv4. Updates for IPv6 are specified as OSPF Version 3 in {rfc}`5340`
+(2008). OSPF supports the {abbr}`CIDR (Classless Inter-Domain Routing)`
+addressing model.
+
+OSPF is a widely used IGP in large enterprise networks.
+
+## OSPFv2 (IPv4)
+
+### Configuration
+
+#### General
+
+VyOS does not have a special command to start the OSPF process. The OSPF process
+starts when the first ospf enabled interface is configured.
+
+```{cfgcmd} set protocols ospf area \<number\> network \<A.B.C.D/M\>
+
+   This command specifies the OSPF enabled interface(s). If the interface has
+   an address from defined range then the command enables OSPF on this
+   interface so router can provide network information to the other ospf
+   routers via this interface.
+
+   This command is also used to enable the OSPF process. The area number can be
+   specified in decimal notation in the range from 0 to 4294967295. Or it
+   can be specified in dotted decimal notation similar to ip address.
+
+   Prefix length in interface must be equal or bigger (i.e. smaller network)
+   than prefix length in network statement. For example statement above doesn't
+   enable ospf on interface with address 192.168.1.1/23, but it does on
+   interface with address 192.168.1.129/25.
+
+   In some cases it may be more convenient to enable OSPF on a per
+   interface/subnet
+   basis {cfgcmd}`set protocols ospf interface <interface> area <x.x.x.x | x>`
+```
+
+
+```{cfgcmd} set protocols ospf auto-cost reference-bandwidth \<number\>
+
+This command sets the reference bandwidth for cost calculations, where
+bandwidth can be in range from 1 to 4294967, specified in Mbits/s. The
+default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will
+have a cost of 1. Cost of lower bandwidth links will be scaled with
+reference to this cost).
+```
+
+
+```{cfgcmd} set protocols ospf parameters router-id \<rid\>
+
+This command sets the router-ID of the OSPF process. The router-ID may be an
+IP address of the router, but need not be – it can be any arbitrary 32bit
+number. However it MUST be unique within the entire OSPF domain to the OSPF
+speaker – bad things will happen if multiple OSPF speakers are configured
+with the same router-ID!
+```
+
+#### Optional
+
+```{cfgcmd} set protocols ospf default-information originate [always] [metric \<number\>] [metric-type \<1|2\>] [route-map \<name\>]
+
+Originate an AS-External (type-5) LSA describing a default route into all
+external-routing capable areas, of the specified metric and metric type.
+If the {cfgcmd}`always` keyword is given then the default is always
+advertised, even when there is no default present in the routing table.
+The argument {cfgcmd}`route-map` specifies to advertise the default route
+if the route map is satisfied.
+```
+
+
+```{cfgcmd} set protocols ospf distance global \<distance\>
+
+This command change distance value of OSPF globally.
+The distance range is 1 to 255.
+```
+
+
+```{cfgcmd} set protocols ospf distance ospf \<external|inter-area|intra-area\> \<distance\>
+
+This command change distance value of OSPF. The arguments are the distance
+values for external routes, inter-area routes and intra-area routes
+respectively. The distance range is 1 to 255.
+
+:::{note}
+Routes with a distance of 255 are effectively disabled and not
+installed into the kernel.
+:::
+```
+
+
+```{cfgcmd} set protocols ospf log-adjacency-changes [detail]
+
+This command allows to log changes in adjacency. With the optional
+{cfgcmd}`detail` argument, all changes in adjacency status are shown.
+Without {cfgcmd}`detail`, only changes to full or regressions are shown.
+```
+
+
+```{cfgcmd} set protocols ospf max-metric router-lsa \<administrative|on-shutdown <seconds\>|on-startup \<seconds\>>
+
+This enables {rfc}`3137` support, where the OSPF process describes its
+transit links in its router-LSA as having infinite distance so that other
+routers will avoid calculating transit paths through the router while
+still being able to reach networks through the router.
+
+This support may be enabled administratively (and indefinitely) with the
+{cfgcmd}`administrative` command. It may also be enabled conditionally.
+Conditional enabling of max-metric router-lsas can be for a period of
+seconds after startup with the {cfgcmd}`on-startup <seconds>` command
+and/or for a period of seconds prior to shutdown with the
+{cfgcmd}`on-shutdown <seconds>` command. The time range is 5 to 86400.
+```
+
+
+```{cfgcmd} set protocols ospf parameters abr-type \<cisco|ibm|shortcut|standard\>
+
+This command selects ABR model. OSPF router supports four ABR models:
+
+**cisco** – a router will be considered as ABR if it has several configured
+links to the networks in different areas one of which is a backbone area.
+Moreover, the link to the backbone area should be active (working).
+**ibm** – identical to "cisco" model but in this case a backbone area link
+may not be active.
+**standard** – router has several active links to different areas.
+**shortcut** – identical to "standard" but in this model a router is
+allowed to use a connected areas topology without involving a backbone
+area for inter-area connections.
+
+Detailed information about "cisco" and "ibm" models differences can be
+found in {rfc}`3509`. A "shortcut" model allows ABR to create routes
+between areas based on the topology of the areas connected to this router
+but not using a backbone area in case if non-backbone route will be
+cheaper. For more information about "shortcut" model,
+see ospf-shortcut-abr-02.txt
+```
+
+
+```{cfgcmd} set protocols ospf parameters rfc1583-compatibility
+
+{rfc}`2328`, the successor to {rfc}`1583`, suggests according to section
+G.2 (changes) in section 16.4.1 a change to the path preference algorithm
+that prevents possible routing loops that were possible in the old version
+of OSPFv2. More specifically it demands that inter-area paths and
+intra-area backbone path are now of equal preference but still both
+preferred to external paths.
+
+This command should NOT be set normally.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> passive [disable]
+
+This command specifies interface as passive. Passive interface advertises
+its address, but does not run the OSPF protocol (adjacencies are not formed
+and hello packets are not generated).
+
+The optional disable option allows to exclude interface from passive state.
+This command is used if the command {cfgcmd}`passive-interface default` was
+configured.
+```
+
+
+```{cfgcmd} set protocols ospf passive-interface default
+
+This command specifies all interfaces as passive by default. Because this
+command changes the configuration logic to a default passive; therefore,
+interfaces where router adjacencies are expected need to be configured
+with the {cfgcmd}`passive-interface-exclude` command.
+```
+
+
+```{cfgcmd} set protocols ospf maximum-paths \<1-64\>
+
+Use this command to control the maximum number of equal cost paths to reach
+a specific destination. The upper limit may differ if you change the value
+of MULTIPATH_NUM during compilation. The default is MULTIPATH_NUM (64).
+```
+
+
+```{cfgcmd} set protocols ospf refresh timers \<seconds\>
+
+The router automatically updates link-state information with its neighbors.
+Only an obsolete information is updated which age has exceeded a specific
+threshold. This parameter changes a threshold value, which by default is
+1800 seconds (half an hour). The value is applied to the whole OSPF router.
+The timer range is 10 to 1800.
+```
+
+
+```{cfgcmd} set protocols ospf timers throttle spf \<delay|initial-holdtime|max-holdtime\> \<seconds\>
+
+This command sets the initial delay, the initial-holdtime and the
+maximum-holdtime between when SPF is calculated and the event which
+triggered the calculation. The times are specified in milliseconds and must
+be in the range of 0 to 600000 milliseconds. {cfgcmd}`delay` sets the
+initial SPF schedule delay in milliseconds. The default value is 200 ms.
+{cfgcmd}`initial-holdtime` sets the minimum hold time between two
+consecutive SPF calculations. The default value is 1000 ms.
+{cfgcmd}`max-holdtime` sets the maximum wait time between two
+consecutive SPF calculations. The default value is 10000 ms.
+```
+
+
+```{cfgcmd} set protocols ospf ldp-sync
+
+This command will enable IGP-LDP synchronization globally for OSPF. This
+requires for LDP to be functional. This is described in {rfc}`5443`. By
+default all interfaces operational in OSPF are enabled for synchronization.
+Loopbacks are exempt.
+```
+
+
+```{cfgcmd} set protocols ospf ldp-sync holddown \<seconds\>
+
+This command will change the hold down value globally for IGP-LDP
+synchronization during convergence/interface flap events.
+```
+
+
+```{cfgcmd} set protocols ospf capability opaque
+
+ospfd supports Opaque LSA {rfc}`2370` as partial support for MPLS Traffic
+Engineering LSAs. The opaque-lsa capability must be enabled in the
+configuration.
+
+An alternate command could be "mpls-te on" (Traffic Engineering)
+
+:::{note}
+FRR offers only partial support for some of the routing
+protocol extensions that are used with MPLS-TE; it does not
+support a complete RSVP-TE solution.
+:::
+```
+
+#### Area Configuration
+
+```{cfgcmd} set protocols ospf area \<number\> area-type stub
+
+This command specifies the area to be a Stub Area. That is, an area where
+no router originates routes external to OSPF and hence an area where all
+external routes are via the ABR(s). Hence, ABRs for such an area do not
+need to pass AS-External LSAs (type-5) or ASBR-Summary LSAs (type-4) into
+the area. They need only pass Network-Summary (type-3) LSAs into such an
+area, along with a default-route summary.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> area-type stub no-summary
+
+This command specifies the area to be a Totally Stub Area. In addition to
+stub area limitations this area type prevents an ABR from injecting
+Network-Summary (type-3) LSAs into the specified stub area. Only default
+summary route is allowed.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> area-type stub default-cost \<number\>
+
+This command sets the cost of default-summary LSAs announced to stubby
+areas. The cost range is 0 to 16777215.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> area-type nssa
+
+This command specifies the area to be a Not So Stubby Area. External
+routing information is imported into an NSSA in Type-7 LSAs. Type-7 LSAs
+are similar to Type-5 AS-external LSAs, except that they can only be
+flooded into the NSSA. In order to further propagate the NSSA external
+information, the Type-7 LSA must be translated to a Type-5 AS-external-LSA
+by the NSSA ABR.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> area-type nssa no-summary
+
+This command specifies the area to be a NSSA Totally Stub Area. ABRs for
+such an area do not need to pass Network-Summary (type-3) LSAs (except the
+default summary route), ASBR-Summary LSAs (type-4) and AS-External LSAs
+(type-5) into the area. But Type-7 LSAs that convert to Type-5 at the NSSA
+ABR are allowed.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> area-type nssa default-cost \<number\>
+
+This command sets the default cost of LSAs announced to NSSA areas.
+The cost range is 0 to 16777215.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> area-type nssa translate \<always|candidate|never\>
+
+Specifies whether this NSSA border router will unconditionally translate
+Type-7 LSAs into Type-5 LSAs. When role is Always, Type-7 LSAs are
+translated into Type-5 LSAs regardless of the translator state of other
+NSSA border routers. When role is Candidate, this router participates in
+the translator election to determine if it will perform the translations
+duties. When role is Never, this router will never translate Type-7 LSAs
+into Type-5 LSAs.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> authentication plaintext-password
+
+This command specifies that simple password authentication should be used
+for the given area. The password must also be configured on a per-interface
+basis.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> authentication md5
+
+This command specify that OSPF packets must be authenticated with MD5 HMACs
+within the given area. Keying material must also be configured on a
+per-interface basis.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> range \<A.B.C.D/M\> [cost \<number\>]
+
+This command summarizes intra area paths from specified area into one
+summary-LSA (Type-3) announced to other areas. This command can be used
+only in ABR and ONLY router-LSAs (Type-1) and network-LSAs (Type-2)
+(i.e. LSAs with scope area) can be summarized. AS-external-LSAs (Type-5)
+can’t be summarized - their scope is AS. The optional argument
+{cfgcmd}`cost` specifies the aggregated link metric. The metric range is 0
+to 16777215.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> range \<A.B.C.D/M\> not-advertise
+
+This command instead of summarizing intra area paths filter them - i.e.
+intra area paths from this range are not advertised into other areas.
+This command makes sense in ABR only.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> export-list \<acl_number\>
+
+Filter Type-3 summary-LSAs announced to other areas originated from
+intra- area paths from specified area.
+This command makes sense in ABR only.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> import-list \<acl_number\>
+
+Same as export-list, but it applies to paths announced into specified
+area as Type-3 summary-LSAs.
+This command makes sense in ABR only.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> range \<A.B.C.D/M\> substitute \<E.F.G.H/M\>
+
+One Type-3 summary-LSA with routing info <E.F.G.H/M> is announced into
+backbone area if defined area contains at least one intra-area network
+(i.e. described with router-LSA or network-LSA) from range <A.B.C.D/M>.
+This command makes sense in ABR only.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> shortcut \<default|disable|enable\>
+
+This parameter allows to "shortcut" routes (non-backbone) for inter-area
+routes. There are three modes available for routes shortcutting:
+
+**default** –  this area will be used for shortcutting only if ABR does not
+have a link to the backbone area or this link was lost.
+**enable** – the area will be used for shortcutting every time the route
+that goes through it is cheaper.
+**disable** – this area is never used by ABR for routes shortcutting.
+```
+
+
+```{cfgcmd} set protocols ospf area \<number\> virtual-link \<A.B.C.D\>
+
+Provides a backbone area coherence by virtual link establishment.
+
+In general, OSPF protocol requires a backbone area (area 0) to be coherent
+and fully connected. I.e. any backbone area router must have a route to any
+other backbone area router. Moreover, every ABR must have a link to
+backbone area. However, it is not always possible to have a physical link
+to a backbone area. In this case between two ABR (one of them has a link to
+the backbone area) in the area (not stub area) a virtual link is organized.
+
+\<number\> – area identifier through which a virtual link goes.
+\<A.B.C.D\> – ABR router-id with which a virtual link is established. Virtual
+link must be configured on both routers.
+
+Formally, a virtual link looks like a point-to-point network connecting two
+ABR from one area one of which physically connected to a backbone area.
+This pseudo-network is considered to belong to a backbone area.
+```
+
+#### Interface Configuration
+
+```{cfgcmd} set protocols ospf interface \<interface\> area \<x.x.x.x | x\>
+
+   Enable ospf on an interface and set associated area.
+
+   If you have a lot of interfaces, and/or a lot of subnets, then enabling
+   OSPF via this command may result in a slight performance improvement.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> authentication plaintext-password \<text\>
+
+This command sets OSPF authentication key to a simple password. After
+setting, all OSPF packets are authenticated. Key has length up to 8 chars.
+
+Simple text password authentication is insecure and deprecated in favour of
+MD5 HMAC authentication.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> authentication md5 key-id \<id\> md5-key \<text\>
+
+This command specifys that MD5 HMAC authentication must be used on this
+interface. It sets OSPF authentication key to a cryptographic password.
+Key-id identifies secret key used to create the message digest. This ID
+is part of the protocol and must be consistent across routers on a link.
+The key can be long up to 16 chars (larger strings will be truncated),
+and is associated with the given key-id.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> bandwidth \<number\>
+
+This command sets the interface bandwidth for cost calculations, where
+bandwidth can be in range from 1 to 100000, specified in Mbits/s.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> cost \<number\>
+
+This command sets link cost for the specified interface. The cost value is
+set to router-LSA’s metric field and used for SPF calculation. The cost
+range is 1 to 65535.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> dead-interval \<number\>
+
+Set number of seconds for router Dead Interval timer value used for Wait
+Timer and Inactivity Timer. This value must be the same for all routers
+attached to a common network. The default value is 40 seconds. The
+interval range is 1 to 65535.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> hello-multiplier \<number\>
+
+The hello-multiplier specifies how many Hellos to send per second, from 1
+(every second) to 10 (every 100ms). Thus one can have 1s convergence time
+for OSPF. If this form is specified, then the hello-interval advertised in
+Hello packets is set to 0 and the hello-interval on received Hello packets
+is not checked, thus the hello-multiplier need NOT be the same across
+multiple routers on a common link.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> hello-interval \<number\>
+
+Set number of seconds for Hello Interval timer value. Setting this value,
+Hello packet will be sent every timer value seconds on the specified
+interface. This value must be the same for all routers attached to a
+common network. The default value is 10 seconds. The interval range is 1
+to 65535.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> bfd
+
+This command enables {abbr}`BFD (Bidirectional Forwarding Detection)` on
+this OSPF link interface.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> mtu-ignore
+
+This command disables check of the MTU value in the OSPF DBD packets. Thus,
+use of this command allows the OSPF adjacency to reach the FULL state even
+though there is an interface MTU mismatch between two OSPF routers.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> network \<type\>
+
+This command allows to specify the distribution type for the network
+connected to this interface:
+
+**broadcast** – broadcast IP addresses distribution.
+**non-broadcast** – address distribution in NBMA networks topology.
+**point-to-multipoint** – address distribution in point-to-multipoint
+networks.
+**point-to-point** – address distribution in point-to-point networks.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> priority \<number\>
+
+This command sets Router Priority integer value. The router with the
+highest priority will be more eligible to become Designated Router.
+Setting the value to 0, makes the router ineligible to become
+Designated Router. The default value is 1. The interval range is 0 to 255.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> retransmit-interval \<number\>
+
+This command sets number of seconds for RxmtInterval timer value. This
+value is used when retransmitting Database Description and Link State
+Request packets if acknowledge was not received. The default value is 5
+seconds. The interval range is 3 to 65535.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> transmit-delay \<number\>
+
+This command sets number of seconds for InfTransDelay value. It allows to
+set and adjust for each interface the delay interval before starting the
+synchronizing process of the router's database with all neighbors. The
+default value is 1 seconds. The interval range is 3 to 65535.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> ldp-sync disable
+
+This command disables IGP-LDP sync for this specific interface.
+```
+
+
+```{cfgcmd} set protocols ospf interface \<interface\> ldp-sync holddown \<seconds\>
+
+This command will change the hold down value for IGP-LDP synchronization
+during convergence/interface flap events, but for this interface only.
+```
+
+#### External Route Summarisation
+
+
+This feature summarises originated external LSAs (Type-5 and Type-7). Summary
+Route will be originated on-behalf of all matched external LSAs.
+
+```{cfgcmd} set protocols ospf aggregation timer \<seconds\>
+
+Configure aggregation delay timer interval.
+
+Summarisation starts only after this delay timer expiry.
+```
+
+
+```{cfgcmd} set protocols ospf summary-address x.x.x.x/y [tag (1-4294967295)]
+
+This command enable/disables summarisation for the configured address range.
+
+Tag is the optional parameter. If tag configured Summary route will be
+originated with the configured tag.
+```
+
+
+```{cfgcmd} set protocols ospf summary-address x.x.x.x/y no-advertise
+
+This command to ensure not advertise the summary lsa for the matched
+external LSAs.
+```
+
+#### Graceful Restart
+
+```{cfgcmd} set protocols ospf graceful-restart [grace-period (1-1800)]
+
+Configure Graceful Restart {rfc}`3623` restarting support. When enabled,
+the default grace period is 120 seconds.
+
+To perform a graceful shutdown, the FRR ``graceful-restart prepare ip
+ospf`` EXEC-level command needs to be issued before restarting the
+ospfd daemon.
+```
+
+
+```{cfgcmd} set protocols ospf graceful-restart helper enable [router-id A.B.C.D]
+
+Configure Graceful Restart {rfc}`3623` helper support. By default, helper support
+is disabled for all neighbours. This config enables/disables helper support
+on this router for all neighbours.
+
+To enable/disable helper support for a specific neighbour, the router-id
+(A.B.C.D) has to be specified.
+```
+
+
+```{cfgcmd} set protocols ospf graceful-restart helper no-strict-lsa-checking
+
+By default strict-lsa-checking is configured then the helper will abort
+the Graceful Restart when a LSA change occurs which affects the restarting
+router.
+
+This command disables it.
+```
+
+
+```{cfgcmd} set protocols ospf graceful-restart helper supported-grace-time
+
+Supports as HELPER for configured grace period.
+```
+
+
+```{cfgcmd} set protocols ospf graceful-restart helper planned-only
+
+It helps to support as HELPER only for planned restarts.
+
+By default, it supports both planned and unplanned outages.
+```
+
+#### Manual Neighbor Configuration
+
+
+OSPF routing devices normally discover their neighbors dynamically by
+listening to the broadcast or multicast hello packets on the network.
+Because an NBMA network does not support broadcast (or multicast), the
+device cannot discover its neighbors dynamically, so you must configure all
+the neighbors statically.
+
+```{cfgcmd} set protocols ospf neighbor \<A.B.C.D\>
+
+This command specifies the IP address of the neighboring device.
+```
+
+
+```{cfgcmd} set protocols ospf neighbor \<A.B.C.D\> poll-interval \<seconds\>
+
+This command specifies the length of time, in seconds, before the routing
+device sends hello packets out of the interface before it establishes
+adjacency with a neighbor. The range is 1 to 65535 seconds. The default
+value is 60 seconds.
+```
+
+
+```{cfgcmd} set protocols ospf neighbor \<A.B.C.D\> priority \<number\>
+
+This command specifies the router priority value of the nonbroadcast
+neighbor associated with the IP address specified. The default is 0.
+This keyword does not apply to point-to-multipoint interfaces.
+```
+
+#### Redistribution Configuration
+
+```{cfgcmd} set protocols ospf redistribute \<route source\>
+
+   This command redistributes routing information from the given route source
+   to the OSPF process. There are five modes available for route source: bgp,
+   connected, kernel, rip, static.
+```
+
+
+```{cfgcmd} set protocols ospf default-metric \<number\>
+
+This command specifies the default metric value of redistributed routes.
+The metric range is 0 to 16777214.
+```
+
+
+```{cfgcmd} set protocols ospf redistribute \<route source\> metric \<number\>
+
+This command specifies metric for redistributed routes from the given
+route source. There are five modes available for route source: bgp,
+connected, kernel, rip, static. The metric range is 1 to 16777214.
+```
+
+
+```{cfgcmd} set protocols ospf redistribute \<route source\> metric-type \<1|2\>
+
+This command specifies metric type for redistributed routes. Difference
+between two metric types that metric type 1 is a metric which is
+"commensurable" with inner OSPF links. When calculating a metric to the
+external destination, the full path metric is calculated as a metric sum
+path of a router which had advertised this link plus the link metric.
+Thus, a route with the least summary metric will be selected. If external
+link is advertised with metric type 2 the path is selected which lies
+through the router which advertised this link with the least metric
+despite of the fact that internal path to this router is longer (with more
+cost). However, if two routers advertised an external link and with metric
+type 2 the preference is given to the path which lies through the router
+with a shorter internal path. If two different routers advertised two
+links to the same external destimation but with different metric type,
+metric type 1 is preferred. If type of a metric left undefined the router
+will consider these external links to have a default metric type 2.
+```
+
+
+```{cfgcmd} set protocols ospf redistribute \<route source\> route-map \<name\>
+
+This command allows to use route map to filter redistributed routes from
+the given route source. There are five modes available for route source:
+bgp, connected, kernel, rip, static.
+```
+
+#### Operational Mode Commands
+
+```{opcmd} show ip ospf neighbor
+
+   This command displays the neighbors status.
+```
+
+
+```none
+Neighbor ID     Pri State           Dead Time Address         Interface                        RXmtL RqstL DBsmL
+10.0.13.1         1 Full/DR           38.365s 10.0.13.1       eth0:10.0.13.3                       0     0     0
+10.0.23.2         1 Full/Backup       39.175s 10.0.23.2       eth1:10.0.23.3                       0     0     0
+```
+
+
+```{opcmd} show ip ospf neighbor detail
+
+This command displays the neighbors information in a detailed form, not
+just a summary table.
+```
+
+
+```none
+ Neighbor 10.0.13.1, interface address 10.0.13.1
+
+    In the area 0.0.0.0 via interface eth0
+
+    Neighbor priority is 1, State is Full, 5 state changes
+
+    Most recent state change statistics:
+
+      Progressive change 11m55s ago
+
+    DR is 10.0.13.1, BDR is 10.0.13.3
+
+    Options 2 *|-|-|-|-|-|E|-
+
+    Dead timer due in 34.854s
+
+    Database Summary List 0
+
+    Link State Request List 0
+
+    Link State Retransmission List 0
+
+    Thread Inactivity Timer on
+
+    Thread Database Description Retransmision off
+
+    Thread Link State Request Retransmission on
+
+    Thread Link State Update Retransmission on
+
+
+Neighbor 10.0.23.2, interface address 10.0.23.2
+
+   In the area 0.0.0.1 via interface eth1
+
+   Neighbor priority is 1, State is Full, 4 state changes
+
+   Most recent state change statistics:
+
+     Progressive change 41.193s ago
+
+   DR is 10.0.23.3, BDR is 10.0.23.2
+
+   Options 2 *|-|-|-|-|-|E|-
+
+   Dead timer due in 35.661s
+
+   Database Summary List 0
+
+   Link State Request List 0
+
+   Link State Retransmission List 0
+
+   Thread Inactivity Timer on
+
+   Thread Database Description Retransmision off
+
+   Thread Link State Request Retransmission on
+
+   Thread Link State Update Retransmission on
+```
+
+
+```{opcmd} show ip ospf neighbor \<A.B.C.D\>
+
+This command displays the neighbors information in a detailed form for a
+neighbor whose IP address is specified.
+```
+
+
+```{opcmd} show ip ospf neighbor \<interface\>
+
+This command displays the neighbors status for a neighbor on the specified
+interface.
+```
+
+
+```{opcmd} show ip ospf interface [\<interface\>]
+
+This command displays state and configuration of OSPF the specified
+interface, or all interfaces if no interface is given.
+```
+
+
+```none
+eth0 is up
+  ifindex 2, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST>
+  Internet Address 10.0.13.3/24, Broadcast 10.0.13.255, Area 0.0.0.0
+  MTU mismatch detection: enabled
+  Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1
+  Transmit Delay is 1 sec, State Backup, Priority 1
+  Backup Designated Router (ID) 10.0.23.3, Interface Address 10.0.13.3
+  Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters
+  Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5
+    Hello due in 4.470s
+  Neighbor Count is 1, Adjacent neighbor count is 1
+eth1 is up
+  ifindex 3, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST>
+  Internet Address 10.0.23.3/24, Broadcast 10.0.23.255, Area 0.0.0.1
+  MTU mismatch detection: enabled
+  Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1
+  Transmit Delay is 1 sec, State DR, Priority 1
+  Backup Designated Router (ID) 10.0.23.2, Interface Address 10.0.23.2
+  Saved Network-LSA sequence number 0x80000002
+  Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters
+  Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5
+    Hello due in 4.563s
+  Neighbor Count is 1, Adjacent neighbor count is 1
+```
+
+
+```{opcmd} show ip ospf route [detail]
+
+This command displays the OSPF routing table, as determined by the most
+recent SPF calculation. With the optional {cfgcmd}`detail` argument,
+each route item's advertiser router and network attribute will be shown.
+```
+
+
+```none
+============ OSPF network routing table ============
+N IA 10.0.12.0/24          [3] area: 0.0.0.0
+                           via 10.0.13.3, eth0
+N    10.0.13.0/24          [1] area: 0.0.0.0
+                           directly attached to eth0
+N IA 10.0.23.0/24          [2] area: 0.0.0.0
+                           via 10.0.13.3, eth0
+N    10.0.34.0/24          [2] area: 0.0.0.0
+                           via 10.0.13.3, eth0
+
+============ OSPF router routing table =============
+R    10.0.23.3             [1] area: 0.0.0.0, ABR
+                           via 10.0.13.3, eth0
+R    10.0.34.4             [2] area: 0.0.0.0, ASBR
+                           via 10.0.13.3, eth0
+
+============ OSPF external routing table ===========
+N E2 172.16.0.0/24         [2/20] tag: 0
+                           via 10.0.13.3, eth0
+```
+
+The table consists of following data:
+
+
+**OSPF network routing table** – includes a list of acquired routes for all
+accessible networks (or aggregated area ranges) of OSPF system. "IA" flag
+means that route destination is in the area to which the router is not
+connected, i.e. it’s an inter-area path. In square brackets a summary metric
+for all links through which a path lies to this network is specified. "via"
+prefix defines a router-gateway, i.e. the first router on the way to the
+destination (next hop).
+**OSPF router routing table** – includes a list of acquired routes to all
+accessible ABRs and ASBRs.
+**OSPF external routing table** – includes a list of acquired routes that are
+external to the OSPF process. "E" flag points to the external link metric type
+(E1 – metric type 1, E2 – metric type 2). External link metric is printed in
+the "\<metric of the router which advertised the link>/\<link metric>" format.
+
+```{opcmd} show ip ospf border-routers
+
+This command displays a table of paths to area boundary and autonomous
+system boundary routers.
+```
+
+
+```{opcmd} show ip ospf database
+
+This command displays a summary table with a database contents (LSA).
+```
+
+
+```none
+       OSPF Router with ID (10.0.13.1)
+
+                Router Link States (Area 0.0.0.0)
+
+Link ID         ADV Router      Age  Seq#       CkSum  Link count
+10.0.13.1       10.0.13.1        984 0x80000005 0xd915 1
+10.0.23.3       10.0.23.3       1186 0x80000008 0xfe62 2
+10.0.34.4       10.0.34.4       1063 0x80000004 0x4e3f 1
+
+                Net Link States (Area 0.0.0.0)
+
+Link ID         ADV Router      Age  Seq#       CkSum
+10.0.13.1       10.0.13.1        994 0x80000003 0x30bb
+10.0.34.4       10.0.34.4       1188 0x80000001 0x9411
+
+                Summary Link States (Area 0.0.0.0)
+
+Link ID         ADV Router      Age  Seq#       CkSum  Route
+10.0.12.0       10.0.23.3       1608 0x80000001 0x6ab6 10.0.12.0/24
+10.0.23.0       10.0.23.3        981 0x80000003 0xe232 10.0.23.0/24
+
+                AS External Link States
+
+Link ID         ADV Router      Age  Seq#       CkSum  Route
+172.16.0.0      10.0.34.4       1063 0x80000001 0xc40d E2 172.16.0.0/24 [0x0]
+```
+
+
+```{opcmd} show ip ospf database \<type\> [A.B.C.D] [adv-router \<A.B.C.D\>|self-originate]
+
+ This command displays a database contents for a specific link advertisement
+ type.
+
+ The type can be the following:
+ asbr-summary, external, network, nssa-external, opaque-area, opaque-as,
+ opaque-link, router, summary.
+
+ [A.B.C.D] – link-state-id. With this specified the command displays portion
+ of the network environment that is being described by the advertisement.
+ The value entered depends on the advertisement’s LS type. It must be
+ entered in the form of an IP address.
+
+ {cfgcmd}`adv-router <A.B.C.D>` – router id, which link advertisements need
+ to be reviewed.
+
+ {cfgcmd}`self-originate` displays only self-originated LSAs from the local
+ router.
+```
+
+
+```none
+        OSPF Router with ID (10.0.13.1)
+
+              Router Link States (Area 0.0.0.0)
+
+LS age: 1213
+Options: 0x2  : *|-|-|-|-|-|E|-
+LS Flags: 0x3
+Flags: 0x0
+LS Type: router-LSA
+Link State ID: 10.0.13.1
+Advertising Router: 10.0.13.1
+LS Seq Number: 80000009
+Checksum: 0xd119
+Length: 36
+
+ Number of Links: 1
+
+  Link connected to: a Transit Network
+   (Link ID) Designated Router address: 10.0.13.1
+   (Link Data) Router Interface address: 10.0.13.1
+   Number of TOS metrics: 0
+     TOS 0 Metric: 1
+```
+
+
+```{opcmd} show ip ospf database max-age
+
+This command displays LSAs in MaxAge list.
+```
+
+#### Examples
+### Enable OSPF
+
+**Node 1**
+
+```none
+set interfaces loopback lo address 10.1.1.1/32
+set interfaces ethernet eth0 address 192.168.0.1/24
+set protocols ospf area 0 network 192.168.0.0/24
+set protocols ospf area 0 network 10.1.1.1/32
+set protocols ospf parameters router-id 10.1.1.1
+```
+
+**Node 2**
+
+```none
+set interfaces loopback lo address 10.1.1.2/32
+set interfaces ethernet eth0 address 192.168.0.2/24
+set protocols ospf area 0 network 192.168.0.0/24
+set protocols ospf area 0 network 10.1.1.2/32
+set protocols ospf parameters router-id 10.1.1.2
+```
+
+Here's the neighbors up:
+
+```none
+Node-1@vyos:~$ show ip ospf neighbor
+
+Neighbor ID     Pri State           Up Time         Dead Time Address         Interface                        RXmtL RqstL DBsmL
+10.1.1.2          1 Full/DR         3m43s             36.094s 192.168.0.2     eth0:192.168.0.1                     0     0     0
+
+
+Node-2@vyos:~$ show ip ospf neighbor
+
+Neighbor ID     Pri State           Up Time         Dead Time Address         Interface                        RXmtL RqstL DBsmL
+10.1.1.1          1 Full/Backup     3m47s             31.736s 192.168.0.1     eth0:192.168.0.2                     0     0     0
+```
+
+Here's the routes:
+
+```none
+Node-1@vyos:~$ show ip route ospf
+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
+
+O   10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:00:14
+O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, weight 1, 00:00:07
+O   192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:32
+
+Node-2@vyos:~$ show ip route ospf
+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
+
+O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, weight 1, 00:00:11
+O   10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:00:04
+O   192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:18
+```
+
+### Enable OSPF with route redistribution of the loopback and default originate:
+
+**Node 1**
+
+```none
+set interfaces loopback lo address 10.1.1.1/32
+set protocols ospf area 0 network 192.168.0.0/24
+set protocols ospf default-information originate always
+set protocols ospf default-information originate metric 10
+set protocols ospf default-information originate metric-type 2
+set protocols ospf log-adjacency-changes
+set protocols ospf parameters router-id 10.1.1.1
+set protocols ospf redistribute connected metric-type 2
+set protocols ospf redistribute connected route-map CONNECT
+
+set policy route-map CONNECT rule 10 action permit
+set policy route-map CONNECT rule 10 match interface lo
+```
+
+**Node 2**
+
+```none
+set interfaces loopback lo address 10.2.2.2/32
+set protocols ospf area 0 network 192.168.0.0/24
+set protocols ospf log-adjacency-changes
+set protocols ospf parameters router-id 10.2.2.2
+set protocols ospf redistribute connected metric-type 2
+set protocols ospf redistribute connected route-map CONNECT
+
+set policy route-map CONNECT rule 10 action permit
+set policy route-map CONNECT rule 10 match interface lo
+```
+
+### Enable OSPF and IGP-LDP synchronization:
+
+**Node 1:**
+
+```none
+set interfaces loopback lo address 10.1.1.1/32
+set interfaces ethernet eth0 address 192.168.0.1/24
+
+set protocols ospf area 0 network '192.168.0.0/24'
+set protocols ospf area 0 network '10.1.1.1/32'
+set protocols ospf parameters router-id '10.1.1.1'
+set protocols ospf ldp-sync
+
+set protocols mpls interface eth0
+set protocols mpls ldp discovery transport-ipv4-address 10.1.1.1
+set protocols mpls ldp interface lo
+set protocols mpls ldp interface eth0
+set protocols mpls ldp parameters transport-prefer-ipv4
+set protocols mpls ldp router-id 10.1.1.1
+```
+
+This gives us IGP-LDP synchronization for all non-loopback interfaces with
+a holddown timer of zero seconds:
+
+```none
+Node-1@vyos:~$ show ip ospf mpls ldp-sync
+  eth0
+  LDP-IGP Synchronization enabled: yes
+  Holddown timer in seconds: 0
+  State: Sync achieved
+```
+
+### Enable OSPF with Segment Routing (Experimental):
+
+**Node 1**
+
+```none
+set interfaces loopback lo address 10.1.1.1/32
+set interfaces ethernet eth0 address 192.168.0.1/24
+
+set protocols ospf area 0 network '192.168.0.0/24'
+set protocols ospf area 0 network '10.1.1.1/32'
+set protocols ospf parameters opaque-lsa
+set protocols ospf parameters router-id '10.1.1.1'
+set protocols ospf segment-routing global-block high-label-value '1100'
+set protocols ospf segment-routing global-block low-label-value '1000'
+set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null
+set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1'
+```
+
+**Node 2**
+
+```none
+set interfaces loopback lo address 10.1.1.2/32
+set interfaces ethernet eth0 address 192.168.0.2/24
+
+set protocols ospf area 0 network '192.168.0.0/24'
+set protocols ospf area 0 network '10.1.1.2/32'
+set protocols ospf parameters opaque-lsa
+set protocols ospf parameters router-id '10.1.1.2'
+set protocols ospf segment-routing global-block high-label-value '1100'
+set protocols ospf segment-routing global-block low-label-value '1000'
+set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null
+set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2'
+```
+
+This gives us MPLS segment routing enabled and labels for far end loopbacks:
+
+```none
+Node-1@vyos:~$ show mpls table
+ Inbound Label  Type       Nexthop      Outbound Label
+ -----------------------------------------------------------
+ 1002           SR (OSPF)  192.168.0.2  IPv4 Explicit Null  <-- Node-2 loopback learned on Node-1
+ 15000          SR (OSPF)  192.168.0.2  implicit-null
+ 15001          SR (OSPF)  192.168.0.2  implicit-null
+
+Node-2@vyos:~$ show mpls table
+ Inbound Label  Type       Nexthop      Outbound Label
+ -----------------------------------------------------------
+ 1001           SR (OSPF)  192.168.0.1  IPv4 Explicit Null  <-- Node-1 loopback learned on Node-2
+ 15000          SR (OSPF)  192.168.0.1  implicit-null
+ 15001          SR (OSPF)  192.168.0.1  implicit-null
+```
+
+Here is the routing tables showing the MPLS segment routing label operations:
+
+```none
+Node-1@vyos:~$ show ip route ospf
+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
+
+O   10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43
+O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32
+O   192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43
+
+Node-2@vyos:~$ show ip route ospf
+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
+
+O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36
+O   10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51
+O   192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51
+```
+
+(routing-ospfv3)=
+
+## OSPFv3 (IPv6)
+
+(ospf-v3-configuration)=
+
+### Configuration
+
+(ospf-v3-general)=
+
+#### General
+
+VyOS does not have a special command to start the OSPFv3 process. The OSPFv3
+process starts when the first ospf enabled interface is configured.
+
+```{cfgcmd} set protocols ospfv3 interface \<interface\> area \<number\>
+
+   This command specifies the OSPFv3 enabled interface. This command is also
+   used to enable the OSPF process. The area number can be specified in
+   decimal notation in the range from 0 to 4294967295. Or it can be specified
+   in dotted decimal notation similar to ip address.
+```
+
+
+```{cfgcmd} set protocols ospfv3 parameters router-id \<rid\>
+
+This command sets the router-ID of the OSPFv3 process. The router-ID may be
+an IP address of the router, but need not be – it can be any arbitrary
+32bit number. However it MUST be unique within the entire OSPFv3 domain to
+the OSPFv3 speaker – bad things will happen if multiple OSPFv3 speakers are
+configured with the same router-ID!
+```
+
+(ospf-v3-optional)=
+
+#### Optional
+
+```{cfgcmd} set protocols ospfv3 distance global \<distance\>
+
+This command change distance value of OSPFv3 globally.
+The distance range is 1 to 255.
+```
+```{cfgcmd} set protocols ospfv3 distance ospfv3 \<external|inter-area|intra-area\> \<distance\>
+
+This command change distance value of OSPFv3. The arguments are the
+distance values for external routes, inter-area routes and intra-area
+routes respectively. The distance range is 1 to 255.
+```
+
+(ospf-v3-area-configuration)=
+
+#### Area Configuration
+
+```{cfgcmd} set protocols ospfv3 area \<number\> range \<prefix\>
+
+This command summarizes intra area paths from specified area into one
+Type-3 Inter-Area Prefix LSA announced to other areas. This command can be
+used only in ABR.
+```
+```{cfgcmd} set protocols ospfv3 area \<number\> range \<prefix\> not-advertise
+
+This command instead of summarizing intra area paths filter them - i.e.
+intra area paths from this range are not advertised into other areas. This
+command makes sense in ABR only.
+```
+
+(ospf-v3-interface-config)=
+
+#### Interface Configuration
+
+```{cfgcmd} set protocols ospfv3 interface \<interface\> ipv6 cost \<number\>
+
+This command sets link cost for the specified interface. The cost value is
+set to router-LSA’s metric field and used for SPF calculation. The cost
+range is 1 to 65535.
+```
+```{cfgcmd} set protocols ospfv3 interface \<interface\> dead-interval \<number\>
+
+Set number of seconds for router Dead Interval timer value used for Wait
+Timer and Inactivity Timer. This value must be the same for all routers
+attached to a common network. The default value is 40 seconds. The
+interval range is 1 to 65535.
+```
+```{cfgcmd} set protocols ospfv3 interface \<interface\> hello-interval \<number\>
+
+Set number of seconds for Hello Interval timer value. Setting this value,
+Hello packet will be sent every timer value seconds on the specified
+interface. This value must be the same for all routers attached to a
+common network. The default value is 10 seconds. The interval range is 1
+to 65535.
+```
+```{cfgcmd} set protocols ospfv3 interface \<interface\> mtu-ignore
+
+This command disables check of the MTU value in the OSPF DBD packets.
+Thus, use of this command allows the OSPF adjacency to reach the FULL
+state even though there is an interface MTU mismatch between two OSPF
+routers.
+```
+```{cfgcmd} set protocols ospfv3 interface \<interface\> network \<type\>
+
+This command allows to specify the distribution type for the network
+connected to this interface:
+
+**broadcast** – broadcast IP addresses distribution.
+**point-to-point** – address distribution in point-to-point networks.
+```
+```{cfgcmd} set protocols ospfv3 interface \<interface\> priority \<number\>
+
+This command sets Router Priority integer value. The router with the
+highest priority will be more eligible to become Designated Router.
+Setting the value to 0, makes the router ineligible to become Designated
+Router. The default value is 1. The interval range is 0 to 255.
+```
+```{cfgcmd} set protocols ospfv3 interface \<interface\> passive
+
+This command specifies interface as passive. Passive interface advertises
+its address, but does not run the OSPF protocol (adjacencies are not formed
+and hello packets are not generated).
+```
+```{cfgcmd} set protocols ospfv3 interface \<interface\> retransmit-interval \<number\>
+
+This command sets number of seconds for RxmtInterval timer value. This
+value is used when retransmitting Database Description and Link State
+Request packets if acknowledge was not received. The default value is 5
+seconds. The interval range is 3 to 65535.
+```
+```{cfgcmd} set protocols ospfv3 interface \<interface\> transmit-delay \<number\>
+
+This command sets number of seconds for InfTransDelay value. It allows to
+set and adjust for each interface the delay interval before starting the
+synchronizing process of the router's database with all neighbors. The
+default value is 1 seconds. The interval range is 3 to 65535.
+```
+
+(ospf-v3-graceful-restart)=
+
+#### Graceful Restart
+
+```{cfgcmd} set protocols ospfv3 graceful-restart [grace-period (1-1800)]
+
+Configure Graceful Restart {rfc}`3623` restarting support. When enabled,
+the default grace period is 120 seconds.
+
+To perform a graceful shutdown, the FRR ``graceful-restart prepare ip
+ospf`` EXEC-level command needs to be issued before restarting the
+ospfd daemon.
+```
+```{cfgcmd} set protocols ospfv3 graceful-restart helper enable [router-id A.B.C.D]
+
+Configure Graceful Restart {rfc}`3623` helper support. By default, helper support
+is disabled for all neighbours. This config enables/disables helper support
+on this router for all neighbours.
+
+To enable/disable helper support for a specific neighbour, the router-id
+(A.B.C.D) has to be specified.
+```
+```{cfgcmd} set protocols ospfv3 graceful-restart helper lsa-check-disable
+
+By default strict-lsa-checking is configured then the helper will abort
+the Graceful Restart when a LSA change occurs which affects the restarting
+router.
+
+This command disables it.
+```
+```{cfgcmd} set protocols ospfv3 graceful-restart helper supported-grace-time
+
+Supports as HELPER for configured grace period.
+```
+```{cfgcmd} set protocols ospfv3 graceful-restart helper planned-only
+
+It helps to support as HELPER only for planned restarts.
+By default, it supports both planned and unplanned outages.
+```
+
+(ospf-v3-redistribution-config)=
+
+#### Redistribution Configuration
+
+```{cfgcmd} set protocols ospfv3 redistribute \<route source\>
+
+This command redistributes routing information from the given route source
+to the OSPFv3 process. There are five modes available for route source:
+bgp, connected, kernel, ripng, static.
+```
+```{cfgcmd} set protocols ospf redistribute \<route source\> route-map \<name\>
+
+This command allows to use route map to filter redistributed routes from
+given route source. There are five modes available for route source: bgp,
+connected, kernel, ripng, static.
+```
+
+(ospf-v3-op-cmd)=
+
+#### Operational Mode Commands
+
+```{opcmd} show ipv6 ospfv3 neighbor
+
+This command displays the neighbors status.
+```
+```{opcmd} show ipv6 ospfv3 neighbor detail
+
+This command displays the neighbors information in a detailed form, not
+just a summary table.
+```
+```{opcmd} show ipv6 ospfv3 neighbor drchoice
+
+This command displays the neighbor DR choice information.
+```
+```{opcmd} show ipv6 ospfv3 interface [prefix]|[\<interface\> [prefix]]
+
+This command displays state and configuration of OSPF the specified
+interface, or all interfaces if no interface is given. Whith the argument
+{cfgcmd}`prefix` this command shows connected prefixes to advertise.
+```
+```{opcmd} show ipv6 ospfv3 route
+
+This command displays the OSPF routing table, as determined by the most
+recent SPF calculation.
+```
+```{opcmd} show ipv6 ospfv3 border-routers
+
+This command displays a table of paths to area boundary and autonomous
+system boundary routers.
+```
+```{opcmd} show ipv6 ospfv3 database
+
+This command displays a summary table with a database contents (LSA).
+```
+```{opcmd} show ipv6 ospfv3 database \<type\> [A.B.C.D] [adv-router \<A.B.C.D\>|self-originate]
+
+This command displays a database contents for a specific link
+advertisement type.
+```
+```{opcmd} show ipv6 ospfv3 redistribute
+
+This command displays external information redistributed into OSPFv3
+```
+
+(ospf-v3-config-example)=
+
+#### Configuration Example
+
+A typical configuration using 2 nodes.
+
+**Node 1:**
+
+```none
+set protocols ospfv3 interface eth1 area 0.0.0.0
+set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64
+set protocols ospfv3 parameters router-id 192.168.1.1
+set protocols ospfv3 redistribute connected
+```
+
+**Node 2:**
+
+```none
+set protocols ospfv3 interface eth1 area 0.0.0.0
+set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64
+set protocols ospfv3 parameters router-id 192.168.2.1
+set protocols ospfv3 redistribute connected
+```
+
+**To see the redistributed routes:**
+
+```none
+show ipv6 ospfv3 redistribute
+```
+
+Cost calculation wireguard interfaces is unreliable as ospfv3 uses the link speed to calculate the link cost.
+You might therefore want to set the link cost to a fixed value on WireGuard tunnels.
+
+Example configuration for WireGuard interfaces:
+
+**Node 1**
+
+```none
+set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0'
+set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345'
+set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...='
+set interfaces wireguard wg01 port '12345'
+set protocols ospfv3 parameters router-id 192.168.1.1
+set protocols ospfv3 interface 'wg01' area 0.0.0.0
+set protocols ospfv3 interface 'wg01' cost 10
+set protocols ospfv3 interface 'lo' area 0.0.0.0
+```
+
+**Node 2**
+
+```none
+set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0'
+set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345'
+set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...='
+set interfaces wireguard wg01 port '12345'
+set protocols ospfv3 parameters router-id 192.168.1.2
+set protocols ospfv3 interface 'wg01' area 0.0.0.0
+set protocols ospfv3 interface 'wg01' cost 10
+set protocols ospfv3 interface 'lo' area 0.0.0.0
+```
+
+**Status**
+
+```none
+vyos@ospf01:~$ sh ipv6 ospfv3 neighbor
+Neighbor ID     Pri    DeadTime    State/IfState         Duration I/F[State]
+192.168.0.2       1    00:00:37     Full/PointToPoint    00:18:03 wg01[PointToPoint]
+
+vyos@ospf02# run sh ipv6 ospfv3 neighbor
+Neighbor ID     Pri    DeadTime    State/IfState         Duration I/F[State]
+192.168.0.1       1    00:00:39     Full/PointToPoint    00:19:44 wg01[PointToPoint]
+```
diff --git a/docs/configuration/protocols/pim.md b/docs/configuration/protocols/pim.md
new file mode 100644
index 00000000..db8c9fb7
--- /dev/null
+++ b/docs/configuration/protocols/pim.md
@@ -0,0 +1,282 @@
+---
+lastproofread: '2023-11-13'
+---
+
+(pim)=
+
+# PIM – Protocol Independent Multicast
+
+VyOS supports {abbr}`PIM-SM (PIM Sparse Mode)` as well as
+{abbr}`IGMP (Internet Group Management Protocol)` v2 and v3
+
+{abbr}`PIM (Protocol Independent Multicast)` must be configured in every
+interface of every participating router. Every router must also have the
+location of the Rendevouz Point manually configured. Then, unidirectional
+shared trees rooted at the Rendevouz Point will automatically be built
+for multicast distribution.
+
+Traffic from multicast sources will go to the Rendezvous Point, and
+receivers will pull it from a shared tree using {abbr}`IGMP (Internet
+Group Management Protocol)`.
+
+Multicast receivers will talk IGMP to their local router, so, besides
+having PIM configured in every router, IGMP must also be configured in
+any router where there could be a multicast receiver locally connected.
+
+VyOS supports both IGMP version 2 and version 3 (which allows
+source-specific multicast).
+
+## PIM-SM - PIM Sparse Mode
+
+```{cfgcmd} set protocols pim ecmp
+
+If PIM has the a choice of ECMP nexthops for a particular
+{abbr}`RPF (Reverse Path Forwarding)`, PIM will cause S,G flows to be
+spread out amongst the nexthops. If this command is not specified then
+the first nexthop found will be used.
+```
+
+```{cfgcmd} set protocols pim ecmp rebalance
+
+If PIM is using ECMP and an interface goes down, cause PIM to rebalance all
+S,G flows across the remaining nexthops. If this command is not configured
+PIM only modifies those S,G flows that were using the interface that went
+down.
+```
+
+```{cfgcmd} set protocols pim join-prune-interval \<n\>
+
+Modify the join/prune interval that PIM uses to the new value. Time is
+specified in seconds.
+
+The default time is 60 seconds.
+
+If you enter a value smaller than 60 seconds be aware that this can and
+will affect convergence at scale.
+```
+
+```{cfgcmd} set protocols pim keep-alive-timer \<n\>
+
+Modify the time out value for a S,G flow from 1-65535 seconds. If choosing
+a value below 31 seconds be aware that some hardware platforms cannot see
+data flowing in better than 30 second chunks.
+```
+
+```{cfgcmd} set protocols pim packets \<n\>
+
+When processing packets from a neighbor process the number of packets
+incoming at one time before moving on to the next task.
+
+The default value is 3 packets.
+
+This command is only useful at scale when you can possibly have a large
+number of PIM control packets flowing.
+```
+
+```{cfgcmd} set protocols pim register-accept-list \<prefix-list\>
+
+When PIM receives a register packet the source of the packet will be compared
+to the prefix-list specified, and if a permit is received normal processing
+continues. If a deny is returned for the source address of the register packet
+a register stop message is sent to the source.
+```
+
+```{cfgcmd} set protocols pim register-suppress-time \<n\>
+
+Modify the time that pim will register suppress a FHR will send register
+notifications to the kernel.
+```
+
+```{cfgcmd} set protocols pim rp \<address\> group \<group\>
+
+In order to use PIM, it is necessary to configure a {abbr}`RP (Rendezvous Point)`
+for join messages to be sent to. Currently the only methodology to do this is
+via static rendezvous point commands.
+
+All routers in the PIM network must agree on these values.
+
+The first ip address is the RP's address and the second value is the matching
+prefix of group ranges covered.
+```
+
+```{cfgcmd} set protocols pim rp keep-alive-timer \<n\>
+
+Modify the time out value for a S,G flow from 1-65535 seconds at
+{abbr}`RP (Rendezvous Point)`. The normal keepalive period for the KAT(S,G)
+defaults to 210 seconds. However, at the {abbr}`RP (Rendezvous Point)`, the
+keepalive period must be at least the Register_Suppression_Time, or the RP
+may time out the (S,G) state before the next Null-Register arrives.
+Thus, the KAT(S,G) is set to max(Keepalive_Period, RP_Keepalive_Period)
+when a Register-Stop is sent.
+
+If choosing a value below 31 seconds be aware that some hardware platforms
+cannot see data flowing in better than 30 second chunks.
+
+See {rfc}`7761#section-4.1` for details.
+```
+
+```{cfgcmd} set protocols pim no-v6-secondary
+
+When sending PIM hello packets tell PIM to not send any v6 secondary
+addresses on the interface. This information is used to allow PIM to use v6
+nexthops in it's decision for {abbr}`RPF (Reverse Path Forwarding)` lookup
+if this option is not set (default).
+```
+
+```{cfgcmd} set protocols pim spt-switchover infinity-and-beyond [prefix-list \<list\>]
+
+On the last hop router if it is desired to not switch over to the SPT tree
+configure this command.
+
+Optional parameter prefix-list can be use to control which groups to switch or
+not switch. If a group is PERMIT as per the prefix-list, then the SPT switchover
+does not happen for it and if it is DENY, then the SPT switchover happens.
+```
+
+```{cfgcmd} set protocols pim ssm prefix-list \<list\>
+
+Specify a range of group addresses via a prefix-list that forces PIM to never
+do {abbr}`SSM (Source-Specific Multicast)` over.
+```
+
+
+### Interface specific commands
+
+```{cfgcmd} set protocols pim interface \<interface\> bfd [profile \<name\>]
+
+Automatically create BFD session for each RIP peer discovered in this
+interface. When the BFD session monitor signalize that the link is down
+the RIP peer is removed and all the learned routes associated with that
+peer are removed.
+
+If optional profile parameter is used, select a BFD profile for the BFD
+sessions created via this interface.
+```
+
+```{cfgcmd} set protocols pim interface \<interface\> dr-priority \<n\>
+
+Set the {abbr}`DR (Designated Router)` Priority for the interface.
+This command is useful to allow the user to influence what node becomes
+the DR for a LAN segment.
+```
+
+```{cfgcmd} set protocols pim interface \<interface\> hello \<n\>
+
+Set the PIM hello and hold interval for a interface.
+```
+
+```{cfgcmd} set protocols pim interface \<interface\> no-bsm
+
+Tell PIM that we would not like to use this interface to process
+bootstrap messages.
+```
+
+```{cfgcmd} set protocols pim interface \<interface\> no-unicast-bsm
+
+Tell PIM that we would not like to use this interface to process
+unicast bootstrap messages.
+```
+
+```{cfgcmd} set protocols pim interface \<interface\> passive
+
+Disable sending and receiving PIM control packets on the interface.
+```
+
+```{cfgcmd} set protocols pim interface \<interface\> source-address \<ip-address\>
+
+If you have multiple addresses configured on a particular interface and would
+like PIM to use a specific source address associated with that interface.
+```
+
+
+## IGMP - Internet Group Management Protocol)
+
+```{cfgcmd} set protocols pim igmp watermark-warning \<n\>
+
+Configure watermark warning generation for an IGMP group limit. Generates
+warning once the configured group limit is reached while adding new groups.
+```
+
+(pim-igmp-interface-commands)=
+
+### Interface specific commands
+
+```{cfgcmd} set protocols pim interface \<interface\> igmp join \<multicast-address\> source-address \<IP-address\>
+
+Use this command to allow the selected interface to join a multicast
+group defining the multicast address you want to join and the source
+IP address too.
+```
+
+```{cfgcmd} set protocols pim interface \<interface\> igmp query-interval \<seconds\>
+
+Use this command to configure in the selected interface the IGMP
+host query interval (1-1800) in seconds that PIM will use.
+```
+
+```{cfgcmd} set protocols pim interface \<interface\> igmp query-max-response-time \<n\>
+
+Use this command to configure in the selected interface the IGMP
+query response timeout value (10-250) in deciseconds. If a report is
+not returned in the specified time, it will be assumed the (S,G) or
+(\*,G) state {rfc}`7761#section-4.1` has timed out.
+```
+
+```{cfgcmd} set protocols pim interface \<interface\> igmp version \<version-number\>
+
+Use this command to define in the selected interface whether you
+choose IGMP version 2 or 3.
+
+The default value is 3.
+```
+
+
+#### Example
+
+In the following example we can see a basic multicast setup:
+
+```{image} /_static/images/multicast-basic.webp
+:align: center
+:alt: Network Topology Diagram
+:width: 90%
+```
+
+**Router 1**
+
+```none
+set interfaces ethernet eth2 address '172.16.0.2/24'
+set interfaces ethernet eth1 address '100.64.0.1/24'
+set protocols ospf area 0 network '172.16.0.0/24'
+set protocols ospf area 0 network '100.64.0.0/24'
+set protocols igmp interface eth1
+set protocols pim interface eth1
+set protocols pim interface eth2
+set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
+```
+
+**Router 3**
+
+```none
+set interfaces dummy dum0 address '172.16.255.1/24'
+set interfaces ethernet eth0 address '172.16.0.1/24'
+set interfaces ethernet eth1 address '172.16.1.1/24'
+set protocols ospf area 0 network '172.16.0.0/24'
+set protocols ospf area 0 network '172.16.255.0/24'
+set protocols ospf area 0 network '172.16.1.0/24'
+set protocols pim interface dum0
+set protocols pim interface eth0
+set protocols pim interface eth1
+set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
+```
+
+**Router 2**
+
+```none
+set interfaces ethernet eth1 address '10.0.0.1/24'
+set interfaces ethernet eth2 address '172.16.1.2/24'
+set protocols ospf area 0 network '10.0.0.0/24'
+set protocols ospf area 0 network '172.16.1.0/24'
+set protocols pim interface eth1
+set protocols pim interface eth2
+set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
+```
diff --git a/docs/configuration/protocols/pim6.md b/docs/configuration/protocols/pim6.md
new file mode 100644
index 00000000..707ae606
--- /dev/null
+++ b/docs/configuration/protocols/pim6.md
@@ -0,0 +1,100 @@
+(pim6)=
+
+# PIM6 - Protocol Independent Multicast for IPv6
+
+VyOS facilitates IPv6 Multicast by supporting **PIMv6** and **MLD**.
+
+PIMv6 (Protocol Independent Multicast for IPv6) must be configured in every
+interface of every participating router. Every router must also have the
+location of the Rendevouz Point manually configured.
+Then, unidirectional shared trees rooted at the Rendevouz Point will
+automatically be built for multicast distribution.
+
+Traffic from multicast sources will go to the Rendezvous Point, and receivers
+will pull it from a shared tree using MLD (Multicast Listener Discovery).
+
+Multicast receivers will talk MLD to their local router, so, besides having
+PIMv6 configured in every router, MLD must also be configured in any router
+where there could be a multicast receiver locally connected.
+
+VyOS supports both MLD version 1 and version 2
+(which allows source-specific multicast).
+
+## Basic commands
+
+These are the commands for a basic setup.
+
+```{cfgcmd} set protocols pim6 interface \<interface-name\>
+
+   Use this command to enable PIMv6 in the selected interface so that it
+   can communicate with PIMv6 neighbors. This command also enables MLD reports
+   and query on the interface unless {cfgcmd}`mld disable` is configured.
+```
+
+
+```{cfgcmd} set protocols pim6 interface \<interface-name\> mld disable
+
+Disable MLD reports and query on the interface.
+```
+
+
+## Tuning commands
+
+You can also tune multicast with the following commands.
+
+```{cfgcmd} set protocols pim6 interface \<interface-name\> mld interval \<seconds\>
+
+Use this command to configure in the selected interface the MLD
+host query interval (1-65535) in seconds that PIM will use.
+The default value is 125 seconds.
+```
+
+```{cfgcmd} set protocols pim6 interface \<interface-name\> mld join \<multicast-address\>
+
+Use this command to allow the selected interface to join a multicast group.
+```
+
+```{cfgcmd} set protocols pim6 interface \<interface-name\> mld join \<multicast-address\> source \<source-address\>
+
+Use this command to allow the selected interface to join a source-specific multicast
+group.
+```
+
+```{cfgcmd} set protocols pim6 interface \<interface-name\> mld last-member-query-count \<count\>
+
+Set the MLD last member query count. The default value is 2.
+```
+
+```{cfgcmd} set protocols pim6 interface \<interface-name\> mld last-member-query-interval \<milliseconds\>
+
+Set the MLD last member query interval in milliseconds (100-6553500). The default value is 1000 milliseconds.
+```
+
+```{cfgcmd} set protocols pim6 interface \<interface-name\> mld max-response-time \<milliseconds\>
+
+Set the MLD query response timeout in milliseconds (100-6553500). The default value is 10000 milliseconds.
+```
+
+```{cfgcmd} set protocols pim6 interface \<interface-name\> mld version \<version-number\>
+
+Set the MLD version used on this interface. The default value is 2.
+```
+
+
+### Configuration Example
+
+To enable MLD reports and query on interfaces `eth0` and `eth1`:
+
+```none
+set protocols pim6 interface eth0
+set protocols pim6 interface eth1
+```
+
+The following configuration explicitly joins multicast group `ff15::1234` on interface `eth1`
+and source-specific multicast group `ff15::5678` with source address `2001:db8::1` on interface
+`eth1`:
+
+```none
+set protocols pim6 interface eth0 mld join ff15::1234
+set protocols pim6 interface eth1 mld join ff15::5678 source 2001:db8::1
+```
diff --git a/docs/configuration/protocols/rip.md b/docs/configuration/protocols/rip.md
new file mode 100644
index 00000000..684337d6
--- /dev/null
+++ b/docs/configuration/protocols/rip.md
@@ -0,0 +1,294 @@
+---
+lastproofread: '2021-10-04'
+---
+
+(rip)=
+
+# RIP
+
+{abbr}`RIP (Routing Information Protocol)` is a widely deployed interior gateway
+protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS
+routing protocol. RIP is a distance-vector protocol and is based on the
+Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates
+to its neighbors periodically, thus allowing the convergence to a known
+topology. In each update, the distance to any given network will be broadcast
+to its neighboring router.
+
+Supported versions of RIP are:
+
+> - RIPv1 as described in {rfc}`1058`
+> - RIPv2 as described in {rfc}`2453`
+
+## General Configuration
+
+```{cfgcmd} set protocols rip network \<A.B.C.D/M\>
+
+This command enables RIP and sets the RIP enable interface by NETWORK.
+The interfaces which have addresses matching with NETWORK are enabled.
+```
+
+
+```{cfgcmd} set protocols rip interface \<interface\>
+
+This command specifies a RIP enabled interface by interface name. Both
+the sending and receiving of RIP packets will be enabled on the port
+specified in this command.
+```
+
+
+```{cfgcmd} set protocols rip neighbor \<A.B.C.D\>
+
+This command specifies a RIP neighbor. When a neighbor doesn’t understand
+multicast, this command is used to specify neighbors. In some cases, not
+all routers will be able to understand multicasting, where packets are
+sent to a network or a group of addresses. In a situation where a neighbor
+cannot process multicast packets, it is necessary to establish a direct
+link between routers.
+```
+
+
+```{cfgcmd} set protocols rip passive-interface interface \<interface\>
+
+This command sets the specified interface to passive mode. On passive mode
+interface, all receiving packets are processed as normal and VyOS does not
+send either multicast or unicast RIP packets except to RIP neighbors
+specified with neighbor command.
+```
+
+
+```{cfgcmd} set protocols rip passive-interface interface default
+
+This command specifies all interfaces to passive mode.
+```
+
+## Optional Configuration
+
+```{cfgcmd} set protocols rip default-distance \<distance\>
+
+This command change the distance value of RIP. The distance range is 1 to 255.
+
+> :::{note}
+> Routes with a distance of 255 are effectively disabled and not
+> installed into the kernel.
+> :::
+```
+
+
+```{cfgcmd} set protocols rip network-distance \<A.B.C.D/M\> distance \<distance\>
+
+This command sets default RIP distance to a specified value when the routes
+source IP address matches the specified prefix.
+```
+
+
+```{cfgcmd} set protocols rip network-distance \<A.B.C.D/M\> access-list \<name\>
+
+This command can be used with previous command to sets default RIP distance
+to specified value when the route source IP address matches the specified
+prefix and the specified access-list.
+```
+
+
+```{cfgcmd} set protocols rip default-information originate
+
+This command generate a default route into the RIP.
+```
+
+
+```{cfgcmd} set protocols rip distribute-list access-list \<in|out\> \<number\>
+
+This command can be used to filter the RIP path using access lists.
+{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the access
+lists are applied.
+```
+
+
+```{cfgcmd} set protocols rip distribute-list interface \<interface\> access-list \<in|out\> \<number\>
+
+This command allows you apply access lists to a chosen interface to
+filter the RIP path.
+```
+
+
+```{cfgcmd} set protocols rip distribute-list prefix-list \<in|out\> \<name\>
+
+This command can be used to filter the RIP path using prefix lists.
+{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the prefix
+lists are applied.
+```
+
+
+```{cfgcmd} set protocols rip distribute-list interface \<interface\> prefix-list \<in|out\> \<name\>
+
+This command allows you apply prefix lists to a chosen interface to
+filter the RIP path.
+```
+
+
+```{cfgcmd} set protocols rip route \<A.B.C.D/M\>
+
+This command is specific to FRR and VyOS. The route command makes a static
+route only inside RIP. This command should be used only by advanced users
+who are particularly knowledgeable about the RIP protocol. In most cases,
+we recommend creating a static route in VyOS and redistributing it in RIP
+using {cfgcmd}`redistribute static`.
+```
+
+
+```{cfgcmd} set protocols rip timers update \<seconds\>
+
+This command specifies the update timer. Every update timer seconds, the
+RIP process is awakened to send an unsolicited response message containing
+the complete routing table to all neighboring RIP routers. The time range
+is 5 to 2147483647. The default value is 30 seconds.
+```
+
+
+```{cfgcmd} set protocols rip timers timeout \<seconds\>
+
+This command specifies the timeout timer. Upon expiration of the timeout,
+the route is no longer valid; however, it is retained in the routing table
+for a short time so that neighbors can be notified that the route has been
+dropped. The time range is 5 to 2147483647. The default value is 180
+seconds.
+```
+
+
+```{cfgcmd} set protocols rip timers garbage-collection \<seconds\>
+
+This command specifies the garbage-collection timer. Upon expiration of
+the garbage-collection timer, the route is finally removed from the
+routing table. The time range is 5 to 2147483647. The default value is 120
+seconds.
+```
+
+## Redistribution Configuration
+
+```{cfgcmd} set protocols rip redistribute \<route source\>
+
+This command redistributes routing information from the given route source
+into the RIP tables. There are five modes available for route source: bgp,
+connected, kernel, ospf, static.
+```
+
+
+```{cfgcmd} set protocols rip redistribute \<route source\> metric \<metric\>
+
+This command specifies metric for redistributed routes from the given route
+source. There are five modes available for route source: bgp, connected,
+kernel, ospf, static. The metric range is 1 to 16.
+```
+
+
+```{cfgcmd} set protocols rip redistribute \<route source\> route-map \<name\>
+
+This command allows to use route map to filter redistributed routes from
+the given route source. There are five modes available for route source:
+bgp, connected, kernel, ospf, static.
+```
+
+
+```{cfgcmd} set protocols rip default-metric \<metric\>
+
+This command modifies the default metric (hop count) value for redistributed
+routes. The metric range is 1 to 16. The default value is 1. This command
+does not affect connected route even if it is redistributed by
+{cfgcmd}`redistribute connected`. To modify connected routes metric
+value, please use {cfgcmd}`redistribute connected metric`.
+```
+
+## Interfaces Configuration
+
+```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip authentication plaintext-password \<text\>
+
+This command sets the interface with RIP simple password authentication.
+This command also sets authentication string. The string must be shorter
+than 16 characters.
+```
+
+
+```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip authentication md5 \<id\> password \<text\>
+
+This command sets the interface with RIP MD5 authentication. This command
+also sets MD5 Key. The key must be shorter than 16 characters.
+```
+
+
+```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip split-horizon disable
+
+This command disables split-horizon on the interface. By default, VyOS does
+not advertise RIP routes out the interface over which they were learned
+(split horizon).3
+```
+
+
+```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip split-horizon poison-reverse
+
+This command enables poison-reverse on the interface. If both poison reverse
+and split horizon are enabled, then VyOS advertises the learned routes
+as unreachable over the interface on which the route was learned.
+```
+
+## Operational Mode Commands
+
+```{opcmd} show ip rip
+
+This command displays RIP routes.
+```
+```none
+Codes: R - RIP, C - connected, S - Static, O - OSPF, B - BGP
+Sub-codes:
+      (n) - normal, (s) - static, (d) - default, (r) - redistribute,
+      (i) - interface
+
+     Network            Next Hop         Metric From            Tag Time
+C(i) 10.0.12.0/24       0.0.0.0               1 self              0
+C(i) 10.0.13.0/24       0.0.0.0               1 self              0
+R(n) 10.0.23.0/24       10.0.12.2             2 10.0.12.2         0 02:53
+```
+
+```{opcmd} show ip rip status
+
+The command displays current RIP status. It includes RIP timer, filtering,
+version, RIP enabled interface and RIP peer information.
+```
+```none
+Routing Protocol is "rip"
+  Sending updates every 30 seconds with +/-50%, next due in 11 seconds
+  Timeout after 180 seconds, garbage collect after 120 seconds
+  Outgoing update filter list for all interface is not set
+  Incoming update filter list for all interface is not set
+  Default redistribution metric is 1
+  Redistributing:
+  Default version control: send version 2, receive any version
+    Interface        Send  Recv   Key-chain
+    eth0             2     1 2
+    eth2             2     1 2
+  Routing for Networks:
+    10.0.12.0/24
+    eth0
+  Routing Information Sources:
+    Gateway          BadPackets BadRoutes  Distance Last Update
+    10.0.12.2                0         0       120   00:00:11
+  Distance: (default is 120)
+```
+
+## Configuration Example
+
+Simple RIP configuration using 2 nodes and redistributing connected interfaces.
+
+**Node 1:**
+
+```none
+set interfaces loopback address 10.1.1.1/32
+set protocols rip network 192.168.0.0/24
+set protocols rip redistribute connected
+```
+
+**Node 2:**
+
+```none
+set interfaces loopback address 10.2.2.2/32
+set protocols rip network 192.168.0.0/24
+set protocols rip redistribute connected
+```
diff --git a/docs/configuration/protocols/rpki.md b/docs/configuration/protocols/rpki.md
new file mode 100644
index 00000000..1f4cf5bf
--- /dev/null
+++ b/docs/configuration/protocols/rpki.md
@@ -0,0 +1,210 @@
+(rpki)=
+
+# RPKI
+
+:::{pull-quote}
+
+There are two types of Network Admins who deal with BGP, those who have
+created an international incident and/or outage, and those who are lying
+
+-- [tweet by EvilMog](https://twitter.com/Evil_Mog/status/1230924170508169216), 2020-02-21
+:::
+
+{abbr}`RPKI (Resource Public Key Infrastructure)` is a framework designed to
+secure the Internet routing infrastructure. It associates BGP route
+announcements with the correct originating {abbr}`ASN (Autonomus System
+Number)` which BGP routers can then use to check each route against the
+corresponding {abbr}`ROA (Route Origin Authorisation)` for validity. RPKI is
+described in {rfc}`6480`.
+
+A BGP-speaking router like VyOS can retrieve ROA information from RPKI
+"Relying Party software" (often just called an "RPKI server" or "RPKI
+validator") by using {abbr}`RTR (RPKI to Router)` protocol. There are several
+open source implementations to choose from, such as NLNetLabs' [Routinator]
+(written in Rust), OpenBSD's [rpki-client] (written in C), and [StayRTR] (written
+in Go). The RTR protocol is described in {rfc}`8210`.
+
+:::{tip}
+If you are new to these routing security technologies then there is an
+[excellent guide to RPKI] by NLnet Labs which will get you up to speed
+very quickly. Their documentation explains everything from what RPKI is to
+deploying it in production. It also has some
+[help and operational guidance] including "What can I do about my route
+having an Invalid state?"
+:::
+
+## Getting started
+
+First you will need to deploy an RPKI validator for your routers to use. NLnet
+Labs provides a collection of [software] you can compare and settle on one.
+Once your server is running you can start validating announcements.
+
+Imported prefixes during the validation may have values:
+
+> valid
+>
+> : The prefix and ASN that originated it match a signed ROA. These are
+>   probably trustworthy route announcements.
+>
+> invalid
+>
+> : The prefix or prefix length and ASN that originated it doesn't
+>   match any existing ROA. This could be the result of a prefix hijack, or
+>   merely a misconfiguration, but should probably be treated as
+>   untrustworthy route announcements.
+>
+> notfound
+>
+> : No ROA exists which covers that prefix. Unfortunately this is the case for
+>   about 40%-50% of the prefixes which were announced to the {abbr}`DFZ
+>   (default-free zone)` at the start of 2024.
+
+:::{note}
+If you are responsible for the global addresses assigned to your
+network, please make sure that your prefixes have ROAs associated with them
+to avoid being `notfound` by RPKI. For most ASNs this will involve
+publishing ROAs via your {abbr}`RIR (Regional Internet Registry)` (RIPE
+NCC, APNIC, ARIN, LACNIC, or AFRINIC), and is something you are encouraged
+to do whenever you plan to announce addresses into the DFZ.
+
+Particularly large networks may wish to run their own RPKI certificate
+authority and publication server instead of publishing ROAs via their RIR.
+This is a subject far beyond the scope of VyOS' documentation. Consider
+reading about [Krill] if this is a rabbit hole you need or especially want
+to dive down.
+:::
+
+### Features of the Current Implementation
+
+In a nutshell, the current implementation provides the following features:
+
+- The BGP router can connect to one or more RPKI cache servers to receive
+  validated prefix to origin AS mappings. Advanced failover can be implemented
+  by server sockets with different preference values.
+- If no connection to an RPKI cache server can be established after a
+  pre-defined timeout, the router will process routes without prefix origin
+  validation. It still will try to establish a connection to an RPKI cache
+  server in the background.
+- By default, enabling RPKI does not change best path selection. In particular,
+  invalid prefixes will still be considered during best path selection. However,
+  the router can be configured to ignore all invalid prefixes.
+- Route maps can be configured to match a specific RPKI validation state. This
+  allows the creation of local policies, which handle BGP routes based on the
+  outcome of the Prefix Origin Validation.
+- Updates from the RPKI cache servers are directly applied and path selection is
+  updated accordingly. (Soft reconfiguration must be enabled for this to work).
+
+## Configuration
+
+```{cfgcmd} set protocols rpki polling-period \<1-86400\>
+
+Define the time interval to update the local cache
+
+The default value is 300 seconds.
+```
+
+```{cfgcmd} set protocols rpki expire-interval \<600-172800\>
+
+Set the number of seconds the router waits until the router
+expires the cache.
+
+The default value is 7200 seconds.
+```
+
+```{cfgcmd} set protocols rpki retry-interval \<1-7200\>
+
+Set the number of seconds the router waits until retrying to connect
+to the cache server.
+
+The default value is 600 seconds.
+```
+
+```{cfgcmd} set protocols rpki cache \<address\> port \<port\>
+
+Defined the IPv4, IPv6 or FQDN and port number of the caching RPKI caching
+instance which is used.
+
+This is a mandatory setting.
+```
+
+```{cfgcmd} set protocols rpki cache \<address\> preference \<preference\>
+
+Multiple RPKI caching instances can be supplied and they need a preference in
+which their result sets are used.
+
+This is a mandatory setting.
+```
+
+
+### SSH
+
+Connections to the RPKI caching server can not only be established by TCP using
+the RTR protocol but you can also rely on a secure SSH session to the server.
+This provides transport integrity and confidentiality and it is a good idea if
+your validation software supports it. To enable SSH, first you need to create
+an SSH client keypair using `generate ssh client-key
+/config/auth/id_rsa_rpki`. Once your key is created you can setup the
+connection.
+
+```{cfgcmd} set protocols rpki cache \<address\> ssh username \<user\>
+
+SSH username to establish an SSH connection to the cache server.
+```
+
+```{cfgcmd} set protocols rpki cache \<address\> ssh private-key-file \<filepath\>
+
+Local path that includes the private key file of the router.
+```
+
+```{cfgcmd} set protocols rpki cache \<address\> ssh public-key-file \<filepath\>
+
+Local path that includes the public key file of the router.
+```
+
+:::{note}
+When using SSH, private-key-file and public-key-file
+are mandatory options.
+:::
+
+## Example
+
+We can build route-maps for import based on these states. Here is a simple
+RPKI configuration, where `routinator` is the RPKI-validating "cache"
+server with ip `192.0.2.1`:
+
+```none
+set protocols rpki cache 192.0.2.1 port '3323'
+set protocols rpki cache 192.0.2.1 preference '1'
+```
+
+Here is an example route-map to apply to routes learned at import. In this
+filter we reject prefixes with the state `invalid`, and set a higher
+`local-preference` if the prefix is RPKI `valid` rather than merely
+`notfound`.
+
+```none
+set policy route-map ROUTES-IN rule 10 action 'permit'
+set policy route-map ROUTES-IN rule 10 match rpki 'valid'
+set policy route-map ROUTES-IN rule 10 set local-preference '300'
+set policy route-map ROUTES-IN rule 20 action 'permit'
+set policy route-map ROUTES-IN rule 20 match rpki 'notfound'
+set policy route-map ROUTES-IN rule 20 set local-preference '125'
+set policy route-map ROUTES-IN rule 30 action 'deny'
+set policy route-map ROUTES-IN rule 30 match rpki 'invalid'
+```
+
+Once your routers are configured to reject RPKI-invalid prefixes, you can
+test whether the configuration is working correctly using Cloudflare's [test]
+website. Keep in mind that in order for this to work, you need to have no
+default routes or anything else that would still send traffic to RPKI-invalid
+destinations.
+
+[excellent guide to rpki]: https://rpki.readthedocs.io/
+[help and operational guidance]: https://rpki.readthedocs.io/en/latest/about/help.html
+[krill]: https://www.nlnetlabs.nl/projects/rpki/krill/
+[routinator]: https://www.nlnetlabs.nl/projects/rpki/routinator/
+[rpki-client]: https://www.rpki-client.org/
+[software]: https://rpki.readthedocs.io/en/latest/ops/tools.html#relying-party-software
+[stayrtr]: https://github.com/bgp/stayrtr/
+[test]: https://isbgpsafeyet.com/
+[tweet by evilmog]: <https://twitter.com/Evil_Mog/status/1230924170508169216>
diff --git a/docs/configuration/protocols/segment-routing.md b/docs/configuration/protocols/segment-routing.md
new file mode 100644
index 00000000..45c89a41
--- /dev/null
+++ b/docs/configuration/protocols/segment-routing.md
@@ -0,0 +1,359 @@
+(segment-routing)=
+
+# Segment Routing
+
+Segment Routing (SR) is a network architecture that is similar to source-routing
+. In this architecture, the ingress router adds a list of segments, known as
+SIDs, to the packet as it enters the network. These segments represent different
+portions of the network path that the packet will take.
+
+The SR segments are portions of the network path taken by the packet, and are
+called SIDs. At each node, the first SID of the list is read, executed as a
+forwarding function, and may be popped to let the next node read the next SID of
+the list. The SID list completely determines the path where the packet is
+forwarded.
+
+Segment Routing can be applied to an existing MPLS-based data plane and defines
+a control plane network architecture. In MPLS networks, segments are encoded as
+MPLS labels and are added at the ingress router. These MPLS labels are then
+exchanged and populated by Interior Gateway Protocols (IGPs) like IS-IS or OSPF
+which are running on most ISPs.
+
+:::{note}
+Segment routing defines a control plane network architecture and
+can be applied to an existing MPLS based dataplane. In the MPLS networks,
+segments are encoded as MPLS labels and are imposed at the ingress router.
+MPLS labels are exchanged and populated by IGPs like IS-IS.Segment Routing
+as per RFC8667 for MPLS dataplane. It supports IPv4, IPv6 and ECMP and has
+been tested against Cisco & Juniper routers.however,this deployment is still
+EXPERIMENTAL for FRR.
+:::
+
+## IS-IS SR Configuration
+
+Segment routing (SR) is used by the IGP protocols to interconnect network
+devices, below configuration shows how to enable SR on IS-IS:
+
+:::{note}
+``Known limitations:``
+
+No support for level redistribution (L1 to L2 or L2 to L1)
+
+No support for binding SID
+
+No support for SRLB
+
+Only one SRGB and default SPF Algorithm is supported
+:::
+
+```{cfgcmd} set protocols isis segment-routing global-block high-label-value \<label-value\>
+
+Set the Segment Routing Global Block i.e. the label range used by MPLS to
+store label in the MPLS FIB for Prefix SID. Note that the block size may
+not exceed 65535.
+```
+
+
+```{cfgcmd} set protocols isis segment-routing global-block low-label-value \<label-value\>
+
+Set the Segment Routing Global Block i.e. the low label range used by MPLS to
+store label in the MPLS FIB for Prefix SID. Note that the block size may
+not exceed 65535.
+```
+
+
+```{cfgcmd} set protocols isis segment-routing local-block high-label-value \<label-value\>
+
+Set the Segment Routing Local Block i.e. the label range used by MPLS to
+store label in the MPLS FIB for Prefix SID. Note that the block size may
+not exceed 65535.Segment Routing Local Block, The negative command always
+unsets both.
+```
+
+
+```{cfgcmd} set protocols isis segment-routing local-block \<low-label-value \<label-value\>
+
+Set the Segment Routing Local Block i.e. the low label range used by MPLS to
+store label in the MPLS FIB for Prefix SID. Note that the block size may
+not exceed 65535.Segment Routing Local Block, The negative command always
+unsets both.
+```
+
+
+```{cfgcmd} set protocols isis segment-routing maximum-label-depth \<1-16\>
+
+Set the Maximum Stack Depth supported by the router. The value depend of
+the MPLS dataplane.
+```
+
+
+```{cfgcmd} set protocols isis segment-routing prefix \<address\> index value \<0-65535\>
+
+A segment ID that contains an IP address prefix calculated by an IGP in the
+service provider core network. Prefix SIDs are globally unique, this value
+indentify it
+```
+
+
+```{cfgcmd} set protocols isis segment-routing prefix \<address\> index \<no-php-flag | explicit-null| n-flag-clear\>
+
+this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO
+Penultimate Hop Popping that allows SR node to request to its neighbor to
+not pop the label. The ‘explicit-null’ flag allows SR node to request to its
+neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’
+option can be used to explicitly clear the Node flag that is set by default
+for Prefix-SIDs associated to loopback addresses. This option is necessary
+to configure Anycast-SIDs.
+```
+
+```{opcmd} show isis segment-routing node
+
+   Show detailed information about all learned Segment Routing Nodes
+```
+
+
+```{opcmd} show isis route prefix-sid
+
+Show detailed information about prefix-sid and label learned
+```
+
+:::{note}
+more information related IGP - {ref}`routing-isis`
+:::
+
+
+## OSPF SR Configuration
+
+
+Segment routing (SR) is used by the IGP protocols to interconnect network
+devices, below configuration shows how to enable SR on OSPF:
+
+```{cfgcmd} set protocols ospf parameters opaque-lsa
+
+Enable the Opaque-LSA capability (rfc2370), necessary to transport label
+on IGP
+```
+
+```{cfgcmd} set protocols ospf segment-routing global-block high-label-value \<label-value\>
+
+Set the Segment Routing Global Block i.e. the label range used by MPLS to
+store label in the MPLS FIB for Prefix SID. Note that the block size may
+not exceed 65535.
+```
+
+```{cfgcmd} set protocols ospf segment-routing global-block low-label-value \<label-value\>
+
+Set the Segment Routing Global Block i.e. the low label range used by MPLS to
+store label in the MPLS FIB for Prefix SID. Note that the block size may
+not exceed 65535.
+```
+
+```{cfgcmd} set protocols ospf segment-routing local-block high-label-value \<label-value\>
+
+Set the Segment Routing Local Block i.e. the label range used by MPLS to
+store label in the MPLS FIB for Prefix SID. Note that the block size may
+not exceed 65535.Segment Routing Local Block, The negative command always
+unsets both.
+```
+
+```{cfgcmd} set protocols ospf segment-routing local-block \<low-label-value \<label-value\>
+
+Set the Segment Routing Local Block i.e. the low label range used by MPLS to
+store label in the MPLS FIB for Prefix SID. Note that the block size may
+not exceed 65535.Segment Routing Local Block, The negative command always
+unsets both.
+```
+
+```{cfgcmd} set protocols ospf segment-routing maximum-label-depth \<1-16\>
+
+Set the Maximum Stack Depth supported by the router. The value depend of
+the MPLS dataplane.
+```
+
+```{cfgcmd} set protocols ospf segment-routing prefix \<address\> index value \<0-65535\>
+
+A segment ID that contains an IP address prefix calculated by an IGP in the
+service provider core network. Prefix SIDs are globally unique, this value
+indentify it
+```
+
+```{cfgcmd} set protocols ospf segment-routing prefix \<address\> index \<no-php-flag | explicit-null| n-flag-clear\>
+
+this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO
+Penultimate Hop Popping that allows SR node to request to its neighbor to
+not pop the label. The ‘explicit-null’ flag allows SR node to request to its
+neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’
+option can be used to explicitly clear the Node flag that is set by default
+for Prefix-SIDs associated to loopback addresses. This option is necessary
+to configure Anycast-SIDs.
+```
+
+:::{note}
+more information related IGP - {ref}`routing-ospf`
+:::
+
+## Configuration Example
+
+we described the configuration SR ISIS / SR OSPF using 2 connected with them to
+share label information.
+
+### Enable IS-IS with Segment Routing (Experimental)
+
+**Node 1:**
+
+```none
+set interfaces loopback lo address '192.168.255.255/32'
+set interfaces ethernet eth1 address '192.0.2.1/24'
+
+set protocols isis interface eth1
+set protocols isis interface lo
+set protocols isis net '49.0001.1921.6825.5255.00'
+set protocols isis segment-routing global-block high-label-value '599'
+set protocols isis segment-routing global-block low-label-value '550'
+set protocols isis segment-routing prefix 192.168.255.255/32 index value '1'
+set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null
+set protocols mpls interface 'eth1'
+```
+
+**Node 2:**
+
+```none
+set interfaces loopback lo address '192.168.255.254/32'
+set interfaces ethernet eth1 address '192.0.2.2/24'
+
+set protocols isis interface eth1
+set protocols isis interface lo
+set protocols isis net '49.0001.1921.6825.5254.00'
+set protocols isis segment-routing global-block high-label-value '599'
+set protocols isis segment-routing global-block low-label-value '550'
+set protocols isis segment-routing prefix 192.168.255.254/32 index value '2'
+set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null
+set protocols mpls interface 'eth1'
+```
+
+This gives us MPLS segment routing enabled and labels for far end loopbacks:
+
+```none
+Node-1@vyos:~$ show mpls table
+ Inbound Label  Type        Nexthop                Outbound Label
+ ----------------------------------------------------------------------
+ 552            SR (IS-IS)  192.0.2.2              IPv4 Explicit Null <-- Node-2 loopback learned on Node-1
+ 15000          SR (IS-IS)  192.0.2.2              implicit-null
+ 15001          SR (IS-IS)  fe80::e87:6cff:fe09:1  implicit-null
+ 15002          SR (IS-IS)  192.0.2.2              implicit-null
+ 15003          SR (IS-IS)  fe80::e87:6cff:fe09:1  implicit-null
+
+Node-2@vyos:~$ show mpls table
+ Inbound Label  Type        Nexthop               Outbound Label
+ ---------------------------------------------------------------------
+ 551            SR (IS-IS)  192.0.2.1             IPv4 Explicit Null <-- Node-1 loopback learned on Node-2
+ 15000          SR (IS-IS)  192.0.2.1             implicit-null
+ 15001          SR (IS-IS)  fe80::e33:2ff:fe80:1  implicit-null
+ 15002          SR (IS-IS)  192.0.2.1             implicit-null
+ 15003          SR (IS-IS)  fe80::e33:2ff:fe80:1  implicit-null
+```
+
+Here is the routing tables showing the MPLS segment routing label operations:
+
+```none
+Node-1@vyos:~$ show ip route isis
+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
+
+I   192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48
+I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39
+
+Node-2@vyos:~$ show ip route isis
+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
+
+I   192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46
+I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43
+```
+
+
+### Enable OSPF with Segment Routing (Experimental):
+
+**Node 1**
+
+```none
+set interfaces loopback lo address 10.1.1.1/32
+set interfaces ethernet eth0 address 192.168.0.1/24
+set protocols ospf area 0 network '192.168.0.0/24'
+set protocols ospf area 0 network '10.1.1.1/32'
+set protocols ospf parameters opaque-lsa
+set protocols ospf parameters router-id '10.1.1.1'
+set protocols ospf segment-routing global-block high-label-value '1100'
+set protocols ospf segment-routing global-block low-label-value '1000'
+set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null
+set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1'
+```
+
+**Node 2**
+
+```none
+set interfaces loopback lo address 10.1.1.2/32
+set interfaces ethernet eth0 address 192.168.0.2/24
+set protocols ospf area 0 network '192.168.0.0/24'
+set protocols ospf area 0 network '10.1.1.2/32'
+set protocols ospf parameters opaque-lsa
+set protocols ospf parameters router-id '10.1.1.2'
+set protocols ospf segment-routing global-block high-label-value '1100'
+set protocols ospf segment-routing global-block low-label-value '1000'
+set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null
+set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2'
+```
+
+This gives us MPLS segment routing enabled and labels for far end loopbacks:
+
+```none
+Node-1@vyos:~$ show mpls table
+ Inbound Label  Type       Nexthop      Outbound Label
+ -----------------------------------------------------------
+ 1002           SR (OSPF)  192.168.0.2  IPv4 Explicit Null  <-- Node-2 loopback learned on Node-1
+ 15000          SR (OSPF)  192.168.0.2  implicit-null
+ 15001          SR (OSPF)  192.168.0.2  implicit-null
+
+Node-2@vyos:~$ show mpls table
+ Inbound Label  Type       Nexthop      Outbound Label
+ -----------------------------------------------------------
+ 1001           SR (OSPF)  192.168.0.1  IPv4 Explicit Null  <-- Node-1 loopback learned on Node-2
+ 15000          SR (OSPF)  192.168.0.1  implicit-null
+ 15001          SR (OSPF)  192.168.0.1  implicit-null
+```
+
+Here is the routing tables showing the MPLS segment routing label operations:
+
+```none
+Node-1@vyos:~$ show ip route ospf
+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
+
+O   10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43
+O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32
+O   192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43
+
+Node-2@vyos:~$ show ip route ospf
+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
+
+O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36
+O   10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51
+O   192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51
+```
diff --git a/docs/configuration/protocols/static.md b/docs/configuration/protocols/static.md
new file mode 100644
index 00000000..357f7076
--- /dev/null
+++ b/docs/configuration/protocols/static.md
@@ -0,0 +1,298 @@
+(routing-static)=
+
+# Static
+
+Static routes are manually configured routes, which, in general, cannot be
+updated dynamically from information VyOS learns about the network topology from
+other routing protocols. However, if a link fails, the router will remove
+routes, including static routes, from the {abbr}`RIPB (Routing Information
+Base)` that used this interface to reach the next hop. In general, static
+routes should only be used for very simple network topologies, or to override
+the behavior of a dynamic routing protocol for a small number of routes. The
+collection of all routes the router has learned from its configuration or from
+its dynamic routing protocols is stored in the RIB. Unicast routes are directly
+used to determine the forwarding table used for unicast packet forwarding.
+
+## IPv4 Unicast Routes
+
+```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\>
+
+Configure next-hop *\<address\>* for an IPv4 static route. Multiple static
+routes can be created.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> disable
+
+Disable this IPv4 static route entry.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> distance \<distance\>
+
+Defines next-hop distance for this route, routes with smaller administrative
+distance are elected prior to those with a higher distance.
+
+Range is 1 to 255, default is 1.
+
+:::{note}
+Routes with a distance of 255 are effectively disabled and not
+installed into the kernel.
+:::
+```
+
+
+### IPv4 Interface Routes
+
+```{cfgcmd} set protocols static route \<subnet\> interface \<interface\>
+
+Allows you to configure the next-hop interface for an interface-based IPv4
+static route. *\<interface\>* will be the next-hop interface where traffic is
+routed for the given *\<subnet\>*.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> interface \<interface\> disable
+
+Disables interface-based IPv4 static route.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> interface \<interface\> distance \<distance\>
+
+Defines next-hop distance for this route, routes with smaller administrative
+distance are elected prior to those with a higher distance.
+
+Range is 1 to 255, default is 1.
+```
+
+
+### IPv4 BFD
+
+```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd
+
+Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the
+gateway address as BFD peer destination address.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd profile \<profile\>
+
+Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the
+gateway address as BFD peer destination address with BFD profile *\<profile\>*.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd multi-hop source-address \<source-address\>
+
+Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the
+gateway address as BFD peer destination address with source address
+*\<source\>* but initiate a multi-hop session.
+```
+
+
+### DHCP Interface Routes
+
+```{cfgcmd} set protocols static route \<subnet\> dhcp-interface \<interface\>
+
+Defines route with DHCP interface supplying next-hop IP address.
+```
+
+
+### IPv4 Reject Routes
+
+```{cfgcmd} set protocol static route \<subnet\> reject
+
+Defines route which emits an ICMP unreachable when matched.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> reject distance \<distance\>
+
+Defines distance for this route, routes with smaller administrative
+distance are elected prior to those with a higher distance.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> reject tag \<tag\>
+
+Sets a tag for this route.
+```
+
+```{cfgcmd} set protocol static route6 \<subnet\> reject
+
+Defines route which emits an ICMP unreachable when matched.
+```
+
+
+### IPv4 Blackhole Routes
+
+```{cfgcmd} set protocols static route \<subnet\> blackhole
+
+Use this command to configure a "black-hole" route on the router. A
+black-hole route is a route for which the system silently discard packets
+that are matched. This prevents networks leaking out public interfaces, but
+it does not prevent them from being used as a more specific route inside your
+network.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> blackhole distance \<distance\>
+
+Defines blackhole distance for this route, routes with smaller administrative
+distance are elected prior to those with a higher distance.
+```
+
+```{cfgcmd} set protocols static route \<subnet\> blackhole tag \<tag\>
+
+Sets a tag for this route.
+```
+
+
+## IPv6 Unicast Routes
+
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\>
+
+Configure next-hop *\<address\>* for an IPv6 static route. Multiple static
+routes can be created.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> disable
+
+Disable this IPv6 static route entry.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> distance \<distance\>
+
+Defines next-hop distance for this route, routes with smaller administrative
+distance are elected prior to those with a higher distance.
+
+Range is 1 to 255, default is 1.
+
+:::{note}
+Routes with a distance of 255 are effectively disabled and not
+installed into the kernel.
+:::
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> segments \<segments\>
+
+It is possible to specify a static route for ipv6 prefixes using an
+SRv6 segments instruction. The ``/`` separator can be used to specify
+multiple segment instructions.
+
+Example:
+
+:::{code-block} none
+set protocols static route6 2001:db8:1000::/36 next-hop 2001:db8:201::ffff segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2'
+:::
+
+:::{code-block} none
+vyos@vyos:~$ show ipv6 route
+Codes: K - kernel route, C - connected, S - static, R - RIPng,
+      O - OSPFv3, I - IS-IS, B - BGP, 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
+C>* 2001:db8:201::/64 is directly connected, eth0.201, 00:00:46
+S>* 2001:db8:1000::/36 [1/0] via 2001:db8:201::ffff, eth0.201, seg6 2001:db8:aaaa::7,2002::4,2002::3,2002::2, weight 1, 00:00:08
+:::
+```
+
+
+### IPv6 Interface Routes
+
+```{cfgcmd} set protocols static route6 \<subnet\> interface \<interface\>
+
+Allows you to configure the next-hop interface for an interface-based IPv6
+static route. *\<interface\>* will be the next-hop interface where traffic is
+routed for the given *\<subnet\>*.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> interface \<interface\> disable
+
+Disables interface-based IPv6 static route.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> interface \<interface\> distance \<distance\>
+
+Defines next-hop distance for this route, routes with smaller administrative
+distance are elected prior to those with a higher distance.
+
+Range is 1 to 255, default is 1.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> interface \<interface\> segments \<segments\>
+
+It is possible to specify a static route for ipv6 prefixes using an
+SRv6 segments instruction. The ``/`` separator can be used to specify
+multiple segment instructions.
+
+Example:
+
+:::{code-block} none
+set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2'
+:::
+```
+
+
+### IPv6 BFD
+
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd
+
+Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the
+gateway address as BFD peer destination address.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd profile \<profile\>
+
+Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the
+gateway address as BFD peer destination address with BFD profile *\<profile\>*.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd multi-hop source-address \<source\>
+
+Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the
+gateway address as BFD peer destination address with source address
+*\<source\>* but initiate a multi-hop session.
+```
+
+
+### IPv6 Reject Routes
+
+```{cfgcmd} set protocol static route6 \<subnet\> reject
+
+Defines route which emits an ICMP unreachable when matched.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> reject distance \<distance\>
+
+Defines distance for this route, routes with smaller administrative
+distance are elected prior to those with a higher distance.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> reject tag \<tag\>
+
+Sets a tag for this route.
+```
+
+
+### IPv6 Blackhole Routes
+
+```{cfgcmd} set protocols static route6 \<subnet\> blackhole
+
+Use this command to configure a "black-hole" route on the router. A
+black-hole route is a route for which the system silently discard packets
+that are matched. This prevents networks leaking out public interfaces, but
+it does not prevent them from being used as a more specific route inside your
+network.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> blackhole distance \<distance\>
+
+Defines blackhole distance for this route, routes with smaller administrative
+distance are elected prior to those with a higher distance.
+```
+
+```{cfgcmd} set protocols static route6 \<subnet\> blackhole tag \<tag\>
+
+Sets a tag for this route.
+```
+
+
+## Alternate Routing Tables
+
+Alternate routing tables are used with policy based routing by utilizing
+{ref}`vrf`.
diff --git a/docs/configuration/protocols/traffic-engineering.md b/docs/configuration/protocols/traffic-engineering.md
new file mode 100644
index 00000000..832023a7
--- /dev/null
+++ b/docs/configuration/protocols/traffic-engineering.md
@@ -0,0 +1,54 @@
+(traffic-engineering)=
+
+# Traffic Engineering
+
+Traffic Engineering (TE) is possibility to send traffic from node to node using
+alternative path.
+
+## Common link parameters
+
+Traffic Engineering parameters are used for both IS-IS and OSPF (not supported yet).
+
+```{cfgcmd} set protocols traffic-engineering admin-group \<admin-group-name\> bit-position \<bit-position-value\>
+
+Create Administrative group and assosiate bit position with it. These groups can be
+used in the following commands.
+
+\<bit-position-value\> can have value 0-31. There cannot be two groups with same bit position.
+```
+
+
+```{cfgcmd} set protocols traffic-engineering interface \<ifname\> admin-group \<admin-group-name\>
+
+Set administrative group for interface \<ifname\>. Multiple values can be provided.
+```
+
+
+```{cfgcmd} set protocols traffic-engineering interface \<ifname\> max-bandwidth \<max-bandwidth-value-mbps\>
+
+Set maximum bandwidth for interface \<ifname\>. Value given in Mbits per second.
+```
+
+
+```{cfgcmd} set protocols traffic-engineering interface \<ifname\> max-reservable-bandwidth \<max-reservable-bandwidth-value-mbps\>
+
+Set maximum reservable bandwidth for interface \<ifname\>. Value given in Mbits per second.
+```
+
+## IS-IS TE Configuration
+
+Traffic Engineering (TE) can be enabled and exported for IS-IS
+using the following commands:
+
+```{cfgcmd} set protocols isis traffic-engineering enable
+
+Enable Traffic Engineering for IS-IS.
+```
+```{cfgcmd} set protocols isis traffic-engineering export
+
+Export Traffic Engineering data to neighbors.
+```
+```{cfgcmd} set protocols isis traffic-engineering address \<ipv4-address\>
+
+Configure IPv4 address for MPLS-TE.
+```
\ No newline at end of file
diff --git a/docs/configuration/service/broadcast-relay.md b/docs/configuration/service/broadcast-relay.md
new file mode 100644
index 00000000..4202ad6b
--- /dev/null
+++ b/docs/configuration/service/broadcast-relay.md
@@ -0,0 +1,70 @@
+(udp-broadcast-relay)=
+
+# UDP Broadcast Relay
+
+Certain vendors use broadcasts to identify their equipment within one ethernet
+segment. Unfortunately if you split your network with multiple VLANs you loose
+the ability of identifying your equipment.
+
+This is where "UDP broadcast relay" comes into play! It will forward received
+broadcasts to other configured networks.
+
+Every UDP port which will be forward requires one unique ID. Currently we
+support 99 IDs!
+
+## Configuration
+
+```{cfgcmd} set service broadcast-relay id \<n\> description \<description\>
+
+A description can be added for each and every unique relay ID. This is
+useful to distinguish between multiple different ports/applications.
+```
+
+```{cfgcmd} set service broadcast-relay id \<n\> interface \<interface\>
+
+The interface used to receive and relay individual broadcast packets. If you
+want to receive/relay packets on both `eth1` and `eth2` both interfaces need
+to be added.
+```
+
+```{cfgcmd} set service broadcast-relay id \<n\> address \<ipv4-address\>
+
+Set the source IP of forwarded packets, otherwise original senders address
+is used.
+```
+
+```{cfgcmd} set service broadcast-relay id \<n\> port \<port\>
+
+The UDP port number used by your application. It is mandatory for this kind
+of operation.
+```
+
+```{cfgcmd} set service broadcast-relay id \<n\> disable
+
+Each broadcast relay instance can be individually disabled without deleting
+the configured node by using the following command:
+```
+
+```{cfgcmd} set service broadcast-relay disable
+
+In addition you can also disable the whole service without the need to remove
+it from the current configuration.
+```
+
+:::{note}
+You can run the UDP broadcast relay service on multiple routers
+connected to a subnet. There is **NO** UDP broadcast relay packet storm!
+:::
+
+## Example
+
+To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4`
+or `eth5` to all other interfaces in this configuration.
+
+```none
+set service broadcast-relay id 1 description 'SONOS'
+set service broadcast-relay id 1 interface 'eth3'
+set service broadcast-relay id 1 interface 'eth4'
+set service broadcast-relay id 1 interface 'eth5'
+set service broadcast-relay id 1 port '1900'
+```
diff --git a/docs/configuration/service/config-sync.md b/docs/configuration/service/config-sync.md
new file mode 100644
index 00000000..a575f947
--- /dev/null
+++ b/docs/configuration/service/config-sync.md
@@ -0,0 +1,164 @@
+(config-sync)=
+
+# Config Sync
+
+Configuration synchronization (config sync) is a feature of VyOS that
+permits synchronization of the configuration of one VyOS router to
+another in a network.
+
+The main benefit to configuration synchronization is that it eliminates having
+to manually replicate configuration changes made on the primary router to the
+secondary (replica) router.
+
+The writing of the configuration to the secondary router is performed through
+the VyOS HTTP API. The user can specify which portion(s) of the configuration will
+be synchronized and the mode to use - whether to replace or add.
+
+To prevent issues with divergent configurations between the pair of routers,
+synchronization is strictly unidirectional from primary to replica. Both
+routers should be online and run the same version of VyOS.
+
+## Configuration
+
+```{cfgcmd} set service config-sync secondary \<address|key|timeout|port\>
+
+Specify the address, API key, timeout and port of the secondary router.
+You need to enable and configure the HTTP API service on the secondary
+router for config sync to operate.
+```
+
+```{cfgcmd} set service config-sync section \<section\>
+
+Specify the section of the configuration to synchronize. If more than one
+section is to be synchronized, repeat the command to add additional
+sections as required.
+```
+
+```{cfgcmd} set service config-sync mode \<load|set\>
+
+Two options are available for *mode*: either *load* and replace or *set*
+the configuration section.
+```
+
+```none
+Supported options for <section> include:
+    firewall
+    interfaces <interface>
+    nat
+    nat66
+    pki
+    policy
+    protocols <protocol>
+    qos <interface|policy>
+    service <service>
+    system <conntrack| 
+    flow-accounting|option|sflow|static-host-mapping|sysctl|time-zone>
+    vpn
+    vrf
+```
+
+
+## Operational Commands
+
+````{opcmd} show configuration secondary sync [commands] [running | candidate | saved] [\<config-node-path\>]
+
+Display configuration differences between the local node and
+a config-sync secondary node.
+
+This command allows operators to compare configurations across nodes
+participating in configuration synchronization (e.g., primary and
+secondary routers). It helps detect configuration drift and validate
+intended changes before synchronization.
+
+**Parameters:**
+
+```{eval-rst}
+.. list-table::
+   :widths: 30 70
+   :header-rows: 0
+
+   * - ``commands`` (optional)
+     - Show output as a list of configuration commands instead of raw diff.
+   * - ``running|candidate|saved`` (optional, mutually exclusive)
+     - Select which configuration to compare:
+       ``running`` (current active configuration, default),
+       ``candidate`` (uncommitted changes), or
+       ``saved`` (last saved configuration). Only one of these may be
+       specified at a time; if omitted, ``running`` is used.
+```
+
+**Examples:**
+
+:::{code-block} none
+# compare full running configuration with a secondary node
+show configuration secondary sync
+
+# compare only interface configuration
+show configuration secondary sync running interfaces dummy
+
+# compare candidate configuration and display as a list of commands
+show configuration secondary sync commands candidate
+:::
+````
+
+Without a built-in cross-node diff, operators may unintentionally push
+changes that conflict with the remote configuration (e.g., mismatched
+interfaces, firewall policies, or protocol settings).
+
+
+## Example
+
+- Synchronize the time-zone and OSPF configuration from Router A to Router B
+- The address of Router B is 10.0.20.112 and the port used is 8443
+
+Configure the HTTP API service on Router B
+
+```none
+set service https listen-address '10.0.20.112'
+set service https port '8443'
+set service https api keys id KID key 'foo'
+set service https api rest
+```
+
+Configure the config-sync service on Router A
+
+```none
+set service config-sync mode 'load'
+set service config-sync secondary address '10.0.20.112'
+set service config-sync secondary port '8443'
+set service config-sync secondary key 'foo'
+set service config-sync section protocols 'ospf'
+set service config-sync section system 'time-zone'
+```
+
+Make config-sync relevant changes to Router A's configuration
+
+```none
+vyos@vyos-A# set system time-zone 'America/Los_Angeles'
+vyos@vyos-A# commit
+INFO:vyos_config_sync:Config synchronization: Mode=load, 
+Secondary=10.0.20.112
+vyos@vyos-A# save
+
+vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30'
+vyos@vyos-A# commit
+INFO:vyos_config_sync:Config synchronization: Mode=load, 
+Secondary=10.0.20.112
+yos@vyos-A# save
+```
+
+Verify configuration changes have been replicated to Router B
+
+```none
+vyos@vyos-B:~$ show configuration commands | match time-zone
+set system time-zone 'America/Los_Angeles'
+
+vyos@vyos-B:~$ show configuration commands | match ospf
+set protocols ospf area 0 network '10.0.48.0/30'
+```
+
+
+## Known issues
+
+Configuration resynchronization. With the current implementation of *service
+config-sync*, the secondary node must be online.
diff --git a/docs/configuration/service/conntrack-sync.md b/docs/configuration/service/conntrack-sync.md
new file mode 100644
index 00000000..47a0ae2f
--- /dev/null
+++ b/docs/configuration/service/conntrack-sync.md
@@ -0,0 +1,321 @@
+(conntrack-sync)=
+
+# Conntrack Sync
+
+One of the important features built on top of the Netfilter framework is
+connection tracking. Connection tracking allows the kernel to keep track of all
+logical network connections or sessions, and thereby relate all of the packets
+which may make up that connection. NAT relies on this information to translate
+all related packets in the same way, and iptables can use this information to
+act as a stateful firewall.
+
+The connection state however is completely independent of any upper-level
+state, such as TCP's or SCTP's state. Part of the reason for this is that when
+merely forwarding packets, i.e. no local delivery, the TCP engine may not
+necessarily be invoked at all. Even connectionless-mode transmissions such as
+UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo
+connection state. The heuristic for such protocols is often based upon a preset
+timeout value for inactivity, after whose expiration a Netfilter connection is
+dropped.
+
+Each Netfilter connection is uniquely identified by a (layer-3 protocol, source
+address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4
+key depends on the transport protocol; for TCP/UDP it is the port numbers, for
+tunnels it can be their tunnel ID, but otherwise is just zero, as if it were
+not part of the tuple. To be able to inspect the TCP port in all cases, packets
+will be mandatorily defragmented.
+
+It is possible to use either Multicast or Unicast to sync conntrack traffic.
+Most examples below show Multicast, but unicast can be specified by using the
+"peer" keywork after the specified interface, as in the following example:
+
+{cfgcmd}`set service conntrack-sync interface eth0 peer 192.168.0.250`
+
+## Configuration
+
+```{cfgcmd} set service conntrack-sync accept-protocol
+
+Accept only certain protocols: You may want to replicate the state of flows
+depending on their layer 4 protocol.
+
+Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp.
+```
+
+
+```{cfgcmd} set service conntrack-sync event-listen-queue-size \<size\>
+
+The daemon doubles the size of the netlink event socket buffer size if it
+detects netlink event message dropping. This clause sets the maximum buffer
+size growth that can be reached.
+
+Queue size for listening to local conntrack events in MB.
+```
+
+
+```{cfgcmd} set service conntrack-sync expect-sync \<all|ftp|h323|nfs|sip|sqlnet\>
+
+Protocol for which expect entries need to be synchronized.
+```
+
+
+```{cfgcmd} set service conntrack-sync failover-mechanism vrrp sync-group \<group\>
+
+Failover mechanism to use for conntrack-sync.
+
+Only VRRP is supported. Required option.
+```
+
+
+```{cfgcmd} set service conntrack-sync ignore-address \<x.x.x.x\>
+
+IP addresses or networks for which local conntrack entries will not be synced
+```
+
+
+```{cfgcmd} set service conntrack-sync interface \<name\>
+
+Interface to use for syncing conntrack entries.
+```
+
+
+```{cfgcmd} set service conntrack-sync interface \<name\> port \<port\>
+
+Port number used by connection.
+```
+
+
+```{cfgcmd} set service conntrack-sync listen-address \<ipv4address\>
+
+Local IPv4 addresses for service to listen on.
+```
+
+
+```{cfgcmd} set service conntrack-sync mcast-group \<x.x.x.x\>
+
+Multicast group to use for syncing conntrack entries.
+
+Defaults to 225.0.0.50.
+```
+
+
+```{cfgcmd} set service conntrack-sync interface \<name\> peer \<address\>
+
+Peer to send unicast UDP conntrack sync entires to, if not using Multicast
+configuration from above above.
+```
+
+
+```{cfgcmd} set service conntrack-sync sync-queue-size \<size\>
+
+Queue size for syncing conntrack entries in MB.
+```
+
+
+```{cfgcmd} set service conntrack-sync disable-external-cache
+
+This diable the external cache and directly injects the flow-states into the
+in-kernel Connection Tracking System of the backup firewall.
+```
+
+
+```{cfgcmd} set service conntrack-sync purge-timeout \<timeout\>
+
+Timeout (in seconds) for purging synchronized entries on handover events.
+
+On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table
+flush after ``<timeout>`` seconds to purge stale (“zombie”) entries and
+reduce clashes when multiple handovers occur in a short period.
+The default is 60 seconds.
+```
+
+:::{note}
+In VRRP stateful firewall deployments, align VRRP timing with this
+behavior: because synchronized conntrack state is purged after the purge
+timeout, set **VRRP preempt-delay** to ≥ **purge-timeout** so mastership
+can be restored before conntrack state is purged.
+:::
+
+```{cfgcmd} set service conntrack-sync disable-syslog
+
+Disable connection logging via Syslog.
+```
+
+
+```{cfgcmd} set service conntrack-sync startup-resync
+
+Order conntrackd to request a complete conntrack table resync against
+the other node at startup.
+```
+
+## Operation
+
+```{opcmd} show conntrack table ipv4
+
+Make sure conntrack is enabled by running and show connection tracking table.
+
+:::{code-block} none
+vyos@vyos:~$ show conntrack table ipv4
+TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED,
+FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK,
+TW - TIME WAIT, CL - CLOSE, LI - LISTEN
+
+CONN ID    Source                 Destination            Protocol         TIMEOUT
+1015736576 10.35.100.87:58172     172.31.20.12:22        tcp [6] ES       430279
+1006235648 10.35.101.221:57483    172.31.120.21:22       tcp [6] ES       413310
+1006237088 10.100.68.100          172.31.120.21          icmp [1]         29
+1015734848 10.35.100.87:56282     172.31.20.12:22        tcp [6] ES       300
+1015734272 172.31.20.12:60286     239.10.10.14:694       udp [17]         29
+1006239392 10.35.101.221          172.31.120.21          icmp [1]         29
+:::
+:::{note}
+If the table is empty and you have a warning message, it means
+conntrack is not enabled. To enable conntrack, just create a NAT or a firewall
+rule. {cfgcmd}`set firewall state-policy established action accept`
+:::
+```
+
+
+```{opcmd} show conntrack-sync cache external
+
+Show connection syncing external cache entries
+```
+
+
+```{opcmd} show conntrack-sync cache internal
+
+Show connection syncing internal cache entries
+```
+
+
+```{opcmd} show conntrack-sync statistics
+
+Retrieve current statistics of connection tracking subsystem.
+
+:::{code-block} none
+vyos@vyos:~$ show conntrack-sync statistics
+Main Table Statistics:
+
+cache internal:
+current active connections:            19606
+connections created:                 6298470    failed:            0
+connections updated:                 3786793    failed:            0
+connections destroyed:               6278864    failed:            0
+
+cache external:
+current active connections:            15771
+connections created:                 1660193    failed:            0
+connections updated:                   77204    failed:            0
+connections destroyed:               1644422    failed:            0
+
+traffic processed:
+0 Bytes                         0 Pckts
+
+multicast traffic (active device=eth0.5):
+976826240 Bytes sent            212898000 Bytes recv
+8302333 Pckts sent              2009929 Pckts recv
+0 Error send                    0 Error recv
+
+message tracking:
+0 Malformed msgs                  263 Lost msgs
+:::
+```
+```{opcmd} show conntrack-sync status
+
+Retrieve current status of connection tracking subsystem.
+
+:::{code-block} none
+vyos@vyos:~$ show conntrack-sync status
+sync-interface        : eth0.5
+failover-mechanism    : vrrp [sync-group GEFOEKOM]
+last state transition : no transition yet!
+ExpectationSync       : disabled
+:::
+```
+
+## Example
+
+The next example is a simple configuration of conntrack-sync.
+
+:::{figure} /_static/images/service_conntrack_sync-schema.webp
+:alt: Conntrack Sync Example
+:scale: 60 %
+:::
+
+Now configure conntrack-sync service on `router1` **and** `router2`
+
+```none
+set high-availability vrrp group internal virtual-address ... etc ...
+set high-availability vrrp sync-group syncgrp member 'internal'
+set service conntrack-sync accept-protocol 'tcp'
+set service conntrack-sync accept-protocol 'udp'
+set service conntrack-sync accept-protocol 'icmp'
+set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp'
+set service conntrack-sync interface 'eth0'
+set service conntrack-sync mcast-group '225.0.0.50'
+```
+
+On the active router, you should have information in the internal-cache of
+conntrack-sync. The same current active connections number should be shown in
+the external-cache of the standby router
+
+On active router run:
+
+```none
+$ show conntrack-sync statistics
+
+Main Table Statistics:
+
+cache internal:
+current active connections:               10
+connections created:                    8517    failed:            0
+connections updated:                     127    failed:            0
+connections destroyed:                  8507    failed:            0
+
+cache external:
+current active connections:                0
+connections created:                       0    failed:            0
+connections updated:                       0    failed:            0
+connections destroyed:                     0    failed:            0
+
+traffic processed:
+                   0 Bytes                         0 Pckts
+
+multicast traffic (active device=eth0):
+              868780 Bytes sent               224136 Bytes recv
+               20595 Pckts sent                14034 Pckts recv
+                   0 Error send                    0 Error recv
+
+message tracking:
+                   0 Malformed msgs                    0 Lost msgs
+```
+
+On standby router run:
+
+```none
+$ show conntrack-sync statistics
+
+Main Table Statistics:
+
+cache internal:
+current active connections:                0
+connections created:                       0    failed:            0
+connections updated:                       0    failed:            0
+connections destroyed:                     0    failed:            0
+
+cache external:
+current active connections:               10
+connections created:                     888    failed:            0
+connections updated:                     134    failed:            0
+connections destroyed:                   878    failed:            0
+
+traffic processed:
+                   0 Bytes                         0 Pckts
+
+multicast traffic (active device=eth0):
+              234184 Bytes sent               907504 Bytes recv
+               14663 Pckts sent                21495 Pckts recv
+                   0 Error send                    0 Error recv
+
+message tracking:
+                   0 Malformed msgs                    0 Lost msgs
+```
diff --git a/docs/configuration/service/console-server.md b/docs/configuration/service/console-server.md
new file mode 100644
index 00000000..9402e935
--- /dev/null
+++ b/docs/configuration/service/console-server.md
@@ -0,0 +1,139 @@
+(console-server)=
+
+# Console Server
+
+Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an
+Out-of-Band Management device which provides remote access by means of SSH to
+directly attached serial interfaces.
+
+Serial interfaces can be any interface which is directly connected to the CPU
+or chipset (mostly known as a ttyS interface in Linux) or any other USB to
+serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips).
+
+If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or
+NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement.
+
+For USB port information please refor to: {ref}`hardware_usb`.
+
+## Configuration
+
+Between computers, the most common configuration used was "8N1": eight bit
+characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud
+times are used to send a single character, and so dividing the signalling
+bit-rate by ten results in the overall transmission speed in characters per
+second. This is also the default setting if none of those options are defined.
+
+```{cfgcmd} set service console-server device \<device\> data-bits [7 | 8]
+
+Configure either seven or eight data bits. This defaults to eight data
+bits if left unconfigured.
+```
+
+
+```{cfgcmd} set service console-server device \<device\> description \<string\>
+
+A user friendly description identifying the connected peripheral.
+```
+
+
+```{cfgcmd} set service console-server device \<device\> alias \<string\>
+
+A user friendly alias for this connection. Can be used instead of the
+device name when connecting.
+```
+
+
+```{cfgcmd} set service console-server device \<device\> parity [even | odd | none]
+
+Set the parity option for the console. If unset this will default to none.
+```
+
+
+```{cfgcmd} set service console-server device \<device\> stop-bits [1 | 2]
+
+Configure either one or two stop bits. This defaults to one stop bits if
+left unconfigured.
+```
+
+
+```{cfgcmd} set service console-server device \<device\> speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ]
+
+:::{note}
+USB to serial converters will handle most of their work in software
+so you should be carefull with the selected baudrate as some times they
+can't cope with the expected speed.
+:::
+```
+
+### Remote Access
+
+
+Each individual configured console-server device can be directly exposed to
+the outside world. A user can directly connect via SSH to the configured
+port.
+
+```{cfgcmd} set service console-server device \<device\> ssh port \<port\>
+
+Accept SSH connections for the given `<device>` on TCP port `<port>`.
+After successfull authentication the user will be directly dropped to
+the connected serial device.
+
+:::{hint}
+Multiple users can connect to the same serial device but only
+one is allowed to write to the console port.
+:::
+```
+
+## Operation
+
+```{opcmd} show console-server ports
+
+Show configured serial ports and their respective interface configuration.
+
+:::{code-block} none
+vyos@vyos:~$ show console-server ports
+usb0b2.4p1.0             on /dev/serial/by-bus/usb0b2.4p1.0@ at   9600n
+:::
+```
+
+
+```{opcmd} show console-server user
+
+Show currently connected users.
+
+:::{code-block} none
+vyos@vyos:~$ show console-server user
+usb0b2.4p1.0               up   vyos@localhost
+:::
+```
+```{opcmd} connect console \<device\>
+
+Locally connect to serial port identified by `<device>`.
+
+:::{code-block} none
+vyos@vyos-r1:~$ connect console usb0b2.4p1.0
+[Enter `^Ec?' for help]
+[-- MOTD -- VyOS Console Server]
+
+vyos-r2 login:
+:::
+
+:::{hint}
+Multiple users can connect to the same serial device but only
+one is allowed to write to the console port.
+:::
+
+:::{hint}
+The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit
+the session use: ``Ctrl+E c .``
+:::
+
+:::{hint}
+If ``alias`` is set, it can be used instead of the device when
+connecting.
+:::
+```
+```{opcmd} show log console-server
+
+Show the console server log.
+```
\ No newline at end of file
diff --git a/docs/configuration/service/dhcp-relay.md b/docs/configuration/service/dhcp-relay.md
new file mode 100644
index 00000000..a4a10109
--- /dev/null
+++ b/docs/configuration/service/dhcp-relay.md
@@ -0,0 +1,205 @@
+(dhcp-relay)=
+
+# DHCP Relay
+
+If you want your router to forward DHCP requests to an external DHCP server
+you can configure the system to act as a DHCP relay agent. The DHCP relay
+agent works with IPv4 and IPv6 addresses.
+
+All interfaces used for the DHCP relay must be configured. This includes the
+uplink to the DHCP server.
+
+## IPv4 relay
+
+### Configuration
+
+```{cfgcmd} set service dhcp-relay interface \<interface\>
+
+Interfaces that participate in the DHCP relay process. If this command is
+used, at least two entries of it are required: one for the interface that
+captures the dhcp-requests, and one for the interface to forward such
+requests. A warning message will be shown if this command is used, since
+new implementations should use ``listen-interface`` and
+``upstream-interface``.
+```
+
+```{cfgcmd} set service dhcp-relay listen-interface \<interface\>
+
+Interface for DHCP Relay Agent to listen for requests.
+```
+
+```{cfgcmd} set service dhcp-relay upstream-interface \<interface\>
+
+Interface for DHCP Relay Agent to forward requests out.
+```
+
+```{cfgcmd} set service dhcp-relay server \<server\>
+
+Configure IP address of the DHCP `<server>` which will handle the relayed
+packets.
+```
+
+```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets discard
+
+The router should discard DHCP packages already containing relay agent
+information to ensure that only requests from DHCP clients are forwarded.
+```
+
+```{cfgcmd} set service dhcp-relay disable
+
+Disable dhcp-relay service.
+```
+
+
+#### Options
+
+```{cfgcmd} set service dhcp-relay relay-options hop-count \<count\>
+
+Set the maximum hop `<count>` before packets are discarded. Range 0...255,
+default 10.
+```
+
+```{cfgcmd} set service dhcp-relay relay-options max-size \<size\>
+
+Set maximum `<size>` of DHCP packets including relay agent information. If a
+DHCP packet size surpasses this value it will be forwarded without appending
+relay agent information. Range 64...1400, default 576.
+```
+
+```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets \<append | discard | forward | replace\>
+
+Four policies for reforwarding DHCP packets exist:
+* **append:** The relay agent is allowed to append its own relay information
+to a received DHCP packet, disregarding relay information already present
+in the packet.
+* **discard:** Received packets which already contain relay information will
+be discarded.
+* **forward:** All packets are forwarded, relay information already present
+will be ignored.
+* **replace:** Relay information already present in a packet is stripped and
+replaced with the router's own relay information set.
+```
+
+
+### Example
+
+- Listen for DHCP requests on interface `eth1`.
+- DHCP server is located at IPv4 address 10.0.1.4 on `eth2`.
+- Router receives DHCP client requests on `eth1` and relays them to the
+  server at 10.0.1.4 on `eth2`.
+
+:::{figure} /_static/images/service_dhcp-relay01.webp
+:alt: DHCP relay example
+:scale: 80 %
+DHCP relay example
+:::
+
+The generated configuration will look like:
+
+```none
+show service dhcp-relay
+    listen-interface eth1
+    upstream-interface eth2
+    server 10.0.1.4
+    relay-options {
+       relay-agents-packets discard
+    }
+```
+
+Also, for backwards compatibility this configuration, which uses generic
+interface definition, is still valid:
+
+```none
+show service dhcp-relay
+    interface eth1
+    interface eth2
+    server 10.0.1.4
+    relay-options {
+       relay-agents-packets discard
+    }
+```
+
+
+### Operation
+
+```{opcmd} restart dhcp relay-agent
+
+Restart DHCP relay service
+```
+
+
+## IPv6 relay
+
+(dhcp-relay-ipv6-configuration)=
+
+### Configuration
+
+```{cfgcmd} set service dhcpv6-relay listen-interface \<interface\>
+
+Set eth1 to be the listening interface for the DHCPv6 relay.
+
+Multiple interfaces may be specified.
+```
+
+```{cfgcmd} set service dhcpv6-relay upstream-interface \<interface\> address \<server\>
+
+Specifies an upstream network `<interface>` from which replies from
+`<server>` and other relay agents will be accepted.
+```
+
+(dhcp-relay-ipv6-options)=
+
+```{cfgcmd} set service dhcpv6-relay disable
+
+Disable dhcpv6-relay service.
+```
+
+(dhcp-relay-v6-options)=
+
+#### Options
+
+```{cfgcmd} set service dhcpv6-relay max-hop-count \<count\>
+
+Set maximum hop count before packets are discarded, default: 10
+```
+
+```{cfgcmd} set service dhcpv6-relay use-interface-id-option
+
+If this is set the relay agent will insert the interface ID. This option is
+set automatically if more than one listening interfaces are in use.
+```
+
+(dhcp-relay-ipv6-example)=
+
+### Example
+
+- DHCPv6 requests are received by the router on `listening interface` `eth1`
+- Requests are forwarded through `eth2` as the `upstream interface`
+- External DHCPv6 server is at 2001:db8::4
+
+:::{figure} /_static/images/service_dhcpv6-relay01.webp
+:alt: DHCPv6 relay example
+:scale: 80 %
+DHCPv6 relay example
+:::
+
+The generated configuration will look like:
+
+```none
+commit
+show service dhcpv6-relay
+    listen-interface eth1 {
+    }
+    upstream-interface eth2 {
+       address 2001:db8::4
+    }
+```
+
+(dhcp-relay-ipv6-op-cmd)=
+
+### Operation
+
+```{opcmd} restart dhcpv6 relay-agent
+
+Restart DHCPv6 relay agent immediately.
+```
\ No newline at end of file
diff --git a/docs/configuration/service/dhcp-server.md b/docs/configuration/service/dhcp-server.md
new file mode 100644
index 00000000..96c375da
--- /dev/null
+++ b/docs/configuration/service/dhcp-server.md
@@ -0,0 +1,1178 @@
+(dhcp-server)=
+
+# DHCP Server
+
+VyOS uses Kea DHCP server for both IPv4 and IPv6 address assignment.
+
+## IPv4 server
+
+The network topology is declared by shared-network-name and the subnet
+declarations. The DHCP service can serve multiple shared networks, with each
+shared network having 1 or more subnets. Each subnet must be present on an
+interface. A range can be declared inside a subnet to define a pool of dynamic
+addresses. Multiple ranges can be defined and can contain holes. Static
+mappings can be set to assign "static" addresses to clients based on their MAC
+address.
+
+### Configuration
+
+```{cfgcmd} set service dhcp-server hostfile-update
+
+   Create DNS record per client lease, by adding clients to /etc/hosts file.
+   Entry will have format: `<shared-network-name>_<hostname>.<domain-name>`
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> option domain-name \<domain-name\>
+
+The domain-name parameter should be the domain name that will be appended to
+the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP
+Option 015).
+
+This is the configuration parameter for the entire shared network definition.
+All subnets will inherit this configuration item if not specified locally.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> option domain-search \<domain-name\>
+
+The domain-name parameter should be the domain name used when completing DNS
+request where no full FQDN is passed. This option can be given multiple times
+if you need multiple search domains (DHCP Option 119).
+
+This is the configuration parameter for the entire shared network definition.
+All subnets will inherit this configuration item if not specified locally.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> option name-server \<address\>
+
+Inform client that the DNS server can be found at `<address>`.
+
+This is the configuration parameter for the entire shared network definition.
+All subnets will inherit this configuration item if not specified locally.
+Multiple DNS servers can be defined.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> option vendor-option \<option-name\>
+
+This configuration parameter lets you specify a vendor-option for the
+entire shared network definition. All subnets will inherit this
+configuration item if not specified locally. An example for Ubiquiti is
+shown below:
+```
+
+**Example:**
+
+
+Pass address of Unifi controller at `172.16.100.1` to all clients of `NET1`
+
+```none
+set service dhcp-server shared-network-name 'NET1' option vendor-option
+ubiquiti '172.16.100.1'
+```
+
+
+```{cfgcmd} set service dhcp-server listen-address \<address\>
+
+This configuration parameter lets the DHCP server to listen for DHCP
+requests sent to the specified address, it is only realistically useful for
+a server whose only clients are reached via unicasts, such as via DHCP relay
+agents.
+```
+
+#### Individual Client Subnet
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> authoritative
+
+This says that this device is the only DHCP server for this network. If other
+devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to
+any device trying to request an IP address that is not valid for this
+network.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> subnet-id \<id\>
+
+This configuration parameter is required and must be unique to each subnet.
+It is required to map subnets to lease file entries.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option default-router \<address\>
+
+This is a configuration parameter for the `<subnet>`, saying that as part of
+the response, tell the client that the default gateway can be reached at
+`<address>`.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option name-server \<address\>
+
+This is a configuration parameter for the subnet, saying that as part of the
+response, tell the client that the DNS server can be found at `<address>`.
+
+Multiple DNS servers can be defined.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> lease \<time\>
+
+Assign the IP address to this machine for `<time>` seconds.
+
+The default value is 86400 seconds which corresponds to one day.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> range \<n\> start \<address\>
+
+Create DHCP address range with a range id of `<n>`. DHCP leases are taken
+from this pool. The pool starts at address `<address>`.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> range \<n\> stop \<address\>
+
+Create DHCP address range with a range id of `<n>`. DHCP leases are taken
+from this pool. The pool stops with address `<address>`.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> exclude \<address\>
+
+Always exclude this address from any defined range. This address will never
+be assigned by the DHCP server.
+
+This option can be specified multiple times.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option domain-name \<domain-name\>
+
+The domain-name parameter should be the domain name that will be appended to
+the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP
+Option 015).
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option domain-search \<domain-name\>
+
+The domain-name parameter should be the domain name used when completing DNS
+request where no full FQDN is passed. This option can be given multiple times
+if you need multiple search domains (DHCP Option 119).
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option vendor-option \<option-name\>
+
+This configuration parameter lets you specify a vendor-option for the
+subnet specified within the shared network definition. An example for
+Ubiquiti is shown below:
+```
+
+**Example:**
+
+
+Create `172.18.201.0/24` as a subnet within `NET1` and pass address of
+Unifi controller at `172.16.100.1` to clients of that subnet.
+
+```none
+set service dhcp-server shared-network-name 'NET1' subnet
+'172.18.201.0/24' option vendor-option ubiquiti '172.16.100.1'
+```
+
+#### Dynamic DNS Update (RFC 2136)
+
+
+VyOS DHCP service supports RFC-2136 DDNS protocol. Based on DHCP lease change
+events, DHCP server generates DDNS update requests (defines as NameChangeRequests
+or NCRs) and posts them to a compliant DNS server, that will update its name
+database accordingly.
+
+
+VyOS built-in DNS Forwarder does not support DDNS, you will need an external DNS
+server with RFC-2136 DDNS support.
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update
+
+Enables DDNS globally.
+```
+
+**Behavioral settings**
+
+
+These settings can be configured on the global level and overridden on the scope
+level, i.e. for individual shared networks or subnets. See examples below.
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update send-updates [ enable | disable ]
+
+If set to ``enable`` on global level, updates for all scopes will be enabled,
+except if explicitly set to ``disable`` on the scope level. If set to ``disable``,
+updates will only be sent for scopes, where ``send-updates`` is explicity
+set to ``enable``.
+
+This model is followed for a few behavioral settings below: if the option is
+not set, the setting is inherited from the parent scope. You can override the
+parent scope setting by setting the option explicitly.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update override-no-update [ enable | disable ]
+
+VyOS will ignore client request not to update DNS records and send DDNS
+update requests regardless.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update override-client-update [ enable | disable ]
+
+VyOS will override client DDNS request settings and always update both
+forward and reverse DNS records.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update update-on-renew [ enable | disable ]
+
+Issue DDNS update requests on DHCP lease renew. In busy networks this may
+generate a lot of traffic.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update conflict-resolution [ enable | disable ]
+
+Use RFC-4703 conflict resolution. This algorithm helps in situation when
+multiple clients reserve same IP addresses or advertise identical hostnames.
+Should be used in most situations.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update replace-client-name [ never | always | when-present | when-not-present ]
+
+* **never**: use the name sent by the client. If the client didn't provide any,
+do not generate one. This is the default behavior
+
+* **always**: always generate a name for the client
+
+* **when-present**: replace the name the client sent with a generated one, if
+the client didn't send any, do not generate one
+
+* **when-not-present**: use the name sent by the client. If the client didn't
+send any, generate one for the client
+
+The names are generated using ``generated-prefix``, ``qualifying-suffix`` and the
+client's IP address string.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update generated-prefix \<prefix\>
+
+Prefix used in client name generation.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update qualifying-suffix \<suffix\>
+
+DNS suffix used in client name generation.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update ttl-percent \<0-100\>
+
+TTL of the DNS record as a percentage of the DHCP lease time.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update hostname-char-set \<character string\>
+
+Characters, that are considered invalid in the client name. They will be replaced
+with ``hostname-char-replacement`` string.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update hostname-char-replacement \<character string\>
+
+Replacement string for the invalid characters defined by ``hostname-char-set``.
+```
+
+**TSIG keys definition**
+
+
+This is the global list of TSIG keys for DDNS updates. They need to be specified by
+the name in the DNS domain definitions.
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update tsig-key \<key-name\> algorithm \<algorithm\>
+
+Sets the algorithm for the TSIG key. Supported algorithms are ``hmac-md5``,
+``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, ``hmac-sha512``
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update tsig-key \<key-name\> secret \<key-secret\>
+
+base64-encoded TSIG key secret value
+```
+
+**DNS domains definition**
+
+
+This is global configuration of DNS servers for the updatable forward and reverse
+DNS domains. For every domain multiple DNS servers can be specified.
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> key-name \<tsig-key-name\>
+
+TSIG key used for the domain.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> dns-server \<number\> address \<ip-address\>
+
+IP address of the DNS server.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> dns-server \<number\> port \<port\>
+
+UDP port of the DNS server. ``53`` is the default.
+```
+
+**Example:**
+
+
+Global configuration you will most likely want:
+
+```none
+set service dhcp-server dynamic-dns-update send-updates enable
+set service dhcp-server dynamic-dns-update conflict-resolution enable
+```
+
+Override the above configuration for a shared network NET1:
+
+```none
+set service dhcp-server shared-network-name 'NET1' dynamic-dns-update replace-client-name when-not-present
+set service dhcp-server shared-network-name 'NET1' dynamic-dns-update generated-prefix ip
+set service dhcp-server shared-network-name 'NET1' dynamic-dns-update qualifying-suffix mybigdomain.net
+```
+
+And in a subnet within the same shared network:
+
+```none
+set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' dynamic-dns-update qualifying-suffix mydomain.net
+```
+
+Configure TSIG keys:
+
+```none
+set service dhcp-server dynamic-dns-update tsig-key mydomain-net algorithm hmac-sha256
+set service dhcp-server dynamic-dns-update tsig-key mydomain-net secret eWF5YW15bGl0dGxla2V5IQ==
+set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 algorithm hmac-sha256
+set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 secret eWF5YW15YW5vdGhlcmxpdHRsZWtleSE=
+```
+
+Configure DDNS domains:
+
+```none
+set service dhcp-server dynamic-dns-update forward-domain mydomain.net key-name mydomain-net
+set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 address '172.18.0.254'
+set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 port 1053
+set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 address '192.168.124.254'
+set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 port 53
+set service dhcp-server dynamic-dns-update forward-domain 201.18.172.in-addr.arpa key-name reverse-172-18-201
+set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 address '172.18.0.254'
+set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 port 1053
+set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 address '192.168.124.254'
+set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 port 53
+```
+
+#### High Availability
+
+
+VyOS provides High Availability support for DHCP server. DHCP High
+Availability can act in two different modes:
+
+
+- **Active-active**: both DHCP servers will respond to DHCP requests. If
+  `mode` is not defined, this is the default behavior.
+- **Active-passive**: only `primary` server will respond to DHCP requests.
+  If this server goes offline, then `secondary` server will take place.
+
+
+DHCP High Availability must be configured explicitly by the following
+statements on both servers:
+
+```{cfgcmd} set service dhcp-server high-availability mode [active-active | active-passive]
+
+Define operation mode of High Availability feature. Default value if command
+is not specified is `active-active`
+```
+
+
+```{cfgcmd} set service dhcp-server high-availability source-address \<address\>
+
+Local IP `<address>` used when communicating to the HA peer.
+```
+
+
+```{cfgcmd} set service dhcp-server high-availability remote \<address\>
+
+Remote peer IP `<address>` of the second DHCP server in this HA
+cluster.
+```
+
+
+```{cfgcmd} set service dhcp-server high-availability name \<name\>
+
+Define the name of the peer server to establish and identify the HA (High Availability) connection.
+
+:::{note}
+Make sure the specified value does not conflict with the system host-name.
+:::
+```
+
+
+```{cfgcmd} set service dhcp-server high-availability status \<primary | secondary\>
+
+The primary and secondary statements determines whether the server is primary
+or secondary.
+
+:::{note}
+In order for the primary and the secondary DHCP server to keep
+their lease tables in sync, they must be able to reach each other on TCP
+port 647. If you have firewall rules in effect, adjust them accordingly.
+:::
+:::{hint}
+The dialogue between HA partners is neither encrypted nor
+authenticated. Since most DHCP servers exist within an organisation's own
+secure Intranet, this would be an unnecessary overhead. However, if you
+have DHCP HA peers whose communications traverse insecure networks,
+then we recommend that you consider the use of VPN tunneling between them
+to ensure that the HA partnership is immune to disruption
+(accidental or otherwise) via third parties.
+:::
+```
+
+#### Static mappings
+
+
+You can specify a static DHCP assignment on a per host basis. You will need the
+MAC address of the station and your desired IP address. The address must be
+inside the subnet definition but can be outside of the range statement.
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> mac \<address\>
+
+Create a new DHCP static mapping named `<description>` which is valid for
+the host identified by its MAC `<address>`.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> duid \<identifier\>
+
+Create a new DHCP static mapping named `<description>` which is valid for
+the host identified by its DHCP unique identifier (DUID) `<identifier>`.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> ip-address \<address\>
+
+Static DHCP IP address assign to host identified by `<description>`. IP
+address must be inside the `<subnet>` which is defined but can be outside
+the dynamic range created with {cfgcmd}`set service dhcp-server
+shared-network-name <name> subnet <subnet> range <n>`. If no ip-address is
+specified, an IP from the dynamic pool is used.
+
+This is useful, for example, in combination with hostfile update.
+
+:::{hint}
+This is the equivalent of the host block in dhcpd.conf of
+isc-dhcpd.
+:::
+```
+
+**Example:**
+
+
+- IP address `192.168.1.100` shall be statically mapped to client named `client1`
+
+```none
+set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 subnet-id 1
+set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 ip-address 192.168.1.100
+set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 mac aa:bb:11:22:33:00
+```
+
+The configuration will look as follows:
+
+```none
+show service dhcp-server shared-network-name NET1
+ subnet 192.168.1.0/24 {
+     static-mapping client1 {
+         ip-address 192.168.1.100
+         mac aa:bb:11:22:33:00
+     }
+     subnet-id 1
+ }
+```
+
+#### Relay agent information (Option 82)
+
+
+Some DHCP relays support the injection of information into a DHCP request, depending on
+where the request originated from. This is commonly used to determine the
+behaviour of the DHCP server, based on the port/switch combination where the
+request was first detected. I.e. the device plugged into a particular port (or
+set of ports) always gets the same IP address (or range of IP addresses). This
+information is usually included in the request using Option 82, hence this
+is what we call this part of the configuration.
+
+
+This behaviour is controlled in two parts. First, "client classes" are defined
+which determine which inputs match. Once a positive match has been found the
+request is "tagged" with this client class. Second, when the DHCP server
+processes the request it checks to see if the configuration has a client class
+defined. If it does then that part of the configuration will override the others
+
+
+Client classes can be applied at either the subnet or range level, depending on
+how you want the server to behave.
+
+
+**Client Class definition**
+
+```{cfgcmd} set service dhcp-server client-class \<name\> relay-agent-information circuit-id \<value\>
+
+Create a new client class (if not already defined) and set it to match on
+the "Circuit ID" part of the Option 82 field in the DHCP request. This is
+sub option "1" as specified by RFC 3046. The value specified here is either
+interpreted as a raw hex value, if it starts with the prefix 0x, or ASCII text
+otherwise. e.g. ``e1-5`` and ``0x65312d35`` are the same
+```
+
+
+```{cfgcmd} set service dhcp-server client-class \<name\> relay-agent-information remote-id \<value\>
+
+Create a new client class (if not already defined) and set it to match on
+the "Remote ID" part of the Option 82 field in the DHCP request. This is
+sub option "2" as specified by RFC 3046. The value specified here is either
+interpreted as a raw hex value, if it starts with the prefix 0x, or ASCII text
+otherwise. e.g. ``10.100.0.41`` and ``0x31302e3130302e302e3431`` are the
+same
+```
+
+**Client Class application**
+
+```{cfgcmd} set service dhcp-server shared-network-name \<subnet-name\> subnet \<CIDR\> client-class \<class-name\>
+
+Applies the Client Class with the name `<class-name>` to the subnet `<subnet-name>`.
+This means that whenever the client class matches a request it is always
+routed to this subnet definition first.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<subnet-name\> subnet \<CIDR\> range \<range-name\> client-class \<class-name\>
+
+Applies the Client Class with the name `<class-name>` to the range
+`<range-name>` which belongs to subnet `<subnet-name>`. This means that whenever the
+client class matches a request it is always routed to this range definition
+first.
+```
+
+NB: Kea (the DHCP server used by VyOS) is programmed to offer as many
+alternatives as it can to repeated DHCP Discover requests. Some operating
+systems (Notably Microsoft Windows) make multiple DHCP Discover requests before
+settling on an address. This particularly seems to happen when the DHCP server
+isn't set to authorative. This may explain why the address you espect isn't
+being chosen. Wireshark is helpful in these situations.
+
+
+**Example:**
+
+
+The following configuration example will classify requests coming in on port
+`e1-5` from DHCP Relay `192.0.2.1` and make sure that they are allocated the
+address `192.0.2.4`. Any requests which do not match the circuit and remote ID
+will, instead, be allocated from the range otherRange in the usual manner.
+
+
+NB: Both the Circuit ID and Remote ID fields are arbitrary free text. *Most*
+switches set the Remote ID to the IP address of the management interface but
+that should not be relied upon. Check the documentation of your DHCP Relay for
+more detail or, as a measure of last resort, inspect the DHCP requests in
+Wireshark.
+
+```none
+service {
+    dhcp-server {
+        client-class className {
+            relay-agent-information {
+                circuit-id e1-5
+                remote-id 192.0.2.1
+            }
+        }
+        shared-network-name test {
+            subnet 192.0.2.0/24 {
+                range classNameRange {
+                    client-class className
+                    start 192.0.2.4
+                    stop 192.0.2.4
+                }
+                range otherRange {
+                    start 192.0.2.5
+                    stop 192.0.2.100
+                }
+                subnet-id 1
+            }
+        }
+    }
+}
+```
+
+### Options
+
+
+:::{list-table}
+:header-rows: 1
+:stub-columns: 0
+:widths: 12 7 23 40 20
+
+* - Setting name
+  - Option number
+  - ISC-DHCP Option name
+  - Option description
+  - Multi
+* - client-prefix-length
+  - 1
+  - subnet-mask
+  - Specifies the clients subnet mask as per RFC 950. If unset,
+    subnet declaration is used.
+  - N
+* - time-offset
+  - 2
+  - time-offset
+  - Offset of the client's subnet in seconds from Coordinated
+    Universal Time (UTC)
+  - N
+* - default-router
+  - 3
+  - routers
+  - IPv4 address of router on the client's subnet
+  - N
+* - time-server
+  - 4
+  - time-servers
+  - RFC 868 time server IPv4 address
+  - Y
+* - name-server
+  - 6
+  - domain-name-servers
+  - DNS server IPv4 address
+  - Y
+* - domain-name
+  - 15
+  - domain-name
+  - Client domain name
+  - Y
+* - ip-forwarding
+  - 19
+  - ip-forwarding
+  - Enable IP forwarding on client
+  - N
+* - ntp-server
+  - 42
+  - ntp-servers
+  - IP address of NTP server
+  - Y
+* - wins-server
+  - 44
+  - netbios-name-servers
+  - NetBIOS over TCP/IP name server
+  - Y
+* - server-identifier
+  - 54
+  - dhcp-server-identifier
+  - IP address for DHCP server identifier
+  - N
+* - bootfile-server
+  - siaddr
+  - next-server
+  - IPv4 address of next bootstrap server
+  - N
+* - tftp-server-name
+  - 66
+  - tftp-server-name
+  - Name or IPv4 address of TFTP server
+  - N
+* - bootfile-name
+  - 67
+  - bootfile-name, filename
+  - Bootstrap file name
+  - N
+* - bootfile-size
+  - 13
+  - boot-size
+  - Boot image length in 512-octet blocks
+  - N
+* - smtp-server
+  - 69
+  - smtp-server
+  - IP address of SMTP server
+  - Y
+* - pop-server
+  - 70
+  - pop-server
+  - IP address of POP3 server
+  - Y
+* - domain-search
+  - 119
+  - domain-search
+  - Client domain search
+  - Y
+* - static-route
+  - 121, 249
+  - rfc3442-static-route, windows-static-route
+  - Classless static route
+  - N
+* - wpad-url
+  - 252
+  - wpad-url, wpad-url code 252 = text
+  - Web Proxy Autodiscovery (WPAD) URL
+  - N
+* - lease
+  -
+  - default-lease-time, max-lease-time
+  - Lease timeout in seconds (default: 86400)
+  - N
+* - range
+  -
+  - range
+  - DHCP lease range
+  - Y
+* - exclude
+  -
+  -
+  - IP address to exclude from DHCP lease range
+  - Y
+* - failover
+  -
+  -
+  - DHCP failover parameters
+  -
+* - static-mapping
+  -
+  -
+  - Name of static mapping
+  - Y
+:::
+
+
+Multi: can be specified multiple times.
+
+
+### Example
+
+
+Please see the {ref}`dhcp-dns-quick-start` configuration.
+
+
+(dhcp-server-v4-example-failover)=
+
+
+#### High Availability
+
+
+Configuration of a DHCP HA pair:
+
+
+- Setup DHCP HA for network 192.0.2.0/24
+- Use active-active HA mode.
+- Default gateway and DNS server is at `192.0.2.254`
+- The primary DHCP server named dhcp-primary uses address `192.168.189.252`
+- The secondary DHCP server with named dhcp-secondary uses address `192.168.189.253`
+- DHCP range spans from `192.168.189.10` - `192.168.189.250`
+
+
+Common configuration, valid for both primary and secondary node.
+
+```none
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option default-router '192.0.2.254'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option name-server '192.0.2.254'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option domain-name 'vyos.net'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 subnet-id '1'
+```
+
+**Primary**
+
+```none
+set service dhcp-server high-availability mode 'active-active'
+set service dhcp-server high-availability source-address '192.168.189.252'
+set service dhcp-server high-availability name 'dhcp-secondary'
+set service dhcp-server high-availability remote '192.168.189.253'
+set service dhcp-server high-availability status 'primary'
+```
+
+**Secondary**
+
+```none
+set service dhcp-server high-availability mode 'active-active'
+set service dhcp-server high-availability source-address '192.168.189.253'
+set service dhcp-server high-availability name 'dhcp-primary'
+set service dhcp-server high-availability remote '192.168.189.252'
+set service dhcp-server high-availability status 'secondary'
+```
+
+(dhcp-server-v4-example-raw)=
+
+
+### Operation Mode
+
+```{opcmd} show log dhcp server
+
+Show DHCP server daemon log file
+```
+
+
+```{opcmd} show log dhcp client
+
+Show logs from all DHCP client processes.
+```
+
+
+```{opcmd} show log dhcp client interface \<interface\>
+
+Show logs from specific `interface` DHCP client process.
+```
+
+
+```{opcmd} restart dhcp server
+
+Restart the DHCP server
+```
+
+
+```{opcmd} show dhcp server statistics
+
+Show the DHCP server statistics:
+```
+
+
+```none
+vyos@vyos:~$ show dhcp server statistics
+Pool           Size    Leases    Available  Usage
+-----------  ------  --------  -----------  -------
+dhcpexample      99         2           97  2%
+```
+
+
+```{opcmd} show dhcp server statistics pool \<pool\>
+
+Show the DHCP server statistics for the specified pool.
+```
+
+
+```{opcmd} show dhcp server leases
+
+Show statuses of all active leases:
+```
+
+
+```none
+vyos@vyos:~$ show dhcp server leases
+IP Address      MAC address        State    Lease start          Lease expiration     Remaining    Pool      Hostname    Origin
+--------------  -----------------  -------  -------------------  -------------------  -----------  --------  ----------  --------
+192.168.11.134  00:50:79:66:68:09  active   2023/11/29 09:51:05  2023/11/29 10:21:05  0:24:10      LAN       VPCS1       local
+192.168.11.133  50:00:00:06:00:00  active   2023/11/29 09:51:38  2023/11/29 10:21:38  0:24:43      LAN       VYOS-6      local
+10.11.11.108    50:00:00:05:00:00  active   2023/11/29 09:51:43  2023/11/29 10:21:43  0:24:48      VIF-1001  VYOS5       local
+192.168.11.135  00:50:79:66:68:07  active   2023/11/29 09:55:16  2023/11/29 09:59:16  0:02:21                            remote
+vyos@vyos:~$
+```
+
+:::{hint}
+Static mappings aren't shown. To show all states, use
+`show dhcp server leases state all`.
+:::
+
+```{opcmd} show dhcp server leases origin [local | remote]
+
+Show statuses of all active leases granted by local (this server) or
+remote (failover server):
+```
+
+
+```none
+vyos@vyos:~$ show dhcp server leases origin remote
+IP Address      MAC address        State    Lease start          Lease expiration     Remaining    Pool      Hostname    Origin
+--------------  -----------------  -------  -------------------  -------------------  -----------  --------  ----------  --------
+192.168.11.135  00:50:79:66:68:07  active   2023/11/29 09:55:16  2023/11/29 09:59:16  0:02:21                            remote
+vyos@vyos:~$
+```
+
+
+```{opcmd} show dhcp server leases pool \<pool\>
+
+Show only leases in the specified pool.
+```
+
+
+```none
+vyos@vyos:~$ show dhcp server leases pool LAN
+IP Address      MAC address        State    Lease start          Lease expiration     Remaining    Pool    Hostname    Origin
+--------------  -----------------  -------  -------------------  -------------------  -----------  ------  ----------  --------
+192.168.11.134  00:50:79:66:68:09  active   2023/11/29 09:51:05  2023/11/29 10:21:05  0:23:55      LAN     VPCS1       local
+192.168.11.133  50:00:00:06:00:00  active   2023/11/29 09:51:38  2023/11/29 10:21:38  0:24:28      LAN     VYOS-6      local
+vyos@vyos:~$
+```
+
+
+```{opcmd} show dhcp server leases sort \<key\>
+
+Sort the output by the specified key. Possible keys: ip, hardware_address,
+state, start, end, remaining, pool, hostname (default = ip)
+```
+
+
+```{opcmd} show dhcp server leases state \<state\>
+
+Show only leases with the specified state. Possible states: all, active,
+free, expired, released, abandoned, reset, backup (default = active)
+```
+
+## IPv6 server
+
+VyOS also provides DHCPv6 server functionality which is described in this
+section.
+(dhcp-server-v6-config)=
+
+### Configuration
+
+```{cfgcmd} set service dhcpv6-server preference \<preference value\>
+
+   Clients receiving advertise messages from multiple servers choose the server
+   with the highest preference value. The range for this value is ``0...255``.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<subnet\> subnet-id \<id\>
+
+This configuration parameter is required and must be unique to each subnet.
+It is required to map subnets to lease file entries.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> lease-time {default | maximum | minimum}
+
+The default lease time for DHCPv6 leases is 24 hours. This can be changed by
+supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All
+values need to be supplied in seconds.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nis-domain \<domain-name\>
+
+A {abbr}`NIS (Network Information Service)` domain can be set to be used for
+DHCPv6 clients.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nisplus-domain \<domain-name\>
+
+The procedure to specify a {abbr}`NIS+ (Network Information Service Plus)`
+domain is similar to the NIS domain one:
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nis-server \<address\>
+
+Specify a NIS server address for DHCPv6 clients.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nisplus-server \<address\>
+
+Specify a NIS+ server address for DHCPv6 clients.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option sip-server \<address | fqdn\>
+
+Specify a {abbr}`SIP (Session Initiation Protocol)` server by IPv6
+address of Fully Qualified Domain Name for all DHCPv6 clients.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option sntp-server-address \<address\>
+
+A SNTP server address can be specified for DHCPv6 clients.
+```
+
+#### Prefix Delegation
+
+
+To hand out individual prefixes to your clients the following configuration is
+used:
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> prefix-length \<lenght\>
+
+Delegate prefixes from `<pd-prefix>` to clients in subnet `<prefix>`. Range
+is defined by `<lenght>` in bits, 32 to 64.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> delegated-length \<lenght\>
+
+Hand out prefixes of size `<length>` in bits from `<pd-prefix>` to clients
+in subnet `<prefix>` when the request for prefix delegation.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> excluded-prefix \<exclude-prefix\>
+
+Exclude `<exclude-prefix>` from `<pd-prefix>`.
+```
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> excluded-prefix-length \<length\>
+
+Define lenght of exclude prefix in `<pd-prefix>`.
+```
+
+**Example:**
+- A shared network named `PD-NET` serves subnet `2001:db8::/64`.
+- It is connected to `eth1`.
+- Address pool shall be `2001:db8::100` through `2001:db8::199`.
+- It hands out prefixes `2001:db8:0:10::/64` through `2001:db8:0:1f::/64`.
+
+```none
+set service dhcpv6-server shared-network-name 'PD-NET' interface 'eth1'
+set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 start 2001:db8::100
+set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 stop 2001:db8::199
+set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: delegated-length '64'
+set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: prefix-length '60'
+set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 subnet-id 1
+```
+
+#### Address pools
+
+DHCPv6 address pools must be configured for the system to act as a DHCPv6
+server. The following example describes a common scenario.
+
+**Example:**
+- A shared network named `NET1` serves subnet `2001:db8::/64`
+- It is connected to `eth1`
+- DNS server is located at `2001:db8::ffff`
+- Address pool shall be `2001:db8::100` through `2001:db8::199`.
+- Lease time will be left at the default value which is 24 hours
+
+```none
+set service dhcpv6-server shared-network-name 'NET' interface 'eth1'
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 range 1 start 2001:db8::100
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 range 1 stop 2001:db8::199
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 option name-server 2001:db8::ffff
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 subnet-id 1
+```
+
+The configuration will look as follows:
+
+```none
+show service dhcpv6-server
+    shared-network-name NET1 {
+        subnet 2001:db8::/64 {
+           range 1 {
+              start 2001:db8::100
+              stop 2001:db8::199
+           }
+           option {
+              name-server 2001:db8::ffff
+           }
+           subnet-id 1
+        }
+    }
+```
+
+(dhcp-server-v6-static-mapping)=
+
+#### Static mappings
+
+In order to map specific IPv6 addresses to specific hosts static mappings can
+be created. The following example explains the process.
+
+**Example:**
+- IPv6 address `2001:db8::101` shall be statically mapped
+- IPv6 prefix `2001:db8:0:101::/64` shall be statically mapped
+- Host specific mapping shall be named `client1`
+
+:::{hint}
+The identifier is the device's DUID: colon-separated hex list (as
+used by isc-dhcp option dhcpv6.client-id). If the device already has a
+dynamic lease from the DHCPv6 server, its DUID can be found with `show
+service dhcpv6 server leases`. The DUID begins at the 5th octet (after the
+4th colon) of IAID_DUID.
+:::
+```none
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-prefix 2001:db8:0:101::/64
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 duid 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff
+```
+
+The configuration will look as follows:
+
+```none
+show service dhcpv6-server shared-network-name NET1
+ subnet 2001:db8::/64 {
+     static-mapping client1 {
+         duid 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff
+         ipv6-address 2001:db8::101
+         ipv6-prefix 2001:db8:0:101::/64
+     }
+ }
+```
+
+(dhcp-server-v6-op-cmd)=
+
+### Operation Mode
+
+```{opcmd} show log dhcpv6 server
+
+Show DHCPv6 server daemon log file
+```
+```{opcmd} show log dhcpv6 client
+
+Show logs from all DHCPv6 client processes.
+```
+```{opcmd} show log dhcpv6 client interface \<interface\>
+
+Show logs from specific `interface` DHCPv6 client process.
+```
+```{opcmd} restart dhcpv6 server
+
+To restart the DHCPv6 server
+```
+```{opcmd} show dhcpv6 server leases
+
+Shows status of all assigned leases:
+```
+```none
+vyos@vyos:~$ show dhcpv6 server leases
+IPv6 address      State    Last communication    Lease expiration     Remaining    Type   Pool      DUID
+----------------  -------  --------------------  -------------------  -----------  -----  --------  --------------------------------------------
+2001:db8::101     active   2019/12/05 19:40:10   2019/12/06 07:40:10  11:45:21     IA_NA  NET1      98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff
+2001:db8::102     active   2019/12/05 14:01:23   2019/12/06 02:01:23  6:06:34      IA_NA  NET1      87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff
+2001:db8:10::/64  active   2019/12/05 23:20:10   2019/12/06 11:40:10  11:45:21     IA_PD  PD-NET1   98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff
+```
+
+:::{hint}
+Static mappings aren't shown. To show all states, use `show dhcp
+server leases state all`.
+:::
+
+```{opcmd} show dhcpv6 server leases pool \<pool\>
+
+Show only leases in the specified pool.
+```
+```{opcmd} show dhcpv6 server leases sort \<key\>
+
+Sort the output by the specified key. Possible keys: expires, iaid_duid, ip,
+last_comm, pool, remaining, state, type (default = ip)
+```
+```{opcmd} show dhcpv6 server leases state \<state\>
+
+Show only leases with the specified state. Possible states: abandoned,
+active, all, backup, expired, free, released, reset (default = active)
+```
\ No newline at end of file
diff --git a/docs/configuration/service/dns.md b/docs/configuration/service/dns.md
new file mode 100644
index 00000000..e7e9b457
--- /dev/null
+++ b/docs/configuration/service/dns.md
@@ -0,0 +1,582 @@
+(dns-forwarding)=
+
+# DNS Forwarding
+
+## Configuration
+
+VyOS provides DNS infrastructure for small networks. It is designed to be
+lightweight and have a small footprint, suitable for resource constrained
+routers and firewalls. For this we utilize PowerDNS recursor.
+
+The VyOS DNS forwarder does not require an upstream DNS server. It can serve as
+a full recursive DNS server - but it can also forward queries to configurable
+upstream DNS servers. By not configuring any upstream DNS servers you also
+avoid being tracked by the provider of your upstream DNS server.
+
+```{cfgcmd} set service dns forwarding system
+
+   Forward incoming DNS queries to the DNS servers configured under the ``system
+   name-server`` nodes.
+```
+
+
+```{cfgcmd} set service dns forwarding dhcp \<interface\>
+
+Interfaces whose DHCP client nameservers to forward requests to.
+```
+
+
+```{cfgcmd} set service dns forwarding name-server \<address\> port \<port\>
+
+Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`
+on optional port specified under `<port>`. The port defaults to 53. You can
+configure multiple nameservers here.
+```
+
+
+```{cfgcmd} set service dns forwarding domain \<domain-name\> name-server \<address\>
+
+Forward received queries for a particular domain
+(specified via `domain-name`) to a given nameserver. Multiple nameservers
+can be specified. You can use this feature for a DNS split-horizon
+configuration.
+
+:::{note}
+This also works for reverse-lookup zones (``18.172.in-addr.arpa``).
+:::
+```
+
+
+```{cfgcmd} set service dns forwarding domain \<domain-name\> addnta
+
+Add NTA (negative trust anchor) for this domain. This must be set if the
+domain does not support DNSSEC.
+```
+
+
+```{cfgcmd} set service dns forwarding domain \<domain-name\> recursion-desired
+
+Set the "recursion desired" bit in requests to the upstream nameserver.
+```
+
+
+```{cfgcmd} set service dns forwarding allow-from \<network\>
+
+Given the fact that open DNS recursors could be used on DDoS amplification
+attacks, you must configure the networks which are allowed to use this
+recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and
+IPv6 networks to query this server. This is generally a bad idea.
+```
+
+
+```{cfgcmd} set service dns forwarding dnssec \<off | process-no-validate | process | log-fail | validate\>
+
+The PowerDNS recursor has 5 different levels of DNSSEC processing, which can
+be set with the dnssec setting. In order from least to most processing, these
+are:
+
+* **off** In this mode, no DNSSEC processing takes place. The recursor will
+not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the
+DO and AD bits in queries.
+
+* **process-no-validate** In this mode the recursor acts as a "security
+aware, non-validating" nameserver, meaning it will set the DO-bit on
+outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to
+clients that ask for them (by means of a DO-bit in the query), except for
+zones provided through the auth-zones setting. It will not do any
+validation in this mode, not even when requested by the client.
+
+* **process** When dnssec is set to process the behavior is similar to
+process-no-validate. However, the recursor will try to validate the data
+if at least one of the DO or AD bits is set in the query; in that case,
+it will set the AD-bit in the response when the data is validated
+successfully, or send SERVFAIL when the validation comes up bogus.
+
+* **log-fail** In this mode, the recursor will attempt to validate all data
+it retrieves from authoritative servers, regardless of the client's DNSSEC
+desires, and will log the validation result. This mode can be used to
+determine the extra load and amount of possibly bogus answers before
+turning on full-blown validation. Responses to client queries are the same
+as with process.
+
+* **validate** The highest mode of DNSSEC processing. In this mode, all
+queries will be validated and will be answered with a SERVFAIL in case of
+bogus data, regardless of the client's request.
+
+:::{note}
+The popular Unix/Linux ``dig`` tool sets the AD-bit in the query.
+This might lead to unexpected query results when testing. Set ``+noad``
+on the ``dig`` command line when this is the case.
+:::
+
+:::{note}
+The ``CD``-bit is honored correctly for process and validate. For
+log-fail, failures will be logged too.
+:::
+```
+
+
+```{cfgcmd} set service dns forwarding ignore-hosts-file
+
+Do not use the local ``/etc/hosts`` file in name resolution. VyOS DHCP
+server will use this file to add resolvers to assigned addresses.
+```
+
+
+```{cfgcmd} set service dns forwarding cache-size \<0-2147483647\>
+
+Maximum number of DNS cache entries. 1 million per CPU core will generally
+suffice for most installations.
+
+This defaults to 10000.
+```
+
+
+```{cfgcmd} set service dns forwarding negative-ttl \<0-7200\>
+
+A query for which there is authoritatively no answer is cached to quickly
+deny a record's existence later on, without putting a heavy load on the
+remote server. In practice, caches can become saturated with hundreds of
+thousands of hosts which are tried only once.
+
+This setting, which defaults to 3600 seconds, puts a maximum on the amount
+of time negative entries are cached.
+```
+
+
+```{cfgcmd} set service dns forwarding timeout \<10-60000\>
+
+The number of milliseconds to wait for a remote authoritative server to
+respond before timing out and responding with SERVFAIL.
+
+This setting defaults to 1500 and is valid between 10 and 60000.
+```
+
+
+```{cfgcmd} set service dns forwarding listen-address \<address\>
+
+The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder
+will listen on this address for incoming connections.
+```
+
+
+```{cfgcmd} set service dns forwarding source-address \<address\>
+
+The local IPv4 or IPv6 addresses to use as a source address for sending queries.
+The forwarder will send forwarded outbound DNS requests from this address.
+```
+
+
+```{cfgcmd} set service dns forwarding no-serve-rfc1918
+
+This makes the server authoritatively not aware of: 10.in-addr.arpa,
+168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream
+DNS server(s) to be used for reverse lookups of these zones.
+```
+
+### Authoritative zones
+
+
+The VyOS DNS forwarder can also be configured to host authoritative records for a domain.
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> disable
+
+Disable hosting authoritative zone for `<domain-name>` without deleting from
+configuration.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> disable
+
+Disable specific record without deleting it from configuration.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> ttl \<seconds\>
+
+Set the {abbr}`TTL (Time-to-live)` for the record in seconds. Default is 300 seconds.
+```
+
+#### Record types
+
+
+Below are a list of record types available to be configured within VyOS. Some records
+support special `<name>` keywords:
+
+
+- `@` Use @ as record name to set the record for the root domain.
+- `any` Use any as record name to configure the record as a wildcard.
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records a \<name\> address \<x.x.x.x\>
+
+Set an {abbr}`A (Address)` record. Supports ``@`` and ``any`` keywords.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records aaaa \<name\> address \<h:h:h:h:h:h:h:h\>
+
+Set an {abbr}`AAAA (IPv6 Address)` record. Supports ``@`` and ``any`` keywords.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records cname \<name\> target \<target-domain-name\>
+
+Set an {abbr}`CNAME (Canonical name)` record. Supports ``@`` keyword.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<rule-number\> \<option\> \<value\>
+
+Set an {abbr}`NAPTR (Naming authority pointer)` record. Supports ``@`` keyword.
+NAPTR records support the following options:
+
+* **lookup-a** A Flag.
+
+* **lookup-srv** S flag.
+
+* **order** Rule order. Requires `<value>`.
+
+* **preference** Rule preference. Requires `<value>`. Defaults to 0 if not set.
+
+* **protocol-specific** P flag.
+
+* **regexp** Regular expression. Requires `<value>`.
+
+* **replacement** Replacement DNS name.
+
+* **resolve-uri** U flag.
+
+* **service** Service type. Requires `<value>`.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records ns \<name\> target \<target-name\>
+
+Set an {abbr}`NS (Nameserver)` record.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records ptr \<name\> target \<target-name\>
+
+Set an {abbr}`PTR (Pointer record)` record. Supports ``@`` keyword.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records spf \<name\> value \<value\>
+
+Set an {abbr}`SPF (Sender policy framework)` record. Supports ``@`` keyword.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records srv \<name\> entry \<entry-number\> [hostname | port | priority | weight] \<value\>
+
+Set an {abbr}`SRV (Service)` record. Supports ``@`` keyword.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records txt \<name\> value \<value\>
+
+Set an {abbr}`TXT (Text)` record. Supports ``@`` keyword.
+```
+
+## Example
+
+
+A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to
+implement a split-horizon DNS configuration for example.com.
+
+
+In this scenario:
+
+
+- All DNS requests for example.com must be forwarded to a DNS server
+  at 192.0.2.254 and 2001:db8:cafe::1
+- All other DNS requests will be forwarded to a different set of DNS servers at
+  192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff
+- The VyOS DNS forwarder will only listen for requests on the eth1 (LAN)
+  interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6
+- The VyOS DNS forwarder will only accept lookup requests from the
+  LAN subnets - 192.168.1.0/24 and 2001:db8::/64
+- The VyOS DNS forwarder will pass reverse lookups for 10.in-addr.arpa,
+  168.192.in-addr.arpa, 16-31.172.in-addr.arpa zones to upstream server.
+
+```none
+set service dns forwarding domain example.com name-server 192.0.2.254
+set service dns forwarding domain example.com name-server 2001:db8:cafe::1
+set service dns forwarding name-server 192.0.2.1
+set service dns forwarding name-server 192.0.2.2
+set service dns forwarding name-server 192.0.2.3 port 853
+set service dns forwarding name-server 2001:db8::1:ffff
+set service dns forwarding name-server 2001:db8::2:ffff
+set service dns forwarding name-server 2001:db8::3:ffff port 8053
+set service dns forwarding listen-address 192.168.1.254
+set service dns forwarding listen-address 2001:db8::ffff
+set service dns forwarding allow-from 192.168.1.0/24
+set service dns forwarding allow-from 2001:db8::/64
+set service dns forwarding no-serve-rfc1918
+```
+
+## Operation
+
+```{opcmd} reset dns forwarding \<all | domain\>
+
+Resets the local DNS forwarding cache database. You can reset the cache
+for all entries or only for entries to a specific domain.
+```
+
+
+```{opcmd} restart dns forwarding
+
+Restarts the DNS recursor process. This also invalidates the local DNS
+forwarding cache.
+```
+
+(dynamic-dns)=
+
+# Dynamic DNS
+
+VyOS is able to update a remote DNS record when an interface gets a new IP
+address. In order to do so, VyOS includes [ddclient], a Perl script written for
+this only one purpose.
+
+[ddclient] uses two methods to update a DNS record. The first one will send
+updates directly to the DNS daemon, in compliance with {rfc}`2136`. The second
+one involves a third party service, like DynDNS.com or any other such
+service provider. This method uses HTTP requests to transmit the new IP address.
+You can configure both in VyOS.
+(dns-dynamic-config)=
+
+## Configuration
+### {rfc}`2136` Based
+
+```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\>
+
+   Create new dynamic DNS update configuration which will update the IP
+   address assigned to `<interface>` on the service you configured under
+   `<service-name>`.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\>
+
+Set description `<text>` for dynamic DNS service being configured.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> key \<filename\>
+
+File identified by `<filename>` containing the TSIG authentication key for RFC2136
+nsupdate on remote DNS server.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\>
+
+Configure the DNS `<server>` IP/FQDN used when updating this dynamic
+assignment.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> zone \<zone\>
+
+Configure DNS `<zone>` to be updated.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<record\>
+
+Configure DNS `<record>` which should be updated. This can be set multiple times.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> ttl \<ttl\>
+
+Configure optional TTL value on the given resource record. This defaults to
+600 seconds.
+```
+
+
+```{cfgcmd} set service dns dynamic interval \<60-3600\>
+
+Specify interval in seconds to wait between Dynamic DNS updates.
+The default is  300 seconds.
+```
+
+(dns-dynamic-example)=
+
+
+#### Example
+
+
+- Register DNS record `example.vyos.io` on DNS server `ns1.vyos.io`
+- Use auth key file at `/config/auth/my.key`
+- Set TTL to 300 seconds
+
+```none
+# Configuration commands entered:
+#
+set service dns dynamic name 'VyOS-DNS' address interface 'eth0'
+set service dns dynamic name 'VyOS-DNS' description 'RFC 2136 dynamic dns service'
+set service dns dynamic name 'VyOS-DNS' key '/config/auth/my.key'
+set service dns dynamic name 'VyOS-DNS' server 'ns1.vyos.io'
+set service dns dynamic name 'VyOS-DNS' zone 'vyos.io'
+set service dns dynamic name 'VyOS-DNS' host-name 'example.vyos.io'
+set service dns dynamic name 'VyOS-DNS' protocol 'nsupdate'
+set service dns dynamic name 'VyOS-DNS' ttl '300'
+
+# Resulting config:
+#
+vyos@vyos# show service dns dynamic
+ name VyOS-DNS {
+     address {
+         interface eth0
+     }
+     description "RFC 2136 dynamic dns service"
+     host-name example.vyos.io
+     key /config/auth/my.key
+     protocol nsupdate
+     server ns1.vyos.io
+     ttl 300
+     zone vyos.io
+ }
+```
+
+This will render the following [ddclient] configuration entry:
+
+```none
+# ddclient configuration for interface "eth0":
+#
+
+# Web service dynamic DNS configuration for VyOS-DNS: [nsupdate, example.vyos.io]
+use=if, \
+if=eth0, \
+protocol=nsupdate, \
+server=ns1.vyos.io, \
+zone=vyos.io, \
+password='/config/auth/my.key', \
+ttl=300 \
+example.vyos.io
+```
+
+:::{note}
+You can also keep different DNS zone updated. Just create a new
+config node: `set service dns dynamic interface <interface> rfc2136
+<other-service-name>`
+:::
+
+
+### HTTP based services
+
+
+VyOS is also able to use any service relying on protocols supported by ddclient.
+
+
+To use such a service, one must define a login, password, one or multiple
+hostnames, protocol and server.
+
+```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\>
+
+Create new dynamic DNS update configuration which will update the IP
+address assigned to `<interface>` on the service you configured under
+`<service-name>`.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\>
+
+Set description `<text>` for dynamic DNS service being configured.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<hostname\>
+
+Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS
+provider identified by `<service-name>`.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> username \<username\>
+
+Configure `<username>` used when authenticating the update request for
+DynDNS service identified by `<service-name>`.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> password \<password\>
+
+Configure `<password>` used when authenticating the update request for
+DynDNS service identified by `<service-name>`.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> protocol \<protocol\>
+
+When a ``custom`` DynDNS provider is used, the protocol used for communicating
+to the provider must be specified under `<protocol>`. See the embedded
+completion helper when entering above command for available protocols.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\>
+
+When a ``custom`` DynDNS provider is used the `<server>` where update
+requests are being sent to must be specified.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> ip-version 'ipv6'
+
+Allow explicit IPv6 address for the interface.
+```
+
+#### Example:
+
+Use deSEC (dedyn.io) as your preferred provider:
+
+```none
+set service dns dynamic name dedyn description 'deSEC dynamic dns service'
+set service dns dynamic name dedyn username 'myusername'
+set service dns dynamic name dedyn password 'mypassword'
+set service dns dynamic name dedyn host-name 'myhostname.dedyn.io'
+set service dns dynamic name dedyn protocol 'dyndns2'
+set service dns dynamic name dedyn server 'update.dedyn.io'
+set service dns dynamic name dedyn address interface 'eth0'
+```
+
+:::{note}
+Multiple services can be used per interface. Just specify as many
+services per interface as you like!
+:::
+#### Example IPv6 only:
+
+```none
+set service dns dynamic name dedyn description 'deSEC ipv6 dynamic dns service'
+set service dns dynamic name dedyn username 'myusername'
+set service dns dynamic name dedyn password 'mypassword'
+set service dns dynamic name dedyn host-name 'myhostname.dedyn.io'
+set service dns dynamic name dedyn protocol 'dyndns2'
+set service dns dynamic name dedyn ip-version 'ipv6'
+set service dns dynamic name dedyn server 'update6.dedyn.io'
+set service dns dynamic name dedyn address interface 'eth0'
+```
+
+### Running Behind NAT
+
+By default, [ddclient] will update a dynamic dns record using the IP address
+directly attached to the interface. If your VyOS instance is behind NAT, your
+record will be updated to point to your internal IP.
+
+[ddclient] has another way to determine the WAN IP address. This is controlled
+by:
+
+```{cfgcmd} set service dns dynamic name \<service-name\> address web \<url\>
+
+Use configured `<url>` to determine your IP address. [ddclient] will load
+`<url>` and tries to extract your IP address from the response.
+```
+```{cfgcmd} set service dns dynamic name \<service-name\> address web skip \<pattern\>
+
+ddclient will skip any address located before the string set in `<pattern>`.
+```
+
+[ddclient]: https://github.com/ddclient/ddclient
diff --git a/docs/configuration/service/eventhandler.md b/docs/configuration/service/eventhandler.md
new file mode 100644
index 00000000..48031909
--- /dev/null
+++ b/docs/configuration/service/eventhandler.md
@@ -0,0 +1,130 @@
+(event-handler)=
+
+# Event Handler
+
+## Event Handler Technology Overview
+
+Event handler allows you to execute scripts when a string that matches
+a regex or a regex with a service name appears in journald logs. You
+can pass variables, arguments, and a full matching string to the script.
+
+## How to configure Event Handler
+
+> [1. Create an event handler](#create-an-event-handler)
+>
+> [2. Add regex to the script](#add-regex-to-the-script)
+>
+> [3. Add a full path to the script](#add-a-full-path-to-the-script)
+>
+> [4. Add optional parameters](#add-optional-parameters)
+
+## Event Handler Configuration Steps
+
+### 1. Create an event handler
+
+```{cfgcmd} set service event-handler event \<event-handler name\>
+
+This is an optional command because the event handler will be
+automatically created after any of the next commands.
+```
+
+
+### 2. Add regex to the script
+
+```{cfgcmd} set service event-handler event \<event-handler name\> filter pattern \<regex\>
+
+This is a mandatory command. Sets regular expression to match
+against log string message.
+
+:::{note}
+The regular expression matches if and only if the entire
+string matches the pattern.
+:::
+```
+
+
+### 3. Add a full path to the script
+
+```{cfgcmd} set service event-handler event \<event-handler name\> script path \<path to script\>
+
+This is a mandatory command. Sets the full path to the script.
+The script file must be executable.
+```
+
+
+### 4. Add optional parameters
+
+```{cfgcmd} set service event-handler event \<event-handler name\> filter syslog-identifier \<syslogid name\>
+
+This is an optional command. Filters log messages by
+syslog-identifier.
+```
+
+```{cfgcmd} set service event-handler event \<event-handler name\> script environment \<env name\> value \<env value\>
+
+This is an optional command. Adds environment and its value to
+the script. Use separate commands for each environment.
+
+One implicit environment exists.
+
+* ``message``: Full message that has triggered the script.
+```
+
+```{cfgcmd} set service event-handler event \<event-handler name\> script arguments \<arguments\>
+
+This is an optional command. Adds arguments to the script.
+Arguments must be separated by spaces.
+
+:::{note}
+We don't recommend to use arguments. Using environments
+is more preferable.
+:::
+```
+
+
+## Example
+
+Event handler that monitors the state of interface eth0.
+
+```none
+set service event-handler event INTERFACE_STATE_DOWN filter pattern '.*eth0.*,RUNNING,.*->.*'
+set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd'
+set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down'
+set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth0'
+set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py'
+```
+
+Event handler script
+
+```none
+#!/usr/bin/env python3
+#
+# VyOS event-handler script example
+from os import environ
+import subprocess
+from sys import exit
+
+# Perform actions according to requirements
+def process_event() -> None:
+    # Get variables
+    message_text = environ.get('message')
+    interface_name = environ.get('interface_name')
+    interface_action = environ.get('interface_action')
+    # Print the message that triggered this script
+    print(f'Logged message: {message_text}')
+    # Prepare a command to run
+    command = f'sudo ip link set {interface_name} {interface_action}'.split()
+    # Execute a command
+    subprocess.run(command)
+
+if __name__ == '__main__':
+    try:
+        # Run script actions and exit
+        process_event()
+        exit(0)
+    except Exception as err:
+        # Exit properly in case if something in the script goes wrong
+        print(f'Error running script: {err}')
+        exit(1)
+```
+
diff --git a/docs/configuration/service/https.md b/docs/configuration/service/https.md
new file mode 100644
index 00000000..184fd088
--- /dev/null
+++ b/docs/configuration/service/https.md
@@ -0,0 +1,138 @@
+(http-api)=
+
+# HTTP API
+
+VyOS provide an HTTP API. You can use it to execute op-mode commands,
+update VyOS, set or delete config.
+
+Please take a look at the {ref}`vyosapi` page for an detailed how-to.
+
+## Configuration
+
+```{cfgcmd} set service https allow-client address \<address\>
+
+Only allow certain IP addresses or prefixes to access the https
+webserver.
+```
+
+```{cfgcmd} set service https certificates ca-certificate \<name\>
+
+Use CA certificate from PKI subsystem
+```
+
+```{cfgcmd} set service https certificates certificate \<name\>
+
+Use certificate from PKI subsystem
+```
+
+```{cfgcmd} set service https certificates dh-params \<name\>
+
+Use {abbr}`DH (Diffie–Hellman)` parameters from PKI subsystem.
+Must be at least 2048 bits in length.
+```
+
+```{cfgcmd} set service https listen-address \<address\>
+
+Webserver should only listen on specified IP address
+```
+
+```{cfgcmd} set service https port \<number\>
+
+Webserver should listen on specified port.
+
+Default: 443
+```
+
+```{cfgcmd} set service https enable-http-redirect
+
+Enable automatic redirect from http to https.
+```
+
+```{cfgcmd} set service https tls-version \<1.2 | 1.3\>
+
+Select TLS version used.
+
+This defaults to both 1.2 and 1.3.
+```
+
+```{cfgcmd} set service https vrf \<name\>
+
+Start Webserver in given VRF.
+```
+
+```{cfgcmd} set service https request-body-size-limit \<size\>
+
+Set the maximum request body size in megabytes. Default is 1MB.
+```
+
+
+### API
+
+```{cfgcmd} set service https api keys id \<name\> key \<apikey\>
+
+Set a named api key. Every key has the same, full permissions
+on the system.
+```
+
+
+### REST
+
+```{cfgcmd} set service https api rest
+
+Enable REST API
+```
+
+```{cfgcmd} set service https api rest debug
+
+To enable debug messages. Available via {opcmd}`show log` or
+{opcmd}`monitor log`
+```
+
+```{cfgcmd} set service https api rest strict
+
+Enforce strict path checking.
+```
+
+
+### GraphQL
+
+```{cfgcmd} set service https api graphql introspection
+
+Enable GraphQL Schema introspection.
+```
+
+:::{note}
+Do not leave introspection enabled in production, it is a security risk.
+:::
+
+```{cfgcmd} set service https api graphql authentication type \<key | token\>
+
+Set the authentication type for GraphQL, default option is key. Available options are:
+* ``key`` use API keys configured in ``service https api keys``
+* ``token`` use JWT tokens.
+```
+
+```{cfgcmd} set service https api graphql authentication expiration
+
+Set the lifetime for JWT tokens in seconds. Default is 3600 seconds.
+```
+
+```{cfgcmd} set service https api graphql authentication secret-length
+
+Set the byte length of the JWT secret. Default is 32.
+```
+
+```{cfgcmd} set service https api graphql cors allow-origin \<origin\>
+
+Allow cross-origin requests from \<origin\>.
+```
+
+
+## Example Configuration
+
+Setting REST API and an API-KEY is the minimal configuration to get a working API Endpoint.
+
+```none
+set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY
+set service https api rest
+```
diff --git a/docs/configuration/service/index.md b/docs/configuration/service/index.md
new file mode 100644
index 00000000..4018c5be
--- /dev/null
+++ b/docs/configuration/service/index.md
@@ -0,0 +1,29 @@
+# Service
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+broadcast-relay
+config-sync
+conntrack-sync
+console-server
+dhcp-relay
+dhcp-server
+dns
+eventhandler
+https
+ipoe-server
+lldp
+mdns
+monitoring
+ntp
+pppoe-server
+router-advert
+salt-minion
+snmp
+ssh
+tftp-server
+webproxy
+suricata
+```
diff --git a/docs/configuration/service/ipoe-server.md b/docs/configuration/service/ipoe-server.md
new file mode 100644
index 00000000..88ec4f51
--- /dev/null
+++ b/docs/configuration/service/ipoe-server.md
@@ -0,0 +1,512 @@
+(ipoe-server)=
+
+# IPoE Server
+
+VyOS utilizes [accel-ppp] to provide {abbr}`IPoE (Internet Protocol over
+Ethernet)` server functionality. It can be used with local authentication
+(mac-address) or a connected RADIUS server.
+
+IPoE is a method of delivering an IP payload over an Ethernet-based access
+network or an access network using bridged Ethernet over Asynchronous Transfer
+Mode (ATM) without using PPPoE. It directly encapsulates the IP datagrams in
+Ethernet frames, using the standard {rfc}`894` encapsulation.
+
+The use of IPoE addresses the disadvantage that PPP is unsuited for multicast
+delivery to multiple users. Typically, IPoE uses Dynamic Host Configuration
+Protocol and Extensible Authentication Protocol to provide the same
+functionality as PPPoE, but in a less robust manner.
+
+:::{note}
+Please be aware, due to an upstream bug, config changes/commits
+will restart the ppp daemon and will reset existing IPoE sessions,
+in order to become effective.
+:::
+
+## Configuring IPoE Server
+
+IPoE can be configured on different interfaces, it will depend on each specific
+situation which interface will provide IPoE to clients. The client's mac address
+and the incoming interface is being used as control parameter, to authenticate
+a client.
+
+The example configuration below will assign an IP to the client on the incoming
+interface eth1 with the client mac address 00:50:79:66:68:00. Other DHCP
+discovery requests will be ignored, unless the client mac has been enabled in
+the configuration.
+
+```none
+set interfaces ethernet eth1 address '192.168.0.1/24'
+set service ipoe-server authentication interface eth1.100 mac 00:50:79:66:68:00
+set service ipoe-server authentication interface eth1.101 mac 00:50:79:66:68:01
+set service ipoe-server authentication mode 'local'
+set service ipoe-server client-ip-pool IPOE-POOL range '192.168.0.2-192.168.0.254'
+set service ipoe-server default-pool 'IPOE-POOL'
+set service ipoe-server gateway-address '192.168.0.1/24'
+set service ipoe-server interface eth1 mode 'l2'
+set service ipoe-server interface eth1 network 'vlan'
+set service ipoe-server interface eth1 vlan '100-200'
+```
+
+```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\>
+
+Creates local IPoE user with username=\*\*\<interface\>\*\* and
+password=\*\*\<MAC\>\*\* (mac-address)
+```
+
+
+```{cfgcmd} set service ipoe-server authentication mode \<local | radius\>
+
+Set authentication backend. The configured authentication backend is used
+for all queries.
+
+* **radius**: All authentication queries are handled by a configured RADIUS
+server.
+* **local**: All authentication queries are handled locally.
+* **noauth**: Authentication disabled
+```
+
+
+```{cfgcmd} set service ipoe-server client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\>
+
+Use this command to define the first IP address of a pool of
+addresses to be given to IPoE clients. If notation ``x.x.x.x-x.x.x.x``,
+it must be within a /24 subnet. If notation ``x.x.x.x/x`` is
+used there is possibility to set host/netmask.
+```
+
+
+```{cfgcmd} set service ipoe-server default-pool \<POOL-NAME\>
+
+Use this command to define default address pool name.
+```
+
+
+```{cfgcmd} set service ipoe-server gateway-address \<x.x.x.x/x\>
+
+Specifies address to be used as server ip address if radius can assign
+only client address. In such case if client address is matched network
+and mask then specified address and mask will be used. You can specify
+multiple such options.
+```
+
+
+```{cfgcmd} set service ipoe-server interface \<interface\> mode \<l2 | l3\>
+
+> Specifies the client connectivity mode.
+
+* **l2**: It means that clients are on same network where interface
+is.\*\*(default)\*\*
+* **l3**: It means that client are behind some router.
+```
+
+
+```{cfgcmd} set service ipoe-server interface \<interface\> network \<shared | vlan\>
+
+Specify where interface is shared by multiple users or it is vlan-per-user.
+
+* **shared**: Multiple clients share the same network. **(default)**
+* **vlan**: One VLAN per client.
+```
+
+
+```none
+vyos@vyos:~$ show ipoe-server sessions
+
+ ifname | username |    calling-sid    |     ip      | rate-limit | type | comp | state  |  uptime
+--------+----------+-------------------+-------------+------------+------+------+--------+----------
+ ipoe0  | eth1.100 | 00:50:79:66:68:00 | 192.168.0.2 |            | ipoe |      | active | 00:04:55
+ ipoe1  | eth1.101 | 00:50:79:66:68:01 | 192.168.0.3 |            | ipoe |      | active | 00:04:44
+```
+
+## Configuring RADIUS authentication
+
+
+To enable RADIUS based authentication, the authentication mode needs to be
+changed within the configuration. Previous settings like the local users, still
+exists within the configuration, however they are not used if the mode has been
+changed from local to radius. Once changed back to local, it will use all local
+accounts again.
+
+```none
+set service ipoe-server authentication mode radius
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius server \<server\> key \<secret\>
+
+Configure RADIUS *\<server\>* and its required shared *\<secret\>* for
+communicating with the RADIUS server.
+```
+
+Since the RADIUS server would be a single point of failure, multiple RADIUS
+servers can be setup and will be used subsequentially.
+For example:
+
+```none
+set service ipoe-server authentication radius server 10.0.0.1 key 'foo'
+set service ipoe-server authentication radius server 10.0.0.2 key 'foo'
+```
+
+:::{note}
+Some RADIUS severs use an access control list which allows or denies
+queries, make sure to add your VyOS router to the allowed client list.
+:::
+
+
+### RADIUS source address
+
+
+If you are using OSPF as IGP, always the closest interface connected to the
+RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests
+to a single source IP e.g. the loopback interface.
+
+```{cfgcmd} set service ipoe-server authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queires.
+```
+
+:::{note}
+The ``source-address`` must be configured on one of VyOS interface.
+Best practice would be a loopback or dummy interface.
+:::
+
+
+### RADIUS advanced options
+
+```{cfgcmd} set service ipoe-server authentication radius server \<server\> port \<port\>
+
+Configure RADIUS *\<server\>* and its required port for authentication requests.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius server \<server\> fail-time \<time\>
+
+Mark RADIUS server as offline for this given *\<time\>* in seconds.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius server \<server\> disable
+
+Temporary disable this RADIUS server.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius acct-timeout \<timeout\>
+
+Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius dynamic-author server \<address\>
+
+Specifies IP address for Dynamic Authorization Extension server (DM/CoA).
+This IP must exist on any VyOS interface or it can be ``0.0.0.0``.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius dynamic-author port \<port\>
+
+UDP port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius dynamic-author key \<secret\>
+
+Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius max-try \<number\>
+
+Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius timeout \<timeout\>
+
+Timeout to wait response from server (seconds)
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius nas-identifier \<identifier\>
+
+Value to send to RADIUS server in NAS-Identifier attribute and to be matched
+in DM/CoA requests.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius nas-ip-address \<address\>
+
+Value to send to RADIUS server in NAS-IP-Address attribute and to be matched
+in DM/CoA requests. Also DM/CoA server will bind to that address.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queires.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius rate-limit attribute \<attribute\>
+
+Specifies which RADIUS server attribute contains the rate limit information.
+The default attribute is *Filter-Id*.
+```
+
+:::{note}
+If you set a custom RADIUS attribute you must define it on both
+dictionaries at RADIUS server and client.
+:::
+
+```{cfgcmd} set service ipoe-server authentication radius rate-limit enable
+
+Enables bandwidth shaping via RADIUS.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius rate-limit vendor
+
+Specifies the vendor dictionary, dictionary needs to be in
+/usr/share/accel-ppp/radius.
+```
+
+Received RADIUS attributes have a higher priority than parameters defined within
+the CLI configuration, refer to the explanation below.
+
+
+### Allocation clients ip addresses by RADIUS
+
+
+If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP
+address will be allocated to the client and the option ``default-pool`` within the CLI
+config is being ignored.
+
+
+If the RADIUS server sends the attribute ``Framed-Pool``, IP address will be allocated
+from a predefined IP pool whose name equals the attribute value.
+
+
+If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, IPv6 address
+will be allocated from a predefined IPv6 pool ``prefix`` whose name equals the attribute value.
+
+
+If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, IPv6
+delegation pefix will be allocated from a predefined IPv6 pool ``delegate``
+whose name equals the attribute value.
+
+
+:::{note}
+``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in
+RFC6911. If they are not defined in your RADIUS server, add new [dictionary].
+:::
+
+
+User interface can be put to VRF context via RADIUS Access-Accept packet, or change
+it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. It is custom [ACCEL-PPP attribute].
+Define it in your RADIUS server.
+
+
+## IPv6
+
+```{cfgcmd} set service ipoe-server client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\>  mask \<number-of-bits\>
+
+Use this comand to set the IPv6 address pool from which an IPoE client
+will get an IPv6 prefix of your defined length (mask) to terminate the
+IPoE endpoint at their side. The mask length can be set from 48 to 128
+bit long, the default value is 64.
+```
+
+
+```{cfgcmd} set service ipoe-server client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\>  delegation-prefix \<number-of-bits\>
+
+Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on
+IPoE. You will have to set your IPv6 pool and the length of the
+delegation prefix. From the defined IPv6 pool you will be handing out
+networks of the defined length (delegation-prefix). The length of the
+delegation prefix can be set from 32 to 64 bit long.
+```
+
+
+```{cfgcmd} set service ipoe-server default-ipv6-pool \<IPv6-POOL-NAME\>
+
+Use this command to define default IPv6 address pool name.
+```
+
+
+```none
+set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56'
+set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64'
+set service ipoe-server default-ipv6-pool IPv6-POOL
+```
+
+## Scripting
+
+```{cfgcmd} set service ipoe-server extended-scripts on-change \<path_to_script\>
+
+Script to run when session interface changed by RADIUS CoA handling
+```
+
+
+```{cfgcmd} set service ipoe-server extended-scripts on-down \<path_to_script\>
+
+Script to run when session interface going to terminate
+```
+
+
+```{cfgcmd} set service ipoe-server extended-scripts on-pre-up \<path_to_script\>
+
+Script to run before session interface comes up
+```
+
+
+```{cfgcmd} set service ipoe-server extended-scripts on-up \<path_to_script\>
+
+Script to run when session interface is completely configured and started
+```
+
+## Advanced Options
+
+
+### Authentication Advanced Options
+
+```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> vlan  \<vlan-id\>
+
+VLAN monitor for automatic creation of VLAN interfaces for specific user on specific \<interface\>
+```
+
+
+```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit  download \<bandwidth\>
+
+Download bandwidth limit in kbit/s for user on interface *\<interface\>*.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit  upload \<bandwidth\>
+
+Upload bandwidth limit in kbit/s for for user on interface *\<interface\>*.
+```
+
+### Client IP Pool Advanced Options
+
+```{cfgcmd} set service ipoe-server client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\>
+
+Use this command to define the next address pool name.
+```
+
+### Advanced Interface Options
+
+```{cfgcmd} set service ipoe-server interface \<interface\> client-subnet \<x.x.x.x/x\>
+
+Specify local range of ip address to give to dhcp clients. First IP in range is router IP.
+If you need more customization use *client-ip-pool*
+```
+
+
+```{cfgcmd} set service ipoe-server interface \<interface\> external-dhcp dhcp-relay \<x.x.x.x\>
+
+Specify DHCPv4 relay IP address to pass requests to. If specified giaddr is also needed.
+```
+
+
+```{cfgcmd} set service ipoe-server interface \<interface\> external-dhcp giaddr \<x.x.x.x\>
+
+Specifies relay agent IP addre
+```
+
+### Global Advanced options
+
+```{cfgcmd} set service ipoe-server description \<description\>
+
+Set description.
+```
+```{cfgcmd} set service ipoe-server limits burst \<value\>
+
+Burst count
+```
+```{cfgcmd} set service ipoe-server limits connection-limit \<value\>
+
+Acceptable rate of connections (e.g. 1/min, 60/sec)
+```
+```{cfgcmd} set service ipoe-server limits timeout \<value\>
+
+Timeout in seconds
+```
+```{cfgcmd} set service ipoe-server max-concurrent-sessions
+
+Maximum number of concurrent session start attempts
+```
+```{cfgcmd} set service ipoe-server name-server \<address\>
+
+Connected client should use *\<address\>* as their DNS server. This
+command accepts both IPv4 and IPv6 addresses. Up to two nameservers
+can be configured for IPv4, up to three for IPv6.
+```
+```{cfgcmd} set service ipoe-server shaper fwmark \<1-2147483647\>
+
+Match firewall mark value
+```
+```{cfgcmd} set service ipoe-server snmp master-agent
+
+Enable SNMP
+```
+
+## Monitoring
+
+```{opcmd} show ipoe-server sessions
+
+Use this command to locally check the active sessions in the IPoE
+server.
+```
+```none
+vyos@vyos:~$ show ipoe-server sessions
+ifname  | username |    calling-sid    |     ip      | rate-limit | type | comp | state  |  uptime
+----------+----------+-------------------+-------------+------------+------+------+--------+----------
+ eth1.100 | eth1.100 | 0c:98:bd:b8:00:01 | 192.168.0.3 |            | ipoe |      | active | 03:03:58
+```
+
+```none
+vyos@vyos:~$ show ipoe-server statistics
+uptime: 0.03:31:36
+cpu: 0%
+mem(rss/virt): 6044/101360 kB
+core:
+  mempool_allocated: 148628
+  mempool_available: 144748
+  thread_count: 1
+  thread_active: 1
+  context_count: 10
+  context_sleeping: 0
+  context_pending: 0
+  md_handler_count: 6
+  md_handler_pending: 0
+  timer_count: 1
+  timer_pending: 0
+sessions:
+  starting: 0
+  active: 1
+  finishing: 0
+ipoe:
+  starting: 0
+  active: 1
+  delayed: 0
+```
+
+## Toubleshooting
+
+```none
+vyos@vyos:~$ show log ipoe-server
+
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:: recv [DHCPv4 Discover xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Discover> <Request-IP 192.168.0.3> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>]
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: eth1.100: authentication succeeded
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Offer xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Offer> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>]
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: recv [DHCPv4 Request xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Request> <Server-ID 192.168.0.1> <Request-IP 192.168.0.4> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>]
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: activate session
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: no free IPv6 address
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: session started
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Ack xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Ack> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>]
+```
+
+[accel-ppp]: https://accel-ppp.org/
+[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
+[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911
diff --git a/docs/configuration/service/lldp.md b/docs/configuration/service/lldp.md
new file mode 100644
index 00000000..7fdba6c8
--- /dev/null
+++ b/docs/configuration/service/lldp.md
@@ -0,0 +1,154 @@
+(lldp)=
+
+# LLDP
+
+{abbr}`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer
+protocol in the Internet Protocol Suite used by network devices for advertising
+their identity, capabilities, and neighbors on an IEEE 802 local area network,
+principally wired Ethernet. The protocol is formally referred to by the IEEE
+as Station and Media Access Control Connectivity Discovery specified in IEEE
+802.1AB and IEEE 802.3-2012 section 6 clause 79.
+
+LLDP performs functions similar to several proprietary protocols, such as
+{abbr}`CDP (Cisco Discovery Protocol)`,
+{abbr}`FDP (Foundry Discovery Protocol)`,
+{abbr}`NDP (Nortel Discovery Protocol)` and {abbr}`LLTD (Link Layer Topology
+Discovery)`.
+
+Information gathered with LLDP is stored in the device as a {abbr}`MIB
+(Management Information Database)` and can be queried with {abbr}`SNMP (Simple
+Network Management Protocol)` as specified in {rfc}`2922`. The topology of an
+LLDP-enabled network can be discovered by crawling the hosts and querying this
+database. Information that may be retrieved include:
+
+- System Name and Description
+- Port name and description
+- VLAN name
+- IP management address
+- System capabilities (switching, routing, etc.)
+- MAC/PHY information
+- MDI power
+- Link aggregation
+
+## Configuration
+
+```{cfgcmd} set service lldp
+
+Enable LLDP service
+```
+
+```{cfgcmd} set service lldp management-address \<address\>
+
+Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses
+can be defined. Only addresses connected to the system will be transmitted.
+```
+
+```{cfgcmd} set service lldp interface \<interface\>
+
+Enable transmission of LLDP information on given \<interface\>. You can also
+say ``all`` here so LLDP is turned on on every interface.
+```
+
+```{cfgcmd} set service lldp interface \<interface\> mode [disable|rx-tx|rx|tx]
+
+Configure the administrative status of the given port.
+
+By default, all ports are configured to be in rx-tx mode. This means they
+can receive and transmit LLDP frames.
+
+In rx mode, they won't emit any frames. In tx mode, they won't receive
+any frames. In disabled mode, no frame will be sent and any incoming frame
+will be discarded.
+```
+
+```{cfgcmd} set service lldp snmp
+
+Enable SNMP queries of the LLDP database
+```
+
+```{cfgcmd} set service lldp legacy-protocols \<cdp|edp|fdp|sonmp\>
+
+Enable given legacy protocol on this LLDP instance. Legacy protocols include:
+* ``cdp`` - Listen for CDP for Cisco routers/switches
+* ``edp`` - Listen for EDP for Extreme routers/switches
+* ``fdp`` - Listen for FDP for Foundry routers/switches
+* ``sonmp`` - Listen for SONMP for Nortel routers/switches
+```
+
+
+## Operation
+
+```{opcmd} show lldp neighbors
+
+Displays information about all neighbors discovered via LLDP.
+
+:::{code-block} none
+vyos@vyos:~$ show lldp neighbors
+Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station
+                  D - Docsis, T - Telephone, O - Other
+
+Device ID                 Local     Proto  Cap   Platform             Port ID
+---------                 -----     -----  ---   --------             -------
+BR2.vyos.net              eth0      LLDP   R     VyOS 1.2.4           eth1
+BR3.vyos.net              eth0      LLDP   RB    VyOS 1.2.4           eth2
+SW1.vyos.net              eth0      LLDP   B     Cisco IOS Software   GigabitEthernet0/6
+:::
+```
+
+```{opcmd} show lldp neighbors detail
+
+Get detailed information about LLDP neighbors.
+
+:::{code-block} none
+vyos@vyos:~$ show lldp neighbors detail
+-------------------------------------------------------------------------------
+LLDP neighbors:
+-------------------------------------------------------------------------------
+Interface:    eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33
+Chassis:
+  ChassisID:    mac 00:53:00:01:02:c9
+  SysName:      BR2.vyos.net
+  SysDescr:     VyOS 1.3-rolling-201912230217
+  MgmtIP:       192.0.2.1
+  MgmtIP:       2001:db8::ffff
+  Capability:   Bridge, on
+  Capability:   Router, on
+  Capability:   Wlan, off
+  Capability:   Station, off
+Port:
+  PortID:       mac 00:53:00:01:02:c9
+  PortDescr:    eth0
+  TTL:          120
+  PMD autoneg:  supported: no, enabled: no
+      MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable
+VLAN:         201 eth0.201
+VLAN:         205 eth0.205
+LLDP-MED:
+  Device Type:  Network Connectivity Device
+  Capability:   Capabilities, yes
+  Capability:   Policy, yes
+  Capability:   Location, yes
+  Capability:   MDI/PSE, yes
+  Capability:   MDI/PD, yes
+  Capability:   Inventory, yes
+  Inventory:
+      Hardware Revision: None
+      Software Revision: 4.19.89-amd64-vyos
+      Firmware Revision: 6.00
+      Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7
+      Manufacturer: VMware, Inc.
+      Model:        VMware Virtual Platform
+      Asset ID:     No Asset Tag
+-------------------------------------------------------------------------------
+:::
+```
+
+```{opcmd} show lldp neighbors interface \<interface\>
+
+Show LLDP neighbors connected via interface \<interface\>.
+```
+
+```{opcmd} show log lldp
+
+Used for troubleshooting.
+```
\ No newline at end of file
diff --git a/docs/configuration/service/mdns.md b/docs/configuration/service/mdns.md
new file mode 100644
index 00000000..088bca3c
--- /dev/null
+++ b/docs/configuration/service/mdns.md
@@ -0,0 +1,131 @@
+# mDNS Repeater
+
+Starting with VyOS 1.2 a {abbr}`mDNS (Multicast DNS)` repeater functionality is
+provided. Additional information can be obtained from
+<https://en.wikipedia.org/wiki/Multicast_DNS>.
+
+Multicast DNS uses the reserved address `224.0.0.251`, which is
+"administratively scoped" and does not leave the subnet. mDNS repeater
+retransmits mDNS packets from one interface to other interfaces. This enables
+support for devices using mDNS discovery (like network printers, Apple Airplay,
+Chromecast, various IP based home-automation devices etc) across multiple VLANs.
+
+Since the mDNS protocol sends the {abbr}`AA(Authoritative Answer)` records in
+the packet itself, the repeater does not need to forge the source address.
+Instead, the source address is of the interface that repeats the packet.
+
+:::{note}
+You can not run this in a VRRP setup, if multiple mDNS repeaters
+are launched in a subnet you will experience the mDNS packet storm death!
+:::
+
+## Configuration
+
+```{cfgcmd} set service mdns repeater interface \<interface\>
+
+To enable mDNS repeater you need to configure at least two interfaces so that
+all incoming mDNS packets from one interface configured here can be
+re-broadcasted to any other interface(s) configured under this section.
+```
+
+```{cfgcmd} set service mdns repeater disable
+
+mDNS repeater can be temporarily disabled without deleting the service using
+```
+
+```{cfgcmd} set service mdns repeater ip-version \<ipv4 | ipv6 | both\>
+
+mDNS repeater can be enabled either on IPv4 socket or on IPv6 socket or both
+to re-broadcast. By default, mDNS repeater will listen on both IPv4 and IPv6.
+```
+
+```{cfgcmd} set service mdns repeater allow-service \<service\>
+
+mDNS repeater can be configured to re-broadcast only specific services. By
+default, all services are re-broadcasted.
+```
+
+```{cfgcmd} set service mdns repeater browse-domain \<domain\>
+
+Allow listing additional custom domains to be browsed (in addition to the
+default ``local``) so that they can be reflected.
+```
+
+```{cfgcmd} set service mdns repeater cache-entries \<entries\>
+
+Specify how many resource records are cached per interface. Bigger values
+allow mDNS work correctly in large LANs but also increase memory consumption.
+
+Defaults to: 4096
+```
+
+
+## Firewall recommendations
+
+Unlike typical routed traffic, mDNS packets relayed between interfaces do not
+traverse the FORWARD hook chain in the firewall. Instead, they are processed
+through the following hooks:
+> - **INPUT**: For packets received by the local system
+> - **OUTPUT**: For packets sent from the local system
+
+To control or allow mDNS packet forwarding via the relay, you must define
+appropriate rules in the INPUT and OUTPUT directions. Rules in the FORWARD
+direction will have no effect on mDNS relay traffic.
+
+```none
+set firewall ipv4 input filter rule 10 action 'accept'
+set firewall ipv4 input filter rule 10 destination address '224.0.0.251'
+set firewall ipv4 input filter rule 10 destination port '5353'
+set firewall ipv4 input filter rule 10 protocol 'udp'
+set firewall ipv4 output filter rule 10 action 'accept'
+set firewall ipv4 output filter rule 10 destination address '224.0.0.251'
+set firewall ipv4 output filter rule 10 destination port '5353'
+set firewall ipv4 output filter rule 10 protocol 'udp'
+```
+
+
+## Example
+
+To listen on both `eth0` and `eth1` mDNS packets and also repeat packets
+received on `eth0` to `eth1` (and vice-versa) use the following commands:
+
+```none
+set service mdns repeater interface 'eth0'
+set service mdns repeater interface 'eth1'
+```
+
+To allow only specific services, for example `_airplay._tcp` or `_ipp._tcp`,
+(instead of all services) to be re-broadcasted, use the following command:
+
+```none
+set service mdns repeater allow-service '_airplay._tcp'
+set service mdns repeater allow-service '_ipp._tcp'
+```
+
+To allow listing additional custom domain, for example
+`openthread.thread.home.arpa`, so that it can reflected in addition to the
+default `local`, use the following command:
+
+```none
+set service mdns repeater browse-domain 'openthread.thread.home.arpa'
+```
+
+
+## Operation
+
+```{opcmd} restart mdns repeater
+
+Restart mDNS repeater service.
+```
+
+```{opcmd} show log mdns repeater
+
+Show logs for mDNS repeater service.
+```
+
+```{opcmd} monitor log mdns repeater
+
+Follow the logs for mDNS repeater service.
+```
+
+[multicast dns]: <https://en.wikipedia.org/wiki/Multicast_DNS>
diff --git a/docs/configuration/service/monitoring.md b/docs/configuration/service/monitoring.md
new file mode 100644
index 00000000..a6bf2605
--- /dev/null
+++ b/docs/configuration/service/monitoring.md
@@ -0,0 +1,334 @@
+# Monitoring
+
+VyOS supports monitoring through Telegraf as well as through Prometheus exporters.
+
+## Telegraf
+
+Telegraf is the open source server agent to help you collect metrics, events
+and logs from your routers.
+
+The following Telegraf plugins are configurable to export metrics and logs:
+: - Azure Data Explorer
+  - Prometheus Client
+  - Splunk
+  - InfluxDB
+  - Loki
+
+### Azure data explorer
+
+Telegraf output plugin [azure-data-explorer].
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer authentication client-id \<client-id\>
+
+   Authentication application client-id.
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer authentication client-secret \<client-secret\>
+
+Authentication application client-secret.
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer authentication tenant-id \<tenant-id\>
+
+Authentication application tenant-id
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer database \<name\>
+
+Remote database name.
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer group-metrics \<single-table | table-per-metric\>
+
+Type of metrics grouping when push to Azure Data Explorer. The default is
+``table-per-metric``.
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer table \<name\>
+
+Name of the single table Only if set group-metrics single-table.
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer url \<url\>
+
+Remote URL.
+```
+
+### Prometheus client
+
+Telegraf output plugin [prometheus-client]
+This plugin allows export of Telegraf metrics to Prometheus,
+for Prometheus native metrics through exporters see section below.
+
+```{cfgcmd} set service monitoring telegraf prometheus-client
+
+   Output plugin Prometheus client
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client allow-from \<prefix\>
+
+Networks allowed to query this server
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client authentication username \<username\>
+
+HTTP basic authentication username
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client authentication password \<password\>
+
+HTTP basic authentication username
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client listen-address \<address\>
+
+Local IP addresses to listen on
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client metric-version \<1 | 2\>
+
+Metris version, the default is ``2``
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client port \<port\>
+
+Port number used by connection, default is ``9273``
+```
+
+Example:
+
+```none
+set service monitoring telegraf prometheus-client
+```
+
+
+```none
+vyos@r14:~$ curl --silent localhost:9273/metrics | egrep -v "#" |  grep cpu_usage_system
+cpu_usage_system{cpu="cpu-total",host="r14"} 0.20040080160320556
+cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915
+cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655
+```
+
+### Splunk
+
+
+Telegraf output plugin [splunk] HTTP Event Collector.
+
+```{cfgcmd} set service monitoring telegraf splunk authentication insecure
+
+Use TLS but skip host validation
+```
+
+
+```{cfgcmd} set service monitoring telegraf splunk authentication token \<token\>
+
+Authorization token
+```
+
+
+```{cfgcmd} set service monitoring telegraf splunk authentication url \<url\>
+
+Remote URL to Splunk collector
+```
+
+Example:
+
+```none
+set service monitoring telegraf splunk authentication insecure
+set service monitoring telegraf splunk authentication token 'xxxxf5b8-xxxx-452a-xxxx-43828911xxxx'
+set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector'
+```
+
+### InfluxDB
+
+
+Telegraf output plugin [influxdb] to write metrics to `InfluxDB` via HTTP.
+
+```{cfgcmd} set service monitoring telegraf influxdb authentication organization \<organization\>
+
+Authentication organization name
+```
+
+
+```{cfgcmd} set service monitoring telegraf influxdb authentication token \<token\>
+
+Authentication token
+```
+
+
+```{cfgcmd} set service monitoring telegraf bucket \<bucket\>
+
+Remote ``InfluxDB`` bucket name
+```
+
+
+```{cfgcmd} set service monitoring telegraf influxdb port \<port\>
+
+Remote port
+```
+
+
+```{cfgcmd} set service monitoring telegraf influxdb url \<url\>
+
+Remote URL
+```
+
+Example:
+
+```none
+set service monitoring telegraf influxdb authentication organization 'vyos'
+set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...=='
+set service monitoring telegraf influxdb bucket 'bucket_vyos'
+set service monitoring telegraf influxdb port '8086'
+set service monitoring telegraf influxdb url 'http://r1.influxdb2.local'
+```
+
+### Loki
+
+Telegraf can be used to send logs to [loki] using tags as labels.
+
+```{cfgcmd} set service monitoring telegraf loki port \<port\>
+
+   Remote Loki port
+
+   Default is 3100
+```
+
+
+```{cfgcmd} set service monitoring telegraf loki url \<url\>
+
+Remote Loki url
+```
+
+
+```{cfgcmd} set service monitoring telegraf loki authentication username \<username\>
+```
+
+```{cfgcmd} set service monitoring telegraf loki authentication password \<password\>
+
+HTTP basic authentication.
+
+If either is set both must be set.
+```
+
+```{cfgcmd} set service monitoring telegraf loki metric-name-label \<label\>
+
+Label to use for the metric name when sending metrics.
+
+If set to an empty string, the label will not be added.
+This is NOT recommended, as it makes it impossible to differentiate
+between multiple metrics.
+```
+
+## Prometheus
+
+
+The following Prometheus exporters are configurable to export metrics:
+: - Node Exporter
+  - FRR Exporter
+
+
+### Node Exporter
+
+
+Prometheus [node_exporter] which provides a wide range of hardware and OS metrics.
+
+```{cfgcmd} set service monitoring prometheus node-exporter listen-address \<address\>
+
+Configure the address node_exporter is listening on.
+```
+
+```{cfgcmd} set service monitoring prometheus node-exporter port \<port\>
+
+Configure the port number node_exporter is listening on.
+```
+
+```{cfgcmd} set service monitoring prometheus node-exporter vrf \<name\>
+
+Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+```{cfgcmd} set service monitoring prometheus node-exporter collectors textfile
+
+Configure textfile collector to export custom metrics read from
+`/run/node_exporter/collector`
+```
+
+### FRR Exporter
+
+Prometheus [frr_exporter] which provides free range routing metrics.
+
+```{cfgcmd} set service monitoring prometheus frr-exporter listen-address \<address\>
+
+Configure the address frr_exporter is listening on.
+
+```
+
+```{cfgcmd} set service monitoring prometheus frr-exporter port \<port\>
+
+Configure the port number frr_exporter is listening on.
+```
+
+```{cfgcmd} set service monitoring prometheus frr-exporter vrf \<name\>
+
+Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+### Blackbox Exporter
+
+Prometheus [blackbox_exporter] which allows probing of endpoints over
+HTTP, HTTPS, DNS, TCP, ICMP and gRPC .
+
+```{cfgcmd} set service monitoring prometheus blackbox-exporter listen-address \<address\>
+
+Configure the address blackbox_exporter is listening on.
+```
+```{cfgcmd} set service monitoring prometheus blackbox-exporter port \<port\>
+
+Configure the port number blackbox_exporter is listening on.
+```
+```{cfgcmd} set service monitoring prometheus blackbox-exporter vrf \<name\>
+
+Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+#### Configuring modules
+
+Blackbox exporter can be configured with different modules for probing DNS or ICMP.
+
+DNS module example:
+
+```none
+set service monitoring prometheus blackbox-exporter modules dns name dns4 preferred-ip-protocol ipv4
+set service monitoring prometheus blackbox-exporter modules dns name dns4 query-name vyos.io
+set service monitoring prometheus blackbox-exporter modules dns name dns4 query-type A
+```
+
+ICMP module example:
+
+```none
+set service monitoring prometheus blackbox-exporter modules icmp name ping6 preferred-ip-protocol ipv6
+set service monitoring prometheus blackbox-exporter modules icmp name ping6 ip-protocol-fallback
+set service monitoring prometheus blackbox-exporter modules icmp name ping6 timeout 3
+```
+
+[azure-data-explorer]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer>
+[blackbox_exporter]: <https://github.com/prometheus/blackbox_exporter>
+[frr_exporter]: <https://github.com/tynany/frr_exporter>
+[influxdb]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/influxdb_v2>
+[loki]: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/loki
+[node_exporter]: <https://github.com/prometheus/node_exporter>
+[prometheus-client]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client>
+[splunk]: <https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html>
diff --git a/docs/configuration/service/ntp.md b/docs/configuration/service/ntp.md
new file mode 100644
index 00000000..c8c1dee3
--- /dev/null
+++ b/docs/configuration/service/ntp.md
@@ -0,0 +1,202 @@
+(ntp)=
+
+# NTP
+
+{abbr}`NTP (Network Time Protocol`) is a networking protocol for clock
+synchronization between computer systems over packet-switched, variable-latency
+data networks. In operation since before 1985, NTP is one of the oldest Internet
+protocols in current use.
+
+NTP is intended to synchronize all participating computers to within a few
+milliseconds of {abbr}`UTC (Coordinated Universal Time)`. It uses the
+intersection algorithm, a modified version of Marzullo's algorithm, to select
+accurate time servers and is designed to mitigate the effects of variable
+network latency. NTP can usually maintain time to within tens of milliseconds
+over the public Internet, and can achieve better than one millisecond accuracy
+in local area networks under ideal conditions. Asymmetric routes and network
+congestion can cause errors of 100 ms or more.
+
+The protocol is usually described in terms of a client-server model, but can as
+easily be used in peer-to-peer relationships where both peers consider the other
+to be a potential time source. Implementations send and receive timestamps using
+{abbr}`UDP (User Datagram Protocol)` on port number 123.
+
+NTP supplies a warning of any impending leap second adjustment, but no
+information about local time zones or daylight saving time is transmitted.
+
+The current protocol is version 4 (NTPv4), which is a proposed standard as
+documented in {rfc}`5905`. It is backward compatible with version 3, specified
+in {rfc}`1305`.
+
+:::{note}
+VyOS 1.4 uses chrony instead of ntpd (see {vytask}`T3008`) which will
+no longer accept anonymous NTP requests as in VyOS 1.3. All configurations
+will be migrated to keep the anonymous functionality. For new setups if you
+have clients using your VyOS installation as NTP server, you must specify
+the `allow-client` directive.
+:::
+
+## Configuration
+
+```{cfgcmd} set service ntp server \<address\>
+
+   Configure one or more servers for synchronisation. Server name can be either
+   an IP address or {abbr}`FQDN (Fully Qualified Domain Name)`.
+
+   There are 3 default NTP server set. You are able to change them.
+
+   * ``time1.vyos.net``
+   * ``time2.vyos.net``
+   * ``time3.vyos.net``
+```
+
+
+```{cfgcmd} set service ntp server \<address\> \<noselect | nts | pool | prefer | ptp | interleave\>
+
+Configure one or more attributes to the given NTP server.
+
+* ``noselect`` marks the server as unused, except for display purposes. The
+server is discarded by the selection algorithm.
+
+* ``nts`` enables Network Time Security (NTS) for the server as specified
+in {rfc}`8915`
+
+* ``pool`` mobilizes persistent client mode association with a number of
+remote servers.
+
+* ``prefer`` marks the server as preferred. All other things being equal,
+this host will be chosen for synchronization among a set of correctly
+operating hosts.
+
+* ``ptp`` enables the PTP transport for this server (see {ref}`ptp-transport`).
+
+* ``interleave`` enables NTP interleaved mode (see [draft-ntp-interleaved-modes]), which can improve
+synchronization accuracy and stability when supported by both parties.
+```
+
+
+```{cfgcmd} set service ntp listen-address \<address\>
+
+NTP process will only listen on the specified IP address. You must specify
+the `<address>` and optionally the permitted clients. Multiple listen
+addresses for same IP family is no longer supported. Only one IPv4 and one
+IPv6 address can be configured, using separate commands for each.
+```
+
+
+```{cfgcmd} set service ntp allow-client address \<address\>
+
+List of networks or client addresses permitted to contact this NTP server.
+
+Multiple networks/client IP addresses can be configured.
+```
+
+
+```{cfgcmd} set service ntp vrf \<name\>
+
+Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+
+```{cfgcmd} set service ntp leap-second [ignore|smear|system|timezone]
+
+Define how to handle leap-seconds.
+
+* `ignore`: No correction is applied to the clock for the leap second. The
+clock will be corrected later in normal operation when new measurements are
+made and the estimated offset includes the one second error.
+
+* `smear`: When smearing a leap second, the leap status is suppressed on the
+server and the served time is corrected slowly by slewing instead of
+stepping. The clients do not need any special configuration as they do not
+know there is any leap second and they follow the server time which
+eventually brings them back to UTC. Care must be taken to ensure they use
+only NTP servers which smear the leap second in exactly the same way for
+synchronisation.
+
+* `system`: When inserting a leap second, the kernel steps the system clock
+backwards by one second when the clock gets to 00:00:00 UTC. When deleting
+a leap second, it steps forward by one second when the clock gets to
+23:59:59 UTC.
+
+* `timezone`: This directive specifies a timezone in the system timezone
+database which chronyd can use to determine when will the next leap second
+occur and what is the current offset between TAI and UTC. It will
+periodically check if 23:59:59 and 23:59:60 are valid times in the
+timezone. This normally works with the right/UTC timezone which is the
+default
+```
+
+## Hardware Timestamping of NTP Packets
+
+
+The chrony daemon on VyOS can leverage NIC hardware capabilities to record the
+exact time packets are received on the interface, as well as when packets were
+actually transmitted. This provides improved accuracy and stability when the
+system is under load, as queuing and OS context switching can introduce a
+variable delay between when the packet is received on the network and when it
+is actually processed by the NTP daemon.
+
+
+Hardware timestamping depends on NIC support. Some NICs can be configured to
+apply timestamps to any incoming packet, while others only support applying
+timestamps to specific protocols (e.g. PTP).
+
+
+When timestamping is enabled on an interface, chrony's default behavior is to
+try to configure the interface to only timestamp NTP packets. If this mode is
+not supported, chrony will attempt to set it to timestamp all packets. If
+neither option is supported (e.g. the NIC can only timestamp received PTP
+packets), chrony will leverage timestamping on transmitted packets only, which
+still provides some benefit.
+
+```{cfgcmd} set service ntp timestamp interface \<interface\>
+
+Configures hardware timestamping on the interface \<interface\>. The special
+value `all` can also be specified to enable timestamping on all interfaces
+that support it.
+
+Configure the timestamping behavior with the following option:
+
+* ``receive-filter [all|ntp|ptp|none]`` selects the receive filter mode,
+which controls which inbound packets the NIC applies timestamps to. The
+selected mode must be supported by the NIC, or timestamping will be
+disabled for the interface.
+```
+
+The following `receive-filter` modes can be selected:
+- *all*: All received packets will be timestamped.
+- *ntp*: Only received NTP protocol packets will be timestamped.
+- *ptp*: Only received PTP protocol packets will be timestamped. Combined with
+  the PTP transport for NTP packets, this can be leveraged to take advantage of
+  hardware timestamping on NICs that only support the ptp filter mode.
+- *none*: No received packets will be timestamped. Hardware timestamping of
+  transmitted packets will still be leveraged, if supported by the NIC.
+(ptp-transport)=
+
+## PTP Transport of NTP Packets
+
+The Precision Time Protocol (IEEE 1588) is a local network time synchronization
+protocol that provides high precision time synchronization by leveraging
+hardware clocks in NICs and other network elements. VyOS does not currently
+support standards-based PTP, which can be deployed independently of
+NTP.
+
+For networks consisting of VyOS and other Linux systems running relatively
+recent versions of the chrony daemon, NTP packets can be "tunneled" over
+PTP. NTP over PTP provides the best of both worlds, leveraging hardware support
+for timestamping PTP packets while retaining the configuration flexibility and
+fault tolerance of NTP.
+
+```{cfgcmd} set service ntp ptp
+
+Enables the NTP daemon PTP transport. The NTP daemon will listen on the
+configured PTP port. Note that one or more servers must be individually
+enabled for PTP before the daemon will synchronize over the transport.
+```
+```{cfgcmd} set service ntp ptp port \<port\>
+
+Configures the PTP port. By default, the standard port 319 is used.
+```
+
+[draft-ntp-interleaved-modes]: https://datatracker.ietf.org/doc/draft-ietf-ntp-interleaved-modes/07/
diff --git a/docs/configuration/service/pppoe-server.md b/docs/configuration/service/pppoe-server.md
new file mode 100644
index 00000000..32881845
--- /dev/null
+++ b/docs/configuration/service/pppoe-server.md
@@ -0,0 +1,753 @@
+---
+lastproofread: '2022-09-17'
+---
+
+(pppoe-server)=
+
+# PPPoE Server
+
+VyOS utilizes [accel-ppp](https://accel-ppp.org/) to provide PPPoE server functionality. It can
+be used with local authentication or a connected RADIUS server.
+
+:::{note}
+Please be aware, due to an upstream bug, config
+changes/commits will restart the ppp daemon and will reset existing
+PPPoE connections from connected users, in order to become effective.
+:::
+
+## Configuring PPPoE Server
+
+```none
+set service pppoe-server access-concentrator PPPoE-Server
+set service pppoe-server authentication mode local
+set service pppoe-server authentication local-users username test password 'test'
+set service pppoe-server client-ip-pool PPPOE-POOL range 192.168.255.2-192.168.255.254
+set service pppoe-server default-pool 'PPPOE-POOL'
+set service pppoe-server gateway-address 192.168.255.1
+set service pppoe-server interface eth0
+```
+
+```{cfgcmd} set service pppoe-server access-concentrator \<name\>
+
+   Use this command to set a name for this PPPoE-server access
+   concentrator.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication mode \<local | radius\>
+
+Set authentication backend. The configured authentication backend is used
+for all queries.
+
+* **radius**: All authentication queries are handled by a configured RADIUS
+server.
+* **local**: All authentication queries are handled locally.
+* **noauth**: Authentication disabled.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication local-users username \<name\> password \<password\>
+
+Create `<user>` for local authentication on this system. The users password
+will be set to `<pass>`.
+```
+
+
+```{cfgcmd} set service pppoe-server client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\>
+
+Use this command to define the first IP address of a pool of
+addresses to be given to pppoe clients. If notation ``x.x.x.x-x.x.x.x``,
+it must be within a /24 subnet. If notation ``x.x.x.x/x`` is
+used there is possibility to set host/netmask.
+```
+
+
+```{cfgcmd} set service pppoe-server default-pool \<POOL-NAME\>
+
+Use this command to define default address pool name.
+```
+
+
+```{cfgcmd} set service pppoe-server interface \<interface\>
+
+Use this command to define the interface the PPPoE server will use to
+listen for PPPoE clients.
+```
+
+
+```{cfgcmd} set service pppoe-server gateway-address \<address\>
+
+Specifies single `<gateway>` IP address to be used as local address of PPP
+interfaces.
+```
+
+## Configuring RADIUS authentication
+
+To enable RADIUS based authentication, the authentication mode needs to be
+changed within the configuration. Previous settings like the local users, still
+exists within the configuration, however they are not used if the mode has been
+changed from local to radius. Once changed back to local, it will use all local
+accounts again.
+
+```none
+set service pppoe-server authentication mode radius
+```
+
+```{cfgcmd} set service pppoe-server authentication radius server \<server\> key \<secret\>
+
+Configure RADIUS `<server>` and its required shared `<secret>` for
+communicating with the RADIUS server.
+```
+
+Since the RADIUS server would be a single point of failure, multiple RADIUS
+servers can be setup and will be used subsequentially.
+For example:
+
+```none
+set service pppoe-server authentication radius server 10.0.0.1 key 'foo'
+set service pppoe-server authentication radius server 10.0.0.2 key 'foo'
+```
+
+:::{note}
+Some RADIUS severs use an access control list which allows or denies
+queries, make sure to add your VyOS router to the allowed client list.
+:::
+
+
+### RADIUS source address
+
+
+If you are using OSPF as IGP, always the closest interface connected to the
+RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests
+to a single source IP e.g. the loopback interface.
+
+```{cfgcmd} set service pppoe-server authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queires.
+```
+
+:::{note}
+The `source-address` must be configured on one of VyOS interface.
+Best practice would be a loopback or dummy interface.
+:::
+
+
+### RADIUS advanced options
+
+```{cfgcmd} set service pppoe-server authentication radius server \<server\> port \<port\>
+
+Configure RADIUS `<server>` and its required port for authentication requests.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius server \<server\> fail-time \<time\>
+
+Mark RADIUS server as offline for this given `<time>` in seconds.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius server \<server\> disable
+
+Temporary disable this RADIUS server.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius acct-timeout \<timeout\>
+
+Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius dynamic-author server \<address\>
+
+Specifies IP address for Dynamic Authorization Extension server (DM/CoA).
+This IP must exist on any VyOS interface or it can be ``0.0.0.0``.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius dynamic-author port \<port\>
+
+UDP port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius dynamic-author key \<secret\>
+
+Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius max-try \<number\>
+
+Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius timeout \<timeout\>
+
+Timeout to wait response from server (seconds)
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius nas-identifier \<identifier\>
+
+Value to send to RADIUS server in NAS-Identifier attribute and to be matched
+in DM/CoA requests.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius nas-ip-address \<address\>
+
+Value to send to RADIUS server in NAS-IP-Address attribute and to be matched
+in DM/CoA requests. Also DM/CoA server will bind to that address.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queires.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius rate-limit attribute \<attribute\>
+
+Specifies which RADIUS server attribute contains the rate limit information.
+The default attribute is ``Filter-Id``.
+```
+
+:::{note}
+If you set a custom RADIUS attribute you must define it on both
+dictionaries at RADIUS server and client.
+:::
+
+```{cfgcmd} set service pppoe-server authentication radius rate-limit enable
+
+Enables bandwidth shaping via RADIUS.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius rate-limit vendor
+
+Specifies the vendor dictionary, dictionary needs to be in
+/usr/share/accel-ppp/radius.
+```
+
+Received RADIUS attributes have a higher priority than parameters defined within
+the CLI configuration, refer to the explanation below.
+
+
+### Allocation clients ip addresses by RADIUS
+
+
+If the RADIUS server sends the attribute `Framed-IP-Address` then this IP
+address will be allocated to the client and the option `default-pool`
+within the CLI config is being ignored.
+
+
+If the RADIUS server sends the attribute `Framed-Pool`, IP address will
+be allocated from a predefined IP pool whose name equals the attribute value.
+
+
+If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`,
+IPv6 address will be allocated from a predefined IPv6 pool `prefix`
+whose name equals the attribute value.
+
+
+If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`,
+IPv6 delegation pefix will be allocated from a predefined IPv6 pool `delegate`
+whose name equals the attribute value.
+
+
+:::{note}
+`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool`
+are defined in RFC6911. If they are not defined in your RADIUS server,
+add new [dictionary].
+:::
+
+
+User interface can be put to VRF context via RADIUS Access-Accept packet,
+or change it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes.
+It is custom [ACCEL-PPP attribute]. Define it in your RADIUS server.
+
+
+### Renaming clients interfaces by RADIUS
+
+
+If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be
+renamed.
+
+
+:::{note}
+The value of the attribute `NAS-Port-Id` must be less than 16
+characters, otherwise the interface won't be renamed.
+:::
+
+
+## Automatic VLAN Creation
+
+```{cfgcmd} set service pppoe-server interface \<interface\> vlan \<id | range\>
+
+VLAN's can be created by Accel-ppp on the fly via the use of a Kernel module
+named ``vlan_mon``, which is monitoring incoming vlans and creates the
+necessary VLAN if required and allowed. VyOS supports the use of either
+VLAN ID's or entire ranges, both values can be defined at the same time for
+an interface.
+
+When configured, PPPoE will create the necessary VLANs when required. Once
+the user session has been cancelled and the VLAN is not needed anymore, VyOS
+will remove it again.
+```
+
+
+```none
+set service pppoe-server interface eth3 vlan 100
+set service pppoe-server interface eth3 vlan 200
+set service pppoe-server interface eth3 vlan 500-1000
+set service pppoe-server interface eth3 vlan 2000-3000
+```
+
+## Bandwidth Shaping
+
+
+Bandwidth rate limits can be set for local users or RADIUS based
+attributes.
+
+
+### For Local Users
+
+```{cfgcmd} set service pppoe-server authentication local-users username \<user\> rate-limit download \<bandwidth\>
+
+Download bandwidth limit in kbit/s for `<user>`.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication local-users username \<user\> rate-limit upload \<bandwidth\>
+
+Upload bandwidth limit in kbit/s for `<user>`.
+```
+```none
+set service pppoe-server access-concentrator 'ACN'
+set service pppoe-server authentication local-users username foo password 'bar'
+set service pppoe-server authentication local-users username foo rate-limit download '20480'
+set service pppoe-server authentication local-users username foo rate-limit upload '10240'
+set service pppoe-server authentication mode 'local'
+set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100/24'
+set service pppoe-server default-pool 'IP-POOL'
+set service pppoe-server name-server '10.100.100.1'
+set service pppoe-server name-server '10.100.200.1'
+set service pppoe-server interface 'eth1'
+set service pppoe-server gateway-address '10.1.1.2'
+```
+
+Once the user is connected, the user session is using the set limits and
+can be displayed via `show pppoe-server sessions`.
+
+```none
+show pppoe-server sessions
+ifname | username |     ip     |    calling-sid    | rate-limit  | state  |  uptime  | rx-bytes | tx-bytes
+-------+----------+------------+-------------------+-------------+--------+----------+----------+----------
+ppp0   | foo      | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B    | 76 B
+```
+
+### For RADIUS users
+
+The current attribute `Filter-Id` is being used as default and can be
+setup within RADIUS:
+
+Filter-Id=2000/3000 (means 2000Kbit down-stream rate and 3000Kbit
+up-stream rate)
+
+The command below enables it, assuming the RADIUS connection has been
+setup and is working.
+
+```{cfgcmd} set service pppoe-server authentication radius rate-limit enable
+
+   Use this command to enable bandwidth shaping via RADIUS.
+```
+
+Other attributes can be used, but they have to be in one of the
+dictionaries in */usr/share/accel-ppp/radius*.
+
+
+## Load Balancing
+
+```{cfgcmd} set service pppoe-server pado-delay \<number-of-ms\> sessions \<number-of-sessions\>
+
+Use this command to enable the delay of PADO (PPPoE Active Discovery
+Offer) packets, which can be used as a session balancing mechanism
+with other PPPoE servers.
+```
+
+
+```none
+set service pppoe-server pado-delay 50 sessions '500'
+set service pppoe-server pado-delay 100 sessions '1000'
+set service pppoe-server pado-delay 300 sessions '3000'
+```
+
+In the example above, the first 499 sessions connect without delay. PADO
+packets will be delayed 50 ms for connection from 500 to 999, this trick
+allows other PPPoE servers send PADO faster and clients will connect to
+other servers. Last command says that this PPPoE server can serve only
+3000 clients.
+
+
+## IPv6
+
+```{cfgcmd} set service pppoe-server ppp-options ipv6 \<require | prefer | allow | deny\>
+
+Specifies IPv6 negotiation preference.
+
+* **require** - Require IPv6 negotiation
+* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects
+* **allow** - Negotiate IPv6 only if client requests
+* **deny** - Do not negotiate IPv6 (default value)
+```
+
+
+```{cfgcmd} set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\>
+
+Use this comand to set the IPv6 address pool from which an PPPoE client
+will get an IPv6 prefix of your defined length (mask) to terminate the
+PPPoE endpoint at their side. The mask length can be set from 48 to 128
+bit long, the default value is 64.
+```
+
+
+```{cfgcmd} set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\>
+
+Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on
+PPPoE. You will have to set your IPv6 pool and the length of the
+delegation prefix. From the defined IPv6 pool you will be handing out
+networks of the defined length (delegation-prefix). The length of the
+delegation prefix can be set from 32 to 64 bit long.
+```
+
+
+```{cfgcmd} set service pppoe-server default-ipv6-pool \<IPv6-POOL-NAME\>
+
+Use this command to define default IPv6 address pool name.
+```
+
+
+```none
+set service pppoe-server ppp-options ipv6 allow
+set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56'
+set service pppoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64'
+set service pppoe-server default-ipv6-pool IPv6-POOL
+```
+
+### IPv6 Advanced Options
+
+```{cfgcmd} set service pppoe-server ppp-options ipv6-accept-peer-interface-id
+
+Accept peer interface identifier. By default is not defined.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<random | x:x:x:x\>
+
+Specifies fixed or random interface identifier for IPv6.
+By default is fixed.
+
+* **random** - Random interface identifier for IPv6
+* **x:x:x:x** - Specify interface identifier for IPv6
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<random | x:x:x:x\>
+
+Specifies peer interface identifier for IPv6. By default is fixed.
+
+* **random** - Random interface identifier for IPv6
+* **x:x:x:x** - Specify interface identifier for IPv6
+* **ipv4-addr** - Calculate interface identifier from IPv4 address.
+* **calling-sid** - Calculate interface identifier from calling-station-id.
+```
+
+## Scripting
+
+```{cfgcmd} set service pppoe-server extended-scripts on-change \<path_to_script\>
+
+Script to run when session interface changed by RADIUS CoA handling
+```
+
+
+```{cfgcmd} set service pppoe-server extended-scripts on-down \<path_to_script\>
+
+Script to run when session interface going to terminate
+```
+
+
+```{cfgcmd} set service pppoe-server extended-scripts on-pre-up \<path_to_script\>
+
+Script to run before session interface comes up
+```
+
+
+```{cfgcmd} set service pppoe-server extended-scripts on-up \<path_to_script\>
+
+Script to run when session interface is completely configured and started
+```
+
+## Advanced Options
+
+
+### Authentication Advanced Options
+
+```{cfgcmd} set service pppoe-server authentication local-users username \<user\> disable
+
+Disable `<user>` account.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication local-users username \<user\> static-ip \<address\>
+
+Assign static IP address to `<user>` account.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication protocols \<pap | chap | mschap | mschap-v2\>
+
+Require the peer to authenticate itself using one of the following protocols:
+pap, chap, mschap, mschap-v2.
+```
+
+### Client IP Pool Advanced Options
+
+```{cfgcmd} set service pppoe-server client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\>
+
+Use this command to define the next address pool name.
+```
+
+### PPP Advanced Options
+
+```{cfgcmd} set service pppoe-server ppp-options disable-ccp
+
+Disable Compression Control Protocol (CCP).
+CCP is enabled by default.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options interface-cache \<number\>
+
+Specifies number of interfaces to keep in cache. It means that don’t
+destroy interface after corresponding session is destroyed, instead
+place it to cache and use it later for new sessions repeatedly.
+This should reduce kernel-level interface creation/deletion rate lack.
+Default value is **0**.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options ipv4 \<require | prefer | allow | deny\>
+
+Specifies IPv4 negotiation preference.
+
+* **require** - Require IPv4 negotiation
+* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects
+* **allow** - Negotiate IPv4 only if client requests (Default value)
+* **deny** - Do not negotiate IPv4
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options lcp-echo-failure \<number\>
+
+Defines the maximum `<number>` of unanswered echo requests. Upon reaching the
+value `<number>`, the session will be reset. Default value is **3**.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options lcp-echo-interval \<interval\>
+
+If this option is specified and is greater than 0, then the PPP module will
+send LCP pings of the echo request every `<interval>` seconds.
+Default value is **30**.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options lcp-echo-timeout
+
+Specifies timeout in seconds to wait for any peer activity. If this option
+specified it turns on adaptive lcp echo functionality and "lcp-echo-failure"
+is not used. Default value is **0**.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options min-mtu \<number\>
+
+Defines minimum acceptable MTU. If client will try to negotiate less then
+specified MTU then it will be NAKed or disconnected if rejects greater MTU.
+Default value is **100**.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options mppe \<require | prefer | deny\>
+
+Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation
+preference.
+
+* **require** - ask client for mppe, if it rejects drop connection
+* **prefer** - ask client for mppe, if it rejects don't fail. (Default value)
+* **deny** - deny mppe
+
+Default behavior - don't ask client for mppe, but allow it if client wants.
+Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy
+attribute.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options mru \<number\>
+
+Defines preferred MRU. By default is not defined.
+```
+
+### Global Advanced options
+
+```{cfgcmd} set service pppoe-server description \<description\>
+
+Set description.
+```
+
+
+```{cfgcmd} set service pppoe-server limits burst \<value\>
+
+Burst count
+```
+
+
+```{cfgcmd} set service pppoe-server limits connection-limit \<value\>
+
+Acceptable rate of connections (e.g. 1/min, 60/sec)
+```
+
+
+```{cfgcmd} set service pppoe-server limits timeout \<value\>
+
+Timeout in seconds
+```
+
+
+```{cfgcmd} set service pppoe-server mtu
+
+Maximum Transmission Unit (MTU) (default: **1492**)
+```
+
+
+```{cfgcmd} set service pppoe-server max-concurrent-sessions
+
+Maximum number of concurrent session start attempts
+```
+
+
+```{cfgcmd} set service pppoe-server name-server \<address\>
+
+Connected client should use `<address>` as their DNS server. This
+command accepts both IPv4 and IPv6 addresses. Up to two nameservers
+can be configured for IPv4, up to three for IPv6.
+```
+
+
+```{cfgcmd} set service pppoe-server service-name \<names\>
+
+Specifies Service-Name to respond. If absent any Service-Name is
+acceptable and client’s Service-Name will be sent back. Also possible
+set multiple service-names: `sn1,sn2,sn3`
+```
+
+Per default the user session is being replaced if a second
+authentication request succeeds. Such session requests can be either
+denied or allowed entirely, which would allow multiple sessions for a
+user in the latter case. If it is denied, the second session is being
+rejected even if the authentication succeeds, the user has to terminate
+its first session and can then authentication again.
+
+```{cfgcmd} set service pppoe-server session-control
+
+* **disable**: Disables session control.
+* **deny**: Deny second session authorization.
+* **replace**: Terminate first session when second is authorized **(default)**
+```
+
+
+```{cfgcmd} set service pppoe-server shaper fwmark \<1-2147483647\>
+
+Match firewall mark value
+```
+
+
+```{cfgcmd} set service pppoe-server snmp master-agent
+
+Enable SNMP
+```
+
+
+```{cfgcmd} set service pppoe-server wins-server \<address\>
+
+Windows Internet Name Service (WINS) servers propagated to client
+```
+
+## Monitoring
+
+```{opcmd} show pppoe-server sessions
+
+Use this command to locally check the active sessions in the PPPoE
+server.
+```
+```none
+show pppoe-server sessions
+ifname | username |     ip     |    calling-sid    | rate-limit  | state  |  uptime  | rx-bytes | tx-bytes
+-------+----------+------------+-------------------+-------------+--------+----------+----------+----------
+ppp0   | foo      | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B    | 76 B
+```
+
+## Examples
+### IPv4
+
+The example below uses ACN as access-concentrator name, assigns an
+address from the pool 10.1.1.100-111, terminates at the local endpoint
+10.1.1.1 and serves requests only on eth1.
+
+```none
+set service pppoe-server access-concentrator 'ACN'
+set service pppoe-server authentication local-users username foo password 'bar'
+set service pppoe-server authentication mode 'local'
+set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100-10.1.1.111'
+set service pppoe-server default-pool 'IP-POOL'
+set service pppoe-server interface eth1
+set service pppoe-server gateway-address '10.1.1.2'
+set service pppoe-server name-server '10.100.100.1'
+set service pppoe-server name-server '10.100.200.1'
+```
+
+### Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation
+
+The example below covers a dual-stack configuration.
+
+```none
+set service pppoe-server authentication local-users username test password 'test'
+set service pppoe-server authentication mode 'local'
+set service pppoe-server client-ip-pool IP-POOL range '192.168.0.1/24'
+set service pppoe-server default-pool 'IP-POOL'
+set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56'
+set service pppoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64'
+set service pppoe-server default-ipv6-pool IPv6-POOL
+set service pppoe-server ppp-options ipv6 allow
+set service pppoe-server name-server '10.1.1.1'
+set service pppoe-server name-server '2001:db8:4860::8888'
+set service pppoe-server interface 'eth2'
+set service pppoe-server gateway-address '10.100.100.1'
+```
+
+The client, once successfully authenticated, will receive an IPv4 and an
+IPv6 /64 address to terminate the PPPoE endpoint on the client side and
+a /56 subnet for the clients internal use.
+
+```none
+vyos@pppoe-server:~$ sh pppoe-server sessions
+ ifname | username |     ip      |            ip6           |       ip6-dp        |    calling-sid    | rate-limit | state  |  uptime  | rx-bytes | tx-bytes
+--------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+----------
+ ppp0   | test     | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb |            | active | 00:00:49 | 875 B    | 2.1 KiB
+```
+
+[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
+[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911
diff --git a/docs/configuration/service/router-advert.md b/docs/configuration/service/router-advert.md
new file mode 100644
index 00000000..10753105
--- /dev/null
+++ b/docs/configuration/service/router-advert.md
@@ -0,0 +1,121 @@
+(router-advert)=
+
+# Router Advertisements
+
+{abbr}`RAs (Router advertisements)` are described in {rfc}`4861#section-4.6.2`.
+They are part of what is known as {abbr}`SLAAC (Stateless Address
+Autoconfiguration)`.
+
+Supported interface types:
+
+> - bonding
+> - bridge
+> - ethernet
+> - geneve
+> - l2tpv3
+> - openvpn
+> - pseudo-ethernet
+> - tunnel
+> - vxlan
+> - wireguard
+> - wireless
+> - wwan
+
+## Configuration
+
+```{cfgcmd} set service router-advert interface \<interface\> ...
+```
+
+```{eval-rst}
+.. csv-table::
+   :header: "Field", "VyOS Option", "Description"
+   :widths: 10, 10, 20
+
+   "Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets"
+   """Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration"
+   """Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information"
+   "MTU","link-mtu","Link MTU value placed in RAs, excluded in RAs if unset"
+   "Router Lifetime","default-lifetime","Lifetime associated with the default router in units of seconds"
+   "Reachable Time","reachable-time","Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation"
+   "Retransmit Timer","retrans-timer","Time in milliseconds between retransmitted Neighbor Solicitation messages"
+   "Default Router Preference","default-preference","Preference associated with the default router"
+   "Interval", "interval", "Min and max intervals between unsolicited multicast RAs"
+   "DNSSL", "dnssl", "DNS search list to advertise"
+   "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106"
+   "Auto Ignore Prefix", "auto-ignore", "Exclude a prefix from being advertised when the wildcard ::/64 prefix is used"
+   "Captive Portal", "captive-portal", "Advertise a URL pointing to an RFC 8908-compliant API to tell hosts that they are behind a captive portal"
+```
+
+### Advertising a Prefix
+
+```{cfgcmd} set service router-advert interface \<interface\> prefix \<prefix/mask\>
+
+:::{note}
+You can also opt for using ::/64 as prefix for your {abbr}`RAs (Router
+Advertisements)`. This is a special wildcard prefix that will emit {abbr}`RAs (Router Advertisements)` for every prefix assigned to the interface.
+This comes in handy when using dynamically obtained prefixes from DHCPv6-PD.
+:::
+```
+```{eval-rst}
+.. csv-table::
+    :header: "VyOS Field", "Description"
+    :widths: 10,30
+
+    "decrement-lifetime", "Lifetime is decremented by the number of seconds since the last RA - use in conjunction with a DHCPv6-PD prefix"
+    "deprecate-prefix", "Upon shutdown, this option will deprecate the prefix by announcing it in the shutdown RA"
+    "no-autonomous-flag","Prefix can not be used for stateless address auto-configuration"
+    "no-on-link-flag","Prefix can not be used for on-link determination"
+    "preferred-lifetime","Time in seconds that the prefix will remain preferred (default 4 hours)"
+    "valid-lifetime","Time in seconds that the prefix will remain valid (default: 30 days)"
+```
+
+### Advertising a NAT64 Prefix
+
+```{cfgcmd} set service router-advert interface \<interface\> nat64prefix \<prefix/mask\>
+
+Enable PREF64 option as outlined in {rfc}`8781`.
+
+NAT64 prefix mask must be one of: /32, /40, /48, /56, /64 or 96.
+
+:::{note}
+The well known NAT64 prefix is ``64:ff9b::/96``
+:::
+```
+```{eval-rst}
+.. csv-table::
+    :header: "VyOS Field", "Description"
+    :widths: 10,30
+
+    "valid-lifetime","Time in seconds that the prefix will remain valid (default: 65528 seconds)"
+```
+
+### Disabling Advertisements
+
+To disable advertisements without deleting the configuration:
+
+```{cfgcmd} set service router-advert interface \<interface\> no-send-advert
+
+If set, the router will no longer send periodic router advertisements and
+will not respond to router solicitations.
+```
+
+```{cfgcmd} set service router-advert interface \<interface\> no-send-interval
+
+Advertisement Interval Option (specified by Mobile IPv6) is always included in
+Router Advertisements unless this option is set.
+```
+
+## Example
+
+Your LAN connected on eth0 uses prefix `2001:db8:beef:2::/64` with the router
+beeing `2001:db8:beef:2::1`
+
+```none
+set interfaces ethernet eth0 address 2001:db8:beef:2::1/64
+
+set service router-advert interface eth0 default-preference 'high'
+set service router-advert interface eth0 name-server '2001:db8::1'
+set service router-advert interface eth0 name-server '2001:db8::2'
+set service router-advert interface eth0 other-config-flag
+set service router-advert interface eth0 prefix 2001:db8:beef:2::/64
+```
diff --git a/docs/configuration/service/salt-minion.md b/docs/configuration/service/salt-minion.md
new file mode 100644
index 00000000..e6f99752
--- /dev/null
+++ b/docs/configuration/service/salt-minion.md
@@ -0,0 +1,51 @@
+(saltminion)=
+
+# Salt-Minion
+
+[SaltStack] is Python-based, open-source
+software for event-driven IT automation, remote task execution, and
+configuration management. Supporting the "infrastructure as code"
+approach to data center system and network deployment and management,
+configuration automation, SecOps orchestration, vulnerability remediation,
+and hybrid cloud control.
+
+## Requirements
+
+To use the Salt-Minion, a running Salt-Master is required. You can find more
+in the [Salt Project Documentation](https://docs.saltproject.io/en/latest/contents.html)
+
+## Configuration
+
+```{cfgcmd} set service salt-minion hash \<type\>
+
+   The hash type used when discovering file on master server (default: sha256)
+```
+
+
+```{cfgcmd} set service salt-minion id \<id\>
+
+Explicitly declare ID for this minion to use (default: hostname)
+```
+
+
+```{cfgcmd} set service salt-minion interval \<1-1440\>
+
+Interval in minutes between updates (default: 60)
+```
+
+
+```{cfgcmd} set service salt-minion master \<hostname | IP\>
+
+The hostname or IP address of the master
+```
+
+
+```{cfgcmd} set service salt-minion master-key \<key\>
+
+URL with signature of master for auth reply verification
+```
+
+Please take a look in the Automation section to find some usefull
+Examples.
+
+[saltstack]: https://saltproject.io/
diff --git a/docs/configuration/service/snmp.md b/docs/configuration/service/snmp.md
new file mode 100644
index 00000000..ac0429ff
--- /dev/null
+++ b/docs/configuration/service/snmp.md
@@ -0,0 +1,258 @@
+(snmp)=
+
+# SNMP
+
+{abbr}`SNMP (Simple Network Management Protocol)` is an Internet Standard
+protocol for collecting and organizing information about managed devices on
+IP networks and for modifying that information to change device behavior.
+Devices that typically support SNMP include cable modems, routers, switches,
+servers, workstations, printers, and more.
+
+SNMP is widely used in network management for network monitoring. SNMP exposes
+management data in the form of variables on the managed systems organized in
+a management information base ([MIB]) which describe the system status and
+configuration. These variables can then be remotely queried (and, in some
+circumstances, manipulated) by managing applications.
+
+Three significant versions of SNMP have been developed and deployed. SNMPv1 is
+the original version of the protocol. More recent versions, SNMPv2c and SNMPv3,
+feature improvements in performance, flexibility and security.
+
+SNMP is a component of the Internet Protocol Suite as defined by the Internet
+Engineering Task Force (IETF). It consists of a set of standards for network
+management, including an application layer protocol, a database schema, and a
+set of data objects.
+
+## Overview and basic concepts
+
+In typical uses of SNMP, one or more administrative computers called managers
+have the task of monitoring or managing a group of hosts or devices on a
+computer network. Each managed system executes a software component called an
+agent which reports information via SNMP to the manager.
+
+An SNMP-managed network consists of three key components:
+
+- Managed devices
+- Agent - software which runs on managed devices
+- Network management station (NMS) - software which runs on the manager
+
+A managed device is a network node that implements an SNMP interface that
+allows unidirectional (read-only) or bidirectional (read and write) access to
+node-specific information. Managed devices exchange node-specific information
+with the NMSs. Sometimes called network elements, the managed devices can be
+any type of device, including, but not limited to, routers, access servers,
+switches, cable modems, bridges, hubs, IP telephones, IP video cameras,
+computer hosts, and printers.
+
+An agent is a network-management software module that resides on a managed
+device. An agent has local knowledge of management information and translates
+that information to or from an SNMP-specific form.
+
+A network management station executes applications that monitor and control
+managed devices. NMSs provide the bulk of the processing and memory resources
+required for network management. One or more NMSs may exist on any managed
+network.
+
+:::{figure} /_static/images/service_snmp_communication_principles_diagram.webp
+:alt: Principle of SNMP Communication
+:scale: 20 %
+
+Image thankfully borrowed from
+<https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG>
+which is under the GNU Free Documentation License
+:::
+
+:::{note}
+VyOS SNMP supports both IPv4 and IPv6.
+:::
+
+## SNMP Protocol Versions
+
+VyOS itself supports [SNMPv2] (version 2) and [SNMPv3] (version 3) where the
+later is recommended because of improved security (optional authentication and
+encryption).
+
+### SNMPv2
+
+SNMPv2 is the original and most commonly used version. For authorizing clients,
+SNMP uses the concept of communities. Communities may have authorization set
+to read only (this is most common) or to read and write (this option is not
+actively used in VyOS).
+
+SNMP can work synchronously or asynchronously. In synchronous communication,
+the monitoring system queries the router periodically. In asynchronous, the
+router sends notification to the "trap" (the monitoring host).
+
+SNMPv2 does not support any authentication mechanisms, other than client source
+address, so you should specify addresses of clients allowed to monitor the
+router. Note that SNMPv2 also supports no encryption and always sends data in
+plain text.
+
+#### Example
+
+```none
+# Define a community
+set service snmp community routers authorization ro
+
+# Allow monitoring access from the entire network
+set service snmp community routers network 192.0.2.0/24
+set service snmp community routers network 2001::db8:ffff:eeee::/64
+
+# Allow monitoring access from specific addresses
+set service snmp community routers client 203.0.113.10
+set service snmp community routers client 203.0.113.20
+
+# Define optional router information
+set service snmp location "UK, London"
+set service snmp contact "admin@example.com"
+
+# Trap target if you want asynchronous communication
+set service snmp trap-target 203.0.113.10
+
+# Listen only on specific IP addresses (port defaults to 161)
+set service snmp listen-address 172.16.254.36 port 161
+set service snmp listen-address 2001:db8::f00::1
+```
+
+
+### SNMPv3
+
+SNMPv3 (version 3 of the SNMP protocol) introduced a whole slew of new security
+related features that have been missing from the previous versions. Security
+was one of the biggest weakness of SNMP until v3. Authentication in SNMP
+Versions 1 and 2 amounts to nothing more than a password (community string)
+sent in clear text between a manager and agent. Each SNMPv3 message contains
+security parameters which are encoded as an octet string. The meaning of these
+security parameters depends on the security model being used.
+
+The security approach in SNMPv3 targets:
+
+- Confidentiality – Encryption of packets to prevent snooping by an
+  unauthorized source.
+- Integrity – Message integrity to ensure that a packet has not been tampered
+  while in transit including an optional packet replay protection mechanism.
+- Authentication – to verify that the message is from a valid source.
+
+(snmp-v3-example)=
+
+#### Example
+
+- Let SNMP daemon listen only on IP address 192.0.2.1
+- Configure new SNMP user named "vyos" with password "vyos12345678"
+- New user will use SHA/AES for authentication and privacy
+
+```none
+set service snmp listen-address 192.0.2.1
+set service snmp location 'VyOS Datacenter'
+set service snmp v3 engineid '000000000000000000000002'
+set service snmp v3 group default mode 'ro'
+set service snmp v3 group default view 'default'
+set service snmp v3 user vyos auth plaintext-password 'vyos12345678'
+set service snmp v3 user vyos auth type 'sha'
+set service snmp v3 user vyos group 'default'
+set service snmp v3 user vyos privacy plaintext-password 'vyos12345678'
+set service snmp v3 user vyos privacy type 'aes'
+set service snmp v3 view default oid 1
+```
+
+After commit the plaintext passwords will be hashed and stored in your
+configuration. The resulting CLI config will look like:
+
+```none
+vyos@vyos# show service snmp
+ listen-address 192.0.2.1 {
+ }
+ location "VyOS Datacenter"
+ v3 {
+     engineid 000000000000000000000002
+     group default {
+         mode ro
+         view default
+     }
+     user vyos {
+         auth {
+             encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe
+             type sha
+         }
+         group default
+         privacy {
+             encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe
+             type aes
+         }
+     }
+     view default {
+         oid 1 {
+         }
+     }
+ }
+```
+
+You can test the SNMPv3 functionality from any linux based system, just run the
+following command: `snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES
+-X vyos12345678 -l authPriv 192.0.2.1 .1`
+
+## VyOS MIBs
+
+All SNMP MIBs are located in each image of VyOS here: `/usr/share/snmp/mibs/`
+
+You are be able to download the files using SCP, once the SSH service
+has been activated like so
+
+```none
+scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs
+```
+
+
+## SNMP Extensions
+
+To extend SNMP agent functionality, custom scripts can be executed every time
+the agent is being called. This can be achieved by using
+`arbitrary extensioncommands`. The first step is to create a functional
+script of course, then upload it to your VyOS instance via the command
+`scp your_script.sh vyos@your_router:/config/user-data`.
+Once the script is uploaded, it needs to be configured via the command below.
+
+```none
+set service snmp script-extensions extension-name my-extension script your_script.sh
+commit
+```
+
+The OID `.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116`, once called, will
+contain the output of the extension.
+
+```none
+root@vyos:/home/vyos# snmpwalk -v2c  -c public 127.0.0.1 nsExtendOutput1
+NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello
+NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello
+NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1
+NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0
+```
+
+
+## SolarWinds
+
+If you happen to use SolarWinds Orion as NMS you can also use the Device
+Templates Management. A template for VyOS can be easily imported.
+
+Create a file named `VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands` using the
+following content:
+
+```none
+<Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641">
+    <Commands>
+        <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/>
+        <Command Name="Reboot" Value="reboot${CRLF}Yes"/>
+        <Command Name="EnterConfigMode" Value="configure"/>
+        <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/>
+        <Command Name="DownloadConfig" Value="show configuration commands"/>
+        <Command Name="SaveConfig" Value="commit${CRLF}save"/>
+        <Command Name="Version" Value="show version"/>
+        <Command Name="MenuBased" Value="False"/>
+        <Command Name="VirtualPrompt" Value=":~"/>
+    </Commands>
+</Configuration-Management>
+```
+
+[mib]: <https://en.wikipedia.org/wiki/Management_information_base>
+[snmpv2]: <https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2>
+[snmpv3]: <https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3>
diff --git a/docs/configuration/service/ssh.md b/docs/configuration/service/ssh.md
new file mode 100644
index 00000000..d873cbee
--- /dev/null
+++ b/docs/configuration/service/ssh.md
@@ -0,0 +1,366 @@
+(ssh)=
+
+# SSH
+
+{abbr}`SSH (Secure Shell)` is a cryptographic network protocol for operating
+network services securely over an unsecured network. The standard TCP port for
+SSH is 22. The best known example application is for remote login to computer
+systems by users.
+
+SSH provides a secure channel over an unsecured network in a client-server
+architecture, connecting an SSH client application with an SSH server. Common
+applications include remote command-line login and remote command execution,
+but any network service can be secured with SSH. The protocol specification
+distinguishes between two major versions, referred to as SSH-1 and SSH-2.
+
+The most visible application of the protocol is for access to shell accounts
+on Unix-like operating systems, but it sees some limited use on Windows as
+well. In 2015, Microsoft announced that they would include native support for
+SSH in a future release.
+
+SSH was designed as a replacement for Telnet and for unsecured remote shell
+protocols such as the Berkeley rlogin, rsh, and rexec protocols.
+Those protocols send information, notably passwords, in plaintext,
+rendering them susceptible to interception and disclosure using packet
+analysis. The encryption used by SSH is intended to provide confidentiality
+and integrity of data over an unsecured network, such as the Internet.
+
+:::{note}
+VyOS 1.1 supported login as user `root`. This has been removed due
+to tighter security in VyOS 1.2.
+:::
+
+:::{seealso}
+SSH {ref}`ssh_key_based_authentication`
+:::
+
+## Configuration
+
+```{cfgcmd} set service ssh port \<port\>
+
+Enabling SSH only requires you to specify the port ``<port>`` you want SSH to
+listen on. By default, SSH runs on port 22.
+```
+
+
+```{cfgcmd} set service ssh listen-address \<address\>
+
+Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be
+defined.
+```
+
+
+```{cfgcmd} set service ssh cipher \<cipher\>
+
+Define allowed ciphers used for the SSH connection. A number of allowed
+ciphers can be specified, use multiple occurrences to allow multiple ciphers.
+
+List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``,
+``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``,
+``aes128-gcm@openssh.com``, ``aes256-gcm@openssh.com``,
+``chacha20-poly1305@openssh.com``
+```
+
+
+```{cfgcmd} set service ssh disable-password-authentication
+
+Disable password based authentication. Login via SSH keys only. This hardens
+security!
+```
+
+
+```{cfgcmd} set service ssh fido pin-required
+
+Require FIDO2 keys to attest that a user has been verified (e.g. via a PIN).
+```
+
+
+````{cfgcmd} set service ssh fido touch-required
+
+Require FIDO2 keys to attest that a user is physically present.
+
+VyOS supports SSH authentication using FIDO2-backed keys generated by OpenSSH.
+Two FIDO2 key types are supported by OpenSSH: ``ed25519-sk``, ``ecdsa-sk``
+
+Generic FIDO2-backed SSH key generation example:
+
+:::{code-block} none
+ssh-keygen -t ecdsa-sk -O verify-required -C "fido2-ssh-key"
+:::
+
+```{eval-rst}
+During key generation, OpenSSH will:
+    * Request user presence (for example, a physical touch or confirmation)
+    * Optionally request user verification (PIN), if supported by the authenticator
+    * Create a local key handle file and a corresponding public key (``.pub``)
+```
+
+The private key material never leaves the authenticator device.
+
+VyOS configuration example:
+
+:::{code-block} none
+# Generate a FIDO2 SSH key on the client system
+# Copy the public key to the VyOS instance
+set system login user vyos authentication public-keys fido key '<public-key>'
+set system login user vyos authentication public-keys fido type 'sk-ecdsa-sha2-nistp256@openssh.com'
+set service ssh fido touch-required
+:::
+
+You can now log into the system using: ``ssh -i ~/.ssh/id_fido_key vyos@192.0.2.1``
+````
+
+
+```{cfgcmd} set service ssh disable-host-validation
+
+Disable the host validation through reverse DNS lookups - can speedup login
+time when reverse lookup is not possible.
+```
+
+
+```{cfgcmd} set service ssh mac \<mac\>
+
+Specifies the available {abbr}`MAC (Message Authentication Code)` algorithms.
+The MAC algorithm is used in protocol version 2 for data integrity protection.
+Multiple algorithms can be provided by using multiple commands, defining
+one algorithm per command.
+
+List of supported MACs: ``hmac-md5``, ``hmac-md5-96``, ``hmac-ripemd160``,
+``hmac-sha1``, ``hmac-sha1-96``, ``hmac-sha2-256``, ``hmac-sha2-512``,
+``umac-64@openssh.com``, ``umac-128@openssh.com``,
+``hmac-md5-etm@openssh.com``, ``hmac-md5-96-etm@openssh.com``,
+``hmac-ripemd160-etm@openssh.com``, ``hmac-sha1-etm@openssh.com``,
+``hmac-sha1-96-etm@openssh.com``, ``hmac-sha2-256-etm@openssh.com``,
+``hmac-sha2-512-etm@openssh.com``, ``umac-64-etm@openssh.com``,
+``umac-128-etm@openssh.com``
+```
+
+
+```{cfgcmd} set service ssh access-control \<allow | deny\> \<group | user\> \<name\>
+
+Add access-control directive to allow or deny users and groups. Directives
+are processed in the following order of precedence: ``deny-users``,
+``allow-users``, ``deny-groups`` and ``allow-groups``.
+```
+
+
+```{cfgcmd} set service ssh client-keepalive-interval \<interval\>
+
+Specify timeout interval for keepalive message in seconds.
+```
+
+
+```{cfgcmd} set service ssh key-exchange \<kex\>
+
+Specify allowed {abbr}`KEX (Key Exchange)` algorithms.
+
+List of supported algorithms: ``diffie-hellman-group1-sha1``,
+``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``,
+``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``,
+``diffie-hellman-group-exchange-sha1``,
+``diffie-hellman-group-exchange-sha256``,
+``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``,
+``curve25519-sha256`` and ``curve25519-sha256@libssh.org``.
+```
+
+
+```{cfgcmd} set service ssh loglevel \<quiet | fatal | error | info | verbose\>
+
+Set the ``sshd`` log level. The default is ``info``.
+```
+
+
+```{cfgcmd} set service ssh vrf \<name\>
+
+Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+
+```{cfgcmd} set service ssh pubkey-accepted-algorithm \<name\>
+
+Specifies the signature algorithms that will be accepted for public key
+authentication
+
+List of supported algorithms: ``ssh-ed25519``,
+``ssh-ed25519-cert-v01@openssh.com``, ``sk-ssh-ed25519@openssh.com``,
+``sk-ssh-ed25519-cert-v01@openssh.com``, ``ecdsa-sha2-nistp256``,
+``ecdsa-sha2-nistp256-cert-v01@openssh.com``, ``ecdsa-sha2-nistp384``,
+``ecdsa-sha2-nistp384-cert-v01@openssh.com``, ``ecdsa-sha2-nistp521``,
+``ecdsa-sha2-nistp521-cert-v01@openssh.com``,
+``sk-ecdsa-sha2-nistp256@openssh.com``,
+``sk-ecdsa-sha2-nistp256-cert-v01@openssh.com``,
+``webauthn-sk-ecdsa-sha2-nistp256@openssh.com``,
+``ssh-dss``, ``ssh-dss-cert-v01@openssh.com``, ``ssh-rsa``,
+``ssh-rsa-cert-v01@openssh.com``, ``rsa-sha2-256``,
+``rsa-sha2-256-cert-v01@openssh.com``, ``rsa-sha2-512``,
+``rsa-sha2-512-cert-v01@openssh.com``
+```
+
+
+```{cfgcmd} set service ssh trusted-user-ca \<name\>
+
+Specify the name of the OpenSSH key-pair that acts as certificate authority
+and will be used to verify user certificates.
+
+You can use it by adding the OpenSSH key-pair under the PKI subsystem.
+
+Example:
+
+:::{code-block} none
+# Generate key-pair acting as CA
+$ ssh-keygen -f vyos-ssh-ca.key
+
+# Generate key for user: vyos_testca
+$ ssh-keygen -f vyos_testca  -C "vyos_tesca@vyos.net"
+
+# Sign public key from user vyos_testca and insert principal names: vyos, vyos_testca
+# with a key lifetime of two weeks - after which the key is unusable
+$ ssh-keygen -s vyos-ssh-ca.key -I vyos_testca@vyos.net -n vyos,vyos_testca -V +2w vyos_testca.pub
+
+$ set system login user vyos_testca
+$ set pki openssh test_ca public key AAAAB3N.....
+$ set pki openssh test_ca public type ssh-rsa
+$ set service ssh trusted-user-ca test_ca
+:::
+You can now log into the system using: ``ssh -i vyos_testca vyos_testca@vyos.test.com``
+```
+
+## Dynamic-protection
+
+Protects host from brute-force attacks against
+SSH. Log messages are parsed, line-by-line, for recognized patterns. If an
+attack, such as several login failures within a few seconds, is detected, the
+offending IP is blocked. Offenders are unblocked after a set interval.
+
+```{cfgcmd} set service ssh dynamic-protection
+
+Allow ``ssh`` dynamic-protection.
+```
+```{cfgcmd} set service ssh dynamic-protection allow-from \<address | prefix\>
+
+Whitelist of addresses and networks. Always allow inbound connections from
+these systems.
+```
+```{cfgcmd} set service ssh dynamic-protection block-time \<sec\>
+
+Block source IP in seconds. Subsequent blocks increase by a factor of 1.5
+The default is 120.
+```
+```{cfgcmd} set service ssh dynamic-protection detect-time \<sec\>
+
+Remember source IP in seconds before reset their score. The default is 1800.
+```
+```{cfgcmd} set service ssh dynamic-protection threshold \<sec\>
+
+Block source IP when their cumulative attack score exceeds threshold. The
+default is 30.
+```
+
+(ssh-operation)=
+
+## Operation
+
+```{opcmd} restart ssh
+
+Restart the SSH daemon process, the current session is not affected, only the
+background daemon is restarted.
+```
+```{opcmd} generate ssh server-key
+
+Re-generated the public/private keyportion which SSH uses to secure
+connections.
+
+:::{note}
+Already learned known_hosts files of clients need an update as the
+public key will change.
+:::
+```
+```{opcmd} generate ssh client-key /path/to/private_key
+
+Re-generated a known pub/private keyfile which can be used to connect to
+other services (e.g. RPKI cache).
+
+Example:
+
+:::{code-block} none
+vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki
+Generating public/private rsa key pair.
+Your identification has been saved in /config/auth/id_rsa_rpki.
+Your public key has been saved in /config/auth/id_rsa_rpki.pub.
+The key fingerprint is:
+SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q vyos@vyos
+The key's randomart image is:
++---[RSA 2048]----+
+|         oo      |
+|          ..o    |
+|       . o.o.. o.|
+|       o+ooo  o.o|
+|        Eo*  =.o |
+|       o = +.o*+ |
+|        = o *.o.o|
+|       o * +.o+.+|
+|        =.. o=.oo|
++----[SHA256]-----+
+:::
+Two new files ``/config/auth/id_rsa_rpki`` and
+``/config/auth/id_rsa_rpki.pub``
+will be created.
+```
+```{opcmd} generate public-key-command user \<username\> path \<location\>
+
+> Generate the configuration mode commands to add a public key for
+> {ref}`ssh_key_based_authentication`.
+> ``<location>`` can be a local path or a URL pointing at a remote file.
+>
+> Supported remote protocols are FTP, FTPS, HTTP, HTTPS, SCP/SFTP and TFTP.
+
+Example:
+
+:::{code-block} none
+alyssa@vyos:~$ generate public-key-command user alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub
+# To add this key as an embedded key, run the following commands:
+configure
+set system login user alyssa authentication public-keys alyssa@example.net key AAA...
+set system login user alyssa authentication public-keys alyssa@example.net type ssh-rsa
+commit
+save
+exit
+
+ben@vyos:~$ generate public-key-command user ben path ~/.ssh/id_rsa.pub
+# To add this key as an embedded key, run the following commands:
+configure
+set system login user ben authentication public-keys ben@vyos key AAA...
+set system login user ben authentication public-keys ben@vyos type ssh-dss
+commit
+save
+exit
+:::
+```
+```{opcmd} show log ssh
+
+Show SSH server log.
+```
+```{opcmd} monitor log ssh
+
+Follow the SSH server log.
+```
+```{opcmd} show log ssh dynamic-protection
+
+Show SSH dynamic-protection log.
+```
+```{opcmd} monitor log ssh dynamic-protection
+
+Follow the SSH dynamic-protection log.
+```
+```{opcmd} show ssh dynamic-protection
+
+Show list of IPs currently blocked by SSH dynamic-protection.
+```
+```{opcmd} show ssh fingerprints
+
+Show SSH server public key fingerprints.
+```
+```{opcmd} show ssh fingerprints ascii
+
+Show SSH server public key fingerprints, including a visual ASCII art representation.
+```
\ No newline at end of file
diff --git a/docs/configuration/service/suricata.md b/docs/configuration/service/suricata.md
new file mode 100644
index 00000000..ca9ae968
--- /dev/null
+++ b/docs/configuration/service/suricata.md
@@ -0,0 +1,93 @@
+(suricata)=
+
+# suricata
+
+Suricata and VyOS are powerful tools for ensuring network security and traffic management.
+Suricata is an open-source intrusion detection and prevention system (IDS/IPS) that analyzes network packets in real-time.
+
+## Suricata Features
+
+Intrusion Detection (IDS): Analyzes network traffic and detects suspicious activities, attacks, and malicious traffic.
+Intrusion Prevention (IPS): Blocks or modifies suspicious traffic in real-time, preventing attacks before they penetrate the network.
+Network Security Monitoring (NSM): Collects and analyzes network data to detect anomalies and identify threats.
+Multi-Protocol Support: Suricata supports analysis of various network protocols such as HTTP, FTP, SMB, and many others.
+In configuration mode, the commands are as follows:
+
+```none
+vyos@vyos# set service suricata
+Possible completions:
++> address-group        Address group name
++  interface            Interface to use
+ > log                  Suricata log outputs
++> port-group           Port group name
+```
+
+These commands create a flexible interface for configuring the Suricata service, allowing users to specify addresses, ports,
+and logging parameters.
+
+After completing the service configuration in configuration mode, the main configuration file suricata.yaml is created,
+into which all specified parameters are added. Then, to ensure proper operation, the command {opcmd}`update suricata` must be run
+from operational mode, waiting for Suricata to update all its rules, which are used for analyzing traffic for threats and attacks.
+
+## Configuration
+
+```{cfgcmd} set service suricata address-group \<text\> \<address | group\>
+
+   Address groups are useful when you need to create rules that apply to specific IP addresses.
+   For example, if you want to create a rule that monitors traffic going to or from a specific IP address,
+   you can use the group name instead of the actual IP address. This simplifies rule management and makes the
+   configuration more flexible.
+
+   * ``address`` IP address or subnet.
+
+   * ``group``  Address group.
+```
+
+
+```{cfgcmd} set service suricata port-group \<text\> \<address | group\>
+
+Port groups are useful when you need to create rules that apply to specific ports.
+For example, if you want to create a rule that monitors traffic directed to a specific port or group of ports,
+you can use the group name instead of the actual port. This also simplifies rule management and makes
+the configuration more flexible.
+
+* ``port``  Port number.
+
+* ``group``  Port group.
+```
+
+
+```{cfgcmd} set service suricata interface \<text\>
+
+The interface that will be monitored by the Suricata service.
+```
+```{cfgcmd} set service suricata log eve \<filename | filetype | type\>
+
+   Configuration of the logging file.
+
+   * ``filename``  Log file (default: eve.json).
+
+   * ``filetype``  EVE logging destination (default: regular).
+
+   * ``type``  Log types.
+```
+
+## Operation Mode
+
+```{cfgcmd} update suricata
+
+Checks for the existence of the Suricata configuration file, updates the service,
+and then restarts it. If the configuration file is not found, a message indicates that Suricata is not configured.
+```
+```{cfgcmd} restart suricata
+
+Restarts the service. It checks if the Suricata service is active before attempting to restart it.
+If it is not active, a message indicates that the service is not configured. This command is used when adding new rules manually.
+```
+
+## Conclusion
+
+Using address and port groups allows you to make your Suricata configuration more flexible and manageable.
+Instead of specifying IP addresses and ports directly in each rule, you can define them once in the vars section and then
+reference them by group names. This is especially useful in large networks and complex configurations where multiple IP addresses
+and ports need to be monitored.
diff --git a/docs/configuration/service/tftp-server.md b/docs/configuration/service/tftp-server.md
new file mode 100644
index 00000000..f4a6c34c
--- /dev/null
+++ b/docs/configuration/service/tftp-server.md
@@ -0,0 +1,78 @@
+(tftp-server)=
+
+# TFTP Server
+
+{abbr}`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file
+transfer protocol which allows a client to get a file from or put a file onto
+a remote host. One of its primary uses is in the early stages of nodes booting
+from a local area network. TFTP has been used for this application because it
+is very simple to implement.
+
+## Configuration
+
+```{cfgcmd} set service tftp-server directory \<directory\>
+
+Enable TFTP service by specifying the `<directory>` which will be used to serve
+files.
+```
+
+:::{hint}
+Choose your `directory` location carefully or you will loose the
+content on image upgrades. Any directory under `/config` is save at this
+will be migrated.
+:::
+
+```{cfgcmd} set service tftp-server listen-address \<address\>
+
+Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and
+IPv6 addresses can be given. There will be one TFTP server instances listening
+on each IP address.
+```
+
+```{cfgcmd} set service tftp-server listen-address \<address\> vrf \<name\>
+```
+
+Additional option to run TFTP server in the {abbr}`VRF (Virtual Routing and Forwarding)` context
+
+:::{note}
+Configuring a listen-address is essential for the service to work.
+:::
+```{cfgcmd} set service tftp-server allow-upload
+
+Optional, if you want to enable uploads, else TFTP server will act as a
+read-only server.
+```
+
+### Example
+
+Provide TFTP server listening on both IPv4 and IPv6 addresses `192.0.2.1` and
+`2001:db8::1` serving the content from `/config/tftpboot`. Uploading via
+TFTP to this server is disabled.
+
+The resulting configuration will look like:
+
+```none
+vyos@vyos# show service
+ tftp-server {
+    directory /config/tftpboot
+    listen-address 2001:db8::1
+    listen-address 192.0.2.1
+ }
+```
+
+### Verification
+
+Client:
+
+```none
+vyos@RTR2:~$ tftp -p -l /config/config.boot -r backup 192.0.2.1
+backup1             100% |******************************|   723  0:00:00 ETA
+```
+
+Server:
+
+```none
+vyos@RTR1# ls -ltr /config/tftpboot/
+total 1
+-rw-rw-rw- 1 tftp tftp  1995 May 19 16:02 backup
+```
diff --git a/docs/configuration/service/webproxy.md b/docs/configuration/service/webproxy.md
new file mode 100644
index 00000000..28156b2b
--- /dev/null
+++ b/docs/configuration/service/webproxy.md
@@ -0,0 +1,459 @@
+(webproxy)=
+
+# Webproxy
+
+The proxy service in VyOS is based on [Squid] and some related modules.
+
+[Squid] is a caching and forwarding HTTP web proxy. It has a wide variety of
+uses, including speeding up a web server by caching repeated requests, caching
+web, DNS and other computer network lookups for a group of people sharing
+network resources, and aiding security by filtering traffic. Although primarily
+used for HTTP and FTP, Squid includes limited support for several other
+protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does not
+support the SOCKS protocol.
+
+URL Filtering is provided by [SquidGuard].
+
+## Configuration
+
+```{cfgcmd} set service webproxy append-domain \<domain\>
+
+Use this command to specify a domain name to be appended to domain-names
+within URLs that do not include a dot ``.`` the domain is appended.
+
+Example: to be appended is set to ``vyos.net`` and the URL received is
+``www/foo.html``, the system will use the generated, final URL of
+``www.vyos.net/foo.html``.
+
+:::{code-block} none
+set service webproxy append-domain vyos.net
+:::
+```
+
+
+```{cfgcmd} set service webproxy cache-size \<size\>
+
+The size of the on-disk Proxy cache is user configurable. The Proxies default
+cache-size is configured to 100 MB.
+
+Unit of this command is MB.
+
+:::{code-block} none
+set service webproxy cache-size 1024
+:::
+```
+
+
+```{cfgcmd} set service webproxy default-port \<port\>
+
+Specify the port used on which the proxy service is listening for requests.
+This port is the default port used for the specified listen-address.
+
+Default port is 3128.
+
+:::{code-block} none
+set service webproxy default-port 8080
+:::
+```
+
+
+```{cfgcmd} set service webproxy domain-block \<domain\>
+
+Used to block specific domains by the Proxy. Specifying "vyos.net" will block
+all access to vyos.net, and specifying ".xxx" will block all access to URLs
+having an URL ending on .xxx.
+
+:::{code-block} none
+set service webproxy domain-block vyos.net
+:::
+```
+
+
+```{cfgcmd} set service webproxy domain-noncache \<domain\>
+
+Allow access to sites in a domain without retrieving them from the Proxy
+cache. Specifying "vyos.net" will allow access to vyos.net but the pages
+accessed will not be cached. It useful for working around problems with
+"If-Modified-Since" checking at certain sites.
+
+:::{code-block} none
+set service webproxy domain-noncache vyos.net
+:::
+```
+
+
+```{cfgcmd} set service webproxy listen-address \<address\>
+
+Specifies proxy service listening address. The listen address is the IP
+address on which the web proxy service listens for client requests.
+
+For security, the listen address should only be used on internal/trusted
+networks!
+
+:::{code-block} none
+set service webproxy listen-address 192.0.2.1
+:::
+```
+
+
+```{cfgcmd} set service webproxy listen-address \<address\> disable-transparent
+
+Disables web proxy transparent mode at a listening address.
+
+In transparent proxy mode, all traffic arriving on port 80 and destined for
+the Internet is automatically forwarded through the proxy. This allows
+immediate proxy forwarding without configuring client browsers.
+
+Non-transparent proxying requires that the client browsers be configured with
+the proxy settings before requests are redirected. The advantage of this is
+that the client web browser can detect that a proxy is in use and can behave
+accordingly. In addition, web-transmitted malware can sometimes be blocked by
+a non-transparent web proxy, since they are not aware of the proxy settings.
+
+:::{code-block} none
+set service webproxy listen-address 192.0.2.1 disable-transparent
+:::
+```
+
+
+```{cfgcmd} set service webproxy listen-address \<address\> port \<port\>
+
+Sets the listening port for a listening address. This overrides the default
+port of 3128 on the specific listen address.
+
+:::{code-block} none
+set service webproxy listen-address 192.0.2.1 port 8080
+:::
+```
+```{cfgcmd} set service webproxy reply-block-mime \<mime\>
+
+Used to block a specific mime-type.
+
+:::{code-block} none
+# block all PDFs
+set service webproxy reply-block-mime application/pdf
+:::
+```
+```{cfgcmd} set service webproxy reply-body-max-size \<size\>
+
+Specifies the maximum size of a reply body in KB, used to limit the reply
+size.
+
+All reply sizes are accepted by default.
+
+:::{code-block} none
+set service webproxy reply-body-max-size 2048
+:::
+```
+
+
+```{cfgcmd} set service webproxy safe-ports \<port\>
+
+Add new port to Safe-ports acl. Ports included by default in Safe-ports acl:
+21, 70, 80, 210, 280, 443, 488, 591, 777, 873, 1025-65535
+```
+
+
+```{cfgcmd} set service webproxy ssl-safe-ports \<port\>
+
+Add new port to SSL-ports acl. Ports included by default in SSL-ports acl:
+443
+```
+
+### Authentication
+
+The embedded Squid proxy can use LDAP to authenticate users against a company
+wide directory. The following configuration is an example of how to use Active
+Directory as authentication backend. Queries are done via LDAP.
+
+```{cfgcmd} set service webproxy authentication children \<number\>
+
+Maximum number of authenticator processes to spawn. If you start too few
+Squid will have to wait for them to process a backlog of credential
+verifications, slowing it down. When password verifications are done via a
+(slow) network you are likely to need lots of authenticator processes.
+
+This defaults to 5.
+
+:::{code-block} none
+set service webproxy authentication children 10
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication credentials-ttl \<time\>
+
+Specifies how long squid assumes an externally validated username:password
+pair is valid for - in other words how often the helper program is called for
+that user. Set this low to force revalidation with short lived passwords.
+
+Time is in minutes and defaults to 60.
+
+:::{code-block} none
+set service webproxy authentication credentials-ttl 120
+:::
+```
+```{cfgcmd} set service webproxy authentication method \<ldap\>
+
+Proxy authentication method, currently only LDAP is supported.
+
+:::{code-block} none
+set service webproxy authentication method ldap
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication realm
+
+Specifies the protection scope (aka realm name) which is to be reported to
+the client for the authentication scheme. It is commonly part of the text
+the user will see when prompted for their username and password.
+
+:::{code-block} none
+set service webproxy authentication realm "VyOS proxy auth"
+:::
+```
+
+#### LDAP
+
+```{cfgcmd} set service webproxy authentication ldap base-dn \<base-dn\>
+
+Specifies the base DN under which the users are located.
+
+:::{code-block} none
+set service webproxy authentication ldap base-dn DC=vyos,DC=net
+:::
+```
+```{cfgcmd} set service webproxy authentication ldap bind-dn \<bind-dn\>
+
+The DN and password to bind as while performing searches.
+
+:::{code-block} none
+set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap filter-expression \<expr\>
+
+LDAP search filter to locate the user DN. Required if the users are in a
+hierarchy below the base DN, or if the login name is not what builds the user
+specific part of the users DN.
+
+The search filter can contain up to 15 occurrences of %s which will be
+replaced by the username, as in "uid=%s" for {rfc}`2037` directories. For a
+detailed description of LDAP search filter syntax see {rfc}`2254`.
+
+:::{code-block} none
+set service webproxy authentication ldap filter-expression (cn=%s)
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap password \<password\>
+
+The DN and password to bind as while performing searches. As the password
+needs to be printed in plain text in your Squid configuration it is strongly
+recommended to use a account with minimal associated privileges. This to limit
+the damage in case someone could get hold of a copy of your Squid
+configuration file.
+
+:::{code-block} none
+set service webproxy authentication ldap password vyos
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap persistent-connection
+
+Use a persistent LDAP connection. Normally the LDAP connection is only open
+while validating a username to preserve resources at the LDAP server. This
+option causes the LDAP connection to be kept open, allowing it to be reused
+for further user validations.
+
+Recommended for larger installations.
+
+:::{code-block} none
+set service webproxy authentication ldap persistent-connection
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap port \<port\>
+
+Specify an alternate TCP port where the ldap server is listening if other than
+the default LDAP port 389.
+
+:::{code-block} none
+set service webproxy authentication ldap port 389
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap server \<server\>
+
+Specify the LDAP server to connect to.
+
+:::{code-block} none
+set service webproxy authentication ldap server ldap.vyos.net
+:::
+```
+```{cfgcmd} set service webproxy authentication ldap use-ssl
+
+Use TLS encryption.
+
+:::{code-block} none
+set service webproxy authentication ldap use-ssl
+:::
+```
+```{cfgcmd} set service webproxy authentication ldap username-attribute \<attr\>
+
+Specifies the name of the DN attribute that contains the username/login.
+Combined with the base DN to construct the users DN when no search filter is
+specified (filter-expression).
+
+Defaults to 'uid'
+
+:::{note}
+This can only be done if all your users are located directly under
+the same position in the LDAP tree and the login name is used for naming
+each user object. If your LDAP tree does not match these criterias or if you
+want to filter who are valid users then you need to use a search filter to
+search for your users DN (filter-expression).
+:::
+
+:::{code-block} none
+set service webproxy authentication ldap username-attribute uid
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap version \<2 | 3\>
+
+LDAP protocol version. Defaults to 3 if not specified.
+
+:::{code-block} none
+set service webproxy authentication ldap version 2
+:::
+```
+
+### URL filtering
+
+```{include} /_include/need_improvement.txt
+```
+```{cfgcmd} set service webproxy url-filtering disable
+
+Disables web filtering without discarding configuration.
+
+:::{code-block} none
+set service webproxy url-filtering disable
+:::
+```
+
+## Operation
+
+```{include} /_include/need_improvement.txt
+```
+
+### Filtering
+#### Update
+
+If you want to use existing blacklists you have to create/download a database
+first. Otherwise you will not be able to commit the config changes.
+
+```{opcmd} update webproxy blacklists
+
+Download/Update complete blacklist
+
+:::{code-block} none
+vyos@vyos:~$ update webproxy blacklists
+Warning: No url-filtering blacklist installed
+Would you like to download a default blacklist? [confirm][y]
+Connecting to ftp.univ-tlse1.fr (193.49.48.249:21)
+blacklists.gz        100% |*************************************************************************************************************| 17.0M  0:00:00 ETA
+Uncompressing blacklist...
+Checking permissions...
+Skip link for   [ads] -> [publicite]
+Building DB for [adult/domains] - 2467177 entries
+Building DB for [adult/urls] - 67798 entries
+Skip link for   [aggressive] -> [agressif]
+Building DB for [agressif/domains] - 348 entries
+Building DB for [agressif/urls] - 36 entries
+Building DB for [arjel/domains] - 69 entries
+...
+Building DB for [webmail/domains] - 374 entries
+Building DB for [webmail/urls] - 9 entries
+The webproxy daemon must be restarted
+Would you like to restart it now? [confirm][y]
+[ ok ] Restarting squid (via systemctl): squid.service.
+vyos@vyos:~$
+:::
+```
+```{opcmd} update webproxy blacklists category \<category\>
+
+Download/Update partial blacklist.
+
+Use tab completion to get a list of categories.
+```
+
+- To auto update the blacklist files
+
+  `set service webproxy url-filtering squidguard auto-update update-hour 23`
+
+- To configure blocking add the following to the configuration
+
+  `set service webproxy url-filtering squidguard block-category ads`
+
+  `set service webproxy url-filtering squidguard block-category malware`
+
+#### Bypassing the webproxy
+
+```{include} /_include/need_improvement.txt
+```
+
+Some services don't work correctly when being handled via a web proxy.
+So sometimes it is useful to bypass a transparent proxy:
+
+- To bypass the proxy for every request that is directed to a specific
+  destination:
+
+  `set service webproxy whitelist destination-address 198.51.100.33`
+
+  `set service webproxy whitelist destination-address 192.0.2.0/24`
+
+- To bypass the proxy for every request that is coming from a specific source:
+
+  `set service webproxy whitelist source-address 192.168.1.2`
+
+  `set service webproxy whitelist source-address 192.168.2.0/24`
+
+  (This can be useful when a called service has many and/or often changing
+  destination addresses - e.g. Netflix.)
+
+## Examples
+
+```none
+vyos@vyos# show service webproxy
+ authentication {
+     children 5
+     credentials-ttl 60
+     ldap {
+         base-dn DC=example,DC=local
+         bind-dn CN=proxyuser,CN=Users,DC=example,DC=local
+         filter-expression (cn=%s)
+         password Qwert1234
+         server ldap.example.local
+         username-attribute cn
+     }
+     method ldap
+     realm "VyOS Webproxy"
+ }
+ cache-size 100
+ default-port 3128
+ listen-address 192.168.188.103 {
+     disable-transparent
+ }
+```
+
+[squid]: http://www.squid-cache.org/
+[squidguard]: http://www.squidguard.org/
diff --git a/docs/configuration/system/acceleration.md b/docs/configuration/system/acceleration.md
new file mode 100644
index 00000000..871129e6
--- /dev/null
+++ b/docs/configuration/system/acceleration.md
@@ -0,0 +1,158 @@
+(acceleration)=
+
+# Acceleration
+
+In this command tree, all hardware acceleration options will be handled.
+At the moment only [Intel® QAT] is supported
+
+## Intel® QAT
+
+```{opcmd} show system acceleration qat
+
+use this command to check if there is an Intel® QAT supported Processor in your system.
+
+:::{code-block} none
+vyos@vyos:~$ show system acceleration qat
+01:00.0 Co-processor [0b40]: Intel Corporation Atom Processor C3000 Series QuickAssist Technology [8086:19e2] (rev 11)
+:::
+
+if there is non device the command will show `` `No QAT device found` ``
+```
+
+```{cfgcmd} set system acceleration qat
+
+if there is a supported device, enable Intel® QAT
+```
+
+
+```{opcmd} show system acceleration qat status
+
+Check if the Intel® QAT device is up and ready to do the job.
+
+:::{code-block} none
+vyos@vyos:~$ show system acceleration qat status
+Checking status of all devices.
+There is 1 QAT acceleration device(s) in the system:
+qat_dev0 - type: c3xxx,  inst_id: 0,  node_id: 0,  bsf: 0000:01:00.0,  #accel: 3 #engines: 6 state: up
+:::
+```
+
+
+### Operation Mode
+
+```{opcmd} show system acceleration qat device \<device\> config
+
+Show the full config uploaded to the QAT device.
+```
+
+
+```{opcmd} show system acceleration qat device \<device\> flows
+
+Get an overview over the encryption counters.
+```
+
+
+```{opcmd} show system acceleration qat interrupts
+
+Show binded qat device interrupts to certain core.
+```
+
+
+### Example
+
+Let's build a simple VPN between 2 Intel® QAT ready devices.
+
+Side A:
+
+```
+set interfaces vti vti1 address '192.168.1.2/24'
+set vpn ipsec authentication psk right id '10.10.10.2'
+set vpn ipsec authentication psk right id '10.10.10.1'
+set vpn ipsec authentication psk right secret 'Qwerty123'
+set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256'
+set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256'
+set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14'
+set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256'
+set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256'
+set vpn ipsec interface 'eth0'
+set vpn ipsec site-to-site peer right authentication local-id '10.10.10.2'
+set vpn ipsec site-to-site peer right authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer right authentication remote-id '10.10.10.1'
+set vpn ipsec site-to-site peer right connection-type 'initiate'
+set vpn ipsec site-to-site peer right default-esp-group 'MyESPGroup'
+set vpn ipsec site-to-site peer right ike-group 'MyIKEGroup'
+set vpn ipsec site-to-site peer right local-address '10.10.10.2'
+set vpn ipsec site-to-site peer right remote-address '10.10.10.1'
+set vpn ipsec site-to-site peer right vti bind 'vti1'
+```
+
+Side B:
+
+```
+set interfaces vti vti1 address '192.168.1.1/24'
+set vpn ipsec authentication psk left id '10.10.10.2'
+set vpn ipsec authentication psk left id '10.10.10.1'
+set vpn ipsec authentication psk left secret 'Qwerty123'
+set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256'
+set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256'
+set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14'
+set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256'
+set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256'
+set vpn ipsec interface 'eth0'
+set vpn ipsec site-to-site peer left authentication local-id '10.10.10.1'
+set vpn ipsec site-to-site peer left authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer left authentication remote-id '10.10.10.2'
+set vpn ipsec site-to-site peer left connection-type 'initiate'
+set vpn ipsec site-to-site peer left default-esp-group 'MyESPGroup'
+set vpn ipsec site-to-site peer left ike-group 'MyIKEGroup'
+set vpn ipsec site-to-site peer left local-address '10.10.10.1'
+set vpn ipsec site-to-site peer left remote-address '10.10.10.2'
+set vpn ipsec site-to-site peer left vti bind 'vti1'
+```
+
+a bandwidth test over the VPN got these results:
+
+```
+Connecting to host 192.168.1.2, port 5201
+[  9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201
+[ ID] Interval           Transfer     Bitrate         Retr  Cwnd
+[  9]   0.00-1.01   sec  32.3 MBytes   268 Mbits/sec    0    196 KBytes
+[  9]   1.01-2.03   sec  32.5 MBytes   268 Mbits/sec    0    208 KBytes
+[  9]   2.03-3.03   sec  32.5 MBytes   271 Mbits/sec    0    208 KBytes
+[  9]   3.03-4.04   sec  32.5 MBytes   272 Mbits/sec    0    208 KBytes
+[  9]   4.04-5.00   sec  31.2 MBytes   272 Mbits/sec    0    208 KBytes
+[  9]   5.00-6.01   sec  32.5 MBytes   272 Mbits/sec    0    234 KBytes
+[  9]   6.01-7.04   sec  32.5 MBytes   265 Mbits/sec    0    234 KBytes
+[  9]   7.04-8.04   sec  32.5 MBytes   272 Mbits/sec    0    234 KBytes
+[  9]   8.04-9.04   sec  32.5 MBytes   273 Mbits/sec    0    336 KBytes
+[  9]   9.04-10.00  sec  31.2 MBytes   272 Mbits/sec    0    336 KBytes
+- - - - - - - - - - - - - - - - - - - - - - - - -
+[ ID] Interval           Transfer     Bitrate         Retr
+[  9]   0.00-10.00  sec   322 MBytes   270 Mbits/sec    0           sender
+[  9]   0.00-10.00  sec   322 MBytes   270 Mbits/sec                receiver
+```
+
+with {cfgcmd}`set system acceleration qat` on both systems the bandwidth
+increases.
+
+```
+Connecting to host 192.168.1.2, port 5201
+[  9] local 192.168.1.1 port 51340 connected to 192.168.1.2 port 5201
+[ ID] Interval           Transfer     Bitrate         Retr  Cwnd
+[  9]   0.00-1.00   sec  97.3 MBytes   817 Mbits/sec    0   1000 KBytes
+[  9]   1.00-2.00   sec  92.5 MBytes   776 Mbits/sec    0   1.07 MBytes
+[  9]   2.00-3.00   sec  92.5 MBytes   776 Mbits/sec    0    820 KBytes
+[  9]   3.00-4.00   sec  92.5 MBytes   776 Mbits/sec    0    899 KBytes
+[  9]   4.00-5.00   sec  91.2 MBytes   765 Mbits/sec    0    972 KBytes
+[  9]   5.00-6.00   sec  92.5 MBytes   776 Mbits/sec    0   1.02 MBytes
+[  9]   6.00-7.00   sec  92.5 MBytes   776 Mbits/sec    0   1.08 MBytes
+[  9]   7.00-8.00   sec  92.5 MBytes   776 Mbits/sec    0   1.14 MBytes
+[  9]   8.00-9.00   sec  91.2 MBytes   765 Mbits/sec    0    915 KBytes
+[  9]   9.00-10.00  sec  92.5 MBytes   776 Mbits/sec    0   1000 KBytes
+- - - - - - - - - - - - - - - - - - - - - - - - -
+[ ID] Interval           Transfer     Bitrate         Retr
+[  9]   0.00-10.00  sec   927 MBytes   778 Mbits/sec    0             sender
+[  9]   0.00-10.01  sec   925 MBytes   775 Mbits/sec                  receiver
+```
+
+[intel® qat]: https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html
diff --git a/docs/configuration/system/conntrack.md b/docs/configuration/system/conntrack.md
new file mode 100644
index 00000000..f83f0684
--- /dev/null
+++ b/docs/configuration/system/conntrack.md
@@ -0,0 +1,218 @@
+# Conntrack
+
+VyOS can be configured to track connections using the connection
+tracking subsystem. Connection tracking becomes operational once either
+stateful firewall or NAT is configured.
+
+## Configure
+
+```{cfgcmd} set system conntrack table-size \<1-50000000\>
+:defaultvalue:
+
+The connection tracking table contains one entry for each connection being
+tracked by the system.
+```
+
+```{cfgcmd} set system conntrack expect-table-size \<1-50000000\>
+:defaultvalue:
+
+The connection tracking expect table contains one entry for each expected
+connection related to an existing connection. These are generally used by
+“connection tracking helper” modules such as FTP.
+The default size of the expect table is 2048 entries.
+```
+
+```{cfgcmd} set system conntrack hash-size \<1-50000000\>
+:defaultvalue:
+
+Set the size of the hash table. The connection tracking hash table makes
+searching the connection tracking table faster. The hash table uses
+“buckets” to record entries in the connection tracking table.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack modules ftp
+.. cfgcmd:: set system conntrack modules h323
+.. cfgcmd:: set system conntrack modules nfs
+.. cfgcmd:: set system conntrack modules pptp
+.. cfgcmd:: set system conntrack modules sip
+.. cfgcmd:: set system conntrack modules sqlnet
+.. cfgcmd:: set system conntrack modules tftp
+
+    Configure the connection tracking protocol helper modules.
+    All modules are enable by default.
+
+    | Use `delete system conntrack modules` to deactive all modules.
+    | Or, for example ftp, `delete system conntrack modules ftp`.
+```
+
+```{cfgcmd} set system conntrack tcp half-open-connections \<1-21474836\>
+:defaultvalue:
+
+Set the maximum number of TCP half-open connections.
+```
+
+```{cfgcmd} set system conntrack tcp loose \<enable | disable\>
+:defaultvalue:
+
+Policy to track previously established connections.
+```
+
+```{cfgcmd} set system conntrack tcp max-retrans \<1-2147483647\>
+:defaultvalue:
+
+Set the number of TCP maximum retransmit attempts.
+```
+
+### Contrack Timeouts
+
+You can define custom timeout values to apply to a specific subset of
+connections, based on a packet and flow selector. To do this, you need to
+create a rule defining the packet and flow selector.
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   description <test>
+
+    Set a rule description.
+
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   destination address <ip-address>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   source address <ip-address>
+
+    Set a destination and/or source address. Accepted input for ipv4:
+
+    .. code-block:: none
+
+        set system conntrack timeout custom ipv4 rule <1-999999> [source | destination] address
+        Possible completions:
+           <x.x.x.x>            IPv4 address to match
+           <x.x.x.x/x>          IPv4 prefix to match
+           <x.x.x.x>-<x.x.x.x>  IPv4 address range to match
+           !<x.x.x.x>           Match everything except the specified address
+           !<x.x.x.x/x>         Match everything except the specified prefix
+           !<x.x.x.x>-<x.x.x.x> Match everything except the specified range
+
+        set system conntrack timeout custom ipv6 rule <1-999999> [source | destination] address
+        Possible completions:
+           <h:h:h:h:h:h:h:h>    IP address to match
+           <h:h:h:h:h:h:h:h/x>  Subnet to match
+           <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>
+                                IP range to match
+           !<h:h:h:h:h:h:h:h>   Match everything except the specified address
+           !<h:h:h:h:h:h:h:h/x> Match everything except the specified prefix
+           !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>
+                                Match everything except the specified range
+
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   destination port <value>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   source port <value>
+
+    Set a destination and/or source port. Accepted input:
+
+    .. code-block:: none
+
+        <port name>    Named port (any name in /etc/services, e.g., http)
+        <1-65535>      Numbered port
+        <start>-<end>  Numbered port range (e.g., 1001-1005)
+    
+    Multiple destination ports can be specified as a comma-separated list.
+    The whole list can also be "negated" using '!'. For example:
+    `!22,telnet,http,123,1001-1005``
+
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   protocol tcp close <1-21474836>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   protocol tcp close-wait <1-21474836>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   protocol tcp established <1-21474836>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   protocol tcp fin-wait <1-21474836>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   protocol tcp last-ack <1-21474836>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   protocol tcp syn-recv <1-21474836>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   protocol tcp syn-sent <1-21474836>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   protocol tcp time-wait <1-21474836>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   protocol udp replied <1-21474836>
+.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999>
+   protocol udp unreplied <1-21474836>
+
+    Set the timeout in seconds for a protocol or state in a custom rule.
+```
+
+### Conntrack ignore rules
+
+:::{note}
+**Important note about conntrack ignore rules:**
+Starting from vyos-1.5-rolling-202406120020, ignore rules can be defined in
+``set firewall [ipv4 | ipv6] prerouting raw ...``. It's expected that in
+the future the conntrack ignore rules will be removed.
+
+> Customized ignore rules, based on a packet and flow selector.
+:::
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999>
+   description <text>
+.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999>
+   destination address <ip-address>
+.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999>
+   destination port <port>
+.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999>
+   inbound-interface <interface>
+.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999>
+   protocol <protocol>
+.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999>
+   source address <ip-address>
+.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999>
+   source port <port>
+.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999>
+   tcp flags [not] <text>
+
+   Allowed values fpr TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``,
+   ``rst``, ``syn`` and ``urg``. Multiple values are supported, and for
+   inverted selection use ``not``, as shown in the example.
+```
+
+### Conntrack log
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log event destroy
+.. cfgcmd:: set system conntrack log event new
+.. cfgcmd:: set system conntrack log event update
+
+    Log the connection tracking events per type.
+
+.. cfgcmd:: set system conntrack log event destroy icmp
+.. cfgcmd:: set system conntrack log event destroy other
+.. cfgcmd:: set system conntrack log event destroy tcp
+.. cfgcmd:: set system conntrack log event destroy udp
+.. cfgcmd:: set system conntrack log event new icmp
+.. cfgcmd:: set system conntrack log event new other
+.. cfgcmd:: set system conntrack log event new tcp
+.. cfgcmd:: set system conntrack log event new udp
+.. cfgcmd:: set system conntrack log event update icmp
+.. cfgcmd:: set system conntrack log event update other
+.. cfgcmd:: set system conntrack log event update tcp
+.. cfgcmd:: set system conntrack log event update udp
+
+    Log the connection tracking events per protocol.
+
+.. cfgcmd:: set system conntrack log timestamp
+
+    Turn on flow-based timestamp extension.
+
+.. cfgcmd:: set system conntrack log queue-size <100-999999>
+
+    Manage internal queue size, default size is 4096 events.
+
+.. cfgcmd:: set system conntrack log log-level <info | debug>
+
+    Manage log level
+```
\ No newline at end of file
diff --git a/docs/configuration/system/console.md b/docs/configuration/system/console.md
new file mode 100644
index 00000000..9017fa30
--- /dev/null
+++ b/docs/configuration/system/console.md
@@ -0,0 +1,59 @@
+(serial-console)=
+
+# Serial Console
+
+For the average user a serial console has no advantage over a console offered
+by a directly attached keyboard and screen. Serial consoles are much slower,
+taking up to a second to fill a 80 column by 24 line screen. Serial consoles
+generally only support non-proportional ASCII text, with limited support for
+languages other than English.
+
+There are some scenarios where serial consoles are useful. System administration
+of remote computers is usually done using {ref}`ssh`, but there are times when
+access to the console is the only way to diagnose and correct software failures.
+Major upgrades to the installed distribution may also require console access.
+
+```{cfgcmd} set system console device \<device\>
+
+Defines the specified device as a system console. Available console devices
+can be (see completion helper):
+* ``ttySN`` - Serial device name
+* ``ttyAMAN``- Serial device name for some arm64 systems
+* ``ttyUSBX`` - USB Serial device name
+* ``hvc0`` - Xen console
+```
+
+```{cfgcmd} set system console device \<device\> kernel
+
+When set, the selected serial console is used as the kernel boot console.
+When removed, the kernel boot console falls back to tty0.
+
+:::{note}
+Only one serial console can carry the ``kernel`` option.
+When VyOS is installed via serial console, this option is set automatically
+for the serial interface used during installation; usually ``ttyS0`` or
+``ttyAMA0``.
+:::
+```
+
+```{cfgcmd} set system console device \<device\> speed \<speed\>
+
+The speed (baudrate) of the console device. Supported values are:
+* ``1200`` - 1200 bps
+* ``2400`` - 2400 bps
+* ``4800`` - 4800 bps
+* ``9600`` - 9600 bps
+* ``19200`` - 19,200 bps
+* ``38400`` - 38,400 bps (default for Xen console)
+* ``57600`` - 57,600 bps
+* ``115200`` - 115,200 bps (default for serial console)
+
+:::{note}
+If you use USB to serial converters for connecting to your VyOS
+appliance please note that most of them use software emulation without flow
+control. This means you should start with a common baud rate (most likely
+9600 baud) as otherwise you probably can not connect to the device using
+high speed baud rates as your serial converter simply can not process this
+data rate.
+:::
+```
\ No newline at end of file
diff --git a/docs/configuration/system/default-route.md b/docs/configuration/system/default-route.md
new file mode 100644
index 00000000..9f2793d1
--- /dev/null
+++ b/docs/configuration/system/default-route.md
@@ -0,0 +1,40 @@
+(default-gateway)=
+
+# Default Gateway/Route
+
+In the past (VyOS 1.1) used a gateway-address configured under the system tree
+({cfgcmd}`set system gateway-address <address>`), this is no longer supported
+and existing configurations are migrated to the new CLI command.
+
+## Configuration
+
+```{cfgcmd} set protocols static route 0.0.0.0/0 next-hop \<address\>
+
+Specify static route into the routing table sending all non local traffic
+to the nexthop address \<address\>.
+```
+
+```{cfgcmd} delete protocols static route 0.0.0.0/0
+
+Delete default route from the system.
+```
+
+
+## Operation
+
+```{opcmd} show ip route 0.0.0.0
+
+Show routing table entry for the default route.
+
+:::{code-block} none
+vyos@vyos:~$ show ip route 0.0.0.0
+Routing entry for 0.0.0.0/0
+Known via "static", distance 10, metric 0, best
+Last update 09:46:30 ago
+* 172.18.201.254, via eth0.201
+:::
+```
+
+:::{seealso}
+Configuration of {ref}`routing-static`
+:::
diff --git a/docs/configuration/system/flow-accounting.md b/docs/configuration/system/flow-accounting.md
new file mode 100644
index 00000000..c97d5473
--- /dev/null
+++ b/docs/configuration/system/flow-accounting.md
@@ -0,0 +1,209 @@
+(flow-accounting)=
+
+# Flow Accounting
+
+VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts
+as a flow exporter, and you are free to use it with any compatible collector.
+
+Flows can be exported via protocol NetFlow (versions 5, 9 and
+10/IPFIX). Additionally, you may save flows to an in-memory table
+internally in a router.
+
+:::{warning}
+You need to disable the in-memory table in production environments!
+Using {abbr}`IMT (In-Memory Table)` may lead to heavy CPU overloading and
+unstable flow-accounting behavior.
+:::
+
+## NetFlow / IPFIX
+
+NetFlow is a feature that was introduced on Cisco routers around 1996 that
+provides the ability to collect IP network traffic as it enters or exits an
+interface. By analyzing the data provided by NetFlow, a network administrator
+can determine things such as the source and destination of traffic, class of
+service, and the causes of congestion. A typical flow monitoring setup (using
+NetFlow) consists of three main components:
+
+- **exporter**: aggregates packets into flows and exports flow records towards
+  one or more flow collectors
+- **collector**: responsible for reception, storage and pre-processing of flow
+  data received from a flow exporter
+- **application**: analyzes received flow data in the context of intrusion
+  detection or traffic profiling, for example
+
+For connectionless protocols as like ICMP and UDP, a flow is considered
+complete once no more packets for this flow appear after configurable timeout.
+
+NetFlow is usually enabled on a per-interface basis to limit load on the router
+components involved in NetFlow, or to limit the amount of NetFlow records
+exported.
+
+## Configuration
+
+:::{warning}
+Using NetFlow on routers with high traffic levels may lead to
+high CPU usage and may affect the router's performance. In such cases,
+consider using sFlow instead.
+:::
+
+In order for flow accounting information to be collected and displayed for an
+interface, the interface must be configured for flow accounting.
+
+```{cfgcmd} set system flow-accounting interface \<interface\>
+
+Configure and enable collection of flow information for the interface
+identified by \<interface\>.
+
+You can configure multiple interfaces which would participate in flow
+accounting.
+```
+
+:::{note}
+Will be recorded only packets/flows on **incoming** direction in
+configured interfaces by default.
+:::
+
+By default, recorded flows will be saved internally and can be listed with the
+CLI command. You may disable using the local in-memory table with the command:
+
+```{cfgcmd} set system flow-accounting disable-imt
+
+If you need to sample also egress traffic, you may want to
+configure egress flow-accounting:
+```
+
+```{cfgcmd} set system flow-accounting enable-egress
+
+Internally, in flow-accounting processes exist a buffer for data exchanging
+between core process and plugins (each export target is a separated plugin).
+If you have high traffic levels or noted some problems with missed records
+or stopping exporting, you may try to increase a default buffer size (10
+MiB) with the next command:
+```
+
+```{cfgcmd} set system flow-accounting buffer-size \<buffer size\>
+
+In case, if you need to catch some logs from flow-accounting daemon, you may
+configure logging facility:
+```
+
+```{cfgcmd} set system flow-accounting syslog-facility \<facility\>
+
+Set the syslog facility for flow-accounting log messages. Supported values
+include ``daemon``, ``local0`` through ``local7``, and other standard syslog
+facilities.
+```
+
+
+### Flow Export
+
+In addition to displaying flow accounting information locally, one can also
+exported them to a collection server.
+
+#### NetFlow
+
+```{cfgcmd} set system flow-accounting netflow version \<version\>
+
+There are multiple versions available for the NetFlow data. The \<version\>
+used in the exported flow data can be configured here. The following
+versions are supported:
+* **5** - Most common version, but restricted to IPv4 flows only
+* **9** - NetFlow version 9 (default)
+* **10** - {abbr}`IPFIX (IP Flow Information Export)` as per {rfc}`3917`
+```
+
+```{cfgcmd} set system flow-accounting netflow server \<address\>
+
+Configure address of NetFlow collector. NetFlow server at \<address\> can
+be both listening on an IPv4 or IPv6 address.
+```
+
+```{cfgcmd} set system flow-accounting netflow source-ip \<address\>
+
+IPv4 or IPv6 source address of NetFlow packets
+```
+
+```{cfgcmd} set system flow-accounting netflow engine-id \<id\>
+
+NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255.
+```
+
+```{cfgcmd} set system flow-accounting netflow sampling-rate \<rate\>
+
+Use this command to configure the  sampling rate for flow accounting. The
+system samples one in every \<rate\> packets, where \<rate\> is the value
+configured for the sampling-rate option. The advantage of sampling every n
+packets, where n > 1, allows you to decrease the amount of processing
+resources required for flow accounting. The disadvantage of not sampling
+every packet is that the statistics produced are estimates of actual data
+flows.
+
+Per default every packet is sampled (that is, the sampling rate is 1).
+```
+
+```{cfgcmd} set system flow-accounting netflow timeout expiry-interval \<interval\>
+
+Specifies the interval at which Netflow data will be sent to a collector. As
+per default, Netflow data will be sent every 60 seconds.
+
+You may also additionally configure timeouts for different types of
+connections.
+```
+
+```{cfgcmd} set system flow-accounting netflow max-flows \<n\>
+
+If you want to change the maximum number of flows, which are tracking
+simultaneously, you may do this with this command (default 8192).
+```
+
+
+### Example:
+
+NetFlow v5 example:
+
+```none
+set system flow-accounting netflow engine-id 100
+set system flow-accounting netflow version 5
+set system flow-accounting netflow server 192.168.2.10 port 2055
+```
+
+
+## Operation
+
+Once flow accounting is configured on an interfaces it provides the ability to
+display captured network traffic information for all configured interfaces.
+
+```{opcmd} show flow-accounting interface \<interface\>
+
+Show flow accounting information for given \<interface\>.
+
+
+:::{code-block} none
+vyos@vyos:~$ show flow-accounting interface eth0
+IN_IFACE    SRC_MAC            DST_MAC            SRC_IP                     DST_IP             SRC_PORT    DST_PORT  PROTOCOL      TOS    PACKETS    FLOWS    BYTES
+----------  -----------------  -----------------  ------------------------  ---------------  ----------  ----------  ----------  -----  ---------  -------  -------
+eth0        00:53:01:a8:28:ac  ff:ff:ff:ff:ff:ff  192.0.2.2                 255.255.255.255        5678        5678  udp             0          1        1      178
+eth0        00:53:01:b2:2f:34  33:33:ff:00:00:00  fe80::253:01ff:feb2:2f34  ff02::1:ff00:0            0           0  ipv6-icmp       0          2        1      144
+eth0        00:53:01:1a:b4:53  33:33:ff:00:00:00  fe80::253:01ff:fe1a:b453  ff02::1:ff00:0            0           0  ipv6-icmp       0          1        1       72
+eth0        00:53:01:b2:22:48  00:53:02:58:a2:92  192.0.2.100               192.0.2.14            40152          22  tcp            16         39        1     2064
+eth0        00:53:01:c8:33:af  ff:ff:ff:ff:ff:ff  192.0.2.3                 255.255.255.255        5678        5678  udp             0          1        1      154
+eth0        00:53:01:b2:22:48  00:53:02:58:a2:92  192.0.2.100               192.0.2.14            40006          22  tcp            16        146        1     9444
+eth0        00:53:01:b2:22:48  00:53:02:58:a2:92  192.0.2.100               192.0.2.14                0           0  icmp          192         27        1     4455
+:::
+```
+
+```{opcmd} show flow-accounting interface \<interface\> host \<address\>
+
+Show flow accounting information for given \<interface\> for a specific host
+only.
+
+
+:::{code-block} none
+vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14
+IN_IFACE    SRC_MAC            DST_MAC            SRC_IP       DST_IP        SRC_PORT    DST_PORT  PROTOCOL      TOS    PACKETS    FLOWS    BYTES
+----------  -----------------  -----------------  -----------  ----------  ----------  ----------  ----------  -----  ---------  -------  -------
+eth0        00:53:01:b2:22:48  00:53:02:58:a2:92  192.0.2.100  192.0.2.14       40006          22  tcp            16        197        2    12940
+eth0        00:53:01:b2:22:48  00:53:02:58:a2:92  192.0.2.100  192.0.2.14       40152          22  tcp            16         94        1     4924
+eth0        00:53:01:b2:22:48  00:53:02:58:a2:92  192.0.2.100  192.0.2.14           0           0  icmp          192         36        1     5877
+:::
+```
\ No newline at end of file
diff --git a/docs/configuration/system/frr.md b/docs/configuration/system/frr.md
new file mode 100644
index 00000000..1741e286
--- /dev/null
+++ b/docs/configuration/system/frr.md
@@ -0,0 +1,45 @@
+(system-frr)=
+
+# FRR
+
+VyOS uses [FRRouting](https://frrouting.org/) as the control plane for dynamic
+and static routing. The routing daemon behavior can be adjusted during runtime,
+but requires either a restart of the routing daemon, or a reboot of the system.
+
+```{cfgcmd} set system frr bmp
+
+Enable {abbr}`BMP (BGP Monitoring Protocol)` support.
+```
+
+```{cfgcmd} set system frr descriptors \<numer\>
+
+This allows the operator to control the number of open file descriptors
+each daemon is allowed to start with. If the operator plans to run bgp with
+several thousands of peers then this is where we would modify FRR to allow
+this to happen.
+```
+
+```{cfgcmd} set system frr irdp
+
+Enable ICMP Router Discovery Protocol support.
+```
+
+```{cfgcmd} set system frr profile \<traditional | datacenter\>
+
+Select an FRR profile to adapt its default settings. If unset, the
+traditional profile is applied.
+```
+
+```{cfgcmd} set system frr snmp \<daemon\>
+
+Enable SNMP support for an individual routing daemon.
+
+Supported daemons:
+- bgpd
+- isisd
+- ldpd
+- ospf6d
+- ospfd
+- ripd
+- zebra
+```
\ No newline at end of file
diff --git a/docs/configuration/system/host-name.md b/docs/configuration/system/host-name.md
new file mode 100644
index 00000000..81840d1f
--- /dev/null
+++ b/docs/configuration/system/host-name.md
@@ -0,0 +1,70 @@
+(host-information)=
+
+# Host Information
+
+This section describes the system's host information and how to configure them,
+it covers the following topics:
+
+- Host name
+- Domain
+- IP address
+- Aliases
+
+## Hostname
+
+A hostname is the label (name) assigned to a network device (a host) on a
+network and is used to distinguish one device from another on specific networks
+or over the internet. On the other hand this will be the name which appears on
+the command line prompt.
+
+```{cfgcmd} set system host-name \<hostname\>
+
+   The hostname can be up to 63 characters. A hostname
+   must start and end with a letter or digit, and have as interior characters
+   only letters, digits, or a hyphen.
+
+   The default hostname used is `vyos`.
+```
+
+## Domain Name
+
+
+A domain name is the label (name) assigned to a computer network and is thus
+unique. VyOS appends the domain name as a suffix to any unqualified name. For
+example, if you set the domain name `example.com`, and you would ping the
+unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`.
+
+```{cfgcmd} set system domain-name \<domain\>
+
+Configure system domain name. A domain name must start and end with a letter
+or digit, and have as interior characters only letters, digits, or a hyphen.
+```
+
+## Static Hostname Mapping
+
+
+How an IP address is assigned to an interface in {ref}`ethernet-interface`.
+This section shows how to statically map an IP address to a hostname for local
+(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to
+`/etc/hosts` file entries.
+
+
+:::{note}
+Do *not* manually edit `/etc/hosts`. This file will automatically be
+regenerated on boot based on the settings in this section, which means you'll
+lose all your manual edits. Instead, configure static host mappings as follows.
+:::
+
+```{cfgcmd} set system static-host-mapping host-name \<hostname\> inet \<address\>
+
+Create a static hostname mapping which will always resolve the name
+`<hostname>` to IP address `<address>`.
+```
+```{cfgcmd} set system static-host-mapping host-name \<hostname\> alias \<alias\>
+
+Create named `<alias>` for the configured static mapping for `<hostname>`.
+Thus the address configured as {cfgcmd}`set system static-host-mapping
+host-name <hostname> inet <address>` can be reached via multiple names.
+
+Multiple aliases can be specified per host-name.
+```
\ No newline at end of file
diff --git a/docs/configuration/system/index.md b/docs/configuration/system/index.md
new file mode 100644
index 00000000..e0b8a5a1
--- /dev/null
+++ b/docs/configuration/system/index.md
@@ -0,0 +1,34 @@
+# System
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+acceleration
+conntrack
+console
+flow-accounting
+frr
+host-name
+ip
+ipv6
+lcd
+login
+name-server
+option
+proxy
+sflow
+syslog
+sysctl
+task-scheduler
+time-zone
+updates
+watchdog
+```
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+default-route
+```
diff --git a/docs/configuration/system/ip.md b/docs/configuration/system/ip.md
new file mode 100644
index 00000000..717ee57d
--- /dev/null
+++ b/docs/configuration/system/ip.md
@@ -0,0 +1,126 @@
+# IP
+
+## System configuration commands
+
+```{cfgcmd} set system ip disable-forwarding
+
+Use this command to disable IPv4 forwarding on all interfaces.
+```
+
+```{cfgcmd} set system ip disable-directed-broadcast
+
+Use this command to disable IPv4 directed broadcast forwarding on all
+interfaces.
+
+If set, IPv4 directed broadcast forwarding will be completely disabled
+regardless of whether per-interface directed broadcast forwarding is
+enabled or not.
+```
+
+```{cfgcmd} set system ip arp table-size \<number\>
+
+Use this command to define the maximum number of entries to keep in
+the ARP cache (1024, 2048, 4096, 8192, 16384, 32768).
+```
+
+```{cfgcmd} set system ip multipath layer4-hashing
+
+Use this command to use Layer 4 information for IPv4 ECMP hashing.
+```
+
+```{cfgcmd} set system ip import-table \<table-id\>
+
+Use this command to immport the table, by given table id, into the main RIB.
+```
+
+```{cfgcmd} set system ip import-table \<table-id\> distance \<distance\>
+
+Use this command to override the default distance when importing routers
+from the alternate table.
+```
+
+```{cfgcmd} set system ip import-table \<table-id\> route-map \<route-map\>
+
+Use this command to filter routes that are imported into the main table
+from alternate table using route-map.
+```
+
+
+### Zebra/Kernel route filtering
+
+Zebra supports prefix-lists and Route Maps to match routes received from
+other FRR components. The permit/deny facilities provided by these commands
+can be used to filter which routes zebra will install in the kernel.
+
+```{cfgcmd} set system ip protocol \<protocol\> route-map \<route-map\>
+
+Apply a route-map filter to routes for the specified protocol. The following
+protocols can be used: any, babel, bgp, eigrp, isis, ospf, rip, static
+
+:::{note}
+If you choose any as the option that will cause all protocols that
+are sending routes to zebra.
+:::
+```
+
+
+### Nexthop Tracking
+
+Nexthop tracking resolve nexthops via the default route by default. This is enabled
+by default for a traditional profile of FRR which we use. It and can be disabled if
+you do not want to e.g. allow BGP to peer across the default route.
+
+```{cfgcmd} set system ip nht no-resolve-via-default
+
+Do not allow IPv4 nexthop tracking to resolve via the default route. This
+parameter is configured per-VRF, so the command is also available in the VRF
+subnode.
+```
+
+
+## Operational commands
+
+### show commands
+
+See below the different parameters available for the IPv4 **show** command:
+
+```none
+vyos@vyos:~$ show ip
+Possible completions:
+  access-list   Show all IP access-lists
+  as-path-access-list
+                Show all as-path-access-lists
+  bgp           Show Border Gateway Protocol (BGP) information
+  community-list
+                Show IP community-lists
+  extcommunity-list
+                Show extended IP community-lists
+  forwarding    Show IP forwarding status
+  groups        Show IP multicast group membership
+  igmp          Show IGMP (Internet Group Management Protocol) information
+  large-community-list
+                Show IP large-community-lists
+  multicast     Show IP multicast
+  ospf          Show IPv4 Open Shortest Path First (OSPF) routing information
+  pim           Show PIM (Protocol Independent Multicast) information
+  ports         Show IP ports in use by various system services
+  prefix-list   Show all IP prefix-lists
+  protocol      Show IP route-maps per protocol
+  rip           Show Routing Information Protocol (RIP) information
+  route         Show IP routes
+```
+
+
+### reset commands
+
+And the different IPv4 **reset** commands available:
+
+```none
+vyos@vyos:~$ reset ip
+Possible completions:
+  arp           Reset Address Resolution Protocol (ARP) cache
+  bgp           Clear Border Gateway Protocol (BGP) statistics or status
+  igmp          IGMP clear commands
+  multicast     IP multicast routing table
+  route         Reset IP route
+```
diff --git a/docs/configuration/system/ipv6.md b/docs/configuration/system/ipv6.md
new file mode 100644
index 00000000..ee0a6ade
--- /dev/null
+++ b/docs/configuration/system/ipv6.md
@@ -0,0 +1,193 @@
+# IPv6
+
+## System configuration commands
+
+```{cfgcmd} set system ipv6 disable-forwarding
+
+   Use this command to disable IPv6 forwarding on all interfaces.
+```
+
+
+```{cfgcmd} set system ipv6 neighbor table-size \<number\>
+
+Use this command to define the maximum number of entries to keep in
+the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768).
+```
+
+
+```{cfgcmd} set system ipv6 strict-dad
+
+Use this command to disable IPv6 operation on interface when
+Duplicate Address Detection fails on Link-Local address.
+```
+
+
+```{cfgcmd} set system ipv6 multipath layer4-hashing
+
+Use this command to user Layer 4 information for ECMP hashing.
+```
+
+### Zebra/Kernel route filtering
+
+
+Zebra supports prefix-lists and Route Maps to match routes received from
+other FRR components. The permit/deny facilities provided by these commands
+can be used to filter which routes zebra will install in the kernel.
+
+```{cfgcmd} set system ipv6 protocol \<protocol\> route-map \<route-map\>
+
+Apply a route-map filter to routes for the specified protocol. The following
+protocols can be used: any, babel, bgp, isis, ospfv3, ripng, static
+
+:::{note}
+If you choose any as the option that will cause all protocols that
+are sending routes to zebra.
+:::
+```
+
+### Nexthop Tracking
+
+
+Nexthop tracking resolve nexthops via the default route by default. This is enabled
+by default for a traditional profile of FRR which we use. It and can be disabled if
+you do not want to e.g. allow BGP to peer across the default route.
+
+```{cfgcmd} set system ipv6 nht no-resolve-via-default
+
+Do not allow IPv6 nexthop tracking to resolve via the default route. This
+parameter is configured per-VRF, so the command is also available in the VRF
+subnode.
+```
+
+## Operational commands
+
+
+### Show commands
+
+```{opcmd} show ipv6 neighbors
+
+Use this command to show IPv6 Neighbor Discovery Protocol information.
+```
+
+
+```{opcmd} show ipv6 groups
+
+Use this command to show IPv6 multicast group membership.
+```
+
+
+```{opcmd} show ipv6 forwarding
+
+Use this command to show IPv6 forwarding status.
+```
+
+
+```{opcmd} show ipv6 route
+
+Use this command to show IPv6 routes.
+
+Check the many parameters available for the show ipv6 route command:
+
+:::{code-block} none
+vyos@vyos:~$ show ipv6 route
+Possible completions:
+  <Enter>       Execute the current command
+  <X:X::X:X>    Show IPv6 routes of given address or prefix
+  <X:X::X:X/M>
+  bgp           Show IPv6 BGP routes
+  cache         Show kernel IPv6 route cache
+  connected     Show IPv6 connected routes
+  forward       Show kernel IPv6 route table
+  isis          Show IPv6 ISIS routes
+  kernel        Show IPv6 kernel routes
+  ospfv3        Show IPv6 OSPF6 routes
+  ripng         Show IPv6 RIPNG routes
+  static        Show IPv6 static routes
+  summary       Show IPv6 routes summary
+  table         Show IP routes in policy table
+  tag           Show only routes with tag
+  vrf           Show IPv6 routes in VRF
+:::
+```
+```{opcmd} show ipv6 prefix-list
+
+   Use this command to show all IPv6 prefix lists
+
+   There are different parameters for getting prefix-list information:
+
+   :::{code-block} none
+   vyos@vyos:~$ show ipv6 prefix-list
+   Possible completions:
+     <Enter>       Execute the current command
+     <WORD>        Show specified IPv6 prefix-list
+     detail        Show detail of IPv6 prefix-lists
+     summary       Show summary of IPv6 prefix-lists
+   :::
+```
+
+
+```{opcmd} show ipv6 access-list
+
+Use this command to show all IPv6 access lists
+
+You can also specify which IPv6 access-list should be shown:
+
+:::{code-block} none
+vyos@vyos:~$ show ipv6 access-list
+Possible completions:
+  <Enter>       Execute the current command
+  <text>        Show specified IPv6 access-list
+:::
+```
+```{opcmd} show ipv6 ospfv3
+
+   Use this command to get information about OSPFv3.
+
+   You can get more specific OSPFv3 information by using the parameters
+   shown below:
+
+   :::{code-block} none
+   vyos@vyos:~$ show ipv6 ospfv3
+   Possible completions:
+     <Enter>       Execute the current command
+     area          Show OSPFv3 spf-tree information
+     border-routers
+                   Show OSPFv3 border-router (ABR and ASBR) information
+     database      Show OSPFv3 Link state database information
+     interface     Show OSPFv3 interface information
+     linkstate     Show OSPFv3 linkstate routing information
+     neighbor      Show OSPFv3 neighbor information
+     redistribute  Show OSPFv3 redistribute External information
+     route         Show OSPFv3 routing table information
+   :::
+```
+
+
+```{opcmd} show ipv6 ripng
+
+Use this command to get information about the RIPNG protocol
+```
+
+
+```{opcmd} show ipv6 ripng status
+
+Use this command to show the status of the RIPNG protocol
+```
+
+### Reset commands
+
+```{opcmd} reset bgp ipv6 \<address\>
+
+Use this command to clear Border Gateway Protocol statistics or
+status.
+```
+```{opcmd} reset ipv6 neighbors \<address | interface\>
+
+Use this command to reset IPv6 Neighbor Discovery Protocol cache for
+an address or interface.
+```
+```{opcmd} reset ipv6 route cache
+
+Use this command to flush the kernel IPv6 route cache.
+An address can be added to flush it only for that route.
+```
\ No newline at end of file
diff --git a/docs/configuration/system/lcd.md b/docs/configuration/system/lcd.md
new file mode 100644
index 00000000..ef9031ea
--- /dev/null
+++ b/docs/configuration/system/lcd.md
@@ -0,0 +1,41 @@
+(system-display)=
+
+# System Display (LCD)
+
+The system LCD {abbr}`LCD (Liquid-crystal display)` option is for users running
+VyOS on hardware that features an LCD display. This is typically a small display
+built in an 19 inch rack-mountable appliance. Those displays are used to show
+runtime data.
+
+To configure your LCD display you must first identify the used hardware, and
+connectivity of the display to your system. This can be any serial port
+(`ttySxx`) or serial via USB or even old parallel port interfaces.
+
+## Configuration
+
+```{cfgcmd} set system lcd device \<device\>
+
+This is the name of the physical interface used to connect to your LCD
+display. Tab completion is supported and it will list you all available
+serial interface.
+
+For serial via USB port information please refer to the USB hardware section.
+```
+
+```{cfgcmd} set system lcd model \<model\>
+
+This is the LCD model used in your system.
+
+At the time of this writing the following displays are supported:
+* Crystalfontz CFA-533
+* Crystalfontz CFA-631
+* Crystalfontz CFA-633
+* Crystalfontz CFA-635
+
+:::{note}
+We can't support all displays from the beginning. If your display
+type is missing, please create a feature request via
+Phabricator.
+:::
+```
+
diff --git a/docs/configuration/system/login.md b/docs/configuration/system/login.md
new file mode 100644
index 00000000..288d30a8
--- /dev/null
+++ b/docs/configuration/system/login.md
@@ -0,0 +1,604 @@
+---
+lastproofread: '2026-01-12'
+---
+
+(user-management)=
+
+# Login/user management
+
+The default VyOS user account (`vyos`), as well as newly created user accounts,
+possess full system configuration privileges. These accounts are granted sudo
+privileges, allowing them to execute commands as the root user.
+
+VyOS supports both local authentication and remote authentication via
+{abbr}`RADIUS (Remote Authentication Dial-In User Service)`/ {abbr}`TACACS+
+(Terminal Access Controller Access-Control System)`.
+
+## Local authentication
+
+```{cfgcmd} set system login user \<name\> full-name "\<string\>"
+
+**Configure the real name or description for a system user.**
+
+If the description includes spaces, enclose ``<string>`` in double quotes.
+
+If the user ``<name>`` already exists, the command updates the current
+description. If not, it creates a new user with the specified description.
+```
+
+```{cfgcmd} set system login user \<name\> authentication plaintext-password \<password\>
+
+**Configure a password for a system user.**
+
+Enter the password in plaintext. Upon ``commit``, VyOS hashes the password for
+secure storage and removes the plaintext value.
+
+If the user ``<name>`` already exists, the command updates the current password.
+If not, it creates a new user with the specified plaintext password.
+```
+
+```{cfgcmd} set system login user \<name\> authentication encrypted-password \<password\>
+
+**Configure a pre-encrypted password for a system user.**
+
+Enter the password in its hashed format. Upon ``commit``, VyOS stores this value
+directly without modification.
+
+If the user ``<name>`` already exists, the command updates the current password.
+If not, it creates a new user with the specified pre-encrypted password.
+```
+
+```{cfgcmd} set system login user \<name\> authentication principal \<principal\>
+
+**Configure an SSH certificate principal for a system user.**
+
+Enter the principal (a string included in the user's signed SSH certificate).
+Upon ``commit``, VyOS stores this mapping, allowing the user to log in if the
+certificate they present contains this principal.
+
+If the user ``<name>`` already exists, the command updates the principal. If not,
+it creates a new user linked to the specified principal.
+
+**If not configured**, the principal defaults to ``<name>``.
+```
+
+```{cfgcmd} set system login user \<name\> disable
+
+**Disable a system user account.**
+
+VyOS locks the account, preventing the user from logging in.
+```
+
+(ssh_key_based_authentication)=
+
+## Key-based authentication
+
+Key-based authentication is the recommended method for securing SSH access in
+VyOS. It uses a **public/private key pair** to verify user identity without
+requiring a password. To authorize access, you assign **SSH public keys** to
+user accounts on the router, while SSH private keys remain on local devices.
+VyOS allows assigning multiple SSH public keys to a single user account, which
+is useful for accessing a router from different devices.
+
+### Generate the key pair
+
+Generate an SSH key pair on your **local machine** using the `ssh-keygen`
+command. This creates two files:
+- **Private key** (e.g., `id_rsa`): Remains on your local machine and must
+  never be shared.
+- **Public key** (e.g., `id_rsa.pub`): Is used to configure the VyOS user
+  account. By default, it is saved to `~/.ssh/id_rsa.pub`.
+
+Each SSH public key consists of three parts, separated by spaces:
+- **Encryption algorithm type:** `ssh-rsa`, `ssh-ed25519`, etc.
+- **Key:** The actual data (a long string beginning with `AAAA...`).
+- **Comment:** An identifier for your reference (e.g., `user@host`).
+
+Only the encryption algorithm type and key parts are required to
+configure the authorization entry in VyOS. The comment part is optional.
+
+:::{seealso}
+{ref}`SSH operation <ssh_operation>`
+:::
+
+:::{warning}
+SSH key strings are long. When copying and pasting, ensure your
+terminal does not insert line breaks. The key must be entered as a **single
+line** to function correctly.
+:::
+
+### Configure the router
+
+To configure SSH public key authentication for a user account, run the
+following two commands using the same `<identifier>`:
+
+```{cfgcmd} set system login user \<username\> authentication public-keys \<identifier\> key \<key\>
+
+**Configure the SSH public key for the user account.**
+* ``<identifier>``: A unique label that identifies this specific key entry.
+* ``<key>``: The actual string of characters from your public key.
+```
+
+```{cfgcmd} set system login user \<username\> authentication public-keys \<identifier\> type \<type\>
+
+**Configure the SSH key's encryption type.**
+
+The following encryption algorithm types are available:
+
+* ``ecdsa-sha2-nistp256``
+* ``ecdsa-sha2-nistp384``
+* ``ecdsa-sha2-nistp521``
+* ``ssh-dss``
+* ``ssh-ed25519``
+* ``ssh-rsa``
+
+:::{note}
+To assign multiple SSH public keys to a user account, repeat the
+commands above with a unique identifier for each key.
+:::
+```
+
+```{cfgcmd} set system login user \<username\> authentication public-keys \<identifier\> options \<options\>
+
+**Configure specific restrictions or behaviors for an SSH public key.**
+
+``<options>``: A string of comma-separated values that define permissions
+or restrictions for this key.
+
+The command accepts standard OpenSSH options listed in the router's
+``~/.ssh/authorized_keys`` file.
+
+To include a ``"`` character in the options string, use ``&quot;``.
+
+For example, to restrict allowed source IP addresses for an SSH public key,
+use: ``from=&quot;10.0.0.0/24&quot;``.
+```
+
+
+## OTP-based MFA
+
+VyOS lets you enhance user access security by enabling {abbr}`OTP (One-time
+password)`-based {abbr}`MFA (Multi-factor Authentication)` for individual
+users. Users with {abbr}`OTP (One-time password)`-based {abbr}`MFA
+(Multi-factor Authentication)` must enter a valid {abbr}`OTP (One-time
+password)` along with their password at login. Users without {abbr}`OTP
+(One-time password)`-based {abbr}`MFA (Multi-factor Authentication)` use
+standard authentication.
+
+```{cfgcmd} set system login user \<username\> authentication otp key \<key\>
+
+**Configure** {abbr}`OTP (One-time password)`**-based** {abbr}`MFA
+(Multi-factor Authentication)` **for a user.**
+
+``<key>``: A Base32-encoded secret key. This key must be added to the user's
+authenticator app to generate valid {abbr}`OTPs (One-time passwords)`.
+
+**When configured**, the user is required to enter their password followed by
+a valid OTP for all subsequent logins.
+```
+
+
+### OTP settings
+
+```{cfgcmd} set system login user \<username\> authentication otp rate-limit \<limit\>
+
+**Configure the number of** {abbr}`OTP (One-time password)` **authentication
+attempts allowed within a specified time period.**
+
+If this limit is exceeded, the user is temporarily blocked.
+
+The default value is 3 attempts. The valid range is 1 to 10 attempts.
+```
+
+```{cfgcmd} set system login user \<username\> authentication otp rate-time \<seconds\>
+
+**Configure the time period, in seconds, for tracking** {abbr}`OTP (One-time
+password)` **authentication attempts.**
+
+The default value is 30 seconds. The valid range is 1 to 600 seconds.
+```
+
+```{cfgcmd} set system login user \<username\> authentication otp window-size \<size\>
+
+**Configure the** {abbr}`OTP (One-time password)` **window size for a user.**
+
+The {abbr}`OTP (One-time password)` window size defines the number of
+concurrently valid {abbr}`OTPs (One-time passwords)` that the authentication
+server accepts. This setting assumes a new token is generated every 30 seconds.
+
+The default value is 3. This permits 3 concurrent codes: the code for the
+current 30-second interval, the preceding code, and the following code. This
+allows up to 30 seconds of time skew between the authentication server and
+client.
+
+If the window size is increased to 17, the system permits 17 concurrent codes
+(the current code, the 8 preceding codes, and the 8 following codes). This
+allows for a time skew of up to 4 minutes.
+
+The valid range is 1 to 21.
+```
+
+
+### Generate an OTP-key
+
+Use the following command to generate an OTP key:
+
+```{cfgcmd} generate system login username \<username\> otp-key hotp-time rate-limit \<1-10\> rate-time \<15-600\> window-size \<1-21\>
+```
+
+Key generation example:
+
+```none
+vyos@vyos:~$ generate system login username otptester otp-key hotp-time rate-limit 2 rate-time 20 window-size 5
+# You can share it with the user, he just needs to scan the QR in his OTP app
+# username:  otptester
+# OTP KEY:  J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY
+# OTP URL:  otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30
+█████████████████████████████████████████████
+█████████████████████████████████████████████
+████ ▄▄▄▄▄ █▀█ █▄   ▀▄▀▄█▀▄  ▀█▀ █ ▄▄▄▄▄ ████
+████ █   █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀  ▄█ █   █ ████
+████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████
+████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████
+████ ▄   █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄  █ █▄█ █████
+████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█  ████
+█████▄  ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄   ▄████
+████▀▀▄   ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄  ▀█ █  ████
+████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄  ▄ ▄▀ █▄████
+████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄   ▄▄ ████
+████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████
+████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █  ▀▄▄  ▄█▀ ▄▄   ▀▄▄ ████
+████  ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄  ▄████
+████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀  ███▄ ▄████
+████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████
+████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█  ████
+████ █   █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄  ▀ ▄    ▄ ▄▄████
+████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████
+████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████
+█████████████████████████████████████████████
+█████████████████████████████████████████████
+# To add this OTP key to configuration, run the following commands:
+set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY'
+set system login user otptester authentication otp rate-limit '2'
+set system login user otptester authentication otp rate-time '20'
+set system login user otptester authentication otp window-size '5'
+```
+
+### Display the OTP key for a user
+
+Use the following command to display the {abbr}`OTP (One-time password)`
+key for a user:
+
+```{cfgcmd} sh system login authentication user \<username\> otp \<full | key-b32 | qrcode | uri\>
+```
+
+Example:
+
+```none
+vyos@vyos:~$ sh system login authentication user otptester otp full
+# You can share the OTP key with the user. They just need to scan the QR in their OTP app.
+# username: otptester
+# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY
+# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30
+█████████████████████████████████████████████
+█████████████████████████████████████████████
+████ ▄▄▄▄▄ █▀█ █▄   ▀▄▀▄█▀▄  ▀█▀ █ ▄▄▄▄▄ ████
+████ █   █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀  ▄█ █   █ ████
+████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████
+████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████
+████ ▄   █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄  █ █▄█ █████
+████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█  ████
+█████▄  ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄   ▄████
+████▀▀▄   ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄  ▀█ █  ████
+████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄  ▄ ▄▀ █▄████
+████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄   ▄▄ ████
+████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████
+████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █  ▀▄▄  ▄█▀ ▄▄   ▀▄▄ ████
+████  ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄  ▄████
+████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀  ███▄ ▄████
+████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████
+████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█  ████
+████ █   █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄  ▀ ▄    ▄ ▄▄████
+████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████
+████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████
+█████████████████████████████████████████████
+█████████████████████████████████████████████
+# To add this OTP key to configuration, run the following commands:
+set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY'
+set system login user otptester authentication otp rate-limit '2'
+set system login user otptester authentication otp rate-time '20'
+set system login user otptester authentication otp window-size '5'
+```
+
+Once {abbr}`OTP (One-time password)`-based {abbr}`MFA (Multi-factor
+Authentication)` is configured for a user account, this user must enter their
+standard password followed by the current 6-digit OTP code at login. For
+example, if the user's password is `vyosrocks` and the OTP is `817454`, they
+should enter `vyosrocks817454`.
+
+## RADIUS authentication
+
+For large-scale deployments, managing individual user accounts across multiple
+VyOS instances is inefficient. VyOS supports centralized authentication via
+{abbr}`RADIUS (Remote Authentication Dial-In User Service)`, consolidating user
+account management on a single backend server.
+
+### Configuration
+
+```{cfgcmd} set system login radius server \<address\> key \<secret\>
+
+**Configure the** {abbr}`RADIUS (Remote Authentication Dial-In User Service)`
+**server's IP address and shared secret.**
+
+The shared secret is used to verify the router's identity and to encrypt user
+passwords during authentication.
+
+You can configure multiple {abbr}`RADIUS (Remote Authentication Dial-In User
+Service)` servers.
+```
+
+```{cfgcmd} set system login radius server \<address\> port \<port\>
+
+**Configure the UDP port for communication with the** {abbr}`RADIUS (Remote
+Authentication Dial-In User Service)` **server.**
+
+The default port is 1812.
+```
+
+```{cfgcmd} set system login radius server \<address\> disable
+
+**Disable a** {abbr}`RADIUS (Remote Authentication Dial-In User Service)`
+**server from the authentication process.**
+
+Disabling a specific {abbr}`RADIUS (Remote Authentication Dial-In User
+Service)` server doesn’t remove its configuration settings (the server’s IP
+address and shared secret).
+```
+
+```{cfgcmd} set system login radius server \<address\> timeout \<timeout\>
+
+Configure the duration, in seconds, that the VyOS router waits for a
+response from the {abbr}`RADIUS (Remote Authentication Dial-In User Service)`
+server after sending an authentication request.
+
+If the server does not respond within this timeframe, the VyOS router tries to
+connect to another configured server or falls back to local authentication.
+```
+
+```{cfgcmd} set system login radius source-address \<address\>
+
+**Configure the source IP address the router uses for** {abbr}`RADIUS (Remote
+Authentication Dial-In User Service)` **authentication requests.**
+
+A consistent source IP address is recommended as RADIUS servers typically
+accept requests only from known, trusted IP addresses.
+
+If not explicitly defined, the router uses the current egress interface
+address, which may change (e.g., due to a link outage), causing authentication
+failures.
+```
+
+```{cfgcmd} set system login radius vrf \<name\>
+
+**Configure the router to send all** {abbr}`RADIUS (Remote Authentication
+Dial-In User Service)` **authentication requests via a specific VRF.**
+
+By default, {abbr}`RADIUS (Remote Authentication Dial-In User Service)`
+authentication requests are sent via the global routing table.
+```
+
+### Configuration example
+
+```none
+set system login radius server 192.168.0.2 key 'test-vyos'
+set system login radius server 192.168.0.2 port '1812'
+set system login radius server 192.168.0.2 timeout '5'
+set system login radius source-address '192.168.0.1'
+```
+
+If communication with the {abbr}`RADIUS (Remote Authentication Dial-In User
+Service)` server fails, the router falls back to local user authentication.
+During this process, users may experience a login delay while the system waits
+for the {abbr}`RADIUS (Remote Authentication Dial-In User Service)` request to
+time out. This delay depends on the configured timeout value.
+
+:::{hint}
+To grant administrative privileges to {abbr}`RADIUS (Remote
+Authentication Dial-In User Service)`-authenticated users, the server must
+return the Cisco-AV-Pair attribute set to `shell:priv-lvl=15`. Otherwise, users
+receive standard privileges and cannot perform configuration tasks.
+:::
+
+## TACACS+ authentication
+
+In addition to {abbr}`RADIUS (Remote Authentication Dial-In User Service)`,
+VyOS supports {abbr}`TACACS+ (Terminal Access Controller Access Control
+System)`, which is commonly used in large enterprise environments.
+
+Unlike {abbr}`RADIUS (Remote Authentication Dial-In User Service)`,
+{abbr}`TACACS+ (Terminal Access Controller Access Control System)` separates
+Authentication, Authorization, and Accounting (AAA) into independent processes
+and encrypts the entire packet body for enhanced security.
+
+{abbr}`TACACS+ (Terminal Access Controller Access Control System)` is defined
+in {rfc}`8907`.
+(tacacs-configuration)=
+
+### Configuration
+
+```{cfgcmd} set system login tacacs server \<address\> key \<secret\>
+
+**Configure the** {abbr}`TACACS+ (Terminal Access Controller Access Control
+System)` **server IP address and shared secret.**
+
+Unlike {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, which
+encrypts only passwords, {abbr}`TACACS+ (Terminal Access Controller Access
+Control System)` encrypts the entire packet body for enhanced security.
+
+You can configure multiple {abbr}`TACACS+ (Terminal Access Controller Access
+Control System)` servers.
+```
+
+```{cfgcmd} set system login tacacs server \<address\> port \<port\>
+
+**Configure the TCP port for communication with the** {abbr}`TACACS+ (Terminal
+Access Controller Access Control System)` **server.**
+
+The default port is 49.
+```
+
+```{cfgcmd} set system login tacacs server \<address\> disable
+
+**Disable a** {abbr}`TACACS+ (Terminal Access Controller Access Control
+System)` **server from the authentication process.**
+
+Disabling a specific {abbr}`TACACS+ (Terminal Access Controller Access Control
+System)` server doesn’t remove its configuration settings (the server’s IP
+address and shared secret).
+```
+
+```{cfgcmd} set system login tacacs server \<address\> timeout \<timeout\>
+
+Configure the duration, in seconds, that the VyOS router waits for a
+response from the {abbr}`TACACS+ (Terminal Access Controller Access
+Control System)` server after sending an authentication request.
+
+If the server does not respond within this timeframe, the VyOS router tries
+to connect to another configured server or falls back to local authentication.
+```
+
+```{cfgcmd} set system login tacacs source-address \<address\>
+
+**Configure the source IP address the router uses for**
+{abbr}`TACACS+ (Terminal Access Controller Access Control System)`
+**authentication requests.**
+
+A consistent source IP address is recommended as {abbr}`TACACS+ (Terminal
+Access Controller Access Control System)` servers typically accept requests
+only from known, trusted IP addresses.
+
+If not explicitly defined, the router uses the current egress interface address,
+which may change (e.g., due to a link outage), causing authentication failures.
+```
+
+```{cfgcmd} set system login tacacs vrf \<name\>
+
+Configure the router to send all {abbr}`TACACS+ (Terminal Access Controller
+Access Control System)` authentication requests via a specific VRF.
+
+By default, {abbr}`TACACS+ (Terminal Access Controller Access Control System)`
+authentication requests are sent via the global routing table.
+```
+
+(login-tacacs-example)=
+
+### Configuration example
+
+```none
+set system login tacacs server 192.168.0.2 key 'test-vyos'
+set system login tacacs server 192.168.0.2 port '49'
+set system login tacacs source-address '192.168.0.1'
+```
+
+If communication with the {abbr}`TACACS+ (Terminal Access Controller Access
+Control System)` server fails, the router falls back to local user
+authentication.
+
+## Login banners
+
+VyOS allows you to configure **pre-login** and **post-login** banners.
+Pre-login banners are typically used for system identification, legal disclaimers, or security warnings
+displayed before authentication, while post-login banners provide system
+information or operational notices to users after login.
+
+```{cfgcmd} set system login banner pre-login \<message\>
+
+Configure a message to be shown to users before the ``username`` and ``password``
+prompts appear.
+```
+
+```{cfgcmd} set system login banner post-login \<message\>
+
+Configure a message to be shown to users after successful authentication.
+```
+:::{note}
+Use `\\n` to insert line breaks in multi-line banner messages.
+:::
+
+## Login session limits
+
+```{cfgcmd} set system login max-login-session \<number\>
+
+**Configure the maximum number of concurrent login sessions.**
+```
+:::{note}
+If you limit concurrent login sessions, you must also configure a
+session `<timeout>`. This clears inactive sessions and prevents blocking new
+login attempts.
+:::
+```{cfgcmd} set system login timeout \<timeout\>
+
+**Configure the login session timeout, in seconds.**
+
+Idle login sessions are terminated after this period.
+```
+
+## Configuration examples
+
+Example 1: Multi-key SSH with MFA and source restrictions
+
+In this configuration, `User1` and `User2` both use the vyos user account,
+each with a unique SSH key. `User1` is restricted to authentication from a
+single IP address.
+
+For both users, password-based logins require {abbr}`OTP (One-time password)`
+-based {abbr}`MFA (Multi-factor Authentication)`.
+
+```none
+set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW"
+set system login user vyos authentication public-keys 'User1' type ssh-rsa
+set system login user vyos authentication public-keys 'User1' options "from=&quot;192.168.0.100&quot;"
+
+set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3"
+set system login user vyos authentication public-keys 'User2' type ssh-rsa
+
+set system login user vyos authentication otp key OHZ3OJ7U2N25BK4G7SOFFJTZDTCFUUE2
+set system login user vyos authentication plaintext-password vyos
+```
+
+Example 2: Containerized {abbr}`TACACS+ (Terminal Access Controller Access Control System)`
+deployment with redundancy.
+
+In this configuration, the VyOS router hosts its own authentication
+infrastructure using two containerized {abbr}`TACACS+ (Terminal Access
+Controller Access Control System)` servers (`tacacs1` and `tacacs2`) on a
+private network for redundancy.
+
+System logins are authenticated against credentials stored within these internal
+containers rather than the router's local user database.
+
+First, download the image in operational mode:
+
+```none
+add container image lfkeitel/tacacs_plus:latest
+```
+
+Next, configure the containers in configuration mode:
+
+```none
+set container network tac-test prefix '100.64.0.0/24'
+
+set container name tacacs1 image 'lfkeitel/tacacs_plus:latest'
+set container name tacacs1 network tac-test address '100.64.0.11'
+
+set container name tacacs2 image 'lfkeitel/tacacs_plus:latest'
+set container name tacacs2 network tac-test address '100.64.0.12'
+
+set system login tacacs server 100.64.0.11 key 'tac_plus_key'
+set system login tacacs server 100.64.0.12 key 'tac_plus_key'
+
+commit
+```
+
+You can now log in via SSH or console using `admin/admin` credentials supplied
+by the container image.
diff --git a/docs/configuration/system/name-server.md b/docs/configuration/system/name-server.md
new file mode 100644
index 00000000..9090ba5f
--- /dev/null
+++ b/docs/configuration/system/name-server.md
@@ -0,0 +1,65 @@
+(system-dns)=
+
+# System DNS
+
+:::{warning}
+If you are configuring a VRF for management purposes, there is
+currently no way to force system DNS traffic via a specific VRF.
+:::
+
+This section describes configuring DNS on the system, namely:
+
+> - DNS name servers
+> - Domain search order
+
+## DNS name servers
+
+```{cfgcmd} set system name-server \<address\>
+
+Use this command to specify a DNS server for the system to be used
+for DNS lookups. More than one DNS server can be added, configuring
+one at a time. Both IPv4 and IPv6 addresses are supported.
+```
+
+
+### Example
+
+In this example, some *OpenNIC* servers are used, two IPv4 addresses
+and two IPv6 addresses:
+
+```none
+set system name-server 176.9.37.132
+set system name-server 195.10.195.195
+set system name-server 2a01:4f8:161:3441::1
+set system name-server 2a00:f826:8:2::195
+```
+
+
+## Domain search order
+
+In order for the system to use and complete unqualified host names, a
+list can be defined which will be used for domain searches.
+
+```{cfgcmd} set system domain-search \<domain\>
+
+Use this command to define domains, one at a time, so that the system
+uses them to complete unqualified host names. Maximum: 6 entries.
+```
+
+:::{note}
+Domain names can include letters, numbers, hyphens and periods
+with a maximum length of 253 characters.
+:::
+
+(name-server-domain-search-order-example)=
+
+### Example
+
+The system is configured to attempt domain completion in the following
+order: vyos.io (first), vyos.net (second) and vyos.network (last):
+
+```none
+set system domain-search vyos.io
+set system domain-search vyos.net
+set system domain-search vyos.network
+```
diff --git a/docs/configuration/system/option.md b/docs/configuration/system/option.md
new file mode 100644
index 00000000..c7a6ccf2
--- /dev/null
+++ b/docs/configuration/system/option.md
@@ -0,0 +1,190 @@
+(system-option)=
+
+# Option
+
+This chapter describe the possibilities of advanced system behavior.
+
+## General
+
+```{cfgcmd} set system option ctrl-alt-delete \<ignore | reboot | poweroff\>
+
+Action which will be run once the ctrl-alt-del keystroke is received.
+```
+
+```{cfgcmd} set system option reboot-on-panic
+
+Automatically reboot system on kernel panic after 60 seconds.
+```
+
+```{cfgcmd} set system option reboot-on-upgrade-failure \<timeout\>
+
+Automatically reboot after `timeout` minutes into the previous running
+image, that was used to perform the image upgrade.
+
+Reboot `timeout` is configurable in minutes. This gives the user the change
+to log into the system and perform some analysis before automatic rebooting.
+
+Automatic reboot can be cancelled after login using: {opcmd}`reboot cancel`
+```
+
+```{cfgcmd} set system option startup-beep
+
+Play an audible beep to the system speaker when system is ready.
+```
+
+```{cfgcmd} set system option root-partition-auto-resize
+
+Enables the root partition auto-extension and resizes to the maximum
+available space on system boot.
+```
+
+
+### Kernel
+
+```{cfgcmd} set system option kernel disable-mitigations
+
+Disable all optional CPU mitigations. This improves system performance,
+but it may also expose users to several CPU vulnerabilities.
+
+This will add the following option to the Kernel commandline:
+* ``mitigations=off``
+
+:::{note}
+Setting will only become active with the next reboot!
+:::
+```
+
+```{cfgcmd} set system option kernel disable-power-saving
+
+This will add the following two options to the Kernel commandline:
+* ``intel_idle.max_cstate=0`` Disable intel_idle and fall back on acpi_idle
+* ``processor.max_cstate=1`` Limit processor to maximum C-state 1
+
+:::{note}
+Setting will only become active with the next reboot!
+:::
+```
+
+```{cfgcmd} set system option kernel amd-pstate-driver \<mode\>
+
+Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs.
+
+The available modes are:
+* ``active`` This is the low-level firmware control mode based on the profile
+set and the system governor has no effect.
+* ``passive`` The driver allows the system governor to manage CPU frequency
+while providing available performance states.
+* ``guided`` The driver allows to set desired performance levels and the firmware
+selects a performance level in this range and fitting to the current workload.
+
+This will add the following two options to the Kernel commandline:
+* ``initcall_blacklist=acpi_cpufreq_init`` Disable default ACPI CPU frequency scale
+* ``amd_pstate={mode}`` Sets the p-state mode
+
+:::{note}
+Setting will only become active with the next reboot!
+:::
+
+:::{seealso}
+<https://docs.kernel.org/admin-guide/pm/amd-pstate.html>
+:::
+```
+
+```{cfgcmd} set system option kernel quiet
+
+Suppress most kernel messages during boot. This is useful for systems with
+embedded serial console interfaces to speed up the boot process.
+```
+
+
+## HTTP client
+
+```{cfgcmd} set system option http-client source-address \<address\>
+
+Several commands utilize cURL to initiate transfers. Configure the local
+source IPv4/IPv6 address used for all cURL operations.
+```
+
+```{cfgcmd} set system option http-client source-interface \<interface\>
+
+Several commands utilize curl to initiate transfers. Configure the local
+source interface used for all CURL operations.
+```
+
+:::{note}
+`source-address` and `source-interface` can not be used at the same
+time.
+:::
+
+## SSH client
+
+```{cfgcmd} set system option ssh-client source-address \<address\>
+
+Use the specified address on the local machine as the source address of the
+connection. Only useful on systems with more than one address.
+```
+
+```{cfgcmd} set system option ssh-client source-interface \<interface\>
+
+Use the address of the specified interface on the local machine as the
+source address of the connection.
+```
+
+
+## Keyboard Layout
+
+When starting a VyOS live system (the installation CD) the configured keyboard
+layout defaults to US. As this might not suite everyone's use case you can adjust
+the used keyboard layout on the system console.
+
+```{cfgcmd} set system option keyboard-layout \<us | fr | de | fi | no | dk\>
+
+Change system keyboard layout to given language.
+
+Defaults to ``us``.
+
+:::{note}
+Changing the keymap only has an effect on the system console, using
+SSH or Serial remote access to the device is not affected as the keyboard
+layout here corresponds to your access system.
+:::
+```
+
+(system-options-performance)=
+
+## Performance
+
+As more and more routers run on Hypervisors, expecially with a {abbr}`NOS
+(Network Operating System)` as VyOS, it makes fewer and fewer sense to use
+static resource bindings like `smp-affinity` as present in VyOS 1.2 and
+earlier to pin certain interrupt handlers to specific CPUs.
+
+We now utilize `tuned` for dynamic resource balancing based on profiles.
+
+:::{seealso}
+<https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf>
+:::
+
+```{cfgcmd} set system option performance \< throughput | latency \>
+
+Configure one of the predefined system performance profiles.
+
+* ``throughput``: A server profile focused on improving network throughput.
+  This profile favors performance over power savings by setting
+  ``intel_pstate`` and ``max_perf_pct=100`` and increasing kernel network
+  buffer sizes.
+
+  It enables transparent huge pages, and uses cpupower to set the performance
+  cpufreq governor. It also sets ``kernel.sched_min_granularity_ns`` to 10 us,
+  ``kernel.sched_wakeup_granularity_ns`` to 15 uss, and ``vm.dirty_ratio`` to
+  40%.
+
+* ``latency``: A server profile focused on lowering network latency.
+  This profile favors performance over power savings by setting
+  ``intel_pstate`` and ``min_perf_pct=100``.
+
+  It disables transparent huge pages, and automatic NUMA balancing. It also
+  uses cpupower to set the performance cpufreq governor, and requests a
+  cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to
+  50 us, and tcp_fastopen to 3.
+```
\ No newline at end of file
diff --git a/docs/configuration/system/proxy.md b/docs/configuration/system/proxy.md
new file mode 100644
index 00000000..286e835f
--- /dev/null
+++ b/docs/configuration/system/proxy.md
@@ -0,0 +1,27 @@
+(system-proxy)=
+
+# System Proxy
+
+Some IT environments require the use of a proxy to connect to the Internet.
+Without this configuration VyOS updates could not be installed directly by
+using the {opcmd}`add system image` command ({ref}`update_vyos`).
+
+```{cfgcmd} set system proxy url \<url\>
+
+Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and
+FTP (anonymous ftp).
+```
+```{cfgcmd} set system proxy port \<port\>
+
+Configure proxy port if it does not listen to the default port 80.
+```
+```{cfgcmd} set system proxy username \<username\>
+
+Some proxys require/support the "basic" HTTP authentication scheme as per
+{rfc}`7617`, thus a username can be configured.
+```
+```{cfgcmd} set system proxy password \<password\>
+
+Some proxys require/support the "basic" HTTP authentication scheme as per
+{rfc}`7617`, thus a password can be configured.
+```
\ No newline at end of file
diff --git a/docs/configuration/system/sflow.md b/docs/configuration/system/sflow.md
new file mode 100644
index 00000000..350bbdd8
--- /dev/null
+++ b/docs/configuration/system/sflow.md
@@ -0,0 +1,66 @@
+# sFlow
+
+VyOS supports sFlow accounting for both IPv4 and IPv6 traffic. The system acts as a flow exporter, and you are free to use it with any compatible collector.
+
+sFlow is a technology that enables monitoring of network traffic by sending sampled packets to a collector device.
+
+The sFlow accounting based on hsflowd <https://sflow.net/>
+
+## Configuration
+
+```{cfgcmd} set system sflow agent-address \<address\>
+
+Configure sFlow agent IPv4 or IPv6 address
+```
+```{cfgcmd} set system sflow agent-interface \<interface\>
+
+Configure agent IP address associated with this interface.
+```
+```{cfgcmd} set system sflow drop-monitor-limit \<limit\>
+
+   Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets
+```
+
+
+```{cfgcmd} set system sflow interface \<interface\>
+
+Configure and enable collection of flow information for the interface identified by \<interface\>.
+
+You can configure multiple interfaces which would participate in sflow accounting.
+```
+```{cfgcmd} set system sflow polling \<sec\>
+
+   Configure schedule counter-polling in seconds (default: 30)
+```
+
+
+```{cfgcmd} set system sflow sampling-rate \<rate\>
+
+Use this command to configure the sampling rate for sFlow accounting (default: 1000)
+```
+
+
+```{cfgcmd} set system sflow server \<address\> port \<port\>
+
+Configure address of sFlow collector. sFlow server at \<address\> can be both listening on an IPv4 or IPv6 address.
+```
+
+
+```{cfgcmd} set system sflow enable-egress
+
+Use this command to if you need to sample also egress traffic
+```
+
+## Example
+
+```none
+set system sflow agent-address '192.0.2.14'
+set system sflow agent-interface 'eth0'
+set system sflow drop-monitor-limit '50'
+set system sflow interface 'eth0'
+set system sflow interface 'eth1'
+set system sflow polling '30'
+set system sflow sampling-rate '1000'
+set system sflow server 192.0.2.1 port '6343'
+set system sflow server 203.0.113.23 port '6343'
+```
diff --git a/docs/configuration/system/sysctl.md b/docs/configuration/system/sysctl.md
new file mode 100644
index 00000000..90434fb2
--- /dev/null
+++ b/docs/configuration/system/sysctl.md
@@ -0,0 +1,16 @@
+(sysctl)=
+
+# Sysctl
+
+:::{note}
+This page is a stub and needs expansion. Contributions
+welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation).
+:::
+
+This chapter describes how to configure kernel parameters at runtime.
+
+`sysctl` is used to modify kernel parameters at runtime. The parameters
+available are those listed under /proc/sys/.
+
+```{cfgcmd} set system sysctl parameter \<parameter\> value \<value\>
+```
\ No newline at end of file
diff --git a/docs/configuration/system/syslog.md b/docs/configuration/system/syslog.md
new file mode 100644
index 00000000..ae30d272
--- /dev/null
+++ b/docs/configuration/system/syslog.md
@@ -0,0 +1,450 @@
+(syslog)=
+
+# Syslog
+
+## Overview
+
+By default, VyOS provides a minimal logging configuration with local storage
+and log rotation. All errors, including local7 messages, are saved to a local
+file. Emergency alerts are sent to the console.
+
+To change these settings, enter configuration mode.
+
+## Syslog configuration
+
+Syslog supports logging to multiple destinations: a local file, a console, or
+a remote syslog server over UDP or TCP.
+
+The syslog configuration is organized into the following categories:
+
+- Global settings
+- Local logging
+- Console logging
+- Remote logging
+- TLS-encrypted remote logging
+
+### Global settings
+
+Configure the general behavior of the syslog service.
+
+```{cfgcmd} set system syslog marker interval \<number\>
+
+**Configure the interval, in seconds, for sending syslog mark messages.**
+
+Syslog mark messages confirm the logging service is operational.
+
+Default: 1200 seconds.
+```
+
+```{cfgcmd} set system syslog marker disable
+
+Disable sending syslog mark messages.
+```
+
+```{cfgcmd} set system syslog preserve-fqdn
+
+**Configure how the logging device's hostname appears in log messages sent
+to a remote syslog server.**
+
+If configured, the device includes its {abbr}`FQDN (Fully Qualified Domain
+Name)` in log messages, even if the syslog server is in the same domain.
+```
+
+
+### Local logging
+
+Configure which log messages to save to a local log file.
+
+```{cfgcmd} set system syslog local \<filename\> facility \<keyword\> level \<keyword\>
+
+**Configure syslog to save log messages for a specific facility and
+severity level to \`\`/var/log/messages\`\`.**
+
+Refer to the tables below for valid facility and severity options.
+```
+
+(syslog-console)=
+
+### Console logging
+
+Configure which log messages to send to `/dev/console`.
+
+```{cfgcmd} set system syslog console facility \<keyword\> level \<keyword\>
+
+**Configure syslog to send log messages for a specific facility and severity
+level to the device's console.**
+
+Refer to the tables below for valid facility and severity options.
+```
+
+(syslog-remote)=
+
+### Remote logging
+
+Configure **remote logging** to send log messages to a remote syslog server.
+
+Remote logging does not affect either **local** or **console logging** and
+runs in parallel with them. Remote logging supports sending log messages
+to multiple hosts.
+
+```{cfgcmd} set system syslog remote \<address\> facility \<keyword\> level \<keyword\>
+
+**Configure log transmission to the remote syslog server for a specific
+facility and severity level.**
+
+The server’s address can be specified using either a {abbr}`FQDN (Fully
+Qualified Domain Name)` or an IP address.
+
+Refer to the tables below for valid facility and severity options.
+```
+
+```{cfgcmd} set system syslog remote \<address\> protocol \<udp | tcp\>
+
+**Configure the protocol for log transmission.**
+
+The protocol can be either UDP or TCP. By default, log messages are sent
+over UDP.
+```
+
+```{cfgcmd} set system syslog remote \<address\> port \<port\>
+
+**Configure the port for log transmission.**
+
+By default, the standard port 514 is used.
+```
+
+```{cfgcmd} set system syslog remote \<address\> format include-timezone
+
+**Configure log transmission in the RFC 5424 format.**
+
+The RFC 5424 format includes the timezone in the timestamp. For example:
+
+:::{code-block} none
+<34>1 2003-10-11T22:14:15.003-07:00 mymachine.example.com su - ID47 - BOM’su root’ failed for lonvick on /dev/pts/8.
+:::
+
+By default, log messages are sent in the RFC 3164 format. For example:
+
+:::{code-block} none
+<34>Oct 11 22:14:15 mymachine su: ‘su root’ failed for lonvick on /dev/pts/8
+:::
+```
+
+```{cfgcmd} set system syslog remote \<address\> format octet-counted
+
+**Enable octet-counted framing for log transmission.**
+
+When enabled, multi-line log messages are sent without splitting. Ensure
+the remote server supports octet-counted framing to avoid parsing errors.
+
+Octet-counted framing is not available for the UDP protocol.
+```
+
+```{cfgcmd} set system syslog remote \<address\> vrf \<name\>
+
+Configure the {abbr}`VRF (Virtual Routing and Forwarding)` instance
+for log transmission.
+```
+
+```{cfgcmd} set system syslog remote \<address\> source-address \<address\>
+
+Configure the source IP address (IPv4 or IPv6) for log transmission.
+```
+
+
+#### {abbr}`TLS (Transport Layer Security)`-encrypted remote logging
+
+VyOS supports {abbr}`TLS (Transport Layer Security)`-encrypted remote logging
+over TCP to ensure secure transmission of syslog data to remote syslog servers.
+
+**Prerequisites**: Before configuring {abbr}`TLS (Transport Layer
+Security)`-encrypted remote logging, ensure you have:
+- A valid remote syslog server address.
+- Valid {abbr}`CA (Certificate Authority)` and client certificates uploaded
+  to the local {abbr}`PKI (Public Key Infrastructure)` storage.
+- The **remote syslog transport protocol** is set to **TCP**:
+
+  ```none
+  set system syslog remote <address> protocol tcp
+  ```
+
+:::{note}
+{abbr}`TLS (Transport Layer Security)`-encrypted remote logging is
+**not supported** over **UDP**.
+:::
+```{cfgcmd} set system syslog remote \<address\> tls
+
+Enable TLS-encrypted remote logging.
+
+```
+
+```{cfgcmd} set system syslog remote \<address\> tls ca-certificate \<ca_name\>
+
+**Configure the** {abbr}`CA (Certificate Authority)` **certificate.**
+
+The syslog client uses the {abbr}`CA (Certificate Authority)` certificate to
+verify the identity of the remote syslog server.
+
+The {abbr}`CA (Certificate Authority)` certificate is required for **all**
+authentication modes except ``anon``.
+
+```
+
+```{cfgcmd} set system syslog remote \<address\> tls certificate \<cert_name\>
+
+**Configure the client certificate.**
+
+The remote syslog server uses the client certificate to verify the identity
+of the syslog client.
+
+The client certificate is required if the remote syslog server enforces
+client certificate verification.
+
+```
+
+````{cfgcmd} set system syslog remote \<address\> tls auth-mode \<anon | fingerprint | certvalid | name\>
+
+**Configure the authentication mode.**
+
+The authentication mode defines how the syslog client verifies the syslog
+server's identity.
+
+The following authentication modes are available:
+
+```{eval-rst}
+* ``anon`` **(default)**: Allows encrypted connections without verifying the syslog
+  server's identity. This mode is **not recommended**, as it is vulnerable to
+  :abbr:`MITM (Man-in-the-Middle)` attacks.
+* ``fingerprint``: Verifies the server’s certificate fingerprint against the
+  value preconfigured with:
+
+  .. code-block:: none
+
+     set system syslog remote <address> tls permitted-peer <peer>
+
+* ``certvalid``: Verifies the server certificate is signed by a trusted
+  :abbr:`CA (Certificate Authority)`, skipping :abbr:`CN (Common Name)` check.
+* ``name``: Verifies that:
+
+  * The server’s certificate is signed by a trusted :abbr:`CA (Certificate
+    Authority)`.
+  * The :abbr:`CN (Common Name)` in the certificate matches the value
+    preconfigured with:
+
+  .. code-block:: none
+
+     set system syslog remote <address> tls permitted-peer <peer>
+
+  This is a **recommended** secure mode for production environments.
+```
+
+````
+
+```{cfgcmd} set system syslog remote \<address\> tls permitted-peer \<peer\>
+
+**Configure the peer certificate identifiers.**
+
+The certificate identifier format depends on the authentication mode:
+* ``fingerprint``: Enter the expected certificate fingerprints (SHA-1 or
+SHA-256).
+* ``name``: Enter the expected certificate {abbr}`CNs (Common Names)`.
+
+For ``anon`` and ``certvalid`` authentication modes, certificate identifiers
+are not required.
+
+```
+
+#### Examples:
+
+```none
+# Example of 'anon' authentication mode
+set system syslog remote 10.10.2.3 facility all level debug
+set system syslog remote 10.10.2.3 port 6514
+set system syslog remote 10.10.2.3 protocol tcp
+set system syslog remote 10.10.2.3 tls auth-mode anon
+# or just use 'set system syslog remote 10.10.2.3 tls'
+
+# Example of 'certvalid' authentication mode
+set system syslog remote elk.example.com facility all level debug
+set system syslog remote elk.example.com port 6514
+set system syslog remote elk.example.com protocol tcp
+set system syslog remote elk.example.com tls ca-certificate my-ca
+set system syslog remote elk.example.com tls auth-mode certvalid
+
+# Example of 'fingerprint' authentication mode
+set system syslog remote syslog.example.com facility all level debug
+set system syslog remote syslog.example.com port 6514
+set system syslog remote syslog.example.com protocol tcp
+set system syslog remote syslog.example.com tls ca-certificate my-ca
+set system syslog remote syslog.example.com tls auth-mode fingerprint
+set system syslog remote syslog.example.com tls permitted-peers 'SHA1:10:C4:26:...,SHA256:7B:4B:10:...'
+
+# Example of 'name' authentication mode
+set system syslog remote graylog.example.com facility all level debug
+set system syslog remote graylog.example.com port 6514
+set system syslog remote graylog.example.com protocol tcp
+set system syslog remote graylog.example.com tls ca-certificate my-ca
+set system syslog remote graylog.example.com tls certificate syslog-client
+set system syslog remote graylog.example.com tls auth-mode name
+set system syslog remote graylog.example.com tls permitted-peers 'graylog.example.com'
+```
+
+#### Security recommendations
+
+- For secure deployments, always use the `name` authentication mode. It
+  ensures that the server is validated by a trusted {abbr}`CA (Certificate
+  Authority)` and that the hostname matches the certificate.
+- Use the `anon` authentication mode only in testing environments, as it
+  doesn't provide  server authentication.
+- Ensure private keys are generated, stored, and maintained exclusively within
+  the {doc}`PKI system </configuration/pki/index>`.
+(syslog_facilities)=
+
+## Syslog facilities
+
+This section lists facilities used by syslog. Most facility names are self-
+explanatory. The local0–local7 facilities are used for custom purposes, such as
+logging from network nodes and equipment. Facility assignment is flexible and
+should be tailored to your company's needs. Consider facilities as categorization
+tools, rather than strict directives.
+
+```{eval-rst}
++----------+----------+----------------------------------------------------+
+| Facility | Keyword  | Description                                        |
+| code     |          |                                                    |
++==========+==========+====================================================+
+|          | all      | All facilities                                     |
++----------+----------+----------------------------------------------------+
+| 0        | kern     | Kernel messages                                    |
++----------+----------+----------------------------------------------------+
+| 1        | user     | User-level messages                                |
++----------+----------+----------------------------------------------------+
+| 2        | mail     | Mail system                                        |
++----------+----------+----------------------------------------------------+
+| 3        | daemon   | System daemons                                     |
++----------+----------+----------------------------------------------------+
+| 4        | auth     | Security/authentication messages                   |
++----------+----------+----------------------------------------------------+
+| 5        | syslog   | Messages generated internally by syslog            |
++----------+----------+----------------------------------------------------+
+| 6        | lpr      | Line printer subsystem                             |
++----------+----------+----------------------------------------------------+
+| 7        | news     | Network news subsystem                             |
++----------+----------+----------------------------------------------------+
+| 8        | uucp     | UUCP subsystem                                     |
++----------+----------+----------------------------------------------------+
+| 9        | cron     | Clock daemon                                       |
++----------+----------+----------------------------------------------------+
+| 10       | security | Security/authentication messages                   |
++----------+----------+----------------------------------------------------+
+| 11       | ftp      | FTP daemon                                         |
++----------+----------+----------------------------------------------------+
+| 12       | ntp      | NTP subsystem                                      |
++----------+----------+----------------------------------------------------+
+| 13       | logaudit | Log audit                                          |
++----------+----------+----------------------------------------------------+
+| 14       | logalert | Log alert                                          |
++----------+----------+----------------------------------------------------+
+| 15       | clock    | clock daemon (note 2)                              |
++----------+----------+----------------------------------------------------+
+| 16       | local0   | local use 0 (local0)                               |
++----------+----------+----------------------------------------------------+
+| 17       | local1   | local use 1 (local1)                               |
++----------+----------+----------------------------------------------------+
+| 18       | local2   | local use 2 (local2)                               |
++----------+----------+----------------------------------------------------+
+| 19       | local3   | local use 3 (local3)                               |
++----------+----------+----------------------------------------------------+
+| 20       | local4   | local use 4 (local4)                               |
++----------+----------+----------------------------------------------------+
+| 21       | local5   | local use 5 (local5)                               |
++----------+----------+----------------------------------------------------+
+| 22       | local6   | local use 6 (local6)                               |
++----------+----------+----------------------------------------------------+
+| 23       | local7   | local use 7 (local7)                               |
++----------+----------+----------------------------------------------------+
+```
+
+(syslog_severity_level)=
+
+## Severity levels
+
+```{eval-rst}
++-------+---------------+---------+-------------------------------------------+
+| Value | Severity      | Keyword | Description                               |
++=======+===============+=========+===========================================+
+|       |               | all     | Log everything.                           |
++-------+---------------+---------+-------------------------------------------+
+| 0     | Emergency     | emerg   | System is unusable - a panic condition.   |
++-------+---------------+---------+-------------------------------------------+
+| 1     | Alert         | alert   | Action must be taken immediately - A      |
+|       |               |         | condition that should be corrected        |
+|       |               |         | immediately, such as a corrupted system   |
+|       |               |         | database.                                 |
++-------+---------------+---------+-------------------------------------------+
+| 2     | Critical      | crit    | Critical conditions - e.g., hard drive    |
+|       |               |         | errors.                                   |
++-------+---------------+---------+-------------------------------------------+
+| 3     | Error         | err     | Error conditions.                         |
++-------+---------------+---------+-------------------------------------------+
+| 4     | Warning       | warning | Warning conditions.                       |
++-------+---------------+---------+-------------------------------------------+
+| 5     | Notice        | notice  | Normal but significant conditions -       |
+|       |               |         | conditions that are not error conditions, |
+|       |               |         | but that may require special handling.    |
++-------+---------------+---------+-------------------------------------------+
+| 6     | Informational | info    | Informational messages.                   |
++-------+---------------+---------+-------------------------------------------+
+| 7     | Debug         | debug   | Debug-level messages - Messages that      |
+|       |               |         | contain information normally of use only  |
+|       |               |         | when debugging a program.                 |
++-------+---------------+---------+-------------------------------------------+
+```
+
+## Display logs
+
+```{opcmd} show log [all | authorization | cluster | conntrack-sync | ...]
+
+**Display logs for a specific category on the console.**
+
+Use tab completion to view a list of available categories.
+
+If no category is specified, all logs are shown.
+
+```
+
+````{opcmd} show log image \<name\> [all | authorization | directory | file \<file name\> | tail \<lines\>]
+
+**Display logs for a specific image on the console.**
+
+Available log categories:
+
+```{eval-rst}
+.. list-table::
+   :widths: 25 75
+   :header-rows: 0
+
+   * - all
+     - Displays the contents of system log files of the specified image.
+   * - authorization
+     - Displays authorization attempts of the specified image.
+   * - directory
+     - Displays user-defined log files of the specified image.
+   * - file <file name>
+     - Displays the contents of a specified user-defined log file of the specified
+       image.
+   * - tail
+     - Displays last lines of the system log of the specified image.
+   * - <lines>
+     - Number of lines to be displayed, default 10.
+```
+
+````
+
+If no category is specified, the contents of the main syslog file are
+displayed.
+
+:::{hint}
+Use `show log | strip-private` to hide private data
+when displaying your logs.
+:::
diff --git a/docs/configuration/system/task-scheduler.md b/docs/configuration/system/task-scheduler.md
new file mode 100644
index 00000000..94ca9f4d
--- /dev/null
+++ b/docs/configuration/system/task-scheduler.md
@@ -0,0 +1,45 @@
+(task-scheduler)=
+
+# Task Scheduler
+
+The task scheduler allows you to execute tasks on a given schedule. It makes
+use of UNIX [cron].
+
+:::{note}
+All scripts executed this way are executed as root user - this may
+be dangerous. Together with {ref}`command-scripting` this can be used for
+automating (re-)configuration.
+:::
+
+```{cfgcmd} set system task-scheduler task \<task\> interval \<interval\>
+
+Specify the time interval when `<task>` should be executed. The interval
+is specified as number with one of the following suffixes:
+* ``none`` - Execution interval in minutes
+* ``m`` - Execution interval in minutes
+* ``h`` - Execution interval in hours
+* ``d`` - Execution interval in days
+
+:::{note}
+If suffix is omitted, minutes are implied.
+:::
+```
+
+```{cfgcmd} set system task-scheduler task \<task\> crontab-spec \<spec\>
+
+Set execution time in common cron time format. A cron `<spec>` of
+``30 */6 * * *`` would execute the `<task>` at minute 30 past every 6th hour.
+```
+
+```{cfgcmd} set system task-scheduler task \<task\> executable path \<path\>
+
+Specify absolute `<path>` to script which will be run when `<task>` is
+executed.
+```
+
+```{cfgcmd} set system task-scheduler task \<task\> executable arguments \<args\>
+
+Arguments which will be passed to the executable.
+```
+
+[cron]: https://en.wikipedia.org/wiki/Cron
diff --git a/docs/configuration/system/time-zone.md b/docs/configuration/system/time-zone.md
new file mode 100644
index 00000000..2279a773
--- /dev/null
+++ b/docs/configuration/system/time-zone.md
@@ -0,0 +1,17 @@
+(timezone)=
+
+# Time Zone
+
+Time Zone setting is very important as e.g all your logfile entries will be
+based on the configured zone. Without proper time zone configuration it will
+be very difficult to compare logfiles from different systems.
+
+```{cfgcmd} set system time-zone \<timezone\>
+
+Specify the systems \<timezone\> as the Region/Location that best defines
+your location. For example, specifying US/Pacific sets the time zone to US
+Pacific time.
+
+Command completion can be used to list available time zones. The adjustment
+for daylight time will take place automatically based on the time of year.
+```
\ No newline at end of file
diff --git a/docs/configuration/system/updates.md b/docs/configuration/system/updates.md
new file mode 100644
index 00000000..c82d37be
--- /dev/null
+++ b/docs/configuration/system/updates.md
@@ -0,0 +1,36 @@
+# Updates
+
+VyOS supports online checking for updates
+
+## Configuration
+
+```{cfgcmd} set system update-check auto-check
+
+Configure auto-checking for new images
+```
+
+```{cfgcmd} set system update-check url \<url\>
+
+Configure a URL that contains information about images.
+```
+
+
+## Example
+
+```none
+set system update-check auto-check
+set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json'
+```
+
+Check:
+
+```none
+vyos@r4:~$ show system updates
+Current version: 1.5-rolling-202312220023
+
+Update available: 1.5-rolling-202312250024
+Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso
+vyos@r4:~$
+
+vyos@r4:~$ add system image latest
+```
diff --git a/docs/configuration/system/watchdog.md b/docs/configuration/system/watchdog.md
new file mode 100644
index 00000000..700051a6
--- /dev/null
+++ b/docs/configuration/system/watchdog.md
@@ -0,0 +1,212 @@
+(system-watchdog)=
+
+# Watchdog
+
+VyOS supports hardware watchdog timers to automatically reboot the system if
+it becomes unresponsive. This is particularly useful for remote or embedded
+systems where physical access is limited.
+
+A watchdog timer is a hardware or software mechanism that automatically resets
+the system if the operating system stops responding within a configured timeout
+period. The system will periodically notify the watchdog that it is still
+running. If the watchdog is not notified within the timeout period, the watchdog
+will reset the system.
+
+## Configuration
+
+The watchdog feature is configured under the `system watchdog` configuration
+tree. The presence of the `system watchdog` node enables the watchdog feature.
+
+```{cfgcmd} set system watchdog
+
+Enable watchdog support.
+
+The watchdog is enabled only when a watchdog device is available as
+``/dev/watchdog0``.
+
+:::{note}
+If multiple watchdog devices are present, only the first watchdog
+device is supported (VyOS uses ``/dev/watchdog0`` only).
+:::
+If ``/dev/watchdog0`` does not exist and no module is configured, commit will
+fail. If a module is configured but ``/dev/watchdog0`` still cannot be
+created, VyOS will emit a warning and will not enable the systemd watchdog.
+```
+
+```{cfgcmd} set system watchdog module \<module-name\>
+
+Specify the kernel watchdog driver module to load for ``/dev/watchdog0``.
+
+The configured module must be a watchdog driver module, not an arbitrary
+kernel module.
+
+**In most cases, this option is not required** as the kernel will
+automatically load the appropriate watchdog driver for your system. Use this
+option if the kernel fails to load the required driver, or when you want to
+use the software watchdog (``softdog``).
+
+Common modules include:
+* ``softdog`` - Software watchdog timer (available on all systems)
+* ``iTCO_wdt`` - Intel TCO watchdog timer
+* ``sp5100_tco`` - AMD SP5100 TCO watchdog timer
+* ``i6300esb`` - Intel 6300ESB watchdog timer
+* ``ipmi_watchdog`` - IPMI watchdog timer
+
+:::{warning}
+``softdog`` is not a hardware watchdog. It is implemented using
+kernel timers and therefore depends on the Linux kernel continuing to run.
+In some fault conditions (for example, a kernel hang), ``softdog`` may not
+be able to trigger a reset.
+
+Prefer a hardware watchdog driver whenever possible, as hardware watchdogs
+can operate independently of the operating system.
+:::
+
+If no module is specified, VyOS will use an existing ``/dev/watchdog0``
+device if available.
+
+:::{note}
+If a module is specified but a different driver is actually bound
+to ``watchdog0``, VyOS will emit a warning during commit.
+:::
+Example:
+
+:::{code-block} none
+set system watchdog module softdog
+:::
+```
+
+```{cfgcmd} set system watchdog timeout \<seconds\>
+:defaultvalue:
+
+Set the watchdog timeout for normal runtime operation in seconds.
+
+Valid range: 1-65535 seconds
+
+:::{note}
+Some watchdog drivers expose minimum and maximum supported runtime
+timeouts via sysfs. When available, VyOS validates ``timeout`` against
+those driver limits during commit.
+:::
+
+This is the interval during which the system must respond to the watchdog.
+If the system does not respond within this time, the watchdog will trigger
+a reboot.
+
+Example:
+
+:::{code-block} none
+set system watchdog timeout 30
+:::
+```
+
+```{cfgcmd} set system watchdog shutdown-timeout \<seconds\>
+:defaultvalue:
+
+Set the watchdog timeout during system shutdown in seconds.
+
+Valid range: 60-65535 seconds
+
+This extended timeout allows the system to complete a graceful shutdown
+without triggering the watchdog.
+
+:::{warning}
+Setting this value too low (below 120 seconds) may cause
+unclean shutdowns, as the system may not have enough time to properly
+stop all services and flush disk buffers. The recommended minimum value
+is 120 seconds.
+:::
+Example:
+
+:::{code-block} none
+set system watchdog shutdown-timeout 180
+:::
+```
+
+```{cfgcmd} set system watchdog reboot-timeout \<seconds\>
+:defaultvalue:
+
+Set the watchdog timeout during system reboot in seconds.
+
+Valid range: 60-65535 seconds
+
+This extended timeout allows the system to complete the reboot process
+without triggering the watchdog during the transition.
+
+:::{warning}
+Setting this value too low (below 120 seconds) may cause
+unclean reboots, as the system may not have enough time to properly
+stop all services before restarting. The recommended minimum value
+is 120 seconds.
+:::
+Example:
+
+:::{code-block} none
+set system watchdog reboot-timeout 180
+:::
+```
+
+
+## Examples
+
+### Basic Configuration with Software Watchdog
+
+This example configures a basic software watchdog with default timeouts:
+
+```none
+set system watchdog module softdog
+```
+
+This will:
+- Enable the watchdog feature
+- Load the `softdog` kernel module
+- Use a 10-second runtime timeout (default)
+- Use 120-second shutdown and reboot timeouts (default)
+
+### Advanced Configuration
+
+This example shows a more customized configuration suitable for a production
+system:
+
+```none
+set system watchdog module iTCO_wdt
+set system watchdog timeout 30
+set system watchdog shutdown-timeout 300
+set system watchdog reboot-timeout 300
+```
+
+This configuration:
+
+- Enables the watchdog feature
+- Loads the Intel TCO hardware watchdog module
+- Sets a 30-second runtime timeout
+- Allows 5 minutes for shutdown and reboot operations
+
+## Best Practices
+
+- **Start with conservative timeouts**: Use longer timeouts initially and
+  reduce them as you gain confidence in system stability.
+- **Test before deployment**: Verify the watchdog works as expected in a
+  non-production environment before deploying to production systems.
+- **Choose appropriate modules**: Use hardware watchdog modules (like
+  `iTCO_wdt`) when available, as they are more reliable than software
+  watchdogs.
+- **Consider shutdown time**: Set `shutdown-timeout` and `reboot-timeout`
+  values high enough to allow for normal shutdown procedures, especially on
+  systems with many services or slow storage.
+- **Monitor watchdog events**: Check system logs after any unexpected reboots
+  to determine if the watchdog triggered the reboot.
+- **Remote systems**: For systems without physical console access, use
+  conservative timeout values to avoid false-positive reboots during high
+  load conditions.
+
+:::{note}
+The watchdog configuration takes effect immediately after commit,
+but systemd must be reloaded. This happens automatically during commit.
+:::
+
+:::{warning}
+Incorrect watchdog configuration on remote systems can result
+in unexpected reboots. Always test watchdog settings in a controlled
+environment before deploying to production systems.
+:::
diff --git a/docs/configuration/trafficpolicy/index.md b/docs/configuration/trafficpolicy/index.md
new file mode 100644
index 00000000..01a820a9
--- /dev/null
+++ b/docs/configuration/trafficpolicy/index.md
@@ -0,0 +1,1299 @@
+(qos)=
+
+# Traffic Policy
+
+## QoS
+
+The generic name of Quality of Service or Traffic Control involves
+things like shaping traffic, scheduling or dropping packets, which
+are the kind of things you may want to play with when you have, for
+instance, a bandwidth bottleneck in a link and you want to somehow
+prioritize some type of traffic over another.
+
+[tc] is a powerful tool for Traffic Control found at the Linux kernel.
+However, its configuration is often considered a cumbersome task.
+Fortunately, VyOS eases the job through its CLI, while using `tc` as
+backend.
+
+### How to make it work
+
+In order to have VyOS Traffic Control working you need to follow 2
+steps:
+
+> 1. **Create a traffic policy**.
+> 2. **Apply the traffic policy to an interface ingress or egress**.
+
+But before learning to configure your policy, we will warn you
+about the different units you can use and also show you what *classes*
+are and how they work, as some policies may require you to configure
+them.
+
+### Units
+
+When configuring your traffic policy, you will have to set data rate
+values, watch out the units you are managing, it is easy to get confused
+with the different prefixes and suffixes you can use. VyOS will always
+show you the different units you can use.
+
+#### Prefixes
+
+They can be **decimal** prefixes.
+
+```{eval-rst}
+   .. code-block:: none
+
+    kbit  (10^3)    kilobit per second
+    mbit  (10^6)    megabit per second
+    gbit  (10^9)    gigabit per second
+    tbit  (10^12)   terabit per second
+
+    kbps  (8*10^3)  kilobyte per second
+    mbps  (8*10^6)  megabyte per second
+    gbps  (8*10^9)  gigabyte per second
+    tbps  (8*10^12) terabyte per second
+```
+
+Or **binary** prefixes.
+
+```{eval-rst}
+   .. code-block:: none
+
+    kibit (2^10 = 1024)    kibibit per second
+    mibit (2^20 = 1024^2)  mebibit per second
+    gibit (2^30 = 1024^3)  gibibit per second
+    tbit  (2^40 = 1024^4)  tebibit per second
+
+    kibps (1024*8)         kibibyte (KiB) per second
+    mibps (1024^2*8)       mebibyte (MiB) per second
+    gibps (1024^3*8)       gibibyte (GiB) per second
+    tibps (1024^4*8)       tebibyte (TiB) per second
+```
+
+
+#### Suffixes
+
+A *bit* is written as **bit**,
+
+```{eval-rst}
+   .. code-block:: none
+
+        kbit (kilobits per second)
+        mbit (megabits per second)
+        gbit (gigabits per second)
+        tbit (terabits per second)
+```
+
+while a *byte* is written as a single **b**.
+
+```{eval-rst}
+   .. code-block:: none
+
+        kbps (kilobytes per second)
+        mbps (megabytes per second)
+        gbps (gigabytes per second)
+```
+
+(classes)=
+
+### Classes
+
+In the {ref}`creating_a_traffic_policy` section you will see that
+some of the policies use *classes*. Those policies let you distribute
+traffic into different classes according to different parameters you can
+choose. So, a class is just a specific type of traffic you select.
+
+The ultimate goal of classifying traffic is to give each class a
+different treatment.
+
+#### Matching traffic
+
+In order to define which traffic goes into which class, you define
+filters (that is, the matching criteria). Packets go through these matching
+rules (as in the rules of a firewall) and, if a packet matches the filter, it
+is assigned to that class.
+
+In VyOS, a class is identified by a number you can choose when
+configuring it.
+
+:::{note}
+The meaning of the Class ID is not the same for every type of
+policy. Normally policies just need a meaningless number to identify
+a class (Class ID), but that does not apply to every policy.
+The number of a class in a Priority Queue it does not only
+identify it, it also defines its priority.
+:::
+```none
+set qos policy <policy> <policy-name> class <class-ID> match <class-matching-rule-name>
+```
+
+In the command above, we set the type of policy we are going to
+work with and the name we choose for it; a class (so that we can
+differentiate some traffic) and an identifiable number for that class;
+then we configure a matching rule (or filter) and a name for it.
+
+A class can have multiple match filters:
+
+```none
+set qos policy shaper MY-SHAPER class 30 match HTTP
+set qos policy shaper MY-SHAPER class 30 match HTTPs
+```
+
+A match filter can contain multiple criteria and will match traffic if
+all those criteria are true.
+
+For example:
+
+```none
+set qos policy shaper MY-SHAPER class 30 match HTTP ip protocol tcp
+set qos policy shaper MY-SHAPER class 30 match HTTP ip source port 80
+```
+
+This will match TCP traffic with source port 80.
+
+There are many parameters you will be able to use in order to match the
+traffic you want for a class:
+
+> - **Ethernet (protocol, destination address or source address)**
+> - **Interface name**
+> - **IPv4 (DSCP value, maximum packet length, protocol, source address,**
+>   **destination address, source port, destination port or TCP flags)**
+> - **IPv6 (DSCP value, maximum payload length, protocol, source address,**
+>   **destination address, source port, destination port or TCP flags)**
+> - **Firewall mark**
+> - **VLAN ID**
+
+When configuring your filter, you can use the `Tab` key to see the many
+different parameters you can configure.
+
+```none
+vyos@vyos# set qos policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER 
+Possible completions:
+   description  Description
+ > ether        Ethernet header match
+   interface    Interface to use
+ > ip           Match IP protocol header
+ > ipv6         Match IPV6 protocol header
+   mark         Match on mark applied by firewall
+   vif          Virtual Local Area Network (VLAN) ID for this match
+```
+
+As shown in the example above, one of the possibilities to match packets
+is based on marks done by the firewall,
+[that can give you a great deal of flexibility].
+
+You can also write a description for a filter:
+
+```none
+set qos policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description"
+```
+:::{note}
+An IPv4 TCP filter will only match packets with an IPv4 header
+length of 20 bytes (which is the majority of IPv4 packets anyway).
+:::
+
+:::{note}
+IPv6 TCP filters will only match IPv6 packets with no header
+extension, see <https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers>
+:::
+
+#### Traffic Match Group
+
+In some case where we need to have an organization of our matching selection,
+in order to be more flexible and organize with our filter definition. We can
+apply traffic match groups, allowing us to create distinct filter groups within
+our policy and define various parameters for each group:
+
+```none
+set qos traffic-match-group <group_name> match <match_name>
+Possible completions:
+   description          Description
+ > ip                   Match IP protocol header
+ > ipv6                 Match IPv6 protocol header
+   mark                 Match on mark applied by firewall
+   vif                  Virtual Local Area Network (VLAN) ID for this match
+```
+
+inherit matches from another group
+
+```none
+set qos traffic-match-group <group_name> match-group <match_group_name>
+```
+
+A match group can contain multiple criteria and inherit them in the same policy.
+
+For example:
+
+```none
+set qos traffic-match-group Mission-Critical match AF31 ip dscp 'AF31'
+set qos traffic-match-group Mission-Critical match AF32 ip dscp 'AF42'
+set qos traffic-match-group Mission-Critical match CS3 ip dscp 'CS3'
+set qos traffic-match-group Streaming-Video match AF11 ip dscp 'AF11'
+set qos traffic-match-group Streaming-Video match AF41 ip dscp 'AF41'
+set qos traffic-match-group Streaming-Video match AF43 ip dscp 'AF43'
+set qos policy shaper VyOS-HTB class 10 bandwidth '30%'
+set qos policy shaper VyOS-HTB class 10 description 'Multimedia'
+set qos policy shaper VyOS-HTB class 10 match CS4 ip dscp 'CS4'
+set qos policy shaper VyOS-HTB class 10 match-group 'Streaming-Video'
+set qos policy shaper VyOS-HTB class 10 priority '1'
+set qos policy shaper VyOS-HTB class 10 queue-type 'fair-queue'
+set qos policy shaper VyOS-HTB class 20 description 'MC'
+set qos policy shaper VyOS-HTB class 20 match-group 'Mission-Critical'
+set qos policy shaper VyOS-HTB class 20 priority '2'
+set qos policy shaper VyOS-HTB class 20 queue-type 'fair-queue'
+set qos policy shaper VyOS-HTB default bandwidth '20%'
+set qos policy shaper VyOS-HTB default queue-type 'fq-codel'
+```
+
+In this example, we can observe that different DSCP criteria are defined based
+on our QoS configuration within the same policy group.
+
+#### Default
+
+Often you will also have to configure your *default* traffic in the same
+way you do with a class. *Default* can be considered a class as it
+behaves like that. It contains any traffic that did not match any
+of the defined classes, so it is like an open class, a class without
+matching filters.
+
+#### Class treatment
+
+Once a class has a filter configured, you will also have to define what
+you want to do with the traffic of that class, what specific
+Traffic-Control treatment you want to give it. You will have different
+possibilities depending on the Traffic Policy you are configuring.
+
+```none
+vyos@vyos# set qos policy shaper MY-SHAPER class 30
+Possible completions:
+   bandwidth    Available bandwidth for this policy (default: auto)
+   burst        Burst size for this class (default: 15k)
+   ceiling      Bandwidth limit for this class
+   codel-quantum
+                Deficit in the fair queuing algorithm (default 1514)
+   description  Description
+   flows        Number of flows into which the incoming packets are classified(default 1024)
+   interval     Interval used to measure the delay (default 100)
++> match        Class matching rule name
+   priority     Priority for rule evaluation
+   queue-limit  Maximum queue size
+   queue-type   Queue type for default traffic (default: fq-codel)
+   set-dscp     Change the Differentiated Services (DiffServ) field in the IP header
+   target       Acceptable minimum standing/persistent queue delay (default: 5)
+```
+
+For instance, with {code}`set qos policy shaper MY-SHAPER
+class 30 set-dscp EF` you would be modifying the DSCP field value of packets in
+that class to Expedite Forwarding.
+
+> DSCP values as per {rfc}`2474` and {rfc}`4595`:
+>
+> | Binary value | Configured value | Drop rate | Description                  |
+> | ------------ | ---------------- | --------- | ---------------------------- |
+> | 101110       | 46               | -         | Expedited forwarding (EF)    |
+> | 000000       | 0                | -         | Best effort traffic, default |
+> | 001010       | 10               | Low       | Assured Forwarding(AF) 11    |
+> | 001100       | 12               | Medium    | Assured Forwarding(AF) 12    |
+> | 001110       | 14               | High      | Assured Forwarding(AF) 13    |
+> | 010010       | 18               | Low       | Assured Forwarding(AF) 21    |
+> | 010100       | 20               | Medium    | Assured Forwarding(AF) 22    |
+> | 010110       | 22               | High      | Assured Forwarding(AF) 23    |
+> | 011010       | 26               | Low       | Assured Forwarding(AF) 31    |
+> | 011100       | 28               | Medium    | Assured Forwarding(AF) 32    |
+> | 011110       | 30               | High      | Assured Forwarding(AF) 33    |
+> | 100010       | 34               | Low       | Assured Forwarding(AF) 41    |
+> | 100100       | 36               | Medium    | Assured Forwarding(AF) 42    |
+> | 100110       | 38               | High      | Assured Forwarding(AF) 43    |
+
+(embed)=
+
+#### Embedding one policy into another one
+
+Often we need to embed one policy into another one. It is possible to do
+so on classful policies, by attaching a new policy into a class. For
+instance, you might want to apply different policies to the different
+classes of a Round-Robin policy you have configured.
+
+A common example is the case of some policies which, in order to be
+effective, they need to be applied to an interface that is directly
+connected where the bottleneck is. If your router is not
+directly connected to the bottleneck, but some hop before it, you can
+emulate the bottleneck by embedding your non-shaping policy into a
+classful shaping one so that it takes effect.
+
+You can configure a policy into a class through the `queue-type`
+setting.
+
+```none
+set qos policy shaper FQ-SHAPER bandwidth 4gbit
+set qos policy shaper FQ-SHAPER default bandwidth 100%
+set qos policy shaper FQ-SHAPER default queue-type fq-codel
+```
+
+As shown in the last command of the example above, the `queue-type`
+setting allows these combinations. You will be able to use it
+in many policies.
+
+:::{note}
+Some policies already include other embedded policies inside.
+That is the case of Shaper: each of its classes use fair-queue
+unless you change it.
+:::
+
+(creating_a_traffic_policy)=
+
+### Creating a traffic policy
+
+VyOS lets you control traffic in many different ways, here we will cover
+every possibility. You can configure as many policies as you want, but
+you will only be able to apply one policy per interface and direction
+(inbound or outbound).
+
+Some policies can be combined, you will be able to embed a different
+policy that will be applied to a class of the main policy.
+
+:::{hint}
+**If you are looking for a policy for your outbound traffic**
+but you don't know which one you need and you don't want to go
+through every possible policy shown here, **our bet is that highly
+likely you are looking for a** Shaper **policy and you want to**
+{ref}`set its queues <embed>` **as FQ-CoDel**.
+:::
+
+#### Drop Tail
+
+```{eval-rst}
+| **Queueing discipline:** PFIFO (Packet First In First Out).
+| **Applies to:** Outbound traffic.
+```
+
+This the simplest queue possible you can apply to your traffic. Traffic
+must go through a finite queue before it is actually sent. You must
+define how many packets that queue can contain.
+
+When a packet is to be sent, it will have to go through that queue, so
+the packet will be placed at the tail of it. When the packet completely
+goes through it, it will be dequeued emptying its place in the queue and
+being eventually handed to the NIC to be actually sent out.
+
+Despite the Drop-Tail policy does not slow down packets, if many packets
+are to be sent, they could get dropped when trying to get enqueued at
+the tail. This can happen if the queue has still not been able to
+release enough packets from its head.
+
+This is the policy that requires the lowest resources for the same
+amount of traffic. But **very likely you do not need it as you cannot
+get much from it. Sometimes it is used just to enable logging.**
+
+```{cfgcmd} set qos policy drop-tail \<policy-name\> queue-limit \<number-of-packets\>
+
+Use this command to configure a drop-tail policy (PFIFO). Choose a
+unique name for this policy and the size of the queue by setting the
+number of packets it can contain (maximum 4294967295).
+
+```
+
+#### Fair Queue
+
+```{eval-rst}
+| **Queueing discipline:** SFQ (Stochastic Fairness Queuing).
+| **Applies to:** Outbound traffic.
+```
+
+Fair Queue is a work-conserving scheduler which schedules the
+transmission of packets based on flows, that is, it balances traffic
+distributing it through different sub-queues in order to ensure
+fairness so that each flow is able to send data in turn, preventing any
+single one from drowning out the rest.
+
+```{cfgcmd} set qos policy fair-queue \<policy-name\>
+
+   Use this command to create a Fair-Queue policy and give it a name.
+   It is based on the Stochastic Fairness Queueing and can be applied to
+   outbound traffic.
+
+```
+
+In order to separate traffic, Fair Queue uses a classifier based on
+source address, destination address and source port. The algorithm
+enqueues packets to hash buckets based on those tree parameters.
+Each of these buckets should represent a unique flow. Because multiple
+flows may get hashed to the same bucket, the hashing algorithm is
+perturbed at configurable intervals so that the unfairness lasts only
+for a short while. Perturbation may however cause some inadvertent
+packet reordering to occur. An advisable value could be 10 seconds.
+
+
+One of the uses of Fair Queue might be the mitigation of Denial of
+Service attacks.
+
+```{cfgcmd} set qos policy fair-queue \<policy-name\> hash-interval \<seconds\>
+
+Use this command to define a Fair-Queue policy, based on the
+Stochastic Fairness Queueing, and set the number of seconds at which
+a new queue algorithm perturbation will occur (maximum 4294967295).
+```
+
+When dequeuing, each hash-bucket with data is queried in a round robin
+fashion. You can configure the length of the queue.
+
+```{cfgcmd} set qos policy fair-queue \<policy-name\> queue-limit \<limit\>
+
+Use this command to define a Fair-Queue policy, based on the
+Stochastic Fairness Queueing, and set the number of maximum packets
+allowed to wait in the queue. Any other packet will be dropped.
+```
+:::{note}
+Fair Queue is a non-shaping (work-conserving) policy, so it
+will only be useful if your outgoing interface is really full. If it
+is not, VyOS will not own the queue and Fair Queue will have no
+effect. If there is bandwidth available on the physical link, you can
+embed Fair-Queue into a classful shaping policy to make sure it owns
+the queue.
+:::
+
+
+(fq-codel)=
+
+
+#### FQ-CoDel
+
+
+```{eval-rst}
+| **Queueing discipline:** Fair/Flow Queue CoDel.
+| **Applies to:** Outbound Traffic.
+```
+
+
+The FQ-CoDel policy distributes the traffic into 1024 FIFO queues and
+tries to provide good service between all of them. It also tries to keep
+the length of all the queues short.
+
+
+FQ-CoDel fights bufferbloat and reduces latency without the need of
+complex configurations. It has become the new default Queueing
+Discipline for the interfaces of some GNU/Linux distributions.
+
+
+It uses a stochastic model to classify incoming packets into
+different flows and is used to provide a fair share of the bandwidth to
+all the flows using the queue. Each flow is managed by the CoDel
+queuing discipline. Reordering within a flow is avoided since Codel
+internally uses a FIFO queue.
+
+
+FQ-CoDel is based on a modified Deficit Round Robin (DRR) queue
+scheduler with the CoDel Active Queue Management (AQM) algorithm
+operating on each queue.
+
+
+:::{note}
+FQ-Codel is a non-shaping (work-conserving) policy, so it
+will only be useful if your outgoing interface is really full. If it
+is not, VyOS will not own the queue and FQ-Codel will have no
+effect. If there is bandwidth available on the physical link, you can
+embed FQ-Codel into a classful shaping policy to make sure it owns
+the queue. If you are not sure if you need to embed your FQ-CoDel
+policy into a Shaper, do it.
+:::
+
+
+FQ-CoDel is tuned to run ok with its default parameters at 10Gbit
+speeds. It might work ok too at other speeds without configuring
+anything, but here we will explain some cases when you might want to
+tune its parameters.
+
+
+When running it at 1Gbit and lower, you may want to reduce the
+`queue-limit` to 1000 packets or less. In rates like 10Mbit, you may
+want to set it to 600 packets.
+
+
+If you are using FQ-CoDel embedded into Shaper and you have large rates
+(100Mbit and above), you may consider increasing `quantum` to 8000 or
+higher so that the scheduler saves CPU.
+
+
+On low rates (below 40Mbit) you may want to tune `quantum` down to
+something like 300 bytes.
+
+
+At very low rates (below 3Mbit), besides tuning `quantum` (300 keeps
+being ok) you may also want to increase `target` to something like 15ms
+and increase `interval` to something around 150 ms.
+
+```{cfgcmd} set qos policy fq-codel \<policy name\> codel-quantum \<bytes\>
+
+Use this command to configure an fq-codel policy, set its name and
+the maximum number of bytes (default: 1514) to be dequeued from a
+queue at once.
+```
+
+```{cfgcmd} set qos policy fq-codel \<policy name\> flows \<number-of-flows\>
+
+Use this command to configure an fq-codel policy, set its name and
+the number of sub-queues (default: 1024) into which packets are
+classified.
+```
+
+```{cfgcmd} set qos policy fq-codel \<policy name\> interval \<milliseconds\>
+
+Use this command to configure an fq-codel policy, set its name and
+the time period used by the control loop of CoDel to detect when a
+persistent queue is developing, ensuring that the measured minimum
+delay does not become too stale (default: 100ms).
+```
+
+```{cfgcmd} set qos policy fq-codel \<policy-name\> queue-limit \<number-of-packets\>
+
+Use this command to configure an fq-codel policy, set its name, and
+define a hard limit on the real queue size. When this limit is
+reached, new packets are dropped (default: 10240 packets).
+```
+
+```{cfgcmd} set qos policy fq-codel \<policy-name\> target \<milliseconds\>
+
+Use this command to configure an fq-codel policy, set its name, and
+define the acceptable minimum standing/persistent queue delay. This
+minimum delay is identified by tracking the local minimum queue delay
+that packets experience (default: 5ms).
+```
+
+##### Example
+
+A simple example of an FQ-CoDel policy working inside a Shaper one.
+
+```none
+set qos policy shaper FQ-CODEL-SHAPER bandwidth 2gbit
+set qos policy shaper FQ-CODEL-SHAPER default bandwidth 100%
+set qos policy shaper FQ-CODEL-SHAPER default queue-type fq-codel
+```
+
+#### Limiter
+
+```{eval-rst}
+| **Queueing discipline:** Ingress policer.
+| **Applies to:** Inbound traffic.
+```
+
+Limiter is one of those policies that uses classes (Ingress qdisc is
+actually a classless policy but filters do work in it).
+
+The limiter performs basic ingress policing of traffic flows. Multiple
+classes of traffic can be defined and traffic limits can be applied to
+each class. Although the policer uses a token bucket mechanism
+internally, it does not have the capability to delay a packet as a
+shaping mechanism does. Traffic exceeding the defined bandwidth limits
+is directly dropped. A maximum allowed burst can be configured too.
+
+You can configure classes (up to 4090) with different settings and a
+default policy which will be applied to any traffic not matching any of
+the configured classes.
+
+:::{note}
+In the case you want to apply some kind of **shaping** to your
+**inbound** traffic, check the ingress-shaping section.
+:::
+```{cfgcmd} set qos policy limiter \<policy-name\> class \<class ID\> match \<match-name\> description \<description\>
+
+Use this command to configure an Ingress Policer, defining its name,
+a class identifier (1-4090), a class matching rule name and its
+description.
+
+```
+
+Once the matching rules are set for a class, you can start configuring
+how you want matching traffic to behave.
+
+```{cfgcmd} set qos policy limiter \<policy-name\> class \<class-ID\> bandwidth \<rate\>
+
+Use this command to configure an Ingress Policer, defining its name,
+a class identifier (1-4090) and the maximum allowed bandwidth for
+this class.
+
+```
+
+```{cfgcmd} set qos policy limiter \<policy-name\> class \<class-ID\> burst \<burst-size\>
+
+Use this command to configure an Ingress Policer, defining its name,
+a class identifier (1-4090) and the burst size in bytes for this
+class (default: 15).
+
+```
+
+```{cfgcmd} set qos policy limiter \<policy-name\> default bandwidth \<rate\>
+
+Use this command to configure an Ingress Policer, defining its name
+and the maximum allowed bandwidth for its default policy.
+
+```
+
+```{cfgcmd} set qos policy limiter \<policy-name\> default burst \<burst-size\>
+
+Use this command to configure an Ingress Policer, defining its name
+and the burst size in bytes (default: 15) for its default policy.
+
+```
+
+```{cfgcmd} set qos policy limiter \<policy-name\> class \<class ID\> priority \<value\>
+
+Use this command to configure an Ingress Policer, defining its name,
+a class identifier (1-4090), and the priority (0-20, default 20) in
+which the rule is evaluated (the lower the number, the higher the
+priority).
+
+```
+
+#### Network Emulator
+
+```{eval-rst}
+| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter).
+| **Applies to:** Outbound traffic.
+```
+
+VyOS Network Emulator policy emulates the conditions you can suffer in a
+real network. You will be able to configure things like rate, burst,
+delay, packet loss, packet corruption or packet reordering.
+
+This could be helpful if you want to test how an application behaves
+under certain network conditions.
+
+```{cfgcmd} set qos policy network-emulator \<policy-name\> bandwidth \<rate\>
+
+   Use this command to configure the maximum rate at which traffic will
+   be shaped in a Network Emulator policy. Define the name of the policy
+   and the rate.
+
+```
+
+```{cfgcmd} set qos policy network-emulator \<policy-name\> burst \<burst-size\>
+
+Use this command to configure the burst size of the traffic in a
+Network Emulator policy. Define the name of the Network Emulator
+policy and its traffic burst size (it will be configured through the
+Token Bucket Filter qdisc). Default:15kb. It will only take effect if
+you have configured its bandwidth too.
+```
+
+```{cfgcmd} set qos policy network-emulator \<policy-name\> delay \<delay\>
+
+Use this command to configure a Network Emulator policy defining its
+name and the fixed amount of time you want to add to all packet going
+out of the interface. The latency will be added through the
+Token Bucket Filter qdisc. It will only take effect if you have
+configured its bandwidth too. You can use secs, ms and us. Default:
+50ms.
+```
+
+```{cfgcmd} set qos policy network-emulator \<policy-name\> corruption \<percent\>
+
+Use this command to emulate noise in a Network Emulator policy. Set
+the policy name and the percentage of corrupted packets you want. A
+random error will be introduced in a random position for the chosen
+percent of packets.
+```
+
+```{cfgcmd} set qos policy network-emulator \<policy-name\> loss \<percent\>
+
+Use this command to emulate packet-loss conditions in a Network
+Emulator policy. Set the policy name and the percentage of loss
+packets your traffic will suffer.
+```
+
+```{cfgcmd} set traffic-policy network-emulator \<policy-name\> reordering \<percent\>
+
+Use this command to emulate packet-reordering conditions in a Network
+Emulator policy. Set the policy name and the percentage of reordered
+packets your traffic will suffer.
+```
+
+```{cfgcmd} set traffic-policy network-emulator \<policy-name\> queue-limit \<limit\>
+
+Use this command to define the length of the queue of your Network
+Emulator policy. Set the policy name and the maximum number of
+packets (1-4294967295) the queue may hold queued at a time.
+```
+
+#### Priority Queue
+
+```{eval-rst}
+| **Queueing discipline:** PRIO.
+| **Applies to:** Outbound traffic.
+```
+
+The Priority Queue is a classful scheduling policy. It does not delay
+packets (Priority Queue is not a shaping policy), it simply dequeues
+packets according to their priority.
+
+:::{note}
+Priority Queue, as other non-shaping policies, is only useful
+if your outgoing interface is really full. If it is not, VyOS will
+not own the queue and Priority Queue will have no effect. If there is
+bandwidth available on the physical link, you can embed Priority
+Queue into a classful shaping policy to make sure it owns the queue.
+In that case packets can be prioritized based on DSCP.
+:::
+
+Up to seven queues -defined as classes with different priorities- can
+be configured. Packets are placed into queues based on associated match
+criteria. Packets are transmitted from the queues in priority order. If
+classes with a higher priority are being filled with packets
+continuously, packets from lower priority classes will only be
+transmitted after traffic volume from higher priority classes decreases.
+
+:::{note}
+In Priority Queue we do not define classes with a meaningless
+class ID number but with a class priority number (1-7). The lower the
+number, the higher the priority.
+:::
+
+As with other policies, you can define different type of matching rules
+for your classes:
+
+```none
+vyos@vyos# set qos policy priority-queue MY-PRIO class 3 match MY-MATCH-RULE 
+Possible completions:
+   description  Description
+ > ether        Ethernet header match
+   interface    Interface to use
+ > ip           Match IP protocol header
+ > ipv6         Match IPV6 protocol header
+   mark         Match on mark applied by firewall
+   vif          Virtual Local Area Network (VLAN) ID for this match
+```
+
+As with other policies, you can embed other policies into the classes
+(and default) of your Priority Queue policy through the `queue-type`
+setting:
+
+```none
+vyos@vyos# set qos policy priority-queue MY-PRIO class 3 queue-type 
+Possible completions:
+   drop-tail    First-In-First-Out (FIFO) (default)
+   fq-codel     Fair Queue Codel
+   fair-queue   Stochastic Fair Queue (SFQ)
+   priority     Priority queueing
+   random-detect
+                Random Early Detection (RED)
+```
+
+```{cfgcmd} set qos policy priority-queue \<policy-name\> class \<class-ID\> queue-limit \<limit\>
+
+Use this command to configure a Priority Queue policy, set its name,
+set a class with a priority from 1 to 7 and define a hard limit on
+the real queue size. When this limit is reached, new packets are
+dropped.
+
+```
+
+(random-detect)=
+
+#### Random-Detect
+
+```{eval-rst}
+| **Queueing discipline:** Generalized Random Early Drop.
+| **Applies to:** Outbound traffic.
+```
+
+A simple Random Early Detection (RED) policy would start randomly
+dropping packets from a queue before it reaches its queue limit thus
+avoiding congestion. That is good for TCP connections as the gradual
+dropping of packets acts as a signal for the sender to decrease its
+transmission rate.
+
+In contrast to simple RED, VyOS' Random-Detect uses a Generalized Random
+Early Detect policy that provides different virtual queues based on the
+IP Precedence value so that some virtual queues can drop more packets
+than others.
+
+This is achieved by using the first three bits of the ToS (Type of
+Service) field to categorize data streams and, in accordance with the
+defined precedence parameters, a decision is made.
+
+IP precedence as defined in {rfc}`791`:
+> | Precedence | Priority             |
+> | ---------- | -------------------- |
+> | 7          | Network Control      |
+> | 6          | Internetwork Control |
+> | 5          | CRITIC/ECP           |
+> | 4          | Flash Override       |
+> | 3          | Flash                |
+> | 2          | Immediate            |
+> | 1          | Priority             |
+> | 0          | Routine              |
+Random-Detect could be useful for heavy traffic. One use of this
+algorithm might be to prevent a backbone overload. But only for TCP
+(because dropped packets could be retransmitted), not for UDP.
+
+```{cfgcmd} set qos policy random-detect \<policy-name\> bandwidth \<bandwidth\>
+
+   Use this command to configure a Random-Detect policy, set its name
+   and set the available bandwidth for this policy. It is used for
+   calculating the average queue size after some idle time. It should be
+   set to the bandwidth of your interface. Random Detect is not a
+   shaping policy, this command will not shape.
+
+```
+
+```{cfgcmd} set qos policy random-detect \<policy-name\> precedence \<IP-precedence-value\> average-packet \<bytes\>
+
+Use this command to configure a Random-Detect policy and set its
+name, then state the IP Precedence for the virtual queue you are
+configuring and what the size of its average-packet should be
+(in bytes, default: 1024).
+```
+:::{note}
+When configuring a Random-Detect policy: **the higher the
+precedence number, the higher the priority**.
+:::
+```{cfgcmd} set qos policy random-detect \<policy-name\> precedence \<IP-precedence-value\> mark-probability \<value\>
+
+Use this command to configure a Random-Detect policy and set its
+name, then state the IP Precedence for the virtual queue you are
+configuring and what its mark (drop) probability will be. Set the
+probability by giving the N value of the fraction 1/N (default: 10).
+```
+
+```{cfgcmd} set qos policy random-detect \<policy-name\> precedence \<IP-precedence-value\> maximum-threshold \<packets\>
+
+Use this command to configure a Random-Detect policy and set its
+name, then state the IP Precedence for the virtual queue you are
+configuring and what its maximum threshold for random detection will
+be (from 0 to 4096 packets, default: 18). At this size, the marking
+(drop) probability is maximal.
+
+```
+
+```{cfgcmd} set qos policy random-detect \<policy-name\> precedence \<IP-precedence-value\> minimum-threshold \<packets\>
+
+Use this command to configure a Random-Detect policy and set its
+name, then state the IP Precedence for the virtual queue you are
+configuring and what its minimum threshold for random detection will
+be (from 0 to 4096 packets).  If this value is exceeded, packets
+start being eligible for being dropped.
+```
+
+The default values for the minimum-threshold depend on IP precedence:
+> | Precedence | default min-threshold |
+> | ---------- | --------------------- |
+> | 7          | 16                    |
+> | 6          | 15                    |
+> | 5          | 14                    |
+> | 4          | 13                    |
+> | 3          | 12                    |
+> | 2          | 11                    |
+> | 1          | 10                    |
+> | 0          | 9                     |
+
+```{cfgcmd} set qos policy random-detect \<policy-name\> precedence \<IP-precedence-value\> queue-limit \<packets\>
+
+Use this command to configure a Random-Detect policy and set its
+name, then name the IP Precedence for the virtual queue you are
+configuring and what the maximum size of its queue will be (from 1 to
+1-4294967295 packets). Packets are dropped when the current queue
+length reaches this value.
+
+```
+
+If the average queue size is lower than the **min-threshold**, an
+arriving packet will be placed in the queue.
+
+In the case the average queue size is between **min-threshold** and
+**max-threshold**, then an arriving packet would be either dropped or
+placed in the queue, it will depend on the defined **mark-probability**.
+
+If the current queue size is larger than **queue-limit**,
+then packets will be dropped. The average queue size depends on its
+former average size and its current one.
+
+If **max-threshold** is set but **min-threshold is not, then
+\*\*min-threshold** is scaled to 50% of **max-threshold**.
+
+In principle, values must be
+{code}`min-threshold` < {code}`max-threshold` < {code}`queue-limit`.
+
+#### Rate Control
+
+```{eval-rst}
+| **Queueing discipline:** Token Bucket Filter.
+| **Applies to:** Outbound traffic.
+```
+
+Rate-Control is a classless policy that limits the packet flow to a set
+rate. It is a pure shaper, it does not schedule traffic. Traffic is
+filtered based on the expenditure of tokens. Tokens roughly correspond
+to bytes.
+
+Short bursts can be allowed to exceed the limit. On creation, the
+Rate-Control traffic is stocked with tokens which correspond to the
+amount of traffic that can be burst in one go. Tokens arrive at a steady
+rate, until the bucket is full.
+
+```{cfgcmd} set qos policy rate-control \<policy-name\> bandwidth \<rate\>
+
+   Use this command to configure a Rate-Control policy, set its name
+   and the rate limit you want to have.
+
+```
+
+```{cfgcmd} set qos policy rate-control \<policy-name\> burst \<burst-size\>
+
+Use this command to configure a Rate-Control policy, set its name
+and the size of the bucket in bytes which will be available for
+burst.
+```
+
+As a reference: for 10mbit/s on Intel, you might need at least 10kbyte
+buffer if you want to reach your configured rate.
+
+A very small buffer will soon start dropping packets.
+
+```{cfgcmd} set qos policy rate-control \<policy-name\> latency
+
+Use this command to configure a Rate-Control policy, set its name
+and the maximum amount of time a packet can be queued (default: 50
+ms).
+
+```
+
+Rate-Control is a CPU-friendly policy. You might consider using it when
+you just simply want to slow traffic down.
+(drr)=
+
+#### Round Robin
+
+**Queueing discipline:**
+ Deficit Round Robin.
+**Applies to:**
+ Outbound traffic.
+
+The round-robin policy is a classful scheduler that divides traffic in
+different classes you can configure (up to 4096). You can embed a
+new policy into each of those classes (default included).
+
+Each class is assigned a deficit counter (the number of bytes that a
+flow is allowed to transmit when it is its turn) initialized to quantum.
+Quantum is a parameter you configure which acts like a credit of fix
+bytes the counter receives on each round. Then the Round-Robin policy
+starts moving its Round Robin pointer through the queues. If the deficit
+counter is greater than the packet's size at the head of the queue, this
+packet will be sent and the value of the counter will be decremented by
+the packet size. Then, the size of the next packet will be compared to
+the counter value again, repeating the process. Once the queue is empty
+or the value of the counter is insufficient, the Round-Robin pointer
+will move to the next queue. If the queue is empty, the value of the
+deficit counter is reset to 0.
+
+At every round, the deficit counter adds the quantum so that even large
+packets will have their opportunity to be dequeued.
+
+```{cfgcmd} set qos policy round-robin \<policy name\> class \<class-ID\> quantum \<packets\>
+
+Use this command to configure a Round-Robin policy, set its name, set
+a class ID, and the quantum for that class. The deficit counter will
+add that value each round.
+
+```
+
+```{cfgcmd} set qos policy round-robin \<policy name\> class <class ID> queue-limit \<packets\>
+
+Use this command to configure a Round-Robin policy, set its name, set
+a class ID, and the queue size in packets.
+```
+
+As with other policies, Round-Robin can embed another policy into a
+class through the `queue-type` setting.
+
+```none
+vyos@vyos# set qos policy round-robin DRR class 10 queue-type 
+Possible completions:
+   drop-tail    First-In-First-Out (FIFO) (default)
+   fq-codel     Fair Queue Codel
+   fair-queue   Stochastic Fair Queue (SFQ)
+   priority     Priority queueing based
+   random-detect
+                Random Early Detection (RED)
+```
+
+(shaper)=
+
+
+#### Shaper
+
+
+```{eval-rst}
+| **Queueing discipline:** Hierarchical Token Bucket.
+| **Applies to:** Outbound traffic.
+```
+
+
+The Shaper policy does not guarantee a low delay, but it does guarantee
+bandwidth to different traffic classes and also lets you decide how to
+allocate more traffic once the guarantees are met.
+
+
+Each class can have a guaranteed part of the total bandwidth defined for
+the whole policy, so all those shares together should not be higher
+than the policy's whole bandwidth.
+
+
+If guaranteed traffic for a class is met and there is room for more
+traffic, the ceiling parameter can be used to set how much more
+bandwidth could be used. If guaranteed traffic is met and there are
+several classes willing to use their ceilings, the priority parameter
+will establish the order in which that additional traffic will be
+allocated. Priority can be any number from 0 to 7. The lower the number,
+the higher the priority.
+
+```{cfgcmd} set qos policy shaper \<policy-name\> bandwidth \<rate\>
+
+Use this command to configure a Shaper policy, set its name
+and the maximum bandwidth for all combined traffic.
+```
+
+```{cfgcmd} set qos policy shaper \<policy-name\> class \<class-ID\> bandwidth \<rate\>
+
+Use this command to configure a Shaper policy, set its name, define
+a class and set the guaranteed traffic you want to allocate to that
+class.
+
+```
+
+```{cfgcmd} set qos policy shaper \<policy-name\> class \<class-ID\> burst \<bytes\>
+
+Use this command to configure a Shaper policy, set its name, define
+a class and set the size of the tocken bucket in bytes, which will
+be available to be sent at ceiling speed (default: 15Kb).
+```
+
+```{cfgcmd} set qos policy shaper \<policy-name\> class \<class-ID\> ceiling \<bandwidth\>
+
+Use this command to configure a Shaper policy, set its name, define
+a class and set the maximum speed possible for this class. The
+default ceiling value is the bandwidth value.
+```
+
+```{cfgcmd} set qos policy shaper \<policy-name\> class \<class-ID\> priority \<0-7\>
+
+Use this command to configure a Shaper policy, set its name, define
+a class and set the priority for usage of available bandwidth once
+guarantees have been met. The lower the priority number, the higher
+the priority. The default priority value is 0, the highest priority.
+```
+
+As with other policies, Shaper can embed other policies into its
+classes through the `queue-type` setting and then configure their
+parameters.
+
+```none
+vyos@vyos# set qos policy shaper HTB class 10 queue-type 
+Possible completions:
+   fq-codel     Fair Queue Codel (default)
+   fair-queue   Stochastic Fair Queue (SFQ)
+   drop-tail    First-In-First-Out (FIFO)
+   priority     Priority queueing
+   random-detect
+                Random Early Detection (RED)
+```
+
+```none
+vyos@vyos# set qos policy shaper HTB class 10
+Possible completions:
+   bandwidth    Available bandwidth for this policy (default: auto)
+   burst        Burst size for this class (default: 15k)
+   ceiling      Bandwidth limit for this class
+   codel-quantum
+                Deficit in the fair queuing algorithm (default 1514)
+   description  Description
+   flows        Number of flows into which the incoming packets are classified (default 1024)
+   interval     Interval used to measure the delay (default 100)
++> match        Class matching rule name
+   priority     Priority for rule evaluation
+   queue-limit  Maximum queue size (packets)
+   queue-type   Queue type for default traffic (default: fq-codel)
+   set-dscp     Change the Differentiated Services (DiffServ) field in the IP header
+   target       Acceptable minimum standing/persistent queue delay (default: 5)
+```
+:::{note}
+If you configure a class for **VoIP traffic**, don't give it any
+*ceiling*, otherwise new VoIP calls could start when the link is
+available and get suddenly dropped when other classes start using
+their assigned *bandwidth* share.
+:::
+
+(traffic-policy-shaper-example)=
+
+##### Example
+
+A simple example of Shaper using priorities.
+
+```none
+set qos policy shaper MY-HTB bandwidth '50mbit'
+set qos policy shaper MY-HTB class 10 bandwidth '20%'
+set qos policy shaper MY-HTB class 10 match DSCP ip dscp 'EF'
+set qos policy shaper MY-HTB class 10 queue-type 'fq-codel'
+set qos policy shaper MY-HTB class 20 bandwidth '10%'
+set qos policy shaper MY-HTB class 20 ceiling '50%'
+set qos policy shaper MY-HTB class 20 match PORT666 ip destination port '666'
+set qos policy shaper MY-HTB class 20 priority '3'
+set qos policy shaper MY-HTB class 20 queue-type 'fair-queue'
+set qos policy shaper MY-HTB class 30 bandwidth '10%'
+set qos policy shaper MY-HTB class 30 ceiling '50%'
+set qos policy shaper MY-HTB class 30 match ADDRESS30 ip source address '192.168.30.0/24'
+set qos policy shaper MY-HTB class 30 priority '5'
+set qos policy shaper MY-HTB class 30 queue-type 'fair-queue'
+set qos policy shaper MY-HTB default bandwidth '10%'
+set qos policy shaper MY-HTB default ceiling '100%'
+set qos policy shaper MY-HTB default priority '7'
+set qos policy shaper MY-HTB default queue-type 'fair-queue'
+```
+
+(cake)=
+
+#### CAKE
+
+```{eval-rst}
+| **Queueing discipline:** Deficit mode.
+| **Applies to:** Outbound traffic.
+```
+
+Common Applications Kept Enhanced (CAKE) is a comprehensive queue management
+system, implemented as a queue discipline (qdisc) for the Linux kernel. It is
+designed to replace and improve upon the complex hierarchy of simple qdiscs
+presently required to effectively tackle the bufferbloat problem at the network
+edge.
+
+```{cfgcmd} set qos policy cake \<text\> bandwidth \<value\>
+
+   Set the shaper bandwidth, either as an explicit bitrate or a percentage
+   of the interface bandwidth.
+
+```
+
+```{cfgcmd} set qos policy cake \<text\> description
+
+Set a description for the shaper.
+```
+
+```{cfgcmd} set qos policy cake \<text\> flow-isolation blind
+
+Disables flow isolation, all traffic passes through a single queue.
+```
+
+```{cfgcmd} set qos policy cake \<text\> flow-isolation dst-host
+
+Flows are defined only by destination address.
+```
+
+```{cfgcmd} set qos policy cake \<text\> flow-isolation dual-dst-host
+
+Flows are defined by the 5-tuple. Fairness is applied first over destination
+addresses, then over individual flows.
+```
+
+```{cfgcmd} set qos policy cake \<text\> flow-isolation dual-src-host
+
+Flows are defined by the 5-tuple. Fairness is applied first over source
+addresses, then over individual flows.
+```
+
+```{cfgcmd} set qos policy cake \<text\> flow-isolation flow
+
+Flows are defined by the entire 5-tuple (source IP address, source port,
+destination IP address, destination port, transport protocol).
+```
+
+```{cfgcmd} set qos policy cake \<text\> flow-isolation host
+
+Flows are defined by source-destination host pairs.
+```
+
+```{cfgcmd} set qos policy cake \<text\> flow-isolation nat
+
+Perform NAT lookup before applying flow-isolation rules.
+```
+
+```{cfgcmd} set qos policy cake \<text\> flow-isolation src-host
+
+Flows are defined only by source address.
+```
+
+```{cfgcmd} set qos policy cake \<text\> flow-isolation triple-isolate
+
+**(Default)** Flows are defined by the 5-tuple, fairness is applied
+over source and destination addresses and also over individual flows.
+```
+
+```{cfgcmd} set qos policy cake \<text\> rtt
+
+Defines the round-trip time used for active queue management (AQM) in
+milliseconds. The default value is 100.
+```
+
+### Applying a traffic policy
+
+Once a traffic-policy is created, you can apply it to an interface:
+
+```none
+set qos interface eth0 egress WAN-OUT
+```
+
+You can only apply one policy per interface and direction, but you could
+reuse a policy on different interfaces and directions:
+
+```none
+set qos interface eth0 ingress WAN-IN
+set qos interface eth0 egress WAN-OUT
+set qos interface eth1 ingress LAN-IN
+set qos interface eth1 egress LAN-OUT
+set qos interface eth2 ingress LAN-IN
+set qos interface eth2 egress LAN-OUT
+set qos interface eth3 ingress TWO-WAY-POLICY
+set qos interface eth3 egress TWO-WAY-POLICY
+set qos interface eth4 ingress TWO-WAY-POLICY
+set qos interface eth4 egress TWO-WAY-POLICY
+```
+
+(ingress-shaping)=
+
+### The case of ingress shaping
+
+**Applies to:**
+ Inbound traffic.
+
+For the ingress traffic of an interface, there is only one policy you
+can directly apply, a **Limiter** policy. You cannot apply a shaping
+policy directly to the ingress traffic of any interface because shaping
+only works for outbound traffic.
+
+This workaround lets you apply a shaping policy to the ingress traffic
+by first redirecting it to an in-between virtual interface
+([Intermediate Functional Block]). There, in that virtual interface,
+you will be able to apply any of the policies that work for outbound
+traffic, for instance, a shaping one.
+
+That is how it is possible to do the so-called "ingress shaping".
+
+```none
+set qos policy shaper MY-INGRESS-SHAPING bandwidth 1000kbit
+set qos policy shaper MY-INGRESS-SHAPING default bandwidth 1000kbit
+set qos policy shaper MY-INGRESS-SHAPING default queue-type fair-queue
+
+set qos interface ifb0 egress MY-INGRESS-SHAPING
+set interfaces ethernet eth0 redirect ifb0
+
+set interfaces input ifb0
+```
+
+:::{warning}
+Do not configure IFB as the first step. First create everything else
+of your traffic-policy, and then you can configure IFB.
+Otherwise you might get the `RTNETLINK answer: File exists` error,
+which can be solved with `sudo ip link delete ifb0`.
+:::
+
+[common applications kept enhanced]: https://www.bufferbloat.net/projects/codel/wiki/Cake/
+[hfsc]: <https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve>
+[intermediate functional block]: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb
+[tc]: <https://en.wikipedia.org/wiki/Tc_(Linux)>
+[that can give you a great deal of flexibility]: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches
+[tocken bucket]: <https://en.wikipedia.org/wiki/Token_bucket>
diff --git a/docs/configuration/vpn/dmvpn.md b/docs/configuration/vpn/dmvpn.md
new file mode 100644
index 00000000..4dc2c85f
--- /dev/null
+++ b/docs/configuration/vpn/dmvpn.md
@@ -0,0 +1,431 @@
+(vpn-dmvpn)=
+
+# DMVPN
+
+{abbr}`DMVPN (Dynamic Multipoint Virtual Private Network)` is a dynamic
+{abbr}`VPN (Virtual Private Network)` technology originally developed by Cisco.
+While their implementation was somewhat proprietary, the underlying
+technologies are actually standards based. The three technologies are:
+
+- {abbr}`NHRP (Next Hop Resolution Protocol)` {rfc}`2332`
+- {abbr}`mGRE (Multipoint Generic Routing Encapsulation)` {rfc}`1702`
+- {abbr}`IPSec (IP Security)` - too many RFCs to list, but start with
+  {rfc}`4301`
+
+NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint
+registration, and endpoint discovery/lookup), mGRE provides the tunnel
+encapsulation itself, and the IPSec protocols handle the key exchange, and
+crypto mechanism.
+
+In short, DMVPN provides the capability for creating a dynamic-mesh VPN
+network without having to pre-configure (static) all possible tunnel end-point
+peers.
+
+:::{note}
+DMVPN only automates the tunnel endpoint discovery and setup. A
+complete solution also incorporates the use of a routing protocol. BGP is
+particularly well suited for use with DMVPN.
+:::
+
+:::{figure} /_static/images/vpn_dmvpn_topology01.webp
+:alt: Baseline DMVPN topology
+:scale: 40 %
+Baseline DMVPN topology
+:::
+
+## Configuration
+
+### Tunnel interface configuration
+
+NHRP never handles routing of prefixes itself. You need to run some real routing
+protocol (e.g. BGP) to advertise routes over the tunnels. What nhrpd does it
+establishes ‘shortcut routes’ that optimizes the routing protocol to avoid going
+through extra nodes in NBMA GRE mesh.
+
+NHRP does route NHRP domain addresses individually using per-host prefixes.
+This is similar to Cisco FlexVPN, but in contrast to opennhrp which uses
+a generic subnet route.
+
+To create NBMA GRE tunnel you might use the following:
+
+```none
+set interfaces tunnel tun100 address '10.0.0.1/32'
+set interfaces tunnel tun100 enable-multicast
+set interfaces tunnel tun100 encapsulation 'gre'
+set interfaces tunnel tun100 ip adjust-mss '1360'
+set interfaces tunnel tun100 mtu '1400'
+set interfaces tunnel tun100 parameters ip key '42'
+set interfaces tunnel tun100 source-interface 'eth0'
+```
+
+- Please refer to the {ref}`tunnel-interface` documentation for the individual
+  tunnel related options.
+
+  :::{note}
+  The IP-address is assigned as host prefix to tunnel interface.
+  NHRP will automatically create additional host routes pointing to tunnel interface
+  when a connection with these hosts is established.
+  :::
+
+The tunnel interface subnet prefix should be announced by routing protocol
+from the hub nodes (e.g. BGP ‘network’ announce). This allows the routing
+protocol to decide which is the closest hub and determine the relay hub on
+prefix basis when direct tunnel is not established.
+
+### NHRP protocol configuration
+
+```{cfgcmd} set protocols nhrp tunnel \<tunnel\> authentication \<secret\>
+
+Enables Cisco style authentication on NHRP packets. This embeds the
+plaintext password to the outgoing NHRP packets. Maximum length of
+the password is 8 characters.
+```
+
+```{cfgcmd} set protocols nhrp tunnel \<tunnel\> holdtime \<timeout\>
+
+Holdtime is the number of seconds that have to pass before stopping to
+advertise an NHRP NBMA address as valid. It also controls how often NHRP
+registration requests are sent. By default registrations are sent every
+one third of the holdtime
+```
+
+```{cfgcmd} set protocols nhrp tunnel \<tunnel\> map tunnel-ip \<tunnel-ip\> nbma \<nbma-ip\>
+
+* **tunnel-ip** - Tunnel ip address in format **x.x.x.x**.
+* **nbma-ip** - NBMA ip address in format **x.x.x.x** or **local**
+
+Map an IP address of a station to the station’s NBMA address.
+```
+
+```{cfgcmd} set protocols nhrp tunnel \<tunnel\> mtu \<mtu\>
+
+Configure NHRP advertised MTU.
+```
+
+```{cfgcmd} set protocols nhrp tunnel \<tunnel\> multicast \<nbma-ip\>
+
+* **nbma-ip** - NBMA ip address in format **x.x.x.x** or **dynamic**
+
+Sends multicast packets to the specified NBMA address. If dynamic is specified
+then destination NBMA address (or addresses) are learnt dynamically.
+```
+
+```{cfgcmd} set protocols nhrp tunnel \<tunnel\> network-id \<network-id\>
+
+* **network-id** - NHRP network id <1-4294967295>
+
+Enable NHRP on this interface and set the interface’s network ID. The network ID
+is used to allow creating multiple nhrp domains on a router when multiple interfaces
+are configured on the router. Interfaces configured with the same ID are part of the
+same logical NBMA network. The ID is a local only parameter and is not sent to other
+NHRP nodes and so IDs on different nodes do not need to match. When NHRP packets are
+received on an interface they are assigned to the local NHRP domain for that interface.
+```
+
+```{cfgcmd} set protocols nhrp tunnel \<tunnel\> nhs tunnel-ip \<tunnel-ip\> nbma \<nbma-ip\>
+
+* **tunnel-ip** - Tunnel ip address in format **x.x.x.x** or **dynamic**
+* **nbma-ip** - NBMA ip address in format **x.x.x.x**
+
+Configure the Next Hop Server address and its NBMA address. If dynamic is specified
+then Next Hop Server can have dynamic address which maps to its NBMA address.
+```
+
+```{cfgcmd} set protocols nhrp tunnel \<tunnel\> redirect
+
+This enable redirect replies on the NHS similar to ICMP redirects except this is
+managed by the nhrp protocol. This setting allows spokes to communicate with each
+others directly.
+```
+
+```{cfgcmd} set protocols nhrp tunnel \<tunnel\> registration-no-unique
+
+Allow the client to not set the unique flag in the NHRP packets. This is useful when
+a station has a dynamic IP address that could change over time.
+```
+
+```{cfgcmd} set protocols nhrp tunnel \<tunnel\> shortcut
+
+Enable shortcut (spoke-to-spoke) tunnels to allow NHC to talk to each others directly
+after establishing a connection without going through the hub.
+```
+
+
+### IPSEC configuration
+
+- Please refer to the {ref}`ipsec_general` documentation for the individual IPSec
+  related options.
+
+:::{note}
+NHRP daemon based on FRR nhrpd. It controls IPSEC. That's why 'close-action'
+parameter in IKE configuration always is set to 'close' and 'dead-peer-detection action'
+always is set to 'clear'.
+:::
+
+```{cfgcmd} set vpn ipsec profile \<profile-name\> authentication mode pre-shared-secret
+
+Set preshared secret mode authentication
+```
+
+```{cfgcmd} set vpn ipsec profile \<profile-name\> authentication pre-shared-secret \<secret\>
+
+Set preshared secret
+```
+
+```{cfgcmd} set vpn ipsec profile \<profile-name\> bind tunnel \<tunnel name\>
+
+Bind IPSEC profile to the specific tunnel interface.
+```
+
+```{cfgcmd} set vpn ipsec profile \<profile-name\> esp-group 'ESP-HUB'
+
+Map ESP group to IPSEC profile
+```
+
+```{cfgcmd} set vpn ipsec profile \<profile-name\> ike-group 'IKE-HUB'
+
+Map IKE group to IPSEC profile
+```
+
+
+## Monitoring
+
+```{opcmd} show ip nhrp cache
+
+Forwarding cache information.
+```
+
+```{opcmd} show ip nhrp nhs
+
+Next hop server information.
+```
+
+```{opcmd} show ip nhrp shortcut
+
+Shortcut information.
+```
+
+
+## Example
+
+This blueprint uses VyOS as the DMVPN Hub and Cisco IOSv 15.5(3)M and VyOS as
+multiple spoke sites.
+
+:::{figure} /_static/images/blueprint-dmvpn.webp
+:align: center
+:alt: DMVPN Network Topology Diagram
+:width: 70%
+DMVPN Network Topology Diagram
+:::
+
+Each node (Hub and Spoke) uses an IP address from the network 10.0.0.0/24.
+
+The below referenced IP address `192.168.0.2` is used as example address
+representing a global unicast address under which the HUB can be contacted by
+each and every individual spoke.
+(dmvpn-example-configuration)=
+
+### Configuration
+
+#### Hub
+
+##### VyOS-HUB-1
+
+```none
+set interfaces ethernet eth0 address '192.168.0.2/30'
+
+set interfaces tunnel tun100 address '10.0.0.100/32'
+set interfaces tunnel tun100 enable-multicast
+set interfaces tunnel tun100 encapsulation 'gre'
+set interfaces tunnel tun100 parameters ip key '42'
+set interfaces tunnel tun100 source-interface 'eth0'
+
+set protocols nhrp tunnel tun100 authentication 'test123'
+set protocols nhrp tunnel tun100 holdtime '300'
+set protocols nhrp tunnel tun100 multicast 'dynamic'
+set protocols nhrp tunnel tun100 network-id '1'
+set protocols nhrp tunnel tun100 redirect
+set protocols nhrp tunnel tun100 registration-no-unique
+
+set protocols static route 0.0.0.0/0 next-hop 192.168.0.1
+
+set vpn ipsec esp-group ESP-HUB lifetime '1800'
+set vpn ipsec esp-group ESP-HUB mode 'transport'
+set vpn ipsec esp-group ESP-HUB pfs 'dh-group2'
+set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256'
+set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1'
+set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1'
+set vpn ipsec ike-group IKE-HUB lifetime '3600'
+set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2'
+set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256'
+set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1'
+set vpn ipsec interface 'eth0'
+set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret'
+set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret'
+set vpn ipsec profile NHRPVPN bind tunnel 'tun100'
+set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB'
+set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB'
+```
+
+:::{note}
+Setting this up on AWS will require a "Custom Protocol Rule" for
+protocol number "47" (GRE) Allow Rule in TWO places. Firstly on the VPC
+Network ACL, and secondly on the security group network ACL attached to the
+EC2 instance. This has been tested as working for the official AMI image on
+the AWS Marketplace. (Locate the correct VPC and security group by navigating
+through the details pane below your EC2 instance in the AWS console).
+:::
+
+#### Spokes
+
+> The individual spoke configurations only differ in interface IP addresses.
+
+##### VyOS-Spoke-1 and VyOS-Spoke-2
+
+```none
+set interfaces ethernet eth0 address '192.168.1.2/30'
+
+set interfaces tunnel tun100 address '10.0.0.1/32'
+set interfaces tunnel tun100 enable-multicast
+set interfaces tunnel tun100 encapsulation 'gre'
+set interfaces tunnel tun100 parameters ip key '42'
+set interfaces tunnel tun100 source-interface 'eth0'
+
+set protocols nhrp tunnel tun100 authentication 'test123'
+set protocols nhrp tunnel tun100 holdtime '300'
+set protocols nhrp tunnel tun100 multicast 'dynamic'
+set protocols nhrp tunnel tun100 network-id '1'
+set protocols nhrp tunnel tun100 nhs tunnel-ip dynamic nbma '192.168.0.2'
+set protocols nhrp tunnel tun100 registration-no-unique
+set protocols nhrp tunnel tun100 shortcut
+
+set protocols static route 0.0.0.0/0 next-hop 192.168.1.1
+set protocols static route 10.0.0.0/24 next-hop 10.0.0.100
+
+set vpn ipsec esp-group ESP-HUB lifetime '1800'
+set vpn ipsec esp-group ESP-HUB mode 'transport'
+set vpn ipsec esp-group ESP-HUB pfs 'dh-group2'
+set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256'
+set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1'
+set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1'
+set vpn ipsec ike-group IKE-HUB lifetime '3600'
+set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2'
+set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256'
+set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1'
+set vpn ipsec interface 'eth0'
+set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret'
+set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret'
+set vpn ipsec profile NHRPVPN bind tunnel 'tun100'
+set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB'
+set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB'
+```
+
+
+##### Cisco-Spoke-3
+
+```none
+crypto isakmp policy 10
+ encr aes 256
+ authentication pre-share
+ group 2
+ lifetime 3600
+crypto isakmp key secret address 0.0.0.0
+!
+!
+crypto ipsec transform-set DMVPNESP esp-aes 256 esp-sha-hmac
+ mode transport
+!
+crypto ipsec profile DMVPNPROFILE
+ set security-association lifetime seconds 1800
+ set transform-set DMVPNESP
+ set pfs group2
+!
+!
+!
+!
+!
+!
+!
+interface Tunnel100
+ ip address 10.0.0.3 255.255.255.0
+ no ip redirects
+ ip nhrp authentication test123
+ ip nhrp map multicast dynamic
+ ip nhrp network-id 1
+ ip nhrp holdtime 300
+ ip nhrp nhs 10.0.0.100 nbma 192.168.0.2
+ ip nhrp registration no-unique
+ ip nhrp redirect
+tunnel source GigabitEthernet0/0
+ tunnel mode gre multipoint
+ tunnel key 42
+ tunnel protection ipsec profile DMVPNPROFILE
+!
+interface GigabitEthernet0/0
+ ip address 192.168.3.2 255.255.255.252
+ duplex auto
+ speed auto
+ media-type rj45
+!
+ip route 0.0.0.0 0.0.0.0 192.168.3.1
+```
+
+
+##### Monitoring DMVPN Network
+
+Let send ICMP packets from VyOS-SPOKE-1 to Cisco-SPOKE-3
+
+```none
+vyos@vyos:~$ ping 10.0.0.3
+PING 10.0.0.3 (10.0.0.3) 56(84) bytes of data.
+64 bytes from 10.0.0.3: icmp_seq=1 ttl=255 time=3.44 ms
+64 bytes from 10.0.0.3: icmp_seq=2 ttl=255 time=3.07 ms
+^C
+--- 10.0.0.3 ping statistics ---
+2 packets transmitted, 2 received, 0% packet loss, time 1002ms
+rtt min/avg/max/mdev = 3.072/3.257/3.442/0.185 ms
+```
+
+
+##### Monitoring on HUB
+
+```none
+vyos@vyos:~$ show ip nhrp cache
+Iface    Type     Protocol                 NBMA                     Claimed NBMA             Flags  Identity
+tun100   dynamic  10.0.0.1                 192.168.1.2              192.168.1.2               T     192.168.1.2
+tun100   dynamic  10.0.0.3                 192.168.3.2              192.168.3.2               T     192.168.3.2
+tun100   dynamic  10.0.0.2                 192.168.2.2              192.168.2.2               T     192.168.2.2
+tun100   local    10.0.0.100               192.168.0.2              192.168.0.2                     -
+
+vyos@vyos:~$ show vpn ipsec sa
+Connection                  State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+--------------------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------------------------------
+dmvpn-NHRPVPN-tun100-child  up       3m46s     230B/270B       2/2               192.168.1.2       192.168.1.2  AES_CBC_256/HMAC_SHA1_96/MODP_1024
+dmvpn-NHRPVPN-tun100-child  up       5m48s     460B/540B       4/4               192.168.2.2       192.168.2.2  AES_CBC_256/HMAC_SHA1_96/MODP_1024
+dmvpn-NHRPVPN-tun100-child  up       16m26s    1K/1K           13/12             192.168.3.2       192.168.3.2  AES_CBC_256/HMAC_SHA1_96/MODP_1024
+```
+
+
+##### Monitoring on Spokes
+
+```none
+vyos@vyos:~$ show ip nhrp cache
+Iface    Type     Protocol                 NBMA                     Claimed NBMA             Flags  Identity
+tun100   local    10.0.0.1                 192.168.1.2              192.168.1.2                     -
+tun100   dynamic  10.0.0.3                 192.168.3.2              192.168.3.2               T     192.168.3.2
+tun100   nhs      10.0.0.100               192.168.0.2              192.168.0.2               T     192.168.0.2
+
+vyos@vyos:~$ show ip nhrp nhs
+Iface    FQDN                     NBMA             Protocol
+tun100   192.168.0.2              192.168.0.2      10.0.0.100
+
+vyos@vyos:~$ show ip nhrp shortcut
+Type     Prefix                   Via                      Identity
+dynamic  10.0.0.3/32              10.0.0.3                 192.168.3.2
+
+vyos@vyos:~$ show vpn ipsec sa
+Connection                  State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+--------------------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------------------------------
+dmvpn-NHRPVPN-tun100-child  up       6m43s     898B/695B       7/6               192.168.0.2       192.168.0.2  AES_CBC_256/HMAC_SHA1_96/MODP_1024
+dmvpn-NHRPVPN-tun100-child  up       49s       215B/187B       2/2               192.168.3.2       192.168.3.2  AES_CBC_256/HMAC_SHA1_96/MODP_1024
+```
diff --git a/docs/configuration/vpn/index.md b/docs/configuration/vpn/index.md
new file mode 100644
index 00000000..9b06e5df
--- /dev/null
+++ b/docs/configuration/vpn/index.md
@@ -0,0 +1,14 @@
+# VPN
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+ipsec/index
+l2tp
+openconnect
+pptp
+rsa-keys
+sstp
+dmvpn
+```
diff --git a/docs/configuration/vpn/ipsec/index.md b/docs/configuration/vpn/ipsec/index.md
new file mode 100644
index 00000000..cc40b6f8
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/index.md
@@ -0,0 +1,11 @@
+# IPsec
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+ipsec_general
+site2site_ipsec
+remoteaccess_ipsec
+troubleshooting_ipsec
+```
diff --git a/docs/configuration/vpn/ipsec/ipsec_general.md b/docs/configuration/vpn/ipsec/ipsec_general.md
new file mode 100644
index 00000000..6fc47386
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/ipsec_general.md
@@ -0,0 +1,407 @@
+(ipsec_general)=
+
+# IPsec General Information
+
+## Information about IPsec
+
+IPsec is the framework used to secure data.
+IPsec accomplishes these goals by providing authentication,
+encryption of IP network packets, key exchange, and key management.
+VyOS uses Strongswan package to implement IPsec.
+
+**Authentication Header (AH)** is defined in {rfc}`4302`. It creates
+a hash using the IP header and data payload, and prepends it to the
+packet. This hash is used to validate that the data has not been
+changed during transfer over the network.
+
+**Encapsulating Security Payload (ESP)** is defined in {rfc}`4303`.
+It provides encryption and authentication of the data.
+
+```{eval-rst}
+There are two IPsec modes:
+    **IPsec Transport Mode**:
+        In transport mode, an IPSec header (AH or ESP) is inserted
+        between the IP header and the upper layer protocol header.
+
+    **IPsec Tunnel Mode:**
+        In tunnel mode, the original IP packet is encapsulated in
+        another IP datagram, and an IPsec header (AH or ESP) is
+        inserted between the outer and inner headers.
+
+.. figure:: /_static/images/ESP_AH.webp
+   :scale: 80 %
+   :alt: AH and ESP in Transport Mode and Tunnel Mode
+```
+
+## IKE (Internet Key Exchange)
+
+The default IPsec method for secure key negotiation is the Internet Key
+Exchange (IKE) protocol. IKE is designed to provide mutual authentication
+of systems, as well as to establish a shared secret key to create IPsec
+security associations. A security association (SA) includes all relevant
+attributes of the connection, including the cryptographic algorithm used,
+the IPsec mode, the encryption key, and other parameters related to the
+transmission of data over the VPN connection.
+
+### IKEv1
+
+IKEv1 is the older version and is still used today. Nowadays, most
+manufacturers recommend using IKEv2 protocol.
+
+IKEv1 is described in the next RFCs: {rfc}`2409` (IKE), {rfc}`3407`
+(IPsec DOI), {rfc}`3947` (NAT-T), {rfc}`3948` (UDP Encapsulation
+of ESP Packets), {rfc}`3706` (DPD)
+
+```{eval-rst}
+IKEv1 operates in two phases to establish these IKE and IPsec SAs:
+    * **Phase 1** provides mutual authentication of the IKE peers and
+      establishment of the session key. This phase creates an IKE SA (a
+      security association for IKE) using a DH exchange, cookies, and an
+      ID exchange. Once an IKE SA is established, all IKE communication
+      between the initiator and responder is protected with encryption
+      and an integrity check that is authenticated. The purpose of IKE
+      phase 1 is to facilitate a secure channel between the peers so that
+      phase 2 negotiations can occur securely. IKE phase 1 offers two modes:
+      Main and Aggressive.
+
+        * **Main Mode** is used for site-to-site VPN connections.
+        
+        * **Aggressive Mode** is used for remote access VPN connections.
+
+    * **Phase 2** provides for the negotiation and establishment of the
+      IPsec SAs using ESP or AH to protect IP data traffic.
+```
+
+### IKEv2
+
+IKEv2 is described in {rfc}`7296`. The biggest difference between IKEv1 and
+IKEv2 is that IKEv2 is much simpler and more reliable than IKEv1 because
+fewer messages are exchanged during the establishment of the VPN and
+additional security capabilities are available.
+
+### IKE Authentication
+
+```{eval-rst}
+VyOS supports 3 authentication methods.
+    * **Pre-shared keys**: In this method, both peers of the IPsec
+      tunnel must have the same preshared keys.
+    * **Digital certificates**: PKI is used in this method.
+    * **RSA-keys**: If the RSA-keys method is used in your IKE policy,
+      you need to make sure each peer has the other peer’s public keys.
+```
+
+## DPD (Dead Peer Detection)
+
+This is a mechanism used to detect when a VPN peer is no longer active.
+This mechanism has different algorithms in IKEv1 and IKEv2 in VyOS.
+DPD Requests are sent as ISAKMP R-U-THERE messages and DPD Responses
+are sent as ISAKMP R-U-THERE-ACK messages. In IKEv1, DPD sends messages
+every configured interval. The remote peer is considered unreachable
+if no response to these packets is received within the DPD timeout.
+In IKEv2, DPD sends messages every configured interval. If one request
+is not responded, Strongswan execute its retransmission algorithm with
+its timers.  [IKEv2 Retransmission](#ikev2-retransmission)
+
+## Post-Quantum Preshared Keys (PPK)
+
+Post-Quantum Preshared Keys help provide some quantum resistance to IPSec
+tunnels when a post-quantum key exchange algorithm such as ML-KEM is not
+available. The use of PPKs in IKEv2 is described in {rfc}`8784`.
+
+```{eval-rst}
+.. cfgmod:: edit vpn authentication ppk <name>
+```
+
+PPKs can be configued within VyOS under the `vpn ipsec authentication ppk`
+config.
+
+```{eval-rst}
+.. cfgmod:: set vpn authentication ppk <name> secret-type <plaintext|hex|base64>
+```
+
+PPKs need an id and a secret value. The ID and the secret must match if PPKs are
+required for a successful IPsec connection. The secret can be plain text, a
+hex value, or a Base64 value. The default is plain text. If using another
+type of value, you must define the secret type.
+
+```{eval-rst}
+.. cfgmod:: set vpn ipsec site-to-site <name> ppk id <id>
+```
+
+To use a PPK within a site-to-site or remote access connection, define the PPK
+id under the connection.
+
+```{eval-rst}
+.. cfgmod:: set vpn ipsec site-to-site <name> ppk required
+```
+
+Optionally, you can require the use of PPK to have a successful connection.
+
+```{eval-rst}
+.. cfgmod:: show vpn ipsec connections
+```
+
+You can view the PPK column for information on if PPK is configured, and
+if it is in use. The output is in the format of `<configured> / <in use>`.
+The options for configured are none if not conifugred, opt if configured
+but optional, and req is configured and required. The in use will show yes
+Possible values of the `configured` field are `none` if not
+conifgured, `opt` if configured but optional, and `req` is
+configured and required. The in use will show yes
+
+## Configuration IKE
+
+```{eval-rst}
+IKE (Internet Key Exchange) Attributes
+======================================
+
+VyOS IKE group has the next options:
+
+.. cfgcmd:: set vpn ipsec ike-group <name> close-action <action>
+
+  Defines the action to take if the remote peer unexpectedly
+  closes a CHILD_SA:
+
+ * **none** - Set action to none (default),
+ * **trap** - Installs a trap policy (IPsec policy without Security
+   Association) for the CHILD_SA and traffic matching these policies
+   will trigger acquire events that cause the daemon to establish the
+   required IKE/IPsec SAs.
+ * **start** - Tries to immediately re-create the CHILD_SA.
+
+.. cfgcmd:: set vpn ipsec ike-group <name> ikev2-reauth
+
+  Whether rekeying of an IKE_SA should also reauthenticate
+  the peer. In IKEv1, reauthentication is always done.
+  Setting this parameter enables remote host re-authentication
+  during an IKE rekey.
+
+.. cfgcmd:: set vpn ipsec ike-group <name> key-exchange
+
+  Which protocol should be used to initialize the connection
+  If not set both protocols are handled and connections will
+  use IKEv2 when initiating, but accept any protocol version
+  when responding:
+
+ * **ikev1** - Use IKEv1 for Key Exchange.
+ * **ikev2** - Use IKEv2 for Key Exchange.
+
+.. cfgcmd:: set vpn ipsec ike-group <name> lifetime
+
+  IKE lifetime in seconds <0-86400> (default 28800).
+
+.. cfgcmd:: set vpn ipsec ike-group <name> mode
+
+  IKEv1 Phase 1 Mode Selection:
+
+ * **main** - Use Main mode for Key Exchanges in the IKEv1 Protocol
+   (Recommended Default).
+ * **aggressive** - Use Aggressive mode for Key Exchanges in the IKEv1
+   protocol aggressive mode is much more insecure compared to Main mode.
+
+.. stop_vyoslinter
+
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> dh-group <dh-group number>
+
+  Dh-group. Default value is **2**.
+
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> encryption <encryption>
+
+  Encryption algorithm. Default value is **aes128**.
+
+.. start_vyoslinter
+
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> hash <hash>
+
+  Hash algorithm. Default value is **sha1**.
+
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> prf <prf>
+
+  Pseudo-random function.
+
+
+DPD (Dead Peer Detection) Configuration
+=======================================
+
+.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection action <action>
+
+  Action to perform for this CHILD_SA on DPD timeout.
+
+  * **trap** - Installs a trap policy (IPsec policy without Security
+    Association), which will catch matching traffic and tries to
+    re-negotiate the tunnel on-demand.
+  * **clear** - Closes the CHILD_SA and does not take further action
+    (default).
+  * **restart** - Immediately tries to re-negotiate the CHILD_SA
+    under a fresh IKE_SA.
+
+.. stop_vyoslinter
+
+.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection interval <interval>
+
+  Keep-alive interval in seconds <2-86400> (default 30).
+
+.. start_vyoslinter
+
+.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection timeout <timeout>
+
+  Keep-alive timeout in seconds <2-86400> (default 120) **IKEv1 only**
+
+ESP (Encapsulating Security Payload) Attributes
+===============================================
+
+In VyOS, ESP attributes are specified through ESP groups.
+Multiple proposals can be specified in a single group.
+
+VyOS ESP group has the next options:
+
+.. cfgcmd:: set vpn ipsec esp-group <name> compression
+
+  Enables the  IPComp(IP Payload Compression) protocol which allows
+  compressing the content of IP packets.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> disable-rekey
+
+  Do not locally initiate a re-key of the SA, remote peer must
+  re-key before expiration.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> life-bytes <bytes>
+
+  ESP life in bytes <1024-26843545600000>. Number of bytes
+  transmitted over an IPsec SA before it expires.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> life-packets <packets>
+
+  ESP life in packets <1000-26843545600000>.
+  Number of packets transmitted over an IPsec SA before it expires.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> lifetime <timeout>
+
+  ESP lifetime in seconds <30-86400> (default 3600).
+  How long a particular instance of a connection (a set of
+  encryption/authentication keys for user packets) should last,
+  from successful negotiation to expiry.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> mode <mode>
+
+  The type of the connection:
+
+  * **tunnel** - Tunnel mode (default).
+  * **transport** - Transport mode.
+
+.. cfgcmd:: set vpn ipsec esp-group <name> pfs < dh-group>
+
+  Whether Perfect Forward Secrecy of keys is desired on the
+  connection's keying channel and defines a Diffie-Hellman group for
+  PFS:
+
+ * **enable** - Inherit Diffie-Hellman group from IKE group (default).
+ * **disable** - Disable PFS.
+ * **<dh-group>** - Defines a Diffie-Hellman group for PFS.
+
+.. stop_vyoslinter
+
+.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> encryption <encryption>
+
+  Encryption algorithm. Default value is **aes128**.
+
+.. start_vyoslinter
+
+.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> hash <hash>
+
+  Hash algorithm. Default value is **sha1**.
+
+Global IPsec Settings
+=====================
+
+.. cfgcmd:: set vpn ipsec interface <name>
+
+  Interface name to restrict outbound IPsec policies. There is a possibility
+  to specify multiple interfaces. If an interfaces are not specified, IPsec
+  policies apply to all interfaces.
+
+
+.. cfgcmd:: set vpn ipsec log level <number>
+
+  Level of logging. Default value is **0**.
+
+.. cfgcmd:: set vpn ipsec log subsystem <name>
+
+  Subsystem of the daemon.
+
+Options
+=======
+
+.. cfgcmd:: set vpn ipsec options disable-route-autoinstall
+
+  Do not automatically install routes to remote
+  networks.
+
+.. cfgcmd:: set vpn ipsec options flexvpn
+
+  Allows FlexVPN vendor ID payload (IKEv2 only). Send the Cisco
+  FlexVPN vendor ID payload (IKEv2 only), which is required in order to make
+  Cisco brand devices allow negotiating a local traffic selector (from
+  strongSwan's point of view) that is not the assigned virtual IP address if
+  such an address is requested by strongSwan. Sending the Cisco FlexVPN
+  vendor ID prevents the peer from narrowing the initiator's local traffic
+  selector and allows it to e.g. negotiate a TS of 0.0.0.0/0 == 0.0.0.0/0
+  instead. This has been tested with a "tunnel mode ipsec ipv4" Cisco
+  template but should also work for GRE encapsulation.
+
+.. cfgcmd:: set vpn ipsec options interface <name>
+
+  Interface Name to use. The name of the interface on which
+  virtual IP addresses should be installed. If not specified the addresses
+  will be installed on the outbound interface.
+
+.. cfgcmd:: set vpn ipsec options virtual-ip
+
+  Allows the installation of virtual-ip addresses.
+```
+
+### IKEv2 Retransmission
+
+If the peer does not respond on DPD packet, the router starts retransmission procedure.
+
+The following formula is used to calculate the timeout:
+
+```none
+relative timeout = timeout * base ^ (attempts-1)
+```
+
+```{cfgcmd} set vpn ipsec options retransmission attempts
+
+Number of attempts before the peer is considered to be in the down state.
+Default value is **5**.
+```
+
+```{cfgcmd} set vpn ipsec options retransmission base
+
+Base number of exponential backoff. Default value is **1.8**.
+```
+
+```{cfgcmd} set vpn ipsec options retransmission timeout
+
+Timeout in seconds before the first retransmission. Default value is **4**.
+```
+
+Using the default values, packets are retransmitted as follows:
+
+```{eval-rst}
++-----------+-------------+------------------+------------------+
+| Attempts  | Formula     | Relative timeout | Absolute timeout |
++-----------+-------------+------------------+------------------+
+| 1         | 4 * 1.8 ^ 0 | 4s               | 4s               |
++-----------+-------------+------------------+------------------+
+| 2         | 4 * 1.8 ^ 1 | 7s               | 11s              |
++-----------+-------------+------------------+------------------+
+| 3         | 4 * 1.8 ^ 2 | 13s              | 24s              |
++-----------+-------------+------------------+------------------+
+| 4         | 4 * 1.8 ^ 3 | 23s              | 47s              |
++-----------+-------------+------------------+------------------+
+| 5         | 4 * 1.8 ^ 4 | 42s              | 89s              |
++-----------+-------------+------------------+------------------+
+| peer down | 4 * 1.8 ^ 5 | 76s              | 165s             |
++-----------+-------------+------------------+------------------+
+```
diff --git a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.md b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.md
new file mode 100644
index 00000000..6931e00b
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.md
@@ -0,0 +1,186 @@
+(remoteaccess-ipsec)=
+
+# IPSec IKEv2 Remote Access VPN
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+Internet Key Exchange version 2 (IKEv2) is a tunneling protocol, based on IPsec,
+that establishes a secure VPN communication between VPN devices, and defines
+negotiation and authentication processes for IPsec security associations (SAs).
+It is often known as IKEv2/IPSec or IPSec IKEv2 remote-access — or road-warriors
+as others call it.
+
+Key exchange and payload encryption is done using IKE and ESP proposals as known
+from IKEv1 but the connections are faster to establish, more reliable, and also
+support roaming from IP to IP (called MOBIKE which makes sure your connection
+does not drop when changing networks from e.g. WIFI to LTE and back).
+Authentication can be achieved with X.509 certificates.
+
+## Setting up certificates:
+
+First of all, we need to create a CA root certificate and server certificate
+on the server side.
+
+```none
+vyos@vpn.vyos.net# run generate pki ca install ca_root
+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)
+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] N
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+
+
+vyos@vpn.vyos.net# comp
+[pki ca]
++ ca_root {
++     certificate "MIIDnTCCAoWgAwI…."
++     private {
++         key "MIIEvAIBADANBgkqhkiG9….”
+
+vyos@vpn.vyos.net# run generate pki certificate sign ca_root install server_cert
+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) vpn.vyos.net
+Do you want to configure Subject Alternative Names? [y/N] 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] N
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+
+vyos@vpn.vyos.net# comp
+[pki certificate]
++ server_cert {
++     certificate "MIIDuzCCAqOgAwIBAgIUaSrCPWx………"
++     private {
++         key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK….."
++     }
++ }
+```
+
+Once the command is completed, it will add the certificate to the configuration
+session, to the pki subtree. You can then review the proposed changes and
+commit them.
+
+## Setting up IPSec:
+
+After the PKI certs are all set up we can start configuring our IPSec/IKE
+proposals used for key-exchange end data encryption. The used encryption ciphers
+and integrity algorithms vary from operating system to operating system. The
+ones used in this example are validated to work on Windows 10.
+
+```none
+set vpn ipsec esp-group ESP-RW lifetime '3600'
+set vpn ipsec esp-group ESP-RW pfs 'disable'
+set vpn ipsec esp-group ESP-RW proposal 10 encryption 'aes128gcm128'
+set vpn ipsec esp-group ESP-RW proposal 10 hash 'sha256'
+
+set vpn ipsec ike-group IKE-RW key-exchange 'ikev2'
+set vpn ipsec ike-group IKE-RW lifetime '7200'
+set vpn ipsec ike-group IKE-RW proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-RW proposal 10 encryption 'aes128gcm128'
+set vpn ipsec ike-group IKE-RW proposal 10 hash 'sha256'
+```
+
+Every connection/remote-access pool we configure also needs a pool where we
+can draw our client IP addresses from. We provide one IPv4 and IPv6 pool.
+Authorized clients will receive an IPv4 address from the configured IPv4 prefix
+and an IPv6 address from the IPv6 prefix. We can also send some DNS nameservers
+down to our clients used on their connection.
+
+```none
+set vpn ipsec remote-access pool ra-rw-ipv4 name-server '192.0.2.1'
+set vpn ipsec remote-access pool ra-rw-ipv4 prefix '192.0.2.128/25'
+
+set vpn ipsec remote-access pool ra-rw-ipv6 name-server '2001:db8:1000::1'
+set vpn ipsec remote-access pool ra-rw-ipv6 prefix '2001:db8:2000::/64'
+```
+
+
+## Setting up tunnel:
+
+```none
+set vpn ipsec remote-access connection rw authentication local-id '192.0.2.1'
+set vpn ipsec remote-access connection rw authentication server-mode 'x509'
+set vpn ipsec remote-access connection rw authentication x509 ca-certificate 'ca_root'
+set vpn ipsec remote-access connection rw authentication x509 certificate 'server_cert'
+set vpn ipsec remote-access connection rw esp-group 'ESP-RW'
+set vpn ipsec remote-access connection rw ike-group 'IKE-RW'
+set vpn ipsec remote-access connection rw local-address '192.0.2.1'
+set vpn ipsec remote-access connection rw pool 'ra-rw-ipv4'
+set vpn ipsec remote-access connection rw pool 'ra-rw-ipv6'
+```
+
+VyOS also supports two different modes of authentication, local and RADIUS.
+To create a new local user named "vyos" with a password of "vyos" use the
+following commands.
+
+```none
+set vpn ipsec remote-access connection rw authentication client-mode 'eap-mschapv2'
+set vpn ipsec remote-access connection rw authentication local-users username vyos password 'vyos'
+```
+
+Some client operating systems like to see the servers certificate. The following
+option causes the server to voluntarily send its certificate, even if it wasn't
+requested.
+
+```none
+set vpn ipsec remote-access connection rw authentication always-send-cert
+```
+
+
+## Client Configuration
+
+Most operating systems include native client support for IPsec IKEv2 VPN
+connections, and others typically have an app or add-on package which adds the
+capability.
+This section covers IPsec IKEv2 client configuration for Windows 10.
+
+VyOS provides a command to generate a connection profile used by Windows clients
+that will connect to the "rw" connection on our VyOS server.
+
+:::{note}
+Windows expects the server name to be also used in the server's
+certificate common name, so it's best to use this DNS name for your VPN
+connection.
+:::
+
+```none
+vyos@vpn.vyos.net:~$ generate ipsec profile windows-remote-access rw remote vpn.vyos.net
+
+
+==== <snip> ====
+Add-VpnConnection -Name "VyOS IKEv2 VPN" -ServerAddress "vpn.vyos.net" -TunnelType "Ikev2"
+
+Set-VpnConnectionIPsecConfiguration -ConnectionName "VyOS IKEv2 VPN" -AuthenticationTransformConstants GCMAES128 -CipherTransformConstants
+GCMAES128 -EncryptionMethod GCMAES128 -IntegrityCheckMethod SHA256128 -PfsGroup None -DHGroup "Group14" -PassThru -Force
+==== </snip> ====
+```
+
+Add the commands from Snippet in the Windows side via PowerShell.
+Also import the root CA cert to the Windows “Trusted Root Certification
+Authorities” and establish the connection.
+
+## Verification:
+
+```none
+vyos@vpn.vyos.net:~$ show vpn ipsec remote-access summary
+  Connection ID  Username    Protocol    State    Uptime    Tunnel IP    Remote Host    Remote ID    IKE Proposal                                IPSec Proposal
+---------------  ----------  ----------  -------  --------  -----------  -------------  -----------  ------------------------------------------  ------------------
+              5  vyos        IKEv2       UP       37s       192.0.2.129  10.0.0.2       10.0.0.2     AES_GCM_16-128/PRF_HMAC_SHA2_256/MODP_2048  ESP:AES_GCM_16-128
+```
diff --git a/docs/configuration/vpn/ipsec/site2site_ipsec.md b/docs/configuration/vpn/ipsec/site2site_ipsec.md
new file mode 100644
index 00000000..d3b65ae1
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/site2site_ipsec.md
@@ -0,0 +1,780 @@
+(size2site-ipsec)=
+
+# IPsec Site-to-Site VPN
+
+## IPsec Site-to-Site VPN Types
+
+VyOS supports two types of IPsec VPN: Policy-based IPsec VPN and Route-based
+IPsec VPN.
+
+### Policy-based VPN
+
+Policy-based VPN is based on static configured policies. Each policy creates
+individual IPSec SA. Traffic matches these SAs encrypted and directed to the
+remote peer.
+
+### Route-Based VPN
+
+Route-based VPN is based on secure traffic passing over Virtual Tunnel
+Interfaces (VTIs). This type of IPsec VPNs allows using routing protocols.
+
+## Configuration Site-to-Site VPN
+
+### Requirements and Prerequisites for Site-to-Site VPN
+
+**Negotiated parameters that need to match**
+
+```{eval-rst}
+Phase 1
+ * IKE version
+ * Authentication
+ * Encryption
+ * Hashing
+ * PRF
+ * Lifetime
+
+ .. note:: Strongswan recommends to use the same lifetime value on both peers
+
+Phase 2
+ * Encryption
+ * Hashing
+ * PFS
+ * Mode (tunnel or transport)
+ * Lifetime
+
+ .. note:: Strongswan recommends to use the same lifetime value on both peers
+
+ * Remote and Local networks in SA must be compatible on both peers
+```
+
+### Configuration Steps for Site-to-Site VPN
+
+The next example shows the configuration one of the router participating in
+IPsec VPN.
+
+```{eval-rst}
+Tunnel information:
+    * Phase 1:
+        * encryption: AES256
+        * hash: SHA256
+        * PRF: SHA256
+        * DH: 14
+        * lifetime: 28800
+    * Phase 2:
+        * IPsec mode: tunnel
+        * encryption: AES256
+        * hash: SHA256
+        * PFS: inherited from DH Phase 1
+        * lifetime: 3600
+    * If Policy based VPN is used
+        * Remote network is 192.168.50.0/24. Local network is 192.168.10.0/24
+    * If Route based VPN is used
+        * IP of the VTI interface is 10.0.0.1/30
+```
+
+:::{note}
+We do not recommend using policy-based vpn and route-based vpn configurations to the same peer.
+:::
+
+**1. Configure ike-group (IKE Phase 1)**
+
+```none
+set vpn ipsec ike-group IKE close-action 'start'
+set vpn ipsec ike-group IKE key-exchange 'ikev1'
+set vpn ipsec ike-group IKE lifetime '28800'
+set vpn ipsec ike-group IKE proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE proposal 10 encryption 'aes256'
+set vpn ipsec ike-group IKE proposal 10 hash 'sha256'
+set vpn ipsec ike-group IKE proposal 10 prf 'prfsha256'
+```
+
+**2. Configure ESP-group (IKE Phase 2)**
+
+```none
+set vpn ipsec esp-group ESP lifetime '3600'
+set vpn ipsec esp-group ESP mode 'tunnel'
+set vpn ipsec esp-group ESP pfs 'enable'
+set vpn ipsec esp-group ESP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group ESP proposal 10 hash 'sha256'
+```
+
+**3. Specify interface facing to the protected destination.**
+
+```none
+set vpn ipsec interface eth0
+```
+
+**4. Configure PSK keys and authentication ids for this key if authentication type is PSK**
+
+```none
+set vpn ipsec authentication psk PSK-KEY id '192.168.0.2'
+set vpn ipsec authentication psk PSK-KEY id '192.168.5.2'
+set vpn ipsec authentication psk PSK-KEY secret 'vyos'
+```
+
+To set base64 secret encode plaintext password to base64 and set secret-type
+
+```none
+echo -n "vyos" | base64
+dnlvcw==
+```
+
+```none
+set vpn ipsec authentication psk PSK-KEY secret 'dnlvcw=='
+set vpn ipsec authentication psk PSK-KEY secret-type base64
+```
+
+**5. Configure peer and apply IKE-group and esp-group to peer.**
+
+```none
+set vpn ipsec site-to-site peer PEER1 authentication local-id '192.168.0.2'
+set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer PEER1 authentication remote-id '192.168.5.2'
+set vpn ipsec site-to-site peer PEER1 connection-type 'initiate'
+set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP'
+set vpn ipsec site-to-site peer PEER1 ike-group 'IKE'
+set vpn ipsec site-to-site peer PEER1 local-address '192.168.0.2'
+set vpn ipsec site-to-site peer PEER1 remote-address '192.168.5.2'
+
+Peer selects the key from step 4 according to local-id/remote-id pair.
+```
+
+**6. Depends to vpn type (route-based vpn or policy-based vpn).**
+
+> **6.1 For Policy-based VPN configure SAs using tunnel command specifying remote and local networks.**
+>
+> > ```none
+> > set vpn ipsec site-to-site peer PEER1 tunnel 1 local prefix '192.168.10.0/24'
+> > set vpn ipsec site-to-site peer PEER1 tunnel 1 remote prefix '192.168.50.0/24'
+> > ```
+>
+> **6.2 For Route-based VPN create VTI interface, set IP address to this interface and bind this interface to the vpn peer.**
+>
+> > ```none
+> > set interfaces vti vti1 address 10.0.0.1/30
+> > set vpn ipsec site-to-site peer PEER1 vti bind vti1
+> > set vpn ipsec options disable-route-autoinstall
+> > ```
+> >
+> > Create routing between local networks via VTI interface using dynamic or
+> > static routing.
+> >
+> > ```none
+> > set protocol static route 192.168.50.0/24 next-hop 10.0.0.2
+> > ```
+
+### Initiator and Responder Connection Types
+
+In Site-to-Site IPsec VPN it is recommended that one peer should be an
+initiator and the other - the responder. The initiator actively establishes
+the VPN tunnel. The responder passively waits for the remote peer to
+establish the VPN tunnel. Depends on selected role it is recommended
+select proper values for close-action and DPD action.
+
+The result of wrong value selection can be unstable work of the VPN.
+: - Duplicate CHILD SA creation.
+  - None of the VPN sides initiates the tunnel establishment.
+
+Below flow-chart could be a quick reference for the close-action
+combination depending on how the peer is configured.
+
+```{eval-rst}
+.. figure:: /_static/images/IPSec_close_action_settings.webp
+```
+
+Similar combinations are applicable for the dead-peer-detection.
+
+### Detailed Configuration Commands
+
+#### PSK Key Authentication
+
+```{cfgcmd} set vpn ipsec authentication psk \<name\> dhcp-interface
+
+ID for authentication generated from DHCP address
+dynamically.
+
+```
+
+```{cfgcmd} set vpn ipsec authentication psk id \<id\>
+
+static ID's for authentication. In general local and remote address
+``<x.x.x.x>``, ``<h:h:h:h:h:h:h:h>`` or ``%any``.
+```
+
+```{cfgcmd} set vpn ipsec authentication psk secret \<secret\>
+
+A predefined shared secret used in configured mode
+``pre-shared-secret``. Base64-encoded secrets are allowed if
+`secret-type base64` is configured.
+```
+
+```{cfgcmd} set vpn ipsec authentication psk secret-type \<type\>
+
+Specifies the secret type:
+
+* **plaintext** - Plain text type (default value).
+* **base64** - Base64 type.
+```
+
+#### Peer Configuration
+
+
+##### Peer Authentication Commands
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication mode \<mode\>
+
+Mode for authentication between VyOS and remote peer:
+
+* **pre-shared-secret** - Use predefined shared secret phrase.
+* **rsa** - Use simple shared RSA key.
+* **x509** - Use certificates infrastructure for authentication.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication local-id \<id\>
+
+ID for the local VyOS router. If defined, during the authentication
+it will be send to remote peer.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication remote-id \<id\>
+
+ID for remote peer, instead of using peer name or
+address. Useful in case if the remote peer is behind NAT
+or if ``mode x509`` is used.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication rsa local-key \<key\>
+
+Name of PKI key-pair with local private key.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication rsa remote-key \<key\>
+
+Name of PKI key-pair with remote public key.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication rsa passphrase \<passphrase\>
+
+Local private key passphrase.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication use-x509-id \<id\>
+
+Use local ID from x509 certificate. Cannot be used when
+``id`` is defined.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication x509 ca-certificate \<name\>
+
+Name of CA certificate in PKI configuration. Using for authenticating
+remote peer in x509 mode.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication x509 certificate \<name\>
+
+Name of certificate in PKI configuration, which will be used
+for authenticating local router on remote peer.
+```
+
+```{cfgcmd} set vpn ipsec authentication x509 passphrase \<passphrase\>
+
+Private key passphrase, if needed.
+```
+
+##### Global Peer Configuration Commands
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> connection-type \<type\>
+
+Operational mode defines how to handle this connection process.
+
+* **initiate** - does initial connection to remote peer immediately
+  after configuring and after boot. In this mode the connection will
+  not be restarted in case of disconnection, therefore should be used
+  only together with DPD or another session tracking methods.
+
+* **trap** - does not try to initiate a connection to a remote
+  peer immediately. Instead, it installs a trap policy that will
+  trigger IKE negotiation and establish the IPsec session when
+  matching traffic is sent from the local side. This can be useful
+  when there is no direct connectivity to the peer due to firewall
+  or NAT in the middle of the local and remote side.
+
+  :::{warning}
+  The ``trap`` mode is not needed in most environments
+  and can lead to connection confusion or unintended tunnel uptime
+  behavior if used incorrectly. Using this mode requires careful
+  coordination with parameters such as ``close-action`` and DPD.
+  For most deployments, use ``initiate`` and ``none`` as described below.
+  :::
+
+* **none** - loads the connection only, which then can be manually
+  initiated or used as a responder configuration.
+
+:::{note}
+For most site-to-site VPNs, configure one peer
+with ``connection-type initiate`` (active side) and the other peer
+with ``connection-type none`` (passive side) to
+ensure stable and predictable tunnel behavior.
+When using ``connection-type initiate``, you must also configure
+DPD or another session tracking method (such as ``close-action``)
+to automatically re-establish the tunnel after a disconnection.
+Otherwise, the tunnel will not reconnect automatically if it goes down.
+:::
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> default-esp-group \<name\>
+
+Name of ESP group to use by default for traffic encryption.
+Might be overwritten by individual settings for tunnel or VTI
+interface binding.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> description \<description\>
+
+Description for this peer.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> dhcp-interface \<interface\>
+
+Specify the interface which IP address, received from DHCP for IPSec
+connection with this peer, will be used as ``local-address``.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> force-udp-encapsulation
+
+Force encapsulation of ESP into UDP datagrams. Useful in case if
+between local and remote side is firewall or NAT, which not
+allows passing plain ESP packets between them.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> ike-group \<name\>
+
+Name of IKE group to use for key exchanges.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> local-address \<address\>
+
+Local IP address for IPsec connection with this peer.
+If defined ``any``, then an IP address which configured on interface with
+default route will be used.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> remote-address \<address\>
+
+Remote IP address or hostname for IPsec connection. IPv4 or IPv6
+address is used when a peer has a public static IP address. Hostname
+is a DNS name which could be used when a peer has a public IP
+address and DNS name, but an IP address could be changed from time
+to time.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> replay-window \<size\>
+
+IPsec replay window to configure for CHILD_SAs
+(default: 32), a value of 0 disables IPsec replay protection.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> virtual-address \<address\>
+
+Defines a virtual IP address which is requested by the initiator and
+one or several IPv4 and/or IPv6 addresses are assigned from multiple
+pools by the responder. The wildcard addresses 0.0.0.0 and ::
+request an arbitrary address, specific addresses may be defined.
+```
+
+##### CHILD SAs Configuration Commands
+
+###### Policy-Based CHILD SAs Configuration Commands
+
+Every configured tunnel under peer configuration is a new CHILD SA.
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> disable
+
+Disable this tunnel.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> esp-group \<name\>
+
+Specify ESP group for this CHILD SA.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> priority \<number\>
+
+Priority for policy-based IPsec VPN tunnels (lowest value more
+preferable).
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> protocol \<name\>
+
+Define the protocol for match traffic, which should be encrypted and
+send to this peer.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> local prefix \<network\>
+
+IP network at the local side.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> local port \<number\>
+
+Local port number. Have effect only when used together with
+``prefix``.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> remote prefix \<network\>
+
+IP network at the remote side.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> remote port \<number\>
+
+Remote port number. Have effect only when used together with
+``prefix``.
+```
+
+###### Route-Based CHILD SAs Configuration Commands
+
+To configure route-based VPN it is enough to create vti interface and
+bind it to the peer. Any traffic, which will be send to VTI interface
+will be encrypted and send to this peer. Using VTI makes IPsec
+configuration much flexible and easier in complex situation, and
+allows to dynamically add/delete remote networks, reachable via a
+peer, as in this mode router don't need to create additional SA/policy
+for each remote network.
+
+:::{warning}
+When using site-to-site IPsec with VTI interfaces,
+be sure to disable route autoinstall.
+:::
+```none
+set vpn ipsec options disable-route-autoinstall
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti bind \<interface\>
+
+VTI interface to bind to this peer.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti esp-group \<name\>
+
+ESP group for encrypt traffic, passed this VTI interface.
+```
+
+Traffic-selectors parameters for traffic that should pass via vti
+interface.
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti traffic-selector local prefix \<network\>
+
+Local prefix for interesting traffic.
+```
+
+```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti traffic-selector remote prefix \<network\>
+
+Remote prefix for interesting traffic.
+```
+
+### IPsec Op-mode Commands
+
+```{opcmd} show vpn ike sa
+
+Shows active IKE SAs information.
+```
+
+```{opcmd} show vpn ike secrets
+
+Shows configured authentication keys.
+```
+
+```{opcmd} show vpn ike status
+
+Shows Strongswan daemon status.
+```
+
+```{opcmd} show vpn ipsec connections
+
+Shows summary status of all configured IKE and IPsec SAs.
+```
+
+```{opcmd} show vpn ipsec sa [detail]
+
+Shows active IPsec SAs information.
+```
+
+```{opcmd} show vpn ipsec status
+
+Shows status of IPsec process.
+```
+
+```{opcmd} show vpn ipsec policy
+
+Shows the in-kernel crypto policies.
+```
+
+```{opcmd} show vpn ipsec state
+
+Shows the in-kernel crypto state.
+```
+
+```{opcmd} show log ipsec
+
+Shows IPsec logs.
+```
+
+```{opcmd} reset vpn ipsec site-to-site all
+
+Clear all ipsec connection and reinitiate them if VyOS is configured
+as initiator.
+```
+
+```{opcmd} reset vpn ipsec site-to-site peer \<name\>
+
+Clear all peer IKE SAs with IPsec SAs and reinitiate them if VyOS is
+configured as initiator.
+```
+
+```{opcmd} reset vpn ipsec site-to-site peer \<name\> tunnel \<number\>
+
+Clear scpecific IPsec SA and reinitiate it if VyOS is configured as
+initiator.
+```
+
+```{opcmd} reset vpn ipsec site-to-site peer \<name\> vti \<number\>
+
+Clear IPsec SA which is map to vti interface of this peer and
+reinitiate it if VyOS is configured as initiator.
+```
+
+```{opcmd} restart ipsec
+
+Restart Strongswan daemon.
+```
+
+## Examples:
+
+### Policy-Based VPN Example
+
+**PEER1:**
+- WAN interface on `eth0`
+- `eth0` interface IP: `10.0.1.2/30`
+- `dum0` interface IP: `192.168.0.1/24` (for testing purposes)
+- Initiator
+
+**PEER2:**
+- WAN interface on `eth0`
+- `eth0` interface IP: `10.0.2.2/30`
+- `dum0` interface IP: `192.168.1.0/24` (for testing purposes)
+- Responder
+
+```none
+# PEER1
+set interfaces dummy dum0 address '192.168.0.1/32'
+set interfaces ethernet eth0 address '10.0.1.2/30'
+set protocols static route 0.0.0.0/0 next-hop 10.0.1.1
+set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2'
+set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2'
+set vpn ipsec authentication psk AUTH-PSK secret 'test'
+set vpn ipsec esp-group ESP-GRPOUP lifetime '3600'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1'
+set vpn ipsec ike-group IKE-GROUP close-action 'start'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120'
+set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1'
+set vpn ipsec ike-group IKE-GROUP lifetime '28800'
+set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256'
+set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1'
+set vpn ipsec interface 'eth0'
+set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2'
+set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2'
+set vpn ipsec site-to-site peer PEER2 connection-type 'initiate'
+set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP'
+set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP'
+set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2'
+set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2'
+set vpn ipsec site-to-site peer PEER2 tunnel 0 local prefix '192.168.0.0/24'
+set vpn ipsec site-to-site peer PEER2 tunnel 0 remote prefix '192.168.1.0/24'
+
+
+# PEER2
+set interfaces dummy dum0 address '192.168.1.1/32'
+set interfaces ethernet eth0 address '10.0.2.2/30'
+set protocols static route 0.0.0.0/0 next-hop 10.0.2.1
+set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2'
+set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2'
+set vpn ipsec authentication psk AUTH-PSK secret 'test'
+set vpn ipsec esp-group ESP-GRPOUP lifetime '3600'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1'
+set vpn ipsec ike-group IKE-GROUP close-action 'none'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120'
+set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1'
+set vpn ipsec ike-group IKE-GROUP lifetime '28800'
+set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256'
+set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1'
+set vpn ipsec interface 'eth0'
+set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2'
+set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2'
+set vpn ipsec site-to-site peer PEER1 connection-type 'none'
+set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP'
+set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP'
+set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2'
+set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2'
+set vpn ipsec site-to-site peer PEER1 tunnel 0 local prefix '192.168.1.0/24'
+set vpn ipsec site-to-site peer PEER1 tunnel 0 remote prefix '192.168.0.0/24'
+```
+
+Show status of policy-based IPsec VPN setup:
+
+```none
+vyos@PEER2:~$ show vpn ike sa
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+10.0.1.2 10.0.1.2                       10.0.2.2 10.0.2.2
+
+    State  IKEVer  Encrypt      Hash          D-H Group      NAT-T  A-Time  L-Time
+    -----  ------  -------      ----          ---------      -----  ------  ------
+    up     IKEv1   AES_CBC_256  HMAC_SHA1_96  MODP_2048      no     1254    25633
+
+
+vyos@srv-gw0:~$ show vpn ipsec sa
+Connection      State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+--------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------------------------------
+PEER1-tunnel-0  up       20m42s    0B/0B           0/0               10.0.1.2          10.0.1.2     AES_CBC_256/HMAC_SHA1_96/MODP_2048
+
+vyos@PEER2:~$ show vpn ipsec connections
+Connection      State    Type    Remote address    Local TS        Remote TS       Local id    Remote id    Proposal
+--------------  -------  ------  ----------------  --------------  --------------  ----------  -----------  ----------------------------------
+PEER1           up       IKEv1   10.0.1.2          -               -               10.0.2.2    10.0.1.2     AES_CBC/256/HMAC_SHA1_96/MODP_2048
+PEER1-tunnel-0  up       IPsec   10.0.1.2          192.168.1.0/24  192.168.0.0/24  10.0.2.2    10.0.1.2     AES_CBC/256/HMAC_SHA1_96/MODP_2048
+```
+
+If there is SNAT rules on eth0, need to add exclude rule
+
+```none
+# PEER1 side
+set nat source rule 10 destination address '192.168.1.0/24'
+set nat source rule 10 'exclude'
+set nat source rule 10 outbound-interface name 'eth0'
+set nat source rule 10 source address '192.168.0.0/24'
+
+# PEER2 side
+set nat source rule 10 destination address '192.168.0.0/24'
+set nat source rule 10 'exclude'
+set nat source rule 10 outbound-interface name 'eth0'
+set nat source rule 10 source address '192.168.1.0/24'
+```
+
+### Route-Based VPN Example
+
+**PEER1:**
+- WAN interface on `eth0`
+- `eth0` interface IP: `10.0.1.2/30`
+- 'vti0' interface IP: `10.100.100.1/30`
+- `dum0` interface IP: `192.168.0.1/24` (for testing purposes)
+- Role: Initiator
+
+**PEER2:**
+- WAN interface on `eth0`
+- `eth0` interface IP: `10.0.2.2/30`
+- 'vti0' interface IP: `10.100.100.2/30`
+- `dum0` interface IP: `192.168.1.0/24` (for testing purposes)
+- Role: Responder
+
+```none
+# PEER1
+set interfaces dummy dum0 address '192.168.0.1/32'
+set interfaces ethernet eth0 address '10.0.1.2/30'
+set interfaces vti vti0 address '10.100.100.1/30'
+set protocols static route 0.0.0.0/0 next-hop 10.0.1.1
+set protocols static route 192.168.1.0/24 next-hop 10.100.100.2
+set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2'
+set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2'
+set vpn ipsec authentication psk AUTH-PSK secret 'test'
+set vpn ipsec esp-group ESP-GRPOUP lifetime '3600'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1'
+set vpn ipsec ike-group IKE-GROUP close-action 'start'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30'
+set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2'
+set vpn ipsec ike-group IKE-GROUP lifetime  '28800'
+set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256'
+set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1'
+set vpn ipsec interface 'eth0'
+set vpn ipsec options disable-route-autoinstall
+set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2'
+set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2'
+set vpn ipsec site-to-site peer PEER2 connection-type 'initiate'
+set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP'
+set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP'
+set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2'
+set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2'
+set vpn ipsec site-to-site peer PEER2 vti bind 'vti0'
+
+
+# PEER2
+set interfaces dummy dum0 address '192.168.1.1/32'
+set interfaces ethernet eth0 address '10.0.2.2/30'
+set interfaces vti vti0 address '10.100.100.2/30'
+set protocols static route 0.0.0.0/0 next-hop 10.0.2.1
+set protocols static route 192.168.0.0/24 next-hop 10.100.100.1
+set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2'
+set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2'
+set vpn ipsec authentication psk AUTH-PSK secret 'test'
+set vpn ipsec esp-group ESP-GRPOUP lifetime '3600'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256'
+set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1'
+set vpn ipsec ike-group IKE-GROUP close-action 'none'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear'
+set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30'
+set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2'
+set vpn ipsec ike-group IKE-GROUP lifetime '28800'
+set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256'
+set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1'
+set vpn ipsec interface 'eth0'
+set vpn ipsec options disable-route-autoinstall
+set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2'
+set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2'
+set vpn ipsec site-to-site peer PEER1 connection-type 'none'
+set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP'
+set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP'
+set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2'
+set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2'
+set vpn ipsec site-to-site peer PEER1 vti bind 'vti0'
+```
+
+Show status of route-based IPsec VPN setup:
+
+```none
+vyos@PEER2:~$ show vpn ike sa
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+10.0.1.2 10.0.1.2                       10.0.2.2 10.0.2.2
+
+    State  IKEVer  Encrypt      Hash          D-H Group      NAT-T  A-Time  L-Time
+    -----  ------  -------      ----          ---------      -----  ------  ------
+    up     IKEv2   AES_CBC_256  HMAC_SHA1_96  MODP_2048      no     404     27650
+
+vyos@PEER2:~$ show vpn ipsec sa
+Connection    State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------------------------------
+PEER1-vti     up       3m28s     0B/0B           0/0               10.0.1.2          10.0.1.2     AES_CBC_256/HMAC_SHA1_96/MODP_2048
+
+vyos@PEER2:~$ show vpn ipsec connections
+Connection    State    Type    Remote address    Local TS    Remote TS    Local id    Remote id    Proposal
+------------  -------  ------  ----------------  ----------  -----------  ----------  -----------  ----------------------------------
+PEER1         up       IKEv2   10.0.1.2          -           -            10.0.2.2    10.0.1.2     AES_CBC/256/HMAC_SHA1_96/MODP_2048
+PEER1-vti     up       IPsec   10.0.1.2          0.0.0.0/0   0.0.0.0/0    10.0.2.2    10.0.1.2     AES_CBC/256/HMAC_SHA1_96/MODP_2048
+                                               ::/0        ::/0
+```
diff --git a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.md b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.md
new file mode 100644
index 00000000..2ca37bc2
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.md
@@ -0,0 +1,313 @@
+(troubleshooting-ipsec)=
+
+# Troubleshooting Site-to-Site VPN IPsec
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+
+## Introduction
+
+This document describes the methodology to monitor and troubleshoot
+Site-to-Site VPN IPsec.
+
+Steps for troubleshooting problems with Site-to-Site VPN IPsec:
+: 1. Ping the remote site through the tunnel using the source and
+     destination IPs included in the policy.
+  2. Check connectivity between the routers using the ping command
+     (if ICMP traffic is allowed).
+  3. Check the IKE SAs' statuses.
+  4. Check the IPsec SAs' statuses.
+  5. Check logs to view debug messages.
+
+## Checking IKE SA Status
+
+The next command shows IKE SAs' statuses.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+192.168.1.2 192.168.1.2                 192.168.0.1 192.168.0.1
+
+    State  IKEVer  Encrypt      Hash          D-H Group      NAT-T  A-Time  L-Time
+    -----  ------  -------      ----          ---------      -----  ------  ------
+    up     IKEv2   AES_CBC_128  HMAC_SHA1_96  MODP_2048      no     162     27023
+```
+
+This command shows the next information:
+: - IKE SA status.
+  - Selected IKE version.
+  - Selected Encryption, Hash and Diffie-Hellman Group.
+  - NAT-T.
+  - ID and IP of both peers.
+  - A-Time: established time, L-Time: time for next rekeying.
+
+## IPsec SA (CHILD SA) Status
+
+The next commands show IPsec SAs' statuses.
+
+```none
+vyos@vyos:~$ show vpn ipsec sa
+Connection     State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+-------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------------------------------
+PEER-tunnel-1  up       16m30s    168B/168B       2/2               192.168.1.2       192.168.1.2  AES_CBC_128/HMAC_SHA1_96/MODP_2048
+```
+
+```none
+vyos@vyos:~$ show vpn ipsec sa detail
+PEER: #1, ESTABLISHED, IKEv2, 101275ac719d5a1b_i* 68ea4ec3bed3bf0c_r
+  local  '192.168.0.1' @ 192.168.0.1[4500]
+  remote '192.168.1.2' @ 192.168.1.2[4500]
+  AES_CBC-128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+  established 4054s ago, rekeying in 23131s
+  PEER-tunnel-1: #2, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA1_96/MODP_2048
+    installed 1065s ago, rekeying in 1998s, expires in 2535s
+    in  c5821882,    168 bytes,     2 packets,    81s ago
+    out c433406a,    168 bytes,     2 packets,    81s ago
+    local  10.0.0.0/24
+    remote 10.0.1.0/24
+```
+
+These commands show the next information:
+: - IPsec SA status.
+  - Uptime and time for the next rekeing.
+  - Amount of transferred data.
+  - Remote and local ID and IP.
+  - Selected Encryption, Hash and Diffie-Hellman Group.
+  - Mode (tunnel or transport).
+  - Remote and local prefixes which are use for policy.
+
+There is a possibility to view the summarized information of SAs' status
+
+```none
+vyos@vyos:~$ show vpn ipsec connections
+Connection     State    Type    Remote address    Local TS     Remote TS    Local id     Remote id    Proposal
+-------------  -------  ------  ----------------  -----------  -----------  -----------  -----------  ----------------------------------
+PEER           up       IKEv2   192.168.1.2       -            -            192.168.0.1  192.168.1.2  AES_CBC/128/HMAC_SHA1_96/MODP_2048
+PEER-tunnel-1  up       IPsec   192.168.1.2       10.0.0.0/24  10.0.1.0/24  192.168.0.1  192.168.1.2  AES_CBC/128/HMAC_SHA1_96/MODP_2048
+```
+
+
+## Viewing Logs for Debugging
+
+If IKE SAs or IPsec SAs are down, need to debug IPsec connectivity
+using logs `show log ipsec`
+
+The next example of the successful IPsec connection initialization.
+
+```none
+vyos@vyos:~$ show log ipsec
+Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 20 14:29:47 charon[2428]: 02[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 20 14:29:47 charon-systemd[2428]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1}
+Jun 20 14:29:47 charon-systemd[2428]: establishing CHILD_SA PEER-tunnel-1{1}
+Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 20 14:29:47 charon-systemd[2428]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 20 14:29:47 charon-systemd[2428]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 20 14:29:47 charon[2428]: 13[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes)
+Jun 20 14:29:47 charon[2428]: 13[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ]
+Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes)
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful
+Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ]
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> peer supports MOBIKE
+Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.1.2' with pre-shared key successful
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 20 14:29:47 charon-systemd[2428]: peer supports MOBIKE
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> scheduling rekeying in 27703s
+Jun 20 14:29:47 charon-systemd[2428]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> maximum IKE_SA lifetime 30583s
+Jun 20 14:29:47 charon-systemd[2428]: scheduling rekeying in 27703s
+Jun 20 14:29:47 charon[2428]: 13[CFG] <PEER|1> selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 20 14:29:47 charon-systemd[2428]: maximum IKE_SA lifetime 30583s
+Jun 20 14:29:47 charon-systemd[2428]: selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24
+Jun 20 14:29:47 charon-systemd[2428]: CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24
+```
+
+
+## Troubleshooting Examples
+
+### IKE PROPOSAL are Different
+
+In this situation, IKE SAs can be down or not active.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+```
+
+The problem is in IKE phase (Phase 1). The next step is checking debug logs.
+
+Responder Side:
+
+```none
+Jun 23 07:36:33 charon[2440]: 01[CFG] <1> received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon-systemd[2440]: received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon[2440]: 01[CFG] <1> configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon-systemd[2440]: configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon[2440]: 01[IKE] <1> received proposals unacceptable
+Jun 23 07:36:33 charon-systemd[2440]: received proposals unacceptable
+Jun 23 07:36:33 charon[2440]: 01[ENC] <1> generating IKE_SA_INIT response 0 [ N(NO_PROP) ]
+```
+
+Initiator side:
+
+```none
+Jun 23 07:36:32 charon-systemd[2444]: parsed IKE_SA_INIT response 0 [ N(NO_PROP) ]
+Jun 23 07:36:32 charon[2444]: 14[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify error
+Jun 23 07:36:32 charon-systemd[2444]: received NO_PROPOSAL_CHOSEN notify error
+```
+
+The notification **NO_PROPOSAL_CHOSEN** means that the proposal mismatch.
+On the Responder side there is concrete information where is mismatch.
+Encryption **AES_CBC_128** is configured in IKE policy on the responder
+but **AES_CBC_256** is configured on the initiator side.
+
+### PSK Secret Mismatch
+
+In this situation, IKE SAs can be down or not active.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+```
+
+The problem is in IKE phase (Phase 1). The next step is checking debug logs.
+
+Responder:
+
+```none
+Jun 23 08:07:26 charon-systemd[2440]: tried 1 shared key for '192.168.1.2' - '192.168.0.1', but MAC mismatched
+Jun 23 08:07:26 charon[2440]: 13[ENC] <PEER|3> generating IKE_AUTH response 1 [ N(AUTH_FAILED) ]
+```
+
+Initiator side:
+
+```none
+Jun 23 08:07:24 charon[2436]: 12[ENC] <PEER|1> parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ]
+Jun 23 08:07:24 charon-systemd[2436]: parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ]
+Jun 23 08:07:24 charon[2436]: 12[IKE] <PEER|1> received AUTHENTICATION_FAILED notify error
+Jun 23 08:07:24 charon-systemd[2436]: received AUTHENTICATION_FAILED notify error
+```
+
+The notification **AUTHENTICATION_FAILED** means that the authentication
+is failed. There is a reason to check PSK on both side.
+
+### ESP Proposal Mismatch
+
+The output of **show** commands shows us that IKE SA is established but
+IPSec SA is not.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+192.168.1.2 192.168.1.2                 192.168.0.1 192.168.0.1
+
+    State  IKEVer  Encrypt      Hash          D-H Group      NAT-T  A-Time  L-Time
+    -----  ------  -------      ----          ---------      -----  ------  ------
+    up     IKEv2   AES_CBC_128  HMAC_SHA1_96  MODP_2048      no     158     26817
+```
+
+```none
+vyos@vyos:~$ show vpn ipsec sa
+Connection    State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------
+```
+
+The next step is checking debug logs.
+
+Initiator side:
+
+```none
+Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 23 08:16:10 charon[3789]: 13[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 23 08:16:10 charon-systemd[3789]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1}
+Jun 23 08:16:10 charon-systemd[3789]: establishing CHILD_SA PEER-tunnel-1{1}
+Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 23 08:16:10 charon-systemd[3789]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 23 08:16:10 charon-systemd[3789]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 23 08:16:10 charon[3789]: 09[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes)
+Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes)
+Jun 23 08:16:10 charon[3789]: 09[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ]
+Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ]
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful
+Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.1.2' with pre-shared key successful
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> peer supports MOBIKE
+Jun 23 08:16:10 charon-systemd[3789]: peer supports MOBIKE
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 23 08:16:10 charon-systemd[3789]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> scheduling rekeying in 26975s
+Jun 23 08:16:10 charon-systemd[3789]: scheduling rekeying in 26975s
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> maximum IKE_SA lifetime 29855s
+Jun 23 08:16:10 charon-systemd[3789]: maximum IKE_SA lifetime 29855s
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built
+Jun 23 08:16:10 charon-systemd[3789]: received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 08:16:10 charon-systemd[3789]: failed to establish CHILD_SA, keeping IKE_SA
+```
+
+There are messages: **NO_PROPOSAL_CHOSEN** and
+**failed to establish CHILD_SA** which refers that the problem is in
+the IPsec(ESP) proposal mismatch.
+
+The reason of this problem is showed on the responder side.
+
+```none
+Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 23 08:16:12 charon-systemd[2440]: received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ
+Jun 23 08:16:12 charon-systemd[2440]: configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ
+Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> no acceptable proposal found
+Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found
+Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> failed to establish CHILD_SA, keeping IKE_SA
+```
+
+Encryption **AES_CBC_128** is configured in IKE policy on the responder but **AES_CBC_256**
+is configured on the initiator side.
+
+### Prefixes in Policies Mismatch
+
+As in previous situation, IKE SA is in up state but IPsec SA is not up.
+According to logs we can see **TS_UNACCEPTABLE** notification. It means
+that prefixes (traffic selectors) mismatch on both sides
+
+Initiator:
+
+```none
+Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> received TS_UNACCEPTABLE notify, no CHILD_SA built
+Jun 23 14:13:17 charon-systemd[4996]: maximum IKE_SA lifetime 29437s
+Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 14:13:17 charon-systemd[4996]: received TS_UNACCEPTABLE notify, no CHILD_SA built
+Jun 23 14:13:17 charon-systemd[4996]: failed to establish CHILD_SA, keeping IKE_SA
+```
+
+The reason of this problem is showed on the responder side.
+
+```none
+Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable
+Jun 23 14:13:19 charon-systemd[2440]: traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable
+Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 14:13:19 charon-systemd[2440]: failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 14:13:19 charon[2440]: 01[ENC] <PEER|7> generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ]
+Jun 23 14:13:19 charon-systemd[2440]: generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ]
+```
+
+Traffic selectors **10.0.2.0/24 === 10.0.0.0/24** are unacceptable on the
+responder side.
diff --git a/docs/configuration/vpn/l2tp.md b/docs/configuration/vpn/l2tp.md
new file mode 100644
index 00000000..d932d095
--- /dev/null
+++ b/docs/configuration/vpn/l2tp.md
@@ -0,0 +1,624 @@
+(l2tp)=
+
+# L2TP
+
+VyOS utilizes [accel-ppp] to provide L2TP server functionality. It can be used
+with local authentication or a connected RADIUS server.
+
+## Configuring L2TP Server
+
+```none
+set vpn l2tp remote-access authentication mode local
+set vpn l2tp remote-access authentication local-users username test password 'test'
+set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254
+set vpn l2tp remote-access default-pool 'L2TP-POOL'
+set vpn l2tp remote-access outside-address 192.0.2.2
+set vpn l2tp remote-access gateway-address 192.168.255.1
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication mode \<local | radius\>
+
+Set authentication backend. The configured authentication backend is used
+for all queries.
+
+* **radius**: All authentication queries are handled by a configured RADIUS
+  server.
+* **local**: All authentication queries are handled locally.
+```
+
+
+```{cfgcmd} set vpn l2tp remote-access authentication local-users username \<user\> password \<pass\>
+
+Create `<user>` for local authentication on this system. The users password
+will be set to `<pass>`.
+```
+
+
+```{cfgcmd} set vpn l2tp remote-access client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\>
+
+Use this command to define the first IP address of a pool of
+addresses to be given to l2tp clients. If notation ``x.x.x.x-x.x.x.x``,
+it must be within a /24 subnet. If notation ``x.x.x.x/x`` is
+used there is possibility to set host/netmask.
+```
+
+
+```{cfgcmd} set vpn l2tp remote-access default-pool \<POOL-NAME\>
+
+Use this command to define default address pool name.
+```
+
+
+```{cfgcmd} set vpn l2tp remote-access gateway-address \<gateway\>
+
+Specifies single `<gateway>` IP address to be used as local address of PPP
+interfaces.
+```
+
+
+## Configuring IPsec
+
+```none
+set vpn ipsec interface eth0
+set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret
+set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret secret
+```
+
+
+```{cfgcmd} set vpn ipsec interface \<INTERFACE\>
+
+Use this command to define IPsec interface.
+```
+
+
+```{cfgcmd} set vpn l2tp remote-access ipsec-settings authentication mode \<pre-shared-secret | x509\>
+
+Set mode for IPsec authentication between VyOS and L2TP clients.
+```
+
+
+```{cfgcmd} set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret \<secret\>
+
+Set predefined shared secret phrase.
+```
+
+If a local firewall policy is in place on your external interface you will need
+to allow the ports below:
+- UDP port 500 (IKE)
+- IP protocol number 50 (ESP)
+- UDP port 1701 for IPsec
+
+As well as the below to allow NAT-traversal (when NAT is detected by the
+VPN client, ESP is encapsulated in UDP for NAT-traversal):
+
+- UDP port 4500 (NAT-T)
+
+Example:
+
+```none
+set firewall ipv4 name OUTSIDE-LOCAL rule 40 action 'accept'
+set firewall ipv4 name OUTSIDE-LOCAL rule 40 protocol 'esp'
+set firewall ipv4 name OUTSIDE-LOCAL rule 41 action 'accept'
+set firewall ipv4 name OUTSIDE-LOCAL rule 41 destination port '500'
+set firewall ipv4 name OUTSIDE-LOCAL rule 41 protocol 'udp'
+set firewall ipv4 name OUTSIDE-LOCAL rule 42 action 'accept'
+set firewall ipv4 name OUTSIDE-LOCAL rule 42 destination port '4500'
+set firewall ipv4 name OUTSIDE-LOCAL rule 42 protocol 'udp'
+set firewall ipv4 name OUTSIDE-LOCAL rule 43 action 'accept'
+set firewall ipv4 name OUTSIDE-LOCAL rule 43 destination port '1701'
+set firewall ipv4 name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec'
+set firewall ipv4 name OUTSIDE-LOCAL rule 43 protocol 'udp'
+```
+
+To allow VPN-clients access via your external address, a NAT rule is required:
+
+```none
+set nat source rule 110 outbound-interface name 'eth0'
+set nat source rule 110 source address '192.168.255.0/24'
+set nat source rule 110 translation address masquerade
+```
+
+
+## Configuring RADIUS authentication
+
+To enable RADIUS based authentication, the authentication mode needs to be
+changed within the configuration. Previous settings like the local users, still
+exists within the configuration, however they are not used if the mode has been
+changed from local to radius. Once changed back to local, it will use all local
+accounts again.
+
+```none
+set vpn l2tp remote-access authentication mode radius
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius server \<server\> key \<secret\>
+
+Configure RADIUS `<server>` and its required shared `<secret>` for
+communicating with the RADIUS server.
+```
+
+Since the RADIUS server would be a single point of failure, multiple RADIUS
+servers can be setup and will be used subsequentially.
+For example:
+
+```none
+set vpn l2tp remote-access authentication radius server 10.0.0.1 key 'foo'
+set vpn l2tp remote-access authentication radius server 10.0.0.2 key 'foo'
+```
+
+:::{note}
+Some RADIUS severs use an access control list which allows or denies
+queries, make sure to add your VyOS router to the allowed client list.
+:::
+
+### RADIUS source address
+
+If you are using OSPF as your IGP, use the interface connected closest to the
+RADIUS server. You can bind all outgoing RADIUS requests to a single source IP
+e.g. the loopback interface.
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queires.
+```
+
+:::{note}
+The `source-address` must be configured to that of an interface.
+Best practice would be a loopback or dummy interface.
+:::
+
+### RADIUS advanced options
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius server \<server\> port \<port\>
+
+Configure RADIUS `<server>` and its required port for authentication requests.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius server \<server\> fail-time \<time\>
+
+Mark RADIUS server as offline for this given `<time>` in seconds.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius server \<server\> disable
+
+Temporary disable this RADIUS server.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius acct-timeout \<timeout\>
+
+Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius dynamic-author server \<address\>
+
+Specifies IP address for Dynamic Authorization Extension server (DM/CoA).
+This IP must exist on any VyOS interface or it can be ``0.0.0.0``.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius dynamic-author port \<port\>
+
+UDP port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius dynamic-author key \<secret\>
+
+Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius max-try \<number\>
+
+Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius timeout \<timeout\>
+
+Timeout to wait response from server (seconds)
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius nas-identifier \<identifier\>
+
+Value to send to RADIUS server in NAS-Identifier attribute and to be matched
+in DM/CoA requests.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius nas-ip-address \<address\>
+
+Value to send to RADIUS server in NAS-IP-Address attribute and to be matched
+in DM/CoA requests. Also DM/CoA server will bind to that address.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queires.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius rate-limit attribute \<attribute\>
+
+Specifies which RADIUS server attribute contains the rate limit information.
+The default attribute is `Filter-Id`.
+```
+
+:::{note}
+If you set a custom RADIUS attribute you must define it on both
+dictionaries on the RADIUS server and client.
+:::
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius rate-limit enable
+
+Enables bandwidth shaping via RADIUS.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication radius rate-limit vendor
+
+Specifies the vendor dictionary. This dictionary needs to be present in
+/usr/share/accel-ppp/radius.
+```
+
+Received RADIUS attributes have a higher priority than parameters defined within
+the CLI configuration, refer to the explanation below.
+
+### Allocation clients ip addresses by RADIUS
+
+If the RADIUS server sends the attribute `Framed-IP-Address` then this IP
+address will be allocated to the client and the option `default-pool` within
+the CLI config will be ignored.
+
+If the RADIUS server sends the attribute `Framed-Pool`, then the IP address
+will be allocated from a predefined IP pool whose name equals the attribute
+value.
+
+If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, the
+IPv6 address will be allocated from a predefined IPv6 pool `prefix` whose
+name equals the attribute value.
+
+If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, an
+IPv6 delegation prefix will be allocated from a predefined IPv6 pool
+`delegate` whose name equals the attribute value.
+
+:::{note}
+`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in
+RFC6911. If they are not defined in your RADIUS server, add new [dictionary].
+:::
+
+The client's interface can be put into a VRF context via a RADIUS Access-Accept
+packet, or changed via RADIUS CoA. `Accel-VRF-Name` is used for these
+purposes. This is a custom [ACCEL-PPP attribute]. Define it in your RADIUS
+server.
+
+### Renaming clients interfaces by RADIUS
+
+If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be
+renamed.
+
+:::{note}
+The value of the attribute `NAS-Port-Id` must be less than 16
+characters, otherwise the interface won't be renamed.
+:::
+
+## Configuring LNS (L2TP Network Server)
+
+LNS are often used to connect to a LAC (L2TP Access Concentrator).
+
+```{cfgcmd} set vpn l2tp remote-access lns host-name \<hostname\>
+
+Sent to the client (LAC) in the Host-Name attribute
+```
+
+```{cfgcmd} set vpn l2tp remote-access lns shared-secret \<secret\>
+
+Tunnel password used to authenticate the client (LAC)
+```
+
+To explain the usage of LNS follow our blueprint {ref}`examples-lac-lns`.
+
+## IPv6
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options ipv6 \<require | prefer | allow | deny\>
+
+Specifies IPv6 negotiation preference.
+* **require** - Require IPv6 negotiation
+* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects
+* **allow** - Negotiate IPv6 only if client requests
+* **deny** - Do not negotiate IPv6 (default value)
+```
+
+```{cfgcmd} set vpn l2tp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\>
+
+Use this comand to set the IPv6 address pool from which an l2tp client will
+get an IPv6 prefix of your defined length (mask) to terminate the l2tp
+endpoint at their side. The mask length can be set between 48 and 128 bits
+long, the default value is 64.
+```
+
+```{cfgcmd} set vpn l2tp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\>
+
+Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on l2tp.
+You will have to set your IPv6 pool and the length of the delegation
+prefix. From the defined IPv6 pool you will be handing out networks of the
+defined length (delegation-prefix). The length of the delegation prefix can
+be between 32 and 64 bits long.
+```
+
+```{cfgcmd} set vpn l2tp remote-access default-ipv6-pool \<IPv6-POOL-NAME\>
+
+Use this command to define default IPv6 address pool name.
+```
+
+```none
+set vpn l2tp remote-access ppp-options ipv6 allow
+set vpn l2tp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56'
+set vpn l2tp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64'
+set vpn l2tp remote-access default-ipv6-pool IPv6-POOL
+```
+
+
+### IPv6 Advanced Options
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options ipv6-accept-peer-interface-id
+
+Accept peer interface identifier. By default this is not defined.
+```
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\>
+
+Specifies if a fixed or random interface identifier is used for IPv6. The
+default is fixed.
+* **random** - Random interface identifier for IPv6
+* **x:x:x:x** - Specify interface identifier for IPv6
+```
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\>
+
+Specifies the peer interface identifier for IPv6. The default is fixed.
+* **random** - Random interface identifier for IPv6
+* **x:x:x:x** - Specify interface identifier for IPv6
+* **ipv4-addr** - Calculate interface identifier from IPv4 address.
+* **calling-sid** - Calculate interface identifier from calling-station-id.
+```
+
+
+## Scripting
+
+```{cfgcmd} set vpn l2tp remote-access extended-scripts on-change \<path_to_script\>
+
+Script to run when the session interface is changed by RADIUS CoA handling
+```
+
+```{cfgcmd} set vpn l2tp remote-access extended-scripts on-down \<path_to_script\>
+
+Script to run when the session interface is about to terminate
+```
+
+```{cfgcmd} set vpn l2tp remote-access extended-scripts on-pre-up \<path_to_script\>
+
+Script to run before the session interface comes up
+```
+
+```{cfgcmd} set vpn l2tp remote-access extended-scripts on-up \<path_to_script\>
+
+Script to run when the session interface is completely configured and started
+```
+
+
+## Advanced Options
+
+### Authentication Advanced Options
+
+```{cfgcmd} set vpn l2tp remote-access authentication local-users username \<user\> disable
+
+Disable `<user>` account.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication local-users username \<user\> static-ip \<address\>
+
+Assign a static IP address to `<user>` account.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication local-users username \<user\> rate-limit download \<bandwidth\>
+
+Rate limit the download bandwidth for `<user>` to `<bandwidth>` kbit/s.
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication local-users username \<user\> rate-limit upload \<bandwidth\>
+
+Rate limit the upload bandwidth for `<user>` to `<bandwidth>` kbit/s
+```
+
+```{cfgcmd} set vpn l2tp remote-access authentication protocols \<pap | chap | mschap | mschap-v2\>
+
+Require the peer to authenticate itself using one of the following protocols:
+pap, chap, mschap, mschap-v2.
+```
+
+
+### Client IP Pool Advanced Options
+
+```{cfgcmd} set vpn l2tp remote-access client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\>
+
+Use this command to define the next address pool name.
+```
+
+
+### PPP Advanced Options
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options disable-ccp
+
+Disable Compression Control Protocol (CCP).
+CCP is enabled by default.
+```
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options interface-cache \<number\>
+
+Specifies number of interfaces to cache. This prevents interfaces from being
+removed once the corresponding session is destroyed. Instead, interfaces are
+cached for later use in new sessions. This should reduce the kernel-level
+interface creation/deletion rate.
+Default value is **0**.
+```
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options ipv4 \<require | prefer | allow | deny\>
+
+Specifies IPv4 negotiation preference.
+* **require** - Require IPv4 negotiation
+* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects
+* **allow** - Negotiate IPv4 only if client requests (Default value)
+* **deny** - Do not negotiate IPv4
+```
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options lcp-echo-failure \<number\>
+
+Defines the maximum `<number>` of unanswered echo requests. Upon reaching the
+value `<number>`, the session will be reset. Default value is **3**.
+```
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options lcp-echo-interval \<interval\>
+
+If this option is specified and is greater than 0, then the PPP module will
+send LCP echo requests every `<interval>` seconds.
+Default value is **30**.
+```
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options lcp-echo-timeout
+
+Specifies timeout in seconds to wait for any peer activity. If this option is
+specified it turns on adaptive lcp echo functionality and "lcp-echo-failure"
+is not used. Default value is **0**.
+```
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options min-mtu \<number\>
+
+Defines the minimum acceptable MTU. If a client tries to negotiate an MTU
+lower than this it will be NAKed, and disconnected if it rejects a greater
+MTU.
+Default value is **100**.
+```
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options mppe \<require | prefer | deny\>
+
+Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation
+preference.
+* **require** - ask client for mppe, if it rejects drop connection
+* **prefer** - ask client for mppe, if it rejects don't fail. (Default value)
+* **deny** - deny mppe
+
+Default behavior - don't ask the client for mppe, but allow it if the client
+wants. Please note that RADIUS may override this option with the
+MS-MPPE-Encryption-Policy attribute.
+```
+
+```{cfgcmd} set vpn l2tp remote-access ppp-options mru \<number\>
+
+Defines preferred MRU. By default is not defined.
+```
+
+
+### Global Advanced options
+
+```{cfgcmd} set vpn l2tp remote-access description \<description\>
+
+Set description.
+```
+
+```{cfgcmd} set vpn l2tp remote-access limits burst \<value\>
+
+Burst count
+```
+
+```{cfgcmd} set vpn l2tp remote-access limits connection-limit \<value\>
+
+Maximum accepted connection rate (e.g. 1/min, 60/sec)
+```
+
+```{cfgcmd} set vpn l2tp remote-access limits timeout \<value\>
+
+Timeout in seconds
+```
+
+```{cfgcmd} set vpn l2tp remote-access mtu
+
+Maximum Transmission Unit (MTU) (default: **1436**)
+```
+
+```{cfgcmd} set vpn l2tp remote-access max-concurrent-sessions
+
+Maximum number of concurrent session start attempts
+```
+
+```{cfgcmd} set vpn l2tp remote-access name-server \<address\>
+
+Connected clients should use `<address>` as their DNS server. This command
+accepts both IPv4 and IPv6 addresses. Up to two nameservers can be configured
+for IPv4, up to three for IPv6.
+```
+
+```{cfgcmd} set vpn l2tp remote-access shaper fwmark \<1-2147483647\>
+
+Match firewall mark value
+```
+
+```{cfgcmd} set vpn l2tp remote-access snmp master-agent
+
+Enable SNMP
+```
+
+```{cfgcmd} set vpn l2tp remote-access wins-server \<address\>
+
+Windows Internet Name Service (WINS) servers propagated to client
+```
+
+
+## Monitoring
+
+```none
+vyos@vyos:~$ show l2tp-server sessions
+ ifname | username |      ip       | ip6 | ip6-dp | calling-sid | rate-limit | state  |  uptime  | rx-bytes | tx-bytes
+--------+----------+---------------+-----+--------+-------------+------------+--------+----------+----------+----------
+ l2tp0  | test     | 192.168.255.3 |     |        | 192.168.0.36 |            | active | 02:01:47 | 7.7 KiB  | 1.2 KiB
+```
+
+```none
+vyos@vyos:~$ show l2tp-server statistics
+ uptime: 0.02:49:49
+cpu: 0%
+mem(rss/virt): 5920/100892 kB
+core:
+  mempool_allocated: 133202
+  mempool_available: 131770
+  thread_count: 1
+  thread_active: 1
+  context_count: 5
+  context_sleeping: 0
+  context_pending: 0
+  md_handler_count: 3
+  md_handler_pending: 0
+  timer_count: 0
+  timer_pending: 0
+sessions:
+  starting: 0
+  active: 0
+  finishing: 0
+l2tp:
+  tunnels:
+    starting: 0
+    active: 0
+    finishing: 0
+  sessions (control channels):
+    starting: 0
+    active: 0
+    finishing: 0
+  sessions (data channels):
+    starting: 0
+    active: 0
+    finishing: 0
+```
+
+[accel-ppp]: https://accel-ppp.org/
+[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
+[cloudflare]: https://blog.cloudflare.com/announcing-1111
+[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911
+[freeradius]: https://freeradius.org
+[google public dns]: https://developers.google.com/speed/public-dns
+[network policy server]: <https://en.wikipedia.org/wiki/Network_Policy_Server>
+[opennic]: https://www.opennic.org/
+[quad9]: https://quad9.net
+[radius]: https://en.wikipedia.org/wiki/RADIUS
diff --git a/docs/configuration/vpn/openconnect.md b/docs/configuration/vpn/openconnect.md
new file mode 100644
index 00000000..0bf804ff
--- /dev/null
+++ b/docs/configuration/vpn/openconnect.md
@@ -0,0 +1,330 @@
+(vpn-openconnect)=
+
+# OpenConnect
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+OpenConnect-compatible server feature has been available since Equuleus (1.3).
+Openconnect VPN supports SSL connection and offers full network access. SSL VPN
+network extension connects the end-user system to the corporate network with
+access controls based only on network layer information, such as destination IP
+address and port number. So, it provides safe communication for all types of
+device traffic across public networks and private networks, also encrypts the
+traffic with SSL protocol.
+
+The remote user will use the openconnect client to connect to the router and
+will receive an IP address from a VPN pool, allowing full access to the
+network.
+
+## Configuration
+
+### SSL Certificates
+
+We need to generate the certificate which authenticates users who attempt to
+access the network resource through the SSL VPN tunnels. The following commands
+will create a self signed certificates and will be stored in configuration:
+
+```none
+run generate pki ca install <CA name>
+run generate pki certificate sign <CA name> install <Server name>
+```
+
+We can also create the certificates using Certbot which is an easy-to-use
+client that fetches a certificate from Let's Encrypt an open certificate
+authority launched by the EFF, Mozilla, and others and deploys it to a web
+server.
+
+```none
+sudo certbot certonly --standalone --preferred-challenges http -d <domain name>
+```
+
+
+### Server Configuration
+
+```none
+set vpn openconnect authentication local-users username <user> password <pass>
+set vpn openconnect authentication mode <local password|radius|certificate>
+set vpn openconnect network-settings client-ip-settings subnet <subnet>
+set vpn openconnect network-settings name-server <address>
+set vpn openconnect network-settings name-server <address>
+set vpn openconnect ssl ca-certificate <pki-ca-name>
+set vpn openconnect ssl certificate <pki-cert-name>
+set vpn openconnect ssl passphrase <pki-password>
+```
+
+
+### 2FA OTP support
+
+Instead of password only authentication, 2FA password
+authentication + OTP key can be used. Alternatively, OTP authentication only,
+without a password, can be used.
+To do this, an OTP configuration must be added to the configuration above:
+
+```none
+set vpn openconnect authentication mode local <password-otp|otp>
+set vpn openconnect authentication local-users username <user> otp <key>
+set vpn openconnect authentication local-users username <user> interval <interval (optional)>
+set vpn openconnect authentication local-users username <user> otp-length <otp-length (optional)>
+set vpn openconnect authentication local-users username <user> token-type <token-type (optional)>
+```
+
+For generating an OTP key in VyOS, you can use the CLI command
+(operational mode):
+
+```none
+generate openconnect username <user> otp-key hotp-time
+```
+
+
+### User Certificate Authentication
+
+You can configure users to be authenticated by certificate by setting
+the authentication mode to certificate, and defining what field (by OID)
+in the certificate will be used to identify the username. Two pre-defined
+
+shortcuts for Common Name (OID 2.5.4.3) and User ID
+(OID 0.9.2342.19200300.100.1.1) have been provided as cn or uid.
+
+Otherwise a specific OID value must be provided.
+
+The user's certificate must be signed by the certificate authority
+defined in the configuration for it to be validated for authentication.
+
+```none
+set vpn openconnect authentication mode certificate
+set vpn openconnect authentication mode certificate user-identifier-field cn
+set vpn openconnect ssl ca-certificate <cert>
+```
+
+
+## Verification
+
+```none
+vyos@vyos:~$ sh openconnect-server sessions
+interface    username    ip             remote IP    RX       TX         state      uptime
+-----------  ----------  -------------  -----------  -------  ---------  ---------  --------
+sslvpn0      tst         172.20.20.198  192.168.6.1  0 bytes  152 bytes  connected  3s
+```
+
+:::{note}
+It is compatible with Cisco (R) AnyConnect (R) clients.
+:::
+
+## Example
+
+### SSL Certificates generation
+
+Follow the instructions to generate CA cert (in configuration mode):
+
+```none
+vyos@vyos# run generate pki ca install ca-ocserv
+Enter private key type: [rsa, dsa, ec] (Default: rsa)
+Enter private key bits: (Default: 2048)
+Enter country code: (Default: GB) US
+Enter state: (Default: Some-State) Delaware
+Enter locality: (Default: Some-City) Mycity
+Enter organization name: (Default: VyOS) MyORG
+Enter common name: (Default: vyos.io) oc-ca
+Enter how many days certificate will be valid: (Default: 1825) 3650
+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] N
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+```
+
+Follow the instructions to generate server cert (in configuration mode):
+
+```none
+vyos@vyos# run generate pki certificate sign ca-ocserv install srv-ocserv
+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) US
+Enter state: (Default: Some-State) Delaware
+Enter locality: (Default: Some-City) Mycity
+Enter organization name: (Default: VyOS) MyORG
+Enter common name: (Default: vyos.io) oc-srv
+Do you want to configure Subject Alternative Names? [y/N] N
+Enter how many days certificate will be valid: (Default: 365) 1830
+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] N
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+```
+
+Each of the install command should be applied to the configuration and commited
+before using under the openconnect configuration:
+
+```none
+vyos@vyos# commit
+[edit]
+vyos@vyos# save
+Saving configuration to '/config/config.boot'...
+Done
+[edit]
+```
+
+
+### Openconnect Configuration
+
+Simple setup with one user added and password authentication:
+
+```none
+set vpn openconnect authentication local-users username tst password 'OC_bad_Secret'
+set vpn openconnect authentication mode local password
+set vpn openconnect network-settings client-ip-settings subnet '172.20.20.0/24'
+set vpn openconnect network-settings name-server '10.1.1.1'
+set vpn openconnect network-settings name-server '10.1.1.2'
+set vpn openconnect ssl ca-certificate 'ca-ocserv'
+set vpn openconnect ssl certificate 'srv-ocserv'
+```
+
+To enable the HTTP security headers in the configuration file, use the command:
+
+```none
+set vpn openconnect http-security-headers
+```
+
+
+### Adding a 2FA with an OTP-key
+
+First the OTP keys must be generated and sent to the user and to the
+configuration:
+
+```none
+vyos@vyos:~$ generate openconnect username tst otp-key hotp-time
+# You can share it with the user, he just needs to scan the QR in his OTP app
+# username:  tst
+# OTP KEY:  5PA4SGYTQSGOBO3H3EQSSNCUNZAYAPH2
+# OTP URL:  otpauth://totp/tst@vyos?secret=5PA4SGYTQSGOBO3H3EQSSNCUNZAYAPH2&digits=6&period=30
+█████████████████████████████████████████
+█████████████████████████████████████████
+████ ▄▄▄▄▄ █▀ ██▄▀ ▄█▄▀▀▄▄▄▄██ ▄▄▄▄▄ ████
+████ █   █ █▀ █▄▄▀▀▀▄█  ▄▄▀▄ █ █   █ ████
+████ █▄▄▄█ █▀█▀▄▄▀  ▄▀ █▀ ▀▄██ █▄▄▄█ ████
+████▄▄▄▄▄▄▄█▄█▄▀ ▀▄█ ▀ ▀ ▀ █▄█▄▄▄▄▄▄▄████
+████  ▄▄▄▀▄▄  ▄███▀▄▀█▄██▀ ▀▄ ▀▄█ ▀ ▀████
+████ ▀▀ ▀ ▄█▄ ▀ ▀▄ ▄█▀ ▄█ ▄▀▀▄██    █████
+████▄ █▄▀▀▄█▀ ▀█▄█▄▄▄▄ ▄▀█▀▀█ ▀ ▄ ▀█▀████
+█████  ▀█▀▄▄ █ ▀▄▄  ▄█▄    ▀█▀▀ █▀ ▄█████
+████▀██▀█▄▄ ▀▀▀▀█▄▀ ▀█▄▄▀▀▀ ▀ ▀█▄██▀▀████
+████▄ ▄ ▄▀▄██▀█ ▄ ▀▄██ ▄▄  ▀▀▄█▄██ ▄█████
+████▀▀ ▄▀ ▄ ▀█▀█▀█  █▀█▄▄▀█▀█▄██▄▄█ ▀████
+████ █ ▀█▄▄█▄ ▀ ▄▄▀▀  ▀ █▄█▀████ █▀ ▀████
+████▄██▄██▄█▀ ▄▀ ▄▄▀▄  ▄▀█ ▄ ▄▄▄ ▀█▄ ████
+████ ▄▄▄▄▄ █▄  ▀█▄█ ▄ ▀ ▄ ▄  █▄█ ▄▀▄█████
+████ █   █ █ ▀▄██▄▄▀█▄▀▄██▄▀  ▄  ▀██▀████
+████ █▄▄▄█ █ ██▀▄▄  ▀▄▄▀█▀ ▀█ ▄▀█ ▀██████
+████▄▄▄▄▄▄▄█▄███▄███▄█▄▄▄▄█▄▄█▄██▄█▄█████
+█████████████████████████████████████████
+█████████████████████████████████████████
+# To add this OTP key to configuration, run the following commands:
+set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa'
+```
+
+Next it is necessary to configure 2FA for OpenConnect:
+
+```none
+set vpn openconnect authentication mode local password-otp
+set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa'
+```
+
+Now when connecting the user will first be asked for the password
+and then the OTP key.
+
+:::{warning}
+When using Time-based one-time password (TOTP) (OTP HOTP-time),
+be sure that the time on the server and the
+OTP token generator are synchronized by NTP
+:::
+
+To display the configured OTP user settings, use the command:
+
+```none
+show openconnect-server user <username> otp <full|key-b32|key-hex|qrcode|uri>
+```
+
+
+### Identity Based Configuration
+
+OpenConnect supports a subset of it's configuration options to be applied on a
+per user/group basis, for configuration purposes we refer to this functionality
+as "Identity based config". The following [OpenConnect Server Manual](https://ocserv.gitlab.io/www/manual.html#:~:text=Configuration%20files%20that%20will%20be%20applied%20per%20user%20connection%20or%0A%23%20per%20group)
+outlines the set of configuration options that are allowed. This can be
+leveraged to apply different sets of configs to different users or groups of
+users.
+
+```none
+sudo mkdir -p /config/auth/ocserv/config-per-user
+sudo touch /config/auth/ocserv/default-user.conf
+
+set vpn openconnect authentication identity-based-config mode user
+set vpn openconnect authentication identity-based-config directory /config/auth/ocserv/config-per-user
+set vpn openconnect authentication identity-based-config default-config /config/auth/ocserv/default-user.conf
+```
+
+:::{warning}
+The above directory and default-config must be a child directory
+of /config/auth, since files outside this directory are not persisted after an
+image upgrade.
+:::
+
+Once you commit the above changes you can create a config file in the
+/config/auth/ocserv/config-per-user directory that matches a username of a
+user you have created e.g. "tst". Now when logging in with the "tst" user the
+config options you set in this file will be loaded.
+
+Be sure to set a sane default config in the default config file, this will be
+loaded in the case that a user is authenticated and no file is found in the
+configured directory matching the users username/group.
+
+```none
+sudo nano /config/auth/ocserv/config-per-user/tst
+```
+
+The same configuration options apply when Identity based config is configured
+in group mode except that group mode can only be used with RADIUS
+authentication.
+
+:::{warning}
+OpenConnect server matches the filename in a case sensitive
+manner, make sure the username/group name you configure matches the
+filename exactly.
+:::
+
+### Configuring RADIUS accounting
+
+OpenConnect can be configured to send accounting information to a
+RADIUS server to capture user session data such as time of
+connect/disconnect, data transferred, and so on.
+
+Configure an accounting server and enable accounting with:
+
+```none
+set vpn openconnect accounting mode radius
+set vpn openconnect accounting radius server 172.20.20.10
+set vpn openconnect accounting radius server 172.20.20.10 port 1813
+set vpn openconnect accounting radius server 172.20.20.10 key your_radius_secret
+```
+
+:::{warning}
+The RADIUS accounting feature must be used with the OpenConnect
+authentication mode RADIUS. It cannot be used with local authentication.
+You must configure the OpenConnect authentication mode to "radius".
+:::
+
+An example of the data captured by a FREERADIUS server with sql accounting:
+
+```none
+mysql> SELECT username, nasipaddress, acctstarttime, acctstoptime, acctinputoctets, acctoutputoctets, callingstationid, framedipaddress, connectinfo_start FROM radacct;
++----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+
+| username | nasipaddress  | acctstarttime       | acctstoptime        | acctinputoctets | acctoutputoctets | callingstationid  | framedipaddress | connectinfo_start                 |
++----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+
+| test     | 198.51.100.15 | 2023-01-13 00:59:15 | 2023-01-13 00:59:21 |           10606 |              152 | 192.168.6.1       | 172.20.20.198   | Open AnyConnect VPN Agent v8.05-1 |
++----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+
+```
+
diff --git a/docs/configuration/vpn/pptp.md b/docs/configuration/vpn/pptp.md
new file mode 100644
index 00000000..5df63755
--- /dev/null
+++ b/docs/configuration/vpn/pptp.md
@@ -0,0 +1,594 @@
+(pptp)=
+
+# PPTP-Server
+
+The Point-to-Point Tunneling Protocol (PPTP) has been implemented in VyOS only
+for backwards compatibility. PPTP has many well known security issues and you
+should use one of the many other new VPN implementations.
+
+## Configuring PPTP Server
+
+```none
+set vpn pptp remote-access authentication mode local
+set vpn pptp remote-access authentication local-users username test password 'test'
+set vpn pptp remote-access client-ip-pool PPTP-POOL range 192.168.255.2-192.168.255.254
+set vpn pptp remote-access default-pool 'PPTP-POOL'
+set vpn pptp remote-access outside-address 192.0.2.2
+set vpn pptp remote-access gateway-address 192.168.255.1
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication mode \<local | radius\>
+
+Set authentication backend. The configured authentication backend is used
+for all queries.
+* **radius**: All authentication queries are handled by a configured RADIUS
+server.
+* **local**: All authentication queries are handled locally.
+* **noauth**: Authentication disabled.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication local-users username \<user\> password \<pass\>
+
+Create `<user>` for local authentication on this system. The users password
+will be set to `<pass>`.
+```
+
+```{cfgcmd} set vpn pptp remote-access client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\>
+
+Use this command to define the first IP address of a pool of
+addresses to be given to PPTP clients. If notation ``x.x.x.x-x.x.x.x``,
+it must be within a /24 subnet. If notation ``x.x.x.x/x`` is
+used there is possibility to set host/netmask.
+```
+
+```{cfgcmd} set vpn pptp remote-access default-pool \<POOL-NAME\>
+
+Use this command to define default address pool name.
+```
+
+```{cfgcmd} set vpn pptp remote-access gateway-address \<gateway\>
+
+Specifies single `<gateway>` IP address to be used as local address of PPP
+interfaces.
+```
+
+
+## Configuring RADIUS authentication
+
+To enable RADIUS based authentication, the authentication mode needs to be
+changed within the configuration. Previous settings like the local users, still
+exists within the configuration, however they are not used if the mode has been
+changed from local to radius. Once changed back to local, it will use all local
+accounts again.
+
+```none
+set vpn pptp remote-access authentication mode radius
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius server \<server\> key \<secret\>
+
+Configure RADIUS `<server>` and its required shared `<secret>` for
+communicating with the RADIUS server.
+```
+
+Since the RADIUS server would be a single point of failure, multiple RADIUS
+servers can be setup and will be used subsequentially.
+For example:
+
+```none
+set vpn pptp remote-access authentication radius server 10.0.0.1 key 'foo'
+set vpn pptp remote-access authentication radius server 10.0.0.2 key 'foo'
+```
+
+:::{note}
+Some RADIUS severs use an access control list which allows or denies
+queries, make sure to add your VyOS router to the allowed client list.
+:::
+
+### RADIUS source address
+
+If you are using OSPF as IGP, always the closest interface connected to the
+RADIUS server is used. You can bind all outgoing RADIUS requests
+to a single source IP e.g. the loopback interface.
+
+```{cfgcmd} set vpn pptp remote-access authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queires.
+```
+
+:::{note}
+Some RADIUS severs use an access control list which allows or denies
+queries, make sure to add your VyOS router to the allowed client list.
+:::
+
+### RADIUS advanced options
+
+```{cfgcmd} set vpn pptp remote-access authentication radius server \<server\> port \<port\>
+
+Configure RADIUS `<server>` and its required port for authentication requests.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius server \<server\> fail-time \<time\>
+
+Mark RADIUS server as offline for this given `<time>` in seconds.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius server \<server\> disable
+
+Temporary disable this RADIUS server.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius acct-timeout \<timeout\>
+
+Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius dynamic-author server \<address\>
+
+Specifies IP address for Dynamic Authorization Extension server (DM/CoA).
+This IP must exist on any VyOS interface or it can be ``0.0.0.0``.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius dynamic-author port \<port\>
+
+UDP port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius dynamic-author key \<secret\>
+
+Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius max-try \<number\>
+
+Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius timeout \<timeout\>
+
+Timeout to wait response from server (seconds)
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius nas-identifier \<identifier\>
+
+Value to send to RADIUS server in NAS-Identifier attribute and to be matched
+in DM/CoA requests.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius nas-ip-address \<address\>
+
+Value to send to RADIUS server in NAS-IP-Address attribute and to be matched
+in DM/CoA requests. Also DM/CoA server will bind to that address.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queires.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius rate-limit attribute \<attribute\>
+
+Specifies which RADIUS server attribute contains the rate limit information.
+The default attribute is `Filter-Id`.
+```
+
+:::{note}
+If you set a custom RADIUS attribute you must define it on both
+dictionaries at RADIUS server and client.
+:::
+
+```{cfgcmd} set vpn pptp remote-access authentication radius rate-limit enable
+
+Enables bandwidth shaping via RADIUS.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication radius rate-limit vendor
+
+Specifies the vendor dictionary, dictionary needs to be in
+/usr/share/accel-ppp/radius.
+```
+
+Received RADIUS attributes have a higher priority than parameters defined within
+the CLI configuration, refer to the explanation below.
+
+### Allocation clients ip addresses by RADIUS
+
+If the RADIUS server sends the attribute `Framed-IP-Address` then this IP
+address will be allocated to the client and the option `default-pool` within the CLI
+config is being ignored.
+
+If the RADIUS server sends the attribute `Framed-Pool`, IP address will be allocated
+from a predefined IP pool whose name equals the attribute value.
+
+If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, IPv6 address
+will be allocated from a predefined IPv6 pool `prefix` whose name equals the attribute value.
+
+If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, IPv6
+delegation pefix will be allocated from a predefined IPv6 pool `delegate`
+whose name equals the attribute value.
+
+:::{note}
+`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in
+RFC6911. If they are not defined in your RADIUS server, add new [dictionary].
+:::
+
+User interface can be put to VRF context via RADIUS Access-Accept packet, or change
+it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. It is custom [ACCEL-PPP attribute].
+Define it in your RADIUS server.
+
+### Renaming clients interfaces by RADIUS
+
+If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be
+renamed.
+
+:::{note}
+The value of the attribute `NAS-Port-Id` must be less than 16
+characters, otherwise the interface won't be renamed.
+:::
+
+## IPv6
+
+```{cfgcmd} set vpn pptp remote-access ppp-options ipv6 \<require | prefer | allow | deny\>
+
+Specifies IPv6 negotiation preference.
+* **require** - Require IPv6 negotiation
+* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects
+* **allow** - Negotiate IPv6 only if client requests
+* **deny** - Do not negotiate IPv6 (default value)
+```
+
+```{cfgcmd} set vpn pptp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\>
+
+Use this comand to set the IPv6 address pool from which an PPTP client
+will get an IPv6 prefix of your defined length (mask) to terminate the
+PPTP endpoint at their side. The mask length can be set from 48 to 128
+bit long, the default value is 64.
+```
+
+```{cfgcmd} set vpn pptp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\>
+
+Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on
+PPTP. You will have to set your IPv6 pool and the length of the
+delegation prefix. From the defined IPv6 pool you will be handing out
+networks of the defined length (delegation-prefix). The length of the
+delegation prefix can be set from 32 to 64 bit long.
+```
+
+```{cfgcmd} set vpn pptp remote-access default-ipv6-pool \<IPv6-POOL-NAME\>
+
+Use this command to define default IPv6 address pool name.
+```
+
+```none
+set vpn pptp remote-access ppp-options ipv6 allow
+set vpn pptp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56'
+set vpn pptp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64'
+set vpn pptp remote-access default-ipv6-pool IPv6-POOL
+```
+
+
+### IPv6 Advanced Options
+
+```{cfgcmd} set vpn pptp remote-access ppp-options ipv6-accept-peer-interface-id
+
+Accept peer interface identifier. By default is not defined.
+```
+
+```{cfgcmd} set vpn pptp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\>
+
+Specifies fixed or random interface identifier for IPv6.
+By default is fixed.
+* **random** - Random interface identifier for IPv6
+* **x:x:x:x** - Specify interface identifier for IPv6
+```
+
+```{cfgcmd} set vpn pptp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\>
+
+Specifies peer interface identifier for IPv6. By default is fixed.
+* **random** - Random interface identifier for IPv6
+* **x:x:x:x** - Specify interface identifier for IPv6
+* **ipv4-addr** - Calculate interface identifier from IPv4 address.
+* **calling-sid** - Calculate interface identifier from calling-station-id.
+```
+
+
+## Scripting
+
+```{cfgcmd} set vpn pptp remote-access extended-scripts on-change \<path_to_script\>
+
+Script to run when session interface changed by RADIUS CoA handling
+```
+
+```{cfgcmd} set vpn pptp remote-access extended-scripts on-down \<path_to_script\>
+
+Script to run when session interface going to terminate
+```
+
+```{cfgcmd} set vpn pptp remote-access extended-scripts on-pre-up \<path_to_script\>
+
+Script to run before session interface comes up
+```
+
+```{cfgcmd} set vpn pptp remote-access extended-scripts on-up \<path_to_script\>
+
+Script to run when session interface is completely configured and started
+```
+
+
+## Advanced Options
+
+### Authentication Advanced Options
+
+```{cfgcmd} set vpn pptp remote-access authentication local-users username \<user\> disable
+
+Disable `<user>` account.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication local-users username \<user\> static-ip \<address\>
+
+Assign static IP address to `<user>` account.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication local-users username \<user\> rate-limit download \<bandwidth\>
+
+Download bandwidth limit in kbit/s for `<user>`.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication local-users username \<user\> rate-limit upload \<bandwidth\>
+
+Upload bandwidth limit in kbit/s for `<user>`.
+```
+
+```{cfgcmd} set vpn pptp remote-access authentication protocols \<pap | chap | mschap | mschap-v2\>
+
+Require the peer to authenticate itself using one of the following protocols:
+pap, chap, mschap, mschap-v2.
+```
+
+
+### Client IP Pool Advanced Options
+
+```{cfgcmd} set vpn pptp remote-access client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\>
+
+Use this command to define the next address pool name.
+```
+
+
+### PPP Advanced Options
+
+```{cfgcmd} set vpn pptp remote-access ppp-options disable-ccp
+
+Disable Compression Control Protocol (CCP).
+CCP is enabled by default.
+```
+
+```{cfgcmd} set vpn pptp remote-access ppp-options interface-cache \<number\>
+
+Specifies number of interfaces to keep in cache. It means that don’t
+destroy interface after corresponding session is destroyed, instead
+place it to cache and use it later for new sessions repeatedly.
+This should reduce kernel-level interface creation/deletion rate lack.
+Default value is **0**.
+```
+
+```{cfgcmd} set vpn pptp remote-access ppp-options ipv4 \<require | prefer | allow | deny\>
+
+Specifies IPv4 negotiation preference.
+* **require** - Require IPv4 negotiation
+* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects
+* **allow** - Negotiate IPv4 only if client requests (Default value)
+* **deny** - Do not negotiate IPv4
+```
+
+```{cfgcmd} set vpn pptp remote-access ppp-options lcp-echo-failure \<number\>
+
+Defines the maximum `<number>` of unanswered echo requests. Upon reaching the
+value `<number>`, the session will be reset. Default value is **3**.
+```
+
+```{cfgcmd} set vpn pptp remote-access ppp-options lcp-echo-interval \<interval\>
+
+If this option is specified and is greater than 0, then the PPP module will
+send LCP pings of the echo request every `<interval>` seconds.
+Default value is **30**.
+```
+
+```{cfgcmd} set vpn pptp remote-access ppp-options lcp-echo-timeout
+
+Specifies timeout in seconds to wait for any peer activity. If this option
+specified it turns on adaptive lcp echo functionality and "lcp-echo-failure"
+is not used. Default value is **0**.
+```
+
+```{cfgcmd} set vpn pptp remote-access ppp-options min-mtu \<number\>
+
+Defines minimum acceptable MTU. If client will try to negotiate less then
+specified MTU then it will be NAKed or disconnected if rejects greater MTU.
+Default value is **100**.
+```
+
+```{cfgcmd} set vpn pptp remote-access ppp-options mppe \<require | prefer | deny\>
+
+Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation
+preference.
+* **require** - ask client for mppe, if it rejects drop connection
+* **prefer** - ask client for mppe, if it rejects don't fail. (Default value)
+* **deny** - deny mppe
+
+Default behavior - don't ask client for mppe, but allow it if client wants.
+Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy
+attribute.
+```
+
+```{cfgcmd} set vpn pptp remote-access ppp-options mru \<number\>
+
+Defines preferred MRU. By default is not defined.
+```
+
+
+### Global Advanced options
+
+```{cfgcmd} set vpn pptp remote-access description \<description\>
+
+Set description.
+```
+
+```{cfgcmd} set vpn pptp remote-access limits burst \<value\>
+
+Burst count
+```
+
+```{cfgcmd} set vpn pptp remote-access limits connection-limit \<value\>
+
+Acceptable rate of connections (e.g. 1/min, 60/sec)
+```
+
+```{cfgcmd} set vpn pptp remote-access limits timeout \<value\>
+
+Timeout in seconds
+```
+
+```{cfgcmd} set vpn pptp remote-access mtu
+
+Maximum Transmission Unit (MTU) (default: **1436**)
+```
+
+```{cfgcmd} set vpn pptp remote-access max-concurrent-sessions
+
+Maximum number of concurrent session start attempts
+```
+
+```{cfgcmd} set vpn pptp remote-access name-server \<address\>
+
+Connected client should use `<address>` as their DNS server. This
+command accepts both IPv4 and IPv6 addresses. Up to two nameservers
+can be configured for IPv4, up to three for IPv6.
+```
+
+```{cfgcmd} set vpn pptp remote-access shaper fwmark \<1-2147483647\>
+
+Match firewall mark value
+```
+
+```{cfgcmd} set vpn pptp remote-access snmp master-agent
+
+Enable SNMP
+```
+
+```{cfgcmd} set vpn pptp remote-access wins-server \<address\>
+
+Windows Internet Name Service (WINS) servers propagated to client
+```
+
+
+## Monitoring
+
+```{opcmd} show pptp-server sessions
+
+Use this command to locally check the active sessions in the PPTP
+server.
+```
+
+```none
+vyos@vyos:~$ show pptp-server sessions
+ ifname | username |    ip    | ip6 | ip6-dp |   calling-sid  | rate-limit | state  |  uptime  | rx-bytes | tx-bytes
+--------+----------+----------+-----+--------+----------------+------------+--------+----------+----------+----------
+ pptp0  | test     | 10.0.0.2 |     |        | 192.168.10.100 |            | active | 00:01:26 | 6.9 KiB  | 220 B
+```
+
+```none
+vyos@vyos:~$ show pptp-server statistics
+ uptime: 0.00:04:52
+cpu: 0%
+mem(rss/virt): 5504/100176 kB
+core:
+  mempool_allocated: 152007
+  mempool_available: 149007
+  thread_count: 1
+  thread_active: 1
+  context_count: 6
+  context_sleeping: 0
+  context_pending: 0
+  md_handler_count: 6
+  md_handler_pending: 0
+  timer_count: 2
+  timer_pending: 0
+sessions:
+  starting: 0
+  active: 1
+  finishing: 0
+pptp:
+  starting: 0
+  active: 1
+```
+
+
+## Troubleshooting
+
+```none
+vyos@vyos:~$sudo journalctl -u accel-ppp@pptp -b 0
+
+Feb 29 14:58:57 vyos accel-pptp[4629]: pptp: new connection from 192.168.10.100
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Start-Ctrl-Conn-Request <Version 1> <Framing 1> <Bearer 1> <Max-Chan 0>]
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [PPTP Start-Ctrl-Conn-Reply <Version 1> <Result 1> <Error 0> <Framing 3> <Bearer 3> <Max-Chan 1>]
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Outgoing-Call-Request <Call-ID 2961> <Call-Serial 2> <Min-BPS 300> <Max-BPS 100000000> <Bearer 3> <Framing 3> <Window-Size 64> <Delay 0>]
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [PPTP Outgoing-Call-Reply <Call-ID 2> <Peer-Call-ID 2961> <Result 1> <Error 0> <Cause 0> <Speed 100000000> <Window-Size 64> <Delay 0> <Channel 0>]
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: lcp_layer_init
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: auth_layer_init
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: ccp_layer_init
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: ipcp_layer_init
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: ipv6cp_layer_init
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: ppp establishing
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: lcp_layer_start
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfReq id=75 <auth PAP> <mru 1436> <magic 483920bd>]
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Set-Link-Info]
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [LCP ConfReq id=0 <mru 1400> <magic 0142785a> <pcomp> <accomp> < d 3 6 >]
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfRej id=0 <pcomp> <accomp> < d 3 6 >]
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [LCP ConfReq id=1 <mru 1400> <magic 0142785a>]
+Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfAck id=1]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: fsm timeout 9
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=75 <auth PAP> <mru 1436> <magic 483920bd>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=75 <auth MSCHAP-v2>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=76 <auth CHAP-md5> <mru 1436> <magic 483920bd>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=76 <auth MSCHAP-v2>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=77 <auth MSCHAP-v1> <mru 1436> <magic 483920bd>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=77 <auth MSCHAP-v2>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=78 <auth MSCHAP-v2> <mru 1436> <magic 483920bd>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfAck id=78 <auth MSCHAP-v2> <mru 1436> <magic 483920bd>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: lcp_layer_started
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: auth_layer_start
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [MSCHAP-v2 Challenge id=1 <8aa758781676e6a8e85c11963ee010>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP Ident id=2 <MSRASV5.20>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP Ident id=3 <MSRAS-0-MSEDGEWIN10>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: [43B blob data]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [PPTP Set-Link-Info]
+Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [MSCHAP-v2 Response id=1 <90c21af1091f745e8bf22388b058>, <e695ae5aae274c88a3fa1ee3dc9057aece4d53c87b9fea>, F=0, name="test"]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: connect: ppp0 <--> pptp(192.168.10.100)
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ppp connected
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [MSCHAP-v2 Success id=1 "S=347F417CF04BEBBC7F75CFA7F43474C36FB218F9 M=Authentication succeeded"]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: test: authentication succeeded
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: auth_layer_started
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ccp_layer_start
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [CCP ConfReq id=b9 <mppe +H -M +S -L -D -C>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipcp_layer_start
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipv6cp_layer_start
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: IPV6CP: discarding packet
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [LCP ProtoRej id=122 <8057>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=6 <addr 0.0.0.0> <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfReq id=3b <addr 10.0.0.1>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfRej id=6 <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [LCP ProtoRej id=7 <80fd>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ccp_layer_finished
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfAck id=3b <addr 10.0.0.1>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=8 <addr 0.0.0.0>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfNak id=8 <addr 10.0.0.2>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=9 <addr 10.0.0.2>]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfAck id=9]
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipcp_layer_started
+Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: rename interface to 'pptp0'
+Feb 29 14:59:00 vyos accel-pptp[4629]: pptp0:test: pptp: ppp started
+```
+
+[accel-ppp]: https://accel-ppp.org/
+[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
+[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911
diff --git a/docs/configuration/vpn/rsa-keys.md b/docs/configuration/vpn/rsa-keys.md
new file mode 100644
index 00000000..b224b514
--- /dev/null
+++ b/docs/configuration/vpn/rsa-keys.md
@@ -0,0 +1,114 @@
+# RSA-Keys
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+RSA can be used for services such as key exchanges and for encryption purposes.
+To make IPSec work with dynamic address on one/both sides, we will have to use
+RSA keys for authentication. They are very fast and easy to setup.
+
+First, on both routers run the operational command "generate pki key-pair
+install \<key-pair nam>>". You may choose different length than 2048 of course.
+
+```none
+vyos@left# run generate pki key-pair install ipsec-LEFT
+Enter private key type: [rsa, dsa, ec] (Default: rsa)
+Enter private key bits: (Default: 2048)
+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] N
+Configure mode commands to install key pair:
+Do you want to install the public key? [Y/n] Y
+set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'
+Do you want to install the private key? [Y/n] Y
+set pki key-pair ipsec-LEFT private key 'MIIEvgIBADAN...'
+[edit]
+```
+
+Configuration commands will display.
+Note the command with the public key
+(set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...').
+Then do the same on the opposite router:
+
+```none
+vyos@left# run generate pki key-pair install ipsec-RIGHT
+```
+
+Note the command with the public key
+(set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...').
+
+The noted public keys should be entered on the opposite routers.
+
+On the LEFT:
+
+```none
+set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...'
+```
+
+On the RIGHT:
+
+```none
+set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'
+```
+
+Now you are ready to setup IPsec. The key points:
+1. Since both routers do not know their effective public addresses,
+   we set the local-address of the peer to "any".
+2. On the initiator, we set the peer address to its public address,
+   but on the responder we only set the id.
+3. On the initiator, we need to set the remote-id option so that it
+   can identify IKE traffic from the responder correctly.
+4. On the responder, we need to set the local id so that initiator
+   can know who's talking to it for the point #3 to work.
+
+On the LEFT (static address):
+
+```none
+set vpn ipsec interface eth0
+
+set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128
+set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1
+
+set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2
+set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128
+set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1
+
+set vpn ipsec site-to-site peer @RIGHT authentication id LEFT
+set vpn ipsec site-to-site peer @RIGHT authentication mode rsa
+set vpn ipsec site-to-site peer @RIGHT authentication rsa local-key ipsec-LEFT
+set vpn ipsec site-to-site peer @RIGHT authentication rsa remote-key ipsec-RIGHT
+set vpn ipsec site-to-site peer @RIGHT authentication remote-id RIGHT
+set vpn ipsec site-to-site peer @RIGHT default-esp-group MyESPGroup
+set vpn ipsec site-to-site peer @RIGHT ike-group MyIKEGroup
+set vpn ipsec site-to-site peer @RIGHT local-address 192.0.2.10
+set vpn ipsec site-to-site peer @RIGHT connection-type none
+set vpn ipsec site-to-site peer @RIGHT tunnel 1 local prefix 192.168.99.1/32  # Additional loopback address on the local
+set vpn ipsec site-to-site peer @RIGHT tunnel 1 remote prefix 192.168.99.2/32 # Additional loopback address on the remote
+```
+
+On the RIGHT (dynamic address):
+
+```none
+set vpn ipsec interface eth0
+
+set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128
+set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1
+
+set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2
+set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128
+set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1
+
+set vpn ipsec site-to-site peer 192.0.2.10 authentication id RIGHT
+set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa
+set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa local-key ipsec-RIGHT
+set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa remote-key ipsec-LEFT
+set vpn ipsec site-to-site peer 192.0.2.10 authentication remote-id LEFT
+set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate
+set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup
+set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup
+set vpn ipsec site-to-site peer 192.0.2.10 local-address any
+set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32  # Additional loopback address on the local
+set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote
+```
+
diff --git a/docs/configuration/vpn/sstp.md b/docs/configuration/vpn/sstp.md
new file mode 100644
index 00000000..54383cc6
--- /dev/null
+++ b/docs/configuration/vpn/sstp.md
@@ -0,0 +1,698 @@
+(sstp)=
+
+# SSTP Server
+
+{abbr}`SSTP (Secure Socket Tunneling Protocol)` is a form of {abbr}`VPN
+(Virtual Private Network)` tunnel that provides a mechanism to transport PPP
+traffic through an SSL/TLS channel. SSL/TLS provides transport-level security
+with key negotiation, encryption and traffic integrity checking. The use of
+SSL/TLS over TCP port 443 allows SSTP to pass through virtually all firewalls
+and proxy servers except for authenticated web proxies.
+
+SSTP is available for Linux, BSD, and Windows.
+
+VyOS utilizes [accel-ppp](https://accel-ppp.org/) to provide SSTP server functionality. We support both
+local and RADIUS authentication.
+
+As SSTP provides PPP via a SSL/TLS channel the use of either publicly signed
+certificates or private PKI is required.
+
+## Configuring SSTP Server
+
+### Certificates
+
+Using our documentation chapter - {ref}`pki` generate and install CA and Server certificate
+
+```none
+vyos@vyos:~$ generate pki ca install CA
+```
+
+```none
+vyos@vyos:~$ generate pki certificate sign CA install Server
+```
+
+
+### Configuration
+
+```none
+set vpn sstp authentication local-users username test password 'test'
+set vpn sstp authentication mode 'local'
+set vpn sstp client-ip-pool SSTP-POOL range '10.0.0.2-10.0.0.100'
+set vpn sstp default-pool 'SSTP-POOL'
+set vpn sstp gateway-address '10.0.0.1'
+set vpn sstp ssl ca-certificate 'CA1'
+set vpn sstp ssl certificate 'Server'
+```
+
+```{cfgcmd} set vpn sstp authentication mode \<local | radius\>
+
+Set authentication backend. The configured authentication backend is used
+for all queries.
+* **radius**: All authentication queries are handled by a configured RADIUS
+server.
+* **local**: All authentication queries are handled locally.
+```
+
+```{cfgcmd} set vpn sstp authentication local-users username \<user\> password \<pass\>
+
+Create `<user>` for local authentication on this system. The users password
+will be set to `<pass>`.
+```
+
+```{cfgcmd} set vpn sstp client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\>
+
+Use this command to define the first IP address of a pool of
+addresses to be given to SSTP clients. If notation ``x.x.x.x-x.x.x.x``,
+it must be within a /24 subnet. If notation ``x.x.x.x/x`` is
+used there is possibility to set host/netmask.
+```
+
+```{cfgcmd} set vpn sstp default-pool \<POOL-NAME\>
+
+Use this command to define default address pool name.
+```
+
+```{cfgcmd} set vpn sstp gateway-address \<gateway\>
+
+Specifies single `<gateway>` IP address to be used as local address of PPP
+interfaces.
+```
+
+```{cfgcmd} set vpn sstp ssl ca-certificate \<file\>
+
+Name of installed certificate authority certificate.
+```
+
+```{cfgcmd} set vpn sstp ssl certificate \<file\>
+
+Name of installed server certificate.
+```
+
+
+## Configuring RADIUS authentication
+
+To enable RADIUS based authentication, the authentication mode needs to be
+changed within the configuration. Previous settings like the local users still
+exist within the configuration, however they are not used if the mode has been
+changed from local to radius. Once changed back to local, it will use all local
+accounts again.
+
+```none
+set vpn sstp authentication mode radius
+```
+
+```{cfgcmd} set vpn sstp authentication radius server \<server\> key \<secret\>
+
+Configure RADIUS `<server>` and its required shared `<secret>` for
+communicating with the RADIUS server.
+```
+
+Since the RADIUS server would be a single point of failure, multiple RADIUS
+servers can be setup and will be used subsequentially.
+For example:
+
+```none
+set vpn sstp authentication radius server 10.0.0.1 key 'foo'
+set vpn sstp authentication radius server 10.0.0.2 key 'foo'
+```
+
+:::{note}
+Some RADIUS severs use an access control list which allows or denies
+queries, make sure to add your VyOS router to the allowed client list.
+:::
+
+### RADIUS source address
+
+If you are using OSPF as your IGP, use the interface connected closest to the
+RADIUS server. You can bind all outgoing RADIUS requests to a single source IP
+e.g. the loopback interface.
+
+```{cfgcmd} set vpn sstp authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queires.
+```
+
+:::{note}
+The `source-address` must be configured to that of an interface.
+Best practice would be a loopback or dummy interface.
+:::
+
+### RADIUS advanced options
+
+```{cfgcmd} set vpn sstp authentication radius server \<server\> port \<port\>
+
+Configure RADIUS `<server>` and its required port for authentication requests.
+```
+
+```{cfgcmd} set vpn sstp authentication radius server \<server\> fail-time \<time\>
+
+Mark RADIUS server as offline for this given `<time>` in seconds.
+```
+
+```{cfgcmd} set vpn sstp authentication radius server \<server\> disable
+
+Temporary disable this RADIUS server.
+```
+
+```{cfgcmd} set vpn sstp authentication radius acct-timeout \<timeout\>
+
+Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+```{cfgcmd} set vpn sstp authentication radius dynamic-author server \<address\>
+
+Specifies IP address for Dynamic Authorization Extension server (DM/CoA).
+This IP must exist on any VyOS interface or it can be ``0.0.0.0``.
+```
+
+```{cfgcmd} set vpn sstp authentication radius dynamic-author port \<port\>
+
+UDP port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{cfgcmd} set vpn sstp authentication radius dynamic-author key \<secret\>
+
+Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{cfgcmd} set vpn sstp authentication radius max-try \<number\>
+
+Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+```{cfgcmd} set vpn sstp authentication radius timeout \<timeout\>
+
+Timeout to wait response from server (seconds)
+```
+
+```{cfgcmd} set vpn sstp authentication radius nas-identifier \<identifier\>
+
+Value to send to RADIUS server in NAS-Identifier attribute and to be matched
+in DM/CoA requests.
+```
+
+```{cfgcmd} set vpn sstp authentication radius nas-ip-address \<address\>
+
+Value to send to RADIUS server in NAS-IP-Address attribute and to be matched
+in DM/CoA requests. Also DM/CoA server will bind to that address.
+```
+
+```{cfgcmd} set vpn sstp authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queires.
+```
+
+```{cfgcmd} set vpn sstp authentication radius rate-limit attribute \<attribute\>
+
+Specifies which RADIUS server attribute contains the rate limit information.
+The default attribute is `Filter-Id`.
+```
+
+:::{note}
+If you set a custom RADIUS attribute you must define it on both
+dictionaries on the RADIUS server and client.
+:::
+
+```{cfgcmd} set vpn sstp authentication radius rate-limit enable
+
+Enables bandwidth shaping via RADIUS.
+```
+
+```{cfgcmd} set vpn sstp authentication radius rate-limit vendor
+
+Specifies the vendor dictionary, This dictionary needs to be present in
+/usr/share/accel-ppp/radius.
+```
+
+Received RADIUS attributes have a higher priority than parameters defined within
+the CLI configuration, refer to the explanation below.
+
+### Allocation clients ip addresses by RADIUS
+
+If the RADIUS server sends the attribute `Framed-IP-Address` then this IP
+address will be allocated to the client and the option `default-pool` within
+the CLI config will being ignored.
+
+If the RADIUS server sends the attribute `Framed-Pool`, then the IP address
+will be allocated from a predefined IP pool whose name equals the attribute
+value.
+
+If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, the
+IPv6 address will be allocated from a predefined IPv6 pool `prefix` whose
+name equals the attribute value.
+
+If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, an
+IPv6 delegation prefix will be allocated from a predefined IPv6 pool `delegate`
+whose name equals the attribute value.
+
+:::{note}
+`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in
+RFC6911. If they are not defined in your RADIUS server, add new [dictionary].
+:::
+
+The client's interface can be put into a VRF context via a RADIUS Access-Accept
+packet, or changed via RADIUS CoA. `Accel-VRF-Name` is used for these
+purposes. This is a custom [ACCEL-PPP attribute]. Define it in your RADIUS
+server.
+
+### Renaming clients interfaces by RADIUS
+
+If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be
+renamed.
+
+:::{note}
+The value of the attribute `NAS-Port-Id` must be less than 16
+characters, otherwise the interface won't be renamed.
+:::
+
+## IPv6
+
+```{cfgcmd} set vpn sstp ppp-options ipv6 \<require | prefer | allow | deny\>
+
+Specifies IPv6 negotiation preference.
+* **require** - Require IPv6 negotiation
+* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects
+* **allow** - Negotiate IPv6 only if client requests
+* **deny** - Do not negotiate IPv6 (default value)
+```
+
+```{cfgcmd} set vpn sstp client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\>
+
+Use this comand to set the IPv6 address pool from which an SSTP client will
+get an IPv6 prefix of your defined length (mask) to terminate the SSTP
+endpoint at their side. The mask length can be set between 48 and 128 bits
+long, the default value is 64.
+```
+
+```{cfgcmd} set vpn sstp client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\>
+
+Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on SSTP. You
+will have to set your IPv6 pool and the length of the delegation prefix. From
+the defined IPv6 pool you will be handing out networks of the defined length
+(delegation-prefix). The length of the delegation prefix can be set between
+32 and 64 bits long.
+```
+
+```{cfgcmd} set vpn sstp default-ipv6-pool \<IPv6-POOL-NAME\>
+
+Use this command to define default IPv6 address pool name.
+```
+
+```none
+set vpn sstp ppp-options ipv6 allow
+set vpn sstp client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56'
+set vpn sstp client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64'
+set vpn sstp default-ipv6-pool IPv6-POOL
+```
+
+
+### IPv6 Advanced Options
+
+```{cfgcmd} set vpn sstp ppp-options ipv6-accept-peer-interface-id
+
+Accept peer interface identifier. By default this is not defined.
+```
+
+```{cfgcmd} set vpn sstp ppp-options ipv6-interface-id \<random | x:x:x:x\>
+
+Specifies if a fixed or random interface identifier is used for IPv6. The
+default is fixed.
+* **random** - Random interface identifier for IPv6
+* **x:x:x:x** - Specify interface identifier for IPv6
+```
+
+```{cfgcmd} set vpn sstp ppp-options ipv6-interface-id \<random | x:x:x:x\>
+
+Specifies the peer interface identifier for IPv6. The default is fixed.
+* **random** - Random interface identifier for IPv6
+* **x:x:x:x** - Specify interface identifier for IPv6
+* **ipv4-addr** - Calculate interface identifier from IPv4 address.
+* **calling-sid** - Calculate interface identifier from calling-station-id.
+```
+
+
+## Scripting
+
+```{cfgcmd} set vpn sstp extended-scripts on-change \<path_to_script\>
+
+Script to run when the session interface is changed by RADIUS CoA handling
+```
+
+```{cfgcmd} set vpn sstp extended-scripts on-down \<path_to_script\>
+
+Script to run when the session interface about to terminate
+```
+
+```{cfgcmd} set vpn sstp extended-scripts on-pre-up \<path_to_script\>
+
+Script to run before the session interface comes up
+```
+
+```{cfgcmd} set vpn sstp extended-scripts on-up \<path_to_script\>
+
+Script to run when the session interface is completely configured and started
+```
+
+
+## Advanced Options
+
+### Authentication Advanced Options
+
+```{cfgcmd} set vpn sstp authentication local-users username \<user\> disable
+
+Disable `<user>` account.
+```
+
+```{cfgcmd} set vpn sstp authentication local-users username \<user\> static-ip \<address\>
+
+Assign a static IP address to `<user>` account.
+```
+
+```{cfgcmd} set vpn sstp authentication local-users username \<user\> rate-limit download \<bandwidth\>
+
+Rate limit the download bandwidth for `<user>` to `<bandwidth>` kbit/s.
+```
+
+```{cfgcmd} set vpn sstp authentication local-users username \<user\> rate-limit upload \<bandwidth\>
+
+Rate limit the upload bandwidth for `<user>` to `<bandwidth>` kbit/s.
+```
+
+```{cfgcmd} set vpn sstp authentication protocols \<pap | chap | mschap | mschap-v2\>
+
+Require the peer to authenticate itself using one of the following protocols:
+pap, chap, mschap, mschap-v2.
+```
+
+
+### Client IP Pool Advanced Options
+
+```{cfgcmd} set vpn sstp client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\>
+
+Use this command to define the next address pool name.
+```
+
+
+### PPP Advanced Options
+
+```{cfgcmd} set vpn sstp ppp-options disable-ccp
+
+Disable Compression Control Protocol (CCP).
+CCP is enabled by default.
+```
+
+```{cfgcmd} set vpn sstp ppp-options interface-cache \<number\>
+
+Specifies number of interfaces to cache. This prevents interfaces from being
+removed once the corresponding session is destroyed. Instead, interfaces are
+cached for later use in new sessions. This should reduce the kernel-level
+interface creation/deletion rate.
+Default value is **0**.
+```
+
+```{cfgcmd} set vpn sstp ppp-options ipv4 \<require | prefer | allow | deny\>
+
+Specifies IPv4 negotiation preference.
+* **require** - Require IPv4 negotiation
+* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects
+* **allow** - Negotiate IPv4 only if client requests (Default value)
+* **deny** - Do not negotiate IPv4
+```
+
+```{cfgcmd} set vpn sstp ppp-options lcp-echo-failure \<number\>
+
+Defines the maximum `<number>` of unanswered echo requests. Upon reaching the
+value `<number>`, the session will be reset. Default value is **3**.
+```
+
+```{cfgcmd} set vpn sstp ppp-options lcp-echo-interval \<interval\>
+
+If this option is specified and is greater than 0, then the PPP module will
+send LCP echo requests every `<interval>` seconds.
+Default value is **30**.
+```
+
+```{cfgcmd} set vpn sstp ppp-options lcp-echo-timeout
+
+Specifies timeout in seconds to wait for any peer activity. If this option is
+specified it turns on adaptive lcp echo functionality and "lcp-echo-failure"
+is not used. Default value is **0**.
+```
+
+```{cfgcmd} set vpn sstp ppp-options min-mtu \<number\>
+
+Defines the minimum acceptable MTU. If a client tries to negotiate an MTU
+lower than this it will be NAKed, and disconnected if it rejects a greater
+MTU.
+Default value is **100**.
+```
+
+```{cfgcmd} set vpn sstp ppp-options mppe \<require | prefer | deny\>
+
+Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation
+preference.
+* **require** - ask client for mppe, if it rejects drop connection
+* **prefer** - ask client for mppe, if it rejects don't fail. (Default value)
+* **deny** - deny mppe
+
+Default behavior - don't ask the client for mppe, but allow it if the client
+wants. Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy
+attribute.
+```
+
+```{cfgcmd} set vpn sstp ppp-options mru \<number\>
+
+Defines preferred MRU. By default is not defined.
+```
+
+
+### Global Advanced options
+
+```{cfgcmd} set vpn sstp description \<description\>
+
+Set description.
+```
+
+```{cfgcmd} set vpn sstp limits burst \<value\>
+
+Burst count
+```
+
+```{cfgcmd} set vpn sstp limits connection-limit \<value\>
+
+Maximum accepted connection rate (e.g. 1/min, 60/sec)
+```
+
+```{cfgcmd} set vpn sstp limits timeout \<value\>
+
+Timeout in seconds
+```
+
+```{cfgcmd} set vpn sstp mtu
+
+Maximum Transmission Unit (MTU) (default: **1500**)
+```
+
+```{cfgcmd} set vpn sstp max-concurrent-sessions
+
+Maximum number of concurrent session start attempts
+```
+
+```{cfgcmd} set vpn sstp name-server \<address\>
+
+Connected clients should use `<address>` as their DNS server. This command
+accepts both IPv4 and IPv6 addresses. Up to two nameservers can be configured
+for IPv4, up to three for IPv6.
+```
+
+```{cfgcmd} set vpn sstp shaper fwmark \<1-2147483647\>
+
+Match firewall mark value
+```
+
+```{cfgcmd} set vpn sstp snmp master-agent
+
+Enable SNMP
+```
+
+```{cfgcmd} set vpn sstp wins-server \<address\>
+
+Windows Internet Name Service (WINS) servers propagated to client
+```
+
+```{cfgcmd} set vpn sstp host-name \<hostname\>
+
+If this option is given, only SSTP connections to the specified host
+and with the same TLS SNI will be allowed.
+```
+
+
+## Configuring SSTP client
+
+Once you have setup your SSTP server there comes the time to do some basic
+testing. The Linux client used for testing is called [sstpc]. [sstpc] requires a
+PPP configuration/peer file.
+
+If you use a self-signed certificate, do not forget to install CA on the client side.
+
+The following PPP configuration tests MSCHAP-v2:
+
+```none
+$ cat /etc/ppp/peers/vyos
+usepeerdns
+#require-mppe
+#require-pap
+require-mschap-v2
+noauth
+lock
+refuse-pap
+refuse-eap
+refuse-chap
+refuse-mschap
+#refuse-mschap-v2
+nobsdcomp
+nodeflate
+debug
+```
+
+You can now "dial" the peer with the follwoing command: `sstpc --log-level 4
+--log-stderr --user vyos --password vyos vpn.example.com -- call vyos`.
+
+A connection attempt will be shown as:
+
+```none
+$ sstpc --log-level 4 --log-stderr --user vyos --password vyos vpn.example.com -- call vyos
+
+Mar 22 13:29:12 sstpc[12344]: Resolved vpn.example.com to 192.0.2.1
+Mar 22 13:29:12 sstpc[12344]: Connected to vpn.example.com
+Mar 22 13:29:12 sstpc[12344]: Sending Connect-Request Message
+Mar 22 13:29:12 sstpc[12344]: SEND SSTP CRTL PKT(14)
+Mar 22 13:29:12 sstpc[12344]:   TYPE(1): CONNECT REQUEST, ATTR(1):
+Mar 22 13:29:12 sstpc[12344]:     ENCAP PROTO(1): 6
+Mar 22 13:29:12 sstpc[12344]: RECV SSTP CRTL PKT(48)
+Mar 22 13:29:12 sstpc[12344]:   TYPE(2): CONNECT ACK, ATTR(1):
+Mar 22 13:29:12 sstpc[12344]:     CRYPTO BIND REQ(4): 40
+Mar 22 13:29:12 sstpc[12344]: Started PPP Link Negotiation
+Mar 22 13:29:15 sstpc[12344]: Sending Connected Message
+Mar 22 13:29:15 sstpc[12344]: SEND SSTP CRTL PKT(112)
+Mar 22 13:29:15 sstpc[12344]:   TYPE(4): CONNECTED, ATTR(1):
+Mar 22 13:29:15 sstpc[12344]:     CRYPTO BIND(3): 104
+Mar 22 13:29:15 sstpc[12344]: Connection Established
+
+$ ip addr show ppp0
+164: ppp0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1452 qdisc fq_codel state UNKNOWN group default qlen 3
+     link/ppp  promiscuity 0
+     inet 100.64.2.2 peer 100.64.1.1/32 scope global ppp0
+        valid_lft forever preferred_lft forever
+```
+
+
+## Monitoring
+
+```{opcmd} show sstp-server sessions
+
+Use this command to locally check the active sessions in the SSTP
+server.
+```
+
+```none
+vyos@vyos:~$ show sstp-server sessions
+ ifname | username |    ip    | ip6 | ip6-dp |   calling-sid  | rate-limit | state  |  uptime  | rx-bytes | tx-bytes
+--------+----------+----------+-----+--------+----------------+------------+--------+----------+----------+----------
+ sstp0  | test     | 10.0.0.2 |     |        | 192.168.10.100 |            | active | 00:15:46 | 16.3 KiB | 210 B
+```
+
+```none
+vyos@vyos:~$ show sstp-server statistics
+ uptime: 0.01:21:54
+cpu: 0%
+mem(rss/virt): 6688/100464 kB
+core:
+  mempool_allocated: 149420
+  mempool_available: 146092
+  thread_count: 1
+  thread_active: 1
+  context_count: 6
+  context_sleeping: 0
+  context_pending: 0
+  md_handler_count: 7
+  md_handler_pending: 0
+  timer_count: 2
+  timer_pending: 0
+sessions:
+  starting: 0
+  active: 1
+  finishing: 0
+sstp:
+  starting: 0
+  active: 1
+```
+
+
+## Troubleshooting
+
+```none
+vyos@vyos:~$sudo journalctl -u accel-ppp@sstp -b 0
+
+Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: new connection from 192.168.10.100:49852
+Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: starting
+Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: started
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <SSTP_DUPLEX_POST /sra_{BA195980-CD49-458b-9E23-C84EE0ADCD75}/ HTTP/1.1>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <SSTPCORRELATIONID: {48B82435-099A-4158-A987-052E7570CFAA}>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <Content-Length: 18446744073709551615>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <Host: vyos.io>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <HTTP/1.1 200 OK>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <Date: Wed, 28 Feb 2024 17:03:04 GMT>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <Content-Length: 18446744073709551615>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [SSTP SSTP_MSG_CALL_CONNECT_REQUEST]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [SSTP SSTP_MSG_CALL_CONNECT_ACK]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: lcp_layer_init
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: auth_layer_init
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: ccp_layer_init
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: ipcp_layer_init
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: ipv6cp_layer_init
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: ppp establishing
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: lcp_layer_start
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfReq id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=0 <mru 4091> <magic 345f64ca> <pcomp> <accomp> < d 3 6 >]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfRej id=0 <pcomp> <accomp> < d 3 6 >]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=1 <mru 4091> <magic 345f64ca>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfNak id=1 <mru 1452>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=2 <mru 1452> <magic 345f64ca>]
+Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfAck id=2]
+Feb 28 17:03:07 vyos accel-sstp[2492]: :: fsm timeout 9
+Feb 28 17:03:07 vyos accel-sstp[2492]: :: send [LCP ConfReq id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP ConfAck id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: :: lcp_layer_started
+Feb 28 17:03:07 vyos accel-sstp[2492]: :: auth_layer_start
+Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP Ident id=3 <MSRASV5.20>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP Ident id=4 <MSRAS-0-MSEDGEWIN10>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: [50B blob data]
+Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [PAP AuthReq id=3]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: connect: ppp0 <--> sstp(192.168.10.100:49852)
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ppp connected
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [PAP AuthAck id=3 "Authentication succeeded"]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: test: authentication succeeded
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: auth_layer_started
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ccp_layer_start
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipcp_layer_start
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipv6cp_layer_start
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [SSTP SSTP_MSG_CALL_CONNECTED]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: IPV6CP: discarding packet
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [LCP ProtoRej id=88 <8057>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=7 <addr 0.0.0.0> <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfReq id=25 <addr 10.0.0.1>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfRej id=7 <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfAck id=25 <addr 10.0.0.1>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=8 <addr 0.0.0.0>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfNak id=8 <addr 10.0.0.5>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=9 <addr 10.0.0.5>]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfAck id=9]
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipcp_layer_started
+Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: rename interface to 'sstp0'
+Feb 28 17:03:07 vyos accel-sstp[2492]: sstp0:test: sstp: ppp: started
+```
+
+[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
+[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911
+[sstpc]: https://github.com/reliablehosting/sstp-client
diff --git a/docs/configuration/vrf/index.md b/docs/configuration/vrf/index.md
new file mode 100644
index 00000000..d679d1c9
--- /dev/null
+++ b/docs/configuration/vrf/index.md
@@ -0,0 +1,646 @@
+---
+lastproofread: '2021-07-07'
+---
+
+(vrf)=
+
+# VRF
+
+{abbr}`VRF (Virtual Routing and Forwarding)` devices combined with ip rules
+provides the ability to create virtual routing and forwarding domains (aka
+VRFs, VRF-lite to be specific) in the Linux network stack. One use case is the
+multi-tenancy problem where each tenant has their own unique routing tables and
+in the very least need different default gateways.
+
+## Configuration
+
+A VRF device is created with an associated route table. Network interfaces are
+then enslaved to a VRF device.
+
+```{cfgcmd} set vrf name \<name\> table \<id\>
+
+Create a new VRF instance with `<name>` and `<id>`. The name is used when placing
+individual interfaces into the VRF.
+
+:::{note}
+A routing table ID can not be modified once it is assigned. It can
+only be changed by deleting and re-adding the VRF instance.
+:::
+```
+
+```{cfgcmd} set vrf bind-to-all
+
+By default the scope of the port bindings for unbound sockets is limited to
+the default VRF. That is, it will not be matched by packets arriving on
+interfaces enslaved to a VRF and processes may bind to the same port if
+they bind to a VRF.
+
+TCP & UDP services running in the default VRF context (ie., not bound to any
+VRF device) can work across all VRF domains by enabling this option.
+```
+
+### Zebra/Kernel route filtering
+
+
+Zebra supports prefix-lists and Route Maps to match routes received from
+other FRR components. The permit/deny facilities provided by these commands
+can be used to filter which routes zebra will install in the kernel.
+
+```{cfgcmd} set vrf \<name\> ip protocol \<protocol\> route-map \<route-map\>
+
+Apply a route-map filter to routes for the specified protocol.
+
+The following protocols can be used: any, babel, bgp, eigrp,
+isis, ospf, rip, static
+
+:::{note}
+If you choose any as the option that will cause all protocols that
+are sending routes to zebra.
+:::
+```
+
+
+```{cfgcmd} set vrf \<name\> ipv6 protocol \<protocol\> route-map \<route-map\>
+
+Apply a route-map filter to routes for the specified protocol.
+
+The following protocols can be used: any, babel, bgp, isis,
+ospfv3, ripng, static
+
+:::{note}
+If you choose any as the option that will cause all protocols that
+are sending routes to zebra.
+:::
+```
+
+### Nexthop Tracking
+
+
+Nexthop tracking resolve nexthops via the default route by default. This is enabled
+by default for a traditional profile of FRR which we use. It and can be disabled if
+you do not want to e.g. allow BGP to peer across the default route.
+
+```{cfgcmd} set vrf name \<name\> ip nht no-resolve-via-default
+
+Do not allow IPv4 nexthop tracking to resolve via the default route. This
+parameter is configured per-VRF, so the command is also available in the VRF
+subnode.
+```
+
+
+```{cfgcmd} set vrf name \<name\> ipv6 nht no-resolve-via-default
+
+Do not allow IPv6 nexthop tracking to resolve via the default route. This
+parameter is configured per-VRF, so the command is also available in the VRF
+subnode.
+```
+
+### Interfaces
+
+
+When VRFs are used it is not only mandatory to create a VRF but also the VRF
+itself needs to be assigned to an interface.
+
+```{cfgcmd} set interfaces \<dummy | ethernet | bonding | bridge | pppoe\> \<interface\> vrf \<name\>
+
+Assign interface identified by `<interface>` to VRF named `<name>`.
+```
+
+### Routing
+
+
+:::{note}
+VyOS 1.4 (sagitta) introduced dynamic routing support for VRFs.
+:::
+
+
+Currently dynamic routing is supported for the following protocols:
+
+
+- {ref}`routing-bgp`
+- {ref}`routing-isis`
+- {ref}`routing-ospf`
+- {ref}`routing-ospfv3`
+- {ref}`routing-static`
+
+
+The CLI configuration is same as mentioned in above articles. The only
+difference is, that each routing protocol used, must be prefixed with the `vrf
+name <name>` command.
+
+
+#### Example
+
+
+The following commands would be required to set options for a given dynamic
+routing protocol inside a given vrf:
+
+
+- {ref}`routing-bgp`: `set vrf name <name> protocols bgp ...`
+- {ref}`routing-isis`: `set vrf name <name> protocols isis ...`
+- {ref}`routing-ospf`: `set vrf name <name> protocols ospf ...`
+- {ref}`routing-ospfv3`: `set vrf name <name> protocols ospfv3 ...`
+- {ref}`routing-static`: `set vrf name <name> protocols static ...`
+
+
+### Services
+
+
+Currently the following services can be created isolated in VRFs
+
+
+- {ref}`dhcp-server`
+
+
+The CLI configuration is same as mentioned in above articles. The only
+difference is, that each service used, must be prefixed with the `vrf
+name <name>` command.
+
+
+#### Example
+
+
+The following commands would be required to set options for a given service
+inside a given vrf:
+
+
+- {ref}`dhcp-server`: `set vrf name <name> service dhcp-server ...`
+- {ref}`dhcp-server`: `set vrf name <name> service dhcpv6-server ...`
+
+
+## Operation
+
+
+It is not sufficient to only configure a VRF but VRFs must be maintained, too.
+For VRF maintenance the following operational commands are in place.
+
+```{opcmd} show vrf
+
+Lists VRFs that have been created
+
+:::{code-block} none
+vyos@vyos:~$ show vrf
+VRF name          state     mac address        flags                     interfaces
+--------          -----     -----------        -----                     ----------
+blue              up        00:53:12:d8:74:24  noarp,master,up,lower_up  dum200,eth0.302
+red               up        00:53:de:02:df:aa  noarp,master,up,lower_up  dum100,eth0.300,bond0.100,peth0
+:::
+:::{note}
+Command should probably be extended to list also the real
+interfaces assigned to this one VRF to get a better overview.
+:::
+```
+
+
+```{opcmd} show vrf \<name\>
+
+:::{code-block} none
+vyos@vyos:~$ show vrf name blue
+VRF name          state     mac address        flags                     interfaces
+--------          -----     -----------        -----                     ----------
+blue              up        00:53:12:d8:74:24  noarp,master,up,lower_up  dum200,eth0.302
+:::
+```
+
+
+```{opcmd} show ip route vrf \<name\>
+
+Display IPv4 routing table for VRF identified by `<name>`.
+
+:::{code-block} none
+vyos@vyos:~$ show ip route vrf blue
+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, D - SHARP,
+       F - PBR, f - OpenFabric,
+       > - selected route, * - FIB route, q - queued route, r - rejected route
+
+VRF blue:
+K   0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:00:50
+S>* 172.16.0.0/16 [1/0] via 192.0.2.1, dum1, 00:00:02
+C>* 192.0.2.0/24 is directly connected, dum1, 00:00:06
+:::
+```
+```{opcmd} show ipv6 route vrf \<name\>
+
+Display IPv6 routing table for VRF identified by `<name>`.
+
+:::{code-block} none
+vyos@vyos:~$ show ipv6 route vrf red
+Codes: K - kernel route, C - connected, S - static, R - RIPng,
+       O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table,
+       v - VNC, V - VNC-Direct, A - Babel, D - SHARP, F - PBR,
+       f - OpenFabric,
+       > - selected route, * - FIB route, q - queued route, r - rejected route
+
+VRF red:
+K   ::/0 [255/8192] unreachable (ICMP unreachable), 00:43:20
+C>* 2001:db8::/64 is directly connected, dum1, 00:02:19
+C>* fe80::/64 is directly connected, dum1, 00:43:19
+K>* ff00::/8 [0/256] is directly connected, dum1, 00:43:19
+:::
+```
+```{opcmd} ping \<host\> vrf \<name\>
+
+   The ping command is used to test whether a network host is reachable or not.
+
+   Ping uses ICMP protocol's mandatory ECHO_REQUEST datagram to elicit an
+   ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST datagrams (pings)
+   will have an IP and ICMP header, followed by "struct timeval" and an
+   arbitrary number of pad bytes used to fill out the packet.
+
+   When doing fault isolation with ping, you should first run it on the local
+   host, to verify that the local network interface is up and running. Then,
+   continue with hosts and gateways further down the road towards your
+   destination. Round-trip time and packet loss statistics are computed.
+
+   Duplicate packets are not included in the packet loss calculation, although
+   the round-trip time of these packets is used in calculating the minimum/
+   average/maximum round-trip time numbers.
+
+   :::{note}
+   Ping command can be interrupted at any given time using ``<Ctrl>+c``.
+   A brief statistic is shown afterwards.
+   :::
+
+   :::{code-block} none
+   vyos@vyos:~$ ping 192.0.2.1 vrf red
+   PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data.
+   64 bytes from 192.0.2.1: icmp_seq=1 ttl=64 time=0.070 ms
+   64 bytes from 192.0.2.1: icmp_seq=2 ttl=64 time=0.078 ms
+   ^C
+   --- 192.0.2.1 ping statistics ---
+   2 packets transmitted, 2 received, 0% packet loss, time 4ms
+   rtt min/avg/max/mdev = 0.070/0.074/0.078/0.004 ms
+   :::
+```
+
+
+```{opcmd} traceroute vrf \<name\> [ipv4 | ipv6] \<host\>
+
+Displays the route packets taken to a network host utilizing VRF instance
+identified by `<name>`. When using the IPv4 or IPv6 option, displays the
+route packets taken to the given hosts IP address family. This option is
+useful when the host is specified as a hostname rather than an IP address.
+```
+
+
+```{opcmd} force vrf \<name\>
+
+Join a given VRF. This will open a new subshell within the specified VRF.
+
+The prompt is adjusted to reflect this change in both config and op-mode.
+
+:::{code-block} none
+vyos@vyos:~$ force vrf blue
+vyos@vyos(vrf:blue):~$
+:::
+```
+
+(vrf-example)=
+
+
+## Example
+
+
+### VRF route leaking
+
+
+The following example topology was built using EVE-NG.
+
+
+```{eval-rst}
+.. figure:: /_static/images/vrf-example-topology-01.webp
+   :alt: VRF topology example
+
+
+   VRF route leaking
+```
+
+
+- PC1 is in the `default` VRF and acting as e.g. a "fileserver"
+- PC2 is in VRF `blue` which is the development department
+- PC3 and PC4 are connected to a bridge device on router `R1` which is in VRF
+  `red`. Say this is the HR department.
+- R1 is managed through an out-of-band network that resides in VRF `mgmt`
+
+
+(vrf-example-configuration)=
+
+
+#### Configuration
+
+
+```none
+set interfaces bridge br10 address '10.30.0.254/24'
+set interfaces bridge br10 member interface eth3
+set interfaces bridge br10 member interface eth4
+set interfaces bridge br10 vrf 'red'
+
+set interfaces ethernet eth0 address 'dhcp'
+set interfaces ethernet eth0 vrf 'mgmt'
+set interfaces ethernet eth1 address '10.0.0.254/24'
+set interfaces ethernet eth2 address '10.20.0.254/24'
+set interfaces ethernet eth2 vrf 'blue'
+
+set protocols static route 10.20.0.0/24 interface eth2 vrf 'blue'
+set protocols static route 10.30.0.0/24 interface br10 vrf 'red'
+
+set service ssh disable-host-validation
+set service ssh vrf 'mgmt'
+
+set system name-server 'eth0'
+
+set vrf name blue protocols static route 10.0.0.0/24 interface eth1 vrf 'default'
+set vrf name blue table '3000'
+set vrf name mgmt table '1000'
+set vrf name red protocols static route 10.0.0.0/24 interface eth1 vrf 'default'
+set vrf name red table '2000'
+```
+
+### VRF and NAT
+
+
+(vrf-nat-configuration)=
+
+
+#### Configuration
+
+
+```none
+set interfaces ethernet eth0 address '172.16.50.12/24'
+set interfaces ethernet eth0 vrf 'red'
+
+set interfaces ethernet eth1 address '192.168.130.100/24'
+set interfaces ethernet eth1 vrf 'blue'
+
+set nat destination rule 110 description 'NAT ssh- INSIDE'
+set nat destination rule 110 destination port '2022'
+set nat destination rule 110 inbound-interface name 'eth0'
+set nat destination rule 110 protocol 'tcp'
+set nat destination rule 110 translation address '192.168.130.40'
+
+set nat source rule 100 outbound-interface name 'eth0'
+set nat source rule 100 protocol 'all'
+set nat source rule 100 source address '192.168.130.0/24'
+set nat source rule 100 translation address 'masquerade'
+
+set service ssh vrf 'red'
+
+set vrf bind-to-all
+set vrf name blue protocols static route 0.0.0.0/0 next-hop 172.16.50.1 vrf 'red'
+set vrf name blue protocols static route 172.16.50.0/24 interface eth0 vrf 'red'
+set vrf name blue table '1010'
+
+set vrf name red protocols static route 0.0.0.0/0 next-hop 172.16.50.1
+set vrf name red protocols static route 192.168.130.0/24 interface eth1 vrf 'blue'
+set vrf name red table '2020'
+```
+
+(vrf-example-operation)=
+
+
+#### Operation
+
+
+After committing the configuration we can verify all leaked routes are
+installed, and try to ICMP ping PC1 from PC3.
+
+
+```none
+PCS> ping 10.0.0.1
+
+84 bytes from 10.0.0.1 icmp_seq=1 ttl=63 time=1.943 ms
+84 bytes from 10.0.0.1 icmp_seq=2 ttl=63 time=1.618 ms
+84 bytes from 10.0.0.1 icmp_seq=3 ttl=63 time=1.745 ms
+```
+
+```none
+VPCS> show ip
+NAME        : VPCS[1]
+IP/MASK     : 10.30.0.1/24
+GATEWAY     : 10.30.0.254
+DNS         :
+MAC         : 00:50:79:66:68:0f
+```
+
+###### VRF default routing table
+
+
+```none
+vyos@R1:~$ show ip route
+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, D - SHARP,
+       F - PBR, f - OpenFabric,
+       > - selected route, * - FIB route, q - queued, r - rejected, b - backup
+
+C>* 10.0.0.0/24 is directly connected, eth1, 00:07:44
+S>* 10.20.0.0/24 [1/0] is directly connected, eth2 (vrf blue), weight 1, 00:07:38
+S>* 10.30.0.0/24 [1/0] is directly connected, br10 (vrf red), weight 1, 00:07:38
+```
+
+###### VRF red routing table
+
+
+```none
+vyos@R1:~$ show ip route vrf red
+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, D - SHARP,
+       F - PBR, f - OpenFabric,
+       > - selected route, * - FIB route, q - queued, r - rejected, b - backup
+
+VRF red:
+K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:07:57
+S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:40
+C>* 10.30.0.0/24 is directly connected, br10, 00:07:54
+```
+
+###### VRF blue routing table
+
+
+```none
+vyos@R1:~$ show ip route vrf blue
+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, D - SHARP,
+       F - PBR, f - OpenFabric,
+       > - selected route, * - FIB route, q - queued, r - rejected, b - backup
+
+VRF blue:
+K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:08:00
+S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:44
+C>* 10.20.0.0/24 is directly connected, eth2, 00:07:53
+```
+
+# L3VPN VRFs
+
+
+{abbr}`L3VPN VRFs ( Layer 3 Virtual Private Networks )` bgpd supports for
+IPv4 RFC 4364 and IPv6 RFC 4659. L3VPN routes, and their associated VRF
+MPLS labels, can be distributed to VPN SAFI neighbors in the default, i.e.,
+non VRF, BGP instance. VRF MPLS labels are reached using core MPLS labels
+which are distributed using LDP or BGP labeled unicast.
+bgpd also supports inter-VRF route leaking.
+
+
+(l3vpn-vrf-route-leaking)=
+
+
+## VRF Route Leaking
+
+
+BGP routes may be leaked (i.e. copied) between a unicast VRF RIB and the VPN
+SAFI RIB of the default VRF for use in MPLS-based L3VPNs. Unicast routes may
+also be leaked between any VRFs (including the unicast RIB of the default BGP
+instance). A shortcut syntax is also available for specifying leaking from
+one VRF to another VRF using the default instance’s VPN RIB as the intemediary
+. A common application of the VRF-VRF feature is to connect a customer’s
+private routing domain to a provider’s VPN service. Leaking is configured from
+the point of view of an individual VRF: import refers to routes leaked from VPN
+to a unicast VRF, whereas export refers to routes leaked from a unicast VRF to
+VPN.
+
+
+:::{note}
+Routes exported from a unicast VRF to the VPN RIB must be augmented
+by two parameters:
+
+
+> an RD / RTLIST
+
+
+Configuration for these exported routes must, at a minimum, specify
+these two parameters.
+:::
+
+
+(l3vpn-vrf-example-configuration)=
+
+
+## Configuration
+
+
+Configuration of route leaking between a unicast VRF RIB and the VPN SAFI RIB
+of the default VRF is accomplished via commands in the context of a VRF
+address-family.
+
+```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> rd vpn export \<asn:nn|address:nn\>
+
+Specifies the route distinguisher to be added to a route exported from the
+current unicast VRF to VPN.
+```
+
+
+```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> route-target vpn \<import|export|both\> [RTLIST]
+
+Specifies the route-target list to be attached to a route (export) or the
+route-target list to match against (import) when exporting/importing
+between the current unicast VRF and VPN.The RTLIST is a space-separated
+list of route-targets, which are BGP extended community values as
+described in Extended Communities Attribute.
+```
+
+
+```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> label vpn export \<0-1048575|auto\>
+
+Enables an MPLS label to be attached to a route exported from the current
+unicast VRF to VPN. If the value specified is auto, the label value is
+automatically assigned from a pool maintained.
+```
+
+
+```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> label vpn allocation-mode per-nexthop
+
+Select how labels are allocated in the given VRF. By default, the per-vrf
+mode is selected, and one label is used for all prefixes from the VRF. The
+per-nexthop will use a unique label for all prefixes that are reachable via
+the same nexthop.
+```
+
+
+```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> route-map vpn \<import|export\> [route-map \<name\>]
+
+Specifies an optional route-map to be applied to routes imported or
+exported between the current unicast VRF and VPN.
+```
+
+
+```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> \<import|export\> vpn
+
+Enables import or export of routes between the current unicast VRF and VPN.
+```
+
+
+```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> import vrf \<name\>
+
+Shortcut syntax for specifying automatic leaking from vrf VRFNAME to the
+current VRF using the VPN RIB as intermediary. The RD and RT are auto
+derived and should not be specified explicitly for either the source or
+destination VRF’s.
+```
+
+
+```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> route-map vrf import [route-map \<name\>]
+
+Specifies an optional route-map to be applied to routes imported from VRFs.
+```
+
+
+```{cfgcmd} set vrf name \<name\> protocols bgp interface \<interface\> mpls forwarding
+
+It is possible to permit BGP install VPN prefixes without transport labels.
+This configuration will install VPN prefixes originated from an e-bgp session,
+and with the next-hop directly connected.
+```
+
+(l3vpn-vrf-example-operation)=
+
+
+## Operation
+
+
+It is not sufficient to only configure a L3VPN VRFs but L3VPN VRFs must be
+maintained, too.For L3VPN VRF maintenance the following operational commands
+are in place.
+
+```{opcmd} show bgp \<ipv4|ipv6\> vpn
+
+ Print active IPV4 or IPV6 routes advertised via the VPN SAFI.
+
+:::{code-block} none
+BGP table version is 2, local router ID is 10.0.1.1, vrf id 0
+Default local pref 100, local AS 65001
+Status codes:  s suppressed, d damped, h history, * valid, > best, = multipath,
+i internal, r RIB-failure, S Stale, R Removed
+Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self
+Origin codes:  i - IGP, e - EGP, ? - incomplete
+
+Network          Next Hop            Metric LocPrf Weight Path
+Route Distinguisher: 10.50.50.1:1011
+*>i10.50.50.0/24    10.0.0.7                  0    100      0 i
+UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0
+Route Distinguisher: 10.60.60.1:1011
+*>i10.60.60.0/24    10.0.0.10              0    100      0 i
+UN=10.0.0.10  EC{65035:1011} label=80 type=bgp, subtype=0
+:::
+```
+
+
+```{opcmd} show bgp \<ipv4|ipv6\> vpn summary
+
+Print a summary of neighbor connections for the specified AFI/SAFI
+combination.
+
+:::{code-block} none
+BGP router identifier 10.0.1.1, local AS number 65001 vrf-id 0
+BGP table version 0
+RIB entries 9, using 1728 bytes of memory
+Peers 4, using 85 KiB of memory
+Peer groups 1, using 64 bytes of memory
+
+Neighbor        V         AS   MsgRcvd   MsgSent   TblVer  InQ OutQ  Up/Down State/PfxRcd   PfxSnt
+10.0.0.7        4      65001      2860      2870        0    0    0 1d23h34m            2       10
+:::
+```