Merge remote-tracking branch 'origin/sagitta' into fix/docs-html-title-sagitta

# Conflicts:
#	docs/conf.py

246 files changed, 38021 insertions, 0 deletions

diff --git a/docs/configuration/container/index.md b/docs/configuration/container/index.md
new file mode 100644
index 00000000..c5163a99
--- /dev/null
+++ b/docs/configuration/container/index.md
@@ -0,0 +1,406 @@
+---
+lastproofread: '2022-06-10'
+---
+
+# Container
+
+The VyOS container implementation is based on `Podman<https://podman.io/>` as
+a deamonless container engine.
+
+## Configuration
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> entrypoint <entrypoint>
+
+   Override the default entrypoint from the image for a container.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> command <command>
+
+    Override the default command from the image for a container.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> arguments <arguments>
+
+    Set the command arguments for a container.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> host-name <hostname>
+
+    Set the host name for a container.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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**
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> network <networkname>
+
+    Attaches user-defined network to a container.
+    Only one network must be specified and must already exist.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> description <text>
+
+    Set a container description
+```
+
+```{eval-rst}
+.. 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'
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> port <portname> source <portnumber>
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> port <portname> destination <portnumber>
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> volume <volumename> source <path>
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> volume <volumename> mode <ro | rw>
+
+    Volume is either mounted as rw (read-write - default) or ro (read-only)
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> uid <number>
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> gid <number>
+
+    Set the User ID or Group ID of the container
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> memory <MB>
+
+   Constrain the memory available to the container.
+
+   Default is 512 MB. Use 0 MB for unlimited memory.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> device <devicename> source <path>
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> device <devicename> destination <path>
+
+   Add a host device to the container.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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)
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> label <label> value <value>
+
+   Add metadata label for this container.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container name <name> disable
+
+   Disable a container.
+```
+
+### Container Networks
+
+```{eval-rst}
+.. cfgcmd:: set container network <name>
+
+    Creates a named container network
+```
+
+```{eval-rst}
+.. cfgcmd:: set container network <name> description
+
+    A brief description what this network is all about.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container network <name> vrf <nme>
+
+    Bind container network to a given VRF instance.
+```
+
+### Container Registry
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set container registry <name> disable
+
+    Disable a given container registry
+```
+
+```{eval-rst}
+.. cfgcmd:: set container registry <name> authentication username
+```
+
+```{eval-rst}
+.. 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.
+
+```
+
+## Operation Commands
+
+```{eval-rst}
+.. opcmd:: add container image <containername>
+
+    Pull a new image for container
+```
+
+```{eval-rst}
+.. opcmd:: show container
+
+    Show the list of all active containers.
+```
+
+```{eval-rst}
+.. opcmd:: show container image
+
+    Show the local container images.
+```
+
+```{eval-rst}
+.. opcmd:: show container log <containername>
+
+    Show logs from a given container
+```
+
+```{eval-rst}
+.. opcmd:: show container network
+
+    Show a list available container networks
+```
+
+```{eval-rst}
+.. opcmd:: restart container <containername>
+
+    Restart a given container
+```
+
+```{eval-rst}
+.. opcmd:: update container image <containername>
+
+    Update container image
+```
+
+```{eval-rst}
+.. 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/container/index.rst b/docs/configuration/container/rst-index.rst
index 69e599a4..69e599a4 100644
--- a/docs/configuration/container/index.rst
+++ b/docs/configuration/container/rst-index.rst
diff --git a/docs/configuration/firewall/bridge.md b/docs/configuration/firewall/bridge.md
new file mode 100644
index 00000000..ebb9287d
--- /dev/null
+++ b/docs/configuration/firewall/bridge.md
@@ -0,0 +1,543 @@
+---
+lastproofread: '2023-11-08'
+---
+
+(firewall-configuration)=
+
+# Bridge Firewall Configuration
+
+:::{note}
+**Documentation under development**
+:::
+
+## Overview
+
+In this section there's useful information of all firewall configuration that
+can be done regarding bridge, and appropiate op-mode commands.
+Configuration commands covered in this section:
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge ...
+```
+
+From 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
+         - name
+            + custom_name
+```
+
+Traffic which is received by the router on an interface which is member of a
+bridge is processed on the **Bridge Layer**. A simplified packet flow diagram
+for this layer is shown next:
+
+:::{figure} /_static/images/firewall-bridge-packet-flow.png
+:::
+
+For traffic that needs to be forwared internally by the bridge, base chain is
+is **forward**, and it's base command for filtering is `set firewall bridge
+forward filter ...`, which happens in stage 4, highlightened with red color.
+
+Custom bridge firewall chains can be create with command `set firewall bridge
+name <name> ...`. In order to use such custom chain, a rule with action jump,
+and the appropiate target should be defined in a base chain.
+
+:::{note}
+**Layer 3 bridge**:
+When an IP address is assigned to the bridge interface, and if traffic
+is sent to the router to this IP (for example using such IP as
+default gateway), then rules defined for **bridge firewall** won't
+match, and firewall analysis continues at **IP layer**.
+:::
+
+## Bridge Rules
+
+For firewall filtering, firewall rules needs to be created. Each rule is
+numbered, has an action to apply if the rule is matched, and the ability
+to specify multiple criteria matchers. 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, then an action must be defined for it. This tells the
+firewall what to do if all criteria matchers defined for such rule do match.
+
+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.
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999> action
+   [accept | continue | drop | jump | queue | return]
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   jump-target <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   jump-target <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   queue <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   queue <0-65535>
+
+   To be used only when action is set to ``queue``. Use this command to specify
+   queue target to use. Queue range is also supported.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   queue-options bypass
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   queue-options bypass
+
+   To be used only when action is set to ``queue``. Use this command to let
+   packet go through firewall when no userspace software is connected to the
+   queue.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   queue-options fanout
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   queue-options fanout
+
+   To be used only when action is set to ``queue``. Use this command to
+   distribute packets between several queues.
+```
+
+Also, **default-action** is an action that takes place whenever a packet does
+not match any rule in it's chain. For base chains, possible options for
+**default-action** are **accept** or **drop**.
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter default-action
+   [accept | drop]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> default-action
+   [accept | continue | drop | jump | queue | return]
+
+   This set the default action of the rule-set if no rule matched a packet
+   criteria. 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 chain,
+   more actions are available.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> default-jump-target <text>
+
+   To be used only when ``defult-action`` is set to ``jump``. Use this
+   command to specify jump target for default rule.
+```
+
+:::{note}
+**Important note about default-actions:**
+If default action for any base chain is not defined, then the default
+action is set to **accept** for that chain. For custom chains, if default
+action is not defined, then the default-action is set to **drop**.
+:::
+
+### Firewall Logs
+
+Logging can be enable for every single firewall rule. If enabled, other
+log options can be defined.
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999> log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999> log
+
+   Enable logging for the matched packet. If this configuration command is not
+   present, then log is not enabled.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter default-log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> default-log
+
+   Use this command to enable the logging of the default action on
+   the specified chain.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   log-options level [emerg | alert | crit | err | warn | notice
+   | info | debug]
+```
+
+```{eval-rst}
+.. 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 enable.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   log-options group <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   log-options group <0-65535>
+
+   Define log group to send message to. Only applicable if rule log is enable.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   log-options snapshot-length <0-9000>
+```
+
+```{eval-rst}
+.. 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 enable and log group is defined.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   log-options queue-threshold <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   log-options queue-threshold <0-65535>
+
+   Define number of packets to queue inside the kernel before sending them to
+   userspace. Only applicable if rule log is enable and log group is defined.
+```
+
+### Firewall Description
+
+For reference, a description can be defined for every defined custom chain.
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> description <text>
+
+   Provide a rule-set description to a custom firewall chain.
+```
+
+### Rule Status
+
+When defining a rule, it is enable by default. In some cases, it is useful to
+just disable the rule, rather than removing it.
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999> disable
+```
+
+```{eval-rst}
+.. 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 a lot of matching criteria against which the packet can be tested.
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   destination mac-address <mac-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   destination mac-address <mac-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   source mac-address <mac-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   source mac-address <mac-address>
+
+   Match criteria based on source and/or destination mac-address.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   inbound-interface name <iface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   inbound-interface name <iface>
+
+   Match based on inbound interface. Wilcard ``*`` can be used.
+   For example: ``eth2*``. Prepending character ``!`` for inverted matching
+   criteria is also supportd. For example ``!eth2``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   inbound-interface group <iface_group>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   inbound-interface group <iface_group>
+
+   Match based on inbound interface group. Prepending character ``!`` for
+   inverted matching criteria is also supportd. For example ``!IFACE_GROUP``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   outbound-interface name <iface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   outbound-interface name <iface>
+
+   Match based on outbound interface. Wilcard ``*`` can be used.
+   For example: ``eth2*``. Prepending character ``!`` for inverted matching
+   criteria is also supportd. For example ``!eth2``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   outbound-interface group <iface_group>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   outbound-interface group <iface_group>
+
+   Match based on outbound interface group. Prepending character ``!`` for
+   inverted matching criteria is also supportd. For example ``!IFACE_GROUP``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   vlan id <0-4096>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   vlan id <0-4096>
+
+   Match based on vlan ID. Range is also supported.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+   vlan priority <0-7>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+   vlan priority <0-7>
+
+   Match based on vlan priority(pcp). Range is also supported.
+```
+
+## 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 statiscits:
+
+```{eval-rst}
+.. opcmd:: show firewall
+```
+
+```{eval-rst}
+.. opcmd:: show firewall summary
+```
+
+```{eval-rst}
+.. opcmd:: show firewall statistics
+```
+
+And, to print only bridge firewall information:
+
+```{eval-rst}
+.. opcmd:: show firewall bridge
+```
+
+```{eval-rst}
+.. opcmd:: show firewall bridge forward filter
+```
+
+```{eval-rst}
+.. opcmd:: show firewall bridge forward filter rule <rule>
+```
+
+```{eval-rst}
+.. opcmd:: show firewall bridge name <name>
+```
+
+```{eval-rst}
+.. opcmd:: show firewall bridge name <name> rule <rule>
+```
+
+### Show Firewall log
+
+```{eval-rst}
+.. opcmd:: show log firewall
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall bridge
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall bridge forward
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall bridge forward filter
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall bridge name <name>
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall bridge forward filter rule <rule>
+```
+
+```{eval-rst}
+.. 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..bc9fc457
--- /dev/null
+++ b/docs/configuration/firewall/flowtables.md
@@ -0,0 +1,195 @@
+---
+lastproofread: '2024-06-20'
+---
+
+(firewall-flowtables-configuration)=
+
+# Flowtables Firewall Configuration
+
+:::{note}
+**Documentation under development**
+:::
+
+## Overview
+
+In this section there's useful information of all firewall configuration that
+can be done regarding flowtables.
+
+```{eval-rst}
+.. cfgcmd:: set firewall flowtables ...
+```
+
+From 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
+    * flowtable
+         - custom_flow_table
+            + ...
+```
+
+Flowtables allows you to define a fastpath through the flowtable datapath.
+The flowtable supports for the layer 3 IPv4 and IPv6 and the layer 4 TCP
+and UDP protocols.
+
+:::{figure} /_static/images/firewall-flowtable-packet-flow.png
+:::
+
+Once the first packet of the flow successfully goes through the IP forwarding
+path (black circles path), from the second packet on, you might decide to
+offload the flow to the flowtable through your ruleset. The flowtable
+infrastructure provides a rule action that allows you to specify when to add
+a flow to the flowtable (On forward filtering, red circle number 6)
+
+A packet that finds a matching entry in the flowtable (flowtable hit) is
+transmitted to the output netdevice, hence, packets bypass the classic IP
+forwarding path and uses the **Fast Path** (orange circles path). The visible
+effect is that you do not see these packets from any of the Netfilter
+hooks coming after ingress. In case that there is no matching entry in the
+flowtable (flowtable miss), the packet follows the classic IP forwarding path.
+
+:::{note}
+**Flowtable Reference:**
+<https://docs.kernel.org/networking/nf_flowtable.html>
+:::
+
+## Flowtable Configuration
+
+In order to use flowtables, the minimal configuration needed includes:
+
+> - Create flowtable: create flowtable, which includes the interfaces
+>   that are going to be used by the flowtable.
+> - Create firewall rule: create a firewall rule, setting action to
+>   `offload` and using desired flowtable for `offload-target`.
+
+Creating a flow table:
+
+```{eval-rst}
+.. cfgcmd:: set firewall flowtable <flow_table_name> interface <iface>
+
+   Define interfaces to be used in the flowtable.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall flowtable <flow_table_name> description <text>
+```
+
+Provide a description to the flow table.
+
+```{eval-rst}
+.. cfgcmd:: set firewall flowtable <flow_table_name> offload
+   <hardware | software>
+
+   Define type of offload to be used by the flowtable: ``hardware`` or
+   ``software``. By default, ``software`` offload is used.
+```
+
+:::{note}
+**Hardware offload:** should be supported by the NICs used.
+:::
+
+Creating rules for using flow tables:
+
+```{eval-rst}
+.. cfgcmd:: set firewall [ipv4 | ipv6] forward filter rule <1-999999>
+   action offload
+
+   Create firewall rule in forward chain, and set action to ``offload``.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall [ipv4 | ipv6] forward filter rule <1-999999>
+   offload-target <flowtable>
+
+   Create firewall rule in forward chain, and define which flowtbale
+   should be used. Only applicable if action is ``offload``.
+```
+
+## Configuration Example
+
+Things to be considred in this setup:
+
+> - Two interfaces are going to be used in the flowtables: eth0 and eth1
+> - Minumum firewall ruleset is provided, which includes some filtering rules,
+>   and appropiate rules for using flowtable offload capabilities.
+
+As described, first packet will be evaluated by all the firewall path, so
+desired connection should be explicitely accepted. Same thing should be taken
+into account for traffic in reverse order. In most cases state policies are
+used in order to accept connection in reverse patch.
+
+We will only accept traffic comming from interface eth0, protocol tcp and
+destination port 1122. All other traffic traspassing the router should be
+blocked.
+
+### 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
+
+Analysis on what happens for desired connection:
+
+> 1\. First packet is received on eth0, with destination address 192.0.2.100,
+> protocol tcp and destination port 1122. Assume such destination address is
+> reachable through interface eth1.
+>
+> 2\. Since this is the first packet, connection status of this connection,
+> so far is **new**. So neither rule 10 nor 20 are valid.
+>
+> 3. Rule 110 is hit, so connection is accepted.
+>
+> 4\. Once answer from server 192.0.2.100 is seen in opposite direction,
+> connection state will be triggered to **established**, so this reply is
+> accepted in rule 20.
+>
+> 5\. Second packet for this connection is received by the router. Since
+> connection state is **established**, then rule 10 is hit, and a new entry
+> in the flowtable FT01 is added for this connection.
+>
+> 6\. All the following packets will skip traditional path, and will be offloaded
+> and will use the **Fast Path**.
+
+### Checks
+
+It's time to check conntrack table, to see if any connection was accepted,
+and if was properly offloaded
+
+```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..6ca5a0e2
--- /dev/null
+++ b/docs/configuration/firewall/global-options.md
@@ -0,0 +1,187 @@
+---
+lastproofread: '2023-12-26'
+---
+
+(firewall-global-options-configuration)=
+
+# Global Options Firewall Configuration
+
+## Overview
+
+Some firewall settings are global and have an affect on the whole system.
+In this section there's useful information about these global-options that can
+be configured using vyos cli.
+
+Configuration commands covered in this section:
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options ...
+```
+
+## Configuration
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options all-ping [enable | disable]
+
+   By default, when VyOS receives an ICMP echo request packet destined for
+   itself, it will answer with an ICMP echo reply, unless you avoid it
+   through its firewall.
+
+   With the firewall you can set rules to accept, drop or reject ICMP in,
+   out or local traffic. You can also use the general **firewall all-ping**
+   command. This command affects only to LOCAL (packets destined for your
+   VyOS system), not to IN or OUT traffic.
+
+   .. note:: **firewall global-options all-ping** affects only to LOCAL
+      and it always behaves in the most restrictive way
+
+   .. code-block:: none
+
+      set firewall global-options all-ping enable
+
+   When the command above is set, VyOS will answer every ICMP echo request
+   addressed to itself, but that will only happen if no other rule is
+   applied dropping or rejecting local echo requests. In case of conflict,
+   VyOS will not answer ICMP echo requests.
+
+   .. code-block:: none
+
+      set firewall global-options all-ping disable
+
+   When the command above is set, VyOS will answer no ICMP echo request
+   addressed to itself at all, no matter where it comes from or whether
+   more specific rules are being applied to accept them.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options broadcast-ping [enable | disable]
+
+   This setting enable or disable the response of icmp broadcast
+   messages. The following system parameter will be altered:
+
+   * ``net.ipv4.icmp_echo_ignore_broadcasts``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options ip-src-route [enable | disable]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options ipv6-src-route [enable | disable]
+
+   This setting handle if VyOS accept packets with a source route
+   option. The following system parameter will be altered:
+
+   * ``net.ipv4.conf.all.accept_source_route``
+   * ``net.ipv6.conf.all.accept_source_route``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options receive-redirects [enable | disable]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options ipv6-receive-redirects
+   [enable | disable]
+
+   enable or disable of ICMPv4 or ICMPv6 redirect messages accepted
+   by VyOS. The following system parameter will be altered:
+
+   * ``net.ipv4.conf.all.accept_redirects``
+   * ``net.ipv6.conf.all.accept_redirects``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options send-redirects [enable | disable]
+
+   enable or disable ICMPv4 redirect messages send by VyOS
+   The following system parameter will be altered:
+
+   * ``net.ipv4.conf.all.send_redirects``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options log-martians [enable | disable]
+
+   enable or disable the logging of martian IPv4 packets.
+   The following system parameter will be altered:
+
+   * ``net.ipv4.conf.all.log_martians``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options source-validation
+   [strict | loose | disable]
+
+   Set the IPv4 source validation mode.
+   The following system parameter will be altered:
+
+   * ``net.ipv4.conf.all.rp_filter``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options syn-cookies [enable | disable]
+
+   Enable or Disable if VyOS use IPv4 TCP SYN Cookies.
+   The following system parameter will be altered:
+
+   * ``net.ipv4.tcp_syncookies``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options twa-hazards-protection
+   [enable | disable]
+
+   Enable or Disable VyOS to be {rfc}`1337` conform.
+   The following system parameter will be altered:
+
+   * ``net.ipv4.tcp_rfc1337``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options state-policy established action
+   [accept | drop | reject]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options state-policy established log
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options state-policy invalid action
+   [accept | drop | reject]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options state-policy invalid log
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options state-policy related action
+   [accept | drop | reject]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall global-options state-policy related log
+```
+
+```{eval-rst}
+.. 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.
+```
diff --git a/docs/configuration/firewall/groups.md b/docs/configuration/firewall/groups.md
new file mode 100644
index 00000000..d3c2db6e
--- /dev/null
+++ b/docs/configuration/firewall/groups.md
@@ -0,0 +1,495 @@
+---
+lastproofread: '2023-11-08'
+---
+
+(firewall-groups-configuration)=
+
+# Firewall groups
+
+## Configuration
+
+Firewall groups represent collections of IP addresses, networks, ports,
+mac addresses, domains or interfaces. Once created, a group can be referenced
+by firewall, nat and policy route rules as either a source or destination
+matcher, and/or as inbound/outbound in the case of interface group.
+
+### Address Groups
+
+In an **address group** a single IP address or IP address ranges are
+defined.
+
+```{eval-rst}
+.. cfgcmd:: set firewall group address-group <name> address [address |
+   address range]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall group ipv6-address-group <name> address <address>
+
+   Define a IPv4 or a 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall group address-group <name> description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall group ipv6-address-group <name> description <text>
+
+   Provide a IPv4 or IPv6 address group description
+```
+
+### Network Groups
+
+While **network groups** accept IP networks in CIDR notation, specific
+IP addresses can be added as a 32-bit prefix. If you foresee the need
+to add a mix of addresses and networks, the network group is
+recommended.
+
+```{eval-rst}
+.. cfgcmd:: set firewall group network-group <name> network <CIDR>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR>
+
+   Define a 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall group network-group <name> description <text>
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set firewall group interface-group <name> interface <text>
+
+   Define an interface group. Wildcard are accepted too.
+```
+
+```none
+set firewall group interface-group LAN interface bond1001
+set firewall group interface-group LAN interface eth3*
+```
+
+```{eval-rst}
+.. 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. Port
+groups can be referenced for either TCP or UDP. It is recommended that
+TCP and UDP groups are created separately to avoid accidentally
+filtering unnecessary ports. Ranges of ports can be specified by using
+`-`.
+
+```{eval-rst}
+.. 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. e.g.: 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
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall group mac-group <name> description <text>
+
+   Provide a mac group description.
+```
+
+### Domain Groups
+
+A **domain group** represents a collection of domains.
+
+```{eval-rst}
+.. cfgcmd:: set firewall group domain-group <name> address <domain>
+
+   Define a domain group.
+```
+
+```none
+set firewall group domain-group DOM address example.com
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall group domain-group <name> description <text>
+
+   Provide a domain group description.
+```
+
+### Dynamic Groups
+
+Firewall dynamic groups are different from all the groups defined previously
+because, not only they can be used as source/destination in firewall rules,
+but members of these groups are not defined statically using vyos
+configuration.
+
+Instead, members of these groups are added dynamically using firewall
+rules.
+
+#### Defining Dynamic Address Groups
+
+Dynamic address group is supported by both IPv4 and IPv6 families.
+Commands used to define dynamic IPv4|IPv6 address groups are:
+
+```{eval-rst}
+.. cfgcmd:: set firewall group dynamic-group address-group <name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall group dynamic-group ipv6-address-group <name>
+```
+
+Add description to firewall groups:
+
+```{eval-rst}
+.. cfgcmd:: set firewall group dynamic-group address-group <name>
+   description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall group dynamic-group ipv6-address-group <name>
+   description <text>
+```
+
+#### Adding elements to Dynamic Firewall Groups
+
+Once dynamic firewall groups are defined, they should be used in firewall
+rules in order to dynamically add elements to it.
+
+Commands used for this task are:
+
+- Add destination IP address of the connection to a dynamic address group:
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule
+   <1-999999> add-address-to-group destination-address address-group <name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group
+   destination-address address-group <name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule
+   <1-999999> add-address-to-group destination-address address-group <name>
+```
+
+```{eval-rst}
+.. 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:
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule
+   <1-999999> add-address-to-group source-address address-group <name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group
+   source-address address-group <name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule
+   <1-999999> add-address-to-group source-address address-group <name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group
+   source-address address-group <name>
+```
+
+Also, specific timeout can be defined per rule. In case rule gets a hit,
+source or destinatination address will be added to the group, and this
+element will remain in the group until timeout expires. If no timeout
+is defined, then the element will remain in the group until next reboot,
+or until a new commit that changes firewall configuration is done.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule
+   <1-999999> add-address-to-group [destination-address | source-address]
+   timeout <timeout>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group
+   [destination-address | source-address] timeout <timeout>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule
+   <1-999999> add-address-to-group [destination-address | source-address]
+   timeout <timeout>
+```
+
+```{eval-rst}
+.. 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
+
+As any other firewall group, dynamic firewall groups can be used 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
+
+As said before, once firewall groups are created, they can be referenced
+either in firewall, nat, nat66 and/or policy-route rules.
+
+Here is an example were multiple groups are created:
+
+> ```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:
+
+> ```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
+
+Using dynamic firewall groups, we can secure access to the router, or any other
+device if needed, by using the technique of port knocking.
+
+A 4 step port knocking example is shown next:
+
+> ```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 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, in order to get ssh access to the router, user
+needs to:
+
+1\. Generate a new TCP connection with destination port 9990. As shown next,
+a new entry was 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\. Generate a new TCP connection with destination port 9991. As shown next,
+a new entry was 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\. Generate a new TCP connection with destination port 9992. As shown next,
+a new entry was 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 user can connect through ssh to the router (assuming ssh is configured).
+
+## Operation-mode
+
+```{eval-rst}
+.. opcmd:: show firewall group
+```
+
+```{eval-rst}
+.. opcmd:: show firewall group <name>
+
+   Overview of defined groups. You see the firewall group name, type,
+   references (where the group is used), members, timeout and expiration (last
+   two only present in 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..53c5a7fc
--- /dev/null
+++ b/docs/configuration/firewall/index.md
@@ -0,0 +1,181 @@
+---
+lastproofread: '2023-11-23'
+---
+
+# Firewall
+
+As VyOS is based on Linux it leverages its firewall. The Netfilter project
+created iptables and its successor nftables for the Linux kernel to
+work directly on packet data flows. This now extends the concept of
+zone-based security to allow for manipulating the data at multiple stages once
+accepted by the network interface and the driver before being handed off to
+the destination (e.g., a web server OR another device).
+
+A simplified traffic flow diagram, based on Netfilter packet flow, is shown
+next, in order to have a full view and understanding of how packets are
+processed, and what possible paths traffic can take.
+
+:::{figure} /_static/images/firewall-gral-packet-flow.png
+:::
+
+The main points regarding this packet flow and terminology used in VyOS
+firewall are covered below:
+
+> - **Bridge Port?**: choose appropriate path based on whether interface
+>   where the packet was received is part of a bridge, or not.
+
+If the interface where the packet was received isn't part of a bridge, then
+packetis processed at the **IP Layer**:
+
+> - **Prerouting**: several actions can be done in this stage, and currently
+>   these actions are defined in different parts in VyOS configuration. Order
+>   is important, and all these actions are performed before any actions
+>   defined under `firewall` section. Relevant configuration that acts in
+>   this stage are:
+>
+>   > - **Conntrack Ignore**: rules defined under `set system conntrack ignore
+>   >   [ipv4 | ipv6] ...`.
+>   > - **Policy Route**: rules defined under `set policy [route | route6]
+>   >   ...`.
+>   > - **Destination NAT**: rules defined under `set [nat | nat66]
+>   >   destination...`.
+>
+> - **Destination is the router?**: choose appropriate path based on
+>   destination IP address. Transit forward continues to **forward**,
+>   while traffic that destination IP address is configured on the router
+>   continues to **input**.
+>
+> - **Input**: stage where traffic destined for the router itself can be
+>   filtered and controlled. This is where all rules for securing the router
+>   should take place. This includes ipv4 and ipv6 filtering rules, defined
+>   in:
+>
+>   - `set firewall ipv4 input filter ...`.
+>   - `set firewall ipv6 input filter ...`.
+>
+> - **Forward**: stage where transit traffic can be filtered and controlled.
+>   This includes ipv4 and ipv6 filtering rules, defined in:
+>
+>   - `set firewall ipv4 forward filter ...`.
+>   - `set firewall ipv6 forward filter ...`.
+>
+> - **Output**: stage where traffic that originates from the router itself
+>   can be filtered and controlled. Bear in mind that this traffic can be a
+>   new connection originated by a internal process running on VyOS router,
+>   such as NTP, or a response to traffic received externaly through
+>   **input** (for example response to an ssh login attempt to the router).
+>   This includes ipv4 and ipv6 filtering rules, defined in:
+>
+>   - `set firewall ipv4 output filter ...`.
+>   - `set firewall ipv6 output filter ...`.
+>
+> - **Postrouting**: as in **Prerouting**, several actions defined in
+>   different parts of VyOS configuration are performed in this
+>   stage. This includes:
+>
+>   - **Source NAT**: rules defined under `set [nat | nat66]
+>     destination...`.
+
+If the interface where the packet was received is part of a bridge, then
+the packet is processed at the **Bridge Layer**, which contains a basic setup for
+bridge filtering:
+
+> - **Forward (Bridge)**: stage where traffic that is trespasing through the
+>   bridge is filtered and controlled:
+>
+>   - `set firewall bridge forward filter ...`.
+
+The main structure of the VyOS firewall CLI is shown next:
+
+```none
+- set firewall
+    * bridge
+         - forward
+            + filter
+    * 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
+         - name
+            + custom_name
+    * ipv6
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+         - ipv6-name
+            + custom_name
+    * zone
+         - custom_zone_name
+            + ...
+```
+
+Please, refer to appropriate section for more information about firewall
+configuration:
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   global-options
+   groups
+   bridge
+   ipv4
+   ipv6
+   flowtables
+```
+
+:::{note}
+**For more information**
+of Netfilter hooks and Linux networking packet flows can be
+found in [Netfilter-Hooks](https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks)
+:::
+
+## Zone-based firewall
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   zone
+```
+
+With zone-based firewalls a new concept was implemented, in addition to the
+standard in and out traffic flows, a local flow was added. This local was for
+traffic originating and destined to the router itself. Which means additional
+rules were required to secure the firewall itself from the network, in
+addition to the existing inbound and outbound rules from the traditional
+concept above.
+
+To configure VyOS with the
+{doc}`zone-based firewall configuration </configuration/firewall/zone>`
+
+As the example image below shows, the device now needs rules to allow/block
+traffic to or from the services running on the device that have open
+connections on that interface.
+
+:::{figure} /_static/images/firewall-zonebased.png
+:::
diff --git a/docs/configuration/firewall/ipv4.md b/docs/configuration/firewall/ipv4.md
new file mode 100644
index 00000000..23ff6c39
--- /dev/null
+++ b/docs/configuration/firewall/ipv4.md
@@ -0,0 +1,2037 @@
+---
+lastproofread: '2023-11-08'
+---
+
+(firewall-ipv4-configuration)=
+
+# IPv4 Firewall Configuration
+
+## Overview
+
+In this section there's useful information of all firewall configuration that
+can be done regarding IPv4, and appropiate op-mode commands.
+Configuration commands covered in this section:
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 ...
+```
+
+From 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
+    * ipv4
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+         - name
+            + custom_name
+```
+
+For transit traffic, which is received by the router and forwarded, base chain
+is **forward**. A simplified packet flow diagram for transit traffic is shown
+next:
+
+:::{figure} /_static/images/firewall-fwd-packet-flow.png
+:::
+
+Where firewall base chain to configure firewall filtering rules for transit
+traffic is `set firewall ipv4 forward filter ...`, which happens in stage 5,
+highlightened with red color.
+
+For traffic towards the router itself, base chain is **input**, while traffic
+originated by the router, base chain is **output**.
+A new simplified packet flow diagram is shown next, which shows the path
+for traffic destinated to the router itself, and traffic generated by the
+router (starting from circle number 6):
+
+:::{figure} /_static/images/firewall-input-packet-flow.png
+:::
+
+Base chain is for traffic toward the router is `set firewall ipv4 input
+filter ...`
+
+And base chain for traffic generated by the router is `set firewall ipv4
+output filter ...`
+
+:::{note}
+**Important note about default-actions:**
+If default action for any base chain is not defined, then the default
+action is set to **accept** for that chain. For custom chains, if default
+action is not defined, then the default-action is set to **drop**
+:::
+
+Custom firewall chains can be created, with commands
+`set firewall ipv4 name <name> ...`. In order to use
+such custom chain, a rule with **action jump**, and the appropiate **target**
+should be defined in a base chain.
+
+## Firewall - IPv4 Rules
+
+For firewall filtering, firewall rules needs to be created. Each rule is
+numbered, has an action to apply if the rule is matched, and the ability
+to specify multiple criteria matchers. 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, then an action must be defined for it. This tells the
+firewall what to do if all criteria matchers defined for such rule do match.
+
+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.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> action
+   [accept | continue | drop | jump | queue | reject | return | synproxy]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> action
+   [accept | continue | drop | jump | queue | reject | return | synproxy]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> action
+   [accept | continue | drop | jump | queue | reject | return]
+```
+
+```{eval-rst}
+.. 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 action is
+   set to jump, then jump-target is also needed.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   jump-target <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   jump-target <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   jump-target <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   jump-target <text>
+
+   To be used only when action is set to ``jump``. Use this command to specify
+   jump target.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   queue <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   queue <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   queue <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   queue <0-65535>
+
+   To be used only when action is set to ``queue``. Use this command to specify
+   queue target to use. Queue range is also supported.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   queue-options bypass
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   queue-options bypass
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   queue-options bypass
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   queue-options bypass
+
+   To be used only when action is set to ``queue``. Use this command to let
+   packet go through firewall when no userspace software is connected to the
+   queue.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   queue-options fanout
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   queue-options fanout
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   queue-options fanout
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   queue-options fanout
+
+   To be used only when action is set to ``queue``. Use this command to
+   distribute packets between several queues.
+```
+
+Also, **default-action** is an action that takes place whenever a packet does
+not match any rule in it's chain. For base chains, possible options for
+**default-action** are **accept** or **drop**.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter default-action
+   [accept | drop]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter default-action
+   [accept | drop]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter default-action
+   [accept | drop]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> default-action
+   [accept | drop | jump | queue | reject | return]
+
+   This set the default action of the rule-set if no rule matched a packet
+   criteria. 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 chain,
+   more actions are available.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> default-jump-target <text>
+
+   To be used only when ``defult-action`` is set to ``jump``. Use this
+   command to specify jump target for default rule.
+```
+
+:::{note}
+**Important note about default-actions:**
+If default action for any base chain is not defined, then the default
+action is set to **accept** for that chain. For custom chains, if default
+action is not defined, then the default-action is set to **drop**.
+:::
+
+### Firewall Logs
+
+Logging can be enable for every single firewall rule. If enabled, other
+log options can be defined.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> log
+
+   Enable logging for the matched packet. If this configuration command is not
+   present, then log is not enabled.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter default-log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter default-log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter default-log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> default-log
+
+   Use this command to enable the logging of the default action on
+   the specified chain.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   log-options level [emerg | alert | crit | err | warn | notice
+   | info | debug]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   log-options level [emerg | alert | crit | err | warn | notice
+   | info | debug]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   log-options level [emerg | alert | crit | err | warn | notice
+   | info | debug]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 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 enable.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   log-options group <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   log-options group <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   log-options group <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   log-options group <0-65535>
+
+   Define log group to send message to. Only applicable if rule log is enable.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   log-options snapshot-length <0-9000>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   log-options snapshot-length <0-9000>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   log-options snapshot-length <0-9000>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 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 enable and log group is defined.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   log-options queue-threshold <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   log-options queue-threshold <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   log-options queue-threshold <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   log-options queue-threshold <0-65535>
+
+   Define number of packets to queue inside the kernel before sending them to
+   userspace. Only applicable if rule log is enable and log group is defined.
+```
+
+### Firewall Description
+
+For reference, a description can be defined for every single rule, and for
+every defined custom chain.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> description <text>
+
+   Provide a rule-set description to a custom firewall chain.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> description <text>
+
+   Provide a description for each rule.
+```
+
+### Rule Status
+
+When defining a rule, it is enable by default. In some cases, it is useful to
+just disable the rule, rather than removing it.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> disable
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> disable
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> disable
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 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.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   connection-status nat [destination | source]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   connection-status nat [destination | source]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   connection-status nat [destination | source]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   connection-status nat [destination | source]
+
+   Match criteria based on nat connection status.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   connection-mark <1-2147483647>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   connection-mark <1-2147483647>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   connection-mark <1-2147483647>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   connection-mark <1-2147483647>
+
+   Match criteria based on connection mark.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination address-mask [address]
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination fqdn <fqdn>
+
+   Specify a Fully Qualified Domain Name as source/destination matcher. Ensure
+   router is able to resolve such dns query.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination geoip inverse-match
+
+   Match IP addresses based on its geolocation. More info: `geoip matching
+   <https://wiki.nftables.org/wiki-nftables/index.php/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.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source mac-address <mac-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source mac-address <mac-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source mac-address <mac-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source mac-address <mac-address>
+
+   Only in the source criteria, you can specify a mac-address.
+
+   .. 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
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination port [1-65535 | portname | start-end]
+
+   A port can be set with a port number or a name which is here
+   defined: ``/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:
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination group address-group <name | !name>
+
+   Use a specific address-group. Prepend character ``!`` for inverted matching
+   criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+
+   Use a specific dynamic-address-group. Prepend character ``!`` for inverted
+   matching criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination group network-group <name | !name>
+
+   Use a specific network-group. Prepend character ``!`` for inverted matching
+   criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination group port-group <name | !name>
+
+   Use a specific port-group. Prepend character ``!`` for inverted matching
+   criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination group domain-group <name | !name>
+
+   Use a specific domain-group. Prepend character ``!`` for inverted matching
+   criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   source group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   source group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   source group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   source group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   destination group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   destination group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   destination group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   destination group mac-group <name | !name>
+
+   Use a specific mac-group. Prepend character ``!`` for inverted matching
+   criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   dscp [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   dscp [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   dscp [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   dscp [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   dscp-exclude [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   dscp-exclude [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   dscp-exclude [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   dscp-exclude [0-63 | start-end]
+
+   Match based on dscp value.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   fragment [match-frag | match-non-frag]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   fragment [match-frag | match-non-frag]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   fragment [match-frag | match-non-frag]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   fragment [match-frag | match-non-frag]
+
+   Match based on fragment criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   icmp [code | type] <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   icmp [code | type] <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   icmp [code | type] <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   icmp [code | type] <0-255>
+
+   Match based on icmp code and type.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   icmp type-name <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   icmp type-name <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   icmp type-name <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   icmp type-name <text>
+
+   Match based on icmp type-name criteria. Use tab for information
+   about what **type-name** criteria are supported.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   inbound-interface name <iface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   inbound-interface name <iface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   inbound-interface name <iface>
+
+   Match based on inbound interface. Wilcard ``*`` can be used.
+   For example: ``eth2*``. Prepending character ``!`` for inverted matching
+   criteria is also supportd. For example ``!eth2``
+```
+
+:::{note}
+If an interface is attached to a non-default vrf, when using
+**inbound-interface**, vrf name must be used. For example `set firewall
+ipv4 forward filter rule 10 inbound-interface name MGMT`
+:::
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   inbound-interface group <iface_group>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   inbound-interface group <iface_group>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   inbound-interface group <iface_group>
+
+   Match based on inbound interface group. Prepending character ``!`` for
+   inverted matching criteria is also supportd. For example ``!IFACE_GROUP``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   outbound-interface name <iface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   outbound-interface name <iface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   outbound-interface name <iface>
+
+   Match based on outbound interface. Wilcard ``*`` can be used.
+   For example: ``eth2*``. Prepending character ``!`` for inverted matching
+   criteria is also supportd. For example ``!eth2``
+```
+
+:::{note}
+If an interface is attached to a non-default vrf, when using
+**outbound-interface**, real interface name must be used. For example
+`set firewall ipv4 forward filter rule 10 outbound-interface name eth0`
+:::
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   outbound-interface group <iface_group>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   outbound-interface group <iface_group>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   outbound-interface group <iface_group>
+
+   Match based on outbound interface group. Prepending character ``!`` for
+   inverted matching criteria is also supportd. For example ``!IFACE_GROUP``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   ipsec [match-ipsec | match-none]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   ipsec [match-ipsec | match-none]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   ipsec [match-ipsec | match-none]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   ipsec [match-ipsec | match-none]
+
+   Match based on ipsec criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   limit burst <0-4294967295>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   limit burst <0-4294967295>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   limit burst <0-4294967295>
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   limit rate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   limit rate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   limit rate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   limit rate <text>
+
+   Match based on the maximum average rate, specified as **integer/unit**.
+   For example **5/minutes**
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   packet-length <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   packet-length <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   packet-length <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   packet-length <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   packet-length-exclude <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   packet-length-exclude <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   packet-length-exclude <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   packet-length-exclude <text>
+
+   Match based on packet length criteria. Multiple values from 1 to 65535
+   and ranges are supported.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   packet-type [broadcast | host | multicast | other]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   packet-type [broadcast | host | multicast | other]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   packet-type [broadcast | host | multicast | other]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   packet-type [broadcast | host | multicast | other]
+
+   Match based on packet type criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   protocol [<text> | <0-255> | all | tcp_udp]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   protocol [<text> | <0-255> | all | tcp_udp]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   protocol [<text> | <0-255> | all | tcp_udp]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   protocol [<text> | <0-255> | all | tcp_udp]
+
+   Match a protocol criteria. A protocol number or a name which is here
+   defined: ``/etc/protocols``.
+   Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and udp
+   based packets. The ``!`` negate the selected protocol.
+
+   .. code-block:: none
+
+      set firewall ipv4 forward fitler rule 10 protocol tcp_udp
+      set firewall ipv4 forward fitler rule 11 protocol !tcp_udp
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   recent time [second | minute | hour]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   recent time [second | minute | hour]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   recent time [second | minute | hour]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   recent time [second | minute | hour]
+
+   Match bases on recently seen sources.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   tcp flags [not] <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   tcp flags [not] <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   tcp flags [not] <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> 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.
+
+   .. 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'
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   state [established | invalid | new | related]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   state [established | invalid | new | related]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   state [established | invalid | new | related]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   state [established | invalid | new | related]
+
+   Match against the state of a packet.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   time startdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   time startdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   time startdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   time startdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   time starttime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   time starttime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   time starttime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   time starttime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   time stopdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   time stopdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   time stopdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   time stopdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   time stoptime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   time stoptime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   time stoptime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   time stoptime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   time weekdays <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   time weekdays <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   time weekdays <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   time weekdays <text>
+
+   Time to match the defined rule.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   ttl <eq | gt | lt> <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   ttl <eq | gt | lt> <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   ttl <eq | gt | lt> <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   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'.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   recent time <second | minute | hour>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   recent time <second | minute | hour>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   recent time <second | minute | hour>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+   recent time <second | minute | hour>
+
+   Match when 'count' amount of connections are seen within 'time'. These
+   matching criteria can be used to block brute-force attempts.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+   conntrack-helper <module>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+   conntrack-helper <module>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+   conntrack-helper <module>
+```
+
+```{eval-rst}
+.. 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
+
+```
+
+## Synproxy
+
+Synproxy connections
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999>
+   action synproxy
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999>
+   protocol tcp
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999>
+   synproxy tcp mss <501-65535>
+
+    Set TCP-MSS (maximum segment size) for the connection
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. opcmd:: show firewall
+
+   This will show you a basic firewall overview, for all ruleset, and 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:~$
+```
+
+```{eval-rst}
+.. 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
+
+```
+
+```{eval-rst}
+.. opcmd:: show firewall ipv4 [forward | input | output] filter
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. opcmd:: show firewall ipv4 [forward | input | output]
+   filter rule <1-999999>
+```
+
+```{eval-rst}
+.. opcmd:: show firewall ipv4 name <name> rule <1-999999>
+
+   This command will give 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:~$
+```
+
+```{eval-rst}
+.. opcmd:: show firewall statistics
+
+   This will show you a statistic of all rule-sets since the last boot.
+```
+
+### Show Firewall log
+
+```{eval-rst}
+.. opcmd:: show log firewall
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv4
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv4 [forward | input | output | name]
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv4 [forward | input | output] filter
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv4 name <name>
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv4 [forward | input | output] filter rule <rule>
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. opcmd:: update geoip
+
+   Command used to update GeoIP database and firewall sets.
+```
diff --git a/docs/configuration/firewall/ipv6.md b/docs/configuration/firewall/ipv6.md
new file mode 100644
index 00000000..e2db7928
--- /dev/null
+++ b/docs/configuration/firewall/ipv6.md
@@ -0,0 +1,2026 @@
+---
+lastproofread: '2023-11-08'
+---
+
+(firewall-ipv6-configuration)=
+
+# IPv6 Firewall Configuration
+
+## Overview
+
+In this section there's useful information of all firewall configuration that
+can be done regarding IPv6, and appropiate op-mode commands.
+Configuration commands covered in this section:
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 ...
+```
+
+From 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
+    * ipv6
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+         - name
+            + custom_name
+```
+
+For transit traffic, which is received by the router and forwarded, base chain
+is **forward**. A simplified packet flow diagram for transit traffic is shown
+next:
+
+:::{figure} /_static/images/firewall-fwd-packet-flow.png
+:::
+
+Where firewall base chain to configure firewall filtering rules for transit
+traffic is `set firewall ipv6 forward filter ...`, which happens in stage 5,
+highlightened with red color.
+
+For traffic towards the router itself, base chain is **input**, while traffic
+originated by the router, base chain is **output**.
+A new simplified packet flow diagram is shown next, which shows the path
+for traffic destinated to the router itself, and traffic generated by the
+router (starting from circle number 6):
+
+:::{figure} /_static/images/firewall-input-packet-flow.png
+:::
+
+Base chain is for traffic toward the router is `set firewall ipv6 input
+filter ...`
+
+And base chain for traffic generated by the router is `set firewall ipv6
+output filter ...`
+
+:::{note}
+**Important note about default-actions:**
+If default action for any base chain is not defined, then the default
+action is set to **accept** for that chain. For custom chains, if default
+action is not defined, then the default-action is set to **drop**
+:::
+
+Custom firewall chains can be created, with commands
+`set firewall ipv6 name <name> ...`. In order to use
+such custom chain, a rule with **action jump**, and the appropiate **target**
+should be defined in a base chain.
+
+## Firewall - IPv6 Rules
+
+For firewall filtering, firewall rules needs to be created. Each rule is
+numbered, has an action to apply if the rule is matched, and the ability
+to specify multiple criteria matchers. 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, then an action must be defined for it. This tells the
+firewall what to do if all criteria matchers defined for such rule do match.
+
+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.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> action
+   [accept | continue | drop | jump | queue | reject | return | synproxy]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> action
+   [accept | continue | drop | jump | queue | reject | return | synproxy]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> action
+   [accept | continue | drop | jump | queue | reject | return]
+```
+
+```{eval-rst}
+.. 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 action is
+   set to jump, then jump-target is also needed.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   jump-target <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   jump-target <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   jump-target <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   jump-target <text>
+
+   To be used only when action is set to ``jump``. Use this command to specify
+   jump target.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   queue <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   queue <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   queue <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   queue <0-65535>
+
+   To be used only when action is set to ``queue``. Use this command to specify
+   queue target to use. Queue range is also supported.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   queue-options bypass
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   queue-options bypass
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   queue-options bypass
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   queue-options bypass
+
+   To be used only when action is set to ``queue``. Use this command to let
+   packet go through firewall when no userspace software is connected to the
+   queue.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   queue-options fanout
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   queue-options fanout
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   queue-options fanout
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   queue-options fanout
+
+   To be used only when action is set to ``queue``. Use this command to
+   distribute packets between several queues.
+```
+
+Also, **default-action** is an action that takes place whenever a packet does
+not match any rule in it's chain. For base chains, possible options for
+**default-action** are **accept** or **drop**.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter default-action
+   [accept | drop]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter default-action
+   [accept | drop]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter default-action
+   [accept | drop]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> default-action
+   [accept | drop | jump | queue | reject | return]
+
+   This set the default action of the rule-set if no rule matched a packet
+   criteria. 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 chain,
+   more actions are available.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> default-jump-target <text>
+
+   To be used only when ``defult-action`` is set to ``jump``. Use this
+   command to specify jump target for default rule.
+```
+
+:::{note}
+**Important note about default-actions:**
+If default action for any base chain is not defined, then the default
+action is set to **accept** for that chain. For custom chains, if default
+action is not defined, then the default-action is set to **drop**.
+:::
+
+### Firewall Logs
+
+Logging can be enable for every single firewall rule. If enabled, other
+log options can be defined.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> log
+
+   Enable logging for the matched packet. If this configuration command is not
+   present, then log is not enabled.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter default-log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter default-log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter default-log
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> default-log
+
+   Use this command to enable the logging of the default action on
+   the specified chain.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   log-options level [emerg | alert | crit | err | warn | notice
+   | info | debug]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   log-options level [emerg | alert | crit | err | warn | notice
+   | info | debug]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   log-options level [emerg | alert | crit | err | warn | notice
+   | info | debug]
+```
+
+```{eval-rst}
+.. 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 enable.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   log-options group <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   log-options group <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   log-options group <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   log-options group <0-65535>
+
+   Define log group to send message to. Only applicable if rule log is enable.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   log-options snapshot-length <0-9000>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   log-options snapshot-length <0-9000>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   log-options snapshot-length <0-9000>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 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 enable and log group is defined.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   log-options queue-threshold <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   log-options queue-threshold <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   log-options queue-threshold <0-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   log-options queue-threshold <0-65535>
+
+   Define number of packets to queue inside the kernel before sending them to
+   userspace. Only applicable if rule log is enable and log group is defined.
+```
+
+### Firewall Description
+
+For reference, a description can be defined for every single rule, and for
+every defined custom chain.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> description <text>
+
+   Provide a rule-set description to a custom firewall chain.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> description <text>
+
+   Provide a description for each rule.
+```
+
+### Rule Status
+
+When defining a rule, it is enable by default. In some cases, it is useful to
+just disable the rule, rather than removing it.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> disable
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> disable
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> disable
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   connection-status nat [destination | source]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   connection-status nat [destination | source]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   connection-status nat [destination | source]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   connection-status nat [destination | source]
+
+   Match criteria based on nat connection status.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   connection-mark <1-2147483647>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   connection-mark <1-2147483647>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   connection-mark <1-2147483647>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   connection-mark <1-2147483647>
+
+   Match criteria based on connection mark.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination address [address | addressrange | CIDR]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 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 ipv6 name FOO rule 100 source address 2001:db8::202
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination address-mask [address]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 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 is particularly useful with IPv6 as rules will
+   remain valid if the IPv6 prefix changes and the host
+   portion of systems IPv6 address is static (for example, with SLAAC or
+   `tokenised IPv6 addresses
+   <https://datatracker.ietf.org
+   /doc/id/draft-chown-6man-tokenised-ipv6-identifiers-02.txt>`_)
+
+   This functions for both individual addresses and address groups.
+
+   .. stop_vyoslinter
+   .. 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
+
+   .. start_vyoslinter
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination fqdn <fqdn>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination fqdn <fqdn>
+
+   Specify a Fully Qualified Domain Name as source/destination matcher. Ensure
+   router is able to resolve such dns query.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination geoip country-code <country>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination geoip inverse-match
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination geoip inverse-match
+
+   Match IP addresses based on its geolocation. More info: `geoip matching
+   <https://wiki.nftables.org/wiki-nftables/index.php/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.
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source mac-address <mac-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source mac-address <mac-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source mac-address <mac-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source mac-address <mac-address>
+
+   Only in the source criteria, you can specify a mac-address.
+
+   .. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination port [1-65535 | portname | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination port [1-65535 | portname | start-end]
+
+   A port can be set with a port number or a name which is here
+   defined: ``/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'
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination group address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination group address-group <name | !name>
+
+   Use a specific address-group. Prepend character ``!`` for inverted matching
+   criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination group dynamic-address-group <name | !name>
+
+   Use a specific dynamic-address-group. Prepend character ``!`` for inverted
+   matching criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination group network-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination group network-group <name | !name>
+
+   Use a specific network-group. Prepend character ``!`` for inverted matching
+   criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination group port-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination group port-group <name | !name>
+
+   Use a specific port-group. Prepend character ``!`` for inverted matching
+   criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination group domain-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination group domain-group <name | !name>
+
+   Use a specific domain-group. Prepend character ``!`` for inverted matching
+   criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   source group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   source group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   source group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   source group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   destination group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   destination group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   destination group mac-group <name | !name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   destination group mac-group <name | !name>
+
+   Use a specific mac-group. Prepend character ``!`` for inverted matching
+   criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   dscp [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   dscp [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   dscp [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   dscp [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   dscp-exclude [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   dscp-exclude [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   dscp-exclude [0-63 | start-end]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   dscp-exclude [0-63 | start-end]
+
+   Match based on dscp value.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   fragment [match-frag | match-non-frag]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   fragment [match-frag | match-non-frag]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   fragment [match-frag | match-non-frag]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   fragment [match-frag | match-non-frag]
+
+   Match based on fragment criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   icmpv6 [code | type] <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   icmpv6 [code | type] <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   icmpv6 [code | type] <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   icmpv6 [code | type] <0-255>
+
+   Match based on icmp|icmpv6 code and type.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   icmpv6 type-name <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   icmpv6 type-name <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   icmpv6 type-name <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   icmpv6 type-name <text>
+
+   Match based on icmpv6 type-name criteria. Use tab for information
+   about what **type-name** criteria are supported.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   inbound-interface name <iface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   inbound-interface name <iface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   inbound-interface name <iface>
+
+   Match based on inbound interface. Wilcard ``*`` can be used.
+   For example: ``eth2*``. Prepending character ``!`` for inverted matching
+   criteria is also supportd. For example ``!eth2``
+```
+
+:::{note}
+If an interface is attached to a non-default vrf, when using
+**inbound-interface**, vrf name must be used. For example `set firewall
+ipv6 forward filter rule 10 inbound-interface name MGMT`
+:::
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   inbound-interface group <iface_group>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   inbound-interface group <iface_group>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   inbound-interface group <iface_group>
+
+   Match based on inbound interface group. Prepending character ``!`` for
+   inverted matching criteria is also supportd. For example ``!IFACE_GROUP``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   outbound-interface name <iface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   outbound-interface name <iface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   outbound-interface name <iface>
+
+   Match based on outbound interface. Wilcard ``*`` can be used.
+   For example: ``eth2*``. Prepending character ``!`` for inverted matching
+   criteria is also supportd. For example ``!eth2``
+```
+
+:::{note}
+If an interface is attached to a non-default vrf, when using
+**outbound-interface**, real interface name must be used. For example
+`set firewall ipv6 forward filter rule 10 outbound-interface name eth0`
+:::
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   outbound-interface group <iface_group>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   outbound-interface group <iface_group>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   outbound-interface group <iface_group>
+
+   Match based on outbound interface group. Prepending character ``!`` for
+   inverted matching criteria is also supportd. For example ``!IFACE_GROUP``
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   ipsec [match-ipsec | match-none]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   ipsec [match-ipsec | match-none]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   ipsec [match-ipsec | match-none]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   ipsec [match-ipsec | match-none]
+
+   Match based on ipsec criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   limit burst <0-4294967295>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   limit burst <0-4294967295>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   limit burst <0-4294967295>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   limit burst <0-4294967295>
+
+   Match based on the maximum number of packets to allow in excess of rate.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   limit rate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   limit rate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   limit rate <text>
+```
+
+```{eval-rst}
+.. 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 **5/minutes**
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   packet-length <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   packet-length <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   packet-length <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   packet-length <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   packet-length-exclude <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   packet-length-exclude <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   packet-length-exclude <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   packet-length-exclude <text>
+
+   Match based on packet length criteria. Multiple values from 1 to 65535
+   and ranges are supported.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   packet-type [broadcast | host | multicast | other]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   packet-type [broadcast | host | multicast | other]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   packet-type [broadcast | host | multicast | other]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   packet-type [broadcast | host | multicast | other]
+
+   Match based on packet type criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   protocol [<text> | <0-255> | all | tcp_udp]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   protocol [<text> | <0-255> | all | tcp_udp]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   protocol [<text> | <0-255> | all | tcp_udp]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   protocol [<text> | <0-255> | all | tcp_udp]
+
+   Match a protocol criteria. A protocol number or a name which is here
+   defined: ``/etc/protocols``.
+   Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and udp
+   based packets. The ``!`` negate the selected protocol.
+
+   .. code-block:: none
+
+      set firewall ipv6 input filter rule 10 protocol tcp
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   recent time [second | minute | hour]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   recent time [second | minute | hour]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   recent time [second | minute | hour]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   recent time [second | minute | hour]
+
+   Match bases on recently seen sources.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   tcp flags [not] <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   tcp flags [not] <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   tcp flags [not] <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> 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.
+
+   .. 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'
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   state [established | invalid | new | related]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   state [established | invalid | new | related]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   state [established | invalid | new | related]
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   state [established | invalid | new | related]
+
+   Match against the state of a packet.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   time startdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   time startdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   time startdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   time startdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   time starttime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   time starttime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   time starttime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   time starttime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   time stopdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   time stopdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   time stopdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   time stopdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   time stoptime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   time stoptime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   time stoptime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   time stoptime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   time weekdays <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   time weekdays <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   time weekdays <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   time weekdays <text>
+
+   Time to match the defined rule.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   hop-limit <eq | gt | lt> <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   hop-limit <eq | gt | lt> <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   hop-limit <eq | gt | lt> <0-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   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'.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+   recent time <second | minute | hour>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+   recent time <second | minute | hour>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+   recent time <second | minute | hour>
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+   recent time <second | minute | hour>
+
+   Match when 'count' amount of connections are seen within 'time'. These
+   matching criteria can be used to block brute-force attempts.
+```
+
+## Synproxy
+
+Synproxy connections
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999>
+   action synproxy
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999>
+   protocol tcp
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999>
+   synproxy tcp mss <501-65535>
+
+    Set TCP-MSS (maximum segment size) for the connection
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. opcmd:: show firewall
+
+   This will show you a basic firewall overview
+
+   .. 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
+```
+
+```{eval-rst}
+.. 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
+
+```
+
+```{eval-rst}
+.. opcmd:: show firewall ipv6 [forward | input | output] filter
+```
+
+```{eval-rst}
+.. 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:~$
+```
+
+```{eval-rst}
+.. opcmd:: show firewall ipv6 [forward | input | output]
+   filter rule <1-999999>
+```
+
+```{eval-rst}
+.. opcmd:: show firewall ipv6 name <name> rule <1-999999>
+```
+
+```{eval-rst}
+.. opcmd:: show firewall ipv6 ipv6-name <name> rule <1-999999>
+
+   This command will give an overview of a rule in a single rule-set
+```
+
+```{eval-rst}
+.. opcmd:: show firewall group <name>
+
+   Overview of defined groups. You see the type, the 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
+
+```
+
+```{eval-rst}
+.. opcmd:: show firewall statistics
+
+   This will show you a statistic of all rule-sets since the last boot.
+```
+
+### Show Firewall log
+
+```{eval-rst}
+.. opcmd:: show log firewall
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv6
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv6 [forward | input | output | name]
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv6 [forward | input | output] filter
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv6 name <name>
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv6 [forward | input | output] filter rule <rule>
+```
+
+```{eval-rst}
+.. opcmd:: show log firewall ipv6 name <name> rule <rule>
+
+   Show the logs of all firewall; show all ipv6 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 {
+    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
+
+```{eval-rst}
+.. opcmd:: update geoip
+
+   Command used to update GeoIP database and firewall sets.
+```
diff --git a/docs/configuration/firewall/bridge.rst b/docs/configuration/firewall/rst-bridge.rst
index bba9e56f..bba9e56f 100644
--- a/docs/configuration/firewall/bridge.rst
+++ b/docs/configuration/firewall/rst-bridge.rst
diff --git a/docs/configuration/firewall/flowtables.rst b/docs/configuration/firewall/rst-flowtables.rst
index 917e74cc..917e74cc 100644
--- a/docs/configuration/firewall/flowtables.rst
+++ b/docs/configuration/firewall/rst-flowtables.rst
diff --git a/docs/configuration/firewall/global-options.rst b/docs/configuration/firewall/rst-global-options.rst
index b3f311aa..b3f311aa 100644
--- a/docs/configuration/firewall/global-options.rst
+++ b/docs/configuration/firewall/rst-global-options.rst
diff --git a/docs/configuration/firewall/groups.rst b/docs/configuration/firewall/rst-groups.rst
index 6111650a..6111650a 100644
--- a/docs/configuration/firewall/groups.rst
+++ b/docs/configuration/firewall/rst-groups.rst
diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/rst-index.rst
index 44e0cd20..44e0cd20 100644
--- a/docs/configuration/firewall/index.rst
+++ b/docs/configuration/firewall/rst-index.rst
diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/rst-ipv4.rst
index 2a654fd7..2a654fd7 100644
--- a/docs/configuration/firewall/ipv4.rst
+++ b/docs/configuration/firewall/rst-ipv4.rst
diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/rst-ipv6.rst
index 19df996a..19df996a 100644
--- a/docs/configuration/firewall/ipv6.rst
+++ b/docs/configuration/firewall/rst-ipv6.rst
diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/rst-zone.rst
index 059b029d..059b029d 100644
--- a/docs/configuration/firewall/zone.rst
+++ b/docs/configuration/firewall/rst-zone.rst
diff --git a/docs/configuration/firewall/zone.md b/docs/configuration/firewall/zone.md
new file mode 100644
index 00000000..40ffd4b4
--- /dev/null
+++ b/docs/configuration/firewall/zone.md
@@ -0,0 +1,177 @@
+---
+lastproofread: '2023-11-01'
+---
+
+(firewall-zone)=
+
+# Zone Based Firewall
+
+## Overview
+
+:::{note}
+Starting from VyOS 1.4-rolling-202308040557, a new firewall
+structure can be found on all vyos instalations. Zone based firewall was
+removed in that version, but re introduced in VyOS 1.4 and 1.5. All
+versions built after 2023-10-22 has this feature.
+Documentation for most of the new firewall CLI can be
+found in the [firewall](https://docs.vyos.io/en/latest/configuration/firewall/general.html)
+chapter. The legacy firewall is still available for versions before
+1.4-rolling-202308040557 and can be found in the
+{doc}`legacy firewall configuration </configuration/firewall/general-legacy>`
+chapter.
+:::
+
+In this section there's useful information of all firewall configuration that
+is needed for zone-based firewall.
+Configuration commands covered in this section:
+
+```{eval-rst}
+.. cfgcmd:: set firewall zone ...
+```
+
+From 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
+    * zone
+         - custom_zone_name
+            + ...
+```
+
+In zone-based policy, interfaces are assigned to zones, and inspection policy
+is applied to traffic moving between the zones and acted on according to
+firewall 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 traffic is subjected to policy restrictions as it crosses to
+another region of a network.
+
+Key Points:
+
+- A zone must be configured before an interface is assigned to it and an
+  interface can be assigned to only a single zone.
+- All traffic to and from an interface within a zone is permitted.
+- All traffic between zones is affected by existing policies
+- Traffic cannot flow between zone member interface and any interface that is
+  not a zone member.
+- You need 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, a zone-based
+firewall can be created to simplify configuration when multiple interfaces
+belong to the same security zone. Instead of applying rule-sets to interfaces,
+they are applied to source zone-destination zone pairs.
+
+A basic introduction to zone-based firewalls can be found [here](https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall),
+and an example at {ref}`examples-zone-policy`.
+
+### Define a Zone
+
+To define a zone setup either one with interfaces or a local zone.
+
+```{eval-rst}
+.. cfgcmd:: set firewall zone <name> interface <interface>
+
+   Set interfaces to a zone. A zone can have multiple interfaces.
+   But an interface can only be a member in one zone.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall zone <name> local-zone
+
+   Define the zone as a local zone. A local zone has no interfaces and
+   will be applied to the router itself.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall zone <name> default-action [drop | reject]
+
+   Change the default-action with this setting.
+```
+
+```{eval-rst}
+.. cfgcmd:: set firewall zone <name> description
+
+   Set a meaningful description.
+```
+
+### Applying a Rule-Set to a Zone
+
+Before you are able to apply a rule-set to a zone you have to create the zones
+first.
+
+It helps to think of the syntax as: (see below). The 'rule-set' should be
+written from the perspective of: *Source Zone*-to->\*Destination Zone\*
+
+```{eval-rst}
+.. cfgcmd::  set firewall zone <Destination Zone> from <Source Zone>
+   firewall name <rule-set>
+```
+
+```{eval-rst}
+.. cfgcmd::  set firewall zone <name> from <name> firewall name
+   <rule-set>
+```
+
+```{eval-rst}
+.. cfgcmd::  set firewall zone <name> from <name> firewall ipv6-name
+   <rule-set>
+
+   You apply a rule-set always to a zone from an other zone, it is recommended
+   to create one rule-set for each zone pair.
+
+   .. code-block:: none
+
+      set firewall zone DMZ from LAN firewall name LANv4-to-DMZv4
+      set firewall zone LAN from DMZ firewall name DMZv4-to-LANv4
+```
+
+## Operation-mode
+
+```{eval-rst}
+.. opcmd:: show firewall zone-policy
+
+   This will show you a basic summary of zones configuration.
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show firewall zone-policy
+      Zone    Interfaces    From Zone    Firewall IPv4    Firewall IPv6
+      ------  ------------  -----------  ---------------  ---------------
+      LAN     eth1          WAN          WAN_to_LAN
+              eth2
+      LOCAL   LOCAL         LAN          LAN_to_LOCAL
+                            WAN          WAN_to_LOCAL     WAN_to_LOCAL_v6
+      WAN     eth3          LAN          LAN_to_WAN
+              eth0          LOCAL        LOCAL_to_WAN
+      vyos@vyos:~$
+```
+
+```{eval-rst}
+.. opcmd:: show firewall zone-policy zone <zone>
+
+   This will show you 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_to_WAN
+              eth0          LOCAL        LOCAL_to_WAN
+      vyos@vyos:~$ show firewall zone-policy zone LOCAL
+      Zone    Interfaces    From Zone    Firewall IPv4    Firewall IPv6
+      ------  ------------  -----------  ---------------  ---------------
+      LOCAL   LOCAL         LAN          LAN_to_LOCAL
+                            WAN          WAN_to_LOCAL     WAN_to_LOCAL_v6
+      vyos@vyos:~$
+```
diff --git a/docs/configuration/highavailability/index.md b/docs/configuration/highavailability/index.md
new file mode 100644
index 00000000..6cf6a254
--- /dev/null
+++ b/docs/configuration/highavailability/index.md
@@ -0,0 +1,491 @@
+---
+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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255>
+```
+
+```{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.
+
+### Health check scripts
+
+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:
+
+```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
+```
+
+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:
+
+```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
+```
+
+### 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:
+
+```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"
+```
+
+To know more about scripting, check the {ref}`command-scripting` section.
+
+## Virtual-server
+
+```{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
+
+```none
+set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script <path-to-script>
+```
+
+### 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
+
+```none
+set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80'
+```
+
+### 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.
+
+```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'
+```
+
+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.
+
+```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 'eth0'
+set nat source rule 100 source address '192.0.2.0/24'
+set nat source rule 100 translation address 'masquerade'
+```
+
+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/highavailability/index.rst b/docs/configuration/highavailability/rst-index.rst
index 3320874d..3320874d 100644
--- a/docs/configuration/highavailability/index.rst
+++ b/docs/configuration/highavailability/rst-index.rst
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
new file mode 100644
index 00000000..2b4aae0a
--- /dev/null
+++ b/docs/configuration/index.md
@@ -0,0 +1,24 @@
+# Configuration Guide
+
+The following structure respresent the cli structure.
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   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..ef6988e5
--- /dev/null
+++ b/docs/configuration/interfaces/bonding.md
@@ -0,0 +1,671 @@
+---
+lastproofread: '2021-06-30'
+---
+
+(bond-interface)=
+
+# Bond / Link Aggregation
+
+The bonding interface provides a method for aggregating multiple network
+interfaces into a single logical "bonded" interface, or LAG, or ether-channel,
+or port-channel. The behavior of the bonded interfaces depends upon the mode;
+generally speaking, modes provide either hot standby or load balancing services.
+Additionally, link integrity monitoring may be performed.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: bonding
+   :var1: bond0
+```
+
+### Member Interfaces
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> member interface <member>
+
+   Enslave `<member>` interface to bond `<interface>`.
+```
+
+### Bond options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> mode <802.3ad | active-backup |
+  broadcast | round-robin | transmit-load-balance | adaptive-load-balance |
+  xor-hash>
+
+   Specifies one of the bonding policies. The default is 802.3ad. Possible
+   values are:
+
+   * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation
+     groups that share the same speed and duplex settings. Utilizes all slaves
+     in the active aggregator according to the 802.3ad specification.
+
+     Slave selection for outgoing traffic is done according to the transmit
+     hash policy, which may be changed from the default simple XOR policy via
+     the {cfgcmd}`hash-policy` option, documented below.
+
+     .. note:: Not all transmit policies may be 802.3ad compliant, particularly
+        in regards to the packet misordering requirements of section 43.2.4
+        of the 802.3ad standard.
+
+   * ``active-backup`` - Active-backup policy: Only one slave in the bond is
+     active. A different slave becomes active if, and only if, the active slave
+     fails. The bond's MAC address is externally visible on only one port
+     (network adapter) to avoid confusing the switch.
+
+     When a failover occurs in active-backup mode, bonding will issue one or
+     more gratuitous ARPs on the newly active slave. One gratuitous ARP is
+     issued for the bonding master interface and each VLAN interfaces
+     configured above it, provided that the interface has at least one IP
+     address configured. Gratuitous ARPs issued for VLAN interfaces are tagged
+     with the appropriate VLAN id.
+
+     This mode provides fault tolerance. The {cfgcmd}`primary` option,
+     documented below, affects the behavior of this mode.
+
+   * ``broadcast`` - Broadcast policy: transmits everything on all slave
+     interfaces.
+
+     This mode provides fault tolerance.
+
+   * ``round-robin`` - Round-robin policy: Transmit packets in sequential
+     order from the first available slave through the last.
+
+     This mode provides load balancing and fault tolerance.
+
+   * ``transmit-load-balance`` - Adaptive transmit load balancing: channel
+     bonding that does not require any special switch support.
+
+     Incoming traffic is received by the current slave. If the receiving slave
+     fails, another slave takes over the MAC address of the failed receiving
+     slave.
+
+   * ``adaptive-load-balance`` - Adaptive load balancing: includes
+     transmit-load-balance plus receive load balancing for IPV4 traffic, and
+     does not require any special switch support. The receive load balancing
+     is achieved by ARP negotiation. The bonding driver intercepts the ARP
+     Replies sent by the local system on their way out and overwrites the
+     source hardware address with the unique hardware address of one of the
+     slaves in the bond such that different peers use different hardware
+     addresses for the server.
+
+     Receive traffic from connections created by the server is also balanced.
+     When the local system sends an ARP Request the bonding driver copies and
+     saves the peer's IP information from the ARP packet. When the ARP Reply
+     arrives from the peer, its hardware address is retrieved and the bonding
+     driver initiates an ARP reply to this peer assigning it to one of the
+     slaves in the bond. A problematic outcome of using ARP negotiation for
+     balancing is that each time that an ARP request is broadcast it uses the
+     hardware address of the bond. Hence, peers learn the hardware address
+     of the bond and the balancing of receive traffic collapses to the current
+     slave. This is handled by sending updates (ARP Replies) to all the peers
+     with their individually assigned hardware address such that the traffic
+     is redistributed. Receive traffic is also redistributed when a new slave
+     is added to the bond and when an inactive slave is re-activated. The
+     receive load is distributed sequentially (round robin) among the group
+     of highest speed slaves in the bond.
+
+     When a link is reconnected or a new slave joins the bond the receive
+     traffic is redistributed among all active slaves in the bond by initiating
+     ARP Replies with the selected MAC address to each of the clients. The
+     updelay parameter (detailed below) must be set to a value equal or greater
+     than the switch's forwarding delay so that the ARP Replies sent to the
+     peers will not be blocked by the switch.
+
+   * ``xor-hash`` - XOR policy: Transmit based on the selected transmit
+     hash policy.  The default policy is a simple [(source MAC address XOR'd
+     with destination MAC address XOR packet type ID) modulo slave count].
+     Alternate transmit policies may be selected via the {cfgcmd}`hash-policy`
+     option, described below.
+
+     This mode provides load balancing and fault tolerance.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> min-links <0-16>
+
+   Specifies the minimum number of links that must be active before asserting
+   carrier. It is similar to the Cisco EtherChannel min-links feature. This
+   allows setting the minimum number of member ports that must be up (link-up
+   state) before marking the bond device as up (carrier on). This is useful for
+   situations where higher level services such as clustering want to ensure a
+   minimum number of low bandwidth links are active before switchover.
+
+   This option only affects 802.3ad mode.
+
+   The default value is 0. This will cause the carrier to be asserted
+   (for 802.3ad mode) whenever there is an active aggregator,
+   regardless of the number of available links in that aggregator.
+
+   .. note:: Because an aggregator cannot be active without at least one
+      available link, setting this option to 0 or to 1 has the exact same
+      effect.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> lacp-rate <slow|fast>
+
+   Option specifying the rate in which we'll ask our link partner to transmit
+   LACPDU packets in 802.3ad mode.
+
+   This option only affects 802.3ad mode.
+
+   * slow: Request partner to transmit LACPDUs every 30 seconds
+
+   * fast: Request partner to transmit LACPDUs every 1 second
+
+   The default value is slow.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> system-mac <mac address>
+
+   This option allow to specifies the 802.3ad system MAC address.You can set a
+   random mac-address that can be used for these LACPDU exchanges.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> hash-policy <policy>
+
+   * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field
+     to generate the hash. The formula is
+
+     .. code-block:: none
+
+       hash = source MAC XOR destination MAC XOR packet type ID
+       slave number = hash modulo slave count
+
+     This algorithm will place all traffic to a particular network peer on
+     the same slave.
+
+     This algorithm is 802.3ad compliant.
+
+   * **layer2+3** - This policy uses a combination of layer2 and layer3
+     protocol information to generate the hash. Uses XOR of hardware MAC
+     addresses and IP addresses to generate the hash. The formula is:
+
+     .. code-block:: none
+
+       hash = source MAC XOR destination MAC XOR packet type ID
+       hash = hash XOR source IP XOR destination IP
+       hash = hash XOR (hash RSHIFT 16)
+       hash = hash XOR (hash RSHIFT 8)
+
+     And then hash is reduced modulo slave count.
+
+     If the protocol is IPv6 then the source and destination addresses are
+     first hashed using ipv6_addr_hash.
+
+     This algorithm will place all traffic to a particular network peer on the
+     same slave. For non-IP traffic, the formula is the same as for the layer2
+     transmit hash policy.
+
+     This policy is intended to provide a more balanced distribution of traffic
+     than layer2 alone, especially in environments where a layer3 gateway
+     device is required to reach most destinations.
+
+     This algorithm is 802.3ad compliant.
+
+   * **layer3+4** - This policy uses upper layer protocol information, when
+     available, to generate the hash. This allows for traffic to a particular
+     network peer to span multiple slaves, although a single connection will
+     not span multiple slaves.
+
+     The formula for unfragmented TCP and UDP packets is
+
+     .. code-block:: none
+
+       hash = source port, destination port (as in the header)
+       hash = hash XOR source IP XOR destination IP
+       hash = hash XOR (hash RSHIFT 16)
+       hash = hash XOR (hash RSHIFT 8)
+
+     And then hash is reduced modulo slave count.
+
+     If the protocol is IPv6 then the source and destination addresses are
+     first hashed using ipv6_addr_hash.
+
+     For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol
+     traffic, the source and destination port information is omitted. For
+     non-IP traffic, the formula is the same as for the layer2 transmit hash
+     policy.
+
+     This algorithm is not fully 802.3ad compliant. A single TCP or UDP
+     conversation containing both fragmented and unfragmented packets will see
+     packets striped across two interfaces. This may result in out of order
+     delivery. Most traffic types will not meet these criteria, as TCP rarely
+     fragments traffic, and most UDP traffic is not involved in extended
+     conversations. Other implementations of 802.3ad may or may not tolerate
+     this noncompliance.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> primary <interface>
+
+    An `<interface>` specifying which slave is the primary device. The specified
+    device will always be the active slave while it is available. Only when the
+    primary is off-line will alternate devices be used. This is useful when one
+    slave is preferred over another, e.g., when one slave has higher throughput
+    than another.
+
+    The primary option is only valid for active-backup, transmit-load-balance,
+    and adaptive-load-balance mode.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time>
+
+   Specifies the ARP link monitoring `<time>` in seconds.
+
+   The ARP monitor works by periodically checking the slave devices to determine
+   whether they have sent or received traffic recently (the precise criteria
+   depends upon the bonding mode, and the state of the slave). Regular traffic
+   is generated via ARP probes issued for the addresses specified by the
+   {cfgcmd}`arp-monitor target` option.
+
+   If ARP monitoring is used in an etherchannel compatible mode (modes
+   round-robin and xor-hash), the switch should be configured in a mode that
+   evenly distributes packets across all links. If the switch is configured to
+   distribute the packets in an XOR fashion, all replies from the ARP targets
+   will be received on the same link which could cause the other team members
+   to fail.
+
+   A value of 0 disables ARP monitoring. The default value is 0.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address>
+
+   Specifies the IP addresses to use as ARP monitoring peers when
+   {cfgcmd}`arp-monitor interval` option is > 0. These are the targets of the
+   ARP request sent to determine the health of the link to the targets.
+
+   Multiple target IP addresses can be specified. At least one IP address must
+   be given for ARP monitoring to function.
+
+   The maximum number of targets that can be specified is 16. The default value
+   is no IP address.
+```
+
+### VLAN
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: bonding
+   :var1: bond0
+```
+
+### Port Mirror (SPAN)
+
+```{eval-rst}
+.. cmdincludemd:: ../../_include/interface-mirror.txt
+   :var0: bondinging
+   :var1: bond1
+   :var2: eth3
+```
+
+#### EVPN Multihoming
+
+All-Active Multihoming is used for redundancy and load sharing. Servers are
+attached to two or more PEs and the links are bonded (link-aggregation).
+This group of server links is referred to as an {abbr}`ES (Ethernet Segment)`.
+
+An Ethernet Segment can be configured by specifying a system-MAC and a local
+discriminator or a complete ESINAME against the bond interface on the PE.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> evpn es-id <<1-16777215|10-byte ID>
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> evpn es-sys-mac <xx:xx:xx:xx:xx:xx>
+
+  The sys-mac and local discriminator are used for generating a 10-byte, Type-3
+  Ethernet Segment ID. ESINAME is a 10-byte, Type-0 Ethernet Segment ID -
+  "00:AA:BB:CC:DD:EE:FF:GG:HH:II".
+
+  Type-1 (EAD-per-ES and EAD-per-EVI) routes are used to advertise the locally
+  attached ESs and to learn off remote ESs in the network. Local Type-2/MAC-IP
+  routes are also advertised with a destination ESI allowing for MAC-IP syncing
+  between Ethernet Segment peers. Reference: RFC 7432, RFC 8365
+
+  EVPN-MH is intended as a replacement for MLAG or Anycast VTEPs. In multihoming
+  each PE has an unique VTEP address which requires the introduction of a new
+  dataplane construct, MAC-ECMP. Here a MAC/FDB entry can point to a list of
+  remote PEs/VTEPs.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bonding <interface> evpn es-df-pref <1-65535>
+
+  Type-4 (ESR) routes are used for Designated Forwarder (DF) election.
+  DFs forward BUM traffic received via the overlay network. This
+  implementation uses a preference based DF election specified by
+  draft-ietf-bess-evpn-pref-df.
+
+  The DF preference is configurable per-ES.
+
+  BUM traffic is rxed via the overlay by all PEs attached to a server but
+  only the DF can forward the de-capsulated traffic to the access port.
+  To accommodate that non-DF filters are installed in the dataplane to drop
+  the traffic.
+
+  Similarly traffic received from ES peers via the overlay cannot be forwarded
+  to the server. This is split-horizon-filtering with local bias.
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-evpn-uplink.txt
+   :var0: bonding
+   :var1: bond0
+```
+
+## Example
+
+The following configuration on VyOS applies to all following 3rd party vendors.
+It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with
+a per VIF IPv4 address.
+
+```none
+# Create 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 happen to run this in a virtual environment like by EVE-NG
+you need to ensure your VyOS NIC is set to use the e1000 driver. Using the
+default `virtio-net-pci` or the `vmxnet3` driver will not work. ICMP
+messages will not be properly processed. They are visible on the virtual wire
+but will not make it fully up the networking stack.
+
+You can check your NIC driver by issuing {opcmd}`show interfaces ethernet
+eth0 physical | grep -i driver`
+:::
+
+### Cisco Catalyst
+
+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 becomes present `Port-channel1`, all configuration like
+allowed VLAN interfaces, STP will happen 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
+
+For a headstart you can use the below example on how to build a bond with two
+interfaces from VyOS to a Juniper EX Switch system.
+
+```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
+
+For a headstart you can use the below example on how to build a
+bond,port-channel with two interfaces from VyOS to a Aruba/HP 2510G switch.
+
+```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
+
+When utilizing VyOS in an environment with Arista gear you can use this blue
+print as an initial setup to get an LACP bond / port-channel operational between
+those two devices.
+
+Lets assume the following topology:
+
+:::{figure} /_static/images/vyos_arista_bond_lacp.png
+: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 using EVE-NG to lab this environment ensure you are using e1000
+as the desired driver for your VyOS network interfaces. When using the
+regular virtio network driver no LACP PDUs will be sent by VyOS thus the
+port-channel will never become active!
+:::
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces bonding
+
+   Show brief interface information.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces bonding
+     Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+     Interface        IP Address                        S/L  Description
+     ---------        ----------                        ---  -----------
+     bond0            -                                 u/u  my-sw1 int 23 and 24
+     bond0.10         192.168.0.1/24                    u/u  office-net
+     bond0.100        10.10.10.1/24                     u/u  management-net
+
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces bonding <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces bonding bond5
+     bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000
+         link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff
+         inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes  packets  errors  dropped  overrun       mcast
+                  0        0       0        0        0           0
+         TX:  bytes  packets  errors  dropped  carrier  collisions
+                  0        0       0        0        0           0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces bonding <interface> detail
+
+   Show detailed information about the underlaying physical links on given
+   bond `<interface>`.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces bonding bond5 detail
+     Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011)
+
+     Bonding Mode: IEEE 802.3ad Dynamic link aggregation
+     Transmit Hash Policy: layer2 (0)
+     MII Status: down
+     MII Polling Interval (ms): 100
+     Up Delay (ms): 0
+     Down Delay (ms): 0
+
+     802.3ad info
+     LACP rate: slow
+     Min links: 0
+     Aggregator selection policy (ad_select): stable
+
+     Slave Interface: eth1
+     MII Status: down
+     Speed: Unknown
+     Duplex: Unknown
+     Link Failure Count: 0
+     Permanent HW addr: 00:50:56:bf:ef:aa
+     Slave queue ID: 0
+     Aggregator ID: 1
+     Actor Churn State: churned
+     Partner Churn State: churned
+     Actor Churned Count: 1
+     Partner Churned Count: 1
+
+     Slave Interface: eth2
+     MII Status: down
+     Speed: Unknown
+     Duplex: Unknown
+     Link Failure Count: 0
+     Permanent HW addr: 00:50:56:bf:19:26
+     Slave queue ID: 0
+     Aggregator ID: 2
+     Actor Churn State: churned
+     Partner Churn State: churned
+     Actor Churned Count: 1
+     Partner Churned Count: 1
+```
diff --git a/docs/configuration/interfaces/bridge.md b/docs/configuration/interfaces/bridge.md
new file mode 100644
index 00000000..409412c1
--- /dev/null
+++ b/docs/configuration/interfaces/bridge.md
@@ -0,0 +1,367 @@
+---
+lastproofread: '2021-06-30'
+---
+
+(bridge-interface)=
+
+# Bridge
+
+A Bridge is a way to connect two Ethernet segments together in a
+protocol independent way. Packets are forwarded based on Ethernet
+address, rather than IP address (like a router). Since forwarding is
+done at Layer 2, all protocols can go transparently through a bridge.
+The Linux bridge code implements a subset of the ANSI/IEEE 802.1d
+standard.
+
+:::{note}
+Spanning Tree Protocol is not enabled by default in VyOS.
+{ref}`stp` can be easily enabled if needed.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: bridge
+   :var1: br0
+```
+
+### Member Interfaces
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+
+   Assign `<member>` interface to bridge `<interface>`. A completion
+   helper will help you with all allowed interfaces which can be
+   bridged. This includes {ref}`ethernet-interface`,
+   {ref}`bond-interface`, {ref}`l2tpv3-interface`, {ref}`openvpn`,
+   {ref}`vxlan-interface`, {ref}`wireless-interface`,
+   {ref}`tunnel-interface` and {ref}`geneve-interface`.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+   priority <priority>
+
+   Configure individual bridge port `<priority>`.
+
+   Each bridge has a relative priority and cost. Each interface is
+   associated with a port (number) in the STP code. Each has a priority
+   and a cost, that is used to decide which is the shortest path to
+   forward a packet. The lowest cost path is always used unless the
+   other path is down. If you have multiple bridges and interfaces then
+   you may need to adjust the priorities to achieve optimum
+   performance.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+   cost <cost>
+
+   Path `<cost>` value for Spanning Tree Protocol. Each interface in a
+   bridge could have a different speed and this value is used when
+   deciding which link to use. Faster interfaces should have lower
+   costs.
+```
+
+### Bridge Options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> aging <time>
+
+   MAC address aging `<time`> in seconds (default: 300).
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> max-age <time>
+
+   Bridge maximum aging `<time>` in seconds (default: 20).
+
+   If an another bridge in the spanning tree does not send out a hello
+   packet for a long period of time, it is assumed to be dead.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> igmp querier
+
+   Enable IGMP and MLD querier.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> igmp snooping
+
+   Enable IGMP and MLD snooping.
+```
+
+(stp)=
+
+#### STP Parameter
+
+{abbr}`STP (Spanning Tree Protocol)` is a network protocol that builds a
+loop-free logical topology for Ethernet networks. The basic function of
+STP is to prevent bridge loops and the broadcast radiation that results
+from them. Spanning tree also allows a network design to include backup
+links providing fault tolerance if an active link fails.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> stp
+
+   Enable spanning tree protocol. STP is disabled by default.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay>
+
+   Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15).
+
+   The forwarding delay time is the time spent in each of the listening and
+   learning states before the Forwarding state is entered. This delay is
+   so that when a new bridge comes onto a busy network it looks at some
+   traffic before participating.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> hello-time <interval>
+
+   Spanning Tree Protocol hello advertisement `<interval>` in seconds
+   (default: 2).
+
+   Periodically, a hello packet is sent out by the Root Bridge and the
+   Designated Bridges. Hello packets are used to communicate information
+   about the topology throughout the entire Bridged Local Area Network.
+```
+
+### VLAN
+
+#### Enable VLAN-Aware Bridge
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> enable-vlan
+
+   To activate the VLAN aware bridge, you must activate this setting to use VLAN
+   settings for the bridge
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> protocol <802.1ad|802.1q>
+
+   Define used ethertype of bridge interface.
+
+   Ethertype ``0x8100`` is used for ``802.1q`` and ethertype ``0x88a8`` is used
+   for ``802.1ad``.
+
+   The default is ``802.1q``.
+```
+
+#### VLAN Options
+
+:::{note}
+It is not valid to use the `vif 1` option for VLAN aware bridges
+because VLAN aware bridges assume that all unlabeled packets belong to
+the default VLAN 1 member and that the VLAN ID of the bridge's parent
+interface is always 1
+:::
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: bridge
+   :var1: br0
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+   native-vlan <vlan-id>
+
+   Set the native VLAN ID flag of the interface. When a data packet without a
+   VLAN tag enters the port, the data packet will be forced to add a tag of a
+   specific vlan id. When the vlan id flag flows out, the tag of the vlan id
+   will be stripped
+
+   Example: Set `eth0` member port to be native VLAN 2
+
+   .. code-block:: none
+
+     set interfaces bridge br1 member interface eth0 native-vlan 2
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces bridge <interface> member interface <member>
+   allowed-vlan <vlan-id>
+
+   Allows specific VLAN IDs to pass through the bridge member interface. This
+   can either be an individual VLAN id or a range of VLAN ids delimited by a
+   hyphen.
+
+   Example: Set `eth0` member port to be allowed VLAN 4
+
+   .. code-block:: none
+
+     set interfaces bridge br1 member interface eth0 allowed-vlan 4
+
+   Example: Set `eth0` member port to be allowed VLAN 6-8
+
+   .. code-block:: none
+
+     set interfaces bridge br1 member interface eth0 allowed-vlan 6-8
+```
+
+### Port Mirror (SPAN)
+
+```{eval-rst}
+.. cmdincludemd:: ../../_include/interface-mirror.txt
+   :var0: bridge
+   :var1: br1
+   :var2: eth3
+```
+
+## Examples
+
+### Create a basic bridge
+
+Creating a bridge interface is very simple. In this example, we will
+have:
+
+- A bridge named `br100`
+- Member interfaces `eth1` and VLAN 10 on interface `eth2`
+- Enable STP
+- Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64
+
+```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
+```
+
+This results in the active 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
+```
+
+### Using VLAN aware Bridge
+
+An example of creating a VLAN-aware bridge is as follows:
+
+- A bridge named `br100`
+- The member interface `eth1` is a trunk that allows VLAN 10 to pass
+- VLAN 10 on member interface `eth2` (ACCESS mode)
+- Enable STP
+- Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64
+
+```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
+```
+
+This results in the active 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
+ }
+```
+
+### Using the operation mode command to view Bridge Information
+
+```{eval-rst}
+.. opcmd:: show bridge
+
+   The `show bridge` operational command can be used to display
+   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
+```
+
+```{eval-rst}
+.. opcmd:: show bridge <name> fdb
+
+   Show bridge `<name>` fdb displays the current forwarding table:
+
+   .. 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
+```
+
+```{eval-rst}
+.. opcmd:: show bridge <name> mdb
+
+   Show bridge `<name>` mdb displays the current multicast group membership
+   table.The table is populated by IGMP and MLD snooping in the bridge driver
+   automatically.
+
+   .. 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 bridge Media Access Control (MAC) address table
+%
+% .. code-block:: none
+%
+%   vyos@vyos:~$ show bridge br100 macs
+%   port no mac addr                is local?       ageing timer
+%     1     00:53:29:44:3b:19       yes                0.00
diff --git a/docs/configuration/interfaces/dummy.md b/docs/configuration/interfaces/dummy.md
new file mode 100644
index 00000000..246c3e7d
--- /dev/null
+++ b/docs/configuration/interfaces/dummy.md
@@ -0,0 +1,94 @@
+---
+lastproofread: '2023-01-20'
+---
+
+(dummy-interface)=
+
+# Dummy
+
+The dummy interface is really a little exotic, but rather useful nevertheless.
+Dummy interfaces are much like the {ref}`loopback-interface` interface, except
+you can have as many as you want.
+
+:::{note}
+Dummy interfaces can be used as interfaces that always stay up (in
+the same fashion to loopbacks in Cisco IOS), or for testing purposes.
+:::
+
+:::{hint}
+On systems with multiple redundant uplinks and routes,
+it's a good idea to use a dedicated address for management and dynamic routing protocols.
+However, assigning that address to a physical link is risky:
+if that link goes down, that address will become inaccessible.
+A common solution is to assign the management address to a loopback or a dummy interface
+and advertise that address via all physical links, so that it's reachable
+through any of them. Since in Linux-based systems, there can be only one loopback interface,
+it's better to use a dummy interface for that purpose, since they can be added, removed,
+and taken up and down independently.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address.txt
+   :var0: dummy
+   :var1: dum0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: dummy
+   :var1: dum0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+   :var0: dummy
+   :var1: dum0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vrf.txt
+   :var0: dummy
+   :var1: dum0
+```
+
+## Operation
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces dummy <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces dummy dum0
+     dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000
+         link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff
+         inet 172.18.254.201/32 scope global dum0
+            valid_lft forever preferred_lft forever
+         inet6 fe80::247c:8eff:febc:fcf5/64 scope link
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes    packets     errors    dropped    overrun      mcast
+                  0          0          0          0          0          0
+         TX:  bytes    packets     errors    dropped    carrier collisions
+            1369707       4267          0          0          0          0
+
+```
diff --git a/docs/configuration/interfaces/ethernet.md b/docs/configuration/interfaces/ethernet.md
new file mode 100644
index 00000000..66d388ea
--- /dev/null
+++ b/docs/configuration/interfaces/ethernet.md
@@ -0,0 +1,324 @@
+---
+lastproofread: '2023-01-20'
+---
+
+(ethernet-interface)=
+
+# Ethernet
+
+This will be the most widely used interface on a router carrying traffic to the
+real world.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: ethernet
+   :var1: eth0
+```
+
+### Ethernet options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half>
+
+   Configure physical interface duplex setting.
+
+   * auto - interface duplex setting is auto-negotiated
+   * full - always use full-duplex
+   * half - always use half-duplex
+
+   VyOS default will be `auto`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 |
+  2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000>
+
+   Configure physical interface speed setting.
+
+   * auto - interface speed is auto-negotiated
+   * 10 - 10 MBit/s
+   * 100 - 100 MBit/s
+   * 1000 - 1 GBit/s
+   * 2500 - 2.5 GBit/s
+   * 5000 - 5 GBit/s
+   * 10000 - 10 GBit/s
+   * 25000 - 25 GBit/s
+   * 40000 - 40 GBit/s
+   * 50000 - 50 GBit/s
+   * 100000 - 100 GBit/s
+
+   VyOS default will be `auto`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interface ethernet <interface> ring-buffer rx <value>
+```
+
+```{eval-rst}
+.. cfgcmd:: set interface ethernet <interface> ring-buffer tx <value>
+
+  Configures the ring buffer size of the interface.
+
+  The supported values for a specific interface can be obtained
+  with: `ethtool -g <interface>`
+
+```
+
+#### Offloading
+
+```{eval-rst}
+.. cfgcmd:: set interfaces ethernet <interface> offload <gro | gso | lro | rps |
+  sg | tso>
+
+  Enable different types of hardware offloading on the given NIC.
+
+  {abbr}`LRO (Large Receive Offload)` is a technique designed to boost the
+  efficiency of how your computer's network interface card (NIC) processes
+  incoming network traffic. Typically, network data arrives in smaller chunks
+  called packets. Processing each packet individually consumes CPU (central
+  processing unit) resources. Lots of small packets can lead to a performance
+  bottleneck. Instead of handing the CPU each packet as it comes in, LRO
+  instructs the NIC to combine multiple incoming packets into a single, larger
+  packet. This larger packet is then passed to the CPU for processing.
+
+  .. note:: Under some circumstances, LRO is known to modify the packet headers
+     of forwarded traffic, which breaks the end-to-end principle of computer
+     networking. LRO is also only able to offload TCP segments encapsulated in
+     IPv4 packets. Due to these limitations, it is recommended to use GRO
+     (Generic Receive Offload) where possible. More information on the
+     limitations of LRO can be found here: https://lwn.net/Articles/358910/
+
+  {abbr}`GSO (Generic Segmentation Offload)` is a pure software offload that is
+  meant to deal with cases where device drivers cannot perform the offloads
+  described above. What occurs in GSO is that a given skbuff will have its data
+  broken out over multiple skbuffs that have been resized to match the MSS
+  provided via skb_shinfo()->gso_size.
+
+  Before enabling any hardware segmentation offload a corresponding software
+  offload is required in GSO. Otherwise it becomes possible for a frame to be
+  re-routed between devices and end up being unable to be transmitted.
+
+  {abbr}`GRO (Generic receive offload)` is the complement to GSO. Ideally any
+  frame assembled by GRO should be segmented to create an identical sequence of
+  frames using GSO, and any sequence of frames segmented by GSO should be able
+  to be reassembled back to the original by GRO. The only exception to this is
+  IPv4 ID in the case that the DF bit is set for a given IP header. If the
+  value of the IPv4 ID is not sequentially incrementing it will be altered so
+  that it is when a frame assembled via GRO is segmented via GSO.
+
+  {abbr}`RPS (Receive Packet Steering)` is logically a software implementation
+  of {abbr}`RSS (Receive Side Scaling)`. Being in software, it is necessarily
+  called later in the datapath. Whereas RSS selects the queue and hence CPU that
+  will run the hardware interrupt handler, RPS selects the CPU to perform
+  protocol processing above the interrupt handler. This is accomplished by
+  placing the packet on the desired CPU's backlog queue and waking up the CPU
+  for processing. RPS has some advantages over RSS:
+
+  - it can be used with any NIC
+  - software filters can easily be added to hash over new protocols
+  - it does not increase hardware device interrupt rate, although it does
+    introduce inter-processor interrupts (IPIs)
+
+  .. note:: In order to use TSO/LRO with VMXNET3 adapters, the SG offloading
+     option must also be enabled.
+```
+
+#### Authentication (EAPoL)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-eapol.txt
+   :var0: ethernet
+   :var1: eth0
+```
+
+#### EVPN Multihoming
+
+Uplink/Core tracking.
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-evpn-uplink.txt
+   :var0: ethernet
+   :var1: eth0
+```
+
+### VLAN
+
+#### Regular VLANs (802.1q)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: ethernet
+   :var1: eth0
+```
+
+#### QinQ (802.1ad)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021ad.txt
+   :var0: ethernet
+   :var1: eth0
+```
+
+### Port Mirror (SPAN)
+
+```{eval-rst}
+.. cmdincludemd:: ../../_include/interface-mirror.txt
+   :var0: ethernet
+   :var1: eth1
+   :var2: eth3
+```
+
+## Operation
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces ethernet <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. 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
+```
+
+
+```{eval-rst}
+.. opcmd:: show interfaces ethernet <interface> physical
+
+   Show information about physical `<interface>`
+
+   .. 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
+```
+
+
+```{eval-rst}
+.. opcmd:: show interfaces ethernet <interface> physical offload
+
+   Show available offloading functions on given `<interface>`
+
+   .. 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
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces ethernet <interface> transceiver
+
+   Show transceiver information from plugin modules, e.g SFP+, QSFP
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces ethernet eth5 transceiver
+        Identifier              : 0x03 (SFP)
+        Extended identifier     : 0x04 (GBIC/SFP defined by 2-wire interface ID)
+        Connector               : 0x07 (LC)
+        Transceiver codes       : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00
+        Transceiver type        : Ethernet: 1000BASE-SX
+        Encoding                : 0x01 (8B/10B)
+        BR, Nominal             : 1300MBd
+        Rate identifier         : 0x00 (unspecified)
+        Length (SMF,km)         : 0km
+        Length (SMF)            : 0m
+        Length (50um)           : 550m
+        Length (62.5um)         : 270m
+        Length (Copper)         : 0m
+        Length (OM3)            : 0m
+        Laser wavelength        : 850nm
+        Vendor name             : CISCO-FINISAR
+        Vendor OUI              : 00:90:65
+        Vendor PN               : FTRJ-8519-7D-CS4
+        Vendor rev              : A
+        Option values           : 0x00 0x1a
+        Option                  : RX_LOS implemented
+        Option                  : TX_FAULT implemented
+        Option                  : TX_DISABLE implemented
+        BR margin, max          : 0%
+        BR margin, min          : 0%
+        Vendor SN               : FNS092xxxxx
+        Date code               : 0506xx
+```
diff --git a/docs/configuration/interfaces/geneve.md b/docs/configuration/interfaces/geneve.md
new file mode 100644
index 00000000..5c561fb8
--- /dev/null
+++ b/docs/configuration/interfaces/geneve.md
@@ -0,0 +1,101 @@
+---
+lastproofread: '2023-01-20'
+---
+
+(geneve-interface)=
+
+# GENEVE
+
+{abbr}`GENEVE (Generic Network Virtualization Encapsulation)` supports all of
+the capabilities of {abbr}`VXLAN (Virtual Extensible LAN)`, {abbr}`NVGRE
+(Network Virtualization using Generic Routing Encapsulation)`, and {abbr}`STT
+(Stateless Transport Tunneling)` and was designed to overcome their perceived
+limitations. Many believe GENEVE could eventually replace these earlier formats
+entirely.
+
+GENEVE is designed to support network virtualization use cases, where tunnels
+are typically established to act as a backplane between the virtual switches
+residing in hypervisors, physical switches, or middleboxes or other appliances.
+An arbitrary IP network can be used as an underlay although Clos networks - A
+technique for composing network fabrics larger than a single switch while
+maintaining non-blocking bandwidth across connection points. ECMP is used to
+divide traffic across the multiple links and switches that constitute the
+fabric. Sometimes termed "leaf and spine" or "fat tree" topologies.
+
+Geneve Header:
+
+```none
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|Ver|  Opt Len  |O|C|    Rsvd.  |          Protocol Type        |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|        Virtual Network Identifier (VNI)       |    Reserved   |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                    Variable Length Options                    |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-mac.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-mtu.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-ip.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-ipv6.txt
+  :var0: geneve
+  :var1: gnv0
+```
+
+### GENEVE options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces geneve gnv0 remote <address>
+
+   Configure GENEVE tunnel far end/remote tunnel endpoint.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces geneve gnv0 vni <vni>
+
+   {abbr}`VNI (Virtual Network Identifier)` is an identifier for a unique
+   element of a virtual network.  In many situations this may represent an L2
+   segment, however, the control plane defines the forwarding semantics of
+   decapsulated packets. The VNI MAY be used as part of ECMP forwarding
+   decisions or MAY be used as a mechanism to distinguish between overlapping
+   address spaces contained in the encapsulated packet when load balancing
+   across CPUs.
+```
diff --git a/docs/configuration/interfaces/index.md b/docs/configuration/interfaces/index.md
new file mode 100644
index 00000000..39546bae
--- /dev/null
+++ b/docs/configuration/interfaces/index.md
@@ -0,0 +1,28 @@
+# Interfaces
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   bonding
+   bridge
+   dummy
+   ethernet
+   geneve
+   l2tpv3
+   loopback
+   macsec
+   openvpn
+   wireguard
+   pppoe
+   pseudo-ethernet
+   sstp-client
+   tunnel
+   virtual-ethernet
+   vti
+   vxlan
+   wireless
+   wwan
+
+```
diff --git a/docs/configuration/interfaces/l2tpv3.md b/docs/configuration/interfaces/l2tpv3.md
new file mode 100644
index 00000000..4a4acd91
--- /dev/null
+++ b/docs/configuration/interfaces/l2tpv3.md
@@ -0,0 +1,198 @@
+---
+lastproofread: '2023-01-20'
+---
+
+```{include} /_include/need_improvement.txt
+```
+
+(l2tpv3-interface)=
+
+# L2TPv3
+
+Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that
+can be used as an alternative protocol to {ref}`mpls` for encapsulation of
+multiprotocol Layer 2 communications traffic over IP networks. Like L2TP,
+L2TPv3 provides a pseudo-wire service but is scaled to fit carrier requirements.
+
+L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version
+of the same concept, with much of the same benefit achieved at a fraction of the
+effort, at the cost of losing some technical features considered less important
+in the market.
+
+In the case of L2TPv3, the features lost are teletraffic engineering features
+considered important in MPLS. However, there is no reason these features could
+not be re-engineered in or on top of L2TPv3 in later products.
+
+The protocol overhead of L2TPv3 is also significantly bigger than MPLS.
+
+L2TPv3 is described in {rfc}`3931`.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-without-dhcp.txt
+   :var0: l2tpv3
+   :var1: l2tpeth0
+```
+
+### L2TPv3 options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces l2tpv3 <interface> encapsulation <udp | ip>
+
+  Set the encapsulation type of the tunnel. Valid values for encapsulation are:
+  udp, ip.
+
+  This defaults to UDP
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces l2tpv3 <interface> source-address <address>
+
+  Set the IP address of the local interface to be used for the tunnel.
+
+  This address must be the address of a local interface. It may be specified as
+  an IPv4 address or an IPv6 address.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces l2tpv3 <interface> remote <address>
+
+  Set the IP address of the remote peer. It may be specified as
+  an IPv4 address or an IPv6 address.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id>
+
+  Set the session id, which is a 32-bit integer value. Uniquely identifies the
+  session being created. The value used must match the peer_session_id value
+  being used at the peer.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id>
+
+  Set the peer-session-id, which is a 32-bit integer value assigned to the
+  session by the peer. The value used must match the session_id value being
+  used at the peer.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces l2tpv3 <interface> tunnel-id <id>
+
+  Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the
+  tunnel into which the session will be created.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces l2tpv3 <interface> peer-tunnel-id <id>
+
+  Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the
+  tunnel into which the session will be created.
+```
+
+## Example
+
+### Over IP
+
+```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 has to be applied to the remote side.
+
+### Over UDP
+
+UDP mode works better with NAT:
+
+- Set source-address to your local IP (LAN).
+- Add a forwarding rule matching UDP port on your internet router.
+
+```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
+}
+```
+
+To create more than one tunnel, use distinct UDP ports.
+
+### Over IPSec, L2 VPN (bridge)
+
+This is the LAN extension use case. The eth0 port of the distant VPN peers
+will be directly connected like if there was a switch between them.
+
+IPSec:
+
+```none
+set vpn ipsec authentication psk <pre-shared-name> id '%any'
+set vpn ipsec authentication psk <pre-shared-name> secret <pre-shared-key>
+set vpn ipsec interface <VPN-interface>
+set vpn ipsec esp-group test-ESP-1 lifetime '3600'
+set vpn ipsec esp-group test-ESP-1 mode 'transport'
+set vpn ipsec esp-group test-ESP-1 pfs 'enable'
+set vpn ipsec esp-group test-ESP-1 proposal 1 encryption 'aes128'
+set vpn ipsec esp-group test-ESP-1 proposal 1 hash 'sha1'
+set vpn ipsec ike-group test-IKE-1 key-exchange 'ikev1'
+set vpn ipsec ike-group test-IKE-1 lifetime '3600'
+set vpn ipsec ike-group test-IKE-1 proposal 1 dh-group '5'
+set vpn ipsec ike-group test-IKE-1 proposal 1 encryption 'aes128'
+set vpn ipsec ike-group test-IKE-1 proposal 1 hash 'sha1'
+set vpn ipsec site-to-site peer <connection-name> authentication mode 'pre-shared-secret'
+set vpn ipsec site-to-site peer <connection-name> connection-type 'initiate'
+set vpn ipsec site-to-site peer <connection-name> ike-group 'test-IKE-1'
+set vpn ipsec site-to-site peer <connection-name> ikev2-reauth 'inherit'
+set vpn ipsec site-to-site peer <connection-name> local-address <local-ip>
+set vpn ipsec site-to-site peer <connection-name> tunnel 1 esp-group 'test-ESP-1'
+set vpn ipsec site-to-site peer <connection-name> tunnel 1 protocol 'l2tp'
+```
+
+Bridge:
+
+```none
+set interfaces bridge br0 description 'L2 VPN Bridge'
+# remote side in this example:
+# set interfaces bridge br0 address '172.16.30.18/30'
+set interfaces bridge br0 address '172.16.30.17/30'
+set interfaces bridge br0 member interface eth0
+set interfaces ethernet eth0 description 'L2 VPN Physical port'
+```
+
+L2TPv3:
+
+```none
+set interfaces bridge br0 member interface 'l2tpeth0'
+set interfaces l2tpv3 l2tpeth0 description 'L2 VPN Tunnel'
+set interfaces l2tpv3 l2tpeth0 destination-port '5000'
+set interfaces l2tpv3 l2tpeth0 encapsulation 'ip'
+set interfaces l2tpv3 l2tpeth0 source-address <local-ip>
+set interfaces l2tpv3 l2tpeth0 mtu '1500'
+set interfaces l2tpv3 l2tpeth0 peer-session-id '110'
+set interfaces l2tpv3 l2tpeth0 peer-tunnel-id '10'
+set interfaces l2tpv3 l2tpeth0 remote <peer-ip>
+set interfaces l2tpv3 l2tpeth0 session-id '110'
+set interfaces l2tpv3 l2tpeth0 source-port '5000'
+set interfaces l2tpv3 l2tpeth0 tunnel-id '10'
+```
diff --git a/docs/configuration/interfaces/loopback.md b/docs/configuration/interfaces/loopback.md
new file mode 100644
index 00000000..37da5399
--- /dev/null
+++ b/docs/configuration/interfaces/loopback.md
@@ -0,0 +1,80 @@
+---
+lastproofread: '2023-01-20'
+---
+
+(loopback-interface)=
+
+# Loopback
+
+The loopback networking interface is a virtual network device implemented
+entirely in software. All traffic sent to it "loops back" and just targets
+services on your local machine.
+
+:::{note}
+There can only be one loopback `lo` interface on the system. If
+you need multiple interfaces, please use the {ref}`dummy-interface`
+interface type.
+:::
+
+:::{hint}
+A loopback interface is always up, thus it could be used for
+management traffic or as source/destination for and {abbr}`IGP (Interior
+Gateway Protocol)` like {ref}`routing-bgp` so your internal BGP link is not
+dependent on physical link states and multiple routes can be chosen to the
+destination. A {ref}`dummy-interface` Interface should always be preferred
+over a {ref}`loopback-interface` interface.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address.txt
+   :var0: loopback
+   :var1: lo
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: loopback
+   :var1: lo
+```
+
+## Operation
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces loopback lo
+
+   Show detailed information on the given loopback interface `lo`.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces loopback lo
+     lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
+         link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+         inet 127.0.0.1/8 scope host lo
+            valid_lft forever preferred_lft forever
+         inet6 ::1/128 scope host
+            valid_lft forever preferred_lft forever
+
+         RX:  bytes    packets     errors    dropped    overrun      mcast
+                300          6          0          0          0          0
+         TX:  bytes    packets     errors    dropped    carrier collisions
+                300          6          0          0          0          0
+```
diff --git a/docs/configuration/interfaces/macsec.md b/docs/configuration/interfaces/macsec.md
new file mode 100644
index 00000000..c3cd2595
--- /dev/null
+++ b/docs/configuration/interfaces/macsec.md
@@ -0,0 +1,305 @@
+---
+lastproofread: '2023-01-20'
+---
+
+(macsec-interface)=
+
+# MACsec
+
+MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in 2006.
+It defines a way to establish a protocol independent connection between two
+hosts with data confidentiality, authenticity and/or integrity, using
+GCM-AES-128. MACsec operates on the Ethernet layer and as such is a layer 2
+protocol, which means it's designed to secure traffic within a layer 2 network,
+including DHCP or ARP requests. It does not compete with other security
+solutions such as IPsec (layer 3) or TLS (layer 4), as all those solutions are
+used for their own specific use cases.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: macsec
+   :var1: macsec0
+```
+
+### MACsec options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security cipher <gcm-aes-128|gcm-aes-256>
+
+  Select cipher suite used for cryptographic operations. This setting is
+  mandatory.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security encrypt
+
+  MACsec only provides authentication by default, encryption is optional. This
+  command will enable encryption for all outgoing packets.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> source-interface <physical-source>
+
+  A physical interface is required to connect this MACsec instance to. Traffic
+  leaving this interface will now be authenticated/encrypted.
+```
+
+#### Static Keys
+
+Static {abbr}`SAK (Secure Authentication Key)` mode can be configured manually on each
+device wishing to use MACsec. Keys must be set statically on all devices for traffic
+to flow properly. Key rotation is dependent on the administrator updating all keys
+manually across connected devices. Static SAK mode can not be used with MKA.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security static key <key>
+
+  Set the device's transmit (TX) key. This key must be a hex string that is 16-bytes
+  (GCM-AES-128) or 32-bytes (GCM-AES-256).
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> mac <mac address>
+
+  Set the peer's MAC address
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> key <key>
+
+  Set the peer's key used to receive (RX) traffic
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> disable
+
+  Disable the peer configuration
+```
+
+#### Key Management
+
+{abbr}`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between
+individual peers.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security mka cak <key>
+
+  IEEE 802.1X/MACsec pre-shared key mode. This allows configuring MACsec with
+  a pre-shared key using a {abbr}`CAK (MACsec connectivity association key)` and
+  {abbr}`CKN (MACsec connectivity association name)` pair.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security mka ckn <key>
+
+  {abbr}`CKN (MACsec connectivity association name)` key
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security mka priority <priority>
+
+  The peer with lower priority will become the key server and start
+  distributing SAKs.
+```
+
+#### Replay protection
+
+```{eval-rst}
+.. cfgcmd:: set interfaces macsec <interface> security replay-window <window>
+
+  IEEE 802.1X/MACsec replay protection window. This determines a window in which
+  replay is tolerated, to allow receipt of frames that have been misordered by
+  the network.
+
+  - ``0``: No replay window, strict check
+  - ``1-4294967295``: Number of packets that could be misordered
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: run generate macsec mka cak <gcm-aes-128|gcm-aes-256>
+
+  Generate {abbr}`MKA (MACsec Key Agreement protocol)` CAK key 128 or 256 bits.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ generate macsec mka cak gcm-aes-128
+    20693b6e08bfa482703a563898c9e3ad
+```
+
+```{eval-rst}
+.. opcmd:: run generate macsec mka ckn
+
+  Generate {abbr}`MKA (MACsec Key Agreement protocol)` CAK key.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ generate macsec mka ckn
+    88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces macsec
+
+  List 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
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces macsec <interface>
+
+  Show specific MACsec interface information
+
+  .. 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
+
+- Two routers connected both via eth1 through an untrusted switch
+- R1 has 192.0.2.1/24 & 2001:db8::1/64
+- R2 has 192.0.2.2/24 & 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 the traffic in `eth1` will
+show you 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 the encryption on the link by removing `security encrypt` will show
+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.(
+```
+
+**R1 Static Key**
+
+```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 Static Key**
+
+```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 R2 mac 00:11:22:33:44:01
+set interfaces macsec macsec1 security static peer R2 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+set interfaces macsec macsec1 source-interface 'eth1'
+```
+
+## MACsec over wan
+
+MACsec is an interesting alternative to existing tunneling solutions that
+protects layer 2 by performing integrity, origin authentication, and optionally
+encryption. The typical use case is to use MACsec between hosts and access
+switches, between two hosts, or between two switches. in this example below,
+we use VXLAN and MACsec to secure the tunnel.
+
+**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.md b/docs/configuration/interfaces/openvpn.md
new file mode 100644
index 00000000..926cb42c
--- /dev/null
+++ b/docs/configuration/interfaces/openvpn.md
@@ -0,0 +1,867 @@
+---
+lastproofread: '2021-07-05'
+---
+
+(openvpn)=
+
+# OpenVPN
+
+Traditionally hardware routers implement IPsec exclusively due to relative
+ease of implementing it in hardware and insufficient CPU power for doing
+encryption in software. Since VyOS is a software router, this is less of a
+concern. OpenVPN has been widely used on UNIX platform for a long time and is
+a popular option for remote access VPN, though it's also capable of
+site-to-site connections.
+
+Advantages of OpenVPN are:
+
+- It uses a single TCP or UDP connection and does not rely on packet source
+  addresses, so it will work even through a double NAT: perfect for public
+  hotspots and such
+- It's easy to setup and offers very flexible split tunneling
+- There's a variety of client GUI frontends for any platform
+
+Disadvantages are:
+
+- It's slower than IPsec due to higher protocol overhead and the fact it runs
+  in user mode while IPsec, on Linux, is in kernel mode
+- None of the operating systems have client software installed by default
+
+In the VyOS CLI, a key point often overlooked is that rather than being
+configured using the `set vpn` stanza, OpenVPN is configured as a network
+interface using `set interfaces openvpn`.
+
+## Site-to-Site
+
+:::{figure} /_static/images/openvpn_site2site_diagram.jpg
+:::
+
+OpenVPN is popular for client-server setups, but its site-to-site mode
+remains a relatively obscure feature, and many router appliances
+still don't support it. However, it's very useful for quickly setting up
+tunnels between routers.
+
+As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates.
+
+The pre-shared key mode is deprecated and will be removed from future OpenVPN versions,
+so VyOS will have to remove support for that option as well. The reason is that using pre-shared keys
+is significantly less secure than using TLS.
+
+We'll configure OpenVPN using 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 side of the VPN will be 198.51.100.10.
+- The public IP address of the remote side of the VPN will be 203.0.113.11.
+- The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote.
+- The local site will have a subnet of 10.0.0.0/16.
+- The remote site will have a subnet of 10.1.0.0/16.
+- The official port for OpenVPN is 1194, which we reserve for client VPN; we
+  will use 1195 for site-to-site VPN.
+- The `persistent-tunnel` directive will allow us to configure tunnel-related
+  attributes, such as firewall policy as we would on any normal network
+  interface.
+- If known, the IP of the remote router can be configured using the
+  `remote-host` directive; if unknown, it can be omitted. We will assume a
+  dynamic IP for our remote router.
+
+### Setting up certificates
+
+Setting up a full-blown PKI with a CA certificate would arguably defeat the purpose
+of site-to-site OpenVPN, since its main goal is supposed to be configuration simplicity,
+compared to server setups that need to support multiple clients.
+
+However, since VyOS 1.4, it is possible to verify self-signed certificates using
+certificate fingerprints.
+
+On both sides, you need to generate a self-signed certificate, preferrably using the "ec" (elliptic curve) type.
+You can generate them by executing command `run generate pki certificate self-signed install <name>` in the configuration mode.
+Once the command is complete, it will add the certificate to the configuration session, to the `pki` subtree.
+You can then review the proposed changes and commit them.
+
+```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, you need to retrieve its SHA-256 fingerprint.
+OpenVPN only supports SHA-256 fingerprints at the moment, so you need to 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 don't matter, we use 'openvpn-local' and 'openvpn-remote' but they can be arbitrary.
+
+Repeat the procedure on the other router.
+
+### Setting up 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 rout
+```
+
+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
+```
+
+### Pre-shared keys
+
+Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use pre-shared keys.
+That option is still available but it is deprecated and will be removed in the future.
+However, if you need to set up a tunnel to an older VyOS version or a system with older OpenVPN,
+you need to still need to know how to use it.
+
+First, you need to generate a key by running `run generate pki openvpn shared-secret install <name>` from configuration mode.
+You can use any name, we will 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]
+```
+
+Then you need to install the key on the remote router:
+
+```none
+vyos@remote# set pki openvpn shared-secret s2s key <generated key string>
+```
+
+Then you need to set the key in your OpenVPN interface settings:
+
+```none
+set interfaces openvpn vtun1 shared-secret-key s2s
+```
+
+### Firewall Exceptions
+
+For the OpenVPN traffic to pass through the WAN interface, you must create a
+firewall exception.
+
+```none
+set firewall name OUTSIDE_LOCAL rule 10 action accept
+set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related'
+set firewall name OUTSIDE_LOCAL rule 10 state established enable
+set firewall name OUTSIDE_LOCAL rule 10 state related enable
+set firewall name OUTSIDE_LOCAL rule 20 action accept
+set firewall name OUTSIDE_LOCAL rule 20 description OpenVPN_IN
+set firewall name OUTSIDE_LOCAL rule 20 destination port 1195
+set firewall name OUTSIDE_LOCAL rule 20 log enable
+set firewall name OUTSIDE_LOCAL rule 20 protocol udp
+set firewall name OUTSIDE_LOCAL rule 20 source
+```
+
+You should also ensure that the OUTISDE_LOCAL firewall group is applied to the
+WAN interface and a direction (local).
+
+```none
+set firewall interface eth0 local name 'OUTSIDE-LOCAL'
+```
+
+Static Routing:
+
+Static routes can be configured referencing the tunnel interface; for example,
+the local router will use a network of 10.0.0.0/16, while the remote has a
+network of 10.1.0.0/16:
+
+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
+```
+
+The configurations above will default to using 256-bit AES in GCM mode
+for encryption (if both sides support NCP) and SHA-1 for HMAC authentication.
+SHA-1 is considered weak, but other hashing algorithms are available, as are
+encryption algorithms:
+
+For Encryption:
+
+This sets the cipher when NCP (Negotiable Crypto Parameters) is disabled or
+OpenVPN version < 2.4.0.
+
+```none
+vyos@vyos# set interfaces openvpn vtun1 encryption cipher
+Possible completions:
+  des          DES algorithm
+  3des         DES algorithm with triple encryption
+  bf128        Blowfish algorithm with 128-bit key
+  bf256        Blowfish algorithm with 256-bit key
+  aes128       AES algorithm with 128-bit key CBC
+  aes128gcm    AES algorithm with 128-bit key GCM
+  aes192       AES algorithm with 192-bit key CBC
+  aes192gcm    AES algorithm with 192-bit key GCM
+  aes256       AES algorithm with 256-bit key CBC
+  aes256gcm    AES algorithm with 256-bit key GCM
+```
+
+This sets the accepted ciphers to use when version => 2.4.0 and NCP is
+enabled (which is the default). Default NCP cipher for versions >= 2.4.0 is
+aes256gcm. The first cipher in this list is what server pushes to clients.
+
+```none
+vyos@vyos# set int open vtun0 encryption ncp-ciphers
+Possible completions:
+  des          DES algorithm
+  3des         DES algorithm with triple encryption
+  aes128       AES algorithm with 128-bit key CBC
+  aes128gcm    AES algorithm with 128-bit key GCM
+  aes192       AES algorithm with 192-bit key CBC
+  aes192gcm    AES algorithm with 192-bit key GCM
+  aes256       AES algorithm with 256-bit key CBC
+  aes256gcm    AES algorithm with 256-bit key GCM
+```
+
+For Hashing:
+
+```none
+vyos@vyos# set interfaces openvpn vtun1 hash
+Possible completions:
+  md5          MD5 algorithm
+  sha1         SHA-1 algorithm
+  sha256       SHA-256 algorithm
+  sha512       SHA-512 algorithm
+```
+
+If you change the default encryption and hashing algorithms, be sure that the
+local and remote ends have matching configurations, otherwise the tunnel will
+not come up.
+
+Firewall policy can also be applied to the tunnel interface for `local`, `in`,
+and `out` directions and functions identically to ethernet interfaces.
+
+If making use of multiple tunnels, OpenVPN must have a way to distinguish
+between different tunnels aside from the pre-shared-key. This is either by
+referencing IP address or port number. One option is to dedicate a public IP
+to each tunnel. Another option is to dedicate a port number to each tunnel
+(e.g. 1195,1196,1197...).
+
+OpenVPN status can be verified using the `show openvpn` operational commands.
+See the built-in help for a complete list of options.
+
+## Server
+
+Multi-client server is the most popular OpenVPN mode on routers. It always uses
+x.509 authentication and therefore requires a PKI setup. Refer this topic
+{ref}`configuration/pki/index:pki` to generate a CA certificate,
+a server certificate and key, a certificate revocation list, a Diffie-Hellman
+key exchange parameters file. You do not need client certificates and keys for
+the server setup.
+
+In this example we will use the most complicated case: a setup where each
+client is a router that has its own subnet (think HQ and branch offices), since
+simpler setups are subsets of it.
+
+Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and
+all client subnets belong to 10.23.0.0/20. All clients need access to the
+192.168.0.0/16 network.
+
+First we need to specify the basic settings. 1194/UDP is the default. The
+`persistent-tunnel` option is recommended, it prevents the TUN/TAP device from
+closing on connection resets or daemon reloads.
+
+:::{note}
+Using **openvpn-option -reneg-sec** can be tricky. This option is
+used to renegotiate data channel after n seconds. When used at both server
+and client, the lower value will trigger the renegotiation. If you set it to
+0 on one side of the connection (to disable it), the chosen value on the
+other side will determine when the renegotiation will occur.
+:::
+
+```none
+set interfaces openvpn vtun10 mode server
+set interfaces openvpn vtun10 local-port 1194
+set interfaces openvpn vtun10 persistent-tunnel
+set interfaces openvpn vtun10 protocol udp
+```
+
+Then we need to generate, add and specify the names of the cryptographic materials.
+Each of the install command should be applied to the configuration and commited
+before using under the openvpn interface configuration.
+
+```none
+run generate pki ca install ca-1                                # Follow the instructions to generate CA cert.
+Configure mode commands to install:
+set pki ca ca-1 certificate 'generated_cert_string'
+set pki ca ca-1 private key 'generated_private_key'
+
+run generate pki certificate sign ca-1 install srv-1            # Follow the instructions to generate server cert.
+Configure mode commands to install:
+set pki certificate srv-1 certificate 'generated_server_cert'
+set pki certificate srv-1 private key 'generated_private_key'
+
+run generate pki dh install dh-1                                # Follow the instructions to generate set of
+                                                                  Diffie-Hellman parameters.
+Generating parameters...
+Configure mode commands to install DH parameters:
+set pki dh dh-1 parameters 'generated_dh_params_set'
+
+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
+```
+
+Now we need to specify the server network settings. In all cases we need to
+specify the subnet for client tunnel endpoints. Since we want clients to access
+a specific network behind our router, we will use a push-route option for
+installing that route on clients.
+
+```none
+set interfaces openvpn vtun10 server push-route 192.168.0.0/16
+set interfaces openvpn vtun10 server subnet 10.23.1.0/24
+```
+
+Since it's a HQ and branch offices setup, we will want all clients to have
+fixed addresses and we will route traffic to specific subnets through them. We
+need configuration for each client to achieve this.
+
+:::{note}
+Clients are identified by the CN field of their x.509 certificates,
+in this example the CN is `client0`:
+:::
+
+```none
+set interfaces openvpn vtun10 server client client0 ip 10.23.1.10
+set interfaces openvpn vtun10 server client client0 subnet 10.23.2.0/25
+```
+
+OpenVPN **will not** automatically create routes in the kernel for client
+subnets when they connect and will only use client-subnet association
+internally, so we need to create a route to the 10.23.0.0/20 network ourselves:
+
+```none
+set protocols static route 10.23.0.0/20 interface vtun10
+```
+
+Additionally, each client needs a copy of ca cert and its own client key and
+cert files. The files are plaintext so they may be copied either manually from the CLI.
+Client key and cert files should be signed with the proper ca cert and generated on the
+server side.
+
+HQ's router requires the following steps to generate crypto materials for the Branch 1:
+
+```none
+run generate pki certificate sign ca-1 install branch-1            # Follow the instructions to generate client
+                                                                     cert for Branch 1
+Configure mode commands to install:
+```
+
+Branch 1's router might have the following lines:
+
+```none
+set pki ca ca-1 certificate 'generated_cert_string'                # CA cert generated on HQ router
+set pki certificate branch-1 certificate 'generated_branch_cert'   # Client cert generated and signed on HQ router
+set pki certificate branch-1 private key 'generated_private_key'   # Client cert key generated on HQ router
+
+set interfaces openvpn vtun10 tls ca-cert ca-1
+set interfaces openvpn vtun10 tls certificate branch-1
+```
+
+### Client Authentication
+
+#### LDAP
+
+Enterprise installations usually ship a kind of directory service which is used
+to have a single password store for all employees. VyOS and OpenVPN support
+using LDAP/AD as single user backend.
+
+Authentication is done by using the `openvpn-auth-ldap.so` plugin which is
+shipped with every VyOS installation. A dedicated configuration file is
+required. It is best practise to store it in `/config` to survive image
+updates
+
+```none
+set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config"
+```
+
+The required config file may look like this:
+
+```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
+
+Despite the fact that AD is a superset of LDAP
+
+```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 if the user account is enabled and can authenticate
+(against the primary group) the following snipped 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 LDAP auth OpenVPN configuration could look like the following
+example:
+
+```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
+     }
+ }
+```
+
+## Client
+
+VyOS can not only act as an OpenVPN site-to-site or server for multiple clients.
+You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client
+connecting to a VyOS OpenVPN server or any other OpenVPN server.
+
+Given the following example we have one VyOS router acting as OpenVPN server
+and another VyOS router acting as OpenVPN client. The server also pushes a
+static client IP address to the OpenVPN client. Remember, clients are identified
+using their CN attribute in the SSL certificate.
+
+(openvpn-client-server)=
+
+### Configuration
+
+#### Server Side
+
+```none
+set interfaces openvpn vtun10 encryption cipher '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.10.0.10'
+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.10.0.0/24'
+set interfaces openvpn vtun10 server topology 'subnet'
+set interfaces openvpn vtun10 tls ca-cert ca-1
+set interfaces openvpn vtun10 tls certificate srv-1
+set interfaces openvpn vtun10 tls crypt-key srv-1
+set interfaces openvpn vtun10 tls dh-params dh-1
+set interfaces openvpn vtun10 use-lzo-compression
+```
+
+(openvpn-client-client)=
+
+#### Client Side
+
+```none
+set interfaces openvpn vtun10 encryption cipher 'aes256'
+set interfaces openvpn vtun10 hash 'sha512'
+set interfaces openvpn vtun10 mode 'client'
+set interfaces openvpn vtun10 persistent-tunnel
+set interfaces openvpn vtun10 protocol 'udp'
+set interfaces openvpn vtun10 remote-host '172.18.201.10'
+set interfaces openvpn vtun10 remote-port '1194'
+set interfaces openvpn vtun10 tls ca-cert ca-1
+set interfaces openvpn vtun10 tls certificate client-1
+set interfaces openvpn vtun10 tls crypt-key client-1
+set interfaces openvpn vtun10 use-lzo-compression
+```
+
+### Options
+
+We do not have CLI nodes for every single OpenVPN option. If an option is
+missing, a feature request should be opened at [Phabricator] so all users can
+benefit from it (see {ref}`issues_features`).
+
+If you are a hacker or want to try on your own we support passing raw OpenVPN
+options to OpenVPN.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'persistent-key'
+```
+
+Will add `persistent-key` at the end of the generated OpenVPN configuration.
+Please use this only as last resort - things might break and OpenVPN won't start
+if you pass invalid options/syntax.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option
+   'push &quot;keepalive 1 10&quot;'
+```
+
+Will add `push "keepalive 1 10"` to the generated OpenVPN config file.
+
+:::{note}
+Sometimes option lines in the generated OpenVPN configuration require
+quotes. This is done through a hack on our config generator. You can pass
+quotes using the `&quot;` statement.
+:::
+
+### Server bridge
+
+In Ethernet bridging configurations, OpenVPN's server mode can be set as a
+'bridge' where the VPN tunnel encapsulates entire Ethernet frames
+(up to 1514 bytes) instead of just IP packets (up to 1500 bytes). This setup
+allows clients to transmit Layer 2 frames through the OpenVPN tunnel. Below,
+we outline a basic configuration to achieve this:
+
+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 'srv-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'
+```
+
+## Multi-factor Authentication
+
+VyOS supports multi-factor authentication (MFA) or two-factor authentication
+using Time-based One-Time Password (TOTP). Compatible with Google Authenticator
+software token, other software tokens.
+
+### MFA TOTP options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp challenge <enable | disable>
+
+  If set to enable, openvpn-otp will expect password as result of challenge/
+  response protocol.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp digits <1-65535>
+
+  Configure number of digits to use for totp hash (default: 6)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp drift <1-65535>
+
+  Configure time drift in seconds (default: 0)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp slop <1-65535>
+
+  Configure maximum allowed clock slop in seconds (default: 180)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp step <1-65535>
+
+  Configure step value for totp in seconds (default: 30)
+```
+
+### Example
+
+```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'
+```
+
+For every client in the openvpn server configuration a totp secret is created.
+To display the authentication information, use the command:
+
+```{eval-rst}
+.. cfgcmd:: show interfaces openvpn <interface> user <username> mfa <qrcode|secret|uri>
+```
+
+An example:
+
+```none
+vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode
+█████████████████████████████████████
+█████████████████████████████████████
+████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████
+████ █   █ █▀▀▄ █▀▀▀█▀██ █ █   █ ████
+████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████
+████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████
+████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████
+████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████
+████ ▄█▀▀▄▄  ▄█▀  ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████
+████▄█ ▀▄▄▄▀  ▀ ▄█ ▄ █▄█▀ █▀  █▀█████
+████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀  ▀ ▀ ▄█▀████
+████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█  █▀██▀████
+████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████
+████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀  █▄█ ██▀█████
+████ █   █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄   ████
+████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████
+████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████
+█████████████████████████████████████
+█████████████████████████████████████
+```
+
+Use the QR code to add the user account in Google authenticator application and
+on client side, use the OTP number as password.
+
+## OpenVPN Data Channel Offload (DCO)
+
+OpenVPN Data Channel Offload (DCO) enables significant performance enhancement
+in encrypted OpenVPN data processing. By minimizing context switching for each
+packet, DCO effectively reduces overhead. This optimization is achieved by
+keeping most data handling tasks within the kernel, avoiding frequent switches
+between kernel and user space for encryption and packet handling.
+
+As a result, the processing of each packet becomes more efficient, potentially
+leveraging hardware encryption offloading support available in the kernel.
+
+:::{note}
+OpenVPN DCO is not full OpenVPN features supported , is currently
+considered experimental. Furthermore, there are certain OpenVPN features and
+use cases that remain incompatible with DCO. To get a comprehensive
+understanding of the limitations associated with DCO, refer to the list of
+known limitations in the documentation.
+
+<https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features>
+:::
+
+### Enabling OpenVPN DCO
+
+DCO support is a per-tunnel option and it is not automatically enabled by
+default for new or upgraded tunnels. Existing tunnels will continue to function
+as they have in the past.
+
+DCO can be enabled for both new and existing tunnels,VyOS adds an option in each
+tunnel configuration where we can enable this function .The current best
+practice is to create a new tunnel with DCO to minimize the chance of problems
+with existing clients.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces openvpn <name> offload dco
+
+  Enable OpenVPN Data Channel Offload feature by loading the appropriate kernel
+  module.
+
+  Disabled by default - no kernel module loaded.
+
+  .. note:: Enable this feature causes an interface reset.
+
+```
+
+### Troubleshooting
+
+VyOS provides some operational commands on OpenVPN.
+
+#### Check status
+
+The following commands let you check tunnel status.
+
+```{eval-rst}
+.. opcmd:: show openvpn client
+
+   Use this command to check the tunnel status for OpenVPN client interfaces.
+```
+
+```{eval-rst}
+.. opcmd:: show openvpn server
+
+   Use this command to check the tunnel status for OpenVPN server interfaces.
+```
+
+```{eval-rst}
+.. opcmd:: show openvpn site-to-site
+
+   Use this command to check the tunnel status for OpenVPN site-to-site
+   interfaces.
+
+```
+
+#### Reset OpenVPN
+
+The following commands let you reset OpenVPN.
+
+```{eval-rst}
+.. opcmd:: reset openvpn client <text>
+
+   Use this command to reset the specified OpenVPN client.
+```
+
+```{eval-rst}
+.. opcmd:: reset openvpn interface <interface>
+
+   Use this command to reset the OpenVPN process on a specific interface.
+
+
+```
+
+```{include} /_include/common-references.txt
+```
diff --git a/docs/configuration/interfaces/pppoe.md b/docs/configuration/interfaces/pppoe.md
new file mode 100644
index 00000000..25e017f4
--- /dev/null
+++ b/docs/configuration/interfaces/pppoe.md
@@ -0,0 +1,443 @@
+---
+lastproofread: '2022-07-27'
+---
+
+(pppoe-interface)=
+
+# PPPoE
+
+{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol
+for encapsulating PPP frames inside Ethernet frames. It appeared in 1999,
+in the context of the boom of DSL as the solution for tunneling packets
+over the DSL connection to the {abbr}`ISPs (Internet Service Providers)`
+IP network, and from there to the rest of the Internet. A 2005 networking
+book noted that "Most DSL providers use PPPoE, which provides authentication,
+encryption, and compression." Typical use of PPPoE involves leveraging the
+PPP facilities for authenticating the user with a username and password,
+predominately via the PAP protocol and less often via CHAP.
+
+## Operating Modes
+
+VyOS supports setting up PPPoE in two different ways to a PPPoE internet
+connection. This is because most ISPs provide a modem that is also a wireless
+router.
+
+### Home Users
+
+In this method, the DSL Modem/Router connects to the ISP for you with your
+credentials preprogrammed into the device. This gives you an {rfc}`1918`
+address, such as `192.168.1.0/24` by default.
+
+For a simple home network using just the ISP's equipment, this is usually
+desirable. But if you want to run VyOS as your firewall and router, this
+will result in having a double NAT and firewall setup. This results in a
+few extra layers of complexity, particularly if you use some NAT or
+tunnel features.
+
+### Business Users
+
+In order to have full control and make use of multiple static public IP
+addresses, your VyOS will have to initiate the PPPoE connection and control
+it. In order for this method to work, you will have to figure out how to make
+your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL
+Transceiver device to connect between the Ethernet link of your VyOS and the
+phone cable. Once your DSL Transceiver is in Bridge Mode, you should get no
+IP address from it. Please make sure you connect to the Ethernet Port 1 if
+your DSL Transceiver has a switch, as some of them only work this way.
+
+Once you have an Ethernet device connected, i.e. `eth0`, then you can
+configure it to open the PPPoE session for you and your DSL Transceiver
+(Modem/Router) just acts to translate your messages in a way that
+vDSL/aDSL understands.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: pppoe
+   :var1: pppoe0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+   :var0: pppoe
+   :var1: pppoe0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-mtu.txt
+   :var0: pppoe
+   :var1: pppoe0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vrf.txt
+   :var0: pppoe
+   :var1: pppoe0
+```
+
+### PPPoE options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name>
+
+   Use this command to restrict the PPPoE session on a given access
+   concentrator. Normally, a host sends a PPPoE initiation packet to start the
+   PPPoE discovery process, a number of access concentrators respond with offer
+   packets and the host selects one of the responding access concentrators to
+   serve this session.
+
+   This command allows you to select a specific access concentrator when you
+   know the access concentrators `<name>`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> authentication username <username>
+
+   Use this command to set the username for authenticating with a remote PPPoE
+   endpoint. Authentication is optional from the system's point of view but
+   most service providers require it.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> authentication password <password>
+
+   Use this command to set the password for authenticating with a remote PPPoE
+   endpoint. Authentication is optional from the system's point of view but
+   most service providers require it.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> connect-on-demand
+
+   When set the interface is enabled for "dial-on-demand".
+
+   Use this command to instruct the system to establish a PPPoE connection
+   automatically once traffic passes through the interface. A disabled on-demand
+   connection is established at boot time and remains up. If the link fails for
+   any reason, the link is brought back up immediately.
+
+   Enabled on-demand PPPoE connections bring up the link only when traffic needs
+   to pass this link.  If the link fails for any reason, the link is brought
+   back up automatically once traffic passes the interface again. If you
+   configure an on-demand PPPoE connection, you must also configure the idle
+   timeout period, after which an idle PPPoE link will be disconnected. A
+   non-zero idle timeout will never disconnect the link after it first came up.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> no-default-route
+
+   Only request an address from the PPPoE server but do not install any default
+   route.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces pppoe pppoe0 no-default-route
+
+   .. note:: This command got added in VyOS 1.4 and inverts the logic from the old
+     ``default-route`` CLI option.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> default-route-distance <distance>
+
+   Set the distance for the default gateway sent by the PPPoE server.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces pppoe pppoe0 default-route-distance 220
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> mru <mru>
+
+   Set the {abbr}`MRU (Maximum Receive Unit)` to `mru`. PPPd will ask the peer to
+   send packets of no more than `mru` bytes. The value of `mru` must be between 128
+   and 16384.
+
+   A value of 296 works well on very slow links (40 bytes for TCP/IP header + 256
+   bytes of data).
+
+   The default is 1492.
+
+   .. note:: When using the IPv6 protocol, MRU must be at least 1280 bytes.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time>
+
+   Use this command to set the idle timeout interval to be used with on-demand
+   PPPoE sessions. When an on-demand connection is established, the link is
+   brought up only when traffic is sent and is disabled when the link is idle
+   for the interval specified.
+
+   If this parameter is not set or 0, an on-demand link will not be taken down
+   when it is idle and after the initial establishment of the connection. It
+   will stay up forever.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> holdoff <time>
+
+   Use this command to set re-dial delay time to be used with persist PPPoE
+   sessions. When the PPPoE session is terminated by peer, and on-demand
+   option is not set, the router will attempt to re-establish the PPPoE link.
+
+   If this parameter is not set, the default holdoff time is 30 seconds.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> local-address <address>
+
+   Use this command to set the IP address of the local endpoint of a PPPoE
+   session. If it is not set it will be negotiated.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> no-peer-dns
+
+   Use this command to not install advertised DNS nameservers into the local
+   system.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> remote-address <address>
+
+   Use this command to set the IP address of the remote endpoint of a PPPoE
+   session. If it is not set it will be negotiated.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> service-name <name>
+
+   Use this command to specify a service name by which the local PPPoE interface
+   can select access concentrators to connect with. It will connect to any
+   access concentrator if not set.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> source-interface <source-interface>
+
+   Use this command to link the PPPoE connection to a physical interface. Each
+   PPPoE connection must be established over a physical interface. Interfaces
+   can be regular Ethernet interfaces, VIFs or bonding interfaces/VIFs.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ip adjust-mss <mss | clamp-mss-to-pmtu>
+
+  As Internet wide PMTU discovery rarely works, we sometimes need to clamp our
+  TCP MSS value to a specific value. This is a field in the TCP options part of
+  a SYN packet. By setting the MSS value, you are telling the remote side
+  unequivocally 'do not try to send me packets bigger than this value'.
+
+  .. note:: This command was introduced in VyOS 1.4 - it was previously called:
+    ``set firewall options interface <name> adjust-mss <value>``
+
+  .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in
+    1452 bytes on a 1492 byte MTU.
+
+  Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to
+  automatically set the proper value.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ip disable-forwarding
+
+  Configure interface-specific Host/Router behaviour. If set, the interface will
+  switch to host mode and IPv6 forwarding will be disabled on this interface.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ip source-validation <strict | loose | disable>
+
+  Enable policy for source validation by reversed path, as specified in
+  {rfc}`3704`. Current recommended practice in {rfc}`3704` is to enable strict
+  mode to prevent IP spoofing from DDos attacks. If using asymmetric routing
+  or other complicated routing, then loose mode is recommended.
+
+  - strict: Each incoming packet is tested against the FIB and if the interface
+    is not the best reverse path the packet check will fail. By default failed
+    packets are discarded.
+
+  - loose: Each incoming packet's source address is also tested against the FIB
+    and if the source address is not reachable via any interface the packet
+    check will fail.
+
+  - disable: No source validation
+```
+
+#### IPv6
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ipv6 address autoconf
+
+   Use this command to enable acquisition of IPv6 address using stateless
+   autoconfig (SLAAC).
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ipv6 adjust-mss <mss | clamp-mss-to-pmtu>
+
+  As Internet wide PMTU discovery rarely works, we sometimes need to clamp our
+  TCP MSS value to a specific value. This is a field in the TCP options part of
+  a SYN packet. By setting the MSS value, you are telling the remote side
+  unequivocally 'do not try to send me packets bigger than this value'.
+
+  .. note:: This command was introduced in VyOS 1.4 - it was previously called:
+    ``set firewall options interface <name> adjust-mss <value>``
+
+  .. hint:: MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in
+    1432 bytes on a 1492 byte MTU.
+
+  Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to
+  automatically set the proper value.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pppoe <interface> ipv6 disable-forwarding
+
+  Configure interface-specific Host/Router behaviour. If set, the interface will
+  switch to host mode and IPv6 forwarding will be disabled on this interface.
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-dhcpv6-prefix-delegation.txt
+  :var0: pppoe
+  :var1: pppoe0
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces pppoe <interface>
+
+   Show detailed information on given `<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
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces pppoe <interface> queue
+
+   Displays queue information for a 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
+
+```{eval-rst}
+.. opcmd:: disconnect interface <interface>
+
+   Test disconnecting given connection-oriented interface. `<interface>` can be
+   ``pppoe0`` as the example.
+```
+
+```{eval-rst}
+.. opcmd:: connect interface <interface>
+
+   Test connecting given connection-oriented interface. `<interface>` can be
+   ``pppoe0`` as the example.
+```
+
+## Example
+
+Requirements:
+
+- Your ISPs modem is connected to port `eth0` of your VyOS box.
+- No VLAN tagging required by your ISP.
+- You need your PPPoE credentials from your DSL ISP in order to configure
+  this. The usual username is in the form of <mailto:name@host.net> but may vary
+  depending on ISP.
+- The largest MTU size you can use with DSL is 1492 due to PPPoE overhead.
+  If you are switching from a DHCP based ISP like cable then be aware that
+  things like VPN links may need to have their MTU sizes adjusted to work
+  within this limit.
+- With the `name-server` option set to `none`, VyOS will ignore the
+  nameservers your ISP sends you and thus you can fully rely on the ones you
+  have configured statically.
+
+:::{note}
+Syntax has changed from VyOS 1.2 (crux) and it will be automatically
+migrated during an upgrade.
+
+A default route is automatically installed once the interface is up.
+To change this behavior use the `no-default-route` CLI option.
+:::
+
+```none
+set interfaces pppoe pppoe0 authentication username 'userid'
+set interfaces pppoe pppoe0 authentication password 'secret'
+set interfaces pppoe pppoe0 source-interface 'eth0'
+```
+
+You should add a firewall to your configuration above as well by
+assigning it to the pppoe0 itself as shown here:
+
+```none
+set firewall interface pppoe0 in name NET-IN
+set firewall interface pppoe0 local name NET-LOCAL
+set firewall interface pppoe0 out name NET-OUT
+```
+
+### VLAN Example
+
+Some recent ISPs require you to build the PPPoE connection through a VLAN
+interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS
+can easily create a PPPoE session through an encapsulated VLAN interface.
+The following configuration will run your PPPoE connection through VLAN7
+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-PD Example
+
+
+The following configuration will setup a PPPoE session source from eth1 and
+assign a /64 prefix out of a /56 delegation (requested from the ISP) to eth0.
+The IPv6 address assigned to eth0 will be \<prefix>::1/64. If you do not know
+the prefix size delegated to you, start with sla-len 0.
+
+In addition we setup IPv6 {abbr}`RA (Router Advertisements)` to make the
+prefix known on the eth0 link.
+
+
+```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..641bc8fb
--- /dev/null
+++ b/docs/configuration/interfaces/pseudo-ethernet.md
@@ -0,0 +1,68 @@
+---
+lastproofread: '2023-01-26'
+---
+
+(pseudo-ethernet-interface)=
+
+# MACVLAN - Pseudo Ethernet
+
+Pseudo-Ethernet or MACVLAN interfaces can be seen as subinterfaces to regular
+ethernet interfaces. Each and every subinterface is created a different media
+access control (MAC) address, for a single physical Ethernet port. Pseudo-
+Ethernet interfaces have most of their application in virtualized environments,
+
+By using Pseudo-Ethernet interfaces there will be less system overhead compared
+to running a traditional bridging approach. Pseudo-Ethernet interfaces can also
+be used to workaround the general limit of 4096 virtual LANs (VLANs) per
+physical Ethernet port, since that limit is with respect to a single MAC
+address.
+
+Every Virtual Ethernet interfaces behaves like a real Ethernet interface. They
+can have IPv4/IPv6 addresses configured, or can request addresses by DHCP/
+DHCPv6 and are associated/mapped with a real ethernet port. This also makes
+Pseudo-Ethernet interfaces interesting for testing purposes. A Pseudo-Ethernet
+device will inherit characteristics (speed, duplex, ...) from its physical
+parent (the so called link) interface.
+
+Once created in the system, Pseudo-Ethernet interfaces can be referenced in
+the exact same way as other Ethernet interfaces. Notes about using Pseudo-
+Ethernet interfaces:
+
+- Pseudo-Ethernet interfaces can not be reached from your internal host. This
+  means that you can not try to ping a Pseudo-Ethernet interface from the host
+  system on which it is defined. The ping will be lost.
+- Loopbacks occurs at the IP level the same way as for other interfaces,
+  ethernet frames are not forwarded between Pseudo-Ethernet interfaces.
+- Pseudo-Ethernet interfaces may not work in environments which expect a
+  {abbr}`NIC (Network Interface Card)` to only have a single address. This
+  applies to:
+  \- VMware machines using default settings
+  \- Network switches with security settings allowing only a single MAC address
+  \- xDSL modems that try to learn the MAC address of the NIC
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: pseudo-ethernet
+   :var1: peth0
+```
+
+### Pseudo Ethernet/MACVLAN options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX>
+
+   Specifies the physical `<ethX>` Ethernet interface associated with a Pseudo
+   Ethernet `<interface>`.
+```
+
+### VLAN
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: pseudo-ethernet
+   :var1: peth0
+```
diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/rst-bonding.rst
index 27f1bbed..27f1bbed 100644
--- a/docs/configuration/interfaces/bonding.rst
+++ b/docs/configuration/interfaces/rst-bonding.rst
diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/rst-bridge.rst
index e69a6e26..e69a6e26 100644
--- a/docs/configuration/interfaces/bridge.rst
+++ b/docs/configuration/interfaces/rst-bridge.rst
diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/rst-dummy.rst
index 945361c2..945361c2 100644
--- a/docs/configuration/interfaces/dummy.rst
+++ b/docs/configuration/interfaces/rst-dummy.rst
diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/rst-ethernet.rst
index 30a13b5b..30a13b5b 100644
--- a/docs/configuration/interfaces/ethernet.rst
+++ b/docs/configuration/interfaces/rst-ethernet.rst
diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/rst-geneve.rst
index 1e8b8096..1e8b8096 100644
--- a/docs/configuration/interfaces/geneve.rst
+++ b/docs/configuration/interfaces/rst-geneve.rst
diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/rst-index.rst
index 0f02d1e3..0f02d1e3 100644
--- a/docs/configuration/interfaces/index.rst
+++ b/docs/configuration/interfaces/rst-index.rst
diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/rst-l2tpv3.rst
index 4fa47199..4fa47199 100644
--- a/docs/configuration/interfaces/l2tpv3.rst
+++ b/docs/configuration/interfaces/rst-l2tpv3.rst
diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/rst-loopback.rst
index b5fbdf83..b5fbdf83 100644
--- a/docs/configuration/interfaces/loopback.rst
+++ b/docs/configuration/interfaces/rst-loopback.rst
diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/rst-macsec.rst
index 1ab7f361..1ab7f361 100644
--- a/docs/configuration/interfaces/macsec.rst
+++ b/docs/configuration/interfaces/rst-macsec.rst
diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/rst-openvpn.rst
index 76d44ed5..76d44ed5 100644
--- a/docs/configuration/interfaces/openvpn.rst
+++ b/docs/configuration/interfaces/rst-openvpn.rst
diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/rst-pppoe.rst
index 65081e1c..65081e1c 100644
--- a/docs/configuration/interfaces/pppoe.rst
+++ b/docs/configuration/interfaces/rst-pppoe.rst
diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/rst-pseudo-ethernet.rst
index 59b3581c..59b3581c 100644
--- a/docs/configuration/interfaces/pseudo-ethernet.rst
+++ b/docs/configuration/interfaces/rst-pseudo-ethernet.rst
diff --git a/docs/configuration/interfaces/sstp-client.rst b/docs/configuration/interfaces/rst-sstp-client.rst
index 27eb9c39..27eb9c39 100644
--- a/docs/configuration/interfaces/sstp-client.rst
+++ b/docs/configuration/interfaces/rst-sstp-client.rst
diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/rst-tunnel.rst
index 31539d9f..31539d9f 100644
--- a/docs/configuration/interfaces/tunnel.rst
+++ b/docs/configuration/interfaces/rst-tunnel.rst
diff --git a/docs/configuration/interfaces/virtual-ethernet.rst b/docs/configuration/interfaces/rst-virtual-ethernet.rst
index 3324feb6..3324feb6 100644
--- a/docs/configuration/interfaces/virtual-ethernet.rst
+++ b/docs/configuration/interfaces/rst-virtual-ethernet.rst
diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/rst-vti.rst
index 1704b9d1..1704b9d1 100644
--- a/docs/configuration/interfaces/vti.rst
+++ b/docs/configuration/interfaces/rst-vti.rst
diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/rst-vxlan.rst
index 831870c5..831870c5 100644
--- a/docs/configuration/interfaces/vxlan.rst
+++ b/docs/configuration/interfaces/rst-vxlan.rst
diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/rst-wireguard.rst
index a40bee01..a40bee01 100644
--- a/docs/configuration/interfaces/wireguard.rst
+++ b/docs/configuration/interfaces/rst-wireguard.rst
diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/rst-wireless.rst
index df153763..df153763 100644
--- a/docs/configuration/interfaces/wireless.rst
+++ b/docs/configuration/interfaces/rst-wireless.rst
diff --git a/docs/configuration/interfaces/wwan.rst b/docs/configuration/interfaces/rst-wwan.rst
index 76a4a3d7..76a4a3d7 100644
--- a/docs/configuration/interfaces/wwan.rst
+++ b/docs/configuration/interfaces/rst-wwan.rst
diff --git a/docs/configuration/interfaces/sstp-client.md b/docs/configuration/interfaces/sstp-client.md
new file mode 100644
index 00000000..b2c79537
--- /dev/null
+++ b/docs/configuration/interfaces/sstp-client.md
@@ -0,0 +1,173 @@
+---
+lastproofread: '2022-12-11'
+---
+
+(sstp-client-interface)=
+
+# SSTP Client
+
+{abbr}`SSTP (Secure Socket Tunneling Protocol)` is a form of {abbr}`VTP (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 (by default, port can be changed) allows SSTP to pass through
+virtually all firewalls and proxy servers except for authenticated web proxies.
+
+:::{note}
+VyOS also comes with a build in SSTP server, see {ref}`sstp`.
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: sstpc
+   :var1: sstpc0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+   :var0: sstpc
+   :var1: sstpc0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-mtu.txt
+   :var0: sstpc
+   :var1: sstpc0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vrf.txt
+   :var0: sstpc
+   :var1: sstpc0
+```
+
+### SSTP Client Options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> no-default-route
+
+   Only request an address from the SSTP server but do not install any default
+   route.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces sstpc sstpc0 no-default-route
+
+   .. note:: This command got added in VyOS 1.4 and inverts the logic from the old
+     ``default-route`` CLI option.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> default-route-distance <distance>
+
+   Set the distance for the default gateway sent by the SSTP server.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces sstpc sstpc0 default-route-distance 220
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> no-peer-dns
+
+   Use this command to not install advertised DNS nameservers into the local
+   system.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> server <address>
+
+   SSTP remote server to connect to. Can be either an IP address or FQDN.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> ip adjust-mss <mss | clamp-mss-to-pmtu>
+
+  As Internet wide PMTU discovery rarely works, we sometimes need to clamp our
+  TCP MSS value to a specific value. This is a field in the TCP options part of
+  a SYN packet. By setting the MSS value, you are telling the remote side
+  unequivocally 'do not try to send me packets bigger than this value'.
+
+  .. note:: This command was introduced in VyOS 1.4 - it was previously called:
+    ``set firewall options interface <name> adjust-mss <value>``
+
+  .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in
+    1452 bytes on a 1492 byte MTU.
+
+  Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to
+  automatically set the proper value.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> ip disable-forwarding
+
+  Configure interface-specific Host/Router behaviour. If set, the interface will
+  switch to host mode and IPv6 forwarding will be disabled on this interface.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces sstpc <interface> ip source-validation <strict | loose | disable>
+
+  Enable policy for source validation by reversed path, as specified in
+  {rfc}`3704`. Current recommended practice in {rfc}`3704` is to enable strict
+  mode to prevent IP spoofing from DDos attacks. If using asymmetric routing
+  or other complicated routing, then loose mode is recommended.
+
+  - strict: Each incoming packet is tested against the FIB and if the interface
+    is not the best reverse path the packet check will fail. By default failed
+    packets are discarded.
+
+  - loose: Each incoming packet's source address is also tested against the FIB
+    and if the source address is not reachable via any interface the packet
+    check will fail.
+
+  - disable: No source validation
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces sstpc <interface>
+
+   Show detailed information on given `<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
+
+```{eval-rst}
+.. opcmd:: disconnect interface <interface>
+
+   Test disconnecting given connection-oriented interface. `<interface>` can be
+   ``sstpc0`` as the example.
+```
+
+```{eval-rst}
+.. opcmd:: connect interface <interface>
+
+   Test connecting given connection-oriented interface. `<interface>` can be
+   ``sstpc0`` as the example.
+```
diff --git a/docs/configuration/interfaces/tunnel.md b/docs/configuration/interfaces/tunnel.md
new file mode 100644
index 00000000..7f435f8c
--- /dev/null
+++ b/docs/configuration/interfaces/tunnel.md
@@ -0,0 +1,281 @@
+---
+lastproofread: '2023-01-26'
+---
+
+(tunnel-interface)=
+
+# Tunnel
+
+This article touches on 'classic' IP tunneling protocols.
+
+GRE is often seen as a one size fits all solution when it comes to classic IP
+tunneling protocols, and for a good reason. However, there are more specialized
+options, and many of them are supported by VyOS. There are also rather obscure
+GRE options that can be useful.
+
+All those protocols are grouped under `interfaces tunnel` in VyOS. Let's take
+a closer look at the protocols and options currently supported by VyOS.
+
+## Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address.txt
+   :var0: tunnel
+   :var1: tun0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-without-mac.txt
+   :var0: tunnel
+   :var1: tun0
+```
+
+## IPIP
+
+This is one of the simplest types of tunnels, as defined by {rfc}`2003`.
+It takes an IPv4 packet and sends it as a payload of another IPv4 packet. For
+this reason, there are no other configuration options for this kind of tunnel.
+
+An 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
+
+This is the IPv6 counterpart of IPIP. I'm not aware of an RFC that defines this
+encapsulation specifically, but it's a natural specific case of IPv6
+encapsulation mechanisms described in :rfc:2473\`.
+
+It's not likely that anyone will need it any time soon, but it does exist.
+
+An 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
+
+In the future this is expected to be a very useful protocol (though there are
+[other proposals]).
+
+As the name implies, it's IPv4 encapsulated in IPv6, as simple as that.
+
+An 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 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in
+{rfc}`4213`. The 6in4 traffic is sent over IPv4 inside IPv4 packets whose IP
+headers have the IP protocol number set to 41. This protocol number is
+specifically designated for IPv6 encapsulation, the IPv4 packet header is
+immediately followed by the IPv6 packet being carried. The encapsulation
+overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of
+1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This
+tunneling technique is frequently used by IPv6 tunnel brokers like [Hurricane
+Electric][hurricane electric].
+
+An 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
+```
+
+A full example of a Tunnelbroker.net config can be found at
+{ref}`here <examples-tunnelbroker-ipv6>`.
+
+## Generic Routing Encapsulation (GRE)
+
+A GRE tunnel operates at layer 3 of the OSI model and is represented by IP
+protocol 47. The main benefit of a GRE tunnel is that you are able to carry
+multiple protocols inside the same tunnel. GRE also supports multicast traffic
+and supports routing protocols that leverage multicast to form neighbor
+adjacencies.
+
+A VyOS GRE tunnel can carry both IPv4 and IPv6 traffic and can also be created
+over either IPv4 (gre) or IPv6 (ip6gre).
+
+### Configuration
+
+A basic configuration requires a tunnel source (source-address), a tunnel
+destination (remote), an encapsulation type (gre), and an address (ipv4/ipv6).
+Below is a basic IPv4 only configuration example taken from a VyOS router and
+a Cisco IOS router. The main difference between these two configurations is
+that VyOS requires you explicitly configure the encapsulation type. The Cisco
+router defaults to GRE IP otherwise it would have to be configured as well.
+
+**VyOS Router:**
+
+```none
+set interfaces tunnel tun100 address '10.0.0.1/30'
+set interfaces tunnel tun100 encapsulation 'gre'
+set interfaces tunnel tun100 source-address '198.51.100.2'
+set interfaces tunnel tun100 remote '203.0.113.10'
+```
+
+**Cisco IOS Router:**
+
+```none
+interface Tunnel100
+ip address 10.0.0.2 255.255.255.252
+tunnel source 203.0.113.10
+tunnel destination 198.51.100.2
+```
+
+Here is a second example of a dual-stack tunnel over IPv6 between a VyOS router
+and a Linux host using 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:**
+
+This requires two files, one to create the device (XXX.netdev) and one
+to configure the network on the device (XXX.network)
+
+```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
+```
+
+### Tunnel keys
+
+GRE is also the only classic protocol that allows creating multiple tunnels
+with the same source and destination due to its support for tunnel keys.
+Despite its name, this feature has nothing to do with security: it's simply
+an identifier that allows routers to tell one tunnel from another.
+
+An 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 tun0 source-address 192.0.2.10
+set interfaces tunnel tun0 remote 192.0.2.20
+set interfaces tunnel tun0 address 172.16.17.18/24
+set interfaces tunnel tun0 parameters ip key 20
+```
+
+### GRETAP
+
+While normal GRE is for layer 3, GRETAP is for layer 2. GRETAP can encapsulate
+Ethernet frames, thus it can be bridged with other interfaces to create
+datalink layer segments that span multiple remote sites.
+
+```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 well defined standard that is common in most networks. While not
+inherently difficult to configure there are a couple of things to keep in mind
+to make sure the configuration performs as expected. A common cause for GRE
+tunnels to fail to come up correctly include ACL or Firewall configurations
+that are discarding IP protocol 47 or blocking your source/destination traffic.
+
+**1. Confirm IP connectivity between tunnel source-address and remote:**
+
+```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. Confirm the link type has been set to GRE:**
+
+```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. Confirm IP connectivity across the tunnel:**
+
+```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
+```
+
+:::{note}
+There is also a GRE over IPv6 encapsulation available, it is
+called: `ip6gre`.
+:::
+
+[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..13d3fb8f
--- /dev/null
+++ b/docs/configuration/interfaces/virtual-ethernet.md
@@ -0,0 +1,118 @@
+---
+lastproofread: '2022-11-25'
+---
+
+(virtual-ethernet)=
+
+# Virtual Ethernet
+
+The veth devices are virtual Ethernet devices. They can act as tunnels between
+network namespaces to create a bridge to a physical network device in another
+namespace or VRF, but can also be used as standalone network devices.
+
+:::{note}
+veth interfaces need to be created in pairs - it's called the peer name
+:::
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address-with-dhcp.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+### VLAN
+
+#### Regular VLANs (802.1q)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+#### QinQ (802.1ad)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021ad.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vrf.txt
+   :var0: virtual-ethernet
+   :var1: veth0
+```
+
+## Operation
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces virtual-ethernet <interface>
+
+   Show detailed information on given `<interface>`
+
+   .. 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
+
+Interconnect the global VRF with vrf "red" using the veth10 \<-> veth 11 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..f516014d
--- /dev/null
+++ b/docs/configuration/interfaces/vti.md
@@ -0,0 +1,40 @@
+(vti-interface)=
+
+# VTI - Virtual Tunnel Interface
+
+Set Virtual Tunnel Interface
+
+```none
+set interfaces vti vti0 address 192.168.2.249/30
+set interfaces vti vti0 address 2001:db8:2::249/64
+```
+
+Results in:
+
+```none
+vyos@vyos# show interfaces vti
+vti vti0 {
+    address 192.168.2.249/30
+    address 2001:db8:2::249/64
+    description "Description"
+}
+```
+
+:::{warning}
+When using site-to-site IPsec with VTI interfaces,
+be sure to disable route autoinstall
+:::
+
+```none
+set vpn ipsec options disable-route-autoinstall
+```
+
+More details about the IPsec and VTI issue and option disable-route-autoinstall
+<https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july>
+
+The root cause of the problem is that for VTI tunnels to work, their traffic
+selectors have to be set to 0.0.0.0/0 for traffic to match the tunnel, even
+though actual routing decision is made according to netfilter marks. Unless
+route insertion is disabled entirely, StrongSWAN thus mistakenly inserts a
+default route through the VTI peer address, which makes all traffic routed
+to nowhere.
diff --git a/docs/configuration/interfaces/vxlan.md b/docs/configuration/interfaces/vxlan.md
new file mode 100644
index 00000000..0eff152c
--- /dev/null
+++ b/docs/configuration/interfaces/vxlan.md
@@ -0,0 +1,366 @@
+---
+lastproofread: '2023-01-26'
+---
+
+(vxlan-interface)=
+
+# VXLAN
+
+{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology
+that attempts to address the scalability problems associated with large cloud
+computing deployments. It uses a VLAN-like encapsulation technique to
+encapsulate OSI layer 2 Ethernet frames within layer 4 UDP datagrams, using
+4789 as the default IANA-assigned destination UDP port number. VXLAN
+endpoints, which terminate VXLAN tunnels and may be either virtual or physical
+switch ports, are known as {abbr}`VTEPs (VXLAN tunnel endpoints)`.
+
+VXLAN is an evolution of efforts to standardize an overlay encapsulation
+protocol. It increases the scalability up to 16 million logical networks and
+allows for layer 2 adjacency across IP networks. Multicast or unicast with
+head-end replication (HER) is used to flood broadcast, unknown unicast,
+and multicast (BUM) traffic.
+
+The VXLAN specification was originally created by VMware, Arista Networks
+and Cisco. Other backers of the VXLAN technology include Huawei, Broadcom,
+Citrix, Pica8, Big Switch Networks, Cumulus Networks, Dell EMC, Ericsson,
+Mellanox, FreeBSD, OpenBSD, Red Hat, Joyent, and Juniper Networks.
+
+VXLAN was officially documented by the IETF in {rfc}`7348`.
+
+If configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing
+(Hyper-V) or Forged Transmits (ESX) are permitted, otherwise forwarded frames
+may be blocked by the hypervisor.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-without-dhcp.txt
+  :var0: vxlan
+  :var1: vxlan0
+```
+
+### VXLAN specific options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> vni <number>
+
+  Each VXLAN segment is identified through a 24-bit segment ID, termed the
+  {abbr}`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows
+  up to 16M VXLAN segments to coexist within the same administrative domain.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> port <port>
+
+  Configure port number of remote VXLAN endpoint.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> source-address <IP address>
+
+  Source IP address used for VXLAN underlay. This is mandatory when using VXLAN
+  via L2VPN/EVPN.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> gpe
+
+  Enables the Generic Protocol extension (VXLAN-GPE). Currently, this is only
+  supported together with the external keyword.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> parameters external
+
+  Specifies whether an external control plane (e.g. BGP L2VPN/EVPN) or the
+  internal FDB should be used.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> parameters neighbor-suppress
+
+  In order to minimize the flooding of ARP and ND messages in the VXLAN network,
+  EVPN includes provisions {rfc}`7432#section-10` that allow participating VTEPs
+  to suppress such messages in case they know the MAC-IP binding and can reply
+  on behalf of the remote host.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> parameters nolearning
+
+   Specifies if unknown source link layer addresses and IP addresses are entered
+   into the VXLAN device forwarding database.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> parameters vni-filter
+
+   Specifies whether the VXLAN device is capable of vni filtering.
+
+   Only works with a VXLAN device with external flag set.
+
+   .. note::  The device can only receive packets with VNIs configured in
+      the VNI filtering table.
+```
+
+#### Unicast
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> remote <address>
+
+  IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the
+  remote IPv4/IPv6 address can set directly.
+```
+
+#### Multicast
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface>
+
+  Interface used for VXLAN underlay. This is mandatory when using VXLAN via
+  a multicast network. VXLAN traffic will always enter and exit this interface.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> group <address>
+
+  Multicast group address for VXLAN interface. VXLAN tunnels can be built
+  either via Multicast or via Unicast.
+
+  Both IPv4 and IPv6 multicast is possible.
+```
+
+## Multicast VXLAN
+
+Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5
+
+PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in
+the same broadcast domain.
+
+Let's assume PC4 on Leaf2 wants to ping PC5 on Leaf3. Instead of setting Leaf3
+as our remote end manually, Leaf2 encapsulates the packet into a UDP-packet and
+sends it to its designated multicast-address via Spine1. When Spine1 receives
+this packet it forwards it to all other leaves who has joined the same
+multicast-group, in this case Leaf3. When Leaf3 receives the packet it forwards
+it, while at the same time learning that PC4 is reachable behind Leaf2, because
+the encapsulated packet had Leaf2's IP address set as source IP.
+
+PC5 receives the ping echo, responds with an echo reply that Leaf3 receives and
+this time forwards to Leaf2's unicast address directly because it learned the
+location of PC4 above. When Leaf2 receives the echo reply from PC5 it sees that
+it came from Leaf3 and so remembers that PC5 is reachable via Leaf3.
+
+Thanks to this discovery, any subsequent traffic between PC4 and PC5 will not
+be using the multicast-address between the leaves as they both know behind which
+Leaf the PCs are connected. This saves traffic as less multicast packets sent
+reduces the load on the network, which improves scalability when more leaves are
+added.
+
+For optimal scalability, Multicast shouldn't be used at all, but instead use BGP
+to signal all connected devices between leaves. Unfortunately, VyOS does not yet
+support this.
+
+## Single VXLAN device (SVD)
+
+FRR supports a new way of configuring VLAN-to-VNI mappings for EVPN-VXLAN, when
+working with the Linux kernel. In this new way, the mapping of a VLAN to a
+{abbr}`VNI (VXLAN Network Identifier (or VXLAN Segment ID))` is configured
+against a container VXLAN interface which is referred to as a
+{abbr}`SVD (Single VXLAN device)`.
+
+Multiple VLAN to VNI mappings can be configured against the same SVD. This
+allows for a significant scaling of the number of VNIs since a separate VXLAN
+interface is no longer required for each VNI.
+
+```{eval-rst}
+.. cfgcmd:: set interfaces vxlan <interface> vlan-to-vni <vlan> vni <vni>
+
+   Maps the VNI to the specified VLAN id. The VLAN can then be consumed by
+   a bridge.
+
+   Sample configuration of SVD with VLAN to VNI mappings is shown below.
+
+   .. 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 setup is this: Leaf2 - Spine1 - Leaf3
+
+Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a
+VyOS router running 1.2.
+
+This topology was built using GNS3.
+
+Topology:
+
+```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 the leaves to forward traffic between each
+other in a more scalable way. This also requires PIM to be enabled towards the
+leaves so that the Spine can learn what multicast groups each Leaf expects
+traffic from.
+
+**Leaf2 configuration:**
+
+```none
+set interfaces ethernet eth0 address '10.1.2.2/24'
+set protocols ospf area 0 network '10.0.0.0/8'
+
+! Our 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'
+
+! Our seconds 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'
+
+! Our 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'
+
+! Our seconds 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'
+```
+
+As you can see, Leaf2 and Leaf3 configuration is almost identical. There are
+lots of commands above, I'll try to into more detail below, command
+descriptions are placed under the command boxes:
+
+```none
+set interfaces bridge br241 address '172.16.241.1/24'
+```
+
+This commands creates a bridge that is used to bind traffic on eth1 vlan 241
+with the vxlan241-interface. The IP address is not required. It may however be
+used as a default gateway for each Leaf which allows devices on the vlan to
+reach other subnets. This requires that the subnets are redistributed by OSPF
+so that the Spine will learn how to reach it. To do this you need to change the
+OSPF network from '10.0.0.0/8' to '0.0.0.0/0' to allow 172.16/12-networks to be
+advertised.
+
+```none
+set interfaces bridge br241 member interface 'eth1.241'
+set interfaces bridge br241 member interface 'vxlan241'
+```
+
+Binds eth1.241 and vxlan241 to each other by making them both member
+interfaces of the same bridge.
+
+```none
+set interfaces vxlan vxlan241 group '239.0.0.241'
+```
+
+The multicast-group used by all leaves for this vlan extension. Has to be the
+same on all leaves that has this interface.
+
+```none
+set interfaces vxlan vxlan241 source-interface 'eth0'
+```
+
+Sets the interface to listen for multicast packets on. Could be a loopback, not
+yet tested.
+
+```none
+set interfaces vxlan vxlan241 vni '241'
+```
+
+Sets the unique id for this vxlan-interface. Not sure how it correlates with
+multicast-address.
+
+```none
+set interfaces vxlan vxlan241 port 12345
+```
+
+The destination port used for creating a VXLAN interface defaults to
+4789\. Aconfiguration directive to support a user-specified destination port
+to override that behavior is available using the above command.
+
+## Unicast VXLAN
+
+Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be
+set directly. Let's change the Multicast example from above:
+
+```none
+# leaf2 and leaf3
+delete interfaces vxlan vxlan241 group '239.0.0.241'
+delete interfaces vxlan vxlan241 source-interface 'eth0'
+
+# leaf2
+set interface vxlan vxlan241 remote 10.1.3.3
+
+# leaf3
+set interface vxlan vxlan241 remote 10.1.2.2
+```
+
+The default port udp is set to 4789.
+It can be changed with `set interface vxlan <vxlanN> port <port>`
diff --git a/docs/configuration/interfaces/wireguard.md b/docs/configuration/interfaces/wireguard.md
new file mode 100644
index 00000000..3f69a7fe
--- /dev/null
+++ b/docs/configuration/interfaces/wireguard.md
@@ -0,0 +1,434 @@
+---
+lastproofread: '2023-01-26'
+---
+
+(wireguard)=
+
+# WireGuard
+
+WireGuard is an extremely simple yet fast and modern VPN that utilizes
+state-of-the-art cryptography. See <https://www.wireguard.com> for more
+information.
+
+## Site to Site VPN
+
+This diagram corresponds with the example site to site configuration below.
+
+:::{figure} /_static/images/wireguard_site2site_diagram.jpg
+:::
+
+## Keypairs
+
+WireGuard requires the generation of a keypair, which includes a private key to
+decrypt incoming traffic, and a public key for peer(s) to encrypt traffic.
+
+### Generate Keypair
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard key-pair
+
+   It generates the keypair, which includes the public and private parts.
+   The key is not stored on the system - only a keypair is generated.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ generate pki wireguard key-pair
+     Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=
+     Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=
+```
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard key-pair install interface <interface>
+
+   Generates a keypair, which includes the public and private parts, and build
+   a configuration command to install this key to ``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 stored to CLI, use configure mode commands to install key:
+
+      set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0='
+
+      Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro='
+
+   .. note:: If this command is invoked from configure mode with the ``run``
+      prefix the key is automatically installed to the appropriate interface:
+
+      .. code-block:: none
+
+        vyos@vyos# run generate pki wireguard key-pair install interface wg10
+        "generate" CLI command executed from config session.
+        Generated private-key was imported to CLI!
+
+        Use the following command to verify: show interfaces wireguard wg10
+        Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8='
+
+        vyos@vyos# compare
+        [edit interfaces]
+        +wireguard wg10 {
+        +    private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc=
+        +}
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireguard <interface> public-key
+
+   Retrieve public key portion from configured WIreGuard interface.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ show interfaces wireguard wg01 public-key
+     EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=
+
+```
+
+#### Optional
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard preshared-key
+
+   An additional layer of symmetric-key crypto can be used on top of the
+   asymmetric crypto.
+
+   This is optional.
+
+   .. code-block:: none
+
+     vyos@vyos:~$ generate pki wireguard preshared-key
+     Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs=
+
+```
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard preshared-key install interface <interface> peer <peer>
+
+   An additional layer of symmetric-key crypto can be used on top of the
+   asymmetric crypto. This command automatically creates for you the required
+   CLI command to install this PSK for a given peer.
+
+   This is optional.
+
+   .. 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 this command is invoked from configure mode with the ``run``
+      prefix the key is automatically installed to the appropriate interface:
+
+```
+
+## Interface configuration
+
+The next step is to configure your local side as well as the policy based
+trusted destination addresses. If you only initiate a connection, the listen
+port and address/port is optional; however, if you act like a server and
+endpoints initiate the connections to your system, you need to define a port
+your clients can connect to, otherwise the port is randomly chosen and may
+make connection difficult with firewall rules, since the port may be different
+each time the system is rebooted.
+
+You will also need the public key of your peer as well as the network(s) you
+want to tunnel (allowed-ips) to configure a WireGuard tunnel. The public key
+below is always the public key from your peer, not your local one.
+
+**local side - commands**
+
+- WireGuard interface itself uses address 10.1.0.1/30
+- We only allow the 192.168.2.0/24 subnet to travel over the tunnel
+- Our remote end of the tunnel for peer `to-wg02` is reachable at 192.0.2.1
+  port 51820
+- The remote peer `to-wg02` uses XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=
+  as its public key portion
+- We listen on port 51820
+- We route all traffic for the 192.168.2.0/24 network to interface `wg01`
+
+```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
+```
+
+The last step is to define an interface route for 192.168.2.0/24 to get through
+the WireGuard interface `wg01`. Multiple IPs or networks can be defined and
+routed. The last check is allowed-ips which either prevents or allows the
+traffic.
+
+:::{warning}
+You can not assign the same allowed-ips statement to multiple
+WireGuard peers. This a design decision. For more information please
+check the [WireGuard mailing list].
+:::
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireguard <interface> private-key <private-key>
+
+  Associates the previously generated private key to a specific WireGuard
+  interface. The private key can be generate via the command
+
+  {opcmd}`generate pki wireguard key-pair`.
+
+  .. code-block:: none
+
+    set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY='
+
+  The command {opcmd}`show interfaces wireguard wg01 public-key` will then show the
+  public key, which needs to be shared with the peer.
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-per-client-thread.txt
+   :var0: wireguard
+   :var1: wg01
+```
+
+**remote side - commands**
+
+```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
+
+For the WireGuard traffic to pass through the WAN interface, you must 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
+```
+
+You should also ensure that the OUTISDE_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'
+```
+
+Assure that your firewall rules allow the traffic, in which case you have a
+working VPN using WireGuard.
+
+```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 crypto can be used on top of the
+asymmetric crypto. 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 on the local filesystem. Because it
+is a symmetric key, only you and your peer should have knowledge of
+its content. Make sure you distribute the key in a safe manner,
+
+```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 "RoadWarrior" Example
+
+With WireGuard, a Road Warrior VPN config is similar to a site-to-site
+VPN. It just lacks the `address` and `port` statements.
+
+In the following example, the IPs for the remote clients are defined in
+the peers. This allows the peers to interact with one another. In
+comparison to the site-to-site example the `persistent-keepalive`
+flag is set to 15 seconds to assure the connection is kept alive.
+This is mainly relevant if one of the peers is behind NAT and can't
+be connected to if the connection is lost. To be effective this
+value needs to 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
+        public-key F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc=
+    }
+    peer iPhone {
+        allowed-ips 10.172.24.20/32
+        allowed-ips 2001:db8:470:22::20/128
+        persistent-keepalive 15
+        public-key BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00=
+    }
+    port 2224
+    private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=
+}
+```
+
+The following is the config for the iPhone peer above. It's important to
+note that the `AllowedIPs` wildcard setting directs all IPv4 and IPv6 traffic
+through the 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 = 25
+```
+
+However, split-tunneling can be achieved by specifying the remote subnets.
+This ensures that only traffic destined for the remote site is sent over the
+tunnel. All other traffic is 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 = 25
+```
+
+## Operational Commands
+
+### Status
+
+```{eval-rst}
+.. opcmd:: show interfaces wireguard wg01 summary
+
+  Show info about the Wireguard service.
+  It also shows 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 public-key>
+      endpoint: <peer public IP>
+      allowed ips: 10.69.69.2/32
+      latest handshake: 23 hours, 45 minutes, 26 seconds ago
+      transfer: 1.26 MiB received, 6.47 MiB sent
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireguard
+
+  Get a list of all wireguard interfaces
+
+  .. code-block:: none
+
+    Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+    Interface        IP Address                        S/L  Description
+    ---------        ----------                        ---  -----------
+    wg01             10.0.0.1/24                       u/u
+
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireguard <interface>
+
+  Show general information about 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 "RoadWarrior" clients
+
+Some users tend to connect their mobile devices using WireGuard to their VyOS
+router. To ease deployment one can 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 secured connection.
+You should create the private portion on your own and only hand out the
+public key. Please keep this in mind when using this convenience feature.
+:::
+
+```{eval-rst}
+.. opcmd:: generate wireguard client-config <name> interface <interface> server
+   <ip|fqdn> address <client-ip>
+
+  Using this command, you will create a new client configuration which can
+  connect to ``interface`` on this router. The public key from the specified
+  interface is automatically extracted and embedded into the configuration.
+
+  The command also generates a configuration snipped which can be copy/pasted
+  into the VyOS CLI if needed. The supplied ``<name>`` on the CLI will become
+  the peer name in the snippet.
+
+  In addition you will specifiy the IP address or FQDN for the client where it
+  will connect to. The address parameter can be used up to two times and is used
+  to assign the clients specific IPv4 (/32) or IPv6 (/128) address.
+
+  .. figure:: /_static/images/wireguard_qrcode.jpg
+     :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..c8273737
--- /dev/null
+++ b/docs/configuration/interfaces/wireless.md
@@ -0,0 +1,698 @@
+---
+lastproofread: '2023-01-26'
+---
+
+(wireless-interface)=
+
+# WLAN/WIFI - Wireless LAN
+
+{abbr}`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless
+support (commonly referred to as Wi-Fi) by means of compatible hardware. If your
+hardware supports it, VyOS supports multiple logical wireless interfaces per
+physical device.
+
+There are three modes of operation for a wireless interface:
+
+- {abbr}`WAP (Wireless Access-Point)` provides network access to connecting
+  stations if the physical hardware supports acting as a WAP
+- A station acts as a Wi-Fi client accessing the network through an available
+  WAP
+- Monitor, the system passively monitors any kind of wireless traffic
+
+If the system detects an unconfigured wireless device, it will be automatically
+added the configuration tree, specifying any detected settings (for example,
+its MAC address) and configured to run in monitor mode.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-common-with-dhcp.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+### Wireless options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> channel <number>
+
+  Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from
+  1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid
+
+  Send empty SSID in beacons and ignore probe request frames that do not specify
+  full SSID, i.e., require stations to know SSID.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations
+
+  Disassociate stations based on excessive transmission failures or other
+  indications of connection loss.
+
+  This depends on the driver capabilities and may not be available with all
+  drivers.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> isolate-stations
+
+  Client isolation can be used to prevent low-level bridging of frames between
+  associated stations in the BSS.
+
+  By default, this bridging is allowed.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> max-stations
+
+  Maximum number of stations allowed in station table. New stations will be
+  rejected after the station table is full. IEEE 802.11 has a limit of 2007
+  different association IDs, so this number should not be larger than that.
+
+  This defaults to 2007.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection
+
+  Management Frame Protection (MFP) according to IEEE 802.11w
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac>
+
+  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
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> physical-device <device>
+
+  Wireless hardware device used as underlay radio.
+
+  This defaults to phy0.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number>
+
+  Add Power Constraint element to Beacon and Probe Response frames.
+
+  This option adds Power Constraint element when applicable and Country element
+  is added. Power Constraint element is required by Transmit Power Control.
+
+  Valid values are 0..255.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> ssid <ssid>
+
+  SSID to be used in IEEE 802.11 management frames
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> type
+   <access-point | station | monitor>
+
+  Wireless device type for this interface
+
+  * ``access-point`` - Access-point forwards packets between other nodes
+  * ``station`` - Connects to another access point
+  * ``monitor`` - Passively monitor all packets on the frequency/channel
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-per-client-thread.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+#### PPDU
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities require-hvt
+```
+
+##### HT (High Throughput) capabilities (802.11n)
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable
+
+  Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]``
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave
+
+  WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD]
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   channel-set-width <ht20 | ht40+ | ht40->
+
+  Supported channel width set.
+
+  * ``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:: There are limits on which channels can be used with HT40- and HT40+.
+    Following table shows the channels that may be available for HT40- and HT40+
+    use per IEEE 802.11n Annex J:
+
+    Depending on the location, not all of these channels may be available for
+    use!
+
+    .. 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 maybe rejected based on overlapping
+    BSSes. These changes are done automatically when hostapd is setting up the
+    40 MHz channel.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   delayed-block-ack
+
+  Enable HT-delayed Block Ack ``[DELAYED-BA]``
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40
+
+  DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]``
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield
+
+  This enables the greenfield option which sets the ``[GF]`` option
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc
+
+  Enable LDPC coding capability
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection
+
+  Enable L-SIG TXOP protection capability
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu
+   <3839 | 7935>
+
+  Maximum A-MSDU length 3839 (default) or 7935 octets
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   short-gi <20 | 40>
+
+  Short GI capabilities for 20 and 40 MHz
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht
+   smps <static | dynamic>
+
+  Spatial Multiplexing Power Save (SMPS) settings
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num>
+
+  Enable receiving PPDU using STBC (Space Time Block Coding)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx
+
+  Enable sending PPDU using STBC (Space Time Block Coding)
+```
+
+##### VHT (Very High Throughput) capabilities (802.11ac)
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count
+
+  Number of antennas on this card
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   antenna-pattern-fixed
+
+  Set if antenna pattern does not change during the lifetime of an association
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform
+  <single-user-beamformer | single-user-beamformee | multi-user-beamformer |
+  multi-user-beamformee>
+
+  Beamforming capabilities:
+
+  * ``single-user-beamformer`` - Support for operation as single user beamformer
+  * ``single-user-beamformee`` - Support for operation as single user beamformee
+  * ``multi-user-beamformer`` - Support for operation as single user beamformer
+  * ``multi-user-beamformee`` - Support for operation as single user beamformer
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   center-channel-freq <freq-1 | freq-2> <number>
+
+  VHT operating channel center frequency - center freq 1
+  (for use with 80, 80+80 and 160 modes)
+
+  VHT operating channel center frequency - center freq 2
+  (for use with the 80+80 mode)
+
+  <number> must be from 34 - 173. For 80 MHz channels it should be channel + 6.
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   channel-set-width <0 | 1 | 2 | 3>
+
+   * ``0`` - 20 or 40 MHz channel width (default)
+   * ``1`` - 80 MHz channel width
+   * ``2`` - 160 MHz channel width
+   * ``3`` - 80+80 MHz channel width
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc
+
+  Enable LDPC (Low Density Parity Check) coding capability
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht link-adaptation
+
+  VHT link adaptation capabilities
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   max-mpdu <value>
+
+  Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   max-mpdu-exp <value>
+
+  Set the maximum length of A-MPDU pre-EOF padding that the station can receive
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht
+   short-gi <80 | 160>
+
+  Short GI capabilities
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num>
+
+  Enable receiving PPDU using STBC (Space Time Block Coding)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx
+
+  Enable sending PPDU using STBC (Space Time Block Coding)
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave
+
+  Enable VHT TXOP Power Save Mode
+```
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf
+
+  Station supports receiving VHT variant HT Control field
+```
+
+### 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 interfaces wireless wlan0 type station
+set interfaces wireless wlan0 address dhcp
+set interfaces wireless wlan0 country-code de
+set interfaces wireless wlan0 ssid Test
+set interfaces wireless wlan0 security wpa passphrase '12345678'
+```
+
+Resulting in
+
+```none
+interfaces {
+  [...]
+  wireless wlan0 {
+    address dhcp
+    country-code de
+    security {
+      wpa {
+        passphrase "12345678"
+      }
+    }
+    ssid TEST
+    type station
+  }
+```
+
+### Security
+
+{abbr}`WPA (Wi-Fi Protected Access)` and WPA2 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 interfaces wireless wlan0 address '192.168.2.1/24'
+set interfaces wireless wlan0 country-code de
+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 radius server 192.168.3.10 key 'VyOSPassword'
+set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812
+```
+
+Resulting in
+
+```none
+interfaces {
+  [...]
+  wireless wlan0 {
+        address 192.168.2.1/24
+        country-code de
+        channel 1
+        mode n
+        security {
+            wpa {
+                cipher CCMP
+                mode wpa2
+                radius {
+                    server 192.168.3.10 {
+                        key 'VyOSPassword'
+                        port 1812
+                    }
+                }
+            }
+        }
+        ssid "Enterprise-TEST"
+        type access-point
+    }
+}
+```
+
+### VLAN
+
+#### Regular VLANs (802.1q)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021q.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+#### QinQ (802.1ad)
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vlan-8021ad.txt
+   :var0: wireless
+   :var1: wlan0
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless info
+```
+
+Use this command to view operational status and wireless-specific information
+about all wireless interfaces.
+
+```none
+vyos@vyos:~$ show interfaces wireless info
+Interface  Type          SSID                         Channel
+wlan0      access-point  VyOS-TEST-0                        1
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless detail
+```
+
+Use this command to view operational status and details wireless-specific
+information about all wireless interfaces.
+
+```none
+vyos@vyos:~$ show interfaces wireless detail
+wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+    link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+    inet xxx.xxx.99.254/24 scope global wlan0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link
+       valid_lft forever preferred_lft forever
+
+    RX:  bytes    packets     errors    dropped    overrun      mcast
+         66072        282          0          0          0          0
+    TX:  bytes    packets     errors    dropped    carrier collisions
+         83413        430          0          0          0          0
+
+wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+    link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+    inet xxx.xxx.100.254/24 scope global wlan0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link
+       valid_lft forever preferred_lft forever
+
+    RX:  bytes    packets     errors    dropped    overrun      mcast
+         166072      5282          0          0          0          0
+    TX:  bytes    packets     errors    dropped    carrier collisions
+         183413      5430          0          0          0          0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless <wlanX>
+```
+
+This command shows both status and statistics on the specified wireless
+interface. The wireless interface identifier can range from wlan0 to wlan999.
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0
+wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+    link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff
+    inet xxx.xxx.99.254/24 scope global wlan0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link
+       valid_lft forever preferred_lft forever
+
+    RX:  bytes    packets     errors    dropped    overrun      mcast
+         66072        282          0          0          0          0
+    TX:  bytes    packets     errors    dropped    carrier collisions
+         83413        430          0          0          0          0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless <wlanX> brief
+```
+
+This command gives a brief status overview of a specified wireless interface.
+The wireless interface identifier can range from wlan0 to wlan999.
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0 brief
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+wlan0            192.168.2.254/24                    u/u
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless <wlanX> queue
+```
+
+Use this command to view wireless interface queue information.
+The wireless interface identifier can range from wlan0 to wlan999.
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0 queue
+qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1
+ Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0)
+ rate 0bit 0pps backlog 0b 0p requeues 0
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wireless <wlanX> scan
+```
+
+This command is used to retrieve information about WAP within the range of your
+wireless interface. This command is useful on wireless interfaces configured
+in station mode.
+
+:::{note}
+Scanning is not supported on all wireless drivers and wireless
+hardware. Refer to your driver and wireless hardware documentation for
+further details.
+:::
+
+```none
+vyos@vyos:~$ show interfaces wireless wlan0 scan
+Address            SSID                          Channel  Signal (dbm)
+00:53:3b:88:6e:d8  WLAN-576405                         1  -64.00
+00:53:3b:88:6e:da  Telekom_FON                         1  -64.00
+00:53:00:f2:c2:a4  BabyView_F2C2A4                     6  -60.00
+00:53:3b:88:6e:d6  Telekom_FON                       100  -72.00
+00:53:3b:88:6e:d4  WLAN-576405                       100  -71.00
+00:53:44:a4:96:ec  KabelBox-4DC8                      56  -81.00
+00:53:d9:7a:67:c2  WLAN-741980                         1  -75.00
+00:53:7c:99:ce:76  Vodafone Homespot                   1  -86.00
+00:53:44:a4:97:21  KabelBox-4DC8                       1  -78.00
+00:53:44:a4:97:21  Vodafone Hotspot                    1  -79.00
+00:53:44:a4:97:21  Vodafone Homespot                   1  -79.00
+00:53:86:40:30:da  Telekom_FON                         1  -86.00
+00:53:7c:99:ce:76  Vodafone Hotspot                    1  -86.00
+00:53:44:46:d2:0b  Vodafone Hotspot                    1  -87.00
+```
+
+## Examples
+
+The following example creates a WAP. When configuring multiple WAP interfaces,
+you must specify unique IP addresses, channels, Network IDs commonly referred
+to as {abbr}`SSID (Service Set Identifier)`, and MAC addresses.
+
+The WAP in this example has the following characteristics:
+
+- IP address `192.168.2.1/24`
+- Network ID (SSID) `TEST`
+- WPA passphrase `12345678`
+- Use 802.11n protocol
+- Wireless channel `1`
+
+```none
+set 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'
+set interfaces wireless wlan0 country-code de
+```
+
+Resulting in
+
+```none
+interfaces {
+  [...]
+  wireless wlan0 {
+        address 192.168.2.1/24
+        channel 1
+        country-code de
+        mode n
+        security {
+            wpa {
+                cipher CCMP
+                mode wpa2
+                passphrase "12345678"
+            }
+        }
+        ssid "TEST"
+        type access-point
+    }
+}
+system {
+  [...]
+  wifi-regulatory-domain DE
+}
+```
+
+To get it to work as an access point with this configuration you will need
+to set up a DHCP server to work with that network. You can - of course - also
+bridge the Wireless interface with any configured bridge
+({ref}`bridge-interface`) on the system.
+
+(wireless-interface-intel-ax200)=
+
+### Intel AX200
+
+The Intel AX200 card does not work out of the box in AP mode, see
+<https://unix.stackexchange.com/questions/598275/intel-ax200-ap-mode>. You can
+still put this card into AP mode using the following configuration:
+
+
+```none
+set interfaces wireless wlan0 channel '1'
+set interfaces wireless wlan0 country-code 'us'
+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..ac096259
--- /dev/null
+++ b/docs/configuration/interfaces/wwan.md
@@ -0,0 +1,372 @@
+---
+lastproofread: '2023-01-27'
+---
+
+(wwan-interface)=
+
+# WWAN - Wireless Wide-Area-Network
+
+The Wireless Wide-Area-Network interface provides access (through a wireless
+modem/wwan) to wireless networks provided by various cellular providers.
+
+VyOS uses the `interfaces wwan` subsystem for configuration.
+
+## Configuration
+
+### Common interface configuration
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-address-with-dhcp.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-description.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-disable-link-detect.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-mtu.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-ip.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-ipv6.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-vrf.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+**DHCP(v6)**
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-dhcp-options.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-dhcpv6-options.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+```{eval-rst}
+.. cmdincludemd:: /_include/interface-dhcpv6-prefix-delegation.txt
+   :var0: wwan
+   :var1: wwan0
+```
+
+### WirelessModem (WWAN) options
+
+```{eval-rst}
+.. cfgcmd:: set interfaces wwan <interface> apn <apn>
+
+  Every WWAN connection requires an {abbr}`APN (Access Point Name)` which is
+  used by the client to dial into the ISPs network. This is a mandatory
+  parameter. Contact your Service Provider for correct APN.
+
+```
+
+## Operation
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface>
+
+  Show detailed information on given `<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
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> summary
+
+  Show detailed information summary on given `<interface>`
+
+  .. 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
+
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> capabilities
+
+  Show WWAN module hardware 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'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> firmware
+
+  Show WWAN module firmware.
+
+  .. 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
+
+```
+
+```{eval-rst}
+.. 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'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> imsi
+
+  Show WWAN module IMSI.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 imsi
+    IMSI: '262xxxxxxxxxxxx'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> model
+
+  Show WWAN module model.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 model
+    Model: 'MC7710'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> msisdn
+
+  Show WWAN module MSISDN.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wwan wwan0 msisdn
+    MSISDN: '4917xxxxxxxx'
+```
+
+```{eval-rst}
+.. 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'
+```
+
+```{eval-rst}
+.. opcmd:: show interfaces wwan <interface> signal
+
+  Show WWAN module signal strength.
+
+  .. 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'
+```
+
+```{eval-rst}
+.. 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 is based on a Sierra Wireless MC7710 miniPCIe card (only
+the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card
+is assembled into a {ref}`pc-engines-apu4`.
+
+```none
+set interfaces wwan wwan0 apn 'internet.telekom'
+set interfaces wwan wwan0 address 'dhcp'
+```
+
+## Supported Modules
+
+The following hardware modules have been tested successfully in an
+{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
+
+All available WWAN cards have a build in, reprogrammable firmware. Most of the
+vendors provide a regular update to the firmware used in the baseband chip.
+
+As VyOS makes use of the QMI interface to connect to the WWAN modem cards, also
+the firmware can be reprogrammed.
+
+To update the firmware, VyOS also ships the `qmi-firmware-update` binary. To
+upgrade the firmware of an e.g. Sierra Wireless MC7710 module to the firmware
+provided in the file `9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe`
+use the following command:
+
+```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/index.md b/docs/configuration/loadbalancing/index.md
new file mode 100644
index 00000000..22c34bd8
--- /dev/null
+++ b/docs/configuration/loadbalancing/index.md
@@ -0,0 +1,12 @@
+(load-balancing)=
+
+# Load-balancing
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   wan
+   reverse-proxy
+```
diff --git a/docs/configuration/loadbalancing/reverse-proxy.md b/docs/configuration/loadbalancing/reverse-proxy.md
new file mode 100644
index 00000000..d9719425
--- /dev/null
+++ b/docs/configuration/loadbalancing/reverse-proxy.md
@@ -0,0 +1,485 @@
+# Reverse-proxy
+
+```{include} /_include/need_improvement.txt
+```
+
+VyOS reverse-proxy is 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 is responsible for binding to a specific port,
+while the backend configuration determines the type of load balancing
+to be applied and specifies the real servers to be utilized.
+
+### Service
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name> listen-address
+   <address>
+
+  Set service to bind on IP address, by default listen on any IPv4 and IPv6
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name> port
+   <port>
+
+  Create service `<name>` to listen on <port>
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name> mode
+   <tcp|http>
+
+  Configure service `<name>` mode TCP or HTTP
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name> backend
+   <name>
+
+  Configure service `<name>` to use the backend <name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name> ssl
+   certificate <name>
+
+  Set SSL certificate <name> for service <name>
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name>
+  http-response-headers <header-name> value <header-value>
+
+  Set custom HTTP headers to be included in all responses
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy 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 syslog configuration section.
+
+```
+
+#### Rules
+
+Rules allow to control and route incoming traffic to specific backend based
+on predefined conditions. Rules allow to define matching criteria and
+perform action accordingly.
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule>
+   domain-name <name>
+
+  Match domain name
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule>
+   ssl <sni>
+
+  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
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule>
+   url-path <match> <url>
+
+  Allows to define URL path matching rules for a specific service.
+
+  With this command, you can specify how the URL path should be matched
+  against incoming requests.
+
+  The available options for <match> are:
+   * ``begin`` Matches the beginning of the URL path
+   * ``end`` Matches the end of the URL path.
+   * ``exact`` Requires an exactly match of the URL path
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule>
+   set backend <name>
+
+  Assign a specific backend to a rule
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy service <name> rule <rule>
+   redirect-location <url>
+
+  Redirect URL to a new location
+
+```
+
+### Backend
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> balance
+   <balance>
+
+  Load-balancing algorithms to be used for distributed requests among the
+  available servers
+
+  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
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> mode
+   <mode>
+
+  Configure backend `<name>` mode TCP or HTTP
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> server
+   <name> address <x.x.x.x>
+
+  Set the address of the backend server to which the incoming traffic will
+  be forwarded
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> server
+   <name> port <port>
+
+  Set the address of the backend port
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> server
+   <name> check
+
+  Active health check backend server
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> server
+   <name> send-proxy
+
+  Send a Proxy Protocol version 1 header (text format)
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> server
+   <name> send-proxy-v2
+
+  Send a Proxy Protocol version 2 header (binary format)
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> ssl
+   ca-certificate <ca-certificate>
+
+  Configure requests to the backend server to use SSL encryption and
+  authenticate backend against <ca-certificate>
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> ssl no-verify
+
+  Configure requests to the backend server to use SSL encryption without
+  validating server certificate
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name>
+  http-response-headers <header-name> value <header-value>
+
+  Set custom HTTP headers to be included in all responses using the backend
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy 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 syslog configuration section.
+
+```
+
+### Global
+
+Global parameters
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy global-parameters max-connections
+   <num>
+
+  Limit maximum number of connections
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy global-parameters ssl-bind-ciphers
+   <ciphers>
+
+  Limit allowed cipher algorithms used during SSL/TLS handshake
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy global-parameters tls-version-min
+   <version>
+
+  Specify the minimum required TLS version 1.2 or 1.3
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy 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 syslog configuration section.
+```
+
+## Health checks
+
+### HTTP checks
+
+For web application providing information about their state HTTP health
+checks can be used to determine their availability.
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check
+
+  Enables HTTP health checks using OPTION HTTP requests against '/' and
+  expecting a successful response code in the 200-399 range.
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check
+   method <method>
+
+  Sets the HTTP method to be used, can be either: option, get, post, put
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check
+   uri <path>
+
+  Sets the endpoint to be used for health checks
+```
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check
+   expect <condition>
+
+  Sets the expected result condition for considering a server healthy.
+
+  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
+
+Health checks can also be configured for TCP mode backends. You can configure
+protocol aware checks for a range of Layer 7 protocols:
+
+```{eval-rst}
+.. cfgcmd:: set load-balancing reverse-proxy backend <name> health-check <protocol>
+
+  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 be checked but do not configure a
+protocol, a basic TCP health check will be attempted. A server shall be
+deemed online if it responses to a connection attempt with a valid
+`SYN/ACK` packet.
+:::
+
+## Redirect HTTP to HTTPS
+
+Configure the load-balancing reverse-proxy service for HTTP.
+
+This configuration listen on port 80 and redirect incoming
+requests to HTTPS:
+
+```none
+set load-balancing reverse-proxy service http port '80'
+set load-balancing reverse-proxy service http redirect-http-to-https
+```
+
+The name of the service can be different, in this example it is only 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 will be load balanced across the backend
+servers (srv01 and srv02) using the round-robin load-balancing algorithm.
+
+```none
+set load-balancing reverse-proxy service my-tcp-api backend 'bk-01'
+set load-balancing reverse-proxy service my-tcp-api mode 'tcp'
+set load-balancing reverse-proxy service my-tcp-api port '8888'
+
+set load-balancing reverse-proxy backend bk-01 balance 'round-robin'
+set load-balancing reverse-proxy backend bk-01 mode 'tcp'
+
+set load-balancing reverse-proxy backend bk-01 server srv01 address '192.0.2.11'
+set load-balancing reverse-proxy backend bk-01 server srv01 port '8881'
+set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12'
+set load-balancing reverse-proxy 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 listen on TCP port 80.
+
+Rule 10 matches requests with the domain name `node1.example.com` forwards
+to the backend `bk-api-01`
+
+Rule 20 matches requests with the domain name `node2.example.com` forwards
+to the backend `bk-api-02`
+
+```none
+set load-balancing reverse-proxy service http description 'bind app listen on 443 port'
+set load-balancing reverse-proxy service http mode 'tcp'
+set load-balancing reverse-proxy service http port '80'
+
+set load-balancing reverse-proxy service http rule 10 domain-name 'node1.example.com'
+set load-balancing reverse-proxy service http rule 10 set backend 'bk-api-01'
+set load-balancing reverse-proxy service http rule 20 domain-name 'node2.example.com'
+set load-balancing reverse-proxy service http rule 20 set backend 'bk-api-02'
+
+set load-balancing reverse-proxy backend bk-api-01 description 'My API-1'
+set load-balancing reverse-proxy backend bk-api-01 mode 'tcp'
+set load-balancing reverse-proxy backend bk-api-01 server api01 address '127.0.0.1'
+set load-balancing reverse-proxy backend bk-api-01 server api01 port '4431'
+set load-balancing reverse-proxy backend bk-api-02 description 'My API-2'
+set load-balancing reverse-proxy backend bk-api-02 mode 'tcp'
+set load-balancing reverse-proxy backend bk-api-02 server api01 address '127.0.0.2'
+set load-balancing reverse-proxy backend bk-api-02 server api01 port '4432'
+```
+
+### Terminate SSL
+
+The following configuration terminates SSL on the router.
+
+The `http` service is listens on port 80 and force redirects from HTTP to
+HTTPS.
+
+The `https` service listens on port 443 with backend `bk-default` to
+handle HTTPS traffic. It uses certificate named `cert` for SSL termination.
+HSTS header is set with a 1-year expiry, to tell browsers to always use SSL for site.
+
+Rule 10 matches requests with the exact URL path `/.well-known/xxx`
+and redirects to location `/certs/`.
+
+Rule 20 matches requests with URL paths ending in `/mail` or exact
+path `/email/bar` redirect to location `/postfix/`.
+
+Additional global parameters are set, including the maximum number
+connection limit of 4000 and a minimum TLS version of 1.3.
+
+```none
+set load-balancing reverse-proxy service http description 'Force redirect to HTTPS'
+set load-balancing reverse-proxy service http port '80'
+set load-balancing reverse-proxy service http redirect-http-to-https
+
+set load-balancing reverse-proxy service https backend 'bk-default'
+set load-balancing reverse-proxy service https description 'listen on 443 port'
+set load-balancing reverse-proxy service https mode 'http'
+set load-balancing reverse-proxy service https port '443'
+set load-balancing reverse-proxy service https ssl certificate 'cert'
+set load-balancing reverse-proxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000'
+
+set load-balancing reverse-proxy service https rule 10 url-path exact '/.well-known/xxx'
+set load-balancing reverse-proxy service https rule 10 set redirect-location '/certs/'
+set load-balancing reverse-proxy service https rule 20 url-path end '/mail'
+set load-balancing reverse-proxy service https rule 20 url-path exact '/email/bar'
+set load-balancing reverse-proxy service https rule 20 set redirect-location '/postfix/'
+
+set load-balancing reverse-proxy backend bk-default description 'Default backend'
+set load-balancing reverse-proxy backend bk-default mode 'http'
+set load-balancing reverse-proxy backend bk-default server sr01 address '192.0.2.23'
+set load-balancing reverse-proxy backend bk-default server sr01 port '80'
+
+set load-balancing reverse-proxy global-parameters max-connections '4000'
+set load-balancing reverse-proxy 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 to the backend server via HTTPS.
+This is useful if encryption is required for both legs, 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 reverse-proxy service https backend 'bk-bridge-ssl'
+set load-balancing reverse-proxy service https description 'listen on 443 port'
+set load-balancing reverse-proxy service https mode 'http'
+set load-balancing reverse-proxy service https port '443'
+set load-balancing reverse-proxy service https ssl certificate 'cert'
+
+set load-balancing reverse-proxy backend bk-bridge-ssl description 'SSL backend'
+set load-balancing reverse-proxy backend bk-bridge-ssl mode 'http'
+set load-balancing reverse-proxy backend bk-bridge-ssl ssl ca-certificate 'cacert'
+set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 address '192.0.2.23'
+set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 port '443'
+```
+
+### Balancing with HTTP health checks
+
+This configuration enables HTTP health checks on backend servers.
+
+```none
+set load-balancing reverse-proxy service my-tcp-api backend 'bk-01'
+set load-balancing reverse-proxy service my-tcp-api mode 'tcp'
+set load-balancing reverse-proxy service my-tcp-api port '8888'
+
+set load-balancing reverse-proxy backend bk-01 balance 'round-robin'
+set load-balancing reverse-proxy backend bk-01 mode 'tcp'
+
+set load-balancing reverse-proxy backend bk-01 http-check method 'get'
+set load-balancing reverse-proxy backend bk-01 http-check uri '/health'
+set load-balancing reverse-proxy backend bk-01 http-check expect 'status 200'
+
+set load-balancing reverse-proxy backend bk-01 server srv01 address '192.0.2.11'
+set load-balancing reverse-proxy backend bk-01 server srv01 port '8881'
+set load-balancing reverse-proxy backend bk-01 server srv01 check
+set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12'
+set load-balancing reverse-proxy backend bk-01 server srv02 port '8882'
+set load-balancing reverse-proxy backend bk-01 server srv02 check
+```
diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/rst-index.rst
index 382bd0d7..382bd0d7 100644
--- a/docs/configuration/loadbalancing/index.rst
+++ b/docs/configuration/loadbalancing/rst-index.rst
diff --git a/docs/configuration/loadbalancing/reverse-proxy.rst b/docs/configuration/loadbalancing/rst-reverse-proxy.rst
index 32be85c8..32be85c8 100644
--- a/docs/configuration/loadbalancing/reverse-proxy.rst
+++ b/docs/configuration/loadbalancing/rst-reverse-proxy.rst
diff --git a/docs/configuration/loadbalancing/wan.rst b/docs/configuration/loadbalancing/rst-wan.rst
index 745cd8c2..745cd8c2 100644
--- a/docs/configuration/loadbalancing/wan.rst
+++ b/docs/configuration/loadbalancing/rst-wan.rst
diff --git a/docs/configuration/loadbalancing/wan.md b/docs/configuration/loadbalancing/wan.md
new file mode 100644
index 00000000..272ba9e9
--- /dev/null
+++ b/docs/configuration/loadbalancing/wan.md
@@ -0,0 +1,300 @@
+---
+lastproofread: '2023-01-27'
+---
+
+# WAN load balancing
+
+Outbound traffic can be balanced between two or more outbound interfaces.
+If a path fails, traffic is balanced across the remaining healthy paths,
+a recovered path is automatically added back to the routing table and used by
+the load balancer. The load balancer automatically adds routes for each path to
+the routing table and balances traffic across the configured interfaces,
+determined by 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).
+
+Let's assume we have 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}
+WAN Load Balacing should not be used when dynamic routing protocol is
+used/needed. This feature creates customized routing tables and firewall
+rules, that makes it incompatible to use with routing protocols.
+:::
+
+## Balancing Rules
+
+Interfaces, their weight and the type of traffic to be balanced are defined in
+numbered balancing rule sets. The rule sets are executed in numerical order
+against outgoing packets. In case of a match the packet is sent through an
+interface specified in the matching rule. If a packet doesn't match any rule
+it is sent by using the system routing table. Rule numbers can't be changed.
+
+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
+
+Let's expand the example from above and add weight to the interfaces.
+The bandwidth from eth0 is larger than eth1. Per default, outbound traffic is
+distributed randomly across available interfaces. Weights can be assigned to
+interfaces to influence the balancing.
+
+```none
+set load-balancing wan rule 1 interface eth0 weight 2
+set load-balancing wan rule 1 interface eth1 weight 1
+```
+
+66% of traffic is routed to eth0, eth1 gets 33% of traffic.
+
+### Rate limit
+
+A packet rate limit can be set for a rule to apply the rule to traffic above or
+below a specified threshold. To configure the 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
+
+Outgoing traffic is balanced in a flow-based manner.
+A connection tracking table is used to track flows by their source address,
+destination address and port. Each flow is assigned to an interface according
+to the defined balancing rules and subsequent packets are sent through the
+same interface. This has the advantage that packets always arrive in order if
+links with different speeds are in use.
+
+Packet-based balancing can lead to a better balance across interfaces when out
+of order packets are no issue. Per-packet-based balancing can be set for a
+balancing 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 is not
+balanced but routed through the system routing table instead:
+
+```none
+set load-balancing wan rule <rule> exclude
+```
+
+## Health checks
+
+The health of interfaces and paths assigned to the load balancer is
+periodically checked by sending ICMP packets (ping) to remote destinations,
+a TTL test or the execution of a user defined script. If an interface fails the
+health check it is removed from the load balancer's pool of interfaces.
+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 nexthop on the path to the destination, `ipv4-address` can be set to
+`dhcp`
+
+```none
+set load-balancing wan interface-health <interface> nexthop <ipv4-address>
+```
+
+Set the number of health check failures before an interface is marked as
+unavailable, range for number is 1 to 10, default 1. Or set the number of
+successful health checks before an interface is added back to the interface
+pool, range for number is 1 to 10, default 1.
+
+```none
+set load-balancing wan interface-health <interface> failure-count <number>
+set load-balancing wan interface-health <interface> success-count <number>
+```
+
+Each health check is configured in its own test, tests are numbered and
+processed in numeric order. For multi target health checking multiple tests
+can be defined:
+
+```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 be sent ICMP packets to, address can be an IPv4
+  address or hostname
+- `test-script`: A user defined script must return 0 to be considered
+  successful and non-zero to fail. Scripts are located in /config/scripts,
+  for different locations the full path needs to be provided
+- `ttl-limit`: For the UDP TTL limit test the hop count limit must be
+  specified. The limit must be shorter than the path length, an ICMP time
+  expired message is needed to be returned for a successful test. default 1
+- `type`: Specify the type of test. type can be ping, ttl or a user defined
+  script
+
+## Source NAT rules
+
+Per default, interfaces used in a load balancing pool replace the source IP
+of each outgoing packet with its own address to ensure that replies arrive on
+the same interface. This works through automatically generated source NAT (SNAT)
+rules, these rules are only applied to balanced traffic. In cases where this
+behaviour is not desired, the automatic generation of SNAT rules can be
+disabled:
+
+```none
+set load-balancing wan disable-source-nat
+```
+
+## Sticky Connections
+
+Inbound connections to a WAN interface can be improperly handled when the reply
+is sent back to the client.
+
+```{image} /_static/images/sticky-connections.jpg
+:align: center
+:width: 80%
+```
+
+Upon reception of an incoming packet, when a response is sent, it might be
+desired to ensure that it leaves from the same interface as the inbound one.
+This can be achieved by enabling sticky connections in the load balancing:
+
+```none
+set load-balancing wan sticky-connections inbound
+```
+
+## Failover
+
+In failover mode, one interface is set to be the primary interface and other
+interfaces are secondary or spare. Instead of balancing traffic across all
+healthy interfaces, only the primary interface is used and in case of failure,
+a secondary interface selected from the pool of available interfaces takes over.
+The primary interface is selected based on its weight and health, others become
+secondary interfaces. Secondary interfaces to take over a failed primary
+interface are chosen from the load balancer's interface pool, depending
+on their weight and health. Interface roles can also be selected based on rule
+order by including interfaces in balancing rules and ordering those rules
+accordingly. To put the load balancer in failover mode, create a failover rule:
+
+```none
+set load-balancing wan rule <number> failover
+```
+
+Because existing sessions do not automatically fail over to a new path,
+the session table can be flushed on each connection state change:
+
+```none
+set load-balancing wan flush-connections
+```
+
+:::{warning}
+Flushing the session table will cause other connections to fall back from
+flow-based to packet-based balancing until each flow is reestablished.
+:::
+
+## Script execution
+
+A script can be run when an interface state change occurs. Scripts are run
+from /config/scripts, for a different 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. System will become unresponsive if script
+does not return!
+:::
+
+## Handling and monitoring
+
+Show WAN load balancer information including test types and targets.
+A character at the start of each line depicts the state of the test
+
+- `+` 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/index.md b/docs/configuration/nat/index.md
new file mode 100644
index 00000000..bb0668ea
--- /dev/null
+++ b/docs/configuration/nat/index.md
@@ -0,0 +1,13 @@
+(nat)=
+
+# NAT
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   nat44
+   nat64
+   nat66
+```
diff --git a/docs/configuration/nat/nat44.md b/docs/configuration/nat/nat44.md
new file mode 100644
index 00000000..f7357f19
--- /dev/null
+++ b/docs/configuration/nat/nat44.md
@@ -0,0 +1,802 @@
+(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.
+
+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.
+
+```{eval-rst}
+.. cfgcmd:: set nat [source | destination] rule <rule> load-balance hash
+   [source-address | destination-address | source-port | destination-port
+   | random]
+```
+
+```{eval-rst}
+.. 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.
+
+It is important to note that when creating firewall rules that 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 policy, we want to allow traffic coming in on the
+outside interface, destined for TCP port 80 and the IP address of
+192.168.0.100.
+
+```none
+set firewall name OUTSIDE-IN rule 20 action 'accept'
+set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100'
+set firewall name OUTSIDE-IN rule 20 destination port '80'
+set firewall name OUTSIDE-IN rule 20 protocol 'tcp'
+set firewall name OUTSIDE-IN rule 20 state new 'enable'
+```
+
+This would generate the following configuration:
+
+```none
+rule 20 {
+    action accept
+    destination {
+        address 192.168.0.100
+        port 80
+    }
+    protocol tcp
+    state {
+        new enable
+    }
+}
+```
+
+:::{note}
+If you have configured the `INSIDE-OUT` policy, you will need to add
+additional rules to permit inbound NAT traffic.
+:::
+
+### 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.
+
+:::{figure} /_static/images/nat_before_vpn_topology.png
+:alt: NAT before VPN Topology
+:scale: 100 %
+
+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..7b700707
--- /dev/null
+++ b/docs/configuration/nat/nat64.md
@@ -0,0 +1,72 @@
+(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..371da24f
--- /dev/null
+++ b/docs/configuration/nat/nat66.md
@@ -0,0 +1,227 @@
+(nat66)=
+
+# NAT66(NPTv6)
+
+{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 '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 'eth0'
+set nat66 destination rule 1 destination address 'fc00::/64'
+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.png
+: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 'eth0'
+set nat66 destination rule 1 translation address 'fc01::/64'
+set nat66 source rule 1 outbound-interface '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.png
+: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/nat/index.rst b/docs/configuration/nat/rst-index.rst
index 6556b7f9..6556b7f9 100644
--- a/docs/configuration/nat/index.rst
+++ b/docs/configuration/nat/rst-index.rst
diff --git a/docs/configuration/nat/nat44.rst b/docs/configuration/nat/rst-nat44.rst
index e833ae5f..e833ae5f 100644
--- a/docs/configuration/nat/nat44.rst
+++ b/docs/configuration/nat/rst-nat44.rst
diff --git a/docs/configuration/nat/nat64.rst b/docs/configuration/nat/rst-nat64.rst
index e8a3a0e6..e8a3a0e6 100644
--- a/docs/configuration/nat/nat64.rst
+++ b/docs/configuration/nat/rst-nat64.rst
diff --git a/docs/configuration/nat/nat66.rst b/docs/configuration/nat/rst-nat66.rst
index 146ed381..146ed381 100644
--- a/docs/configuration/nat/nat66.rst
+++ b/docs/configuration/nat/rst-nat66.rst
diff --git a/docs/configuration/pki/index.md b/docs/configuration/pki/index.md
new file mode 100644
index 00000000..d008daaf
--- /dev/null
+++ b/docs/configuration/pki/index.md
@@ -0,0 +1,408 @@
+---
+lastproofread: '2024-01-05'
+---
+
+```{include} /_include/need_improvement.txt
+```
+
+(pki)=
+
+# PKI
+
+VyOS 1.4 changed the way in how encrytion 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.
+
+```{eval-rst}
+.. opcmd:: generate pki ca
+
+  Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and
+  private key on the console.
+```
+
+```{eval-rst}
+.. opcmd:: generate pki ca install <name>
+
+  Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and
+  private key on the console.
+
+  .. include:: pki_cli_import_help.txt
+```
+
+```{eval-rst}
+.. 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`.
+```
+
+```{eval-rst}
+.. 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`.
+
+  .. include:: pki_cli_import_help.txt
+```
+
+### Certificates
+
+```{eval-rst}
+.. opcmd:: generate pki certificate
+
+  Create a new public/private keypair and output the certificate on the console.
+```
+
+```{eval-rst}
+.. opcmd:: generate pki certificate install <name>
+
+  Create a new public/private keypair and output the certificate on the console.
+
+  .. include:: pki_cli_import_help.txt
+```
+
+```{eval-rst}
+.. opcmd:: generate pki certificate self-signed
+
+  Create a new self-signed certificate. The public/private is then shown on the
+  console.
+```
+
+```{eval-rst}
+.. opcmd:: generate pki certificate self-signed install <name>
+
+  Create a new self-signed certificate. The public/private is then shown on the
+  console.
+
+  .. include:: pki_cli_import_help.txt
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+
+  .. include:: pki_cli_import_help.txt
+```
+
+### Diffie-Hellman parameters
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+
+  .. include:: pki_cli_import_help.txt
+```
+
+### OpenVPN
+
+```{eval-rst}
+.. opcmd:: generate pki openvpn shared-secret
+
+  Genearate a new OpenVPN shared secret. The generated secred is the output to
+  the console.
+```
+
+```{eval-rst}
+.. opcmd:: generate pki openvpn shared-secret install <name>
+
+  Genearate a new OpenVPN shared secret. The generated secred is the output to
+  the console.
+
+  .. include:: pki_cli_import_help.txt
+```
+
+### WireGuard
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard key-pair
+
+  Generate a new WireGuard public/private key portion and output the result to
+  the console.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard pre-shared-key
+
+  Generate a WireGuard pre-shared secret used for peers to communicate.
+```
+
+```{eval-rst}
+.. opcmd:: generate pki wireguard pre-shared-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 secred is to be used.
+```
+
+## Key usage (CLI)
+
+### CA (Certificate Authority)
+
+```{eval-rst}
+.. 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'``
+```
+
+```{eval-rst}
+.. cfgcmd:: set pki ca <name> crl
+
+  Certificate revocation list in PEM format.
+```
+
+```{eval-rst}
+.. cfgcmd:: set pki ca <name> description
+
+  A human readable description what this CA is about.
+```
+
+```{eval-rst}
+.. 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'``
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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'``
+```
+
+```{eval-rst}
+.. cfgcmd:: set pki certificate <name> description
+
+  A human readable description what this certificate is about.
+```
+
+```{eval-rst}
+.. 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'``
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set pki certificate <name> revoke
+
+  If CA is present, this certificate will be included in generated CRLs
+```
+
+#### ACME
+
+The VyOS PKI subsystem can also be used to automatically retrieve Certificates
+using the {abbr}`ACME (Automatic Certificate Management Environment)` protocol.
+VyOS 1.4.1 does not store the intermediate certificates from ACME. Which makes
+this functionality limited. See {vytask}`T7299`.
+
+```{eval-rst}
+.. cfgcmd:: set pki certificate <name> acme domain-name <name>
+
+  Domain names to apply, multiple domain-names can be specified.
+
+  This is a mandatory option
+```
+
+```{eval-rst}
+.. cfgcmd:: set pki certificate <name> acme email <address>
+
+  Email used for registration and recovery contact.
+
+  This is a mandatory option
+```
+
+```{eval-rst}
+.. cfgcmd:: set pki certificate <name> acme listen-address <address>
+
+  The address the server listens to during http-01 challenge
+```
+
+```{eval-rst}
+.. cfgcmd:: set pki certificate <name> acme rsa-key-size <2048 | 3072 | 4096>
+
+  Size of the RSA key.
+
+  This options defaults to 2048
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. opcmd:: show pki ca <name>
+
+  Show only information for specified Certificate Authority.
+```
+
+```{eval-rst}
+.. 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)
+```
+
+```{eval-rst}
+.. opcmd:: show pki certificate <name>
+
+  Show only information for specified certificate.
+```
+
+```{eval-rst}
+.. opcmd:: show pki crl
+
+  Show a list of installed {abbr}`CRLs (Certificate Revocation List)`.
+```
+
+```{eval-rst}
+.. opcmd:: renew certbot
+
+  Manually trigger certificate renewal. This will be done twice a day.
+```
diff --git a/docs/configuration/pki/index.rst b/docs/configuration/pki/rst-index.rst
index 70b89d9f..70b89d9f 100644
--- a/docs/configuration/pki/index.rst
+++ b/docs/configuration/pki/rst-index.rst
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..beaae149
--- /dev/null
+++ b/docs/configuration/policy/community-list.md
@@ -0,0 +1,40 @@
+# BGP - Community List
+
+VyOS provides policies commands exclusively for BGP traffic filtering and
+manipulation: **community-list** is one of them.
+
+## Configuration
+
+### policy community-list
+
+```{eval-rst}
+.. cfgcmd:: set policy community-list <text>
+
+   Creat community-list policy identified by name <text>.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy community-list <text> description <text>
+
+   Set description for community-list policy.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy community-list <text> rule <1-65535> action
+   <permit|deny>
+
+   Set action to take on entries matching this rule.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy community-list <text> rule <1-65535> description <text>
+
+   Set description for rule.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy community-list <text> rule <1-65535> regex
+   <aa:nn|local-AS|no-advertise|no-export|internet|additive>
+
+   Regular expression to match against a community-list.
+```
diff --git a/docs/configuration/policy/examples.md b/docs/configuration/policy/examples.md
new file mode 100644
index 00000000..992aa82c
--- /dev/null
+++ b/docs/configuration/policy/examples.md
@@ -0,0 +1,203 @@
+# 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.png
+: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..284459c7
--- /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
+
+```{eval-rst}
+.. toctree::
+  :maxdepth: 1
+  :includehidden:
+
+  access-list
+  prefix-list
+  route
+  route-map
+  local-route
+  as-path-list
+  community-list
+  extcommunity-list
+  large-community-list
+```
+
+## Examples
+
+Examples of policies usage:
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   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..fb5e2e85
--- /dev/null
+++ b/docs/configuration/policy/local-route.md
@@ -0,0 +1,57 @@
+# Local Route Policy
+
+Policies for local traffic are defined in this section.
+
+## Configuration
+
+### Local Route IPv4
+
+```{eval-rst}
+.. cfgcmd:: set policy local-route rule <1-32765> set table <1-200|main>
+
+   Set routing table to forward packet to.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy local-route rule <1-32765> source <x.x.x.x|x.x.x.x/x>
+
+   Set source address or prefix to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy local-route rule <1-32765> destination <x.x.x.x|x.x.x.x/x>
+
+   Set destination address or prefix to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy local-route rule <1-32765> inbound-interface <interface>
+
+   Set inbound interface to match.
+```
+
+### Local Route IPv6
+
+```{eval-rst}
+.. cfgcmd:: set policy local-route6 rule <1-32765> set table <1-200|main>
+
+   Set routing table to forward packet to.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy local-route6 rule <1-32765> source <h:h:h:h:h:h:h:h | h:h:h:h:h:h:h:h/x>
+
+   Set source address or prefix to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy local-route6 rule <1-32765> destination <h:h:h:h:h:h:h:h | h:h:h:h:h:h:h:h/x>
+
+   Set destination address or prefix to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy local-route6 rule <1-32765> inbound-interface <interface>
+
+   Set inbound interface to match.
+```
diff --git a/docs/configuration/policy/prefix-list.md b/docs/configuration/policy/prefix-list.md
new file mode 100644
index 00000000..7f3d1c3e
--- /dev/null
+++ b/docs/configuration/policy/prefix-list.md
@@ -0,0 +1,143 @@
+# 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
+
+### Prefix Lists
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list <text>
+
+   This command creates the new prefix-list policy, identified by <text>.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list <text> description <text>
+
+   Set description for the prefix-list policy.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list <text> rule <1-65535> description <text>
+
+   Set description for rule in the prefix-list.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list <text> rule <1-65535> prefix <x.x.x.x/x>
+
+   Prefix to match against.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list <text> rule <1-65535> ge <0-32>
+
+   Netmask greater than length.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list <text> rule <1-65535> le <0-32>
+
+   Netmask less than length
+```
+
+### Example: Prefix Lists
+
+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.
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 10 action 'permit'
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 10 le '32'
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 10 prefix '192.0.2.0/24'
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 20 action 'permit'
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 20 le '32'
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 20 prefix '198.51.100.0/24'
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 30 action 'permit'
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 30 le '32'
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list PL4-EXAMPLE-NAME rule 30 prefix '203.0.113.0/24'
+```
+
+### IPv6 Prefix Lists
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list6 <text>
+
+   This command creates the new IPv6 prefix-list policy, identified by <text>.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list6 <text> description <text>
+
+   Set description for the IPv6 prefix-list policy.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> description <text>
+
+   Set description for rule in IPv6 prefix-list.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> prefix
+   <h:h:h:h:h:h:h:h/x>
+
+   IPv6 prefix.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> ge <0-128>
+
+   Netmask greater than length.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy prefix-list6 <text> rule <1-65535> le <0-128>
+
+   Netmask less than length
+```
diff --git a/docs/configuration/policy/route-map.md b/docs/configuration/policy/route-map.md
new file mode 100644
index 00000000..43ccd625
--- /dev/null
+++ b/docs/configuration/policy/route-map.md
@@ -0,0 +1,515 @@
+# 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
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text>
+
+   This command creates a new route-map policy, identified by <text>.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> description <text>
+
+   Set description for the route-map policy.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> action <permit|deny>
+
+   Set action for the route-map policy.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> call <text>
+
+   Call another route-map policy on match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> continue <1-65535>
+
+   Jump to a different rule in this route-map on a match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> description <text>
+
+   Set description for the rule in the route-map policy.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match as-path <text>
+
+   BGP as-path list to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match community
+   community-list <text>
+
+   BGP community-list to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match community
+   exact-match
+
+   Set BGP community-list to exactly match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match extcommunity
+   <text>
+
+   BGP extended community to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match interface <text>
+
+   First hop interface of a route to match.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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..
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop
+   type <blackhole>
+
+   IP next-hop of route to match, based on type.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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..
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match large-community
+   large-community-list <text>
+
+   Match BGP large communities.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match local-preference
+   <0-4294967295>
+
+   Match local preference.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match metric <1-65535>
+
+   Match route metric.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match origin
+   <egp|igp|incomplete>
+
+   Boarder Gateway Protocol (BGP) origin code to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match peer <x.x.x.x>
+
+   Peer IP address to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match protocol <protocol>
+
+   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)
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match rpki
+   <invalid|notfound|valid>
+
+   Match RPKI validation result.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match source-vrf <text>
+
+   Source VRF to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> match tag <1-65535>
+
+   Route tag to match.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> on-match goto <1-65535>
+
+   Exit policy on match: go to rule <1-65535>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> on-match next
+
+   Exit policy on match: go to next sequence number.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set atomic-aggregate
+
+   BGP atomic aggregate attribute.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set community none
+
+   Delete all BGP communities
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set community delete
+   <text>
+
+   Delete BGP communities matching the community-list.
+```
+
+```{eval-rst}
+.. 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>``
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community none
+
+   Delete all BGP large-communities
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community delete
+   <text>
+
+   Delete BGP communities matching the large-community-list.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity bandwidth
+   <1-25600|cumulative|num-multipaths>
+
+   Set extcommunity bandwidth
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity bandwidth-non-transitive
+
+   The link bandwidth extended community is encoded as non-transitive
+```
+
+```{eval-rst}
+.. 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>``.
+```
+
+```{eval-rst}
+.. 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>``.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity none
+
+   Clear all BGP extcommunities.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set distance <0-255>
+
+   Locally significant administrative distance.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set ip-next-hop
+   <x.x.x.x>
+
+   Nexthop IP address.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set local-preference
+   <0-4294967295>
+
+   Set BGP local preference attribute.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set metric-type
+   <type-1|type-2>
+
+   Set OSPF external metric-type.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set origin
+   <igp|egp|incomplete>
+
+   Set BGP origin code.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set originator-id
+   <x.x.x.x>
+
+   Set BGP originator ID attribute.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set table <1-200>
+
+   Set prefixes to table.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route-map <text> rule <1-65535> set tag <1-65535>
+
+   Set tag value for routing protocol.
+```
+
+```{eval-rst}
+.. 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
+> - `internet` - Well-known communities value 0
+> - `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..7230c9b4
--- /dev/null
+++ b/docs/configuration/policy/route.md
@@ -0,0 +1,483 @@
+# 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.
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> description <text>
+
+   Provide a rule-set description.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> default-log
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> default-log
+
+   Option to log packets hitting default-action.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> description <text>
+
+   Provide a description for each rule.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> log <enable|disable>
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> connection-mark <1-2147483647>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> connection-mark <1-2147483647>
+
+  Set match criteria based on connection mark.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> source address
+   <match_criteria>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> destination address
+   <match_criteria>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> source address
+   <match_criteria>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> destination address
+   <match_criteria>
+
+   Set match criteria based on source or destination ipv4|ipv6 address, where
+   <match_criteria> 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.
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> source group
+   <address-group|domain-group|mac-group|network-group|port-group> <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> destination group
+   <address-group|domain-group|mac-group|network-group|port-group> <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> source group
+   <address-group|domain-group|mac-group|network-group|port-group> <text>
+```
+
+```{eval-rst}
+.. 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 <text>
+   would be the group name/identifier. Prepend character '!' for inverted
+   matching criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> destination port <match_criteria>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> destination port <match_criteria>
+
+   Set match criteria based on destination port, where <match_criteria> could
+   be:
+
+   * <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'
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> disable
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> disable
+
+   Option to disable rule.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> dscp <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> dscp <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> dscp-exclude <text>
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> fragment
+   <match-grag|match-non-frag>
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> icmp <code | type>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 <code | type>
+
+   Match based on icmp|icmpv6 code and type.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> icmp type-name <text>
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> ipsec
+   <match-ipsec|match-none>
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> limit burst <0-4294967295>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> limit burst <0-4294967295>
+
+   Set maximum number of packets to alow in excess of rate.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> limit rate <text>
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> protocol
+   <text | 0-255 | tcp_udp | all >
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> packet-length <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> packet-length <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> packet-length-exclude <text>
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> packet-type [broadcast | host
+   | multicast | other]
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> packet-type [broadcast | host
+   | multicast | other]
+
+   Match based on packet type criteria.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> recent count <1-255>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> recent time <1-4294967295>
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> state
+   <established | invalid | new | related>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> state
+   <established | invalid | new | related>
+
+   Set match criteria based on session state.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> tcp flags <text>
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> time monthdays <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> time monthdays <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> time startdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> time startdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> time starttime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> time starttime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> time stopdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> time stopdate <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> time stoptime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> time stoptime <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> time weekdays <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> time weekdays <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> time utc
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> time utc
+
+   Time to match the defined rule.
+```
+
+```{eval-rst}
+.. 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'.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> action drop
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> action drop
+
+   Set rule action to drop.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> set connection-mark
+   <1-2147483647>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> set connection-mark
+   <1-2147483647>
+
+   Set a specific connection mark.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> set dscp <0-63>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> set dscp <0-63>
+
+   Set packet modifications: Packet Differentiated Services Codepoint (DSCP)
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> set mark <1-2147483647>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> set mark <1-2147483647>
+
+   Set a specific packet mark.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> set table <main | 1-200>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> set table <main | 1-200>
+
+   Set the routing table to forward packet with.
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route <name> rule <n> set tcp-mss <500-1460>
+```
+
+```{eval-rst}
+.. cfgcmd:: set policy route6 <name> rule <n> set tcp-mss <500-1460>
+
+   Set packet modifications: Explicitly set TCP Maximum segment size value.
+```
diff --git a/docs/configuration/policy/access-list.rst b/docs/configuration/policy/rst-access-list.rst
index 0af9b911..0af9b911 100644
--- a/docs/configuration/policy/access-list.rst
+++ b/docs/configuration/policy/rst-access-list.rst
diff --git a/docs/configuration/policy/as-path-list.rst b/docs/configuration/policy/rst-as-path-list.rst
index ceeb8e01..ceeb8e01 100644
--- a/docs/configuration/policy/as-path-list.rst
+++ b/docs/configuration/policy/rst-as-path-list.rst
diff --git a/docs/configuration/policy/community-list.rst b/docs/configuration/policy/rst-community-list.rst
index e53abeb3..e53abeb3 100644
--- a/docs/configuration/policy/community-list.rst
+++ b/docs/configuration/policy/rst-community-list.rst
diff --git a/docs/configuration/policy/examples.rst b/docs/configuration/policy/rst-examples.rst
index d822d839..d822d839 100644
--- a/docs/configuration/policy/examples.rst
+++ b/docs/configuration/policy/rst-examples.rst
diff --git a/docs/configuration/policy/extcommunity-list.rst b/docs/configuration/policy/rst-extcommunity-list.rst
index c413b8b5..c413b8b5 100644
--- a/docs/configuration/policy/extcommunity-list.rst
+++ b/docs/configuration/policy/rst-extcommunity-list.rst
diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/rst-index.rst
index 51f60479..51f60479 100644
--- a/docs/configuration/policy/index.rst
+++ b/docs/configuration/policy/rst-index.rst
diff --git a/docs/configuration/policy/large-community-list.rst b/docs/configuration/policy/rst-large-community-list.rst
index 0c57fd4a..0c57fd4a 100644
--- a/docs/configuration/policy/large-community-list.rst
+++ b/docs/configuration/policy/rst-large-community-list.rst
diff --git a/docs/configuration/policy/local-route.rst b/docs/configuration/policy/rst-local-route.rst
index e24d61d0..e24d61d0 100644
--- a/docs/configuration/policy/local-route.rst
+++ b/docs/configuration/policy/rst-local-route.rst
diff --git a/docs/configuration/policy/prefix-list.rst b/docs/configuration/policy/rst-prefix-list.rst
index cc0d8441..cc0d8441 100644
--- a/docs/configuration/policy/prefix-list.rst
+++ b/docs/configuration/policy/rst-prefix-list.rst
diff --git a/docs/configuration/policy/route-map.rst b/docs/configuration/policy/rst-route-map.rst
index 909f7e25..909f7e25 100644
--- a/docs/configuration/policy/route-map.rst
+++ b/docs/configuration/policy/rst-route-map.rst
diff --git a/docs/configuration/policy/route.rst b/docs/configuration/policy/rst-route.rst
index 45975774..45975774 100644
--- a/docs/configuration/policy/route.rst
+++ b/docs/configuration/policy/rst-route.rst
diff --git a/docs/configuration/protocols/babel.md b/docs/configuration/protocols/babel.md
new file mode 100644
index 00000000..b169e861
--- /dev/null
+++ b/docs/configuration/protocols/babel.md
@@ -0,0 +1,245 @@
+(babel)=
+
+# Babel
+
+Babel is a modern routing protocol designed to be robust and efficient
+both in ordinary wired networks and in wireless mesh networks.
+By default, it uses hop-count on wired networks and a variant of ETX
+on wireless links, It can be configured to take radio diversity into account
+and to automatically compute a link's latency and include it in the metric.
+It is defined in {rfc}`8966`.
+
+Babel a dual stack protocol.
+A single Babel instance is able to perform routing for both IPv4 and IPv6.
+
+## General Configuration
+
+VyOS does not have a special command to start the Babel process.
+The Babel process starts when the first Babel enabled interface is configured.
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface>
+
+  This command specifies a Babel enabled interface by interface name. Both
+  the sending and receiving of Babel packets will be enabled on the interface
+  specified in this command.
+```
+
+## Optional Configuration
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel parameters diversity
+
+  This command enables routing using radio frequency diversity.
+  This is highly recommended in networks with many wireless nodes.
+
+   .. note:: If you enable this, you will probably want to
+      set diversity-factor and channel below.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel parameters diversity-factor <1-256>
+
+  This command sets the multiplicative factor used for diversity routing,
+  in units of 1/256; lower values cause diversity to play a more important role
+  in route selection.
+  The default it 256, which means that diversity plays no role in route
+  selection; you will probably want to set that to 128 or less on nodes
+  with multiple independent radios.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel parameters resend-delay <milliseconds>
+
+  This command specifies the time in milliseconds after which an 'important'
+  request or update will be resent. The default is 2000 ms.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel parameters smoothing-half-life <seconds>
+
+  This command specifies the time constant, in seconds, of the smoothing
+  algorithm used for implementing hysteresis.
+  Larger values reduce route oscillation at the cost of very slightly increasing
+  convergence time. The value 0 disables hysteresis, and is suitable for wired
+  networks. The default is 4 s.
+```
+
+## Interfaces Configuration
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> type <auto|wired|wireless>
+
+  This command sets the interface type:
+
+  **auto** – automatically determines the interface type.
+  **wired** – enables optimisations for wired interfaces.
+  **wireless** – disables a number of optimisations that are only correct
+  on wired interfaces. Specifying wireless is always correct,
+  but may cause slower convergence and extra routing traffic.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> split-horizon <default|disable|enable>
+
+  This command specifies whether to perform split-horizon on the interface.
+  Specifying no babel split-horizon is always correct, while babel split-horizon
+  is an optimisation that should only be used on symmetric
+  and transitive (wired) networks.
+
+  **default** – enable split-horizon on wired interfaces, and disable
+  split-horizon on wireless interfaces.
+  **enable** – enable split-horizon on this interfaces.
+  **disable** – disable split-horizon on this interfaces.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> hello-interval <milliseconds>
+
+  This command specifies the time in milliseconds between two scheduled hellos.
+  On wired links, Babel notices a link failure within two hello intervals;
+  on wireless links, the link quality value is reestimated at every hello
+  interval.
+  The default is 4000 ms.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> update-interval <milliseconds>
+
+  This command specifies the time in milliseconds between two scheduled updates.
+  Since Babel makes extensive use of triggered updates,
+  this can be set to fairly high values on links with little packet loss.
+  The default is 20000 ms.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> rxcost <1-65534>
+
+  This command specifies the base receive cost for this interface.
+  For wireless interfaces, it specifies the multiplier used for computing
+  the ETX reception cost (default 256);
+  for wired interfaces, it specifies the cost that will be advertised to
+  neighbours.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> rtt-decay <1-256>
+
+  This command specifies the decay factor for the exponential moving average
+  of RTT samples, in units of 1/256.
+  Higher values discard old samples faster. The default is 42.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> rtt-min <milliseconds>
+
+  This command specifies the minimum RTT, in milliseconds,
+  starting from which we increase the cost to a neighbour.
+  The additional cost is linear in (rtt - rtt-min). The default is 10 ms.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> rtt-max <milliseconds>
+
+  This command specifies the maximum RTT, in milliseconds, above which
+  we don't increase the cost to a neighbour. The default is 120 ms.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> max-rtt-penalty <milliseconds>
+
+  This command specifies the maximum cost added to a neighbour because of RTT,
+  i.e. when the RTT is higher or equal than rtt-max.
+  The default is 150.
+  Setting it to 0 effectively disables the use of a RTT-based cost.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> enable-timestamps
+
+  This command enables sending timestamps with each Hello and IHU message
+  in order to compute RTT values.
+  It is recommended to enable timestamps on tunnel interfaces.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel interface <interface> channel <1-254|interfering|noninterfering>
+
+  This command set the channel number that diversity routing uses for this
+  interface (see diversity option above).
+
+  **1-254** – interfaces with a channel number interfere with
+  interfering interfaces and interfaces with the same channel number.
+  **interfering** – interfering interfaces are assumed to interfere with all other channels except
+  noninterfering channels.
+  **noninterfering** – noninterfering interfaces are assumed to only interfere
+  with themselves.
+```
+
+## Redistribution Configuration
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel redistribute <ipv4|ipv6> <route source>
+
+   This command redistributes routing information from the given route source
+   to the Babel process.
+
+   IPv4 route source: bgp, connected, eigrp, isis, kernel, nhrp, ospf, rip, static.
+
+   IPv6 route source: bgp, connected, eigrp, isis, kernel, nhrp, ospfv3, ripng, static.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> access-list <in|out> <number>
+
+  This command can be used to filter the Babel routes using access lists.
+  {cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the access
+  lists are applied.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> interface <interface> access-list <in|out> <number>
+
+  This command allows you apply access lists to a chosen interface to
+  filter the Babel routes.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> prefix-list <in|out> <name>
+
+  This command can be used to filter the Babel routes using prefix lists.
+  {cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the prefix
+  lists are applied.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols babel distribute-list <ipv4|ipv6> interface <interface> prefix-list <in|out> <name>
+
+  This command allows you apply prefix lists to a chosen interface to
+  filter the Babel routes.
+```
+
+## Configuration Example
+
+Simple Babel configuration using 2 nodes and redistributing connected interfaces.
+
+**Node 1:**
+
+```none
+set interfaces loopback lo address 10.1.1.1/32
+set interfaces loopback lo address fd12:3456:dead:beef::1/128
+set protocols babel interface eth0 type wired
+set protocols babel redistribute ipv4 connected
+set protocols babel redistribute ipv6 connected
+```
+
+**Node 2:**
+
+```none
+set interfaces loopback lo address 10.2.2.2/32
+set interfaces loopback lo address fd12:3456:beef:dead::2/128
+set protocols babel interface eth0 type wired
+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..13623e03
--- /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 identify 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 identify 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..c8f77a6a
--- /dev/null
+++ b/docs/configuration/protocols/bgp.md
@@ -0,0 +1,1435 @@
+(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.
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set protocols bgp neighbor <address|interface> remote-as
+   <nasn>
+
+   This command creates a new neighbor whose remote-as is <nasn>. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols bgp neighbor <address|interface> description
+   <text>
+
+   Set description of the peer or peer group.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set protocols bgp neighbor <address|interface> capability
+   dynamic
+
+   This command would allow the dynamic update of capabilities over an
+   established BGP session.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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`.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols bgp parameters log-neighbor-changes
+
+   This command enable logging neighbor up/down changes and reset reason.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols bgp parameters no-fast-external-failover
+
+   Disable immediate session reset if peer's connected link goes down.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols bgp parameters bestpath as-path ignore
+
+   Ignore AS_PATH length when selecting a route
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+> :::
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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`.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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`
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. opcmd:: show bgp <ip|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
+
+   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
+```
+
+```{eval-rst}
+.. opcmd:: show bgp <ip|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
+```
+
+```{eval-rst}
+.. opcmd:: show bgp cidr-only
+
+   This command displays routes with classless interdomain routing (CIDR).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. opcmd:: show bgp <ipv4|ipv6> community-list <name>
+
+   This command displays routes that are permitted by the BGP
+   community list.
+```
+
+```{eval-rst}
+.. opcmd:: show bgp <ipv4|ipv6> dampening dampened-paths
+
+   This command displays BGP dampened routes.
+```
+
+```{eval-rst}
+.. opcmd:: show bgp <ipv4|ipv6> dampening flap-statistics
+
+   This command displays information about flapping BGP routes.
+```
+
+```{eval-rst}
+.. opcmd:: show bgp <ipv4|ipv6> filter-list <name>
+
+   This command displays BGP routes allowed by the specified AS Path
+   access list.
+```
+
+```{eval-rst}
+.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> advertised-routes
+
+   This command displays BGP routes advertised to a neighbor.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> routes
+
+   This command displays BGP received-routes that are accepted after filtering.
+```
+
+```{eval-rst}
+.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> dampened-routes
+
+   This command displays dampened routes received from BGP neighbor.
+```
+
+```{eval-rst}
+.. opcmd:: show bgp <ipv4|ipv6> regexp <text>
+
+   This command displays information about BGP routes whose AS path
+   matches the specified regular expression.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. opcmd:: reset ip bgp all
+
+   This command resets all BGP connections of given router.
+```
+
+```{eval-rst}
+.. opcmd:: reset bgp <ipv4|ipv6> external
+
+   This command resets all external BGP peers of given router.
+```
+
+```{eval-rst}
+.. 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.2 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..45c3e449
--- /dev/null
+++ b/docs/configuration/protocols/failover.md
@@ -0,0 +1,120 @@
+# Failover
+
+Failover routes are manually configured routes, but they only install
+to the routing table if the health-check target is alive.
+If the target is not alive the route is removed from the routing table
+until the target becomes available.
+
+## Failover Routes
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check
+   target <target-address>
+
+   Configure next-hop `<address>` and `<target-address>` for an IPv4 static
+   route. Specify the target
+   IPv4 address for health checking.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check
+   timeout <timeout>
+
+   Timeout in seconds between health target checks.
+
+   Range is 1 to 300, default is 10.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check
+   type <protocol>
+
+   Defines protocols for checking ARP, ICMP, TCP
+
+   Default is ``icmp``.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check
+   policy <policy>
+
+   Policy for checking targets
+```
+
+- `all-available` all checking target addresses must be available to pass
+  this check
+
+- `any-available` any of the checking target addresses must be available
+  to pass this check
+
+  > Default is `any-available`.
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address>
+   interface <interface>
+
+   Next-hop interface for the route
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols failover route <subnet> next-hop <address>
+   metric <metric>
+
+   Route metric
+
+   Default 1.
+
+```
+
+## Example
+
+**One gateway:**
+
+```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'
+```
+
+Show 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
+  * 192.0.2.1, via eth0
+```
+
+**Two gateways and different metrics:**
+
+```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'
+```
+
+Show 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:08:06 ago
+  * 192.0.2.1, via eth0
+
+Routing entry for 203.0.113.1/32
+  Known via "kernel", distance 0, metric 20
+  Last update 00:08:14 ago
+  * 198.51.100.1, via eth2
+```
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..418e49af
--- /dev/null
+++ b/docs/configuration/protocols/index.md
@@ -0,0 +1,22 @@
+# Protocols
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   babel
+   bfd
+   bgp
+   failover
+   igmp-proxy
+   isis
+   mpls
+   segment-routing
+   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..07ffd827
--- /dev/null
+++ b/docs/configuration/protocols/isis.md
@@ -0,0 +1,596 @@
+```{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 conencted 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.
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis net <network-entity-title>
+
+  This commad 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 (numberical area ``1``)
+
+  * System identifier: ``1921.6800.1002`` - for system idetifiers 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."
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis set-attached-bit
+
+  This command sets ATT bit to 1 in Level1 LSPs. It is described in {rfc}`3787`.
+```
+
+```{eval-rst}
+.. 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`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis name default-information originate <ipv4|ipv6>
+  level-1
+
+  This command will generate a default-route in L1 database.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis name default-information originate <ipv4|ipv6>
+  level-2
+
+  This command will generate a default-route in L2 database.
+
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis interface <interface> passive
+
+  This command configures the passive mode for this interface.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis interface <interface> password
+  plaintext-password <text>
+
+  This command configures the authentication password for the interface.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis interface <interface> psnp-interval
+  <number>
+
+  This command sets PSNP interval in seconds. The interval range is 0
+  to 127.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis interface <interface> ldp-sync disable
+
+  This command disables IGP-LDP sync for this specific interface.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+#### Route Redistribution
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis spf-delay-ietf holddown <milliseconds>
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis spf-delay-ietf init-delay
+  <milliseconds>
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis spf-delay-ietf long-delay
+  <milliseconds>
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols isis spf-delay-ietf short-delay
+  <milliseconds>
+```
+
+```{eval-rst}
+.. 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`.
+
+```
+
+## 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
+```
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/ospf.md b/docs/configuration/protocols/ospf.md
new file mode 100644
index 00000000..adc62520
--- /dev/null
+++ b/docs/configuration/protocols/ospf.md
@@ -0,0 +1,1560 @@
+(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.
+
+```{eval-rst}
+.. 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>`
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols ospf distance global <distance>
+
+   This command change distance value of OSPF globally.
+   The distance range is 1 to 255.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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 :t:`ospf-shortcut-abr-02.txt`
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+   by setting the {cfgcmd}`passive disable` flag for the specific interface.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols ospf interface <interface> bfd
+
+   This command enables {abbr}`BFD (Bidirectional Forwarding Detection)` on
+   this OSPF link interface.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols ospf interface <interface> ldp-sync disable
+
+  This command disables IGP-LDP sync for this specific interface.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set protocols ospf aggregation timer <seconds>
+
+   Configure aggregation delay timer interval.
+
+   Summarisation starts only after this delay timer expiry.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols ospf graceful-restart helper supported-grace-time
+
+   Supports as HELPER for configured grace period.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set protocols ospf neighbor <A.B.C.D>
+
+   This command specifies the IP address of the neighboring device.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols ospf default-metric <number>
+
+   This command specifies the default metric value of redistributed routes.
+   The metric range is 0 to 16777214.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. opcmd:: show ip ospf neighbor <interface>
+
+   This command displays the neighbors status for a neighbor on the specified
+   interface.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. opcmd:: show ip ospf border-routers
+
+   This command displays a table of paths to area boundary and autonomous
+   system boundary routers.
+```
+
+```{eval-rst}
+.. 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]
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set protocols ospfv3 distance global <distance>
+
+   This command change distance value of OSPFv3 globally.
+   The distance range is 1 to 255.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols ospfv3 graceful-restart helper supported-grace-time
+
+   Supports as HELPER for configured grace period.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. opcmd:: show ipv6 ospfv3 neighbor
+
+   This command displays the neighbors status.
+```
+
+```{eval-rst}
+.. opcmd:: show ipv6 ospfv3 neighbor detail
+
+   This command displays the neighbors information in a detailed form, not
+   just a summary table.
+```
+
+```{eval-rst}
+.. opcmd:: show ipv6 ospfv3 neighbor drchoice
+
+   This command displays the neighbor DR choice information.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. opcmd:: show ipv6 ospfv3 route
+
+   This command displays the OSPF routing table, as determined by the most
+   recent SPF calculation.
+```
+
+```{eval-rst}
+.. opcmd:: show ipv6 ospfv3 border-routers
+
+   This command displays a table of paths to area boundary and autonomous
+   system boundary routers.
+```
+
+```{eval-rst}
+.. opcmd:: show ipv6 ospfv3 database
+
+   This command displays a summary table with a database contents (LSA).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+```
+
+:::{note}
+You cannot easily redistribute IPv6 routes via OSPFv3 on a
+WireGuard interface link. This requires you to configure link-local
+addresses manually on the WireGuard interfaces, see {vytask}`T1483`.
+:::
+
+Example configuration for WireGuard interfaces:
+
+**Node 1**
+
+```none
+set interfaces wireguard wg01 address 'fe80::216:3eff:fe51:fd8c/64'
+set interfaces wireguard wg01 address '192.168.0.1/24'
+set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0'
+set interfaces wireguard wg01 peer ospf02 allowed-ips '0.0.0.0/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 'lo' area 0.0.0.0
+```
+
+**Node 2**
+
+```none
+set interfaces wireguard wg01 address 'fe80::216:3eff:fe0a:7ada/64'
+set interfaces wireguard wg01 address '192.168.0.2/24'
+set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0'
+set interfaces wireguard wg01 peer ospf01 allowed-ips '0.0.0.0/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 '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..1768be72
--- /dev/null
+++ b/docs/configuration/protocols/pim.md
@@ -0,0 +1,304 @@
+---
+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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols pim interface <interface> hello <n>
+
+   Set the PIM hello and hold interval for a interface.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols pim interface <interface> no-bsm
+
+   Tell PIM that we would not like to use this interface to process
+   bootstrap messages.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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)
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.png
+: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/babel.rst b/docs/configuration/protocols/rst-babel.rst
index 07d1bc86..07d1bc86 100644
--- a/docs/configuration/protocols/babel.rst
+++ b/docs/configuration/protocols/rst-babel.rst
diff --git a/docs/configuration/protocols/bfd.rst b/docs/configuration/protocols/rst-bfd.rst
index 30876efc..30876efc 100644
--- a/docs/configuration/protocols/bfd.rst
+++ b/docs/configuration/protocols/rst-bfd.rst
diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/rst-bgp.rst
index 6d93bcc4..6d93bcc4 100644
--- a/docs/configuration/protocols/bgp.rst
+++ b/docs/configuration/protocols/rst-bgp.rst
diff --git a/docs/configuration/protocols/failover.rst b/docs/configuration/protocols/rst-failover.rst
index 8088e104..8088e104 100644
--- a/docs/configuration/protocols/failover.rst
+++ b/docs/configuration/protocols/rst-failover.rst
diff --git a/docs/configuration/protocols/igmp-proxy.rst b/docs/configuration/protocols/rst-igmp-proxy.rst
index f62a289e..f62a289e 100644
--- a/docs/configuration/protocols/igmp-proxy.rst
+++ b/docs/configuration/protocols/rst-igmp-proxy.rst
diff --git a/docs/configuration/protocols/index.rst b/docs/configuration/protocols/rst-index.rst
index ea217d3c..ea217d3c 100644
--- a/docs/configuration/protocols/index.rst
+++ b/docs/configuration/protocols/rst-index.rst
diff --git a/docs/configuration/protocols/isis.rst b/docs/configuration/protocols/rst-isis.rst
index 18a7c166..18a7c166 100644
--- a/docs/configuration/protocols/isis.rst
+++ b/docs/configuration/protocols/rst-isis.rst
diff --git a/docs/configuration/protocols/mpls.rst b/docs/configuration/protocols/rst-mpls.rst
index 550473d7..550473d7 100644
--- a/docs/configuration/protocols/mpls.rst
+++ b/docs/configuration/protocols/rst-mpls.rst
diff --git a/docs/configuration/protocols/ospf.rst b/docs/configuration/protocols/rst-ospf.rst
index 43680520..43680520 100644
--- a/docs/configuration/protocols/ospf.rst
+++ b/docs/configuration/protocols/rst-ospf.rst
diff --git a/docs/configuration/protocols/pim.rst b/docs/configuration/protocols/rst-pim.rst
index 2e881943..2e881943 100644
--- a/docs/configuration/protocols/pim.rst
+++ b/docs/configuration/protocols/rst-pim.rst
diff --git a/docs/configuration/protocols/pim6.rst b/docs/configuration/protocols/rst-pim6.rst
index 2b2276a7..2b2276a7 100644
--- a/docs/configuration/protocols/pim6.rst
+++ b/docs/configuration/protocols/rst-pim6.rst
diff --git a/docs/configuration/protocols/rip.rst b/docs/configuration/protocols/rst-rip.rst
index fd20a90c..fd20a90c 100644
--- a/docs/configuration/protocols/rip.rst
+++ b/docs/configuration/protocols/rst-rip.rst
diff --git a/docs/configuration/protocols/rpki.rst b/docs/configuration/protocols/rst-rpki.rst
index 17557884..17557884 100644
--- a/docs/configuration/protocols/rpki.rst
+++ b/docs/configuration/protocols/rst-rpki.rst
diff --git a/docs/configuration/protocols/segment-routing.rst b/docs/configuration/protocols/rst-segment-routing.rst
index 5ee710e9..5ee710e9 100644
--- a/docs/configuration/protocols/segment-routing.rst
+++ b/docs/configuration/protocols/rst-segment-routing.rst
diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/rst-static.rst
index bfc25201..bfc25201 100644
--- a/docs/configuration/protocols/static.rst
+++ b/docs/configuration/protocols/rst-static.rst
diff --git a/docs/configuration/protocols/segment-routing.md b/docs/configuration/protocols/segment-routing.md
new file mode 100644
index 00000000..af47d343
--- /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
+identify 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
+identify 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..fca17a6c
--- /dev/null
+++ b/docs/configuration/protocols/static.md
@@ -0,0 +1,268 @@
+(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.
+
+## Static Routes
+
+```{eval-rst}
+.. cfgcmd:: set protocols static route <subnet> next-hop <address>
+
+   Configure next-hop `<address>` for an IPv4 static route. Multiple static
+   routes can be created.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols static route <subnet> next-hop <address> disable
+
+   Disable this IPv4 static route entry.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols static route6 <subnet> next-hop <address>
+
+   Configure next-hop `<address>` for an IPv6 static route. Multiple static
+   routes can be created.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> disable
+
+   Disable this IPv6 static route entry.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```
+
+### Interface Routes
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols static route <subnet> interface
+   <interface> disable
+
+   Disables interface-based IPv4 static route.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols static route6 <subnet> interface
+   <interface> disable
+
+   Disables interface-based IPv6 static route.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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'
+```
+
+### Blackhole
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+### Alternate Routing Tables
+
+TBD
+
+Alternate routing tables are used with policy based routing by utilizing
+{ref}`vrf`.
+
+(routing-arp)=
+
+# ARP
+
+{abbr}`ARP (Address Resolution Protocol)` is a communication protocol used for
+discovering the link layer address, such as a MAC address, associated with a
+given internet layer address, typically an IPv4 address. This mapping is a
+critical function in the Internet protocol suite. ARP was defined in 1982 by
+{rfc}`826` which is Internet Standard STD 37.
+
+In Internet Protocol Version 6 (IPv6) networks, the functionality of ARP is
+provided by the Neighbor Discovery Protocol (NDP).
+
+To manipulate or display [ARP] table entries, the following commands are
+implemented.
+
+## Configure
+
+```{eval-rst}
+.. cfgcmd:: set protocols static arp interface <interface> address <host>
+   mac <mac>
+
+   This will configure a static ARP entry always resolving `<address>` to
+   `<mac>` for interface `<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
+
+   Display all known ARP table entries spanning across all interfaces
+```
+
+```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 eth1
+
+   Display all known ARP table entries on a given interface only (`eth1`):
+```
+
+```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/index.rst b/docs/configuration/rst-index.rst
index f607d4d7..f607d4d7 100644
--- a/docs/configuration/index.rst
+++ b/docs/configuration/rst-index.rst
diff --git a/docs/configuration/service/broadcast-relay.md b/docs/configuration/service/broadcast-relay.md
new file mode 100644
index 00000000..73baad1b
--- /dev/null
+++ b/docs/configuration/service/broadcast-relay.md
@@ -0,0 +1,76 @@
+(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
+
+```{eval-rst}
+.. 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/appliactions.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service broadcast-relay id <n> address <ipv4-address>
+
+   Set the source IP of forwarded packets, otherwise original senders address
+   is used.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service broadcast-relay id <n> port <port>
+
+   The UDP port number used by your apllication. It is mandatory for this kind
+   of operation.
+```
+
+```{eval-rst}
+.. 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:
+```
+
+```{eval-rst}
+.. 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..0f92768d
--- /dev/null
+++ b/docs/configuration/service/config-sync.md
@@ -0,0 +1,117 @@
+(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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+```
+
+## 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'
+```
+
+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..d82459df
--- /dev/null
+++ b/docs/configuration/service/conntrack-sync.md
@@ -0,0 +1,329 @@
+(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 specificed interface, as in the following example:
+
+{cfgcmd}`set service conntrack-sync interface eth0 peer 192.168.0.250`
+
+## Configuration
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service conntrack-sync expect-sync <all|ftp|h323|nfs|sip|sqlnet>
+
+    Protocol for which expect entries need to be synchronized.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service conntrack-sync failover-mechanism vrrp sync-group <group>
+
+    Failover mechanism to use for conntrack-sync.
+
+    Only VRRP is supported. Required option.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service conntrack-sync ignore-address <x.x.x.x>
+
+    IP addresses or networks for which local conntrack entries will not be synced
+```
+
+```{eval-rst}
+.. cfgcmd:: set service conntrack-sync interface <name>
+
+    Interface to use for syncing conntrack entries.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service conntrack-sync interface <name> port <port>
+
+   Port number used by connection.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service conntrack-sync listen-address <ipv4address>
+
+   Local IPv4 addresses for service to listen on.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service conntrack-sync sync-queue-size <size>
+
+    Queue size for syncing conntrack entries in MB.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+:::
+
+```{eval-rst}
+.. cfgcmd:: set service conntrack-sync disable-syslog
+
+   Disable connection logging via Syslog.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service conntrack-sync startup-resync
+
+   Order conntrackd to request a complete conntrack table resync against
+   the other node at startup.
+```
+
+## Operation
+
+```{eval-rst}
+.. 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`
+```
+
+```{eval-rst}
+.. opcmd:: show conntrack-sync cache external
+
+  Show connection syncing external cache entries
+```
+
+```{eval-rst}
+.. opcmd:: show conntrack-sync cache internal
+
+  Show connection syncing internal cache entries
+```
+
+```{eval-rst}
+.. 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
+
+```
+
+```{eval-rst}
+.. 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.png
+:alt: Conntrack Sync Example
+:scale: 60 %
+:::
+
+Now configure conntrack-sync service on `router1` **and** `router2`
+
+```none
+set high-availablilty 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..f0556652
--- /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 successful 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..4bbee82b
--- /dev/null
+++ b/docs/configuration/service/dhcp-relay.md
@@ -0,0 +1,225 @@
+(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
+
+```{eval-rst}
+.. 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``.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-relay listen-interface <interface>
+
+   Interface for DHCP Relay Agent to listen for requests.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-relay upstream-interface <interface>
+
+   Interface for DHCP Relay Agent to forward requests out.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-relay server <server>
+
+   Configure IP address of the DHCP `<server>` which will handle the relayed
+   packets.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-relay disable
+
+   Disable dhcp-relay service.
+```
+
+#### Options
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-relay relay-options hop-count <count>
+
+   Set the maximum hop `<count>` before packets are discarded. Range 0...255,
+   default 10.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.png
+:alt: DHCP relay example
+:scale: 80 %
+
+DHCP relay example
+:::
+
+The generated configuration will look like:
+
+```none
+show service dhcp-relay
+    listen-interface eth1
+    upstrem-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
+
+```{eval-rst}
+.. opcmd:: restart dhcp relay-agent
+
+   Restart DHCP relay service
+```
+
+## IPv6 relay
+
+(dhcp-relay-ipv6-configuration)=
+
+### Configuration
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-relay listen-interface <interface>
+
+   Set eth1 to be the listening interface for the DHCPv6 relay.
+
+   Multiple interfaces may be specified.
+```
+
+```{eval-rst}
+.. 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)=
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-relay disable
+
+   Disable dhcpv6-relay service.
+```
+
+(dhcp-relay-v6-options)=
+
+#### Options
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-relay max-hop-count <count>
+
+   Set maximum hop count before packets are discarded, default: 10
+```
+
+```{eval-rst}
+.. 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.png
+: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
+
+```{eval-rst}
+.. opcmd:: restart dhcpv6 relay-agent
+
+   Restart DHCPv6 relay agent immediately.
+```
diff --git a/docs/configuration/service/dhcp-server.md b/docs/configuration/service/dhcp-server.md
new file mode 100644
index 00000000..0373c2c3
--- /dev/null
+++ b/docs/configuration/service/dhcp-server.md
@@ -0,0 +1,919 @@
+(dhcp-server)=
+
+# DHCP Server
+
+VyOS uses ISC 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
+
+```{eval-rst}
+.. 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>`
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server host-decl-name
+
+   Will drop `<shared-network-name>_` from client DNS record, using only the
+   host declaration name and domain: `<hostname>.<domain-name>`
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name>
+   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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name>
+   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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name>
+   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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name> ping-check
+
+   When the DHCP server is considering dynamically allocating an IP address to a
+   client, it first sends an ICMP Echo request (a ping) to the address being
+   assigned. It waits for a second, and if no ICMP Echo response has been heard,
+   it assigns the address.
+
+   If a response is heard, the lease is abandoned, and the server does not
+   respond to the client. The lease will remain abandoned for a minimum of
+   abandon-lease-time seconds (defaults to 24 hours).
+
+   If there are no free addresses but there are abandoned IP addresses, the
+   DHCP server will attempt to reclaim an abandoned IP address regardless of the
+   value of abandon-lease-time.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
+   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>`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
+   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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
+   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).
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
+   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).
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
+   ping-check
+
+   When the DHCP server is considering dynamically allocating an IP address to a
+   client, it first sends an ICMP Echo request (a ping) to the address being
+   assigned. It waits for a second, and if no ICMP Echo response has been heard,
+   it assigns the address.
+
+   If a response is heard, the lease is abandoned, and the server does not
+   respond to the client. The lease will remain abandoned for a minimum of
+   abandon-lease-time seconds (defaults to 24 hours).
+
+   If a there are no free addresses but there are abandoned IP addresses, the
+   DHCP server will attempt to reclaim an abandoned IP address regardless of the
+   value of abandon-lease-time.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
+   enable-failover
+
+   Enable DHCP failover configuration for this address pool.
+```
+
+#### 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:
+
+```{eval-rst}
+.. 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`
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server high-availability source-address <address>
+
+   Local IP `<address>` used when communicating to the HA peer.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server high-availability remote <address>
+
+   Remote peer IP `<address>` of the second DHCP server in this HA
+   cluster.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet
+   <subnet> static-mapping <description> mac-address <address>
+
+   Create a new DHCP static mapping named `<description>` which is valid for
+   the host identified by its MAC `<address>`.
+```
+
+```{eval-rst}
+.. 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 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-address 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-address aa:bb:11:22:33:00
+     }
+ }
+```
+
+### Options
+
+```{eval-rst}
+.. 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.
+
+### Raw Parameters
+
+Raw parameters can be passed to shared-network-name, subnet and static-mapping:
+
+```none
+set service dhcp-server shared-network-name <name> shared-network-parameters
+   <text>       Additional shared-network parameters for DHCP server.
+set service dhcp-server shared-network-name <name> subnet <subnet> subnet-parameters
+   <text>       Additional subnet parameters for DHCP server.
+set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> static-mapping-parameters
+   <text>       Additional static-mapping parameters for DHCP server.
+                Will be placed inside the "host" block of the mapping.
+```
+
+These parameters are passed as-is to isc-dhcp's dhcpd.conf under the
+configuration node they are defined in. They are not validated so an error in
+the raw parameters won't be caught by vyos's scripts and will cause dhcpd to
+fail to start. Always verify that the parameters are correct before committing
+the configuration. Refer to isc-dhcp's dhcpd.conf manual for more information:
+<https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf>
+
+Quotes can be used inside parameter values by replacing all quote characters
+with the string `&quot;`. They will be replaced with literal quote characters
+when generating dhcpd.conf.
+
+### 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 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 default-router '192.0.2.254'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 name-server '192.0.2.254'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 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 enable-failover
+```
+
+**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)=
+
+#### Raw Parameters
+
+- Override static-mapping's name-server with a custom one that will be sent only
+  to this host.
+- An option that takes a quoted string is set by replacing all quote characters
+  with the string `&quot;` inside the static-mapping-parameters value.
+  The resulting line in dhcpd.conf will be
+  `option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";`.
+
+```none
+set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;"
+set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile &quot;pxelinux.cfg/01-00-15-17-44-2d-aa&quot;;"
+```
+
+#### Option 43 for UniFI
+
+- These parameters need to be part of the DHCP global options.
+  They stay unchanged.
+
+```none
+set service dhcp-server global-parameters 'option space ubnt;'
+set service dhcp-server global-parameters 'option ubnt.unifi-address code 1 = ip-address;'
+set service dhcp-server global-parameters 'class &quot;ubnt&quot; {'
+set service dhcp-server global-parameters 'match if substring (option vendor-class-identifier, 0, 4) = &quot;ubnt&quot;;'
+set service dhcp-server global-parameters 'option vendor-class-identifier &quot;ubnt&quot;;'
+set service dhcp-server global-parameters 'vendor-option-space ubnt;'
+set service dhcp-server global-parameters '}'
+```
+
+- Now we add the option to the scope, adapt to your setup
+
+```none
+set service dhcp-server shared-network-name example-scope subnet 10.1.1.0/24 subnet-parameters 'option ubnt.unifi-address 172.16.1.10;'
+```
+
+### Operation Mode
+
+```{eval-rst}
+.. opcmd:: show log dhcp server
+
+   Show DHCP server daemon log file
+```
+
+```{eval-rst}
+.. opcmd:: show log dhcp client
+
+   Show logs from all DHCP client processes.
+```
+
+```{eval-rst}
+.. opcmd:: show log dhcp client interface <interface>
+
+   Show logs from specific `interface` DHCP client process.
+```
+
+```{eval-rst}
+.. opcmd:: restart dhcp server
+
+   Restart the DHCP server
+```
+
+```{eval-rst}
+.. 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%
+```
+
+```{eval-rst}
+.. opcmd:: show dhcp server statistics pool <pool>
+
+   Show the DHCP server statistics for the specified pool.
+```
+
+```{eval-rst}
+.. 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`.
+:::
+
+```{eval-rst}
+.. 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:~$
+```
+
+```{eval-rst}
+.. 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:~$
+```
+
+```{eval-rst}
+.. 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)
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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``.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet
+   <prefix> nis-domain <domain-name>
+
+   A {abbr}`NIS (Network Information Service)` domain can be set to be used for
+   DHCPv6 clients.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet
+   <prefix> nisplus-domain <domain-name>
+
+   The procedure to specify a {abbr}`NIS+ (Network Information Service Plus)`
+   domain is similar to the NIS domain one:
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet
+   <prefix> nis-server <address>
+
+   Specify a NIS server address for DHCPv6 clients.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet
+   <prefix> nisplus-server <address>
+
+   Specify a NIS+ server address for DHCPv6 clients.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet
+   <prefix> sip-server <address | fqdn>
+
+   Specify a {abbr}`SIP (Session Initiation Protocol)` server by IPv6
+   address of Fully Qualified Domain Name for all DHCPv6 clients.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet
+   <prefix> sntp-server-address <address>
+
+   A SNTP server address can be specified for DHCPv6 clients.
+```
+
+#### Prefix Delegation
+
+:::{note}
+VyOS =< 1.4.3 does not add the prefixes to the routing table.
+:::
+
+To hand out individual prefixes to your clients the following configuration is
+used:
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet
+   <prefix> prefix-delegation start <address> prefix-length <length>
+
+   Hand out prefixes of size `<length>` to clients in subnet `<prefix>` when
+   they request for prefix delegation.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet
+   <prefix> prefix-delegation start <address> stop <address>
+
+   Delegate prefixes from the range indicated by the start and stop qualifier.
+```
+
+**Example:**
+
+To delegate /64's from a bigger /56
+
+```none
+set service dhcpv6-server shared-network-name MYNET subnet 2001:db8:0:1::/64 prefix-delegation start 2001:0db8:1:: prefix-length '64'
+set service dhcpv6-server shared-network-name MYNET subnet 2001:db8:0:1::/64 prefix-delegation start 2001:0db8:1:: stop '2001:0db8:1:ff::'
+```
+
+#### 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 'NET1' subnet 2001:db8::/64 address-range start 2001:db8::100 stop 2001:db8::199
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 name-server 2001:db8::ffff
+```
+
+The configuration will look as follows:
+
+```none
+show service dhcpv6-server
+    shared-network-name NET1 {
+        subnet 2001:db8::/64 {
+           address-range {
+              start 2001:db8::100 {
+                 stop 2001:db8::199
+              }
+           }
+           name-server 2001:db8::ffff
+        }
+    }
+```
+
+(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`.
+:::
+
+```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 identifier 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 {
+         identifier 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
+
+```{eval-rst}
+.. opcmd:: show log dhcpv6 server
+
+   Show DHCPv6 server daemon log file
+```
+
+```{eval-rst}
+.. opcmd:: show log dhcpv6 client
+
+   Show logs from all DHCPv6 client processes.
+```
+
+```{eval-rst}
+.. opcmd:: show log dhcpv6 client interface <interface>
+
+   Show logs from specific `interface` DHCPv6 client process.
+```
+
+```{eval-rst}
+.. opcmd:: restart dhcpv6 server
+
+   To restart the DHCPv6 server
+```
+
+```{eval-rst}
+.. 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     non-temporary  NET1   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      non-temporary  NET1   00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff
+```
+
+:::{hint}
+Static mappings aren't shown. To show all states, use `show dhcp
+server leases state all`.
+:::
+
+```{eval-rst}
+.. opcmd:: show dhcpv6 server leases pool <pool>
+
+   Show only leases in the specified pool.
+```
+
+```{eval-rst}
+.. opcmd:: show dhcpv6 server leases sort <key>
+
+   Sort the output by the specified key. Possible keys: expires, duid, ip,
+   last_comm, pool, remaining, state, type (default = ip)
+```
+
+```{eval-rst}
+.. 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)
+```
diff --git a/docs/configuration/service/dns.md b/docs/configuration/service/dns.md
new file mode 100644
index 00000000..1e7462e4
--- /dev/null
+++ b/docs/configuration/service/dns.md
@@ -0,0 +1,476 @@
+(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.
+
+```{eval-rst}
+.. cfgcmd:: set service dns forwarding system
+
+   Forward incoming DNS queries to the DNS servers configured under the ``system
+   name-server`` nodes.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dns forwarding dhcp <interface>
+
+   Interfaces whose DHCP client nameservers to forward requests to.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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``).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dns forwarding domain <domain-name> recursion-desired
+
+   Set the "recursion desired" bit in requests to the upstream nameserver.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+## 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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-dynmaic-config)=
+
+## Configuration
+
+### {rfc}`2136` Based
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dns dynamic name <service-name> description <text>
+
+   Set description `<text>` for dynamic DNS service being configured.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dns dynamic name <service-name> server <server>
+
+   Configure the DNS `<server>` IP/FQDN used when updating this dynamic
+   assignment.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dns dynamic name <service-name> zone <zone>
+
+   Configure DNS `<zone>` to be updated.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dns dynamic name <service-name> host-name <record>
+
+   Configure DNS `<record>` which should be updated. This can be set multiple times.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dns dynamic name <service-name> ttl <ttl>
+
+   Configure optional TTL value on the given resource record. This defaults to
+   600 seconds.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dns dynamic interval <60-3600>
+
+   Specify interval in seconds to wait between Dynamic DNS updates.
+   The default is  300 seconds.
+```
+
+(dns-dynmaic-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.
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service dns dynamic name <service-name> description <text>
+
+   Set description `<text>` for dynamic DNS service being configured.
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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:
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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..0d764aba
--- /dev/null
+++ b/docs/configuration/service/eventhandler.md
@@ -0,0 +1,122 @@
+(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]
+>
+> [2. Add regex to the script]
+>
+> [3. Add a full path to the script]
+>
+> [4. Add optional parameters]
+
+## Event Handler Configuration Steps
+
+### 1. Create an event handler
+
+> ```{eval-rst}
+> .. 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
+
+> ```{eval-rst}
+> .. 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
+
+> ```{eval-rst}
+> .. 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
+
+> ```{eval-rst}
+> .. cfgcmd:: set service event-handler event <event-handler name> filter syslog-identifier <sylogid name>
+> ```
+>
+> This is an optional command. Filters log messages by syslog-identifier.
+>
+> ```{eval-rst}
+> .. 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.
+>
+> ```{eval-rst}
+> .. 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 recomend to use arguments. Using environments is more preffereble.
+> :::
+
+## 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 'eth2'
+> 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..c2e97453
--- /dev/null
+++ b/docs/configuration/service/https.md
@@ -0,0 +1,100 @@
+(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
+
+```{eval-rst}
+.. cfgcmd:: set service https allow-client address <address>
+
+   Only allow certain IP addresses or prefixes to access the https
+   webserver.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service https certificates ca-certificate <name>
+
+   Use CA certificate from PKI subsystem
+```
+
+```{eval-rst}
+.. cfgcmd:: set service https certificates certificate <name>
+
+   Use certificate from PKI subsystem
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service https listen-address <address>
+
+   Webserver should only listen on specified IP address
+```
+
+```{eval-rst}
+.. cfgcmd:: set service https port <number>
+
+   Webserver should listen on specified port.
+
+   Default: 443
+```
+
+```{eval-rst}
+.. cfgcmd:: set service https enable-http-redirect
+
+   Enable automatic redirect from http to https.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service https tls-version <1.2 | 1.3>
+
+   Select TLS version used.
+
+   This defaults to both 1.2 and 1.3.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service https vrf <name>
+
+   Start Webserver in given  VRF.
+```
+
+### API
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service https api debug
+
+   To enable debug messages. Available via {opcmd}`show log` or
+   {opcmd}`monitor log`
+```
+
+```{eval-rst}
+.. cfgcmd:: set service https api strict
+
+   Enforce strict path checking
+```
+
+## Example Configuration
+
+Set 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
+```
diff --git a/docs/configuration/service/ids.md b/docs/configuration/service/ids.md
new file mode 100644
index 00000000..813c7ca4
--- /dev/null
+++ b/docs/configuration/service/ids.md
@@ -0,0 +1,200 @@
+(ids)=
+
+# DDoS Protection
+
+## FastNetMon
+
+FastNetMon is a high-performance DDoS detector/sensor built on top of multiple
+packet capture engines: NetFlow, IPFIX, sFlow, AF_PACKET (port mirror). It can
+detect hosts in the deployed network sending or receiving large volumes of
+traffic, packets/bytes/flows per second and perform a configurable action to
+handle that event, such as calling a custom script.
+
+VyOS includes the FastNetMon Community Edition.
+
+### Configuration
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection alert-script <text>
+
+    Configure alert script that will be executed when an attack is detected.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection ban-time <1-4294967294>
+
+    Configure how long an IP (attacker) should be kept in blocked state.
+    Default value is 1900.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection direction [in | out]
+
+    Configure direction for processing traffic.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection exclude-network <x.x.x.x/x>
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection exlude-network <h:h:h:h:h:h:h:h/x>
+
+    Specify IPv4 and/or IPv6 networks which are going to be excluded.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection listen-interface <text>
+
+    Configure listen interface for mirroring traffic.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection mode [mirror | sflow]
+
+    Configure traffic capture mode.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection network <x.x.x.x/x>
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection network <h:h:h:h:h:h:h:h/x>
+
+    Specify IPv4 and/or IPv6 networks that should be protected/monitored.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection sflow listen-address <x.x.x.x>
+
+    Configure local IPv4 address to listen for sflow.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection sflow port <1-65535>
+
+    Configure port number to be used for sflow conection. Default port is 6343.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection threshold general
+   [fps | mbps | pps] <0-4294967294>
+
+    Configure general threshold parameters.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection threshold icmp
+   [fps | mbps | pps] <0-4294967294>
+
+    Configure ICMP threshold parameters.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection threshold tcp
+   [fps | mbps | pps] <0-4294967294>
+
+    Configure TCP threshold parameters
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ids ddos-protection threshold udp
+   [fps | mbps | pps] <0-4294967294>
+
+    Configure UDP threshold parameters
+```
+
+### Example
+
+A configuration example can be found in this section.
+In this simplified scenario, main things to be considered are:
+
+> - Network to be protected: 192.0.2.0/24 (public IPs use by
+>   customers)
+> - **ban-time** and **threshold**: these values are kept very low in order
+>   to easily identify and generate and attack.
+> - Direction: **in** and **out**. Protect public network from external
+>   attacks, and identify internal attacks towards internet.
+> - Interface **eth0** used to connect to upstream.
+
+Since we are analyzing attacks to and from our internal network, two types
+of attacks can be identified, and differents actions are needed:
+
+> - External attack: an attack from the internet towards an internal IP
+>   is identify. In this case, all connections towards such IP will be
+>   blocked
+> - Internal attack: an attack from the internal network (generated by a
+>   customer) towards the internet is identify. In this case, all connections
+>   from this particular IP/Customer will be blocked.
+
+So, firewall configuration needed for this setup:
+
+```none
+set firewall group address-group FNMS-DST-Block
+set firewall group address-group FNMS-SRC-Block
+
+set firewall ipv4 forward filter rule 10 action 'drop'
+set firewall ipv4 forward filter rule 10 description 'FNMS - block destination'
+set firewall ipv4 forward filter rule 10 destination group address-group 'FNMS-DST-Block'
+
+set firewall ipv4 forward filter rule 20 action 'drop'
+set firewall ipv4 forward filter rule 20 description 'FNMS - Block source'
+set firewall ipv4 forward filter rule 20 source group address-group 'FNMS-SRC-Block'
+```
+
+Then, FastNetMon configuration:
+
+```none
+set service ids ddos-protection alert-script '/config/scripts/fnm-alert.sh'
+set service ids ddos-protection ban-time '10'
+set service ids ddos-protection direction 'in'
+set service ids ddos-protection direction 'out'
+set service ids ddos-protection listen-interface 'eth0'
+set service ids ddos-protection mode 'mirror'
+set service ids ddos-protection network '192.0.2.0/24'
+set service ids ddos-protection threshold general pps '100'
+```
+
+And content of the script:
+
+```none
+#!/bin/bash
+
+# alert-script is called twice.
+# When an attack occurs, the program calls a bash script twice:
+# 1st time when threshold exceed
+# 2nd when we collect 100 packets for detailed audit of what happened.
+
+# Do nothing if “attack_details” is passed as an argument
+if [ "${4}" == "attack_details" ]; then
+    # Do nothing
+    exit
+fi
+# Arguments:
+ip=$1
+direction=$2
+pps_rate=$3
+action=$4
+
+logger -t FNMS "** Start - Running alert script **"
+
+if [ "${direction}" == "incoming" ] ; then
+    group="FNMS-DST-Block"
+    origin="external"
+else
+    group="FNMS-SRC-Block"
+    origin="internal"
+fi
+
+if [ "${action}" == "ban" ] ; then
+    logger -t FNMS "Attack detected for IP ${ip} and ${direction} direction from ${origin} network. Need to block IP address."
+    logger -t FNMS "Adding IP address ${ip} to firewall group ${group}."
+    sudo nft add element ip vyos_filter A_${group} { ${ip} }
+else
+    logger -t FNMS "Timeout for IP ${ip}, removing it from group ${group}."
+    sudo nft delete element ip vyos_filter A_${group} { ${ip} }
+fi
+logger -t FNMS "** End - Running alert script **"
+exit
+```
diff --git a/docs/configuration/service/index.md b/docs/configuration/service/index.md
new file mode 100644
index 00000000..4c11daaf
--- /dev/null
+++ b/docs/configuration/service/index.md
@@ -0,0 +1,30 @@
+# Service
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   broadcast-relay
+   config-sync
+   conntrack-sync
+   console-server
+   dhcp-relay
+   dhcp-server
+   dns
+   eventhandler
+   https
+   ids
+   ipoe-server
+   lldp
+   mdns
+   monitoring
+   ntp
+   pppoe-server
+   router-advert
+   salt-minion
+   snmp
+   ssh
+   tftp-server
+   webproxy
+```
diff --git a/docs/configuration/service/ipoe-server.md b/docs/configuration/service/ipoe-server.md
new file mode 100644
index 00000000..bdb55973
--- /dev/null
+++ b/docs/configuration/service/ipoe-server.md
@@ -0,0 +1,531 @@
+(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 configure on different interfaces, it will depend on each specific
+situation which interface will provide IPoE to clients. The clients 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 eth2 with the client mac address 08:00:27:2f:d8:06. 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'
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication interface <interface> mac <MAC>
+
+    Creates local IPoE user with username=**<interface>** and
+    password=**<MAC>** (mac-address)
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server default-pool <POOL-NAME>
+
+   Use this command to define default address pool name.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server interface <interface> mode <l2 | l3>
+
+  Set authentication backend. The configured authentication backend is used
+  for all queries.
+
+  * **l2**: It means that clients are on same network where interface
+    is.**(default)**
+  * **local**: It means that client are behind some router.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius server <server> port <port>
+
+  Configure RADIUS `<server>` and its required port for authentication requests.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius server <server> fail-time <time>
+
+  Mark RADIUS server as offline for this given `<time>` in seconds.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius server <server> disable
+
+  Temporary disable this RADIUS server.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius acct-timeout <timeout>
+
+  Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius dynamic-author server <address>
+
+  Specifies IP address for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius dynamic-author port <port>
+
+  Port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius dynamic-author key <secret>
+
+  Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius max-try <number>
+
+  Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius timeout <timeout>
+
+  Timeout to wait response from server (seconds)
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius source-address <address>
+
+  Source IPv4 address used in all RADIUS server queires.
+```
+
+```{eval-rst}
+.. 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.
+:::
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server authentication radius rate-limit enable
+
+  Enables bandwidth shaping via RADIUS.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server extended-scripts on-change <path_to_script>
+
+  Script to run when session interface changed by RADIUS CoA handling
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server extended-scripts on-down <path_to_script>
+
+  Script to run when session interface going to terminate
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server extended-scripts on-pre-up <path_to_script>
+
+  Script to run before session interface comes up
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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>
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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`
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server interface <interface> external-dhcp giaddr <x.x.x.x>
+
+   Specifies relay agent IP addre
+
+```
+
+### Global Advanced options
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server description <description>
+
+  Set description.
+```
+
+```{eval-rst}
+.. cfgcmd::  set service ipoe-server limits burst <value>
+
+  Burst count
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server limits connection-limit <value>
+
+  Acceptable rate of connections (e.g. 1/min, 60/sec)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server limits timeout <value>
+
+  Timeout in seconds
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server max-concurrent-sessions
+
+  Maximum number of concurrent session start attempts
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server shaper fwmark <1-2147483647>
+
+  Match firewall mark value
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ipoe-server snmp master-agent
+
+  Enable SNMP
+```
+
+## Monitoring
+
+```{eval-rst}
+.. 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:~$sudo journalctl -u accel-ppp@ipoe -b 0
+
+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>]
+```
+
+```{include} /_include/common-references.txt
+```
+
+[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..cb287dbf
--- /dev/null
+++ b/docs/configuration/service/lldp.md
@@ -0,0 +1,158 @@
+(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
+
+```{eval-rst}
+.. cfgcmd:: set service lldp
+
+   Enable LLDP service
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service lldp interface <interface> disable
+
+   Disable transmit of LLDP frames on given `<interface>`. Useful to exclude
+   certain interfaces from LLDP when ``all`` have been enabled.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service lldp snmp
+
+   Enable SNMP queries of the LLDP database
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+     -------------------------------------------------------------------------------
+```
+
+```{eval-rst}
+.. opcmd:: show lldp neighbors interface <interface>
+
+   Show LLDP neighbors connected via interface `<interface>`.
+```
+
+```{eval-rst}
+.. opcmd:: show log lldp
+
+   Used for troubleshooting.
+```
diff --git a/docs/configuration/service/mdns.md b/docs/configuration/service/mdns.md
new file mode 100644
index 00000000..6ff1804b
--- /dev/null
+++ b/docs/configuration/service/mdns.md
@@ -0,0 +1,138 @@
+# 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service mdns repeater disable
+
+   mDNS repeater can be temporarily disabled without deleting the service using
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. opcmd:: restart mdns repeater
+
+  Restart mDNS repeater service.
+```
+
+```{eval-rst}
+.. opcmd:: show log mdns repeater
+
+  Show logs for mDNS repeater service.
+```
+
+```{eval-rst}
+.. 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..0e5d92f9
--- /dev/null
+++ b/docs/configuration/service/monitoring.md
@@ -0,0 +1,191 @@
+# Monitoring
+
+## Azure-data-explorer
+
+Telegraf output plugin [azure-data-explorer]
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-id <client-id>
+
+   Authentication application client-id.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-secret <client-secret>
+
+   Authentication application client-secret.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication tenant-id <tenant-id>
+
+   Authentication application tenant-id
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer database <name>
+
+   Remote database name.
+```
+
+```{eval-rst}
+.. 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``.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer table <name>
+
+   Name of the single table Only if set group-metrics single-table.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf azure-data-explorer url <url>
+
+   Remote URL.
+```
+
+## Prometheus-client
+
+Telegraf output plugin [prometheus-client]
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf prometheus-client
+
+   Output plugin Prometheus client
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf prometheus-client allow-from <prefix>
+
+   Networks allowed to query this server
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf prometheus-client authentication username <username>
+
+   HTTP basic authentication username
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf prometheus-client authentication password <password>
+
+   HTTP basic authentication username
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf prometheus-client listen-address <address>
+
+   Local IP addresses to listen on
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf prometheus-client metric-version <1 | 2>
+
+   Metris version, the default is ``2``
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf splunk authentication insecure
+
+   Use TLS but skip host validation
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf splunk authentication token <token>
+
+   Authorization token
+```
+
+```{eval-rst}
+.. 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'
+```
+
+## Telegraf
+
+Monitoring functionality with `telegraf` and `InfluxDB 2` is provided.
+Telegraf is the open source server agent to help you collect metrics, events
+and logs from your routers.
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf influxdb authentication organization <organization>
+
+   Authentication organization name
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf influxdb authentication token <token>
+
+   Authentication token
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf bucket <bucket>
+
+   Remote ``InfluxDB`` bucket name
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf influxdb port <port>
+
+   Remote port
+```
+
+```{eval-rst}
+.. cfgcmd:: set service monitoring telegraf influxdb url <url>
+
+   Remote URL
+
+```
+
+## Example
+
+An example of a configuration that sends `telegraf` metrics to remote
+`InfluxDB 2`
+
+```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'
+```
+
+[azure-data-explorer]: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer
+[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..e0f6b3ab
--- /dev/null
+++ b/docs/configuration/service/ntp.md
@@ -0,0 +1,124 @@
+(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
+
+```{eval-rst}
+.. 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``
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ntp server <address> <noselect | nts | pool | prefer>
+
+   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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ntp vrf <name>
+
+   Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+```{eval-rst}
+.. 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
+```
diff --git a/docs/configuration/service/pppoe-server.md b/docs/configuration/service/pppoe-server.md
new file mode 100644
index 00000000..d0c72f00
--- /dev/null
+++ b/docs/configuration/service/pppoe-server.md
@@ -0,0 +1,789 @@
+---
+lastproofread: '2022-09-17'
+---
+
+(pppoe-server)=
+
+# PPPoE Server
+
+VyOS utilizes [accel-ppp] 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server access-concentrator <name>
+
+   Use this command to set a name for this PPPoE-server access
+   concentrator.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server default-pool <POOL-NAME>
+
+   Use this command to define default address pool name.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server interface <interface>
+
+   Use this command to define the interface the PPPoE server will use to
+   listen for PPPoE clients.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius
+   server <server> port <port>
+
+  Configure RADIUS `<server>` and its required port for authentication requests.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius
+   server <server> fail-time <time>
+
+  Mark RADIUS server as offline for this given `<time>` in seconds.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius
+   server <server> disable
+
+  Temporary disable this RADIUS server.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius
+   acct-timeout <timeout>
+
+  Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius
+   dynamic-author server <address>
+
+  Specifies IP address for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius
+   dynamic-author port <port>
+
+  Port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius dynamic-author
+   key <secret>
+
+  Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius
+   max-try <number>
+
+  Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius
+   timeout <timeout>
+
+  Timeout to wait response from server (seconds)
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius
+   source-address <address>
+
+  Source IPv4 address used in all RADIUS server queires.
+```
+
+```{eval-rst}
+.. 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.
+:::
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication radius
+   rate-limit enable
+
+  Enables bandwidth shaping via RADIUS.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication local-users username
+   <user> rate-limit download <bandwidth>
+
+  Download bandwidth limit in kbit/s for `<user>`.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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)
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server ppp-options ipv6-accept-peer-interface-id
+
+  Accept peer interface identifier. By default is not defined.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server extended-scripts on-change <path_to_script>
+
+  Script to run when session interface changed by RADIUS CoA handling
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server extended-scripts on-down <path_to_script>
+
+  Script to run when session interface going to terminate
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server extended-scripts on-pre-up <path_to_script>
+
+  Script to run before session interface comes up
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication local-users
+   username <user> disable
+
+  Disable `<user>` account.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server authentication local-users
+   username <user> static-ip <address>
+
+  Assign static IP address to `<user>` account.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server ppp-options disable-ccp
+
+  Disable Compression Control Protocol (CCP).
+  CCP is enabled by default.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server ppp-options mru <number>
+
+  Defines preferred MRU. By default is not defined.
+```
+
+### Global Advanced options
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server description <description>
+
+  Set description.
+```
+
+```{eval-rst}
+.. cfgcmd::  set service pppoe-server limits burst <value>
+
+  Burst count
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server limits connection-limit <value>
+
+  Acceptable rate of connections (e.g. 1/min, 60/sec)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server limits timeout <value>
+
+  Timeout in seconds
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server mtu
+
+  Maximum Transmission Unit (MTU) (default: **1492**)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server max-concurrent-sessions
+
+  Maximum number of concurrent session start attempts
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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)**
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server shaper fwmark <1-2147483647>
+
+  Match firewall mark value
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server snmp master-agent
+
+  Enable SNMP
+```
+
+```{eval-rst}
+.. cfgcmd:: set service pppoe-server wins-server <address>
+
+  Windows Internet Name Service (WINS) servers propagated to client
+```
+
+## Monitoring
+
+```{eval-rst}
+.. 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
+```
+
+```{include} /_include/common-references.txt
+```
+
+[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..73a9718a
--- /dev/null
+++ b/docs/configuration/service/router-advert.md
@@ -0,0 +1,125 @@
+(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
+
+```{eval-rst}
+.. cfgcmd:: set service router-advert interface <interface> ...
+```
+
+
+```{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, exluded 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"
+```
+
+
+### Advertising a Prefix
+
+```{eval-rst}
+.. 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 will take the IPv6 GUA prefix assigned to the interface,
+    which comes in handy when using DHCPv6-PD.
+```
+
+
+```{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
+
+```{eval-rst}
+.. 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``
+```
+
+
+```{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:
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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/broadcast-relay.rst b/docs/configuration/service/rst-broadcast-relay.rst
index b6e2bed7..b6e2bed7 100644
--- a/docs/configuration/service/broadcast-relay.rst
+++ b/docs/configuration/service/rst-broadcast-relay.rst
diff --git a/docs/configuration/service/config-sync.rst b/docs/configuration/service/rst-config-sync.rst
index d0449a78..d0449a78 100644
--- a/docs/configuration/service/config-sync.rst
+++ b/docs/configuration/service/rst-config-sync.rst
diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/rst-conntrack-sync.rst
index de86450e..de86450e 100644
--- a/docs/configuration/service/conntrack-sync.rst
+++ b/docs/configuration/service/rst-conntrack-sync.rst
diff --git a/docs/configuration/service/console-server.rst b/docs/configuration/service/rst-console-server.rst
index c9ea7f77..c9ea7f77 100644
--- a/docs/configuration/service/console-server.rst
+++ b/docs/configuration/service/rst-console-server.rst
diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/rst-dhcp-relay.rst
index dc45d071..dc45d071 100644
--- a/docs/configuration/service/dhcp-relay.rst
+++ b/docs/configuration/service/rst-dhcp-relay.rst
diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/rst-dhcp-server.rst
index 7df69e45..7df69e45 100644
--- a/docs/configuration/service/dhcp-server.rst
+++ b/docs/configuration/service/rst-dhcp-server.rst
diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/rst-dns.rst
index c6deb179..c6deb179 100644
--- a/docs/configuration/service/dns.rst
+++ b/docs/configuration/service/rst-dns.rst
diff --git a/docs/configuration/service/eventhandler.rst b/docs/configuration/service/rst-eventhandler.rst
index 15f08239..15f08239 100644
--- a/docs/configuration/service/eventhandler.rst
+++ b/docs/configuration/service/rst-eventhandler.rst
diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/rst-https.rst
index 973c5355..973c5355 100644
--- a/docs/configuration/service/https.rst
+++ b/docs/configuration/service/rst-https.rst
diff --git a/docs/configuration/service/ids.rst b/docs/configuration/service/rst-ids.rst
index 3e508d50..3e508d50 100644
--- a/docs/configuration/service/ids.rst
+++ b/docs/configuration/service/rst-ids.rst
diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/rst-index.rst
index abb77ef4..abb77ef4 100644
--- a/docs/configuration/service/index.rst
+++ b/docs/configuration/service/rst-index.rst
diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/rst-ipoe-server.rst
index 3f9d2cee..3f9d2cee 100644
--- a/docs/configuration/service/ipoe-server.rst
+++ b/docs/configuration/service/rst-ipoe-server.rst
diff --git a/docs/configuration/service/lldp.rst b/docs/configuration/service/rst-lldp.rst
index 12a9e0b6..12a9e0b6 100644
--- a/docs/configuration/service/lldp.rst
+++ b/docs/configuration/service/rst-lldp.rst
diff --git a/docs/configuration/service/mdns.rst b/docs/configuration/service/rst-mdns.rst
index b4ca1fd1..b4ca1fd1 100644
--- a/docs/configuration/service/mdns.rst
+++ b/docs/configuration/service/rst-mdns.rst
diff --git a/docs/configuration/service/monitoring.rst b/docs/configuration/service/rst-monitoring.rst
index 245af067..245af067 100644
--- a/docs/configuration/service/monitoring.rst
+++ b/docs/configuration/service/rst-monitoring.rst
diff --git a/docs/configuration/service/ntp.rst b/docs/configuration/service/rst-ntp.rst
index f82baa34..f82baa34 100644
--- a/docs/configuration/service/ntp.rst
+++ b/docs/configuration/service/rst-ntp.rst
diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/rst-pppoe-server.rst
index 6d818c70..6d818c70 100644
--- a/docs/configuration/service/pppoe-server.rst
+++ b/docs/configuration/service/rst-pppoe-server.rst
diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/rst-router-advert.rst
index 3efc3454..3efc3454 100644
--- a/docs/configuration/service/router-advert.rst
+++ b/docs/configuration/service/rst-router-advert.rst
diff --git a/docs/configuration/service/salt-minion.rst b/docs/configuration/service/rst-salt-minion.rst
index aa747c36..aa747c36 100644
--- a/docs/configuration/service/salt-minion.rst
+++ b/docs/configuration/service/rst-salt-minion.rst
diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/rst-snmp.rst
index b444ab85..b444ab85 100644
--- a/docs/configuration/service/snmp.rst
+++ b/docs/configuration/service/rst-snmp.rst
diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/rst-ssh.rst
index 4770c950..4770c950 100644
--- a/docs/configuration/service/ssh.rst
+++ b/docs/configuration/service/rst-ssh.rst
diff --git a/docs/configuration/service/tftp-server.rst b/docs/configuration/service/rst-tftp-server.rst
index 84acf3d4..84acf3d4 100644
--- a/docs/configuration/service/tftp-server.rst
+++ b/docs/configuration/service/rst-tftp-server.rst
diff --git a/docs/configuration/service/webproxy.rst b/docs/configuration/service/rst-webproxy.rst
index a6c5ff0a..a6c5ff0a 100644
--- a/docs/configuration/service/webproxy.rst
+++ b/docs/configuration/service/rst-webproxy.rst
diff --git a/docs/configuration/service/salt-minion.md b/docs/configuration/service/salt-minion.md
new file mode 100644
index 00000000..8490783f
--- /dev/null
+++ b/docs/configuration/service/salt-minion.md
@@ -0,0 +1,53 @@
+(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 Poject Documentaion](https://docs.saltproject.io/en/latest/contents.html)
+
+## Configuration
+
+```{eval-rst}
+.. cfgcmd:: set service salt-minion hash <type>
+
+   The hash type used when discovering file on master server (default: sha256)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service salt-minion id <id>
+
+   Explicitly declare ID for this minion to use (default: hostname)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service salt-minion interval <1-1440>
+
+   Interval in minutes between updates (default: 60)
+```
+
+```{eval-rst}
+.. cfgcmd:: set service salt-minion master <hostname | IP>
+
+    The hostname or IP address of the master
+```
+
+```{eval-rst}
+.. 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..c4976318
--- /dev/null
+++ b/docs/configuration/service/snmp.md
@@ -0,0 +1,259 @@
+(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.png
+: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..c038e27d
--- /dev/null
+++ b/docs/configuration/service/ssh.md
@@ -0,0 +1,304 @@
+(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.
+:::
+
+```{eval-rst}
+.. seealso:: SSH {ref}`ssh_key_based_authentication`
+```
+
+## Configuration
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ssh listen-address <address>
+
+  Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be
+  defined.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ssh ciphers <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``
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ssh disable-password-authentication
+
+  Disable password based authentication. Login via SSH keys only. This hardens
+  security!
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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``
+```
+
+```{eval-rst}
+.. 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``.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ssh client-keepalive-interval <interval>
+
+  Specify timeout interval for keepalive message in seconds.
+```
+
+```{eval-rst}
+.. 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``.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ssh loglevel <quiet | fatal | error | info | verbose>
+
+  Set the ``sshd`` log level. The default is ``info``.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ssh vrf <name>
+
+  Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+## 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.
+
+```{eval-rst}
+.. cfgcmd:: set service ssh dynamic-protection
+
+  Allow ``ssh`` dynamic-protection.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ssh dynamic-protection allow-from <address | prefix>
+
+  Whitelist of addresses and networks. Always allow inbound connections from
+  these systems.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set service ssh dynamic-protection detect-time <sec>
+
+  Remember source IP in seconds before reset their score. The default is 1800.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. opcmd:: restart ssh
+
+  Restart the SSH daemon process, the current session is not affected, only the
+  background daemon is restarted.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. opcmd:: show log ssh
+
+  Show SSH server log.
+```
+
+```{eval-rst}
+.. opcmd:: monitor log ssh
+
+  Follow the SSH server log.
+```
+
+```{eval-rst}
+.. opcmd:: show log ssh dynamic-protection
+
+  Show SSH dynamic-protection log.
+```
+
+```{eval-rst}
+.. opcmd:: monitor log ssh dynamic-protection
+
+  Follow the SSH dynamic-protection log.
+```
+
+```{eval-rst}
+.. opcmd:: show ssh dynamic-protection
+
+  Show list of IPs currently blocked by SSH dynamic-protection.
+```
+
+```{eval-rst}
+.. opcmd:: show ssh fingerprints
+
+  Show SSH server public key fingerprints.
+```
+
+```{eval-rst}
+.. opcmd:: show ssh fingerprints ascii
+
+  Show SSH server public key fingerprints, including a visual ASCII art representation.
+```
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..b5f926b7
--- /dev/null
+++ b/docs/configuration/system/conntrack.md
@@ -0,0 +1,365 @@
+# 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
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack table-size <1-50000000>
+    :defaultvalue:
+
+    The connection tracking table contains one entry for each connection being
+    tracked by the system.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack modules h323
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack modules nfs
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack modules pptp
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack modules sip
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack modules sqlnet
+```
+
+```{eval-rst}
+.. 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`.
+
+```
+
+### Define Conection Timeouts
+
+VyOS supports setting timeouts for connections according to the
+connection type. You can set timeout values for generic connections, for ICMP
+connections, UDP connections, or for TCP connections in a number of different
+states.
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout icmp <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout other <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout tcp close <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout tcp close-wait <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout tcp established <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout tcp fin-wait <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout tcp last-ack <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout tcp syn-recv <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout tcp syn-sent <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout tcp time-wait <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout udp other <1-21474836>
+    :defaultvalue:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout udp stream <1-21474836>
+    :defaultvalue:
+
+    Set the timeout in secounds for a protocol or state.
+
+```
+
+You can also 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 rule <1-9999> description <test>
+
+    Set a rule description.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination address <ip-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source address <ip-address>
+
+    set a destination and/or source address. Accepted input:
+
+    .. code-block:: none
+
+        <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
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination port <value>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> 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``
+
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol icmp <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol other <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close-wait <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp established <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp fin-wait <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp last-ack <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-recv <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-sent <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp time-wait <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp other <1-21474836>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp stream <1-21474836>
+
+    Set the timeout in secounds for a protocol or state in a custom rule.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836>
+    :defaultvalue:
+
+    Set the maximum number of TCP half-open connections.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack tcp loose <enable | disable>
+    :defaultvalue:
+
+    Policy to track previously established connections.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647>
+    :defaultvalue:
+
+    Set the number of TCP maximum retransmit attempts.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack ignore rule <1-9999> description <text>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack ignore rule <1-9999> destination address <ip-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack ignore rule <1-9999> destination port <port>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack ignore rule <1-9999> inbound-interface <interface>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack ignore rule <1-9999> protocol <protocol>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack ignore rule <1-9999> source address <ip-address>
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack ignore rule <1-9999> source port <port>
+
+    Customized ignore rules, based on a packet and flow selector.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log icmp destroy
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log icmp new
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log icmp update
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log other destroy
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log other new
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log other update
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log tcp destroy
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log tcp new
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log tcp update close-wait
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log tcp update established
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log tcp update fin-wait
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log tcp update last-ack
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log tcp update syn-received
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log tcp update time-wait
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log udp destroy
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log udp new
+```
+
+```{eval-rst}
+.. cfgcmd:: set system conntrack log udp update
+
+    Log the connection tracking events per protocol.
+```
diff --git a/docs/configuration/system/console.md b/docs/configuration/system/console.md
new file mode 100644
index 00000000..adcaef8c
--- /dev/null
+++ b/docs/configuration/system/console.md
@@ -0,0 +1,47 @@
+(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.
+
+```{eval-rst}
+.. 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
+   * ``ttyUSBX`` - USB Serial device name
+   * ``hvc0`` - Xen console
+```
+
+```{eval-rst}
+.. 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.
+```
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..9b328fff
--- /dev/null
+++ b/docs/configuration/system/flow-accounting.md
@@ -0,0 +1,248 @@
+(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 two different protocols: NetFlow (versions 5, 9 and
+10/IPFIX) and sFlow. 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.
+
+```{eval-rst}
+.. 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 whould 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:
+
+```{eval-rst}
+.. cfgcmd:: set system flow-accounting disable-imt
+
+   If you need to sample also egress traffic, you may want to
+   configure egress flow-accounting:
+```
+
+```{eval-rst}
+.. 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:
+```
+
+```{eval-rst}
+.. 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:
+```
+
+```{eval-rst}
+.. cfgcmd:: set system flow-accounting syslog-facility <facility>
+
+   TBD
+```
+
+### Flow Export
+
+In addition to displaying flow accounting information locally, one can also
+exported them to a collection server.
+
+#### NetFlow
+
+```{eval-rst}
+.. 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`
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system flow-accounting netflow source-ip <address>
+
+   IPv4 or IPv6 source address of NetFlow packets
+```
+
+```{eval-rst}
+.. cfgcmd:: set system flow-accounting netflow engine-id <id>
+
+   NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+#### sFlow
+
+:::{note}
+Using `system sflow` is recommended in favor of
+`system flow-accounting`. See [sflow](sflow.html)
+:::
+
+```{eval-rst}
+.. cfgcmd:: set system flow-accounting sflow server <address>
+
+   Configure address of sFlow collector. sFlow server at `<address>` can
+   be an IPv4 or IPv6 address. But you cannot export to both IPv4 and
+   IPv6 collectors at the same time!
+```
+
+```{eval-rst}
+.. cfgcmd:: set system flow-accounting sflow sampling-rate <rate>
+
+   Enable sampling of packets, which will be transmitted to sFlow collectors.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system flow-accounting sflow agent-address <address>
+
+   Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you
+   must set the same protocol, which is used for sFlow collector addresses. By
+   default, using router-id from BGP or OSPF protocol, or the primary IP
+   address from the first interface.
+```
+
+### 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.
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+```
diff --git a/docs/configuration/system/frr.md b/docs/configuration/system/frr.md
new file mode 100644
index 00000000..37e6e502
--- /dev/null
+++ b/docs/configuration/system/frr.md
@@ -0,0 +1,44 @@
+(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 require either a restart of the routing daemon, or a reboot of the system.
+
+```{eval-rst}
+.. cfgcmd:: set system frr bmp
+
+   Enable {abbr}`BMP (BGP Monitoring Protocol)` support
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system frr irdp
+
+   Enable ICMP Router Discovery Protocol support
+```
+
+```{eval-rst}
+.. cfgcmd:: set system frr snmp <daemon>
+
+   Enable SNMP support for an individual routing daemon.
+
+   Supported daemons:
+
+   - bgpd
+   - isisd
+   - ldpd
+   - ospf6d
+   - ospfd
+   - ripd
+   - zebra
+```
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..624a8434
--- /dev/null
+++ b/docs/configuration/system/index.md
@@ -0,0 +1,36 @@
+# System
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   acceleration
+   conntrack
+   console
+   flow-accounting
+   frr
+   host-name
+   ip
+   ipv6
+   lcd
+   login
+   name-server
+   option
+   proxy
+   sflow
+   syslog
+   sysctl
+   task-scheduler
+   time-zone
+   updates
+
+```
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   default-route
+```
diff --git a/docs/configuration/system/ip.md b/docs/configuration/system/ip.md
new file mode 100644
index 00000000..2445509d
--- /dev/null
+++ b/docs/configuration/system/ip.md
@@ -0,0 +1,110 @@
+# IP
+
+## System configuration commands
+
+```{eval-rst}
+.. cfgcmd:: set system ip disable-forwarding
+
+   Use this command to disable IPv4 forwarding on all interfaces.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. cfgcmd:: set system ip multipath layer4-hashing
+
+   Use this command to use Layer 4 information for IPv4 ECMP hashing.
+```
+
+### Zebra/Kernel route filtering
+
+Zebra supports prefix-lists and Route Mapss 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.
+
+```{eval-rst}
+.. 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, connected, eigrp, isis, kernel,
+   ospf, rip, static, table
+
+   .. 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 wan't to e.g. allow BGP to peer across the default route.
+
+```{eval-rst}
+.. 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..80f0e33a
--- /dev/null
+++ b/docs/configuration/system/ipv6.md
@@ -0,0 +1,235 @@
+# IPv6
+
+## System configuration commands
+
+```{eval-rst}
+.. cfgcmd:: set system ipv6 disable-forwarding
+
+   Use this command to disable IPv6 forwarding on all interfaces.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. cfgcmd:: set system ipv6 strict-dad
+
+   Use this command to disable IPv6 operation on interface when
+   Duplicate Address Detection fails on Link-Local address.
+```
+
+```{eval-rst}
+.. 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 Mapss 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.
+
+```{eval-rst}
+.. 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, connected, isis, kernel, ospfv3,
+   ripng, static, table
+
+   .. 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 wan't to e.g. allow BGP to peer across the default route.
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. opcmd:: show ipv6 neighbors
+
+   Use this command to show IPv6 Neighbor Discovery Protocol information.
+```
+
+```{eval-rst}
+.. opcmd:: show ipv6 groups
+
+   Use this command to show IPv6 multicast group membership.
+```
+
+```{eval-rst}
+.. opcmd:: show ipv6 forwarding
+
+   Use this command to show IPv6 forwarding status.
+```
+
+```{eval-rst}
+.. 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
+        vrf           Show IPv6 routes in VRF
+
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. opcmd:: show ipv6 bgp
+
+   Use this command to show IPv6 Border Gateway Protocol information.
+
+
+   In addition, you can specify many other parameters to get BGP
+   information:
+
+   .. code-block:: none
+
+      vyos@vyos:~$ show ipv6 bgp
+      Possible completions:
+        <Enter>       Execute the current command
+        <X:X::X:X>    Show BGP information for given address or prefix
+        <X:X::X:X/M>
+        community     Show routes matching the communities
+        community-list
+                      Show routes matching the community-list
+        filter-list   Show routes conforming to the filter-list
+        large-community
+                      Show routes matching the large-community-list
+        large-community-list
+        neighbors     Show detailed information on TCP and BGP neighbor connections
+        prefix-list   Show routes matching the prefix-list
+        regexp        Show routes matching the AS path regular expression
+        route-map     Show BGP routes matching the specified route map
+        summary       Show summary of BGP neighbor status
+
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. opcmd:: show ipv6 ripng
+
+   Use this command to get information about the RIPNG protocol
+```
+
+```{eval-rst}
+.. opcmd:: show ipv6 ripng status
+
+   Use this command to show the status of the RIPNG protocol
+
+```
+
+### Reset commands
+
+```{eval-rst}
+.. opcmd:: reset bgp ipv6 <address>
+
+   Use this command to clear Border Gateway Protocol statistics or
+   status.
+
+```
+
+```{eval-rst}
+.. opcmd:: reset ipv6 neighbors <address | interface>
+
+   Use this command to reset IPv6 Neighbor Discovery Protocol cache for
+   an address or interface.
+```
+
+```{eval-rst}
+.. 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.
+```
diff --git a/docs/configuration/system/lcd.md b/docs/configuration/system/lcd.md
new file mode 100644
index 00000000..c857ae34
--- /dev/null
+++ b/docs/configuration/system/lcd.md
@@ -0,0 +1,46 @@
+(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
+
+```{eval-rst}
+.. 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 refor to: {ref}`hardware_usb`.
+```
+
+```{eval-rst}
+.. 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_.
+```
+
+```{include} /_include/common-references.txt
+```
diff --git a/docs/configuration/system/login.md b/docs/configuration/system/login.md
new file mode 100644
index 00000000..562ed419
--- /dev/null
+++ b/docs/configuration/system/login.md
@@ -0,0 +1,474 @@
+---
+lastproofread: '2022-10-15'
+---
+
+(user-management)=
+
+# Login/User Management
+
+The default VyOS user account (`vyos`), as well as newly created user accounts,
+have all capabilities to configure the system. All accounts have sudo
+capabilities and therefore can operate as root on the system.
+
+Both local administered and remote administered {abbr}`RADIUS (Remote
+Authentication Dial-In User Service)` accounts are supported.
+
+## Local
+
+```{eval-rst}
+.. cfgcmd:: set system login user <name> full-name "<string>"
+
+   Create new system user with username `<name>` and real-name specified by
+   `<string>`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login user <name> authentication plaintext-password
+   <password>
+
+   Specify the plaintext password user by user `<name>` on this system. The
+   plaintext password will be automatically transferred into a secure hashed
+   password and not saved anywhere in plaintext.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login user <name> authentication encrypted-password
+   <password>
+
+   Setup encrypted password for given username. This is useful for
+   transferring a hashed password from system to system.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login user <name> disable
+
+   Disable (lock) account. User will not be able to log in.
+```
+
+(ssh_key_based_authentication)=
+
+### Key Based Authentication
+
+It is highly recommended to use SSH key authentication. By default there is
+only one user (`vyos`), and you can assign any number of keys to that user.
+You can generate a ssh key with the `ssh-keygen` command on your local
+machine, which will (by default) save it as `~/.ssh/id_rsa.pub`.
+
+Every SSH key comes in three parts:
+
+`ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com`
+
+Only the type (`ssh-rsa`) and the key (`AAAB3N...`) are used. Note that the
+key will usually be several hundred characters long, and you will need to copy
+and paste it. Some terminal emulators may accidentally split this over several
+lines. Be attentive when you paste it that it only pastes as a single line.
+The third part is simply an identifier, and is for your own reference.
+
+```{eval-rst}
+.. seealso:: SSH {ref}`ssh_operation`
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login user <username> authentication public-keys
+   <identifier> key <key>
+
+   Assign the SSH public key portion `<key>` identified by per-key
+   `<identifier>` to the local user `<username>`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login user <username> authentication public-keys
+   <identifier> type <type>
+
+   Every SSH public key portion referenced by `<identifier>` requires the
+   configuration of the `<type>` of public-key used. This type can be any of:
+
+   * ``ecdsa-sha2-nistp256``
+   * ``ecdsa-sha2-nistp384``
+   * ``ecdsa-sha2-nistp521``
+   * ``ssh-dss``
+   * ``ssh-ed25519``
+   * ``ssh-rsa``
+
+   .. note:: You can assign multiple keys to the same user by using a unique
+      identifier per SSH key.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login user <username> authentication public-keys
+   <identifier> options <options>
+
+   Set the options for this public key. See the ssh ``authorized_keys`` man
+   page for details of what you can specify here. To place a ``"``
+   character in the options field, use ``&quot;``, for example
+   ``from=&quot;10.0.0.0/24&quot;`` to restrict where the user
+   may connect from when using this key.
+```
+
+### MFA/2FA authentication using OTP (one time passwords)
+
+It is possible to enhance authentication security by using the {abbr}`2FA
+(Two-factor authentication)`/{abbr}`MFA (Multi-factor authentication)` feature
+together with {abbr}`OTP (One-Time-Pad)` on VyOS. {abbr}`2FA (Two-factor
+authentication)`/{abbr}`MFA (Multi-factor authentication)` is configured
+independently per each user. If an OTP key is configured for a user, 2FA/MFA
+is automatically enabled for that particular user. If a user does not have an
+OTP key configured, there is no 2FA/MFA check for that user.
+
+```{eval-rst}
+.. cfgcmd:: set system login user <username> authentication otp key <key>
+
+   Enable OTP 2FA for user `username` with default settings, using the BASE32
+   encoded 2FA/MFA key specified by `<key>`.
+```
+
+#### Optional/default settings
+
+```{eval-rst}
+.. cfgcmd:: set system login user <username> authentication otp rate-limit <limit>
+   :defaultvalue:
+
+   Limit logins to `<limit>` per every ``rate-time`` seconds. Rate limit
+   must be between 1 and 10 attempts.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login user <username> authentication otp rate-time <seconds>
+   :defaultvalue:
+
+   Limit logins to ``rate-limit`` attemps per every `<seconds>`. Rate time must
+   be between 15 and 600 seconds.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login user <username> authentication otp window-size <size>
+   :defaultvalue:
+
+   Set window of concurrently valid codes.
+
+   By default, a new token is generated every 30 seconds by the mobile
+   application. In order to compensate for possible time-skew between
+   the client and the server, an extra token before and after the current
+   time is allowed. This allows for a time skew of up to 30 seconds
+   between authentication server and client.
+
+   For example, if problems with poor time synchronization are experienced,
+   the window can be increased from its default size of 3 permitted codes
+   (one previous code, the current code, the next code) to 17 permitted codes
+   (the 8 previous codes, the current code, and the 8 next codes). This will
+   permit for a time skew of up to 4 minutes between client and server.
+
+   The window size must be between 1 and 21.
+```
+
+#### OTP-key generation
+
+The following command can be used to generate the OTP key as well
+as the CLI commands to configure them:
+
+```{eval-rst}
+.. cfgcmd:: generate system login username <username> otp-key hotp-time
+   rate-limit <1-10> rate-time <15-600> window-size <1-21>
+```
+
+An example of key generation:
+
+```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 OTP key for user
+
+To display the configured OTP user key, use the command:
+
+```{eval-rst}
+.. cfgcmd:: sh system login authentication user <username> otp
+   <full|key-b32|qrcode|uri>
+```
+
+An example:
+
+```none
+vyos@vyos:~$ sh system login authentication user otptester otp full
+# 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'
+```
+
+Once a user has 2FA/OTP configured against their account, they must login
+using their password with the OTP code appended to it.
+For example: If the users password is vyosrocks and the OTP code is 817454
+then they would enter their password as vyosrocks817454
+
+## RADIUS
+
+In large deployments it is not reasonable to configure each user individually
+on every system. VyOS supports using {abbr}`RADIUS (Remote Authentication
+Dial-In User Service)` servers as backend for user authentication.
+
+### Configuration
+
+```{eval-rst}
+.. cfgcmd:: set system login radius server <address> key <secret>
+
+   Specify the IP `<address>` of the RADIUS server user with the pre-shared-secret
+   given in `<secret>`.
+
+   Multiple servers can be specified.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login radius server <address> port <port>
+
+   Configure the discrete port under which the RADIUS server can be reached.
+
+   This defaults to 1812.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login radius server <address> disable
+
+   Temporary disable this RADIUS server. It won't be queried.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login radius server <address> timeout <timeout>
+
+   Setup the `<timeout>` in seconds when querying the RADIUS server.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login radius source-address <address>
+
+   RADIUS servers could be hardened by only allowing certain IP addresses to
+   connect. As of this the source address of each RADIUS query can be
+   configured.
+
+   If unset, incoming connections to the RADIUS server will use the nearest
+   interface address pointing towards the server - making it error prone on
+   e.g. OSPF networks when a link fails and a backup route is taken.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login radius vrf <name>
+
+   Source all connections to the RADIUS servers from given VRF `<name>`.
+```
+
+:::{hint}
+If you want to have admin users to authenticate via RADIUS it is
+essential to sent the `Cisco-AV-Pair shell:priv-lvl=15` attribute. Without
+the attribute you will only get regular, non privilegued, system users.
+:::
+
+## TACACS+
+
+In addition to {abbr}`RADIUS (Remote Authentication Dial-In User Service)`,
+{abbr}`TACACS (Terminal Access Controller Access Control System)` can also be
+found in large deployments.
+VyOS only supports `Authentication` via `TACACS+` servers but does not support `Authorization` or `Accounting` yet
+
+TACACS is defined in {rfc}`8907`.
+
+(tacacs-configuration)=
+
+### Configuration
+
+```{eval-rst}
+.. cfgcmd:: set system login tacas server <address> key <secret>
+
+   Specify the IP `<address>` of the TACACS server user with the pre-shared-secret
+   given in `<secret>`.
+
+   Multiple servers can be specified.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login tacas server <address> port <port>
+
+   Configure the discrete port under which the TACACS server can be reached.
+
+   This defaults to 49.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login tacas server <address> disable
+
+   Temporary disable this TACACS server. It won't be queried.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login tacas server <address> timeout <timeout>
+
+   Setup the `<timeout>` in seconds when querying the TACACS server.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login tacas source-address <address>
+
+   TACACS servers could be hardened by only allowing certain IP addresses to
+   connect. As of this the source address of each TACACS query can be
+   configured.
+
+   If unset, incoming connections to the TACACS server will use the nearest
+   interface address pointing towards the server - making it error prone on
+   e.g. OSPF networks when a link fails and a backup route is taken.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login tacas vrf <name>
+
+   Source all connections to the TACACS servers from given VRF `<name>`.
+
+```
+
+## Login Banner
+
+You are able to set post-login or pre-login banner messages to display certain
+information for this system.
+
+```{eval-rst}
+.. cfgcmd:: set system login banner pre-login <message>
+
+   Configure `<message>` which is shown during SSH connect and before a user is
+   logged in.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login banner post-login <message>
+
+   Configure `<message>` which is shown after user has logged in to the system.
+```
+
+:::{note}
+To create a new line in your login message you need to escape the new
+line character by using `\\n`.
+:::
+
+## Limits
+
+Login limits
+
+```{eval-rst}
+.. cfgcmd:: set system login max-login-session <number>
+
+   Set a limit on the maximum number of concurrent logged-in users on
+   the system.
+
+   This option must be used with ``timeout`` option.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system login timeout <timeout>
+
+   Configure session timeout after which the user will be logged out.
+```
+
+## Example
+
+In the following example, both `User1` and `User2` will be able to SSH into
+VyOS as user `vyos` using their very own keys. `User1` is restricted to only
+be able to connect from a single IP address. In addition if password base login
+is wanted for the `vyos` user a 2FA/MFA keycode is required in addition to
+the password.
+
+```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
+```
+
+### TACACS Example
+
+We use a vontainer providing the TACACS serve rin this example.
+
+Load the container image in op-mode.
+
+```none
+add container image lfkeitel/tacacs_plus:latest
+```
+
+```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 SSH into your system using admin/admin as a default user supplied
+from the `lfkeitel/tacacs_plus:latest` container.
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..7fbf5d23
--- /dev/null
+++ b/docs/configuration/system/option.md
@@ -0,0 +1,186 @@
+(system-option)=
+
+# Option
+
+This chapter describe the possibilities of advanced system behavior.
+
+## General
+
+```{eval-rst}
+.. cfgcmd:: set system option ctrl-alt-delete <ignore | reboot | poweroff>
+
+   Action which will be run once the ctrl-alt-del keystroke is received.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system option reboot-on-panic
+
+   Automatically reboot system on kernel panic after 60 seconds.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system option startup-beep
+
+    Play an audible beep to the system speaker when system is ready.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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!
+```
+
+```{eval-rst}
+.. 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!
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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 everyones use case you can adjust
+the used keyboard layout on the system console.
+
+```{eval-rst}
+.. 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.
+
+
+```{eval-rst}
+.. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf
+```
+
+
+```{eval-rst}
+.. 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.
+```
diff --git a/docs/configuration/system/proxy.md b/docs/configuration/system/proxy.md
new file mode 100644
index 00000000..3b12634b
--- /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 proxies require/support the "basic" HTTP authentication scheme as per
+{rfc}`7617`, thus a username can be configured.
+```
+```{cfgcmd} set system proxy password \<password\>
+
+Some proxies 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/acceleration.rst b/docs/configuration/system/rst-acceleration.rst
index 63506d6d..63506d6d 100644
--- a/docs/configuration/system/acceleration.rst
+++ b/docs/configuration/system/rst-acceleration.rst
diff --git a/docs/configuration/system/conntrack.rst b/docs/configuration/system/rst-conntrack.rst
index 68a4f2b8..68a4f2b8 100644
--- a/docs/configuration/system/conntrack.rst
+++ b/docs/configuration/system/rst-conntrack.rst
diff --git a/docs/configuration/system/console.rst b/docs/configuration/system/rst-console.rst
index 1f917e54..1f917e54 100644
--- a/docs/configuration/system/console.rst
+++ b/docs/configuration/system/rst-console.rst
diff --git a/docs/configuration/system/default-route.rst b/docs/configuration/system/rst-default-route.rst
index e102eb9c..e102eb9c 100644
--- a/docs/configuration/system/default-route.rst
+++ b/docs/configuration/system/rst-default-route.rst
diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/rst-flow-accounting.rst
index 7ed2d88c..7ed2d88c 100644
--- a/docs/configuration/system/flow-accounting.rst
+++ b/docs/configuration/system/rst-flow-accounting.rst
diff --git a/docs/configuration/system/frr.rst b/docs/configuration/system/rst-frr.rst
index a7f7ff93..a7f7ff93 100644
--- a/docs/configuration/system/frr.rst
+++ b/docs/configuration/system/rst-frr.rst
diff --git a/docs/configuration/system/host-name.rst b/docs/configuration/system/rst-host-name.rst
index 4d1567bf..4d1567bf 100644
--- a/docs/configuration/system/host-name.rst
+++ b/docs/configuration/system/rst-host-name.rst
diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/rst-index.rst
index dbb63d09..dbb63d09 100644
--- a/docs/configuration/system/index.rst
+++ b/docs/configuration/system/rst-index.rst
diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/rst-ip.rst
index 279630e2..279630e2 100644
--- a/docs/configuration/system/ip.rst
+++ b/docs/configuration/system/rst-ip.rst
diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/rst-ipv6.rst
index ee0fa341..ee0fa341 100644
--- a/docs/configuration/system/ipv6.rst
+++ b/docs/configuration/system/rst-ipv6.rst
diff --git a/docs/configuration/system/lcd.rst b/docs/configuration/system/rst-lcd.rst
index 808d45a2..808d45a2 100644
--- a/docs/configuration/system/lcd.rst
+++ b/docs/configuration/system/rst-lcd.rst
diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/rst-login.rst
index 6009a39b..6009a39b 100644
--- a/docs/configuration/system/login.rst
+++ b/docs/configuration/system/rst-login.rst
diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/rst-name-server.rst
index 5d08dbc5..5d08dbc5 100644
--- a/docs/configuration/system/name-server.rst
+++ b/docs/configuration/system/rst-name-server.rst
diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/rst-option.rst
index d039315c..d039315c 100644
--- a/docs/configuration/system/option.rst
+++ b/docs/configuration/system/rst-option.rst
diff --git a/docs/configuration/system/proxy.rst b/docs/configuration/system/rst-proxy.rst
index 8e0339a7..8e0339a7 100644
--- a/docs/configuration/system/proxy.rst
+++ b/docs/configuration/system/rst-proxy.rst
diff --git a/docs/configuration/system/sflow.rst b/docs/configuration/system/rst-sflow.rst
index c2cf5a80..c2cf5a80 100644
--- a/docs/configuration/system/sflow.rst
+++ b/docs/configuration/system/rst-sflow.rst
diff --git a/docs/configuration/system/sysctl.rst b/docs/configuration/system/rst-sysctl.rst
index 06e15031..06e15031 100644
--- a/docs/configuration/system/sysctl.rst
+++ b/docs/configuration/system/rst-sysctl.rst
diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/rst-syslog.rst
index 95c3bc87..95c3bc87 100644
--- a/docs/configuration/system/syslog.rst
+++ b/docs/configuration/system/rst-syslog.rst
diff --git a/docs/configuration/system/task-scheduler.rst b/docs/configuration/system/rst-task-scheduler.rst
index 382da39f..382da39f 100644
--- a/docs/configuration/system/task-scheduler.rst
+++ b/docs/configuration/system/rst-task-scheduler.rst
diff --git a/docs/configuration/system/time-zone.rst b/docs/configuration/system/rst-time-zone.rst
index 025c4376..025c4376 100644
--- a/docs/configuration/system/time-zone.rst
+++ b/docs/configuration/system/rst-time-zone.rst
diff --git a/docs/configuration/system/updates.rst b/docs/configuration/system/rst-updates.rst
index a55bfa9a..a55bfa9a 100644
--- a/docs/configuration/system/updates.rst
+++ b/docs/configuration/system/rst-updates.rst
diff --git a/docs/configuration/system/sflow.md b/docs/configuration/system/sflow.md
new file mode 100644
index 00000000..c63699db
--- /dev/null
+++ b/docs/configuration/system/sflow.md
@@ -0,0 +1,71 @@
+# 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
+
+```{eval-rst}
+.. cfgcmd:: set system sflow agent-address <address>
+
+   Configure sFlow agent IPv4 or IPv6 address
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set system sflow agent-interface <interface>
+
+   Configure agent IP address associated with this interface.
+
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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 whould participate in sflow accounting.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set system sflow polling <sec>
+
+   Configure schedule counter-polling in seconds (default: 30)
+```
+
+```{eval-rst}
+.. cfgcmd:: set system sflow sampling-rate <rate>
+
+   Use this command to configure the sampling rate for sFlow accounting (default: 1000)
+```
+
+```{eval-rst}
+.. 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.
+
+```
+
+## 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..b815861b
--- /dev/null
+++ b/docs/configuration/system/sysctl.md
@@ -0,0 +1,12 @@
+(sysctl)=
+
+# Sysctl
+
+This chapeter 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/.
+
+```{eval-rst}
+.. cfgcmd:: set system sysctl parameter <parameter> value <value>
+```
diff --git a/docs/configuration/system/syslog.md b/docs/configuration/system/syslog.md
new file mode 100644
index 00000000..b4335c22
--- /dev/null
+++ b/docs/configuration/system/syslog.md
@@ -0,0 +1,365 @@
+(syslog)=
+
+# Syslog
+
+Per default VyOSs has minimal syslog logging enabled which is stored and
+rotated locally. Errors will be always logged to a local file, which includes
+`local7` error messages, emergency messages will be sent to the console, too.
+
+To configure syslog, you need to switch into configuration mode.
+
+## Logging
+
+Syslog supports logging to multiple targets, those targets could be a plain
+file on your VyOS installation itself, a serial console or a remote syslog
+server which is reached via {abbr}`IP (Internet Protocol)` UDP/TCP.
+
+### Console
+
+```{eval-rst}
+.. cfgcmd:: set system syslog console facility <keyword> level <keyword>
+
+   Log syslog messages to ``/dev/console``, for an explanation on
+   {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` keywords
+   see tables below.
+```
+
+(custom-file)=
+
+### Custom File
+
+```{eval-rst}
+.. cfgcmd:: set system syslog file <filename> facility <keyword> level <keyword>
+
+   Log syslog messages to file specified via `<filename>`, for an explanation on
+   {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` keywords
+   see tables below.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system syslog file <filename> archive size <size>
+
+   Syslog will write `<size>` kilobytes into the file specified by `<filename>`.
+   After this limit has been reached, the custom file is "rotated" by logrotate
+   and a new custom file is created.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system syslog file <filename> archive file <number>
+
+   Syslog uses logrotate to rotate logiles after a number of gives bytes.
+   We keep as many as `<number>` rotated file before they are deleted on the
+   system.
+
+```
+
+### Remote Host
+
+Logging to a remote host leaves the local logging configuration intact, it
+can be configured in parallel to a custom file or console logging. You can log
+to multiple hosts at the same time, using either TCP or UDP. The default is
+sending the messages via port 514/UDP.
+
+```{eval-rst}
+.. cfgcmd:: set system syslog host <address> facility <keyword> level <keyword>
+
+   Log syslog messages to remote host specified by `<address>`. The address
+   can be specified by either FQDN or IP address. For an explanation on
+   {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level`
+   keywords see tables below.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set system syslog host <address> facility <keyword> protocol
+   <udp|tcp>
+
+   Configure protocol used for communication to remote syslog host. This can be
+   either UDP or TCP.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set system syslog vrf <name>
+
+  Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+#### {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**.
+:::
+
+```{eval-rst}
+.. cfgcmd:: set system syslog remote <address> tls
+
+   Enable TLS-encrypted remote logging.
+```
+
+```{eval-rst}
+.. 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``.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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:
+
+   * ``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.
+```
+
+```{eval-rst}
+.. 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 host 10.10.2.3 facility all level debug
+set system syslog host 10.10.2.3 port 6514
+set system syslog host 10.10.2.3 protocol tcp
+set system syslog host 10.10.2.3 tls auth-mode anon
+# or just use 'set system syslog host 10.10.2.3 tls'
+
+# Example of 'certvalid' authentication mode
+set system syslog host elk.example.com facility all level debug
+set system syslog host elk.example.com port 6514
+set system syslog host elk.example.com protocol tcp
+set system syslog host elk.example.com tls ca-certificate my-ca
+set system syslog host elk.example.com tls auth-mode certvalid
+
+# Example of 'fingerprint' authentication mode
+set system syslog host syslog.example.com facility all level debug
+set system syslog host syslog.example.com port 6514
+set system syslog host syslog.example.com protocol tcp
+set system syslog host syslog.example.com tls ca-certificate my-ca
+set system syslog host syslog.example.com tls auth-mode fingerprint
+set system syslog host syslog.example.com tls permitted-peer 'SHA1:10:C4:26:...'
+
+# Example of 'name' authentication mode
+set system syslog host graylog.example.com facility all level debug
+set system syslog host graylog.example.com port 6514
+set system syslog host graylog.example.com protocol tcp
+set system syslog host graylog.example.com tls ca-certificate my-ca
+set system syslog host graylog.example.com tls certificate syslog-client
+set system syslog host graylog.example.com tls auth-mode name
+set system syslog host graylog.example.com tls permitted-peer 'graylog.example.com'
+```
+
+#### Security Notes
+
+- Always prefer `auth-mode name` for secure deployments, as it ensures
+  both CA trust and server hostname validation.
+- `anon` mode should only be used for testing, because it does not
+  authenticate the server.
+- Ensure private keys are stored and managed exclusively in the
+  {doc}`PKI system </configuration/pki/index>`.
+
+### Local User Account
+
+```{eval-rst}
+.. cfgcmd:: set system syslog user <username> facility <keyword> level <keyword>
+
+   If logging to a local user account is configured, all defined log messages
+   are display on the console if the local user is logged in, if the user is not
+   logged in, no messages are being displayed. For an explanation on
+   {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` keywords
+   see tables below.
+```
+
+(syslog_facilities)=
+
+## Facilities
+
+List of facilities used by syslog. Most facilities names are self explanatory.
+Facilities local0 - local7 common usage is f.e. as network logs facilities for
+nodes and network equipment. Generally it depends on the situation how to
+classify logs and put them to facilities. See facilities more as a tool rather
+than a directive to follow.
+
+Facilities can be adjusted to meet the needs of the user:
+
+| Facility Code | Keyword  | Description                              |
+| ------------- | -------- | ---------------------------------------- |
+|               | 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 syslogd |
+| 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   | use 6 (local6)                           |
+| 23            | local7   | local use 7 (local7)                     |
+
+(syslog_severity_level)=
+
+## Severity Level
+
+| 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
+
+```{eval-rst}
+.. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...]
+
+   Display log files of given category on the console. Use tab completion to get
+   a list of available categories. Thos categories could be: all, authorization,
+   cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image
+   lldp, nat, openvpn, snmp, tail, vpn, vrrp
+```
+
+If no option is specified, this defaults to `all`.
+
+```{eval-rst}
+.. opcmd:: show log image <name>
+   [all | authorization | directory | file <file name> | tail <lines>]
+
+   Log messages from a specified image can be displayed on the console. Details
+   of allowed parameters:
+
+   .. list-table::
+      :widths: 25 75
+      :header-rows: 0
+
+      * - all
+        - Display contents of all master log files of the specified image
+      * - authorization
+        - Display all authorization attempts of the specified image
+      * - directory
+        - Display list of all user-defined log files of the specified image
+      * - file <file name>
+        - Display contents of a specified user-defined log file of the specified
+          image
+      * - tail
+        - Display last lines of the system log of the specified image
+      * - <lines>
+        - Number of lines to be displayed, default 10
+```
+
+When no options/parameters are used, the contents of the main syslog file are
+displayed.
+
+:::{hint}
+Use `show log | strip-private` if you want to hide private data
+when sharing your logs.
+:::
+
+## Delete Logs
+
+```{eval-rst}
+.. opcmd:: delete log file <text>
+```
+
+Deletes the specified user-defined file \<text> in the /var/log/user directory
+
+Note that deleting the log file does not stop the system from logging events.
+If you use this command while the system is logging events, old log events
+will be deleted, but events after the delete operation will be recorded in
+the new file. To delete the file altogether, first delete logging to the
+file using system syslog {ref}`custom-file` command, and then delete the file.
diff --git a/docs/configuration/system/task-scheduler.md b/docs/configuration/system/task-scheduler.md
new file mode 100644
index 00000000..378a648d
--- /dev/null
+++ b/docs/configuration/system/task-scheduler.md
@@ -0,0 +1,48 @@
+(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 excecuted this way are executed as root user - this may
+be dangerous. Together with {ref}`command-scripting` this can be used for
+automating (re-)configuration.
+:::
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set system task-scheduler task <task> executable path <path>
+
+   Specify absolute `<path>` to script which will be run when `<task>` is
+   executed.
+```
+
+```{eval-rst}
+.. 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..05a9d189
--- /dev/null
+++ b/docs/configuration/system/updates.md
@@ -0,0 +1,37 @@
+# Updates
+
+VyOS supports online checking for updates
+
+## Configuration
+
+```{eval-rst}
+.. cfgcmd:: set system update-check auto-check
+
+   Configure auto-checking for new images
+
+```
+
+```{eval-rst}
+.. 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:~$
+```
diff --git a/docs/configuration/trafficpolicy/index.md b/docs/configuration/trafficpolicy/index.md
new file mode 100644
index 00000000..02630e8c
--- /dev/null
+++ b/docs/configuration/trafficpolicy/index.md
@@ -0,0 +1,1391 @@
+(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.
+
+> ```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.
+
+> ```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**,
+
+> ```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**.
+
+> ```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).
+
+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
+
+**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 requieres 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.**
+
+```{eval-rst}
+.. 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
+
+**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.
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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
+
+**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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set qos policy fq-codel <policy name> interval <miliseconds>
+
+   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).
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. cfgcmd:: set qos policy fq-codel <policy-name> target <miliseconds>
+
+   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
+
+**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.
+:::
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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.
+
+```
+
+```{eval-rst}
+.. 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).
+
+```
+
+```{eval-rst}
+.. 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.
+
+```
+
+```{eval-rst}
+.. 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.
+
+```
+
+```{eval-rst}
+.. 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
+
+**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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+**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 clases 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)
+```
+
+```{eval-rst}
+.. 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
+
+**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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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**.
+:::
+
+```{eval-rst}
+.. 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).
+
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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                     |
+
+```{eval-rst}
+.. 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
+
+**Queueing discipline:**
+
+ Tocken 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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+**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.
+
+```{eval-rst}
+.. 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.
+
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+**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.
+
+```{eval-rst}
+.. cfgcmd:: set qos policy cake <text> bandwidth <value>
+
+   Set the shaper bandwidth, either as an explicit bitrate or a percentage
+   of the interface bandwidth.
+```
+
+```{eval-rst}
+.. cfgcmd:: set qos policy cake <text> description
+
+   Set a description for the shaper.
+```
+
+```{eval-rst}
+.. cfgcmd:: set qos policy cake <text> flow-isolation blind
+
+   Disables flow isolation, all traffic passes through a single queue.
+```
+
+```{eval-rst}
+.. cfgcmd:: set qos policy cake <text> flow-isolation dst-host
+
+   Flows are defined only by destination address.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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).
+```
+
+```{eval-rst}
+.. cfgcmd:: set qos policy cake <text> flow-isolation host
+
+   Flows are defined by source-destination host pairs.
+```
+
+```{eval-rst}
+.. cfgcmd:: set qos policy cake <text> flow-isolation nat
+
+   Perform NAT lookup before applying flow-isolation rules.
+```
+
+```{eval-rst}
+.. cfgcmd:: set qos policy cake <text> flow-isolation src-host
+
+   Flows are defined only by source address.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+```
+
+:::{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/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/rst-index.rst
index 3fb9a9bc..3fb9a9bc 100644
--- a/docs/configuration/trafficpolicy/index.rst
+++ b/docs/configuration/trafficpolicy/rst-index.rst
diff --git a/docs/configuration/vpn/dmvpn.md b/docs/configuration/vpn/dmvpn.md
new file mode 100644
index 00000000..4d1525ad
--- /dev/null
+++ b/docs/configuration/vpn/dmvpn.md
@@ -0,0 +1,351 @@
+(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.png
+:alt: Baseline DMVPN topology
+:scale: 40 %
+
+Baseline DMVPN topology
+:::
+
+## Configuration
+
+- Please refer to the {ref}`tunnel-interface` documentation for the individual
+  tunnel related options.
+- Please refer to the {ref}`ipsec_general` documentation for individual IPSec
+  related options.
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> cisco-authentication <secret>
+
+  Enables Cisco style authentication on NHRP packets. This embeds the secret
+  plaintext password to the outgoing NHRP packets. Incoming NHRP packets on
+  this interface are discarded unless the secret password is present. Maximum
+  length of the secret is 8 characters.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> dynamic-map <address>
+  nbma-domain-name <fqdn>
+
+  Specifies that the {abbr}`NBMA (Non-broadcast multiple-access network)`
+  addresses of the next hop servers are defined in the domain name
+  nbma-domain-name. For each A record opennhrp creates a dynamic NHS entry.
+
+  Each dynamic NHS will get a peer entry with the configured network address
+  and the discovered NBMA address.
+
+  The first registration request is sent to the protocol broadcast address, and
+  the server's real protocol address is dynamically detected from the first
+  registration reply.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> holding-time <timeout>
+
+  Specifies the holding time for NHRP Registration Requests and Resolution
+  Replies sent from this interface or shortcut-target. The holdtime is specified
+  in seconds and defaults to two hours.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> map cisco
+
+  If the statically mapped peer is running Cisco IOS, specify the cisco keyword.
+  It is used to fix statically the Registration Request ID so that a matching
+  Purge Request can be sent if NBMA address has changed. This is to work around
+  broken IOS which requires Purge Request ID to match the original Registration
+  Request ID.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> map nbma-address <address>
+
+  Creates static peer mapping of protocol-address to {abbr}`NBMA (Non-broadcast
+  multiple-access network)` address.
+
+  If the IP prefix mask is present, it directs opennhrp to use this peer as a
+  next hop server when sending Resolution Requests matching this subnet.
+
+  This is also known as the HUBs IP address or FQDN.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> map register
+
+  The optional parameter register specifies that Registration Request should be
+  sent to this peer on startup.
+
+  This option is required when running a DMVPN spoke.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> multicast <dynamic | nhs>
+
+  Determines how opennhrp daemon should soft switch the multicast traffic.
+  Currently, multicast traffic is captured by opennhrp daemon using a packet
+  socket, and resent back to proper destinations. This means that multicast
+  packet sending is CPU intensive.
+
+  Specfying nhs makes all multicast packets to be repeated to each statically
+  configured next hop.
+
+  Synamic instructs to forward to all peers which we have a direct connection
+  with. Alternatively, you can specify the directive multiple times for each
+  protocol-address the multicast traffic should be sent to.
+
+  .. warning:: It is very easy to misconfigure multicast repeating if you have
+    multiple NHSes.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> non-caching
+
+   Disables caching of peer information from forwarded NHRP Resolution Reply
+   packets. This can be used to reduce memory consumption on big NBMA subnets.
+
+  .. note:: Currently does not do much as caching is not implemented.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> redirect
+
+  Enable sending of Cisco style NHRP Traffic Indication packets. If this is
+  enabled and opennhrp detects a forwarded  packet, it will send a message to
+  the original sender of the packet instructing it to create a direct connection
+  with the destination. This is basically a protocol independent equivalent of
+  ICMP redirect.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut
+
+  Enable creation of shortcut routes.
+
+  A received NHRP Traffic Indication will trigger the resolution and
+  establishment of a shortcut route.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-destination
+
+  This instructs opennhrp to reply with authorative answers on NHRP Resolution
+  Requests destinied to addresses in this interface (instead of forwarding the
+  packets). This effectively allows the creation of shortcut routes to subnets
+  located on the interface.
+
+  When specified, this should be the only keyword for the interface.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-target <address>
+
+  Defines an off-NBMA network prefix for which the GRE interface will act as a
+  gateway. This an alternative to defining local interfaces with
+  shortcut-destination flag.
+```
+
+```{eval-rst}
+.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-target <address>
+  holding-time <timeout>
+
+  Specifies the holding time for NHRP Registration Requests and Resolution
+  Replies sent from this interface or shortcut-target. The holdtime is specified
+  in seconds and defaults to two hours.
+```
+
+## Example
+
+This blueprint uses VyOS as the DMVPN Hub and Cisco (7206VXR) and VyOS as
+multiple spoke sites. The lab was built using {abbr}`EVE-NG (Emulated Virtual
+Environment NG)`.
+
+:::{figure} /_static/images/blueprint-dmvpn.png
+:alt: DMVPN network
+
+DMVPN example network
+:::
+
+Each node (Hub and Spoke) uses an IP address from the network 172.16.253.128/29.
+
+The below referenced IP address `192.0.2.1` 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
+
+```none
+set interfaces ethernet eth0 address 192.0.2.1/24
+
+set interfaces tunnel tun100 address '172.16.253.134/29'
+set interfaces tunnel tun100 encapsulation 'gre'
+set interfaces tunnel tun100 local-ip '192.0.2.1'
+set interfaces tunnel tun100 enable-multicast
+set interfaces tunnel tun100 parameters ip key '1'
+
+set protocols nhrp tunnel tun100 cisco-authentication 'secret'
+set protocols nhrp tunnel tun100 holding-time '300'
+set protocols nhrp tunnel tun100 multicast 'dynamic'
+set protocols nhrp tunnel tun100 redirect
+set protocols nhrp tunnel tun100 shortcut
+
+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 esp-group ESP-HUB proposal 2 encryption '3des'
+set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5'
+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 ike-group IKE-HUB proposal 2 dh-group '2'
+set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128'
+set vpn ipsec ike-group IKE-HUB proposal 2 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).
+:::
+
+#### Spoke
+
+The individual spoke configurations only differ in the local IP address on the
+`tun10` interface. See the above diagram for the individual IP addresses.
+
+##### spoke01-spoke04
+
+```none
+crypto keyring DMVPN
+  pre-shared-key address 192.0.2.1 key secret
+!
+crypto isakmp policy 10
+ encr aes 256
+ authentication pre-share
+ group 2
+crypto isakmp invalid-spi-recovery
+crypto isakmp keepalive 30 30 periodic
+crypto isakmp profile DMVPN
+   keyring DMVPN
+   match identity address 192.0.2.1 255.255.255.255
+!
+crypto ipsec transform-set DMVPN-AES256 esp-aes 256 esp-sha-hmac
+ mode transport
+!
+crypto ipsec profile DMVPN
+ set security-association idle-time 720
+ set transform-set DMVPN-AES256
+ set isakmp-profile DMVPN
+!
+interface Tunnel10
+ ! individual spoke tunnel IP must change
+ ip address 172.16.253.129 255.255.255.248
+ no ip redirects
+ ip nhrp authentication secret
+ ip nhrp map 172.16.253.134 192.0.2.1
+ ip nhrp map multicast 192.0.2.1
+ ip nhrp network-id 1
+ ip nhrp holdtime 600
+ ip nhrp nhs 172.16.253.134
+ ip nhrp registration timeout 75
+ tunnel source FastEthernet0/0
+ tunnel mode gre multipoint
+ tunnel protection ipsec profile DMVPN
+ tunnel key 1
+!
+interface FastEthernet0/0
+ ip address dhcp
+ duplex half
+```
+
+##### spoke05
+
+VyOS can also run in DMVPN spoke mode.
+
+```none
+set interfaces ethernet eth0 address 'dhcp'
+
+set interfaces tunnel tun100 address '172.16.253.133/29'
+set interfaces tunnel tun100 local-ip 0.0.0.0
+set interfaces tunnel tun100 encapsulation 'gre'
+set interfaces tunnel tun100 enable-multicast
+set interfaces tunnel tun100 parameters ip key '1'
+
+set protocols nhrp tunnel tun100 cisco-authentication 'secret'
+set protocols nhrp tunnel tun100 holding-time '300'
+set protocols nhrp tunnel tun100 map 172.16.253.134/29 nbma-address '192.0.2.1'
+set protocols nhrp tunnel tun100 map 172.16.253.134/29 register
+set protocols nhrp tunnel tun100 multicast 'nhs'
+set protocols nhrp tunnel tun100 redirect
+set protocols nhrp tunnel tun100 shortcut
+
+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 esp-group ESP-HUB proposal 2 encryption '3des'
+set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5'
+set vpn ipsec ike-group IKE-HUB close-action 'none'
+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 ike-group IKE-HUB proposal 2 dh-group '2'
+set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128'
+set vpn ipsec ike-group IKE-HUB proposal 2 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'
+```
diff --git a/docs/configuration/vpn/index.md b/docs/configuration/vpn/index.md
new file mode 100644
index 00000000..92d9bfef
--- /dev/null
+++ b/docs/configuration/vpn/index.md
@@ -0,0 +1,25 @@
+# VPN
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   ipsec/index
+   l2tp
+   openconnect
+   pptp
+   rsa-keys
+   sstp
+
+```
+
+pages to sort
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   dmvpn
+```
diff --git a/docs/configuration/vpn/ipsec/index.md b/docs/configuration/vpn/ipsec/index.md
new file mode 100644
index 00000000..ff2d0c05
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/index.md
@@ -0,0 +1,20 @@
+# IPsec
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   ipsec_general
+   site2site_ipsec
+   troubleshooting_ipsec
+```
+
+pages to sort
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+```
diff --git a/docs/configuration/vpn/ipsec/ipsec_general.md b/docs/configuration/vpn/ipsec/ipsec_general.md
new file mode 100644
index 00000000..ff8ac76e
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/ipsec_general.md
@@ -0,0 +1,347 @@
+(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 for its IPsec implementation.
+
+**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.
+
+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.png
+:alt: AH and ESP in Transport Mode and Tunnel Mode
+:scale: 80 %
+:::
+
+## 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)
+
+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
+
+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
+does not receive a response, strongSwan executes its retransmission algorithm with
+its timers. <https://docs.strongswan.org/docs/5.9/config/retransmission.html>
+
+## Configuration IKE
+
+### IKE (Internet Key Exchange) Attributes
+
+VyOS IKE group has the next options:
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec ike-group <name> lifetime
+
+  IKE lifetime in seconds <0-86400> (default 28800).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> dh-group <dh-group number>
+
+  Diffie-Hellman algorithm group. Default value is **2**.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> encryption <encryption>
+
+  Encryption algorithm. Default value is **aes128**.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> hash <hash>
+
+  Hash algorithm. Default value is **sha1**.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> prf <prf>
+
+  Pseudo-random function.
+
+```
+
+### DPD (Dead Peer Detection) Configuration
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection interval <interval>
+
+  Keep-alive interval in seconds <2-86400> (default 30).
+```
+
+```{eval-rst}
+.. 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:
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec esp-group <name> compression
+
+  Enables the  IPComp(IP Payload Compression) protocol which allows
+  compressing the content of IP packets.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec esp-group <name> mode <mode>
+
+  The type of the connection:
+
+  * **tunnel** - Tunnel mode (default).
+  * **transport** - Transport mode.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> encryption <encryption>
+
+  Encryption algorithm. Default value is **aes128**.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> hash <hash>
+
+  Hash algorithm. Default value is **sha1**.
+```
+
+### Global IPsec Settings
+
+```{eval-rst}
+.. 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.
+
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec log level <number>
+
+  Level of logging. Default value is **0**.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec log subsystem <name>
+
+  Subsystem of the daemon.
+```
+
+### Options
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec options disable-route-autoinstall
+
+  Do not automatically install routes to remote
+  networks.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec options virtual-ip
+
+  Allows the installation of virtual-ip addresses.
+```
diff --git a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.md b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.md
new file mode 100644
index 00000000..bd25a072
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.md
@@ -0,0 +1,179 @@
+(remoteaccess-ipsec)=
+
+# IPSec IKEv2 Remote Access VPN
+
+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/index.rst b/docs/configuration/vpn/ipsec/rst-index.rst
index b19ffcfe..b19ffcfe 100644
--- a/docs/configuration/vpn/ipsec/index.rst
+++ b/docs/configuration/vpn/ipsec/rst-index.rst
diff --git a/docs/configuration/vpn/ipsec/ipsec_general.rst b/docs/configuration/vpn/ipsec/rst-ipsec_general.rst
index bf0d7668..bf0d7668 100644
--- a/docs/configuration/vpn/ipsec/ipsec_general.rst
+++ b/docs/configuration/vpn/ipsec/rst-ipsec_general.rst
diff --git a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst b/docs/configuration/vpn/ipsec/rst-remoteaccess_ipsec.rst
index 1a41d987..1a41d987 100644
--- a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst
+++ b/docs/configuration/vpn/ipsec/rst-remoteaccess_ipsec.rst
diff --git a/docs/configuration/vpn/ipsec/site2site_ipsec.rst b/docs/configuration/vpn/ipsec/rst-site2site_ipsec.rst
index 80dfa423..80dfa423 100644
--- a/docs/configuration/vpn/ipsec/site2site_ipsec.rst
+++ b/docs/configuration/vpn/ipsec/rst-site2site_ipsec.rst
diff --git a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst b/docs/configuration/vpn/ipsec/rst-troubleshooting_ipsec.rst
index fdeb347d..fdeb347d 100644
--- a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst
+++ b/docs/configuration/vpn/ipsec/rst-troubleshooting_ipsec.rst
diff --git a/docs/configuration/vpn/ipsec/site2site_ipsec.md b/docs/configuration/vpn/ipsec/site2site_ipsec.md
new file mode 100644
index 00000000..b813380f
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/site2site_ipsec.md
@@ -0,0 +1,811 @@
+(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**
+
+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.
+
+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.
+
+:::{figure} /_static/images/IPSec_close_action_settings.png
+:::
+
+Similar combinations are applicable for the dead-peer-detection.
+
+### Detailed Configuration Commands
+
+#### PSK Key Authentication
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec authentication psk <name> dhcp-interface
+
+  ID for authentication generated from DHCP address
+  dynamically.
+```
+
+```{eval-rst}
+.. 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``.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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.
+
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa local-key <key>
+
+  Name of PKI key-pair with local private key.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa remote-key <key>
+
+  Name of PKI key-pair with remote public key.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa passphrase <passphrase>
+
+  Local private key passphrase.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec authentication x509 passphrase <passphrase>
+
+  Private key passphrase, if needed.
+```
+
+##### Global Peer Configuration Commands
+
+```{eval-rst}
+.. 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.
+  * **respond** - does not try to initiate a connection to a remote
+    peer. In this mode, the IPsec session will be established only
+    after initiation from a remote peer. Could 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.
+  * **none** - loads the connection only, which then can be manually
+    initiated or used as a responder configuration.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> description <description>
+
+  Description for this peer.
+```
+
+```{eval-rst}
+.. 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``.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> ike-group <name>
+
+  Name of IKE group to use for key exchanges.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> disable
+
+  Disable this tunnel.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> esp-group <name>
+
+  Specify ESP group for this CHILD SA.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> priority <number>
+
+  Priority for policy-based IPsec VPN tunnels (lowest value more
+  preferable).
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> local prefix <network>
+
+  IP network at the local side.
+```
+
+```{eval-rst}
+.. 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``.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> remote prefix <network>
+
+  IP network at the remote side.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti bind <interface>
+
+  VTI interface to bind to this peer.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti traffic-selector local prefix <network>
+
+  Local prefix for interesting traffic.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti traffic-selector remote prefix <network>
+
+  Remote prefix for interesting traffic.
+```
+
+### IPsec Op-mode Commands
+
+```{eval-rst}
+.. opcmd:: show vpn ike sa
+
+  Shows active IKE SAs information.
+```
+
+```{eval-rst}
+.. opcmd:: show vpn ike secrets
+
+  Shows configured authentication keys.
+```
+
+```{eval-rst}
+.. opcmd:: show vpn ike status
+
+  Shows Strongswan daemon status.
+```
+
+```{eval-rst}
+.. opcmd:: show vpn ipsec connections
+
+  Shows summary status of all configured IKE and IPsec SAs.
+```
+
+```{eval-rst}
+.. opcmd:: show vpn ipsec sa [detail]
+
+  Shows active IPsec SAs information.
+```
+
+```{eval-rst}
+.. opcmd:: show vpn ipsec status
+
+  Shows status of IPsec process.
+```
+
+```{eval-rst}
+.. opcmd:: show vpn ipsec policy
+
+  Shows the in-kernel crypto policies.
+```
+
+```{eval-rst}
+.. opcmd:: show vpn ipsec state
+
+  Shows the in-kernel crypto state.
+```
+
+```{eval-rst}
+.. opcmd:: show log ipsec
+
+  Shows IPsec logs.
+```
+
+```{eval-rst}
+.. opcmd:: reset vpn ipsec site-to-site all
+
+  Clear all ipsec connection and reinitiate them if VyOS is configured
+  as initiator.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. opcmd:: reset vpn ipsec site-to-site peer <name> tunnel <number>
+
+  Clear scpecific IPsec SA and reinitiate it if VyOS is configured as
+  initiator.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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 'respond'
+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 'respond'
+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..064b4709
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.md
@@ -0,0 +1,305 @@
+(troubleshooting-ipsec)=
+
+# Troubleshooting Site-to-Site VPN IPsec
+
+## 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..edd3146b
--- /dev/null
+++ b/docs/configuration/vpn/l2tp.md
@@ -0,0 +1,685 @@
+(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
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access default-pool <POOL-NAME>
+
+   Use this command to define default address pool name.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn ipsec interface <INTERFACE>
+
+   Use this command to define IPsec interface.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access ipsec-settings authentication mode <pre-shared-secret | x509>
+
+   Set mode for IPsec authentication between VyOS and L2TP clients.
+```
+
+```{eval-rst}
+.. 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 '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
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> port <port>
+
+  Configure RADIUS `<server>` and its required port for authentication requests.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> fail-time <time>
+
+  Mark RADIUS server as offline for this given `<time>` in seconds.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius server <server> disable
+
+  Temporary disable this RADIUS server.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius acct-timeout <timeout>
+
+  Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author server <address>
+
+  Specifies IP address for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author port <port>
+
+  Port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author key <secret>
+
+  Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius max-try <number>
+
+  Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius timeout <timeout>
+
+  Timeout to wait response from server (seconds)
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius source-address <address>
+
+  Source IPv4 address used in all RADIUS server queires.
+```
+
+```{eval-rst}
+.. 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.
+:::
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication radius rate-limit enable
+
+  Enables bandwidth shaping via RADIUS.
+```
+
+```{eval-rst}
+.. 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).
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access lns host-name <hostname>
+
+  Sent to the client (LAC) in the Host-Name attribute
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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)
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access ppp-options ipv6-accept-peer-interface-id
+
+  Accept peer interface identifier. By default this is not defined.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-down <path_to_script>
+
+  Script to run when the session interface is about to terminate
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access extended-scripts on-pre-up <path_to_script>
+
+  Script to run before the session interface comes up
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> disable
+
+  Disable `<user>` account.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access authentication local-users username <user> static-ip
+   <address>
+
+  Assign a static IP address to `<user>` account.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access ppp-options disable-ccp
+
+  Disable Compression Control Protocol (CCP).
+  CCP is enabled by default.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access ppp-options mru <number>
+
+  Defines preferred MRU. By default is not defined.
+```
+
+### Global Advanced options
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access description <description>
+
+  Set description.
+```
+
+```{eval-rst}
+.. cfgcmd::  set vpn l2tp remote-access limits burst <value>
+
+  Burst count
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access limits connection-limit <value>
+
+  Maximum accepted connection rate (e.g. 1/min, 60/sec)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access limits timeout <value>
+
+  Timeout in seconds
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access mtu
+
+  Maximum Transmission Unit (MTU) (default: **1436**)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access max-concurrent-sessions
+
+  Maximum number of concurrent session start attempts
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access shaper fwmark <1-2147483647>
+
+  Match firewall mark value
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn l2tp remote-access snmp master-agent
+
+  Enable SNMP
+```
+
+```{eval-rst}
+.. 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..d7352a39
--- /dev/null
+++ b/docs/configuration/vpn/openconnect.md
@@ -0,0 +1,291 @@
+(vpn-openconnect)=
+
+# OpenConnect
+
+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>
+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
+```
+
+## 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'
+```
+
+### 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 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..030d4bbf
--- /dev/null
+++ b/docs/configuration/vpn/pptp.md
@@ -0,0 +1,656 @@
+(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
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access default-pool <POOL-NAME>
+
+   Use this command to define default address pool name.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> port <port>
+
+  Configure RADIUS `<server>` and its required port for authentication requests.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> fail-time <time>
+
+  Mark RADIUS server as offline for this given `<time>` in seconds.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius server <server> disable
+
+  Temporary disable this RADIUS server.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius acct-timeout <timeout>
+
+  Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author server <address>
+
+  Specifies IP address for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author port <port>
+
+  Port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author key <secret>
+
+  Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius max-try <number>
+
+  Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius timeout <timeout>
+
+  Timeout to wait response from server (seconds)
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius source-address <address>
+
+  Source IPv4 address used in all RADIUS server queires.
+```
+
+```{eval-rst}
+.. 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.
+:::
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication radius rate-limit enable
+
+  Enables bandwidth shaping via RADIUS.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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)
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access ppp-options ipv6-accept-peer-interface-id
+
+  Accept peer interface identifier. By default is not defined.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access extended-scripts on-change <path_to_script>
+
+  Script to run when session interface changed by RADIUS CoA handling
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access extended-scripts on-down <path_to_script>
+
+  Script to run when session interface going to terminate
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access extended-scripts on-pre-up <path_to_script>
+
+  Script to run before session interface comes up
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> disable
+
+  Disable `<user>` account.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> static-ip
+   <address>
+
+  Assign static IP address to `<user>` account.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> rate-limit
+   download <bandwidth>
+
+  Download bandwidth limit in kbit/s for `<user>`.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access authentication local-users username <user> rate-limit
+   upload <bandwidth>
+
+  Upload bandwidth limit in kbit/s for `<user>`.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access ppp-options disable-ccp
+
+  Disable Compression Control Protocol (CCP).
+  CCP is enabled by default.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access ppp-options mru <number>
+
+  Defines preferred MRU. By default is not defined.
+```
+
+### Global Advanced options
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access description <description>
+
+  Set description.
+```
+
+```{eval-rst}
+.. cfgcmd::  set vpn pptp remote-access limits burst <value>
+
+  Burst count
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access limits connection-limit <value>
+
+  Acceptable rate of connections (e.g. 1/min, 60/sec)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access limits timeout <value>
+
+  Timeout in seconds
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access mtu
+
+  Maximum Transmission Unit (MTU) (default: **1436**)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access max-concurrent-sessions
+
+  Maximum number of concurrent session start attempts
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access shaper fwmark <1-2147483647>
+
+  Match firewall mark value
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access snmp master-agent
+
+  Enable SNMP
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn pptp remote-access wins-server <address>
+
+  Windows Internet Name Service (WINS) servers propagated to client
+```
+
+## Monitoring
+
+```{eval-rst}
+.. 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..d8d7bca8
--- /dev/null
+++ b/docs/configuration/vpn/rsa-keys.md
@@ -0,0 +1,105 @@
+# RSA-Keys
+
+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] Yrgerg
+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 respond
+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/dmvpn.rst b/docs/configuration/vpn/rst-dmvpn.rst
index fa08f115..fa08f115 100644
--- a/docs/configuration/vpn/dmvpn.rst
+++ b/docs/configuration/vpn/rst-dmvpn.rst
diff --git a/docs/configuration/vpn/index.rst b/docs/configuration/vpn/rst-index.rst
index 12bcc6f0..12bcc6f0 100644
--- a/docs/configuration/vpn/index.rst
+++ b/docs/configuration/vpn/rst-index.rst
diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/rst-l2tp.rst
index 15613ab2..15613ab2 100644
--- a/docs/configuration/vpn/l2tp.rst
+++ b/docs/configuration/vpn/rst-l2tp.rst
diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/rst-openconnect.rst
index c234d4dc..c234d4dc 100644
--- a/docs/configuration/vpn/openconnect.rst
+++ b/docs/configuration/vpn/rst-openconnect.rst
diff --git a/docs/configuration/vpn/pptp.rst b/docs/configuration/vpn/rst-pptp.rst
index 5220929f..5220929f 100644
--- a/docs/configuration/vpn/pptp.rst
+++ b/docs/configuration/vpn/rst-pptp.rst
diff --git a/docs/configuration/vpn/rsa-keys.rst b/docs/configuration/vpn/rst-rsa-keys.rst
index a95f5f33..a95f5f33 100644
--- a/docs/configuration/vpn/rsa-keys.rst
+++ b/docs/configuration/vpn/rst-rsa-keys.rst
diff --git a/docs/configuration/vpn/sstp.rst b/docs/configuration/vpn/rst-sstp.rst
index e750cdcf..e750cdcf 100644
--- a/docs/configuration/vpn/sstp.rst
+++ b/docs/configuration/vpn/rst-sstp.rst
diff --git a/docs/configuration/vpn/sstp.md b/docs/configuration/vpn/sstp.md
new file mode 100644
index 00000000..3574a904
--- /dev/null
+++ b/docs/configuration/vpn/sstp.md
@@ -0,0 +1,765 @@
+(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] 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'
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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>`.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp default-pool <POOL-NAME>
+
+   Use this command to define default address pool name.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp gateway-address <gateway>
+
+  Specifies single `<gateway>` IP address to be used as local address of PPP
+  interfaces.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp ssl ca-certificate <file>
+
+  Name of installed certificate authority certificate.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius server <server> port <port>
+
+  Configure RADIUS `<server>` and its required port for authentication requests.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius server <server> fail-time <time>
+
+  Mark RADIUS server as offline for this given `<time>` in seconds.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius server <server> disable
+
+  Temporary disable this RADIUS server.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius acct-timeout <timeout>
+
+  Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius dynamic-author server <address>
+
+  Specifies IP address for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius dynamic-author port <port>
+
+  Port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius dynamic-author key <secret>
+
+  Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius max-try <number>
+
+  Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius timeout <timeout>
+
+  Timeout to wait response from server (seconds)
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius source-address <address>
+
+  Source IPv4 address used in all RADIUS server queires.
+```
+
+```{eval-rst}
+.. 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.
+:::
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication radius rate-limit enable
+
+  Enables bandwidth shaping via RADIUS.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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)
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp ppp-options ipv6-accept-peer-interface-id
+
+  Accept peer interface identifier. By default this is not defined.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp extended-scripts on-change <path_to_script>
+
+  Script to run when the session interface is changed by RADIUS CoA handling
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp extended-scripts on-down <path_to_script>
+
+  Script to run when the session interface about to terminate
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp extended-scripts on-pre-up <path_to_script>
+
+  Script to run before the session interface comes up
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication local-users username <user> disable
+
+  Disable `<user>` account.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication local-users username <user> static-ip
+   <address>
+
+  Assign a static IP address to `<user>` account.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit
+   download <bandwidth>
+
+  Rate limit the download bandwidth for `<user>` to `<bandwidth>` kbit/s.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit
+   upload <bandwidth>
+
+  Rate limit the upload bandwidth for `<user>` to `<bandwidth>` kbit/s.
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp ppp-options disable-ccp
+
+  Disable Compression Control Protocol (CCP).
+  CCP is enabled by default.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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**.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp ppp-options mru <number>
+
+  Defines preferred MRU. By default is not defined.
+```
+
+### Global Advanced options
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp description <description>
+
+  Set description.
+```
+
+```{eval-rst}
+.. cfgcmd::  set vpn sstp limits burst <value>
+
+  Burst count
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp limits connection-limit <value>
+
+  Maximum accepted connection rate (e.g. 1/min, 60/sec)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp limits timeout <value>
+
+  Timeout in seconds
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp mtu
+
+  Maximum Transmission Unit (MTU) (default: **1500**)
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp max-concurrent-sessions
+
+  Maximum number of concurrent session start attempts
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp shaper fwmark <1-2147483647>
+
+  Match firewall mark value
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp snmp master-agent
+
+  Enable SNMP
+```
+
+```{eval-rst}
+.. cfgcmd:: set vpn sstp wins-server <address>
+
+  Windows Internet Name Service (WINS) servers propagated to client
+```
+
+```{eval-rst}
+.. 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
+
+```{eval-rst}
+.. 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
+```
+
+```{include} /_include/common-references.txt
+```
+
+[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..b0c86bda
--- /dev/null
+++ b/docs/configuration/vrf/index.md
@@ -0,0 +1,601 @@
+---
+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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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 Mapss 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.
+
+```{eval-rst}
+.. 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, connected, eigrp,
+   isis, kernel, ospf, rip, static, table
+
+   .. note:: If you choose any as the option that will cause all protocols that
+      are sending routes to zebra.
+```
+
+```{eval-rst}
+.. 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, connected, isis,
+   kernel, ospfv3, ripng, static, table
+
+   .. 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 wan't to e.g. allow BGP to peer across the default route.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. cfgcmd:: set vrf name <name> ipv6 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.
+```
+
+### 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.
+
+```{eval-rst}
+.. 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 ...`
+
+## 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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+
+```
+
+```{eval-rst}
+.. 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
+
+```
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+
+:::{figure} /_static/images/vrf-example-topology-01.png
+: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 '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 '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.
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+```
+
+```{eval-rst}
+.. 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.
+
+```{eval-rst}
+.. 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
+```
+
+```{eval-rst}
+.. 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
+
+```
+
+```{include} /_include/common-references.txt
+```
diff --git a/docs/configuration/vrf/index.rst b/docs/configuration/vrf/rst-index.rst
index 0d44e326..0d44e326 100644
--- a/docs/configuration/vrf/index.rst
+++ b/docs/configuration/vrf/rst-index.rst