feat: activate 106 visual-validated canaries via swap

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

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

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

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

22 files changed, 5192 insertions, 0 deletions

diff --git a/docs/configuration/firewall/md-bridge.md b/docs/configuration/firewall/md-bridge.md
new file mode 100644
index 00000000..42442ee7
--- /dev/null
+++ b/docs/configuration/firewall/md-bridge.md
@@ -0,0 +1,673 @@
+---
+lastproofread: '2026-03-28'
+---
+
+(firewall-configuration)=
+
+# Bridge Firewall Configuration
+
+## Overview
+
+Learn more about bridge firewall configuration
+and related op-mode commands.
+
+The following commands are covered in this section:
+
+```{cfgcmd} set firewall bridge \<options\>
+```
+From the main structure defined in
+{doc}`Firewall Overview</configuration/firewall/index>`
+in this section you can find detailed information only for the next part
+of the general structure:
+```none
+- set firewall
+    * bridge
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+         - prerouting
+            + filter
+         - name
+            + custom_name
+```
+Traffic that is received by the router on an interface that is a member of a
+bridge is processed on the **Bridge Layer**. Before the bridge decision is
+made, all packets are analyzed at **Prerouting**. First filters can be applied
+here, and also rules for ignoring connection tracking system can be configured.
+The relevant configuration that acts in **prerouting** is:
+
+
+- `set firewall bridge prerouting filter ...`.
+
+
+For traffic that needs to be switched internally by the bridge, the base
+chain is **forward**, and its base command for filtering is `set firewall
+bridge forward filter ...`, which happens in stage 4, highlighted with red
+color.
+
+
+:::{figure} /_static/images/firewall-bridge-forward.png
+:::
+
+
+For traffic destined to the router itself or that needs to be routed
+(assuming a layer3 bridge is configured), the base chain is **input**, and the
+base command is `set firewall bridge input filter ...` and the path is:
+
+
+:::{figure} /_static/images/firewall-bridge-input.png
+:::
+
+
+If it's not dropped, then the packet is sent to **IP Layer**, and will be
+processed by the **IP Layer** firewall: IPv4 or IPv6 ruleset. Check once again
+the {doc}`general packet flow diagram</configuration/firewall/index>` if
+needed.
+
+
+For traffic that originates from the bridge itself, the base chain is
+**output**, and the base command is `set firewall bridge output filter
+...`, and the path is:
+
+
+:::{figure} /_static/images/firewall-bridge-output.png
+:::
+
+
+Custom bridge firewall chains can be created with the command `set firewall
+bridge name <name> ...`. To use such a custom chain, a rule with action jump
+and the appropriate target must be defined in a base chain.
+
+
+## Bridge Rules
+
+
+For firewall filtering, firewall rules need to be created. Each rule is
+numbered, has an action to apply if the rule is matched, and the ability
+to specify multiple matching criteria. Data packets go through the rules
+from 1 - 999999, so order is crucial. At the first match the action of the
+rule will be executed.
+
+
+### Actions
+
+
+If a rule is defined, an action must also be defined for it. This tells the
+firewall what to do if all matching criteria in the rule are met.
+
+
+In firewall bridge rules, the action can be:
+
+
+- `accept`: accept the packet.
+- `continue`: continue parsing next rule.
+- `drop`: drop the packet.
+- `jump`: jump to another custom chain.
+- `return`: Return from the current chain and continue at the next rule
+  of the last chain.
+- `queue`: Enqueue packet to userspace.
+- `notrack`: ignore connection tracking system. This action is only
+  available in prerouting chain.
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return]
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return]
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return]
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> action [accept | continue | drop | jump | notrack | queue | return]
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> action [accept | continue | drop | jump | queue | return]
+
+
+This required setting defines the action of the current rule. If action is
+set to jump, then jump-target is also needed.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> jump-target \<text\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> jump-target \<text\>
+
+
+If action is set to ``queue``, use next command to specify the queue
+target. Range is also supported:
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> queue \<0-65535\>
+
+
+Also, if action is set to ``queue``, use next command to specify the queue
+options. Possible options are ``bypass`` and ``fanout``:
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> queue-options fanout
+```
+Also, **default-action** is an action that takes place whenever a packet does
+not match any rule in its chain. For base chains, possible options for
+**default-action** are **accept** or **drop**.
+```{cfgcmd} set firewall bridge forward filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall bridge input filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall bridge output filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall bridge prerouting filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall bridge name \<name\> default-action [accept | continue | drop | jump | reject | return]
+
+
+This sets the default action of the rule-set if a packet does not match
+any of the rules in that chain. If default-action is set to ``jump``, then
+``default-jump-target`` is also needed. Note that for base chains, default
+action can only be set to ``accept`` or ``drop``, while on custom chains
+more actions are available.
+```
+
+```{cfgcmd} set firewall bridge name \<name\> default-jump-target \<text\>
+
+To be used only when ``default-action`` is set to ``jump``. Use this
+command to specify jump target for default rule.
+```
+:::{note}
+**Important note about default-actions:**
+If the default action for any base chain is not defined, then the default
+action is set to **accept** for that chain. For custom chains, if the
+default action is not defined, then the default-action is set to **drop**.
+:::
+
+
+### Firewall Logs
+
+
+You can enable logging for every firewall rule. If enabled, other log options
+can be configured.
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log
+
+Enable logging for the matched packet. If this configuration command is not
+present, then the log is not enabled.
+```
+
+```{cfgcmd} set firewall bridge forward filter default-log
+```
+
+```{cfgcmd} set firewall bridge input filter default-log
+```
+
+```{cfgcmd} set firewall bridge output filter default-log
+```
+
+```{cfgcmd} set firewall bridge prerouting filter default-log
+```
+
+```{cfgcmd} set firewall bridge name \<name\> default-log
+
+Use this command to enable the logging of the default action on
+the specified chain.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+
+
+Define log-level. Only applicable if rule log is enabled.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options group \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options group \<0-65535\>
+
+
+Define the log group to send messages to. Only applicable if rule log is
+enabled.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options snapshot-length \<0-9000\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options snapshot-length \<0-9000\>
+
+
+Define length of packet payload to include in netlink message. Only
+applicable if rule log is enabled and the log group is defined.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options queue-threshold \<0-65535\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options queue-threshold \<0-65535\>
+
+
+Define the number of packets to queue inside the kernel before sending them
+to userspace. Only applicable if rule log is enabled and the log group is
+defined.
+```
+### Firewall Description
+
+
+You can define a description for reference for every custom chain.
+```{cfgcmd} set firewall bridge name \<name\> description \<text\>
+
+Provide a rule-set description to a custom firewall chain.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> description \<text\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> description \<text\>
+
+
+Provide a description for each rule.
+```
+### Rule Status
+
+
+By default, when you define a rule, it is enabled. In some cases, it is
+useful to disable the rule instead of removing it.
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> disable
+
+Command for disabling a rule but keep it in the configuration.
+```
+### Matching criteria
+
+
+There are many matching criteria against which a packet can be tested. Refer
+to {doc}`IPv4</configuration/firewall/ipv4>` and
+{doc}`IPv6</configuration/firewall/ipv6>` matching criteria for more details.
+
+
+Since bridges operate at layer 2, both matchers for IPv4 and IPv6 are
+supported in bridge firewall configuration. Same applies to firewall groups.
+
+
+Same specific matching criteria that can be used in bridge firewall are
+described in this section:
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+
+
+Match based on the Ethernet type of the packet.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6]
+
+
+Match based on the Ethernet type of the packet when it is VLAN tagged.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan id \<0-4096\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan id \<0-4096\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan id \<0-4096\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan id \<0-4096\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> vlan id \<0-4096\>
+
+
+Match based on VLAN identifier. Range is also supported.
+```
+
+```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan priority \<0-7\>
+```
+
+```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan priority \<0-7\>
+```
+
+```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan priority \<0-7\>
+```
+
+```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan priority \<0-7\>
+```
+
+```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> vlan priority \<0-7\>
+
+
+Match based on VLAN priority (Priority Code Point - PCP). Range is also
+supported.
+```
+### Packet Modifications
+
+
+Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify
+packets before they are sent out. This feaure provides more flexibility in
+packet handling.
+```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set dscp \<0-63\>
+
+
+Set a specific value of Differentiated Services Codepoint (DSCP).
+```
+
+```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set mark \<1-2147483647\>
+
+
+Set a specific packet mark value.
+```
+
+```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set tcp-mss \<500-1460\>
+
+
+Set the TCP-MSS (TCP maximum segment size) for the connection.
+```
+
+```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set ttl \<0-255\>
+
+
+Set the TTL (Time to Live) value.
+```
+
+```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set hop-limit \<0-255\>
+
+
+Set hop limit value.
+```
+
+```{cfgcmd} set firewall bridge [forward | output] filter rule \<1-999999\> set connection-mark \<0-2147483647\>
+
+
+Set connection mark value.
+```
+### Use IP firewall
+
+By default, for switched traffic, only the rules defined under `set firewall
+bridge` are applied. There are two global-options that can be configured in
+order to force deeper analysis of the packet on the IP layer. These options
+are:
+```{cfgcmd} set firewall global-options apply-to-bridged-traffic ipv4
+
+This command enables the IPv4 firewall for bridged traffic. If this option
+is used, packets are also parsed by rules defined in ``set firewall ipv4
+...``
+```
+
+```{cfgcmd} set firewall global-options apply-to-bridged-traffic ipv6
+
+This command enables the IPv6 firewall for bridged traffic. If this option
+is used, packets are also parsed by rules defined in ``set firewall ipv6
+...``
+```
+## Operation-mode Firewall
+### Rule-set overview
+In this section you can find all useful firewall op-mode commands.
+General commands for firewall configuration, counter and statistics:
+```{opcmd} show firewall
+```
+
+```{opcmd} show firewall summary
+```
+
+```{opcmd} show firewall statistics
+```
+And, to print only bridge firewall information:
+```{opcmd} show firewall bridge
+```
+
+```{opcmd} show firewall bridge forward filter
+```
+
+```{opcmd} show firewall bridge forward filter rule \<rule\>
+```
+
+```{opcmd} show firewall bridge name \<name\>
+```
+
+```{opcmd} show firewall bridge name \<name\> rule \<rule\>
+```
+### Show Firewall log
+```{opcmd} show log firewall
+```
+
+```{opcmd} show log firewall bridge
+```
+
+```{opcmd} show log firewall bridge forward
+```
+
+```{opcmd} show log firewall bridge forward filter
+```
+
+```{opcmd} show log firewall bridge name \<name\>
+```
+
+```{opcmd} show log firewall bridge forward filter rule \<rule\>
+```
+
+```{opcmd} show log firewall bridge name \<name\> rule \<rule\>
+
+Show the logs of all firewall; show all bridge firewall logs; show all logs
+for forward hook; show all logs for forward hook and priority filter; show
+all logs for particular custom chain; show logs for specific Rule-Set.
+```
+### Example
+Configuration example:
+```none
+set firewall bridge forward filter default-action 'drop'
+set firewall bridge forward filter default-log
+set firewall bridge forward filter rule 10 action 'continue'
+set firewall bridge forward filter rule 10 inbound-interface name 'eth2'
+set firewall bridge forward filter rule 10 vlan id '22'
+set firewall bridge forward filter rule 20 action 'drop'
+set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT'
+set firewall bridge forward filter rule 20 vlan id '60'
+set firewall bridge forward filter rule 30 action 'jump'
+set firewall bridge forward filter rule 30 jump-target 'TEST'
+set firewall bridge forward filter rule 30 outbound-interface name '!eth1'
+set firewall bridge forward filter rule 35 action 'accept'
+set firewall bridge forward filter rule 35 vlan id '11'
+set firewall bridge forward filter rule 40 action 'continue'
+set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11'
+set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66'
+set firewall bridge name TEST default-action 'accept'
+set firewall bridge name TEST default-log
+set firewall bridge name TEST rule 10 action 'continue'
+set firewall bridge name TEST rule 10 log
+set firewall bridge name TEST rule 10 vlan priority '0'
+```
+And op-mode commands:
+```none
+vyos@BRI:~$ show firewall bridge
+Rulesets bridge Information
+
+---------------------------------
+bridge Firewall "forward filter"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  ---------------------------------------------------------------------
+10       continue  all                 0        0  iifname "eth2" vlan id 22  continue
+20       drop      all                 0        0  iifname @I_TRUNK-RIGHT vlan id 60
+30       jump      all              2130   170688  oifname != "eth1"  jump NAME_TEST
+35       accept    all              2080   168616  vlan id 11  accept
+40       continue  all                 0        0  ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66  continue
+default  drop      all                 0        0
+
+---------------------------------
+bridge Firewall "name TEST"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  --------------------------------------------------
+10       continue  all              2130   170688  vlan pcp 0  prefix "[bri-NAM-TEST-10-C]"  continue
+default  accept    all              2130   170688
+
+vyos@BRI:~$
+vyos@BRI:~$ show firewall bridge name TEST
+Ruleset Information
+
+---------------------------------
+bridge Firewall "name TEST"
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  --------------------------------------------------
+10       continue  all              2130   170688  vlan pcp 0  prefix "[bri-NAM-TEST-10-C]"  continue
+default  accept    all              2130   170688
+
+vyos@BRI:~$
+```
+Inspect logs:
+```none
+vyos@BRI:~$ show log firewall bridge
+Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102
+Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102
+Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102
+...
+vyos@BRI:~$ show log firewall bridge forward filter
+Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0
+Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0
+```
diff --git a/docs/configuration/firewall/md-global-options.md b/docs/configuration/firewall/md-global-options.md
new file mode 100644
index 00000000..adff2d5a
--- /dev/null
+++ b/docs/configuration/firewall/md-global-options.md
@@ -0,0 +1,203 @@
+---
+lastproofread: '2026-03-30'
+---
+
+(firewall-global-options-configuration)=
+
+# Global Options Firewall Configuration
+
+## Overview
+
+Some firewall settings are global and affect the entire system. This section
+provides information about these global options that you can configure using
+the VyOS CLI.
+
+Configuration commands covered in this section:
+
+```{cfgcmd} set firewall global-options ...
+```
+## Configuration
+```{cfgcmd} set firewall global-options all-ping [enable | disable]
+
+By default, when VyOS receives an ICMP echo request packet destined for
+itself, it answers with an ICMP echo reply, unless your firewall prevents
+it.
+
+You can set firewall rules to accept, drop, or reject ICMP in, out, or
+local traffic. You can also use the **firewall global-options all-ping**
+command. This command affects only LOCAL traffic (packets destined for your
+VyOS system), not IN or OUT traffic.
+
+:::{note}
+**firewall global-options all-ping** affects only LOCAL traffic
+and always behaves in the most restrictive way
+:::
+:::{code-block} none
+set firewall global-options all-ping enable
+:::
+When you set this command, VyOS answers every ICMP echo request addressed
+to itself, but that response occurs only if no other rule drops or rejects
+local echo requests. In case of conflict, VyOS does not answer ICMP echo
+requests.
+
+:::{code-block} none
+set firewall global-options all-ping disable
+:::
+When you set this command, VyOS answers no ICMP echo requests addressed to
+itself, regardless of where they come from or what specific rules accept
+them.
+```
+
+```{cfgcmd} set firewall global-options apply-to-bridged-traffic [ipv4 | ipv6]
+
+Apply IPv4 or IPv6 firewall rules to bridged traffic.
+```
+
+```{cfgcmd} set firewall global-options broadcast-ping [enable | disable]
+
+Enable or disable the response to ICMP broadcast messages. The system
+alters the following parameter:
+* ``net.ipv4.icmp_echo_ignore_broadcasts``
+```
+
+```{cfgcmd} set firewall global-options ip-src-route [enable | disable]
+```
+
+```{cfgcmd} set firewall global-options ipv6-src-route [enable | disable]
+
+Set whether VyOS accepts packets with a source route option.
+The following sysctl parameters will be changed:
+* ``net.ipv4.conf.all.accept_source_route``
+* ``net.ipv6.conf.all.accept_source_route``
+```
+
+```{cfgcmd} set firewall global-options receive-redirects [enable | disable]
+```
+
+```{cfgcmd} set firewall global-options ipv6-receive-redirects [enable | disable]
+
+Allow VyOS to accept ICMPv4 and ICMPv6 redirect messages.
+The following sysctl parameters will be changed:
+* ``net.ipv4.conf.all.accept_redirects``
+* ``net.ipv6.conf.all.accept_redirects``
+```
+
+```{cfgcmd} set firewall global-options send-redirects [enable | disable]
+
+Allow VyOS to send ICMPv4 redirect messages.
+The following sysctl parameter will be changed:
+* ``net.ipv4.conf.all.send_redirects``
+```
+
+```{cfgcmd} set firewall global-options log-martians [enable | disable]
+
+Allow VyOS to log martian IPv4 packets.
+The following sysctl parameter will be changed:
+* ``net.ipv4.conf.all.log_martians``
+```
+
+```{cfgcmd} set firewall global-options source-validation [strict | loose | disable]
+
+Set the IPv4 source validation mode.
+The following sysctl parameter will be changed:
+* ``net.ipv4.conf.all.rp_filter``
+```
+
+```{cfgcmd} set firewall global-options syn-cookies [enable | disable]
+
+Allow VyOS to use IPv4 TCP SYN Cookies.
+The following sysctl parameter will be changed:
+* ``net.ipv4.tcp_syncookies``
+```
+
+```{cfgcmd} set firewall global-options twa-hazards-protection [enable | disable]
+
+Enable or disable VyOS {rfc}`1337` conformance.
+The following sysctl parameter will be changed:
+* ``net.ipv4.tcp_rfc1337``
+```
+
+```{cfgcmd} set firewall global-options state-policy established action [accept | drop | reject]
+```
+
+```{cfgcmd} set firewall global-options state-policy established log
+```
+
+```{cfgcmd} set firewall global-options state-policy established log-level [emerg | alert | crit | err | warn | notice | info | debug]
+
+Set the global setting for an established connection.
+```
+
+```{cfgcmd} set firewall global-options state-policy invalid action [accept | drop | reject]
+```
+
+```{cfgcmd} set firewall global-options state-policy invalid log
+```
+
+```{cfgcmd} set firewall global-options state-policy invalid log-level [emerg | alert | crit | err | warn | notice | info | debug]
+
+Set the global setting for invalid packets.
+```
+
+```{cfgcmd} set firewall global-options state-policy related action [accept | drop | reject]
+```
+
+```{cfgcmd} set firewall global-options state-policy related log
+```
+
+```{cfgcmd} set firewall global-options state-policy related log-level [emerg | alert | crit | err | warn | notice | info | debug]
+
+Set the global setting for related connections.
+```
+VyOS supports setting timeouts for connections by connection type. You can
+set timeout values for generic connections, ICMP connections, UDP
+connections, or TCP connections in various states.
+```{cfgcmd} set firewall global-options timeout icmp \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout other \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout tcp close \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout tcp close-wait \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout tcp established \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout tcp fin-wait \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout tcp last-ack \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout tcp syn-recv \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout tcp syn-sent \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout tcp time-wait \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout udp other \<1-21474836\>
+:defaultvalue:
+```
+
+```{cfgcmd} set firewall global-options timeout udp stream \<1-21474836\>
+:defaultvalue:
+
+Set the timeout in seconds for a protocol or state.
+```
\ No newline at end of file
diff --git a/docs/configuration/firewall/md-groups.md b/docs/configuration/firewall/md-groups.md
new file mode 100644
index 00000000..ceb1783f
--- /dev/null
+++ b/docs/configuration/firewall/md-groups.md
@@ -0,0 +1,418 @@
+---
+lastproofread: '2026-03-30'
+---
+
+(firewall-groups-configuration)=
+
+# Firewall groups
+
+## Configuration
+
+Firewall groups represent collections of IP addresses, networks, ports,
+MAC addresses, domains, or interfaces. You can reference a group in firewall,
+NAT, and policy route rules as either a source or destination matcher, and/or
+as inbound or outbound in the case of interface groups.
+
+### Address Groups
+
+An **address group** contains a single IP address or IP address range.
+
+```{cfgcmd} set firewall group address-group \<name\> address [address | address range]
+```
+```{cfgcmd} set firewall group ipv6-address-group \<name\> address \<address\>
+
+Define an IPv4 or IPv6 address group.
+
+:::{code-block} none
+set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1
+set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8
+set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1
+:::
+```
+
+```{cfgcmd} set firewall group address-group \<name\> description \<text\>
+```
+
+```{cfgcmd} set firewall group ipv6-address-group \<name\> description \<text\>
+
+Provide an IPv4 or IPv6 address group description.
+```
+### Remote Groups
+A **remote-group** uses a URL that hosts a newline-delimited list of IPv4
+and/or IPv6 addresses, CIDRs, and ranges. VyOS pulls this list periodically
+according to the frequency you define in the firewall **resolver-interval**
+and loads matching entries into the group for use in rules. The list is cached
+in persistent storage, so rules continue to function if updates fail.
+```{cfgcmd} set firewall group remote-group \<name\> url \<http(s) url\>
+
+Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs
+to fetch.
+```
+
+```{cfgcmd} set firewall group remote-group \<name\> description \<text\>
+
+Set a description for a remote group.
+```
+The remote list format is flexible. VyOS attempts to parse the first word of
+each line as an entry and skips lines it cannot match. Lines that begin with
+an alphanumeric character but do not match valid IPv4 or IPv6 addresses,
+ranges, or CIDRs are logged to the system log. The following examples show
+acceptable formats that VyOS parses correctly:
+```none
+127.0.0.1
+127.0.0.0/24
+127.0.0.1-127.0.0.254
+2001:db8::1
+2001:db8:cafe::/48
+2001:db8:cafe::1-2001:db8:cafe::ffff
+```
+### Network Groups
+**Network groups** accept IP networks in CIDR notation. You can add specific
+IP addresses as a 32-bit prefix. If you need to add a mix of addresses and
+networks, use a network group.
+```{cfgcmd} set firewall group network-group \<name\> network \<CIDR\>
+```
+
+```{cfgcmd} set firewall group ipv6-network-group \<name\> network \<CIDR\>
+
+Define an IPv4 or IPv6 network group.
+
+:::{code-block} none
+set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24
+set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24
+set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64
+:::
+```
+
+```{cfgcmd} set firewall group network-group \<name\> description \<text\>
+```
+
+```{cfgcmd} set firewall group ipv6-network-group \<name\> description \<text\>
+
+Provide an IPv4 or IPv6 network group description.
+```
+### Interface Groups
+An **interface group** represents a collection of interfaces.
+```{cfgcmd} set firewall group interface-group \<name\> interface \<text\>
+
+Define an interface group.
+Wildcard ``*`` is supported. For example: ``eth3*``.
+Prepend the character ``!`` to invert the criteria. For example: ``!eth2``.
+```
+
+```none
+set firewall group interface-group LAN interface bond1001
+set firewall group interface-group LAN interface eth3*
+```
+
+```{cfgcmd} set firewall group interface-group \<name\> description \<text\>
+
+Provide an interface group description.
+```
+### Port Groups
+A **port group** represents only port numbers, not the protocol. You can
+reference port groups for either TCP or UDP. Create TCP and UDP groups
+separately to avoid accidentally filtering unnecessary ports. Specify port
+ranges by using `-`.
+```{cfgcmd} set firewall group port-group \<name\> port [portname | portnumber | startport-endport]
+
+Define a port group. A port name can be any name defined in
+/etc/services. For example, ``http``.
+
+:::{code-block} none
+set firewall group port-group PORT-TCP-SERVER1 port http
+set firewall group port-group PORT-TCP-SERVER1 port 443
+set firewall group port-group PORT-TCP-SERVER1 port 5000-5010
+:::
+```
+
+```{cfgcmd} set firewall group port-group \<name\> description \<text\>
+
+Provide a port group description.
+```
+### MAC Groups
+A **mac group** represents a collection of mac addresses.
+```{cfgcmd} set firewall group mac-group \<name\> mac-address \<mac-address\>
+
+Define a mac group.
+```
+
+```none
+set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f
+set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81
+```
+
+```{cfgcmd} set firewall group mac-group \<name\> description \<text\>
+
+Provide a MAC group description.
+```
+### Domain Groups
+A **domain group** represents a collection of domains.
+```{cfgcmd} set firewall group domain-group \<name\> address \<domain\>
+
+Define a domain group.
+```
+
+```none
+set firewall group domain-group DOM address example.com
+```
+
+```{cfgcmd} set firewall group domain-group \<name\> description \<text\>
+
+Provide a domain group description.
+```
+### Dynamic Groups
+Firewall dynamic groups differ from other groups because you can use them as
+source/destination in firewall rules, and members are not defined statically
+in VyOS configuration. Instead, firewall rules dynamically add members to
+these groups.
+
+#### Defining Dynamic Address Groups
+Dynamic address groups support both IPv4 and IPv6 families. Use these
+commands to define dynamic IPv4 and IPv6 address groups:
+```{cfgcmd} set firewall group dynamic-group address-group \<name\>
+```
+
+```{cfgcmd} set firewall group dynamic-group ipv6-address-group \<name\>
+```
+Add description to firewall groups:
+```{cfgcmd} set firewall group dynamic-group address-group \<name\> description <text>
+```
+
+```{cfgcmd} set firewall group dynamic-group ipv6-address-group \<name\> description <text>
+```
+#### Adding elements to Dynamic Firewall Groups
+After you define dynamic firewall groups, use them in firewall rules to
+dynamically add elements to them.
+
+Commands used for this task are:
+- Add destination IP address of the connection to a dynamic address group:
+```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group destination-address address-group <name>
+```
+
+```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group destination-address address-group <name>
+```
+- Add source IP address of the connection to a dynamic address group:
+```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group source-address address-group <name>
+```
+
+```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group source-address address-group <name>
+```
+You can define specific timeouts per rule. When a rule matches, the source or
+destination address is added to the group, and the element remains in the group
+until the timeout expires. If you do not define a timeout, the element remains
+in the group until the next reboot or until you commit firewall configuration
+changes.
+```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout <timeout>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\>
+```
+
+```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout <timeout>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\>
+```
+Timeout can be defined using seconds, minutes, hours or days:
+```none
+set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout
+Possible completions:
+<number>s            Timeout value in seconds
+<number>m            Timeout value in minutes
+<number>h            Timeout value in hours
+<number>d            Timeout value in days
+```
+#### Using Dynamic Firewall Groups
+Like other firewall groups, you can use dynamic firewall groups in firewall
+rules as matching options. For example:
+```none
+set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO
+set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR
+```
+## Examples
+
+### General example
+After you create firewall groups, you can reference them in firewall, NAT,
+NAT66, and/or policy-route rules. The following example creates multiple
+groups:
+```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
+You can use dynamic firewall groups with port knocking to secure access to
+the router or any other device. The following example shows a 4-step port
+knocking configuration:
+```none
+set firewall global-options state-policy established action 'accept'
+set firewall global-options state-policy invalid action 'drop'
+set firewall global-options state-policy related action 'accept'
+set firewall group dynamic-group address-group ALLOWED
+set firewall group dynamic-group address-group PN_01
+set firewall group dynamic-group address-group PN_02
+set firewall ipv4 input filter default-action 'drop'
+set firewall ipv4 input filter rule 5 action 'accept'
+set firewall ipv4 input filter rule 5 protocol 'icmp'
+set firewall ipv4 input filter rule 10 action 'drop'
+set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01'
+set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m'
+set firewall ipv4 input filter rule 10 description 'Port_nock 01'
+set firewall ipv4 input filter rule 10 destination port '9990'
+set firewall ipv4 input filter rule 10 protocol 'tcp'
+set firewall ipv4 input filter rule 20 action 'drop'
+set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02'
+set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m'
+set firewall ipv4 input filter rule 20 description 'Port_nock 02'
+set firewall ipv4 input filter rule 20 destination port '9991'
+set firewall ipv4 input filter rule 20 protocol 'tcp'
+set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01'
+set firewall ipv4 input filter rule 30 action 'drop'
+set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED'
+set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h'
+set firewall ipv4 input filter rule 30 description 'Port_nock 03'
+set firewall ipv4 input filter rule 30 destination port '9992'
+set firewall ipv4 input filter rule 30 protocol 'tcp'
+set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02'
+set firewall ipv4 input filter rule 99 action 'accept'
+set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh'
+set firewall ipv4 input filter rule 99 destination port '22'
+set firewall ipv4 input filter rule 99 protocol 'tcp'
+set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED'
+```
+Before testing, we can check the members of firewall groups:
+```none
+vyos@vyos# run show firewall group
+Firewall Groups
+
+Name     Type                    References            Members        Timeout    Expires
+-------  ----------------------  --------------------  -------------  ---------  ---------
+ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+PN_01    address_group(dynamic)  ipv4-input-filter-10  N/D            N/D        N/D
+PN_02    address_group(dynamic)  ipv4-input-filter-20  N/D            N/D        N/D
+[edit]
+vyos@vyos#
+```
+With this configuration, to gain SSH access to the router, the user must:
+
+1. Create a new TCP connection to destination port 9990. A new entry is added
+   to dynamic firewall group `PN_01`.
+
+   ```none
+   vyos@vyos# run show firewall group
+   Firewall Groups
+
+   Name     Type                    References            Members        Timeout    Expires
+   -------  ----------------------  --------------------  -------------  ---------  ---------
+   ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+   PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31  120        119
+   PN_02    address_group(dynamic)  ipv4-input-filter-20  N/D            N/D        N/D
+   [edit]
+   vyos@vyos#
+   ```
+
+2. Create a new TCP connection to destination port 9991. A new entry is added
+   to dynamic firewall group `PN_02`.
+
+   ```none
+   vyos@vyos# run show firewall group
+   Firewall Groups
+
+   Name     Type                    References            Members        Timeout    Expires
+   -------  ----------------------  --------------------  -------------  ---------  ---------
+   ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+   PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31  120        106
+   PN_02    address_group(dynamic)  ipv4-input-filter-20  192.168.89.31  180        179
+   [edit]
+   vyos@vyos#
+   ```
+
+3. Create a new TCP connection to destination port 9992. A new entry is added
+   to dynamic firewall group `ALLOWED`.
+
+   ```none
+   vyos@vyos# run show firewall group
+   Firewall Groups
+
+   Name     Type                    References            Members        Timeout    Expires
+   -------  ----------------------  --------------------  -------------  ---------  ---------
+   ALLOWED  address_group(dynamic)  ipv4-input-filter-30  192.168.89.31       7200       7199
+   PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31        120         89
+   PN_02    address_group(dynamic)  ipv4-input-filter-20  192.168.89.31        180        170
+   [edit]
+   vyos@vyos#
+   ```
+
+4. Now you can connect via SSH to the router (assuming SSH is
+   configured).
+
+## Operation-mode
+```{opcmd} show firewall group
+```
+
+```{opcmd} show firewall group \<name\>
+
+Display an overview of defined groups, including the firewall group name,
+type, references (where the group is used), members, timeout, and
+expiration (the last two only apply to dynamic firewall groups).
+```
+Here is an example of such command:
+```none
+vyos@vyos:~$ show firewall group
+Firewall Groups
+
+Name          Type                    References              Members             Timeout    Expires
+------------  ----------------------  ----------------------  ----------------  ---------  ---------
+SERVERS       address_group           nat-destination-101     198.51.100.101
+                                                              198.51.100.102
+ALLOWED       address_group(dynamic)  ipv4-input-filter-30    192.168.77.39          7200       7174
+PN_01         address_group(dynamic)  ipv4-input-filter-10    192.168.0.245           120        112
+                                                              192.168.77.39           120         85
+PN_02         address_group(dynamic)  ipv4-input-filter-20    192.168.77.39           180        151
+LAN           interface_group         ipv4-output-filter-10   bon0
+                                      nat-destination-101     eth2.2001
+TRUSTEDv6     ipv6_network_group      ipv6-input-filter-10    2001:db8::/64
+TRUSTEDv4     network_group           ipv4-forward-filter-20  192.0.2.0/30
+                                                              203.0.113.128/25
+PORT-SERVERS  port_group              route-PBR-201           443
+                                      route-PBR-201           5000-5010
+                                      nat-destination-101     http
+vyos@vyos:~$
+```
diff --git a/docs/configuration/firewall/md-ipv6.md b/docs/configuration/firewall/md-ipv6.md
new file mode 100644
index 00000000..bbbaec16
--- /dev/null
+++ b/docs/configuration/firewall/md-ipv6.md
@@ -0,0 +1,1624 @@
+---
+lastproofread: '2026-04-01'
+---
+
+(firewall-ipv6-configuration)=
+
+# IPv6 Firewall Configuration
+
+## Overview
+
+This section covers useful information about IPv6 firewall configuration and
+appropriate operation-mode commands.
+
+This section describes the following configuration commands:
+
+```{cfgcmd} set firewall ipv6 ...
+```
+To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall </configuration/firewall/index>`.
+```none
+- set firewall
+    * ipv6
+         - forward
+            + filter
+         - input
+            + filter
+         - output
+            + filter
+            + raw
+         - prerouting
+            + raw
+         - name
+            + custom_name
+```
+The router first receives all traffic and processes it in the **prerouting**
+section.
+
+
+This stage includes:
+
+
+- **Firewall Prerouting**: commands found under `set firewall ipv6
+  prerouting raw ...`
+- {doc}`Conntrack Ignore</configuration/system/conntrack>`: `set system
+  conntrack ignore ipv6...`
+- {doc}`Policy Route</configuration/policy/route>`: commands found under
+  `set policy route6 ...`
+- {doc}`Destination NAT</configuration/nat/nat44>`: commands found under
+  `set nat66 destination ...`
+
+
+For transit traffic that the router receives and forwards, the base chain is
+**forward**. The following diagram shows a simplified packet flow for transit
+traffic:
+
+
+:::{figure} /_static/images/firewall-fwd-packet-flow.png
+:::
+
+
+Use `set firewall ipv6 forward filter ...` to configure filtering rules for
+transit traffic. This command corresponds to stage 5 and is highlighted in red
+in the diagram.
+
+
+For traffic destined to the router, use the **input** chain. For traffic the
+router generates, use the **output** chain. The following diagram shows the
+packet flow for traffic destined to the router and traffic generated by the
+router (starting from circle number 6):
+
+
+:::{figure} /_static/images/firewall-input-packet-flow.png
+:::
+
+
+Use `set firewall ipv6 input filter ...` to configure traffic destined to
+the router.
+
+
+Use `set firewall ipv6 output ...` to configure traffic the router generates.
+Two sub-chains are available: **filter** and **raw**:
+
+
+- **Output Prerouting**: `set firewall ipv6 output raw ...`.
+  As described in **Prerouting**, the firewall processes rules in this
+  section before the connection tracking subsystem.
+- **Output Filter**: `set firewall ipv6 output filter ...`. The firewall
+  processes rules in this section after the connection tracking subsystem.
+
+
+:::{note}
+**Important note about default-actions:**
+If you do not define a default action for a base chain, the system sets
+the default action to **accept** for that chain. For custom chains, if you
+do not define a default action, the system sets the default-action to
+**drop**
+:::
+
+
+Create custom firewall chains using the commands
+`set firewall ipv6 name <name> ...`. To use the custom chain, define a
+rule with **action jump** and the appropriate **target** in a base chain.
+
+
+## Firewall - IPv6 Rules
+
+
+Create firewall rules for firewall filtering. Each rule is numbered and has
+an action to apply when the rule is matched. You can specify multiple matching
+criteria. Packets go through rules from 1 - 999999, so order is crucial. The
+firewall executes the action of the first matching rule.
+
+
+### Actions
+
+
+If you define a rule, you must define an action for it. The action tells the
+firewall what to do when all criteria for that rule are met.
+
+
+The action can be :
+
+
+- `accept`: accept the packet.
+- `continue`: continue parsing next rule.
+- `drop`: drop the packet.
+- `reject`: reject the packet.
+- `jump`: jump to another custom chain.
+- `return`: Return from the current chain and continue at the next rule
+  of the last chain.
+- `queue`: Enqueue packet to userspace.
+- `synproxy`: synproxy the packet.
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return]
+
+
+This required setting defines the action of the current rule. If you set
+the action to jump, you must also define a jump-target.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> jump-target <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> jump-target <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> jump-target <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> jump-target <text>
+
+
+Use this command only when action is set to ``jump``. Specify the jump
+target.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue <0-65535>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue <0-65535>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue <0-65535>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> queue <0-65535>
+
+
+Use this command only when action is set to ``queue``. Specify the queue
+target. Queue ranges are also supported.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options bypass
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> queue-options bypass
+
+
+Use this command only when action is set to ``queue``. This command allows
+the packet to go through the firewall when no userspace software is connected
+to the queue.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options fanout
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> queue-options fanout
+
+
+Use this command only when action is set to ``queue``. This command
+distributes packets among multiple queues.
+```
+Also, **default-action** is an action that takes place whenever a packet does
+not match any rule in its chain. For base chains, possible options for
+**default-action** are **accept** or **drop**.
+```{cfgcmd} set firewall ipv6 forward filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall ipv6 input filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall ipv6 output filter default-action [accept | drop]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> default-action [accept | drop | jump | queue | reject | return]
+
+
+Set the default action of the rule-set if a packet does not match any rule
+criteria. If you set default-action to ``jump``, you must also define
+``default-jump-target``. For base chains, you can only set the default
+action to ``accept`` or ``drop``. For custom chains, more actions are
+available.
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> default-jump-target \<text\>
+
+To be used only when ``default-action`` is set to ``jump``. Use this
+command to specify the jump target for the default rule.
+```
+:::{note}
+**Important note about default-actions:**
+If you do not define the default action for a base chain, the system sets
+the default action to **accept** for that chain. For custom chains, if you
+do not define a default action, the system sets the default-action to
+**drop**.
+:::
+
+
+### Firewall Logs
+
+
+You can enable logging for each firewall rule. When enabled, you can also
+define other log options.
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log
+
+Enable logging for matched packets. If this configuration command is not
+present, logging is disabled.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter default-log
+```
+
+```{cfgcmd} set firewall ipv6 input filter default-log
+```
+
+```{cfgcmd} set firewall ipv6 output filter default-log
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> default-log
+
+Use this command to enable the logging of the default action on
+the specified chain.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug]
+
+
+Define log-level. Only applicable if rule log is enabled.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options group <0-65535>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options group <0-65535>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options group <0-65535>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options group <0-65535>
+
+
+Define the log group to send messages to. Only applicable if rule log is
+enabled.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options snapshot-length <0-9000>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options snapshot-length <0-9000>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options snapshot-length <0-9000>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options snapshot-length <0-9000>
+
+
+Define the length of packet payload to include in a netlink message. Only
+applicable when rule logging is enabled and log group is defined.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options queue-threshold <0-65535>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options queue-threshold <0-65535>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options queue-threshold <0-65535>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options queue-threshold <0-65535>
+
+
+Define the number of packets to queue inside the kernel before sending them
+to userspace. Only applicable when rule logging is enabled and log group is
+defined.
+```
+### Firewall Description
+
+
+For reference, you can define descriptions on every rule and custom chain.
+```{cfgcmd} set firewall ipv6 name \<name\> description \<text\>
+
+Provide a rule-set description to a custom firewall chain.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> description <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> description <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> description <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> description \<text\>
+
+Provide a description for each rule.
+```
+### Rule Status
+
+
+New rules are enabled by default. In some cases, you may want to disable a
+rule rather than remove it.
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> disable
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> disable
+
+Command for disabling a rule but keep it in the configuration.
+```
+### Matching criteria
+
+
+There are a lot of matching criteria against which the packet can be tested.
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-status nat [destination | source]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-status nat [destination | source]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-status nat [destination | source]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> connection-status nat [destination | source]
+
+
+Match packets based on NAT connection status.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-mark <1-2147483647>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-mark <1-2147483647>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-mark <1-2147483647>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> connection-mark <1-2147483647>
+
+
+Match packets based on connection mark.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address [address | addressrange | CIDR]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination address [address | addressrange | CIDR]
+
+
+Match based on source or destination address. This is similar to network
+groups, but you can negate the matching addresses here.
+
+
+:::{code-block} none
+set firewall ipv6 name FOO rule 100 source address 2001:db8::202
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address-mask [address]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination address-mask [address]
+
+
+Apply an arbitrary netmask to mask addresses and match only a specific
+portion. This is useful for IPv6 because rules remain valid when the IPv6
+prefix changes if the host portion of the system's IPv6 address is static.
+Examples include SLAAC and [tokenised IPv6 addresses](https://datatracker.ietf.org/doc/id/draft-chown-6man-tokenised-ipv6-identifiers-02.txt)
+
+
+This function works 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
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source fqdn <fqdn>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source fqdn <fqdn>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source fqdn <fqdn>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source fqdn <fqdn>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination fqdn <fqdn>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination fqdn <fqdn>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination fqdn <fqdn>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination fqdn <fqdn>
+
+
+Specify a Fully Qualified Domain Name as source or destination to match.
+Ensure that the router can resolve the DNS query.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip country-code <country>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip country-code <country>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip country-code <country>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source geoip country-code <country>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip country-code <country>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip country-code <country>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip country-code <country>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination geoip country-code <country>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip inverse-match
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination geoip inverse-match
+
+
+Match IP addresses based on their geolocation. For more information, see
+[GeoIP matching](https://wiki.nftables.org/wiki-nftables/index.php/GeoIP_matching).
+Use inverse-match to match anything except the specified country codes.
+```
+DB-IP.com provides data under CC-BY-4.0 license. Attribution is required and
+redistribution is permitted, allowing VyOS to include a database in images
+(approximately 3 MB compressed). The package includes a cron script that you
+can manually call through op-mode update geoip to keep the database and rules
+updated.
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source mac-address <mac-address>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source mac-address <mac-address>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source mac-address <mac-address>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source mac-address <mac-address>
+
+
+You can specify only a source MAC address to match.
+
+
+:::{code-block} none
+set firewall ipv6 input filter rule 100 source mac-address 00:53:00:11:22:33
+set firewall ipv6 input filter rule 101 source mac-address !00:53:00:aa:12:34
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination port [1-65535 | portname | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination port [1-65535 | portname | start-end]
+
+
+Specify a port by number or by name as defined in ``/etc/services``.
+
+
+:::{code-block} none
+set firewall ipv6 forward filter rule 10 source port '22'
+set firewall ipv6 forward filter rule 11 source port '!http'
+set firewall ipv6 forward filter rule 12 source port 'https'
+:::
+Multiple source ports can be specified as a comma-separated list.
+The whole list can also be "negated" using ``!``. For example:
+
+
+:::{code-block} none
+set firewall ipv6 forward filter rule 10 source port '!22,https,3333-3338'
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group address-group <name | !name>
+
+
+Specify an address group. You can prepend the character ``!`` to invert the
+matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group dynamic-address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group dynamic-address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group dynamic-address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group dynamic-address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group dynamic-address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group dynamic-address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group dynamic-address-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group dynamic-address-group <name | !name>
+
+
+Specify a dynamic address group. You can prepend the character ``!`` to
+invert the matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group network-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group network-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group network-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group network-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group network-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group network-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group network-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group network-group <name | !name>
+
+
+Specify a network group. You can prepend the character ``!`` to invert the
+matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group port-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group port-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group port-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group port-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group port-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group port-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group port-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group port-group <name | !name>
+
+
+Specify a port group. You can prepend the character ``!`` to invert the
+matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group domain-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group domain-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group domain-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group domain-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group domain-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group domain-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group domain-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group domain-group <name | !name>
+
+
+Specify a domain group. You can prepend the character ``!`` to invert the
+matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group mac-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group mac-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group mac-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group mac-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group mac-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group mac-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group mac-group <name | !name>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group mac-group <name | !name>
+
+
+Specify a MAC group. You can prepend the character ``!`` to invert the
+matching criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> dscp [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp-exclude [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp-exclude [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp-exclude [0-63 | start-end]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> dscp-exclude [0-63 | start-end]
+
+
+Match based on dscp value.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> fragment [match-frag | match-non-frag]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> fragment [match-frag | match-non-frag]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> fragment [match-frag | match-non-frag]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> fragment [match-frag | match-non-frag]
+
+
+Match packets based on fragmentation.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 [code | type] <0-255>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 [code | type] <0-255>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 [code | type] <0-255>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> icmpv6 [code | type] <0-255>
+
+
+Match packets based on ICMP or ICMPv6 code and type.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 type-name <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 type-name <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 type-name <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> icmpv6 type-name <text>
+
+
+Match based on ICMPv6 type-name. Press **Tab** for information about
+supported **type-name** criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface name <iface>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface name <iface>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> inbound-interface name <iface>
+
+
+Match based on inbound interface. You can use the wildcard ``*``. For
+example: ``eth2*``. You can prepend the character ``!`` to invert the
+matching criteria. For example ``!eth2``
+```
+:::{note}
+If an interface is attached to a non-default VRF, when using
+**inbound-interface**, use the VRF name. For example:
+`set firewall ipv6 forward filter rule 10 inbound-interface name MGMT`
+:::
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface group <iface_group>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface group <iface_group>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> inbound-interface group <iface_group>
+
+
+Match based on the inbound interface group. You can prepend the character
+``!`` to invert the matching criteria. For example ``!IFACE_GROUP``
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface name <iface>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface name <iface>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> outbound-interface name <iface>
+
+
+Match based on outbound interface. You can use the wildcard ``*``. For
+example: ``eth2*``. You can prepend the character ``!`` to invert the
+matching criteria. For example ``!eth2``
+```
+:::{note}
+If an interface is attached to a non-default VRF, when using
+**outbound-interface**, use the physical interface name. For example:
+`set firewall ipv6 forward filter rule 10 outbound-interface name eth0`
+:::
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface group <iface_group>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface group <iface_group>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> outbound-interface group <iface_group>
+
+
+Match based on outbound interface group. You can prepend the character ``!``
+to invert the matching criteria. For example ``!IFACE_GROUP``
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> ipsec [match-ipsec-in | match-none-in]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> ipsec [match-ipsec-out | match-none-out]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out]
+
+
+Match packets based on IPsec.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit burst <0-4294967295>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit burst <0-4294967295>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit burst <0-4294967295>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> limit burst <0-4294967295>
+
+
+Match based on the maximum number of packets allowed to exceed the rate
+limit.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit rate <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit rate <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit rate <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> limit rate <text>
+
+
+Match based on the maximum average rate, specified as ``integer/unit``.
+For example, specify ``5/minutes``.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> packet-length <text>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length-exclude <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length-exclude <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length-exclude <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> packet-length-exclude <text>
+
+
+Match based on packet length. You can specify multiple values from 1 to
+65535 and ranges.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> packet-type [broadcast | host | multicast | other]
+
+
+Match based on packet type.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> protocol [<text> | <0-255> | all | tcp_udp]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> protocol [<text> | <0-255> | all | tcp_udp]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> protocol [<text> | <0-255> | all | tcp_udp]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> protocol [<text> | <0-255> | all | tcp_udp]
+
+
+Match based on protocol number or name as defined in ``/etc/protocols``.
+Specify ``all`` for all protocols and ``tcp_udp`` for TCP and UDP packets.
+Prepend ``!`` to negate the protocol selection.
+
+
+:::{code-block} none
+set firewall ipv6 input filter rule 10 protocol tcp
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count <1-255>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count <1-255>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count <1-255>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent count <1-255>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time [second | minute | hour]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time [second | minute | hour]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time [second | minute | hour]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent time [second | minute | hour]
+
+
+Match packets based on recently seen sources.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> tcp flags [not] <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> tcp flags [not] <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> tcp flags [not] <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> tcp flags [not] <text>
+
+
+Allowed values for TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``,
+``rst``, ``syn``, and ``urg``. You can specify multiple values. To invert
+the selection, use ``not``, as shown in the following example.
+
+
+:::{code-block} none
+set firewall ipv6 input filter rule 10 tcp flags 'ack'
+set firewall ipv6 input filter rule 12 tcp flags 'syn'
+set firewall ipv6 input filter rule 13 tcp flags not 'fin'
+:::
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> state [established | invalid | new | related]
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> state [established | invalid | new | related]
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> state [established | invalid | new | related]
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> state [established | invalid | new | related]
+
+
+Match based on packet state.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time startdate <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time startdate <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time startdate <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time startdate <text>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time starttime <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time starttime <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time starttime <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time starttime <text>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stopdate <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stopdate <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stopdate <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time stopdate <text>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stoptime <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stoptime <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stoptime <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time stoptime <text>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time weekdays <text>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time weekdays <text>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time weekdays <text>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time weekdays <text>
+
+
+Match packets based on time criteria.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> hop-limit <eq | gt | lt> <0-255>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> hop-limit <eq | gt | lt> <0-255>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> hop-limit <eq | gt | lt> <0-255>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> hop-limit <eq | gt | lt> <0-255>
+
+
+Match the hop-limit parameter. Use ``eq`` for equal, ``gt`` for greater than,
+and ``lt`` for less than.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count <1-255>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count <1-255>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count <1-255>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent count <1-255>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time <second | minute | hour>
+```
+
+```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time <second | minute | hour>
+```
+
+```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time <second | minute | hour>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent time <second | minute | hour>
+
+
+Match when the specified number of connections occur within the specified
+time period. Use these criteria to block brute-force attempts.
+```
+### Packet Modifications
+
+
+The firewall can modify packets before sending them.
+This feature provides more flexibility for packet handling.
+```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set dscp <0-63>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set dscp <0-63>
+```
+
+```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set dscp <0-63>
+
+
+Set a specific value of Differentiated Services Codepoint (DSCP).
+```
+
+```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set mark <1-2147483647>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set mark <1-2147483647>
+```
+
+```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set mark <1-2147483647>
+
+
+Set a specific packet mark value.
+```
+
+```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set tcp-mss <500-1460>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set tcp-mss <500-1460>
+```
+
+```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set tcp-mss <500-1460>
+
+
+Set the TCP-MSS (TCP maximum segment size) for the connection.
+```
+
+```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set hop-limit <0-255>
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set hop-limit <0-255>
+```
+
+```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set hop-limit <0-255>
+
+
+Set hop limit value.
+```
+
+```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set connection-mark <0-2147483647>
+```
+
+```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set connection-mark <0-2147483647>
+
+
+Set connection mark value.
+```
+## Synproxy
+
+
+Synproxy connections
+```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> action synproxy
+```
+
+```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> protocol tcp
+```
+
+```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp mss <501-65535>
+
+
+ Set the TCP MSS (maximum segment size) for the connection.
+```
+
+```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp window-scale <1-14>
+
+
+ Set the window scale factor for TCP window scaling.
+```
+### Example synproxy
+
+
+Requirements to enable synproxy:
+
+
+- Traffic must be symmetric
+- Synproxy relies on syncookies and TCP timestamps, ensure these are enabled
+- Disable conntrack loose track option
+```none
+
+set system sysctl parameter net.ipv4.tcp_timestamps value '1'
+
+
+set system conntrack tcp loose disable
+
+set system conntrack ignore ipv6 rule 10 destination port '8080'
+
+set system conntrack ignore ipv6 rule 10 protocol 'tcp'
+
+set system conntrack ignore ipv6 rule 10 tcp flags syn
+
+
+set firewall global-options syn-cookies 'enable'
+
+set firewall ipv6 input filter rule 10 action 'synproxy'
+
+set firewall ipv6 input filter rule 10 destination port '8080'
+
+set firewall ipv6 input filter rule 10 inbound-interface name 'eth1'
+
+set firewall ipv6 input filter rule 10 protocol 'tcp'
+
+set firewall ipv6 input filter rule 10 synproxy tcp mss '1460'
+
+set firewall ipv6 input filter rule 10 synproxy tcp window-scale '7'
+
+set firewall ipv6 input filter rule 1000 action 'drop'
+
+set firewall ipv6 input filter rule 1000 state invalid
+
+```
+## Operation-mode Firewall
+
+
+### Rule-set overview
+```{opcmd} show firewall
+
+Show a basic firewall overview for all rule-sets, not only for IPv6:
+
+
+:::{code-block} none
+vyos@vyos:~$ show firewall
+Rulesets Information
+
+
+---------------------------------
+IPv4 Firewall "forward filter"
+
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  -----------------------------------------
+5        jump      all                 0        0  iifname "eth1"  jump NAME_VyOS_MANAGEMENT
+10       jump      all                 0        0  oifname "eth1"  jump NAME_WAN_IN
+15       jump      all                 0        0  iifname "eth3"  jump NAME_WAN_IN
+default  accept    all
+
+
+---------------------------------
+IPv4 Firewall "name VyOS_MANAGEMENT"
+
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  --------------------------------
+5        accept    all                 0        0  ct state established  accept
+10       drop      all                 0        0  ct state invalid
+20       accept    all                 0        0  ip saddr @A_GOOD_GUYS  accept
+30       accept    all                 0        0  ip saddr @N_ENTIRE_RANGE  accept
+40       accept    all                 0        0  ip saddr @A_VyOS_SERVERS  accept
+50       accept    icmp                0        0  meta l4proto icmp  accept
+default  drop      all                 0        0
+
+
+---------------------------------
+IPv6 Firewall "forward filter"
+
+
+Rule     Action    Protocol
+-------  --------  ----------
+5        jump      all
+10       jump      all
+15       jump      all
+default  accept    all
+
+
+---------------------------------
+IPv6 Firewall "input filter"
+
+
+Rule     Action    Protocol
+-------  --------  ----------
+5        jump      all
+default  accept    all
+
+
+---------------------------------
+IPv6 Firewall "ipv6_name IPV6-VyOS_MANAGEMENT"
+
+
+Rule     Action    Protocol
+-------  --------  ----------
+5        accept    all
+10       drop      all
+20       accept    all
+30       accept    all
+40       accept    all
+50       accept    ipv6-icmp
+default  drop      all
+:::
+```
+
+```{opcmd} show firewall summary
+
+This will show you a summary of rule-sets and groups
+
+
+:::{code-block} none
+vyos@vyos:~$ show firewall summary
+Ruleset Summary
+
+
+IPv6 Ruleset:
+
+
+Ruleset Hook    Ruleset Priority      Description
+--------------  --------------------  -------------------------
+forward         filter
+input           filter
+ipv6_name       IPV6-VyOS_MANAGEMENT
+ipv6_name       IPV6-WAN_IN           PUBLIC_INTERNET
+
+
+IPv4 Ruleset:
+
+
+Ruleset Hook    Ruleset Priority    Description
+--------------  ------------------  -------------------------
+forward         filter
+input           filter
+name            VyOS_MANAGEMENT
+name            WAN_IN              PUBLIC_INTERNET
+
+
+Firewall Groups
+
+
+Name                     Type                References               Members
+-----------------------  ------------------  -----------------------  ----------------
+PBX                      address_group       WAN_IN-100               198.51.100.77
+SERVERS                  address_group       WAN_IN-110               192.0.2.10
+WAN_IN-111               192.0.2.11
+WAN_IN-112               192.0.2.12
+WAN_IN-120
+WAN_IN-121
+WAN_IN-122
+SUPPORT                  address_group       VyOS_MANAGEMENT-20       192.168.1.2
+WAN_IN-20
+PHONE_VPN_SERVERS        address_group       WAN_IN-160               10.6.32.2
+PINGABLE_ADRESSES        address_group       WAN_IN-170               192.168.5.2
+WAN_IN-171
+PBX                      ipv6_address_group  IPV6-WAN_IN-100          2001:db8::1
+SERVERS                  ipv6_address_group  IPV6-WAN_IN-110          2001:db8::2
+IPV6-WAN_IN-111          2001:db8::3
+IPV6-WAN_IN-112          2001:db8::4
+IPV6-WAN_IN-120
+IPV6-WAN_IN-121
+IPV6-WAN_IN-122
+SUPPORT                  ipv6_address_group  IPV6-VyOS_MANAGEMENT-20  2001:db8::5
+IPV6-WAN_IN-20
+:::
+```
+
+```{opcmd} show firewall ipv6 [forward | input | output] filter
+```
+
+```{opcmd} show firewall ipv6 ipv6-name \<name\>
+
+This command will give an overview of a single rule-set.
+
+
+:::{code-block} none
+vyos@vyos:~$ show firewall ipv6 input filter
+Ruleset Information
+
+
+---------------------------------
+ipv6 Firewall "input filter"
+
+
+Rule     Action    Protocol      Packets    Bytes  Conditions
+-------  --------  ----------  ---------  -------  ------------------------------------------------------------------------------
+10       jump      all                13     1456  iifname "eth1"  jump NAME6_INP-ETH1
+20       accept    ipv6-icmp          10     1112  meta l4proto ipv6-icmp iifname "eth0"  prefix "[ipv6-INP-filter-20-A]"  accept
+default  accept    all                14     1584
+
+
+vyos@vyos:~$
+:::
+```
+
+```{opcmd} show firewall ipv6 [forward | input | output] filter rule <1-999999>
+```
+
+```{opcmd} show firewall ipv6 name \<name\> rule \<1-999999\>
+```
+
+```{opcmd} show firewall ipv6 ipv6-name \<name\> rule \<1-999999\>
+
+This command will give an overview of a rule in a single rule-set
+```
+
+```{opcmd} show firewall group \<name\>
+
+Show an overview of defined groups, including the type, members, and where
+the group is used.
+
+
+:::{code-block} none
+vyos@vyos:~$ show firewall group LAN
+Firewall Groups
+
+
+Name          Type                References               Members
+------------  ------------------  -----------------------  ----------------
+LAN           ipv6_network_group  IPV6-VyOS_MANAGEMENT-30  2001:db8::0/64
+IPV6-WAN_IN-30
+LAN           network_group       VyOS_MANAGEMENT-30       192.168.200.0/24
+WAN_IN-30
+:::
+```
+
+```{opcmd} show firewall statistics
+
+Show statistics of all rule-sets since the last boot.
+```
+### Show Firewall log
+```{opcmd} show log firewall
+```
+
+```{opcmd} show log firewall ipv6
+```
+
+```{opcmd} show log firewall ipv6 [forward | input | output | name]
+```
+
+```{opcmd} show log firewall ipv6 [forward | input | output] filter
+```
+
+```{opcmd} show log firewall ipv6 name \<name\>
+```
+
+```{opcmd} show log firewall ipv6 [forward | input | output] filter rule \<rule\>
+```
+
+```{opcmd} show log firewall ipv6 name \<name\> rule \<rule\>
+
+Show firewall logs for all firewalls, all IPv6 firewalls, specific hooks,
+specific priorities, specific custom chains, or specific rule-sets.
+```
+### Example Partial Config
+```none
+firewall {
+    ipv6 {
+        input {
+            filter {
+                rule 10 {
+                    action jump
+                    inbound-interface {
+                        name eth1
+                    }
+                    jump-target INP-ETH1
+                }
+                rule 20 {
+                    action accept
+                    inbound-interface {
+                        name eth0
+                    }
+                    log
+                    protocol ipv6-icmp
+                }
+            }
+        }
+        name INP-ETH1 {
+            default-action drop
+            default-log
+            rule 10 {
+                action accept
+                protocol tcp_udp
+            }
+        }
+    }
+}
+```
+### Update geoip database
+```{opcmd} update geoip
+
+Command used to update GeoIP database and firewall sets.
+```
\ No newline at end of file
diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md
new file mode 100644
index 00000000..9082cd80
--- /dev/null
+++ b/docs/configuration/interfaces/md-index.md
@@ -0,0 +1,26 @@
+# Interfaces
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+bonding
+bridge
+dummy
+ethernet
+geneve
+l2tpv3
+loopback
+macsec
+openvpn
+wireguard
+pppoe
+pseudo-ethernet
+sstp-client
+tunnel
+virtual-ethernet
+vti
+vxlan
+wireless
+wwan
+```
diff --git a/docs/configuration/loadbalancing/md-index.md b/docs/configuration/loadbalancing/md-index.md
new file mode 100644
index 00000000..3241edb7
--- /dev/null
+++ b/docs/configuration/loadbalancing/md-index.md
@@ -0,0 +1,15 @@
+---
+lastproofread: '2026-04-06'
+---
+
+(load-balancing)=
+
+# Load-balancing
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+wan
+haproxy
+```
diff --git a/docs/configuration/md-index.md b/docs/configuration/md-index.md
new file mode 100644
index 00000000..3e215502
--- /dev/null
+++ b/docs/configuration/md-index.md
@@ -0,0 +1,23 @@
+# Configuration Guide
+
+The following structure represents the CLI structure.
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+container/index
+firewall/index
+highavailability/index
+interfaces/index
+loadbalancing/index
+nat/index
+policy/index
+pki/index
+protocols/index
+service/index
+system/index
+trafficpolicy/index
+vpn/index
+vrf/index
+```
diff --git a/docs/configuration/nat/md-index.md b/docs/configuration/nat/md-index.md
new file mode 100644
index 00000000..35e5d32b
--- /dev/null
+++ b/docs/configuration/nat/md-index.md
@@ -0,0 +1,13 @@
+(nat)=
+
+# NAT
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+nat44
+nat64
+nat66
+cgnat
+```
diff --git a/docs/configuration/pki/md-index.md b/docs/configuration/pki/md-index.md
new file mode 100644
index 00000000..be59e30f
--- /dev/null
+++ b/docs/configuration/pki/md-index.md
@@ -0,0 +1,551 @@
+---
+lastproofread: '2024-01-05'
+---
+
+```{include} /_include/need_improvement.txt
+```
+
+(pki)=
+
+# PKI
+VyOS 1.4 changed the way in how encryption keys or certificates are stored on the
+system. In the pre VyOS 1.4 era, certificates got stored under /config and every
+service referenced a file. That made copying a running configuration from system
+A to system B a bit harder, as you had to copy the files and their permissions
+by hand.
+
+{vytask}`T3642` describes a new CLI subsystem that serves as a "certstore" to
+all services requiring any kind of encryption key(s). In short, public and
+private certificates are now stored in PKCS#8 format in the regular VyOS CLI.
+Keys can now be added, edited, and deleted using the regular set/edit/delete
+CLI commands.
+
+VyOS not only can now manage certificates issued by 3rd party Certificate
+Authorities, it can also act as a CA on its own. You can create your own root
+CA and sign keys with it by making use of some simple op-mode commands.
+
+Don't be afraid that you need to re-do your configuration. Key transformation is
+handled, as always, by our migration scripts, so this will be a smooth transition
+for you!
+
+## Key Generation
+
+### Certificate Authority (CA)
+VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other
+keypairs from an easy to access operational level command.
+```{opcmd} generate pki ca
+
+Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and
+private key on the console.
+```
+
+```{opcmd} generate pki ca install \<name\>
+
+Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and
+private key on the console.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+
+```{opcmd} generate pki ca sign \<ca-name\>
+
+Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using
+the private key referenced by ca-name.
+```
+
+```{opcmd} generate pki ca sign \<ca-name\> install \<name\>
+
+Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using
+the private key referenced by `name`.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+### Certificates
+```{opcmd} generate pki certificate
+
+Create a new public/private keypair and output the certificate on the console.
+```
+
+```{opcmd} generate pki certificate install \<name\>
+
+Create a new public/private keypair and output the certificate on the console.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+
+```{opcmd} generate pki certificate self-signed
+
+Create a new self-signed certificate. The public/private is then shown on the
+console.
+```
+
+```{opcmd} generate pki certificate self-signed install \<name\>
+
+Create a new self-signed certificate. The public/private is then shown on the
+console.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+
+```{opcmd} generate pki certificate sign \<ca-name\>
+
+Create a new public/private keypair which is signed by the CA referenced by
+ca-name. The signed certificate is then output to the console.
+```
+
+```{opcmd} generate pki certificate sign \<ca-name\> install \<name\>
+
+Create a new public/private keypair which is signed by the CA referenced by
+ca-name. The signed certificate is then output to the console.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+### Diffie-Hellman parameters
+```{opcmd} generate pki dh
+
+Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size
+is requested by the CLI and defaults to 2048 bit.
+
+The generated parameters are then output to the console.
+```
+
+```{opcmd} generate pki dh install \<name\>
+
+Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size
+is requested by the CLI and defaults to 2048 bit.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+### OpenVPN
+```{opcmd} generate pki openvpn shared-secret
+
+Generate a new OpenVPN shared secret. The generated secret is the output to
+the console.
+```
+
+```{opcmd} generate pki openvpn shared-secret install \<name\>
+
+Generate a new OpenVPN shared secret. The generated secret is the output to
+the console.
+
+:::{note}
+In addition to the command above, the output is in a format which can be used
+to directly import the key into the VyOS CLI by simply copy-pasting the output
+from op-mode into configuration mode.
+
+``name`` is used for the VyOS CLI command to identify this key. This
+key ``name`` is then used in the CLI configuration to reference the key
+instance.
+:::
+```
+### WireGuard
+```{opcmd} generate pki wireguard key-pair
+
+Generate a new WireGuard public/private key portion and output the result to
+the console.
+```
+
+```{opcmd} generate pki wireguard key-pair install \<interface\>
+
+Generate a new WireGuard public/private key portion and output the result to
+the console.
+
+:::{note}
+In addition to the command above, the output is in a format which can
+be used to directly import the key into the VyOS CLI by simply copy-pasting
+the output from op-mode into configuration mode.
+
+``interface`` is used for the VyOS CLI command to identify the WireGuard
+interface where this private key is to be used.
+:::
+```
+
+```{opcmd} generate pki wireguard preshared-key
+
+Generate a WireGuard pre-shared secret used for peers to communicate.
+```
+
+```{opcmd} generate pki wireguard preshared-key install \<peer\>
+
+Generate a WireGuard pre-shared secret used for peers to communicate.
+
+:::{note}
+In addition to the command above, the output is in a format which can
+be used to directly import the key into the VyOS CLI by simply copy-pasting
+the output from op-mode into configuration mode.
+
+``peer`` is used for the VyOS CLI command to identify the WireGuard peer where
+this secret is to be used.
+:::
+```
+## Key usage (CLI)
+### CA (Certificate Authority)
+```{cfgcmd} set pki ca \<name\> certificate
+
+Add the public CA certificate for the CA named `name` to the VyOS CLI.
+
+:::{note}
+When loading the certificate you need to manually strip the
+``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags.
+Also, the certificate/key needs to be presented in a single line without
+line breaks (``\n``), this can be done using the following shell command:
+
+``$ tail -n +2 ca.pem | head -n -1 | tr -d '\n'``
+:::
+```
+
+```{cfgcmd} set pki ca \<name\> crl
+
+Certificate revocation list in PEM format.
+```
+
+```{cfgcmd} set pki ca \<name\> description
+
+A human readable description what this CA is about.
+```
+
+```{cfgcmd} set pki ca \<name\> private key
+
+Add the CAs private key to the VyOS CLI. This should never leave the system,
+and is only required if you use VyOS as your certificate generator as
+mentioned above.
+
+:::{note}
+When loading the certificate you need to manually strip the
+``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the
+certificate/key needs to be presented in a single line without line
+breaks (``\n``), this can be done using the following shell command:
+
+``$ tail -n +2 ca.key | head -n -1 | tr -d '\n'``
+:::
+```
+
+```{cfgcmd} set pki ca \<name\> private password-protected
+
+Mark the CAs private key as password protected. User is asked for the password
+when the key is referenced.
+```
+### Server Certificate
+After we have imported the CA certificate(s) we can now import and add
+certificates used by services on this router.
+```{cfgcmd} set pki certificate \<name\> certificate
+
+Add public key portion for the certificate named `name` to the VyOS CLI.
+
+:::{note}
+When loading the certificate you need to manually strip the
+``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags.
+Also, the certificate/key needs to be presented in a single line without
+line breaks (``\n``), this can be done using the following shell command:
+
+``$ tail -n +2 cert.pem | head -n -1 | tr -d '\n'``
+:::
+```
+
+```{cfgcmd} set pki certificate \<name\> description
+
+A human readable description what this certificate is about.
+```
+
+```{cfgcmd} set pki certificate \<name\> private key
+
+Add the private key portion of this certificate to the CLI. This should never
+leave the system as it is used to decrypt the data.
+
+:::{note}
+When loading the certificate you need to manually strip the
+``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the
+certificate/key needs to be presented in a single line without line
+breaks (``\n``), this can be done using the following shell command:
+
+``$ tail -n +2 cert.key | head -n -1 | tr -d '\n'``
+:::
+```
+
+```{cfgcmd} set pki certificate \<name\> private password-protected
+
+Mark the private key as password protected. User is asked for the password
+when the key is referenced.
+```
+
+```{cfgcmd} set pki certificate \<name\> revoke
+
+If CA is present, this certificate will be included in generated CRLs
+```
+### Import files to PKI format
+VyOS provides this utility to import existing certificates/key files directly
+into PKI from op-mode. Previous to VyOS 1.4, certificates were stored under the
+/config folder permanently and will be retained post upgrade.
+```{opcmd} import pki ca \<name\> file \<Path to CA certificate file\>
+
+Import the public CA certificate from the defined file to VyOS CLI.
+```
+
+```{opcmd} import pki ca \<name\> key-file \<Path to private key file\>
+
+Import the CAs private key portion to the CLI. This should never leave the
+system as it is used to decrypt the data. The key is required if you use
+VyOS as your certificate generator.
+```
+
+```{opcmd} import pki certificate \<name\> file \<path to certificate\>
+
+Import the certificate from the file to VyOS CLI.
+```
+
+```{opcmd} import pki certificate \<name\> key-file \<path to private key\>
+
+Import the private key of the certificate to the VyOS CLI. This should never
+leave the system as it is used to decrypt the data.
+```
+
+```{opcmd} import pki openvpn shared-secret \<name\> file \<path to OpenVPN secret key\>
+
+Import the OpenVPN shared secret stored in file to the VyOS CLI.
+```
+#### ACME
+The VyOS PKI subsystem can also be used to automatically retrieve Certificates
+using the {abbr}`ACME (Automatic Certificate Management Environment)` protocol.
+```{cfgcmd} set pki certificate \<name\> acme domain-name \<name\>
+
+Domain names to apply, multiple domain-names can be specified.
+
+This is a mandatory option
+```
+
+```{cfgcmd} set pki certificate \<name\> acme email \<address\>
+
+Email used for registration and recovery contact.
+
+This is a mandatory option
+```
+
+```{cfgcmd} set pki certificate \<name\> acme listen-address \<address\>
+
+The address the server listens to during http-01 challenge
+```
+
+```{cfgcmd} set pki certificate \<name\> acme rsa-key-size \<2048 | 3072 | 4096\>
+
+Size of the RSA key.
+
+This options defaults to 2048
+```
+
+```{cfgcmd} set pki certificate \<name\> acme url \<url\>
+
+ACME Directory Resource URI.
+
+This defaults to https://acme-v02.api.letsencrypt.org/directory
+
+:::{note}
+During initial deployment we recommend using the staging API
+of LetsEncrypt to prevent and blacklisting of your system. The API
+endpoint is https://acme-staging-v02.api.letsencrypt.org/directory
+:::
+```
+## Operation
+VyOS operational mode commands are not only available for generating keys but
+also to display them.
+```{opcmd} show pki ca
+
+Show a list of installed {abbr}`CA (Certificate Authority)` certificates.
+
+:::{code-block} none
+vyos@vyos:~$ show pki ca
+Certificate Authorities:
+Name            Subject                                                  Issuer CN          Issued               Expiry               Private Key    Parent
+--------------  -------------------------------------------------------  -----------------  -------------------  -------------------  -------------  --------------
+DST_Root_CA_X3  CN=ISRG Root X1,O=Internet Security Research Group,C=US  CN=DST Root CA X3  2021-01-20 19:14:03  2024-09-30 18:14:03  No             N/A
+R3              CN=R3,O=Let's Encrypt,C=US                               CN=ISRG Root X1    2020-09-04 00:00:00  2025-09-15 16:00:00  No             DST_Root_CA_X3
+vyos_rw         CN=VyOS RW CA,O=VyOS,L=Some-City,ST=Some-State,C=GB      CN=VyOS RW CA      2021-07-05 13:46:03  2026-07-04 13:46:03  Yes            N/A
+:::
+```
+
+```{opcmd} show pki ca \<name\>
+
+Show only information for specified Certificate Authority.
+```
+
+```{opcmd} show pki certificate
+
+Show a list of installed certificates
+
+:::{code-block} none
+vyos@vyos:~$ show pki certificate
+Certificates:
+Name       Type    Subject CN             Issuer CN      Issued               Expiry               Revoked    Private Key    CA Present
+---------  ------  ---------------------  -------------  -------------------  -------------------  ---------  -------------  -------------
+ac2        Server  CN=ac2.vyos.net        CN=R3          2021-07-05 07:29:59  2021-10-03 07:29:58  No         Yes            Yes (R3)
+rw_server  Server  CN=VyOS RW             CN=VyOS RW CA  2021-07-05 13:48:02  2022-07-05 13:48:02  No         Yes            Yes (vyos_rw)
+:::
+```
+
+```{opcmd} show pki certificate \<name\>
+
+Show only information for specified certificate.
+```
+
+```{opcmd} show pki crl
+
+Show a list of installed {abbr}`CRLs (Certificate Revocation List)`.
+```
+
+```{opcmd} renew certbot
+
+Manually trigger certificate renewal. This will be done twice a day.
+```
+## Examples
+
+### Create a CA chain and leaf certificates
+This configuration generates & installs into the VyOS PKI system a root
+certificate authority, alongside two intermediary certificate authorities for
+client & server certificates. These CAs are then used to generate a server
+certificate for the router, and a client certificate for a user.
+- `vyos_root_ca` is the root certificate authority.
+- `vyos_client_ca` and `vyos_server_ca` are intermediary certificate authorities,
+  which are signed by the root CA.
+- `vyos_cert` is a leaf server certificate used to identify the VyOS router,
+  signed by the server intermediary CA.
+- `vyos_example_user` is a leaf client certificate used to identify a user,
+  signed by client intermediary CA.
+
+First, we create the root certificate authority.
+```none
+[edit]
+vyos@vyos# run generate pki ca install vyos_root_ca
+Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa
+Enter private key bits: (Default: 2048) 2048
+Enter country code: (Default: GB) GB
+Enter state: (Default: Some-State) Some-State
+Enter locality: (Default: Some-City) Some-City
+Enter organization name: (Default: VyOS) VyOS
+Enter common name: (Default: vyos.io) VyOS Root CA
+Enter how many days certificate will be valid: (Default: 1825) 1825
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N] n
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+```
+Secondly, we create the intermediary certificate authorities, which are used to
+sign the leaf certificates.
+```none
+[edit]
+vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_server_ca
+Do you already have a certificate request? [y/N] n
+Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa
+Enter private key bits: (Default: 2048) 2048
+Enter country code: (Default: GB) GB
+Enter state: (Default: Some-State) Some-State
+Enter locality: (Default: Some-City) Some-City
+Enter organization name: (Default: VyOS) VyOS
+Enter common name: (Default: vyos.io) VyOS Intermediary Server CA
+Enter how many days certificate will be valid: (Default: 1825) 1095
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N] n
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+
+
+[edit]
+vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_client_ca
+Do you already have a certificate request? [y/N] n
+Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa
+Enter private key bits: (Default: 2048) 2048
+Enter country code: (Default: GB) GB
+Enter state: (Default: Some-State) Some-State
+Enter locality: (Default: Some-City) Some-City
+Enter organization name: (Default: VyOS) VyOS
+Enter common name: (Default: vyos.io) VyOS Intermediary Client CA
+Enter how many days certificate will be valid: (Default: 1825) 1095
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N] n
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+```
+Lastly, we can create the leaf certificates that devices and users will utilise.
+```none
+[edit]
+vyos@vyos# run generate pki certificate sign vyos_server_ca install vyos_cert
+Do you already have a certificate request? [y/N] n
+Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa
+Enter private key bits: (Default: 2048) 2048
+Enter country code: (Default: GB) GB
+Enter state: (Default: Some-State) Some-State
+Enter locality: (Default: Some-City) Some-City
+Enter organization name: (Default: VyOS) VyOS
+Enter common name: (Default: vyos.io) vyos.net
+Do you want to configure Subject Alternative Names? [y/N] y
+Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net
+Enter Subject Alternative Names: dns:vyos.net,dns:www.vyos.net
+Enter how many days certificate will be valid: (Default: 365) 365
+Enter certificate type: (client, server) (Default: server) server
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N] n
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+
+
+[edit]
+vyos@vyos# run generate pki certificate sign vyos_client_ca install vyos_example_user
+Do you already have a certificate request? [y/N] n
+Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa
+Enter private key bits: (Default: 2048) 2048
+Enter country code: (Default: GB) GB
+Enter state: (Default: Some-State) Some-State
+Enter locality: (Default: Some-City) Some-City
+Enter organization name: (Default: VyOS) VyOS
+Enter common name: (Default: vyos.io) Example User
+Do you want to configure Subject Alternative Names? [y/N] y
+Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net,rfc822:user@vyos.net
+Enter Subject Alternative Names: rfc822:example.user@vyos.net
+Enter how many days certificate will be valid: (Default: 365) 365
+Enter certificate type: (client, server) (Default: server) client
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N] n
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+```
diff --git a/docs/configuration/policy/md-examples.md b/docs/configuration/policy/md-examples.md
new file mode 100644
index 00000000..992aa82c
--- /dev/null
+++ b/docs/configuration/policy/md-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/md-index.md b/docs/configuration/policy/md-index.md
new file mode 100644
index 00000000..29c9ca87
--- /dev/null
+++ b/docs/configuration/policy/md-index.md
@@ -0,0 +1,47 @@
+---
+lastproofread: '2021-07-12'
+---
+
+```{include} /_include/need_improvement.txt
+```
+
+# Policy
+Policies are used for filtering and traffic management. With policies, network
+administrators could filter and treat traffic
+according to their needs.
+
+There could be a wide range of routing policies. Some examples are listed
+below:
+- Filter traffic based on source/destination address.
+- Set some metric to routes learned from a particular neighbor.
+- Set some attributes (like AS PATH or Community value) to advertised routes
+  to neighbors.
+- Prefer a specific routing protocol routes over another routing protocol
+  running on the same router.
+
+Policies, in VyOS, are implemented using FRR filtering and route maps. Detailed
+information of FRR could be found in <http://docs.frrouting.org/>
+
+## Policy Sections
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+access-list
+prefix-list
+route
+route-map
+local-route
+as-path-list
+community-list
+extcommunity-list
+large-community-list
+```
+## Examples
+Examples of policies usage:
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+examples
+```
diff --git a/docs/configuration/policy/md-route.md b/docs/configuration/policy/md-route.md
new file mode 100644
index 00000000..bf5e552e
--- /dev/null
+++ b/docs/configuration/policy/md-route.md
@@ -0,0 +1,415 @@
+# Route and Route6 Policy
+
+IPv4 route and IPv6 route policies are defined in this section. These route
+policies can then be associated to interfaces.
+
+## Rule-Sets
+
+A rule-set is a named collection of rules that can be applied to an interface.
+Each rule is numbered, has an action to apply if the rule is matched, and the
+ability to specify the criteria to match. Data packets go through the rules
+from 1 - 999999, at the first match the action of the rule will be executed.
+
+```{cfgcmd} set policy route \<name\> description \<text\>
+```
+```{cfgcmd} set policy route6 \<name\> description \<text\>
+
+Provide a rule-set description.
+```
+
+```{cfgcmd} set policy route \<name\> default-log
+```
+
+```{cfgcmd} set policy route6 \<name\> default-log
+
+Option to log packets hitting default-action.
+```
+
+```{cfgcmd} set policy route \<name\> interface \<interface\>
+```
+
+```{cfgcmd} set policy route6 \<name\> interface \<interface\>
+
+Apply routing policy to interface
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> description \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> description \<text\>
+
+Provide a description for each rule.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> log \<enable|disable\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> log \<enable|disable\>
+
+Option to enable or disable log matching rule.
+```
+### Matching criteria
+There are a lot of matching criteria options available, both for
+`policy route` and `policy route6`. These options are listed
+in this section.
+```{cfgcmd} set policy route \<name\> rule \<n\> connection-mark \<1-2147483647\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> connection-mark \<1-2147483647\>
+
+Set match criteria based on connection mark.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> mark \<match_criteria\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> mark \<match_criteria\>
+
+Match based on the firewall mark (fwmark), where \<match_criteria\> can be:
+ * \<0-2147483647\> a single fwmark
+ * !\<0-2147483647\> everything except a single fwmark
+ * &lt;start-end&gt; a range of marks
+ * !&lt;start-end&gt; everything except the range of marks
+
+:::{note}
+When using the ``set table`` or ``set vrf`` commands the mark
+settings are ignored and overwritten with a table-specific mark that
+is set to 0x7FFFFFFF - the id of the table/VRF.
+:::
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> source address \<match_criteria\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> destination address \<match_criteria\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> source address \<match_criteria\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> destination address \<match_criteria\>
+
+Set match criteria based on source or destination ipv4|ipv6 address, where
+&lt;match_criteria&gt; could be:
+```
+For ipv4:
+: - \<x.x.x.x>: IP address to match.
+  - \<x.x.x.x/x>: Subnet to match.
+  - \<x.x.x.x>-\<x.x.x.x>: IP range to match.
+  - !\<x.x.x.x>: Match everything except the specified address.
+  - !\<x.x.x.x/x>: Match everything except the specified subnet.
+  - !\<x.x.x.x>-\<x.x.x.x>: Match everything except the specified range.
+
+And for ipv6:
+: - \<h:h:h:h:h:h:h:h>: IPv6 address to match.
+  - \<h:h:h:h:h:h:h:h/x>: IPv6 prefix to match.
+  - \<h:h:h:h:h:h:h:h>-\<h:h:h:h:h:h:h:h>: IPv6 range to match.
+  - !\<h:h:h:h:h:h:h:h>: Match everything except the specified address.
+  - !\<h:h:h:h:h:h:h:h/x>: Match everything except the specified prefix.
+  - !\<h:h:h:h:h:h:h:h>-\<h:h:h:h:h:h:h:h>: Match everything except the
+    specified range.
+```{cfgcmd} set policy route \<name\> rule \<n\> source group \<address-group|domain-group|mac-group|network-group|port-group\> \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> destination group \<address-group|domain-group|mac-group|network-group|port-group\> \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> source group \<address-group|domain-group|mac-group|network-group|port-group\> \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> destination group \<address-group|domain-group|mac-group|network-group|port-group\> \<text\>
+
+Set match criteria based on source or destination groups, where &lt;text&gt;
+would be the group name/identifier. Prepend character '!' for inverted
+matching criteria.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> destination port \<match_criteria\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> destination port \<match_criteria\>
+
+Set match criteria based on destination port, where \<match_criteria\> could
+be:
+* &lt;port name&gt;: Named port (any name in /etc/services, e.g., http).
+* \<1-65535\>: Numbered port.
+* &lt;start&gt;-&lt;end&gt;: Numbered port range (e.g., 1001-1005).
+
+Multiple destination ports can be specified as a comma-separated list. The
+whole list can also be "negated" using '!'. For example:
+'!22,telnet,http,123,1001-1005'
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> disable
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> disable
+
+Option to disable rule.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> dscp \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> dscp \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> dscp-exclude \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> dscp-exclude \<text\>
+
+Match based on dscp value criteria. Multiple values from 0 to 63
+and ranges are supported.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> fragment \<match-grag|match-non-frag\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> fragment \<match-grag|match-non-frag\>
+
+Set IP fragment match, where:
+* match-frag: Second and further fragments of fragmented packets.
+* match-non-frag: Head fragments or unfragmented packets.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> icmp \<code | type\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> icmpv6 \<code | type\>
+
+Match based on icmp|icmpv6 code and type.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> icmp type-name \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> icmpv6 type-name \<text\>
+
+Match based on icmp|icmpv6 type-name criteria. Use tab for information
+about what type-name criteria are supported.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> ipsec \<match-ipsec|match-none\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> ipsec \<match-ipsec|match-none\>
+
+Set IPSec inbound match criterias, where:
+* match-ipsec: match inbound IPsec packets.
+* match-none: match inbound non-IPsec packets.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> limit burst \<0-4294967295\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> limit burst \<0-4294967295\>
+
+Set maximum number of packets to alow in excess of rate.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> limit rate \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> limit rate \<text\>
+
+Set maximum average matching rate. Format for rate: integer/time_unit, where
+time_unit could be any one of second, minute, hour or day.For example
+1/second implies rule to be matched at an average of once per second.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> protocol \<text | 0-255 | tcp_udp | all \>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> protocol \<text | 0-255 | tcp_udp | all \>
+
+Match a protocol criteria. A protocol number or a name which is defined in:
+``/etc/protocols``. Special names are ``all`` for all protocols and
+``tcp_udp`` for tcp and udp based packets. The ``!`` negates the selected
+protocol.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> packet-length \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> packet-length \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> packet-length-exclude \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> packet-length-exclude \<text\>
+
+Match based on packet length criteria. Multiple values from 1 to 65535
+and ranges are supported.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> packet-type \[broadcast | host | multicast | other\]
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> packet-type \[broadcast | host | multicast | other\]
+
+Match based on packet type criteria.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> recent count \<1-255\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> recent count \<1-255\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> recent time \<1-4294967295\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> recent time \<1-4294967295\>
+
+Set parameters for matching recently seen sources. This match could be used
+by seeting count (source address seen more than <1-255> times) and/or time
+(source address seen in the last <0-4294967295> seconds).
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> state \<established | invalid | new | related\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> state \<established | invalid | new | related\>
+
+Set match criteria based on session state.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> tcp flags \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> tcp flags \<text\>
+
+Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK
+FIN RST URG PSH ALL. When specifying more than one flag, flags should be
+comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match
+packets with the SYN flag set, and the ACK, FIN and RST flags unset.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time monthdays \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time monthdays \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time startdate \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time startdate \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time starttime \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time starttime \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time stopdate \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time stopdate \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time stoptime \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time stoptime \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time weekdays \<text\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time weekdays \<text\>
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> time utc
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> time utc
+
+Time to match the defined rule.
+```
+
+```{cfgcmd} set policy route rule \<n\> ttl \<eq | gt | lt\> \<0-255\>
+
+Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for
+'greater than', and 'lt' stands for 'less than'.
+```
+
+```{cfgcmd} set policy route6 rule \<n\> hop-limit \<eq | gt | lt\> \<0-255\>
+
+Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for
+'greater than', and 'lt' stands for 'less than'.
+```
+### Actions
+When mathcing all patterns defined in a rule, then different actions can
+be made. This includes droping the packet, modifying certain data, or
+setting a different routing table.
+```{cfgcmd} set policy route \<name\> rule \<n\> action drop
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> action drop
+
+Set rule action to drop.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set connection-mark \<1-2147483647\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set connection-mark \<1-2147483647\>
+
+Set a specific connection mark.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set dscp \<0-63\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set dscp \<0-63\>
+
+Set packet modifications: Packet Differentiated Services Codepoint (DSCP)
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set mark \<1-2147483647\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set mark \<1-2147483647\>
+
+Set a specific packet mark.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set table \<main | 1-200\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set table \<main | 1-200\>
+
+Set the routing table to forward packet with.
+
+:::{note}
+When using the ``set table`` or ``set vrf`` commands matching
+against the mark is not possible, because it gets overwritten with a
+table-specific mark that is 0x7FFFFFFF - the id of the table/VRF.
+:::
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set tcp-mss \<500-1460\>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set tcp-mss \<500-1460\>
+
+Set packet modifications: Explicitly set TCP Maximum segment size value.
+```
+
+```{cfgcmd} set policy route \<name\> rule \<n\> set vrf \<default | text \>
+```
+
+```{cfgcmd} set policy route6 \<name\> rule \<n\> set vrf \<default | text \>
+
+Set the VRF to forward packet with.
+
+:::{note}
+When using the ``set table`` or ``set vrf`` commands matching
+against the mark is not possible, because it gets overwritten with a
+table-specific mark that is 0x7FFFFFFF - the id of the table/VRF.
+:::
+```
\ No newline at end of file
diff --git a/docs/configuration/protocols/md-index.md b/docs/configuration/protocols/md-index.md
new file mode 100644
index 00000000..5f190ce1
--- /dev/null
+++ b/docs/configuration/protocols/md-index.md
@@ -0,0 +1,25 @@
+# Protocols
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+arp
+babel
+bfd
+bgp
+failover
+igmp-proxy
+isis
+mpls
+multicast
+segment-routing
+traffic-engineering
+openfabric
+ospf
+pim
+pim6
+rip
+rpki
+static
+```
diff --git a/docs/configuration/service/md-index.md b/docs/configuration/service/md-index.md
new file mode 100644
index 00000000..4018c5be
--- /dev/null
+++ b/docs/configuration/service/md-index.md
@@ -0,0 +1,29 @@
+# Service
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+broadcast-relay
+config-sync
+conntrack-sync
+console-server
+dhcp-relay
+dhcp-server
+dns
+eventhandler
+https
+ipoe-server
+lldp
+mdns
+monitoring
+ntp
+pppoe-server
+router-advert
+salt-minion
+snmp
+ssh
+tftp-server
+webproxy
+suricata
+```
diff --git a/docs/configuration/service/md-snmp.md b/docs/configuration/service/md-snmp.md
new file mode 100644
index 00000000..6a5a66e5
--- /dev/null
+++ b/docs/configuration/service/md-snmp.md
@@ -0,0 +1,255 @@
+(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/system/md-index.md b/docs/configuration/system/md-index.md
new file mode 100644
index 00000000..e0b8a5a1
--- /dev/null
+++ b/docs/configuration/system/md-index.md
@@ -0,0 +1,34 @@
+# System
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+acceleration
+conntrack
+console
+flow-accounting
+frr
+host-name
+ip
+ipv6
+lcd
+login
+name-server
+option
+proxy
+sflow
+syslog
+sysctl
+task-scheduler
+time-zone
+updates
+watchdog
+```
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+default-route
+```
diff --git a/docs/configuration/system/md-sysctl.md b/docs/configuration/system/md-sysctl.md
new file mode 100644
index 00000000..90434fb2
--- /dev/null
+++ b/docs/configuration/system/md-sysctl.md
@@ -0,0 +1,16 @@
+(sysctl)=
+
+# Sysctl
+
+:::{note}
+This page is a stub and needs expansion. Contributions
+welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation).
+:::
+
+This chapter describes how to configure kernel parameters at runtime.
+
+`sysctl` is used to modify kernel parameters at runtime. The parameters
+available are those listed under /proc/sys/.
+
+```{cfgcmd} set system sysctl parameter \<parameter\> value \<value\>
+```
\ No newline at end of file
diff --git a/docs/configuration/vpn/ipsec/md-index.md b/docs/configuration/vpn/ipsec/md-index.md
new file mode 100644
index 00000000..cc40b6f8
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/md-index.md
@@ -0,0 +1,11 @@
+# IPsec
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+ipsec_general
+site2site_ipsec
+remoteaccess_ipsec
+troubleshooting_ipsec
+```
diff --git a/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md b/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md
new file mode 100644
index 00000000..de553aec
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md
@@ -0,0 +1,181 @@
+(remoteaccess-ipsec)=
+
+# IPSec IKEv2 Remote Access VPN
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+Internet Key Exchange version 2 (IKEv2) is a tunneling protocol, based on IPsec,
+that establishes a secure VPN communication between VPN devices, and defines
+negotiation and authentication processes for IPsec security associations (SAs).
+It is often known as IKEv2/IPSec or IPSec IKEv2 remote-access — or road-warriors
+as others call it.
+
+Key exchange and payload encryption is done using IKE and ESP proposals as known
+from IKEv1 but the connections are faster to establish, more reliable, and also
+support roaming from IP to IP (called MOBIKE which makes sure your connection
+does not drop when changing networks from e.g. WIFI to LTE and back).
+Authentication can be achieved with X.509 certificates.
+
+## Setting up certificates:
+First of all, we need to create a CA root certificate and server certificate
+on the server side.
+
+```none
+vyos@vpn.vyos.net# run generate pki ca install ca_root
+Enter private key type: [rsa, dsa, ec] (Default: rsa)
+Enter private key bits: (Default: 2048)
+Enter country code: (Default: GB)
+Enter state: (Default: Some-State)
+Enter locality: (Default: Some-City)
+Enter organization name: (Default: VyOS)
+Enter common name: (Default: vyos.io)
+Enter how many days certificate will be valid: (Default: 1825)
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N] N
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+[edit]
+
+
+vyos@vpn.vyos.net# comp
+[pki ca]
++ ca_root {
++     certificate "MIIDnTCCAoWgAwI…."
++     private {
++         key "MIIEvAIBADANBgkqhkiG9….”
+
+vyos@vpn.vyos.net# run generate pki certificate sign ca_root install server_cert
+Do you already have a certificate request? [y/N] N
+Enter private key type: [rsa, dsa, ec] (Default: rsa)
+Enter private key bits: (Default: 2048)
+Enter country code: (Default: GB)
+Enter state: (Default: Some-State)
+Enter locality: (Default: Some-City)
+Enter organization name: (Default: VyOS)
+Enter common name: (Default: vyos.io) vpn.vyos.net
+Do you want to configure Subject Alternative Names? [y/N] N
+Enter how many days certificate will be valid: (Default: 365)
+Enter certificate type: (client, server) (Default: server)
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N] N
+2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply.
+
+vyos@vpn.vyos.net# comp
+[pki certificate]
++ server_cert {
++     certificate "MIIDuzCCAqOgAwIBAgIUaSrCPWx………"
++     private {
++         key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK….."
++     }
++ }
+```
+
+Once the command is completed, it will add the certificate to the configuration
+session, to the pki subtree. You can then review the proposed changes and
+commit them.
+
+## Setting up IPSec:
+After the PKI certs are all set up we can start configuring our IPSec/IKE
+proposals used for key-exchange end data encryption. The used encryption ciphers
+and integrity algorithms vary from operating system to operating system. The
+ones used in this example are validated to work on Windows 10.
+
+```none
+set vpn ipsec esp-group ESP-RW lifetime '3600'
+set vpn ipsec esp-group ESP-RW pfs 'disable'
+set vpn ipsec esp-group ESP-RW proposal 10 encryption 'aes128gcm128'
+set vpn ipsec esp-group ESP-RW proposal 10 hash 'sha256'
+
+set vpn ipsec ike-group IKE-RW key-exchange 'ikev2'
+set vpn ipsec ike-group IKE-RW lifetime '7200'
+set vpn ipsec ike-group IKE-RW proposal 10 dh-group '14'
+set vpn ipsec ike-group IKE-RW proposal 10 encryption 'aes128gcm128'
+set vpn ipsec ike-group IKE-RW proposal 10 hash 'sha256'
+```
+
+Every connection/remote-access pool we configure also needs a pool where we
+can draw our client IP addresses from. We provide one IPv4 and IPv6 pool.
+Authorized clients will receive an IPv4 address from the configured IPv4 prefix
+and an IPv6 address from the IPv6 prefix. We can also send some DNS nameservers
+down to our clients used on their connection.
+
+```none
+set vpn ipsec remote-access pool ra-rw-ipv4 name-server '192.0.2.1'
+set vpn ipsec remote-access pool ra-rw-ipv4 prefix '192.0.2.128/25'
+
+set vpn ipsec remote-access pool ra-rw-ipv6 name-server '2001:db8:1000::1'
+set vpn ipsec remote-access pool ra-rw-ipv6 prefix '2001:db8:2000::/64'
+```
+
+## Setting up tunnel:
+
+```none
+set vpn ipsec remote-access connection rw authentication local-id '192.0.2.1'
+set vpn ipsec remote-access connection rw authentication server-mode 'x509'
+set vpn ipsec remote-access connection rw authentication x509 ca-certificate 'ca_root'
+set vpn ipsec remote-access connection rw authentication x509 certificate 'server_cert'
+set vpn ipsec remote-access connection rw esp-group 'ESP-RW'
+set vpn ipsec remote-access connection rw ike-group 'IKE-RW'
+set vpn ipsec remote-access connection rw local-address '192.0.2.1'
+set vpn ipsec remote-access connection rw pool 'ra-rw-ipv4'
+set vpn ipsec remote-access connection rw pool 'ra-rw-ipv6'
+```
+
+VyOS also supports two different modes of authentication, local and RADIUS.
+To create a new local user named "vyos" with a password of "vyos" use the
+following commands.
+
+```none
+set vpn ipsec remote-access connection rw authentication client-mode 'eap-mschapv2'
+set vpn ipsec remote-access connection rw authentication local-users username vyos password 'vyos'
+```
+
+Some client operating systems like to see the servers certificate. The following
+option causes the server to voluntarily send its certificate, even if it wasn't
+requested.
+
+```none
+set vpn ipsec remote-access connection rw authentication always-send-cert
+```
+
+## Client Configuration
+Most operating systems include native client support for IPsec IKEv2 VPN
+connections, and others typically have an app or add-on package which adds the
+capability.
+This section covers IPsec IKEv2 client configuration for Windows 10.
+
+VyOS provides a command to generate a connection profile used by Windows clients
+that will connect to the "rw" connection on our VyOS server.
+
+:::{note}
+Windows expects the server name to be also used in the server's
+certificate common name, so it's best to use this DNS name for your VPN
+connection.
+:::
+
+```none
+vyos@vpn.vyos.net:~$ generate ipsec profile windows-remote-access rw remote vpn.vyos.net
+
+
+==== <snip> ====
+Add-VpnConnection -Name "VyOS IKEv2 VPN" -ServerAddress "vpn.vyos.net" -TunnelType "Ikev2"
+
+Set-VpnConnectionIPsecConfiguration -ConnectionName "VyOS IKEv2 VPN" -AuthenticationTransformConstants GCMAES128 -CipherTransformConstants
+GCMAES128 -EncryptionMethod GCMAES128 -IntegrityCheckMethod SHA256128 -PfsGroup None -DHGroup "Group14" -PassThru -Force
+==== </snip> ====
+```
+
+Add the commands from Snippet in the Windows side via PowerShell.
+Also import the root CA cert to the Windows “Trusted Root Certification
+Authorities” and establish the connection.
+
+## Verification:
+
+```none
+vyos@vpn.vyos.net:~$ show vpn ipsec remote-access summary
+  Connection ID  Username    Protocol    State    Uptime    Tunnel IP    Remote Host    Remote ID    IKE Proposal                                IPSec Proposal
+---------------  ----------  ----------  -------  --------  -----------  -------------  -----------  ------------------------------------------  ------------------
+              5  vyos        IKEv2       UP       37s       192.0.2.129  10.0.0.2       10.0.0.2     AES_GCM_16-128/PRF_HMAC_SHA2_256/MODP_2048  ESP:AES_GCM_16-128
+```
diff --git a/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md b/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md
new file mode 100644
index 00000000..2dfd3fec
--- /dev/null
+++ b/docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md
@@ -0,0 +1,302 @@
+(troubleshooting-ipsec)=
+
+# Troubleshooting Site-to-Site VPN IPsec
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+## Introduction
+This document describes the methodology to monitor and troubleshoot
+Site-to-Site VPN IPsec.
+
+Steps for troubleshooting problems with Site-to-Site VPN IPsec:
+: 1. Ping the remote site through the tunnel using the source and
+     destination IPs included in the policy.
+  2. Check connectivity between the routers using the ping command
+     (if ICMP traffic is allowed).
+  3. Check the IKE SAs' statuses.
+  4. Check the IPsec SAs' statuses.
+  5. Check logs to view debug messages.
+
+## Checking IKE SA Status
+The next command shows IKE SAs' statuses.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+192.168.1.2 192.168.1.2                 192.168.0.1 192.168.0.1
+
+    State  IKEVer  Encrypt      Hash          D-H Group      NAT-T  A-Time  L-Time
+    -----  ------  -------      ----          ---------      -----  ------  ------
+    up     IKEv2   AES_CBC_128  HMAC_SHA1_96  MODP_2048      no     162     27023
+```
+
+This command shows the next information:
+: - IKE SA status.
+  - Selected IKE version.
+  - Selected Encryption, Hash and Diffie-Hellman Group.
+  - NAT-T.
+  - ID and IP of both peers.
+  - A-Time: established time, L-Time: time for next rekeying.
+
+## IPsec SA (CHILD SA) Status
+The next commands show IPsec SAs' statuses.
+
+```none
+vyos@vyos:~$ show vpn ipsec sa
+Connection     State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+-------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------------------------------
+PEER-tunnel-1  up       16m30s    168B/168B       2/2               192.168.1.2       192.168.1.2  AES_CBC_128/HMAC_SHA1_96/MODP_2048
+```
+
+```none
+vyos@vyos:~$ show vpn ipsec sa detail
+PEER: #1, ESTABLISHED, IKEv2, 101275ac719d5a1b_i* 68ea4ec3bed3bf0c_r
+  local  '192.168.0.1' @ 192.168.0.1[4500]
+  remote '192.168.1.2' @ 192.168.1.2[4500]
+  AES_CBC-128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+  established 4054s ago, rekeying in 23131s
+  PEER-tunnel-1: #2, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA1_96/MODP_2048
+    installed 1065s ago, rekeying in 1998s, expires in 2535s
+    in  c5821882,    168 bytes,     2 packets,    81s ago
+    out c433406a,    168 bytes,     2 packets,    81s ago
+    local  10.0.0.0/24
+    remote 10.0.1.0/24
+```
+
+These commands show the next information:
+: - IPsec SA status.
+  - Uptime and time for the next rekeing.
+  - Amount of transferred data.
+  - Remote and local ID and IP.
+  - Selected Encryption, Hash and Diffie-Hellman Group.
+  - Mode (tunnel or transport).
+  - Remote and local prefixes which are use for policy.
+
+There is a possibility to view the summarized information of SAs' status
+
+```none
+vyos@vyos:~$ show vpn ipsec connections
+Connection     State    Type    Remote address    Local TS     Remote TS    Local id     Remote id    Proposal
+-------------  -------  ------  ----------------  -----------  -----------  -----------  -----------  ----------------------------------
+PEER           up       IKEv2   192.168.1.2       -            -            192.168.0.1  192.168.1.2  AES_CBC/128/HMAC_SHA1_96/MODP_2048
+PEER-tunnel-1  up       IPsec   192.168.1.2       10.0.0.0/24  10.0.1.0/24  192.168.0.1  192.168.1.2  AES_CBC/128/HMAC_SHA1_96/MODP_2048
+```
+
+## Viewing Logs for Debugging
+If IKE SAs or IPsec SAs are down, need to debug IPsec connectivity
+using logs `show log ipsec`
+
+The next example of the successful IPsec connection initialization.
+
+```none
+vyos@vyos:~$ show log ipsec
+Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 20 14:29:47 charon[2428]: 02[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 20 14:29:47 charon-systemd[2428]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1}
+Jun 20 14:29:47 charon-systemd[2428]: establishing CHILD_SA PEER-tunnel-1{1}
+Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 20 14:29:47 charon-systemd[2428]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 20 14:29:47 charon-systemd[2428]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 20 14:29:47 charon[2428]: 13[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes)
+Jun 20 14:29:47 charon[2428]: 13[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ]
+Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes)
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful
+Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ]
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> peer supports MOBIKE
+Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.1.2' with pre-shared key successful
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 20 14:29:47 charon-systemd[2428]: peer supports MOBIKE
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> scheduling rekeying in 27703s
+Jun 20 14:29:47 charon-systemd[2428]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> maximum IKE_SA lifetime 30583s
+Jun 20 14:29:47 charon-systemd[2428]: scheduling rekeying in 27703s
+Jun 20 14:29:47 charon[2428]: 13[CFG] <PEER|1> selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 20 14:29:47 charon-systemd[2428]: maximum IKE_SA lifetime 30583s
+Jun 20 14:29:47 charon-systemd[2428]: selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24
+Jun 20 14:29:47 charon-systemd[2428]: CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24
+```
+
+## Troubleshooting Examples
+
+### IKE PROPOSAL are Different
+In this situation, IKE SAs can be down or not active.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+```
+
+The problem is in IKE phase (Phase 1). The next step is checking debug logs.
+
+Responder Side:
+
+```none
+Jun 23 07:36:33 charon[2440]: 01[CFG] <1> received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon-systemd[2440]: received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon[2440]: 01[CFG] <1> configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon-systemd[2440]: configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 07:36:33 charon[2440]: 01[IKE] <1> received proposals unacceptable
+Jun 23 07:36:33 charon-systemd[2440]: received proposals unacceptable
+Jun 23 07:36:33 charon[2440]: 01[ENC] <1> generating IKE_SA_INIT response 0 [ N(NO_PROP) ]
+```
+
+Initiator side:
+
+```none
+Jun 23 07:36:32 charon-systemd[2444]: parsed IKE_SA_INIT response 0 [ N(NO_PROP) ]
+Jun 23 07:36:32 charon[2444]: 14[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify error
+Jun 23 07:36:32 charon-systemd[2444]: received NO_PROPOSAL_CHOSEN notify error
+```
+
+The notification **NO_PROPOSAL_CHOSEN** means that the proposal mismatch.
+On the Responder side there is concrete information where is mismatch.
+Encryption **AES_CBC_128** is configured in IKE policy on the responder
+but **AES_CBC_256** is configured on the initiator side.
+
+### PSK Secret Mismatch
+In this situation, IKE SAs can be down or not active.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+```
+
+The problem is in IKE phase (Phase 1). The next step is checking debug logs.
+
+Responder:
+
+```none
+Jun 23 08:07:26 charon-systemd[2440]: tried 1 shared key for '192.168.1.2' - '192.168.0.1', but MAC mismatched
+Jun 23 08:07:26 charon[2440]: 13[ENC] <PEER|3> generating IKE_AUTH response 1 [ N(AUTH_FAILED) ]
+```
+
+Initiator side:
+
+```none
+Jun 23 08:07:24 charon[2436]: 12[ENC] <PEER|1> parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ]
+Jun 23 08:07:24 charon-systemd[2436]: parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ]
+Jun 23 08:07:24 charon[2436]: 12[IKE] <PEER|1> received AUTHENTICATION_FAILED notify error
+Jun 23 08:07:24 charon-systemd[2436]: received AUTHENTICATION_FAILED notify error
+```
+
+The notification **AUTHENTICATION_FAILED** means that the authentication
+is failed. There is a reason to check PSK on both side.
+
+### ESP Proposal Mismatch
+The output of **show** commands shows us that IKE SA is established but
+IPSec SA is not.
+
+```none
+vyos@vyos:~$ show vpn ike sa
+Peer ID / IP                            Local ID / IP
+------------                            -------------
+192.168.1.2 192.168.1.2                 192.168.0.1 192.168.0.1
+
+    State  IKEVer  Encrypt      Hash          D-H Group      NAT-T  A-Time  L-Time
+    -----  ------  -------      ----          ---------      -----  ------  ------
+    up     IKEv2   AES_CBC_128  HMAC_SHA1_96  MODP_2048      no     158     26817
+```
+
+```none
+vyos@vyos:~$ show vpn ipsec sa
+Connection    State    Uptime    Bytes In/Out    Packets In/Out    Remote address    Remote ID    Proposal
+------------  -------  --------  --------------  ----------------  ----------------  -----------  ----------
+```
+
+The next step is checking debug logs.
+
+Initiator side:
+
+```none
+Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes)
+Jun 23 08:16:10 charon[3789]: 13[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ]
+Jun 23 08:16:10 charon-systemd[3789]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048
+Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.0.1' (myself) with pre-shared key
+Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1}
+Jun 23 08:16:10 charon-systemd[3789]: establishing CHILD_SA PEER-tunnel-1{1}
+Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 23 08:16:10 charon-systemd[3789]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ]
+Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 23 08:16:10 charon-systemd[3789]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes)
+Jun 23 08:16:10 charon[3789]: 09[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes)
+Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes)
+Jun 23 08:16:10 charon[3789]: 09[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ]
+Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ]
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful
+Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.1.2' with pre-shared key successful
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> peer supports MOBIKE
+Jun 23 08:16:10 charon-systemd[3789]: peer supports MOBIKE
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 23 08:16:10 charon-systemd[3789]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2]
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> scheduling rekeying in 26975s
+Jun 23 08:16:10 charon-systemd[3789]: scheduling rekeying in 26975s
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> maximum IKE_SA lifetime 29855s
+Jun 23 08:16:10 charon-systemd[3789]: maximum IKE_SA lifetime 29855s
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built
+Jun 23 08:16:10 charon-systemd[3789]: received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built
+Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 08:16:10 charon-systemd[3789]: failed to establish CHILD_SA, keeping IKE_SA
+```
+
+There are messages: **NO_PROPOSAL_CHOSEN** and
+**failed to establish CHILD_SA** which refers that the problem is in
+the IPsec(ESP) proposal mismatch.
+
+The reason of this problem is showed on the responder side.
+
+```none
+Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 23 08:16:12 charon-systemd[2440]: received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ
+Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ
+Jun 23 08:16:12 charon-systemd[2440]: configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ
+Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> no acceptable proposal found
+Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found
+Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> failed to establish CHILD_SA, keeping IKE_SA
+```
+
+Encryption **AES_CBC_128** is configured in IKE policy on the responder but **AES_CBC_256**
+is configured on the initiator side.
+
+### Prefixes in Policies Mismatch
+As in previous situation, IKE SA is in up state but IPsec SA is not up.
+According to logs we can see **TS_UNACCEPTABLE** notification. It means
+that prefixes (traffic selectors) mismatch on both sides
+
+Initiator:
+
+```none
+Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> received TS_UNACCEPTABLE notify, no CHILD_SA built
+Jun 23 14:13:17 charon-systemd[4996]: maximum IKE_SA lifetime 29437s
+Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 14:13:17 charon-systemd[4996]: received TS_UNACCEPTABLE notify, no CHILD_SA built
+Jun 23 14:13:17 charon-systemd[4996]: failed to establish CHILD_SA, keeping IKE_SA
+```
+
+The reason of this problem is showed on the responder side.
+
+```none
+Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable
+Jun 23 14:13:19 charon-systemd[2440]: traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable
+Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 14:13:19 charon-systemd[2440]: failed to establish CHILD_SA, keeping IKE_SA
+Jun 23 14:13:19 charon[2440]: 01[ENC] <PEER|7> generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ]
+Jun 23 14:13:19 charon-systemd[2440]: generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ]
+```
+
+Traffic selectors **10.0.2.0/24 === 10.0.0.0/24** are unacceptable on the
+responder side.
diff --git a/docs/configuration/vpn/md-index.md b/docs/configuration/vpn/md-index.md
new file mode 100644
index 00000000..9b06e5df
--- /dev/null
+++ b/docs/configuration/vpn/md-index.md
@@ -0,0 +1,14 @@
+# VPN
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+ipsec/index
+l2tp
+openconnect
+pptp
+rsa-keys
+sstp
+dmvpn
+```
diff --git a/docs/configuration/vpn/md-rsa-keys.md b/docs/configuration/vpn/md-rsa-keys.md
new file mode 100644
index 00000000..b224b514
--- /dev/null
+++ b/docs/configuration/vpn/md-rsa-keys.md
@@ -0,0 +1,114 @@
+# RSA-Keys
+
+```{todo}
+Convert raw command blocks in this file to cfgcmd/opcmd
+directives for command coverage tracking.
+```
+
+RSA can be used for services such as key exchanges and for encryption purposes.
+To make IPSec work with dynamic address on one/both sides, we will have to use
+RSA keys for authentication. They are very fast and easy to setup.
+
+First, on both routers run the operational command "generate pki key-pair
+install \<key-pair nam>>". You may choose different length than 2048 of course.
+
+```none
+vyos@left# run generate pki key-pair install ipsec-LEFT
+Enter private key type: [rsa, dsa, ec] (Default: rsa)
+Enter private key bits: (Default: 2048)
+Note: If you plan to use the generated key on this router, do not encrypt the private key.
+Do you want to encrypt the private key with a passphrase? [y/N] N
+Configure mode commands to install key pair:
+Do you want to install the public key? [Y/n] Y
+set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'
+Do you want to install the private key? [Y/n] Y
+set pki key-pair ipsec-LEFT private key 'MIIEvgIBADAN...'
+[edit]
+```
+
+Configuration commands will display.
+Note the command with the public key
+(set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...').
+Then do the same on the opposite router:
+
+```none
+vyos@left# run generate pki key-pair install ipsec-RIGHT
+```
+
+Note the command with the public key
+(set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...').
+
+The noted public keys should be entered on the opposite routers.
+
+On the LEFT:
+
+```none
+set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...'
+```
+
+On the RIGHT:
+
+```none
+set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'
+```
+
+Now you are ready to setup IPsec. The key points:
+1. Since both routers do not know their effective public addresses,
+   we set the local-address of the peer to "any".
+2. On the initiator, we set the peer address to its public address,
+   but on the responder we only set the id.
+3. On the initiator, we need to set the remote-id option so that it
+   can identify IKE traffic from the responder correctly.
+4. On the responder, we need to set the local id so that initiator
+   can know who's talking to it for the point #3 to work.
+
+On the LEFT (static address):
+
+```none
+set vpn ipsec interface eth0
+
+set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128
+set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1
+
+set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2
+set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128
+set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1
+
+set vpn ipsec site-to-site peer @RIGHT authentication id LEFT
+set vpn ipsec site-to-site peer @RIGHT authentication mode rsa
+set vpn ipsec site-to-site peer @RIGHT authentication rsa local-key ipsec-LEFT
+set vpn ipsec site-to-site peer @RIGHT authentication rsa remote-key ipsec-RIGHT
+set vpn ipsec site-to-site peer @RIGHT authentication remote-id RIGHT
+set vpn ipsec site-to-site peer @RIGHT default-esp-group MyESPGroup
+set vpn ipsec site-to-site peer @RIGHT ike-group MyIKEGroup
+set vpn ipsec site-to-site peer @RIGHT local-address 192.0.2.10
+set vpn ipsec site-to-site peer @RIGHT connection-type none
+set vpn ipsec site-to-site peer @RIGHT tunnel 1 local prefix 192.168.99.1/32  # Additional loopback address on the local
+set vpn ipsec site-to-site peer @RIGHT tunnel 1 remote prefix 192.168.99.2/32 # Additional loopback address on the remote
+```
+
+On the RIGHT (dynamic address):
+
+```none
+set vpn ipsec interface eth0
+
+set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128
+set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1
+
+set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2
+set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128
+set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1
+
+set vpn ipsec site-to-site peer 192.0.2.10 authentication id RIGHT
+set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa
+set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa local-key ipsec-RIGHT
+set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa remote-key ipsec-LEFT
+set vpn ipsec site-to-site peer 192.0.2.10 authentication remote-id LEFT
+set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate
+set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup
+set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup
+set vpn ipsec site-to-site peer 192.0.2.10 local-address any
+set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32  # Additional loopback address on the local
+set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote
+```
+