Merge remote-tracking branch 'origin/current' into feat/docs-llms-txt-current

# Conflicts:
#	docs/conf.py

46 files changed, 6467 insertions, 0 deletions

diff --git a/docs/configuration/service/broadcast-relay.md b/docs/configuration/service/broadcast-relay.md
new file mode 100644
index 00000000..4202ad6b
--- /dev/null
+++ b/docs/configuration/service/broadcast-relay.md
@@ -0,0 +1,70 @@
+(udp-broadcast-relay)=
+
+# UDP Broadcast Relay
+
+Certain vendors use broadcasts to identify their equipment within one ethernet
+segment. Unfortunately if you split your network with multiple VLANs you loose
+the ability of identifying your equipment.
+
+This is where "UDP broadcast relay" comes into play! It will forward received
+broadcasts to other configured networks.
+
+Every UDP port which will be forward requires one unique ID. Currently we
+support 99 IDs!
+
+## Configuration
+
+```{cfgcmd} set service broadcast-relay id \<n\> description \<description\>
+
+A description can be added for each and every unique relay ID. This is
+useful to distinguish between multiple different ports/applications.
+```
+
+```{cfgcmd} set service broadcast-relay id \<n\> interface \<interface\>
+
+The interface used to receive and relay individual broadcast packets. If you
+want to receive/relay packets on both `eth1` and `eth2` both interfaces need
+to be added.
+```
+
+```{cfgcmd} set service broadcast-relay id \<n\> address \<ipv4-address\>
+
+Set the source IP of forwarded packets, otherwise original senders address
+is used.
+```
+
+```{cfgcmd} set service broadcast-relay id \<n\> port \<port\>
+
+The UDP port number used by your application. It is mandatory for this kind
+of operation.
+```
+
+```{cfgcmd} set service broadcast-relay id \<n\> disable
+
+Each broadcast relay instance can be individually disabled without deleting
+the configured node by using the following command:
+```
+
+```{cfgcmd} set service broadcast-relay disable
+
+In addition you can also disable the whole service without the need to remove
+it from the current configuration.
+```
+
+:::{note}
+You can run the UDP broadcast relay service on multiple routers
+connected to a subnet. There is **NO** UDP broadcast relay packet storm!
+:::
+
+## Example
+
+To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4`
+or `eth5` to all other interfaces in this configuration.
+
+```none
+set service broadcast-relay id 1 description 'SONOS'
+set service broadcast-relay id 1 interface 'eth3'
+set service broadcast-relay id 1 interface 'eth4'
+set service broadcast-relay id 1 interface 'eth5'
+set service broadcast-relay id 1 port '1900'
+```
diff --git a/docs/configuration/service/config-sync.md b/docs/configuration/service/config-sync.md
new file mode 100644
index 00000000..a575f947
--- /dev/null
+++ b/docs/configuration/service/config-sync.md
@@ -0,0 +1,164 @@
+(config-sync)=
+
+# Config Sync
+
+Configuration synchronization (config sync) is a feature of VyOS that
+permits synchronization of the configuration of one VyOS router to
+another in a network.
+
+The main benefit to configuration synchronization is that it eliminates having
+to manually replicate configuration changes made on the primary router to the
+secondary (replica) router.
+
+The writing of the configuration to the secondary router is performed through
+the VyOS HTTP API. The user can specify which portion(s) of the configuration will
+be synchronized and the mode to use - whether to replace or add.
+
+To prevent issues with divergent configurations between the pair of routers,
+synchronization is strictly unidirectional from primary to replica. Both
+routers should be online and run the same version of VyOS.
+
+## Configuration
+
+```{cfgcmd} set service config-sync secondary \<address|key|timeout|port\>
+
+Specify the address, API key, timeout and port of the secondary router.
+You need to enable and configure the HTTP API service on the secondary
+router for config sync to operate.
+```
+
+```{cfgcmd} set service config-sync section \<section\>
+
+Specify the section of the configuration to synchronize. If more than one
+section is to be synchronized, repeat the command to add additional
+sections as required.
+```
+
+```{cfgcmd} set service config-sync mode \<load|set\>
+
+Two options are available for *mode*: either *load* and replace or *set*
+the configuration section.
+```
+
+```none
+Supported options for <section> include:
+    firewall
+    interfaces <interface>
+    nat
+    nat66
+    pki
+    policy
+    protocols <protocol>
+    qos <interface|policy>
+    service <service>
+    system <conntrack| 
+    flow-accounting|option|sflow|static-host-mapping|sysctl|time-zone>
+    vpn
+    vrf
+```
+
+
+## Operational Commands
+
+````{opcmd} show configuration secondary sync [commands] [running | candidate | saved] [\<config-node-path\>]
+
+Display configuration differences between the local node and
+a config-sync secondary node.
+
+This command allows operators to compare configurations across nodes
+participating in configuration synchronization (e.g., primary and
+secondary routers). It helps detect configuration drift and validate
+intended changes before synchronization.
+
+**Parameters:**
+
+```{eval-rst}
+.. list-table::
+   :widths: 30 70
+   :header-rows: 0
+
+   * - ``commands`` (optional)
+     - Show output as a list of configuration commands instead of raw diff.
+   * - ``running|candidate|saved`` (optional, mutually exclusive)
+     - Select which configuration to compare:
+       ``running`` (current active configuration, default),
+       ``candidate`` (uncommitted changes), or
+       ``saved`` (last saved configuration). Only one of these may be
+       specified at a time; if omitted, ``running`` is used.
+```
+
+**Examples:**
+
+:::{code-block} none
+# compare full running configuration with a secondary node
+show configuration secondary sync
+
+# compare only interface configuration
+show configuration secondary sync running interfaces dummy
+
+# compare candidate configuration and display as a list of commands
+show configuration secondary sync commands candidate
+:::
+````
+
+Without a built-in cross-node diff, operators may unintentionally push
+changes that conflict with the remote configuration (e.g., mismatched
+interfaces, firewall policies, or protocol settings).
+
+
+## Example
+
+- Synchronize the time-zone and OSPF configuration from Router A to Router B
+- The address of Router B is 10.0.20.112 and the port used is 8443
+
+Configure the HTTP API service on Router B
+
+```none
+set service https listen-address '10.0.20.112'
+set service https port '8443'
+set service https api keys id KID key 'foo'
+set service https api rest
+```
+
+Configure the config-sync service on Router A
+
+```none
+set service config-sync mode 'load'
+set service config-sync secondary address '10.0.20.112'
+set service config-sync secondary port '8443'
+set service config-sync secondary key 'foo'
+set service config-sync section protocols 'ospf'
+set service config-sync section system 'time-zone'
+```
+
+Make config-sync relevant changes to Router A's configuration
+
+```none
+vyos@vyos-A# set system time-zone 'America/Los_Angeles'
+vyos@vyos-A# commit
+INFO:vyos_config_sync:Config synchronization: Mode=load, 
+Secondary=10.0.20.112
+vyos@vyos-A# save
+
+vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30'
+vyos@vyos-A# commit
+INFO:vyos_config_sync:Config synchronization: Mode=load, 
+Secondary=10.0.20.112
+yos@vyos-A# save
+```
+
+Verify configuration changes have been replicated to Router B
+
+```none
+vyos@vyos-B:~$ show configuration commands | match time-zone
+set system time-zone 'America/Los_Angeles'
+
+vyos@vyos-B:~$ show configuration commands | match ospf
+set protocols ospf area 0 network '10.0.48.0/30'
+```
+
+
+## Known issues
+
+Configuration resynchronization. With the current implementation of *service
+config-sync*, the secondary node must be online.
diff --git a/docs/configuration/service/conntrack-sync.md b/docs/configuration/service/conntrack-sync.md
new file mode 100644
index 00000000..4aad6283
--- /dev/null
+++ b/docs/configuration/service/conntrack-sync.md
@@ -0,0 +1,321 @@
+(conntrack-sync)=
+
+# Conntrack Sync
+
+One of the important features built on top of the Netfilter framework is
+connection tracking. Connection tracking allows the kernel to keep track of all
+logical network connections or sessions, and thereby relate all of the packets
+which may make up that connection. NAT relies on this information to translate
+all related packets in the same way, and iptables can use this information to
+act as a stateful firewall.
+
+The connection state however is completely independent of any upper-level
+state, such as TCP's or SCTP's state. Part of the reason for this is that when
+merely forwarding packets, i.e. no local delivery, the TCP engine may not
+necessarily be invoked at all. Even connectionless-mode transmissions such as
+UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo
+connection state. The heuristic for such protocols is often based upon a preset
+timeout value for inactivity, after whose expiration a Netfilter connection is
+dropped.
+
+Each Netfilter connection is uniquely identified by a (layer-3 protocol, source
+address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4
+key depends on the transport protocol; for TCP/UDP it is the port numbers, for
+tunnels it can be their tunnel ID, but otherwise is just zero, as if it were
+not part of the tuple. To be able to inspect the TCP port in all cases, packets
+will be mandatorily defragmented.
+
+It is possible to use either Multicast or Unicast to sync conntrack traffic.
+Most examples below show Multicast, but unicast can be specified by using the
+"peer" keyword after the specified interface, as in the following example:
+
+{cfgcmd}`set service conntrack-sync interface eth0 peer 192.168.0.250`
+
+## Configuration
+
+```{cfgcmd} set service conntrack-sync accept-protocol
+
+Accept only certain protocols: You may want to replicate the state of flows
+depending on their layer 4 protocol.
+
+Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp.
+```
+
+
+```{cfgcmd} set service conntrack-sync event-listen-queue-size \<size\>
+
+The daemon doubles the size of the netlink event socket buffer size if it
+detects netlink event message dropping. This clause sets the maximum buffer
+size growth that can be reached.
+
+Queue size for listening to local conntrack events in MB.
+```
+
+
+```{cfgcmd} set service conntrack-sync expect-sync \<all|ftp|h323|nfs|sip|sqlnet\>
+
+Protocol for which expect entries need to be synchronized.
+```
+
+
+```{cfgcmd} set service conntrack-sync failover-mechanism vrrp sync-group \<group\>
+
+Failover mechanism to use for conntrack-sync.
+
+Only VRRP is supported. Required option.
+```
+
+
+```{cfgcmd} set service conntrack-sync ignore-address \<x.x.x.x\>
+
+IP addresses or networks for which local conntrack entries will not be synced
+```
+
+
+```{cfgcmd} set service conntrack-sync interface \<name\>
+
+Interface to use for syncing conntrack entries.
+```
+
+
+```{cfgcmd} set service conntrack-sync interface \<name\> port \<port\>
+
+Port number used by connection.
+```
+
+
+```{cfgcmd} set service conntrack-sync listen-address \<ipv4address\>
+
+Local IPv4 addresses for service to listen on.
+```
+
+
+```{cfgcmd} set service conntrack-sync mcast-group \<x.x.x.x\>
+
+Multicast group to use for syncing conntrack entries.
+
+Defaults to 225.0.0.50.
+```
+
+
+```{cfgcmd} set service conntrack-sync interface \<name\> peer \<address\>
+
+Peer to send unicast UDP conntrack sync entries to, if not using Multicast
+configuration from above.
+```
+
+
+```{cfgcmd} set service conntrack-sync sync-queue-size \<size\>
+
+Queue size for syncing conntrack entries in MB.
+```
+
+
+```{cfgcmd} set service conntrack-sync disable-external-cache
+
+This disables the external cache and directly injects the flow-states into the
+in-kernel Connection Tracking System of the backup firewall.
+```
+
+
+```{cfgcmd} set service conntrack-sync purge-timeout \<timeout\>
+
+Timeout (in seconds) for purging synchronized entries on handover events.
+
+On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table
+flush after ``<timeout>`` seconds to purge stale (“zombie”) entries and
+reduce clashes when multiple handovers occur in a short period.
+The default is 60 seconds.
+```
+
+:::{note}
+In VRRP stateful firewall deployments, align VRRP timing with this
+behavior: because synchronized conntrack state is purged after the purge
+timeout, set **VRRP preempt-delay** to ≥ **purge-timeout** so mastership
+can be restored before conntrack state is purged.
+:::
+
+```{cfgcmd} set service conntrack-sync disable-syslog
+
+Disable connection logging via Syslog.
+```
+
+
+```{cfgcmd} set service conntrack-sync startup-resync
+
+Order conntrackd to request a complete conntrack table resync against
+the other node at startup.
+```
+
+## Operation
+
+```{opcmd} show conntrack table ipv4
+
+Make sure conntrack is enabled by running and show connection tracking table.
+
+:::{code-block} none
+vyos@vyos:~$ show conntrack table ipv4
+TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED,
+FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK,
+TW - TIME WAIT, CL - CLOSE, LI - LISTEN
+
+CONN ID    Source                 Destination            Protocol         TIMEOUT
+1015736576 10.35.100.87:58172     172.31.20.12:22        tcp [6] ES       430279
+1006235648 10.35.101.221:57483    172.31.120.21:22       tcp [6] ES       413310
+1006237088 10.100.68.100          172.31.120.21          icmp [1]         29
+1015734848 10.35.100.87:56282     172.31.20.12:22        tcp [6] ES       300
+1015734272 172.31.20.12:60286     239.10.10.14:694       udp [17]         29
+1006239392 10.35.101.221          172.31.120.21          icmp [1]         29
+:::
+:::{note}
+If the table is empty and you have a warning message, it means
+conntrack is not enabled. To enable conntrack, just create a NAT or a firewall
+rule. {cfgcmd}`set firewall state-policy established action accept`
+:::
+```
+
+
+```{opcmd} show conntrack-sync cache external
+
+Show connection syncing external cache entries
+```
+
+
+```{opcmd} show conntrack-sync cache internal
+
+Show connection syncing internal cache entries
+```
+
+
+```{opcmd} show conntrack-sync statistics
+
+Retrieve current statistics of connection tracking subsystem.
+
+:::{code-block} none
+vyos@vyos:~$ show conntrack-sync statistics
+Main Table Statistics:
+
+cache internal:
+current active connections:            19606
+connections created:                 6298470    failed:            0
+connections updated:                 3786793    failed:            0
+connections destroyed:               6278864    failed:            0
+
+cache external:
+current active connections:            15771
+connections created:                 1660193    failed:            0
+connections updated:                   77204    failed:            0
+connections destroyed:               1644422    failed:            0
+
+traffic processed:
+0 Bytes                         0 Pckts
+
+multicast traffic (active device=eth0.5):
+976826240 Bytes sent            212898000 Bytes recv
+8302333 Pckts sent              2009929 Pckts recv
+0 Error send                    0 Error recv
+
+message tracking:
+0 Malformed msgs                  263 Lost msgs
+:::
+```
+```{opcmd} show conntrack-sync status
+
+Retrieve current status of connection tracking subsystem.
+
+:::{code-block} none
+vyos@vyos:~$ show conntrack-sync status
+sync-interface        : eth0.5
+failover-mechanism    : vrrp [sync-group GEFOEKOM]
+last state transition : no transition yet!
+ExpectationSync       : disabled
+:::
+```
+
+## Example
+
+The next example is a simple configuration of conntrack-sync.
+
+:::{figure} /_static/images/service_conntrack_sync-schema.webp
+:alt: Conntrack Sync Example
+:scale: 60 %
+:::
+
+Now configure conntrack-sync service on `router1` **and** `router2`
+
+```none
+set high-availability vrrp group internal virtual-address ... etc ...
+set high-availability vrrp sync-group syncgrp member 'internal'
+set service conntrack-sync accept-protocol 'tcp'
+set service conntrack-sync accept-protocol 'udp'
+set service conntrack-sync accept-protocol 'icmp'
+set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp'
+set service conntrack-sync interface 'eth0'
+set service conntrack-sync mcast-group '225.0.0.50'
+```
+
+On the active router, you should have information in the internal-cache of
+conntrack-sync. The same current active connections number should be shown in
+the external-cache of the standby router
+
+On active router run:
+
+```none
+$ show conntrack-sync statistics
+
+Main Table Statistics:
+
+cache internal:
+current active connections:               10
+connections created:                    8517    failed:            0
+connections updated:                     127    failed:            0
+connections destroyed:                  8507    failed:            0
+
+cache external:
+current active connections:                0
+connections created:                       0    failed:            0
+connections updated:                       0    failed:            0
+connections destroyed:                     0    failed:            0
+
+traffic processed:
+                   0 Bytes                         0 Pckts
+
+multicast traffic (active device=eth0):
+              868780 Bytes sent               224136 Bytes recv
+               20595 Pckts sent                14034 Pckts recv
+                   0 Error send                    0 Error recv
+
+message tracking:
+                   0 Malformed msgs                    0 Lost msgs
+```
+
+On standby router run:
+
+```none
+$ show conntrack-sync statistics
+
+Main Table Statistics:
+
+cache internal:
+current active connections:                0
+connections created:                       0    failed:            0
+connections updated:                       0    failed:            0
+connections destroyed:                     0    failed:            0
+
+cache external:
+current active connections:               10
+connections created:                     888    failed:            0
+connections updated:                     134    failed:            0
+connections destroyed:                   878    failed:            0
+
+traffic processed:
+                   0 Bytes                         0 Pckts
+
+multicast traffic (active device=eth0):
+              234184 Bytes sent               907504 Bytes recv
+               14663 Pckts sent                21495 Pckts recv
+                   0 Error send                    0 Error recv
+
+message tracking:
+                   0 Malformed msgs                    0 Lost msgs
+```
diff --git a/docs/configuration/service/console-server.md b/docs/configuration/service/console-server.md
new file mode 100644
index 00000000..f0556652
--- /dev/null
+++ b/docs/configuration/service/console-server.md
@@ -0,0 +1,139 @@
+(console-server)=
+
+# Console Server
+
+Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an
+Out-of-Band Management device which provides remote access by means of SSH to
+directly attached serial interfaces.
+
+Serial interfaces can be any interface which is directly connected to the CPU
+or chipset (mostly known as a ttyS interface in Linux) or any other USB to
+serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips).
+
+If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or
+NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement.
+
+For USB port information please refor to: {ref}`hardware_usb`.
+
+## Configuration
+
+Between computers, the most common configuration used was "8N1": eight bit
+characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud
+times are used to send a single character, and so dividing the signalling
+bit-rate by ten results in the overall transmission speed in characters per
+second. This is also the default setting if none of those options are defined.
+
+```{cfgcmd} set service console-server device \<device\> data-bits [7 | 8]
+
+Configure either seven or eight data bits. This defaults to eight data
+bits if left unconfigured.
+```
+
+
+```{cfgcmd} set service console-server device \<device\> description \<string\>
+
+A user friendly description identifying the connected peripheral.
+```
+
+
+```{cfgcmd} set service console-server device \<device\> alias \<string\>
+
+A user friendly alias for this connection. Can be used instead of the
+device name when connecting.
+```
+
+
+```{cfgcmd} set service console-server device \<device\> parity [even | odd | none]
+
+Set the parity option for the console. If unset this will default to none.
+```
+
+
+```{cfgcmd} set service console-server device \<device\> stop-bits [1 | 2]
+
+Configure either one or two stop bits. This defaults to one stop bits if
+left unconfigured.
+```
+
+
+```{cfgcmd} set service console-server device \<device\> speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ]
+
+:::{note}
+USB to serial converters will handle most of their work in software
+so you should be carefull with the selected baudrate as some times they
+can't cope with the expected speed.
+:::
+```
+
+### Remote Access
+
+
+Each individual configured console-server device can be directly exposed to
+the outside world. A user can directly connect via SSH to the configured
+port.
+
+```{cfgcmd} set service console-server device \<device\> ssh port \<port\>
+
+Accept SSH connections for the given `<device>` on TCP port `<port>`.
+After successful authentication the user will be directly dropped to
+the connected serial device.
+
+:::{hint}
+Multiple users can connect to the same serial device but only
+one is allowed to write to the console port.
+:::
+```
+
+## Operation
+
+```{opcmd} show console-server ports
+
+Show configured serial ports and their respective interface configuration.
+
+:::{code-block} none
+vyos@vyos:~$ show console-server ports
+usb0b2.4p1.0             on /dev/serial/by-bus/usb0b2.4p1.0@ at   9600n
+:::
+```
+
+
+```{opcmd} show console-server user
+
+Show currently connected users.
+
+:::{code-block} none
+vyos@vyos:~$ show console-server user
+usb0b2.4p1.0               up   vyos@localhost
+:::
+```
+```{opcmd} connect console \<device\>
+
+Locally connect to serial port identified by `<device>`.
+
+:::{code-block} none
+vyos@vyos-r1:~$ connect console usb0b2.4p1.0
+[Enter `^Ec?' for help]
+[-- MOTD -- VyOS Console Server]
+
+vyos-r2 login:
+:::
+
+:::{hint}
+Multiple users can connect to the same serial device but only
+one is allowed to write to the console port.
+:::
+
+:::{hint}
+The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit
+the session use: ``Ctrl+E c .``
+:::
+
+:::{hint}
+If ``alias`` is set, it can be used instead of the device when
+connecting.
+:::
+```
+```{opcmd} show log console-server
+
+Show the console server log.
+```
\ No newline at end of file
diff --git a/docs/configuration/service/dhcp-relay.md b/docs/configuration/service/dhcp-relay.md
new file mode 100644
index 00000000..a4a10109
--- /dev/null
+++ b/docs/configuration/service/dhcp-relay.md
@@ -0,0 +1,205 @@
+(dhcp-relay)=
+
+# DHCP Relay
+
+If you want your router to forward DHCP requests to an external DHCP server
+you can configure the system to act as a DHCP relay agent. The DHCP relay
+agent works with IPv4 and IPv6 addresses.
+
+All interfaces used for the DHCP relay must be configured. This includes the
+uplink to the DHCP server.
+
+## IPv4 relay
+
+### Configuration
+
+```{cfgcmd} set service dhcp-relay interface \<interface\>
+
+Interfaces that participate in the DHCP relay process. If this command is
+used, at least two entries of it are required: one for the interface that
+captures the dhcp-requests, and one for the interface to forward such
+requests. A warning message will be shown if this command is used, since
+new implementations should use ``listen-interface`` and
+``upstream-interface``.
+```
+
+```{cfgcmd} set service dhcp-relay listen-interface \<interface\>
+
+Interface for DHCP Relay Agent to listen for requests.
+```
+
+```{cfgcmd} set service dhcp-relay upstream-interface \<interface\>
+
+Interface for DHCP Relay Agent to forward requests out.
+```
+
+```{cfgcmd} set service dhcp-relay server \<server\>
+
+Configure IP address of the DHCP `<server>` which will handle the relayed
+packets.
+```
+
+```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets discard
+
+The router should discard DHCP packages already containing relay agent
+information to ensure that only requests from DHCP clients are forwarded.
+```
+
+```{cfgcmd} set service dhcp-relay disable
+
+Disable dhcp-relay service.
+```
+
+
+#### Options
+
+```{cfgcmd} set service dhcp-relay relay-options hop-count \<count\>
+
+Set the maximum hop `<count>` before packets are discarded. Range 0...255,
+default 10.
+```
+
+```{cfgcmd} set service dhcp-relay relay-options max-size \<size\>
+
+Set maximum `<size>` of DHCP packets including relay agent information. If a
+DHCP packet size surpasses this value it will be forwarded without appending
+relay agent information. Range 64...1400, default 576.
+```
+
+```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets \<append | discard | forward | replace\>
+
+Four policies for reforwarding DHCP packets exist:
+* **append:** The relay agent is allowed to append its own relay information
+to a received DHCP packet, disregarding relay information already present
+in the packet.
+* **discard:** Received packets which already contain relay information will
+be discarded.
+* **forward:** All packets are forwarded, relay information already present
+will be ignored.
+* **replace:** Relay information already present in a packet is stripped and
+replaced with the router's own relay information set.
+```
+
+
+### Example
+
+- Listen for DHCP requests on interface `eth1`.
+- DHCP server is located at IPv4 address 10.0.1.4 on `eth2`.
+- Router receives DHCP client requests on `eth1` and relays them to the
+  server at 10.0.1.4 on `eth2`.
+
+:::{figure} /_static/images/service_dhcp-relay01.webp
+:alt: DHCP relay example
+:scale: 80 %
+DHCP relay example
+:::
+
+The generated configuration will look like:
+
+```none
+show service dhcp-relay
+    listen-interface eth1
+    upstream-interface eth2
+    server 10.0.1.4
+    relay-options {
+       relay-agents-packets discard
+    }
+```
+
+Also, for backwards compatibility this configuration, which uses generic
+interface definition, is still valid:
+
+```none
+show service dhcp-relay
+    interface eth1
+    interface eth2
+    server 10.0.1.4
+    relay-options {
+       relay-agents-packets discard
+    }
+```
+
+
+### Operation
+
+```{opcmd} restart dhcp relay-agent
+
+Restart DHCP relay service
+```
+
+
+## IPv6 relay
+
+(dhcp-relay-ipv6-configuration)=
+
+### Configuration
+
+```{cfgcmd} set service dhcpv6-relay listen-interface \<interface\>
+
+Set eth1 to be the listening interface for the DHCPv6 relay.
+
+Multiple interfaces may be specified.
+```
+
+```{cfgcmd} set service dhcpv6-relay upstream-interface \<interface\> address \<server\>
+
+Specifies an upstream network `<interface>` from which replies from
+`<server>` and other relay agents will be accepted.
+```
+
+(dhcp-relay-ipv6-options)=
+
+```{cfgcmd} set service dhcpv6-relay disable
+
+Disable dhcpv6-relay service.
+```
+
+(dhcp-relay-v6-options)=
+
+#### Options
+
+```{cfgcmd} set service dhcpv6-relay max-hop-count \<count\>
+
+Set maximum hop count before packets are discarded, default: 10
+```
+
+```{cfgcmd} set service dhcpv6-relay use-interface-id-option
+
+If this is set the relay agent will insert the interface ID. This option is
+set automatically if more than one listening interfaces are in use.
+```
+
+(dhcp-relay-ipv6-example)=
+
+### Example
+
+- DHCPv6 requests are received by the router on `listening interface` `eth1`
+- Requests are forwarded through `eth2` as the `upstream interface`
+- External DHCPv6 server is at 2001:db8::4
+
+:::{figure} /_static/images/service_dhcpv6-relay01.webp
+:alt: DHCPv6 relay example
+:scale: 80 %
+DHCPv6 relay example
+:::
+
+The generated configuration will look like:
+
+```none
+commit
+show service dhcpv6-relay
+    listen-interface eth1 {
+    }
+    upstream-interface eth2 {
+       address 2001:db8::4
+    }
+```
+
+(dhcp-relay-ipv6-op-cmd)=
+
+### Operation
+
+```{opcmd} restart dhcpv6 relay-agent
+
+Restart DHCPv6 relay agent immediately.
+```
\ No newline at end of file
diff --git a/docs/configuration/service/dhcp-server.md b/docs/configuration/service/dhcp-server.md
new file mode 100644
index 00000000..721d6d4a
--- /dev/null
+++ b/docs/configuration/service/dhcp-server.md
@@ -0,0 +1,1178 @@
+(dhcp-server)=
+
+# DHCP Server
+
+VyOS uses Kea DHCP server for both IPv4 and IPv6 address assignment.
+
+## IPv4 server
+
+The network topology is declared by shared-network-name and the subnet
+declarations. The DHCP service can serve multiple shared networks, with each
+shared network having 1 or more subnets. Each subnet must be present on an
+interface. A range can be declared inside a subnet to define a pool of dynamic
+addresses. Multiple ranges can be defined and can contain holes. Static
+mappings can be set to assign "static" addresses to clients based on their MAC
+address.
+
+### Configuration
+
+```{cfgcmd} set service dhcp-server hostfile-update
+
+   Create DNS record per client lease, by adding clients to /etc/hosts file.
+   Entry will have format: `<shared-network-name>_<hostname>.<domain-name>`
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> option domain-name \<domain-name\>
+
+The domain-name parameter should be the domain name that will be appended to
+the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP
+Option 015).
+
+This is the configuration parameter for the entire shared network definition.
+All subnets will inherit this configuration item if not specified locally.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> option domain-search \<domain-name\>
+
+The domain-name parameter should be the domain name used when completing DNS
+request where no full FQDN is passed. This option can be given multiple times
+if you need multiple search domains (DHCP Option 119).
+
+This is the configuration parameter for the entire shared network definition.
+All subnets will inherit this configuration item if not specified locally.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> option name-server \<address\>
+
+Inform client that the DNS server can be found at `<address>`.
+
+This is the configuration parameter for the entire shared network definition.
+All subnets will inherit this configuration item if not specified locally.
+Multiple DNS servers can be defined.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> option vendor-option \<option-name\>
+
+This configuration parameter lets you specify a vendor-option for the
+entire shared network definition. All subnets will inherit this
+configuration item if not specified locally. An example for Ubiquiti is
+shown below:
+```
+
+**Example:**
+
+
+Pass address of Unifi controller at `172.16.100.1` to all clients of `NET1`
+
+```none
+set service dhcp-server shared-network-name 'NET1' option vendor-option
+ubiquiti '172.16.100.1'
+```
+
+
+```{cfgcmd} set service dhcp-server listen-address \<address\>
+
+This configuration parameter lets the DHCP server to listen for DHCP
+requests sent to the specified address, it is only realistically useful for
+a server whose only clients are reached via unicasts, such as via DHCP relay
+agents.
+```
+
+#### Individual Client Subnet
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> authoritative
+
+This says that this device is the only DHCP server for this network. If other
+devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to
+any device trying to request an IP address that is not valid for this
+network.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> subnet-id \<id\>
+
+This configuration parameter is required and must be unique to each subnet.
+It is required to map subnets to lease file entries.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option default-router \<address\>
+
+This is a configuration parameter for the `<subnet>`, saying that as part of
+the response, tell the client that the default gateway can be reached at
+`<address>`.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option name-server \<address\>
+
+This is a configuration parameter for the subnet, saying that as part of the
+response, tell the client that the DNS server can be found at `<address>`.
+
+Multiple DNS servers can be defined.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> lease \<time\>
+
+Assign the IP address to this machine for `<time>` seconds.
+
+The default value is 86400 seconds which corresponds to one day.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> range \<n\> start \<address\>
+
+Create DHCP address range with a range id of `<n>`. DHCP leases are taken
+from this pool. The pool starts at address `<address>`.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> range \<n\> stop \<address\>
+
+Create DHCP address range with a range id of `<n>`. DHCP leases are taken
+from this pool. The pool stops with address `<address>`.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> exclude \<address\>
+
+Always exclude this address from any defined range. This address will never
+be assigned by the DHCP server.
+
+This option can be specified multiple times.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option domain-name \<domain-name\>
+
+The domain-name parameter should be the domain name that will be appended to
+the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP
+Option 015).
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option domain-search \<domain-name\>
+
+The domain-name parameter should be the domain name used when completing DNS
+request where no full FQDN is passed. This option can be given multiple times
+if you need multiple search domains (DHCP Option 119).
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option vendor-option \<option-name\>
+
+This configuration parameter lets you specify a vendor-option for the
+subnet specified within the shared network definition. An example for
+Ubiquiti is shown below:
+```
+
+**Example:**
+
+
+Create `172.18.201.0/24` as a subnet within `NET1` and pass address of
+Unifi controller at `172.16.100.1` to clients of that subnet.
+
+```none
+set service dhcp-server shared-network-name 'NET1' subnet
+'172.18.201.0/24' option vendor-option ubiquiti '172.16.100.1'
+```
+
+#### Dynamic DNS Update (RFC 2136)
+
+
+VyOS DHCP service supports RFC-2136 DDNS protocol. Based on DHCP lease change
+events, DHCP server generates DDNS update requests (defines as NameChangeRequests
+or NCRs) and posts them to a compliant DNS server, that will update its name
+database accordingly.
+
+
+VyOS built-in DNS Forwarder does not support DDNS, you will need an external DNS
+server with RFC-2136 DDNS support.
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update
+
+Enables DDNS globally.
+```
+
+**Behavioral settings**
+
+
+These settings can be configured on the global level and overridden on the scope
+level, i.e. for individual shared networks or subnets. See examples below.
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update send-updates [ enable | disable ]
+
+If set to ``enable`` on global level, updates for all scopes will be enabled,
+except if explicitly set to ``disable`` on the scope level. If set to ``disable``,
+updates will only be sent for scopes, where ``send-updates`` is explicitly
+set to ``enable``.
+
+This model is followed for a few behavioral settings below: if the option is
+not set, the setting is inherited from the parent scope. You can override the
+parent scope setting by setting the option explicitly.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update override-no-update [ enable | disable ]
+
+VyOS will ignore client request not to update DNS records and send DDNS
+update requests regardless.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update override-client-update [ enable | disable ]
+
+VyOS will override client DDNS request settings and always update both
+forward and reverse DNS records.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update update-on-renew [ enable | disable ]
+
+Issue DDNS update requests on DHCP lease renew. In busy networks this may
+generate a lot of traffic.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update conflict-resolution [ enable | disable ]
+
+Use RFC-4703 conflict resolution. This algorithm helps in situation when
+multiple clients reserve same IP addresses or advertise identical hostnames.
+Should be used in most situations.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update replace-client-name [ never | always | when-present | when-not-present ]
+
+* **never**: use the name sent by the client. If the client didn't provide any,
+do not generate one. This is the default behavior
+
+* **always**: always generate a name for the client
+
+* **when-present**: replace the name the client sent with a generated one, if
+the client didn't send any, do not generate one
+
+* **when-not-present**: use the name sent by the client. If the client didn't
+send any, generate one for the client
+
+The names are generated using ``generated-prefix``, ``qualifying-suffix`` and the
+client's IP address string.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update generated-prefix \<prefix\>
+
+Prefix used in client name generation.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update qualifying-suffix \<suffix\>
+
+DNS suffix used in client name generation.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update ttl-percent \<0-100\>
+
+TTL of the DNS record as a percentage of the DHCP lease time.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update hostname-char-set \<character string\>
+
+Characters, that are considered invalid in the client name. They will be replaced
+with ``hostname-char-replacement`` string.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update hostname-char-replacement \<character string\>
+
+Replacement string for the invalid characters defined by ``hostname-char-set``.
+```
+
+**TSIG keys definition**
+
+
+This is the global list of TSIG keys for DDNS updates. They need to be specified by
+the name in the DNS domain definitions.
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update tsig-key \<key-name\> algorithm \<algorithm\>
+
+Sets the algorithm for the TSIG key. Supported algorithms are ``hmac-md5``,
+``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, ``hmac-sha512``
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update tsig-key \<key-name\> secret \<key-secret\>
+
+base64-encoded TSIG key secret value
+```
+
+**DNS domains definition**
+
+
+This is global configuration of DNS servers for the updatable forward and reverse
+DNS domains. For every domain multiple DNS servers can be specified.
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> key-name \<tsig-key-name\>
+
+TSIG key used for the domain.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> dns-server \<number\> address \<ip-address\>
+
+IP address of the DNS server.
+```
+
+
+```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> dns-server \<number\> port \<port\>
+
+UDP port of the DNS server. ``53`` is the default.
+```
+
+**Example:**
+
+
+Global configuration you will most likely want:
+
+```none
+set service dhcp-server dynamic-dns-update send-updates enable
+set service dhcp-server dynamic-dns-update conflict-resolution enable
+```
+
+Override the above configuration for a shared network NET1:
+
+```none
+set service dhcp-server shared-network-name 'NET1' dynamic-dns-update replace-client-name when-not-present
+set service dhcp-server shared-network-name 'NET1' dynamic-dns-update generated-prefix ip
+set service dhcp-server shared-network-name 'NET1' dynamic-dns-update qualifying-suffix mybigdomain.net
+```
+
+And in a subnet within the same shared network:
+
+```none
+set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' dynamic-dns-update qualifying-suffix mydomain.net
+```
+
+Configure TSIG keys:
+
+```none
+set service dhcp-server dynamic-dns-update tsig-key mydomain-net algorithm hmac-sha256
+set service dhcp-server dynamic-dns-update tsig-key mydomain-net secret eWF5YW15bGl0dGxla2V5IQ==
+set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 algorithm hmac-sha256
+set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 secret eWF5YW15YW5vdGhlcmxpdHRsZWtleSE=
+```
+
+Configure DDNS domains:
+
+```none
+set service dhcp-server dynamic-dns-update forward-domain mydomain.net key-name mydomain-net
+set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 address '172.18.0.254'
+set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 port 1053
+set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 address '192.168.124.254'
+set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 port 53
+set service dhcp-server dynamic-dns-update forward-domain 201.18.172.in-addr.arpa key-name reverse-172-18-201
+set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 address '172.18.0.254'
+set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 port 1053
+set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 address '192.168.124.254'
+set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 port 53
+```
+
+#### High Availability
+
+
+VyOS provides High Availability support for DHCP server. DHCP High
+Availability can act in two different modes:
+
+
+- **Active-active**: both DHCP servers will respond to DHCP requests. If
+  `mode` is not defined, this is the default behavior.
+- **Active-passive**: only `primary` server will respond to DHCP requests.
+  If this server goes offline, then `secondary` server will take place.
+
+
+DHCP High Availability must be configured explicitly by the following
+statements on both servers:
+
+```{cfgcmd} set service dhcp-server high-availability mode [active-active | active-passive]
+
+Define operation mode of High Availability feature. Default value if command
+is not specified is `active-active`
+```
+
+
+```{cfgcmd} set service dhcp-server high-availability source-address \<address\>
+
+Local IP `<address>` used when communicating to the HA peer.
+```
+
+
+```{cfgcmd} set service dhcp-server high-availability remote \<address\>
+
+Remote peer IP `<address>` of the second DHCP server in this HA
+cluster.
+```
+
+
+```{cfgcmd} set service dhcp-server high-availability name \<name\>
+
+Define the name of the peer server to establish and identify the HA (High Availability) connection.
+
+:::{note}
+Make sure the specified value does not conflict with the system host-name.
+:::
+```
+
+
+```{cfgcmd} set service dhcp-server high-availability status \<primary | secondary\>
+
+The primary and secondary statements determines whether the server is primary
+or secondary.
+
+:::{note}
+In order for the primary and the secondary DHCP server to keep
+their lease tables in sync, they must be able to reach each other on TCP
+port 647. If you have firewall rules in effect, adjust them accordingly.
+:::
+:::{hint}
+The dialogue between HA partners is neither encrypted nor
+authenticated. Since most DHCP servers exist within an organisation's own
+secure Intranet, this would be an unnecessary overhead. However, if you
+have DHCP HA peers whose communications traverse insecure networks,
+then we recommend that you consider the use of VPN tunneling between them
+to ensure that the HA partnership is immune to disruption
+(accidental or otherwise) via third parties.
+:::
+```
+
+#### Static mappings
+
+
+You can specify a static DHCP assignment on a per host basis. You will need the
+MAC address of the station and your desired IP address. The address must be
+inside the subnet definition but can be outside of the range statement.
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> mac \<address\>
+
+Create a new DHCP static mapping named `<description>` which is valid for
+the host identified by its MAC `<address>`.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> duid \<identifier\>
+
+Create a new DHCP static mapping named `<description>` which is valid for
+the host identified by its DHCP unique identifier (DUID) `<identifier>`.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> ip-address \<address\>
+
+Static DHCP IP address assign to host identified by `<description>`. IP
+address must be inside the `<subnet>` which is defined but can be outside
+the dynamic range created with {cfgcmd}`set service dhcp-server
+shared-network-name <name> subnet <subnet> range <n>`. If no ip-address is
+specified, an IP from the dynamic pool is used.
+
+This is useful, for example, in combination with hostfile update.
+
+:::{hint}
+This is the equivalent of the host block in dhcpd.conf of
+isc-dhcpd.
+:::
+```
+
+**Example:**
+
+
+- IP address `192.168.1.100` shall be statically mapped to client named `client1`
+
+```none
+set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 subnet-id 1
+set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 ip-address 192.168.1.100
+set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 mac aa:bb:11:22:33:00
+```
+
+The configuration will look as follows:
+
+```none
+show service dhcp-server shared-network-name NET1
+ subnet 192.168.1.0/24 {
+     static-mapping client1 {
+         ip-address 192.168.1.100
+         mac aa:bb:11:22:33:00
+     }
+     subnet-id 1
+ }
+```
+
+#### Relay agent information (Option 82)
+
+
+Some DHCP relays support the injection of information into a DHCP request, depending on
+where the request originated from. This is commonly used to determine the
+behaviour of the DHCP server, based on the port/switch combination where the
+request was first detected. I.e. the device plugged into a particular port (or
+set of ports) always gets the same IP address (or range of IP addresses). This
+information is usually included in the request using Option 82, hence this
+is what we call this part of the configuration.
+
+
+This behaviour is controlled in two parts. First, "client classes" are defined
+which determine which inputs match. Once a positive match has been found the
+request is "tagged" with this client class. Second, when the DHCP server
+processes the request it checks to see if the configuration has a client class
+defined. If it does then that part of the configuration will override the others
+
+
+Client classes can be applied at either the subnet or range level, depending on
+how you want the server to behave.
+
+
+**Client Class definition**
+
+```{cfgcmd} set service dhcp-server client-class \<name\> relay-agent-information circuit-id \<value\>
+
+Create a new client class (if not already defined) and set it to match on
+the "Circuit ID" part of the Option 82 field in the DHCP request. This is
+sub option "1" as specified by RFC 3046. The value specified here is either
+interpreted as a raw hex value, if it starts with the prefix 0x, or ASCII text
+otherwise. e.g. ``e1-5`` and ``0x65312d35`` are the same
+```
+
+
+```{cfgcmd} set service dhcp-server client-class \<name\> relay-agent-information remote-id \<value\>
+
+Create a new client class (if not already defined) and set it to match on
+the "Remote ID" part of the Option 82 field in the DHCP request. This is
+sub option "2" as specified by RFC 3046. The value specified here is either
+interpreted as a raw hex value, if it starts with the prefix 0x, or ASCII text
+otherwise. e.g. ``10.100.0.41`` and ``0x31302e3130302e302e3431`` are the
+same
+```
+
+**Client Class application**
+
+```{cfgcmd} set service dhcp-server shared-network-name \<subnet-name\> subnet \<CIDR\> client-class \<class-name\>
+
+Applies the Client Class with the name `<class-name>` to the subnet `<subnet-name>`.
+This means that whenever the client class matches a request it is always
+routed to this subnet definition first.
+```
+
+
+```{cfgcmd} set service dhcp-server shared-network-name \<subnet-name\> subnet \<CIDR\> range \<range-name\> client-class \<class-name\>
+
+Applies the Client Class with the name `<class-name>` to the range
+`<range-name>` which belongs to subnet `<subnet-name>`. This means that whenever the
+client class matches a request it is always routed to this range definition
+first.
+```
+
+NB: Kea (the DHCP server used by VyOS) is programmed to offer as many
+alternatives as it can to repeated DHCP Discover requests. Some operating
+systems (Notably Microsoft Windows) make multiple DHCP Discover requests before
+settling on an address. This particularly seems to happen when the DHCP server
+isn't set to authoritative. This may explain why the address you expect isn't
+being chosen. Wireshark is helpful in these situations.
+
+
+**Example:**
+
+
+The following configuration example will classify requests coming in on port
+`e1-5` from DHCP Relay `192.0.2.1` and make sure that they are allocated the
+address `192.0.2.4`. Any requests which do not match the circuit and remote ID
+will, instead, be allocated from the range otherRange in the usual manner.
+
+
+NB: Both the Circuit ID and Remote ID fields are arbitrary free text. *Most*
+switches set the Remote ID to the IP address of the management interface but
+that should not be relied upon. Check the documentation of your DHCP Relay for
+more detail or, as a measure of last resort, inspect the DHCP requests in
+Wireshark.
+
+```none
+service {
+    dhcp-server {
+        client-class className {
+            relay-agent-information {
+                circuit-id e1-5
+                remote-id 192.0.2.1
+            }
+        }
+        shared-network-name test {
+            subnet 192.0.2.0/24 {
+                range classNameRange {
+                    client-class className
+                    start 192.0.2.4
+                    stop 192.0.2.4
+                }
+                range otherRange {
+                    start 192.0.2.5
+                    stop 192.0.2.100
+                }
+                subnet-id 1
+            }
+        }
+    }
+}
+```
+
+### Options
+
+
+:::{list-table}
+:header-rows: 1
+:stub-columns: 0
+:widths: 12 7 23 40 20
+
+* - Setting name
+  - Option number
+  - ISC-DHCP Option name
+  - Option description
+  - Multi
+* - client-prefix-length
+  - 1
+  - subnet-mask
+  - Specifies the clients subnet mask as per RFC 950. If unset,
+    subnet declaration is used.
+  - N
+* - time-offset
+  - 2
+  - time-offset
+  - Offset of the client's subnet in seconds from Coordinated
+    Universal Time (UTC)
+  - N
+* - default-router
+  - 3
+  - routers
+  - IPv4 address of router on the client's subnet
+  - N
+* - time-server
+  - 4
+  - time-servers
+  - RFC 868 time server IPv4 address
+  - Y
+* - name-server
+  - 6
+  - domain-name-servers
+  - DNS server IPv4 address
+  - Y
+* - domain-name
+  - 15
+  - domain-name
+  - Client domain name
+  - Y
+* - ip-forwarding
+  - 19
+  - ip-forwarding
+  - Enable IP forwarding on client
+  - N
+* - ntp-server
+  - 42
+  - ntp-servers
+  - IP address of NTP server
+  - Y
+* - wins-server
+  - 44
+  - netbios-name-servers
+  - NetBIOS over TCP/IP name server
+  - Y
+* - server-identifier
+  - 54
+  - dhcp-server-identifier
+  - IP address for DHCP server identifier
+  - N
+* - bootfile-server
+  - siaddr
+  - next-server
+  - IPv4 address of next bootstrap server
+  - N
+* - tftp-server-name
+  - 66
+  - tftp-server-name
+  - Name or IPv4 address of TFTP server
+  - N
+* - bootfile-name
+  - 67
+  - bootfile-name, filename
+  - Bootstrap file name
+  - N
+* - bootfile-size
+  - 13
+  - boot-size
+  - Boot image length in 512-octet blocks
+  - N
+* - smtp-server
+  - 69
+  - smtp-server
+  - IP address of SMTP server
+  - Y
+* - pop-server
+  - 70
+  - pop-server
+  - IP address of POP3 server
+  - Y
+* - domain-search
+  - 119
+  - domain-search
+  - Client domain search
+  - Y
+* - static-route
+  - 121, 249
+  - rfc3442-static-route, windows-static-route
+  - Classless static route
+  - N
+* - wpad-url
+  - 252
+  - wpad-url, wpad-url code 252 = text
+  - Web Proxy Autodiscovery (WPAD) URL
+  - N
+* - lease
+  -
+  - default-lease-time, max-lease-time
+  - Lease timeout in seconds (default: 86400)
+  - N
+* - range
+  -
+  - range
+  - DHCP lease range
+  - Y
+* - exclude
+  -
+  -
+  - IP address to exclude from DHCP lease range
+  - Y
+* - failover
+  -
+  -
+  - DHCP failover parameters
+  -
+* - static-mapping
+  -
+  -
+  - Name of static mapping
+  - Y
+:::
+
+
+Multi: can be specified multiple times.
+
+
+### Example
+
+
+Please see the {ref}`dhcp-dns-quick-start` configuration.
+
+
+(dhcp-server-v4-example-failover)=
+
+
+#### High Availability
+
+
+Configuration of a DHCP HA pair:
+
+
+- Setup DHCP HA for network 192.0.2.0/24
+- Use active-active HA mode.
+- Default gateway and DNS server is at `192.0.2.254`
+- The primary DHCP server named dhcp-primary uses address `192.168.189.252`
+- The secondary DHCP server with named dhcp-secondary uses address `192.168.189.253`
+- DHCP range spans from `192.168.189.10` - `192.168.189.250`
+
+
+Common configuration, valid for both primary and secondary node.
+
+```none
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option default-router '192.0.2.254'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option name-server '192.0.2.254'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option domain-name 'vyos.net'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250'
+set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 subnet-id '1'
+```
+
+**Primary**
+
+```none
+set service dhcp-server high-availability mode 'active-active'
+set service dhcp-server high-availability source-address '192.168.189.252'
+set service dhcp-server high-availability name 'dhcp-secondary'
+set service dhcp-server high-availability remote '192.168.189.253'
+set service dhcp-server high-availability status 'primary'
+```
+
+**Secondary**
+
+```none
+set service dhcp-server high-availability mode 'active-active'
+set service dhcp-server high-availability source-address '192.168.189.253'
+set service dhcp-server high-availability name 'dhcp-primary'
+set service dhcp-server high-availability remote '192.168.189.252'
+set service dhcp-server high-availability status 'secondary'
+```
+
+(dhcp-server-v4-example-raw)=
+
+
+### Operation Mode
+
+```{opcmd} show log dhcp server
+
+Show DHCP server daemon log file
+```
+
+
+```{opcmd} show log dhcp client
+
+Show logs from all DHCP client processes.
+```
+
+
+```{opcmd} show log dhcp client interface \<interface\>
+
+Show logs from specific `interface` DHCP client process.
+```
+
+
+```{opcmd} restart dhcp server
+
+Restart the DHCP server
+```
+
+
+```{opcmd} show dhcp server statistics
+
+Show the DHCP server statistics:
+```
+
+
+```none
+vyos@vyos:~$ show dhcp server statistics
+Pool           Size    Leases    Available  Usage
+-----------  ------  --------  -----------  -------
+dhcpexample      99         2           97  2%
+```
+
+
+```{opcmd} show dhcp server statistics pool \<pool\>
+
+Show the DHCP server statistics for the specified pool.
+```
+
+
+```{opcmd} show dhcp server leases
+
+Show statuses of all active leases:
+```
+
+
+```none
+vyos@vyos:~$ show dhcp server leases
+IP Address      MAC address        State    Lease start          Lease expiration     Remaining    Pool      Hostname    Origin
+--------------  -----------------  -------  -------------------  -------------------  -----------  --------  ----------  --------
+192.168.11.134  00:50:79:66:68:09  active   2023/11/29 09:51:05  2023/11/29 10:21:05  0:24:10      LAN       VPCS1       local
+192.168.11.133  50:00:00:06:00:00  active   2023/11/29 09:51:38  2023/11/29 10:21:38  0:24:43      LAN       VYOS-6      local
+10.11.11.108    50:00:00:05:00:00  active   2023/11/29 09:51:43  2023/11/29 10:21:43  0:24:48      VIF-1001  VYOS5       local
+192.168.11.135  00:50:79:66:68:07  active   2023/11/29 09:55:16  2023/11/29 09:59:16  0:02:21                            remote
+vyos@vyos:~$
+```
+
+:::{hint}
+Static mappings aren't shown. To show all states, use
+`show dhcp server leases state all`.
+:::
+
+```{opcmd} show dhcp server leases origin [local | remote]
+
+Show statuses of all active leases granted by local (this server) or
+remote (failover server):
+```
+
+
+```none
+vyos@vyos:~$ show dhcp server leases origin remote
+IP Address      MAC address        State    Lease start          Lease expiration     Remaining    Pool      Hostname    Origin
+--------------  -----------------  -------  -------------------  -------------------  -----------  --------  ----------  --------
+192.168.11.135  00:50:79:66:68:07  active   2023/11/29 09:55:16  2023/11/29 09:59:16  0:02:21                            remote
+vyos@vyos:~$
+```
+
+
+```{opcmd} show dhcp server leases pool \<pool\>
+
+Show only leases in the specified pool.
+```
+
+
+```none
+vyos@vyos:~$ show dhcp server leases pool LAN
+IP Address      MAC address        State    Lease start          Lease expiration     Remaining    Pool    Hostname    Origin
+--------------  -----------------  -------  -------------------  -------------------  -----------  ------  ----------  --------
+192.168.11.134  00:50:79:66:68:09  active   2023/11/29 09:51:05  2023/11/29 10:21:05  0:23:55      LAN     VPCS1       local
+192.168.11.133  50:00:00:06:00:00  active   2023/11/29 09:51:38  2023/11/29 10:21:38  0:24:28      LAN     VYOS-6      local
+vyos@vyos:~$
+```
+
+
+```{opcmd} show dhcp server leases sort \<key\>
+
+Sort the output by the specified key. Possible keys: ip, hardware_address,
+state, start, end, remaining, pool, hostname (default = ip)
+```
+
+
+```{opcmd} show dhcp server leases state \<state\>
+
+Show only leases with the specified state. Possible states: all, active,
+free, expired, released, abandoned, reset, backup (default = active)
+```
+
+## IPv6 server
+
+VyOS also provides DHCPv6 server functionality which is described in this
+section.
+(dhcp-server-v6-config)=
+
+### Configuration
+
+```{cfgcmd} set service dhcpv6-server preference \<preference value\>
+
+   Clients receiving advertise messages from multiple servers choose the server
+   with the highest preference value. The range for this value is ``0...255``.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<subnet\> subnet-id \<id\>
+
+This configuration parameter is required and must be unique to each subnet.
+It is required to map subnets to lease file entries.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> lease-time {default | maximum | minimum}
+
+The default lease time for DHCPv6 leases is 24 hours. This can be changed by
+supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All
+values need to be supplied in seconds.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nis-domain \<domain-name\>
+
+A {abbr}`NIS (Network Information Service)` domain can be set to be used for
+DHCPv6 clients.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nisplus-domain \<domain-name\>
+
+The procedure to specify a {abbr}`NIS+ (Network Information Service Plus)`
+domain is similar to the NIS domain one:
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nis-server \<address\>
+
+Specify a NIS server address for DHCPv6 clients.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nisplus-server \<address\>
+
+Specify a NIS+ server address for DHCPv6 clients.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option sip-server \<address | fqdn\>
+
+Specify a {abbr}`SIP (Session Initiation Protocol)` server by IPv6
+address of Fully Qualified Domain Name for all DHCPv6 clients.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option sntp-server-address \<address\>
+
+A SNTP server address can be specified for DHCPv6 clients.
+```
+
+#### Prefix Delegation
+
+
+To hand out individual prefixes to your clients the following configuration is
+used:
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> prefix-length \<length\>
+
+Delegate prefixes from `<pd-prefix>` to clients in subnet `<prefix>`. Range
+is defined by `<length>` in bits, 32 to 64.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> delegated-length \<length\>
+
+Hand out prefixes of size `<length>` in bits from `<pd-prefix>` to clients
+in subnet `<prefix>` when the request for prefix delegation.
+```
+
+
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> excluded-prefix \<exclude-prefix\>
+
+Exclude `<exclude-prefix>` from `<pd-prefix>`.
+```
+```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> excluded-prefix-length \<length\>
+
+Define length of exclude prefix in `<pd-prefix>`.
+```
+
+**Example:**
+- A shared network named `PD-NET` serves subnet `2001:db8::/64`.
+- It is connected to `eth1`.
+- Address pool shall be `2001:db8::100` through `2001:db8::199`.
+- It hands out prefixes `2001:db8:0:10::/64` through `2001:db8:0:1f::/64`.
+
+```none
+set service dhcpv6-server shared-network-name 'PD-NET' interface 'eth1'
+set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 start 2001:db8::100
+set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 stop 2001:db8::199
+set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: delegated-length '64'
+set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: prefix-length '60'
+set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 subnet-id 1
+```
+
+#### Address pools
+
+DHCPv6 address pools must be configured for the system to act as a DHCPv6
+server. The following example describes a common scenario.
+
+**Example:**
+- A shared network named `NET1` serves subnet `2001:db8::/64`
+- It is connected to `eth1`
+- DNS server is located at `2001:db8::ffff`
+- Address pool shall be `2001:db8::100` through `2001:db8::199`.
+- Lease time will be left at the default value which is 24 hours
+
+```none
+set service dhcpv6-server shared-network-name 'NET' interface 'eth1'
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 range 1 start 2001:db8::100
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 range 1 stop 2001:db8::199
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 option name-server 2001:db8::ffff
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 subnet-id 1
+```
+
+The configuration will look as follows:
+
+```none
+show service dhcpv6-server
+    shared-network-name NET1 {
+        subnet 2001:db8::/64 {
+           range 1 {
+              start 2001:db8::100
+              stop 2001:db8::199
+           }
+           option {
+              name-server 2001:db8::ffff
+           }
+           subnet-id 1
+        }
+    }
+```
+
+(dhcp-server-v6-static-mapping)=
+
+#### Static mappings
+
+In order to map specific IPv6 addresses to specific hosts static mappings can
+be created. The following example explains the process.
+
+**Example:**
+- IPv6 address `2001:db8::101` shall be statically mapped
+- IPv6 prefix `2001:db8:0:101::/64` shall be statically mapped
+- Host specific mapping shall be named `client1`
+
+:::{hint}
+The identifier is the device's DUID: colon-separated hex list (as
+used by isc-dhcp option dhcpv6.client-id). If the device already has a
+dynamic lease from the DHCPv6 server, its DUID can be found with `show
+service dhcpv6 server leases`. The DUID begins at the 5th octet (after the
+4th colon) of IAID_DUID.
+:::
+```none
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-prefix 2001:db8:0:101::/64
+set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 duid 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff
+```
+
+The configuration will look as follows:
+
+```none
+show service dhcpv6-server shared-network-name NET1
+ subnet 2001:db8::/64 {
+     static-mapping client1 {
+         duid 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff
+         ipv6-address 2001:db8::101
+         ipv6-prefix 2001:db8:0:101::/64
+     }
+ }
+```
+
+(dhcp-server-v6-op-cmd)=
+
+### Operation Mode
+
+```{opcmd} show log dhcpv6 server
+
+Show DHCPv6 server daemon log file
+```
+```{opcmd} show log dhcpv6 client
+
+Show logs from all DHCPv6 client processes.
+```
+```{opcmd} show log dhcpv6 client interface \<interface\>
+
+Show logs from specific `interface` DHCPv6 client process.
+```
+```{opcmd} restart dhcpv6 server
+
+To restart the DHCPv6 server
+```
+```{opcmd} show dhcpv6 server leases
+
+Shows status of all assigned leases:
+```
+```none
+vyos@vyos:~$ show dhcpv6 server leases
+IPv6 address      State    Last communication    Lease expiration     Remaining    Type   Pool      DUID
+----------------  -------  --------------------  -------------------  -----------  -----  --------  --------------------------------------------
+2001:db8::101     active   2019/12/05 19:40:10   2019/12/06 07:40:10  11:45:21     IA_NA  NET1      98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff
+2001:db8::102     active   2019/12/05 14:01:23   2019/12/06 02:01:23  6:06:34      IA_NA  NET1      87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff
+2001:db8:10::/64  active   2019/12/05 23:20:10   2019/12/06 11:40:10  11:45:21     IA_PD  PD-NET1   98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff
+```
+
+:::{hint}
+Static mappings aren't shown. To show all states, use `show dhcp
+server leases state all`.
+:::
+
+```{opcmd} show dhcpv6 server leases pool \<pool\>
+
+Show only leases in the specified pool.
+```
+```{opcmd} show dhcpv6 server leases sort \<key\>
+
+Sort the output by the specified key. Possible keys: expires, iaid_duid, ip,
+last_comm, pool, remaining, state, type (default = ip)
+```
+```{opcmd} show dhcpv6 server leases state \<state\>
+
+Show only leases with the specified state. Possible states: abandoned,
+active, all, backup, expired, free, released, reset (default = active)
+```
\ No newline at end of file
diff --git a/docs/configuration/service/dns.md b/docs/configuration/service/dns.md
new file mode 100644
index 00000000..e7e9b457
--- /dev/null
+++ b/docs/configuration/service/dns.md
@@ -0,0 +1,582 @@
+(dns-forwarding)=
+
+# DNS Forwarding
+
+## Configuration
+
+VyOS provides DNS infrastructure for small networks. It is designed to be
+lightweight and have a small footprint, suitable for resource constrained
+routers and firewalls. For this we utilize PowerDNS recursor.
+
+The VyOS DNS forwarder does not require an upstream DNS server. It can serve as
+a full recursive DNS server - but it can also forward queries to configurable
+upstream DNS servers. By not configuring any upstream DNS servers you also
+avoid being tracked by the provider of your upstream DNS server.
+
+```{cfgcmd} set service dns forwarding system
+
+   Forward incoming DNS queries to the DNS servers configured under the ``system
+   name-server`` nodes.
+```
+
+
+```{cfgcmd} set service dns forwarding dhcp \<interface\>
+
+Interfaces whose DHCP client nameservers to forward requests to.
+```
+
+
+```{cfgcmd} set service dns forwarding name-server \<address\> port \<port\>
+
+Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`
+on optional port specified under `<port>`. The port defaults to 53. You can
+configure multiple nameservers here.
+```
+
+
+```{cfgcmd} set service dns forwarding domain \<domain-name\> name-server \<address\>
+
+Forward received queries for a particular domain
+(specified via `domain-name`) to a given nameserver. Multiple nameservers
+can be specified. You can use this feature for a DNS split-horizon
+configuration.
+
+:::{note}
+This also works for reverse-lookup zones (``18.172.in-addr.arpa``).
+:::
+```
+
+
+```{cfgcmd} set service dns forwarding domain \<domain-name\> addnta
+
+Add NTA (negative trust anchor) for this domain. This must be set if the
+domain does not support DNSSEC.
+```
+
+
+```{cfgcmd} set service dns forwarding domain \<domain-name\> recursion-desired
+
+Set the "recursion desired" bit in requests to the upstream nameserver.
+```
+
+
+```{cfgcmd} set service dns forwarding allow-from \<network\>
+
+Given the fact that open DNS recursors could be used on DDoS amplification
+attacks, you must configure the networks which are allowed to use this
+recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and
+IPv6 networks to query this server. This is generally a bad idea.
+```
+
+
+```{cfgcmd} set service dns forwarding dnssec \<off | process-no-validate | process | log-fail | validate\>
+
+The PowerDNS recursor has 5 different levels of DNSSEC processing, which can
+be set with the dnssec setting. In order from least to most processing, these
+are:
+
+* **off** In this mode, no DNSSEC processing takes place. The recursor will
+not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the
+DO and AD bits in queries.
+
+* **process-no-validate** In this mode the recursor acts as a "security
+aware, non-validating" nameserver, meaning it will set the DO-bit on
+outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to
+clients that ask for them (by means of a DO-bit in the query), except for
+zones provided through the auth-zones setting. It will not do any
+validation in this mode, not even when requested by the client.
+
+* **process** When dnssec is set to process the behavior is similar to
+process-no-validate. However, the recursor will try to validate the data
+if at least one of the DO or AD bits is set in the query; in that case,
+it will set the AD-bit in the response when the data is validated
+successfully, or send SERVFAIL when the validation comes up bogus.
+
+* **log-fail** In this mode, the recursor will attempt to validate all data
+it retrieves from authoritative servers, regardless of the client's DNSSEC
+desires, and will log the validation result. This mode can be used to
+determine the extra load and amount of possibly bogus answers before
+turning on full-blown validation. Responses to client queries are the same
+as with process.
+
+* **validate** The highest mode of DNSSEC processing. In this mode, all
+queries will be validated and will be answered with a SERVFAIL in case of
+bogus data, regardless of the client's request.
+
+:::{note}
+The popular Unix/Linux ``dig`` tool sets the AD-bit in the query.
+This might lead to unexpected query results when testing. Set ``+noad``
+on the ``dig`` command line when this is the case.
+:::
+
+:::{note}
+The ``CD``-bit is honored correctly for process and validate. For
+log-fail, failures will be logged too.
+:::
+```
+
+
+```{cfgcmd} set service dns forwarding ignore-hosts-file
+
+Do not use the local ``/etc/hosts`` file in name resolution. VyOS DHCP
+server will use this file to add resolvers to assigned addresses.
+```
+
+
+```{cfgcmd} set service dns forwarding cache-size \<0-2147483647\>
+
+Maximum number of DNS cache entries. 1 million per CPU core will generally
+suffice for most installations.
+
+This defaults to 10000.
+```
+
+
+```{cfgcmd} set service dns forwarding negative-ttl \<0-7200\>
+
+A query for which there is authoritatively no answer is cached to quickly
+deny a record's existence later on, without putting a heavy load on the
+remote server. In practice, caches can become saturated with hundreds of
+thousands of hosts which are tried only once.
+
+This setting, which defaults to 3600 seconds, puts a maximum on the amount
+of time negative entries are cached.
+```
+
+
+```{cfgcmd} set service dns forwarding timeout \<10-60000\>
+
+The number of milliseconds to wait for a remote authoritative server to
+respond before timing out and responding with SERVFAIL.
+
+This setting defaults to 1500 and is valid between 10 and 60000.
+```
+
+
+```{cfgcmd} set service dns forwarding listen-address \<address\>
+
+The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder
+will listen on this address for incoming connections.
+```
+
+
+```{cfgcmd} set service dns forwarding source-address \<address\>
+
+The local IPv4 or IPv6 addresses to use as a source address for sending queries.
+The forwarder will send forwarded outbound DNS requests from this address.
+```
+
+
+```{cfgcmd} set service dns forwarding no-serve-rfc1918
+
+This makes the server authoritatively not aware of: 10.in-addr.arpa,
+168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream
+DNS server(s) to be used for reverse lookups of these zones.
+```
+
+### Authoritative zones
+
+
+The VyOS DNS forwarder can also be configured to host authoritative records for a domain.
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> disable
+
+Disable hosting authoritative zone for `<domain-name>` without deleting from
+configuration.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> disable
+
+Disable specific record without deleting it from configuration.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> ttl \<seconds\>
+
+Set the {abbr}`TTL (Time-to-live)` for the record in seconds. Default is 300 seconds.
+```
+
+#### Record types
+
+
+Below are a list of record types available to be configured within VyOS. Some records
+support special `<name>` keywords:
+
+
+- `@` Use @ as record name to set the record for the root domain.
+- `any` Use any as record name to configure the record as a wildcard.
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records a \<name\> address \<x.x.x.x\>
+
+Set an {abbr}`A (Address)` record. Supports ``@`` and ``any`` keywords.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records aaaa \<name\> address \<h:h:h:h:h:h:h:h\>
+
+Set an {abbr}`AAAA (IPv6 Address)` record. Supports ``@`` and ``any`` keywords.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records cname \<name\> target \<target-domain-name\>
+
+Set an {abbr}`CNAME (Canonical name)` record. Supports ``@`` keyword.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<rule-number\> \<option\> \<value\>
+
+Set an {abbr}`NAPTR (Naming authority pointer)` record. Supports ``@`` keyword.
+NAPTR records support the following options:
+
+* **lookup-a** A Flag.
+
+* **lookup-srv** S flag.
+
+* **order** Rule order. Requires `<value>`.
+
+* **preference** Rule preference. Requires `<value>`. Defaults to 0 if not set.
+
+* **protocol-specific** P flag.
+
+* **regexp** Regular expression. Requires `<value>`.
+
+* **replacement** Replacement DNS name.
+
+* **resolve-uri** U flag.
+
+* **service** Service type. Requires `<value>`.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records ns \<name\> target \<target-name\>
+
+Set an {abbr}`NS (Nameserver)` record.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records ptr \<name\> target \<target-name\>
+
+Set an {abbr}`PTR (Pointer record)` record. Supports ``@`` keyword.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records spf \<name\> value \<value\>
+
+Set an {abbr}`SPF (Sender policy framework)` record. Supports ``@`` keyword.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records srv \<name\> entry \<entry-number\> [hostname | port | priority | weight] \<value\>
+
+Set an {abbr}`SRV (Service)` record. Supports ``@`` keyword.
+```
+
+
+```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records txt \<name\> value \<value\>
+
+Set an {abbr}`TXT (Text)` record. Supports ``@`` keyword.
+```
+
+## Example
+
+
+A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to
+implement a split-horizon DNS configuration for example.com.
+
+
+In this scenario:
+
+
+- All DNS requests for example.com must be forwarded to a DNS server
+  at 192.0.2.254 and 2001:db8:cafe::1
+- All other DNS requests will be forwarded to a different set of DNS servers at
+  192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff
+- The VyOS DNS forwarder will only listen for requests on the eth1 (LAN)
+  interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6
+- The VyOS DNS forwarder will only accept lookup requests from the
+  LAN subnets - 192.168.1.0/24 and 2001:db8::/64
+- The VyOS DNS forwarder will pass reverse lookups for 10.in-addr.arpa,
+  168.192.in-addr.arpa, 16-31.172.in-addr.arpa zones to upstream server.
+
+```none
+set service dns forwarding domain example.com name-server 192.0.2.254
+set service dns forwarding domain example.com name-server 2001:db8:cafe::1
+set service dns forwarding name-server 192.0.2.1
+set service dns forwarding name-server 192.0.2.2
+set service dns forwarding name-server 192.0.2.3 port 853
+set service dns forwarding name-server 2001:db8::1:ffff
+set service dns forwarding name-server 2001:db8::2:ffff
+set service dns forwarding name-server 2001:db8::3:ffff port 8053
+set service dns forwarding listen-address 192.168.1.254
+set service dns forwarding listen-address 2001:db8::ffff
+set service dns forwarding allow-from 192.168.1.0/24
+set service dns forwarding allow-from 2001:db8::/64
+set service dns forwarding no-serve-rfc1918
+```
+
+## Operation
+
+```{opcmd} reset dns forwarding \<all | domain\>
+
+Resets the local DNS forwarding cache database. You can reset the cache
+for all entries or only for entries to a specific domain.
+```
+
+
+```{opcmd} restart dns forwarding
+
+Restarts the DNS recursor process. This also invalidates the local DNS
+forwarding cache.
+```
+
+(dynamic-dns)=
+
+# Dynamic DNS
+
+VyOS is able to update a remote DNS record when an interface gets a new IP
+address. In order to do so, VyOS includes [ddclient], a Perl script written for
+this only one purpose.
+
+[ddclient] uses two methods to update a DNS record. The first one will send
+updates directly to the DNS daemon, in compliance with {rfc}`2136`. The second
+one involves a third party service, like DynDNS.com or any other such
+service provider. This method uses HTTP requests to transmit the new IP address.
+You can configure both in VyOS.
+(dns-dynamic-config)=
+
+## Configuration
+### {rfc}`2136` Based
+
+```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\>
+
+   Create new dynamic DNS update configuration which will update the IP
+   address assigned to `<interface>` on the service you configured under
+   `<service-name>`.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\>
+
+Set description `<text>` for dynamic DNS service being configured.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> key \<filename\>
+
+File identified by `<filename>` containing the TSIG authentication key for RFC2136
+nsupdate on remote DNS server.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\>
+
+Configure the DNS `<server>` IP/FQDN used when updating this dynamic
+assignment.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> zone \<zone\>
+
+Configure DNS `<zone>` to be updated.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<record\>
+
+Configure DNS `<record>` which should be updated. This can be set multiple times.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> ttl \<ttl\>
+
+Configure optional TTL value on the given resource record. This defaults to
+600 seconds.
+```
+
+
+```{cfgcmd} set service dns dynamic interval \<60-3600\>
+
+Specify interval in seconds to wait between Dynamic DNS updates.
+The default is  300 seconds.
+```
+
+(dns-dynamic-example)=
+
+
+#### Example
+
+
+- Register DNS record `example.vyos.io` on DNS server `ns1.vyos.io`
+- Use auth key file at `/config/auth/my.key`
+- Set TTL to 300 seconds
+
+```none
+# Configuration commands entered:
+#
+set service dns dynamic name 'VyOS-DNS' address interface 'eth0'
+set service dns dynamic name 'VyOS-DNS' description 'RFC 2136 dynamic dns service'
+set service dns dynamic name 'VyOS-DNS' key '/config/auth/my.key'
+set service dns dynamic name 'VyOS-DNS' server 'ns1.vyos.io'
+set service dns dynamic name 'VyOS-DNS' zone 'vyos.io'
+set service dns dynamic name 'VyOS-DNS' host-name 'example.vyos.io'
+set service dns dynamic name 'VyOS-DNS' protocol 'nsupdate'
+set service dns dynamic name 'VyOS-DNS' ttl '300'
+
+# Resulting config:
+#
+vyos@vyos# show service dns dynamic
+ name VyOS-DNS {
+     address {
+         interface eth0
+     }
+     description "RFC 2136 dynamic dns service"
+     host-name example.vyos.io
+     key /config/auth/my.key
+     protocol nsupdate
+     server ns1.vyos.io
+     ttl 300
+     zone vyos.io
+ }
+```
+
+This will render the following [ddclient] configuration entry:
+
+```none
+# ddclient configuration for interface "eth0":
+#
+
+# Web service dynamic DNS configuration for VyOS-DNS: [nsupdate, example.vyos.io]
+use=if, \
+if=eth0, \
+protocol=nsupdate, \
+server=ns1.vyos.io, \
+zone=vyos.io, \
+password='/config/auth/my.key', \
+ttl=300 \
+example.vyos.io
+```
+
+:::{note}
+You can also keep different DNS zone updated. Just create a new
+config node: `set service dns dynamic interface <interface> rfc2136
+<other-service-name>`
+:::
+
+
+### HTTP based services
+
+
+VyOS is also able to use any service relying on protocols supported by ddclient.
+
+
+To use such a service, one must define a login, password, one or multiple
+hostnames, protocol and server.
+
+```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\>
+
+Create new dynamic DNS update configuration which will update the IP
+address assigned to `<interface>` on the service you configured under
+`<service-name>`.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\>
+
+Set description `<text>` for dynamic DNS service being configured.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<hostname\>
+
+Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS
+provider identified by `<service-name>`.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> username \<username\>
+
+Configure `<username>` used when authenticating the update request for
+DynDNS service identified by `<service-name>`.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> password \<password\>
+
+Configure `<password>` used when authenticating the update request for
+DynDNS service identified by `<service-name>`.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> protocol \<protocol\>
+
+When a ``custom`` DynDNS provider is used, the protocol used for communicating
+to the provider must be specified under `<protocol>`. See the embedded
+completion helper when entering above command for available protocols.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\>
+
+When a ``custom`` DynDNS provider is used the `<server>` where update
+requests are being sent to must be specified.
+```
+
+
+```{cfgcmd} set service dns dynamic name \<service-name\> ip-version 'ipv6'
+
+Allow explicit IPv6 address for the interface.
+```
+
+#### Example:
+
+Use deSEC (dedyn.io) as your preferred provider:
+
+```none
+set service dns dynamic name dedyn description 'deSEC dynamic dns service'
+set service dns dynamic name dedyn username 'myusername'
+set service dns dynamic name dedyn password 'mypassword'
+set service dns dynamic name dedyn host-name 'myhostname.dedyn.io'
+set service dns dynamic name dedyn protocol 'dyndns2'
+set service dns dynamic name dedyn server 'update.dedyn.io'
+set service dns dynamic name dedyn address interface 'eth0'
+```
+
+:::{note}
+Multiple services can be used per interface. Just specify as many
+services per interface as you like!
+:::
+#### Example IPv6 only:
+
+```none
+set service dns dynamic name dedyn description 'deSEC ipv6 dynamic dns service'
+set service dns dynamic name dedyn username 'myusername'
+set service dns dynamic name dedyn password 'mypassword'
+set service dns dynamic name dedyn host-name 'myhostname.dedyn.io'
+set service dns dynamic name dedyn protocol 'dyndns2'
+set service dns dynamic name dedyn ip-version 'ipv6'
+set service dns dynamic name dedyn server 'update6.dedyn.io'
+set service dns dynamic name dedyn address interface 'eth0'
+```
+
+### Running Behind NAT
+
+By default, [ddclient] will update a dynamic dns record using the IP address
+directly attached to the interface. If your VyOS instance is behind NAT, your
+record will be updated to point to your internal IP.
+
+[ddclient] has another way to determine the WAN IP address. This is controlled
+by:
+
+```{cfgcmd} set service dns dynamic name \<service-name\> address web \<url\>
+
+Use configured `<url>` to determine your IP address. [ddclient] will load
+`<url>` and tries to extract your IP address from the response.
+```
+```{cfgcmd} set service dns dynamic name \<service-name\> address web skip \<pattern\>
+
+ddclient will skip any address located before the string set in `<pattern>`.
+```
+
+[ddclient]: https://github.com/ddclient/ddclient
diff --git a/docs/configuration/service/eventhandler.md b/docs/configuration/service/eventhandler.md
new file mode 100644
index 00000000..6413c24d
--- /dev/null
+++ b/docs/configuration/service/eventhandler.md
@@ -0,0 +1,129 @@
+(event-handler)=
+
+# Event Handler
+
+## Event Handler Technology Overview
+
+Event handler allows you to execute scripts when a string that matches
+a regex or a regex with a service name appears in journald logs. You
+can pass variables, arguments, and a full matching string to the script.
+
+## How to configure Event Handler
+
+> [1. Create an event handler](#create-an-event-handler)
+>
+> [2. Add regex to the script](#add-regex-to-the-script)
+>
+> [3. Add a full path to the script](#add-a-full-path-to-the-script)
+>
+> [4. Add optional parameters](#add-optional-parameters)
+
+## Event Handler Configuration Steps
+
+### 1. Create an event handler
+
+```{cfgcmd} set service event-handler event \<event-handler name\>
+
+This is an optional command because the event handler will be
+automatically created after any of the next commands.
+```
+
+
+### 2. Add regex to the script
+
+```{cfgcmd} set service event-handler event \<event-handler name\> filter pattern \<regex\>
+
+This is a mandatory command. Sets regular expression to match
+against log string message.
+
+:::{note}
+The regular expression matches if and only if the entire
+string matches the pattern.
+:::
+```
+
+
+### 3. Add a full path to the script
+
+```{cfgcmd} set service event-handler event \<event-handler name\> script path \<path to script\>
+
+This is a mandatory command. Sets the full path to the script.
+The script file must be executable.
+```
+
+
+### 4. Add optional parameters
+
+```{cfgcmd} set service event-handler event \<event-handler name\> filter syslog-identifier \<syslogid name\>
+
+This is an optional command. Filters log messages by
+syslog-identifier.
+```
+
+```{cfgcmd} set service event-handler event \<event-handler name\> script environment \<env name\> value \<env value\>
+
+This is an optional command. Adds environment and its value to
+the script. Use separate commands for each environment.
+
+One implicit environment exists.
+
+* ``message``: Full message that has triggered the script.
+```
+
+```{cfgcmd} set service event-handler event \<event-handler name\> script arguments \<arguments\>
+
+This is an optional command. Adds arguments to the script.
+Arguments must be separated by spaces.
+
+:::{note}
+We don't recommend using arguments. Using environment variables is preferable.
+:::
+```
+
+
+## Example
+
+Event handler that monitors the state of interface eth0.
+
+```none
+set service event-handler event INTERFACE_STATE_DOWN filter pattern '.*eth0.*,RUNNING,.*->.*'
+set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd'
+set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down'
+set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth0'
+set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py'
+```
+
+Event handler script
+
+```none
+#!/usr/bin/env python3
+#
+# VyOS event-handler script example
+from os import environ
+import subprocess
+from sys import exit
+
+# Perform actions according to requirements
+def process_event() -> None:
+    # Get variables
+    message_text = environ.get('message')
+    interface_name = environ.get('interface_name')
+    interface_action = environ.get('interface_action')
+    # Print the message that triggered this script
+    print(f'Logged message: {message_text}')
+    # Prepare a command to run
+    command = f'sudo ip link set {interface_name} {interface_action}'.split()
+    # Execute a command
+    subprocess.run(command)
+
+if __name__ == '__main__':
+    try:
+        # Run script actions and exit
+        process_event()
+        exit(0)
+    except Exception as err:
+        # Exit properly in case if something in the script goes wrong
+        print(f'Error running script: {err}')
+        exit(1)
+```
+
diff --git a/docs/configuration/service/https.md b/docs/configuration/service/https.md
new file mode 100644
index 00000000..184fd088
--- /dev/null
+++ b/docs/configuration/service/https.md
@@ -0,0 +1,138 @@
+(http-api)=
+
+# HTTP API
+
+VyOS provide an HTTP API. You can use it to execute op-mode commands,
+update VyOS, set or delete config.
+
+Please take a look at the {ref}`vyosapi` page for an detailed how-to.
+
+## Configuration
+
+```{cfgcmd} set service https allow-client address \<address\>
+
+Only allow certain IP addresses or prefixes to access the https
+webserver.
+```
+
+```{cfgcmd} set service https certificates ca-certificate \<name\>
+
+Use CA certificate from PKI subsystem
+```
+
+```{cfgcmd} set service https certificates certificate \<name\>
+
+Use certificate from PKI subsystem
+```
+
+```{cfgcmd} set service https certificates dh-params \<name\>
+
+Use {abbr}`DH (Diffie–Hellman)` parameters from PKI subsystem.
+Must be at least 2048 bits in length.
+```
+
+```{cfgcmd} set service https listen-address \<address\>
+
+Webserver should only listen on specified IP address
+```
+
+```{cfgcmd} set service https port \<number\>
+
+Webserver should listen on specified port.
+
+Default: 443
+```
+
+```{cfgcmd} set service https enable-http-redirect
+
+Enable automatic redirect from http to https.
+```
+
+```{cfgcmd} set service https tls-version \<1.2 | 1.3\>
+
+Select TLS version used.
+
+This defaults to both 1.2 and 1.3.
+```
+
+```{cfgcmd} set service https vrf \<name\>
+
+Start Webserver in given VRF.
+```
+
+```{cfgcmd} set service https request-body-size-limit \<size\>
+
+Set the maximum request body size in megabytes. Default is 1MB.
+```
+
+
+### API
+
+```{cfgcmd} set service https api keys id \<name\> key \<apikey\>
+
+Set a named api key. Every key has the same, full permissions
+on the system.
+```
+
+
+### REST
+
+```{cfgcmd} set service https api rest
+
+Enable REST API
+```
+
+```{cfgcmd} set service https api rest debug
+
+To enable debug messages. Available via {opcmd}`show log` or
+{opcmd}`monitor log`
+```
+
+```{cfgcmd} set service https api rest strict
+
+Enforce strict path checking.
+```
+
+
+### GraphQL
+
+```{cfgcmd} set service https api graphql introspection
+
+Enable GraphQL Schema introspection.
+```
+
+:::{note}
+Do not leave introspection enabled in production, it is a security risk.
+:::
+
+```{cfgcmd} set service https api graphql authentication type \<key | token\>
+
+Set the authentication type for GraphQL, default option is key. Available options are:
+* ``key`` use API keys configured in ``service https api keys``
+* ``token`` use JWT tokens.
+```
+
+```{cfgcmd} set service https api graphql authentication expiration
+
+Set the lifetime for JWT tokens in seconds. Default is 3600 seconds.
+```
+
+```{cfgcmd} set service https api graphql authentication secret-length
+
+Set the byte length of the JWT secret. Default is 32.
+```
+
+```{cfgcmd} set service https api graphql cors allow-origin \<origin\>
+
+Allow cross-origin requests from \<origin\>.
+```
+
+
+## Example Configuration
+
+Setting REST API and an API-KEY is the minimal configuration to get a working API Endpoint.
+
+```none
+set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY
+set service https api rest
+```
diff --git a/docs/configuration/service/index.md b/docs/configuration/service/index.md
new file mode 100644
index 00000000..4018c5be
--- /dev/null
+++ b/docs/configuration/service/index.md
@@ -0,0 +1,29 @@
+# Service
+
+```{toctree}
+:includehidden: true
+:maxdepth: 1
+
+broadcast-relay
+config-sync
+conntrack-sync
+console-server
+dhcp-relay
+dhcp-server
+dns
+eventhandler
+https
+ipoe-server
+lldp
+mdns
+monitoring
+ntp
+pppoe-server
+router-advert
+salt-minion
+snmp
+ssh
+tftp-server
+webproxy
+suricata
+```
diff --git a/docs/configuration/service/ipoe-server.md b/docs/configuration/service/ipoe-server.md
new file mode 100644
index 00000000..f1ef2a63
--- /dev/null
+++ b/docs/configuration/service/ipoe-server.md
@@ -0,0 +1,512 @@
+(ipoe-server)=
+
+# IPoE Server
+
+VyOS utilizes [accel-ppp] to provide {abbr}`IPoE (Internet Protocol over
+Ethernet)` server functionality. It can be used with local authentication
+(mac-address) or a connected RADIUS server.
+
+IPoE is a method of delivering an IP payload over an Ethernet-based access
+network or an access network using bridged Ethernet over Asynchronous Transfer
+Mode (ATM) without using PPPoE. It directly encapsulates the IP datagrams in
+Ethernet frames, using the standard {rfc}`894` encapsulation.
+
+The use of IPoE addresses the disadvantage that PPP is unsuited for multicast
+delivery to multiple users. Typically, IPoE uses Dynamic Host Configuration
+Protocol and Extensible Authentication Protocol to provide the same
+functionality as PPPoE, but in a less robust manner.
+
+:::{note}
+Please be aware, due to an upstream bug, config changes/commits
+will restart the ppp daemon and will reset existing IPoE sessions,
+in order to become effective.
+:::
+
+## Configuring IPoE Server
+
+IPoE can be configured on different interfaces, it will depend on each specific
+situation which interface will provide IPoE to clients. The client's mac address
+and the incoming interface is being used as control parameter, to authenticate
+a client.
+
+The example configuration below will assign an IP to the client on the incoming
+interface eth1 with the client mac address 00:50:79:66:68:00. Other DHCP
+discovery requests will be ignored, unless the client mac has been enabled in
+the configuration.
+
+```none
+set interfaces ethernet eth1 address '192.168.0.1/24'
+set service ipoe-server authentication interface eth1.100 mac 00:50:79:66:68:00
+set service ipoe-server authentication interface eth1.101 mac 00:50:79:66:68:01
+set service ipoe-server authentication mode 'local'
+set service ipoe-server client-ip-pool IPOE-POOL range '192.168.0.2-192.168.0.254'
+set service ipoe-server default-pool 'IPOE-POOL'
+set service ipoe-server gateway-address '192.168.0.1/24'
+set service ipoe-server interface eth1 mode 'l2'
+set service ipoe-server interface eth1 network 'vlan'
+set service ipoe-server interface eth1 vlan '100-200'
+```
+
+```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\>
+
+Creates local IPoE user with username=\*\*\<interface\>\*\* and
+password=\*\*\<MAC\>\*\* (mac-address)
+```
+
+
+```{cfgcmd} set service ipoe-server authentication mode \<local | radius\>
+
+Set authentication backend. The configured authentication backend is used
+for all queries.
+
+* **radius**: All authentication queries are handled by a configured RADIUS
+server.
+* **local**: All authentication queries are handled locally.
+* **noauth**: Authentication disabled
+```
+
+
+```{cfgcmd} set service ipoe-server client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\>
+
+Use this command to define the first IP address of a pool of
+addresses to be given to IPoE clients. If notation ``x.x.x.x-x.x.x.x``,
+it must be within a /24 subnet. If notation ``x.x.x.x/x`` is
+used there is possibility to set host/netmask.
+```
+
+
+```{cfgcmd} set service ipoe-server default-pool \<POOL-NAME\>
+
+Use this command to define default address pool name.
+```
+
+
+```{cfgcmd} set service ipoe-server gateway-address \<x.x.x.x/x\>
+
+Specifies address to be used as server ip address if radius can assign
+only client address. In such case if client address is matched network
+and mask then specified address and mask will be used. You can specify
+multiple such options.
+```
+
+
+```{cfgcmd} set service ipoe-server interface \<interface\> mode \<l2 | l3\>
+
+> Specifies the client connectivity mode.
+
+* **l2**: It means that clients are on same network where interface
+is.\*\*(default)\*\*
+* **l3**: It means that client are behind some router.
+```
+
+
+```{cfgcmd} set service ipoe-server interface \<interface\> network \<shared | vlan\>
+
+Specify where interface is shared by multiple users or it is vlan-per-user.
+
+* **shared**: Multiple clients share the same network. **(default)**
+* **vlan**: One VLAN per client.
+```
+
+
+```none
+vyos@vyos:~$ show ipoe-server sessions
+
+ ifname | username |    calling-sid    |     ip      | rate-limit | type | comp | state  |  uptime
+--------+----------+-------------------+-------------+------------+------+------+--------+----------
+ ipoe0  | eth1.100 | 00:50:79:66:68:00 | 192.168.0.2 |            | ipoe |      | active | 00:04:55
+ ipoe1  | eth1.101 | 00:50:79:66:68:01 | 192.168.0.3 |            | ipoe |      | active | 00:04:44
+```
+
+## Configuring RADIUS authentication
+
+
+To enable RADIUS based authentication, the authentication mode needs to be
+changed within the configuration. Previous settings like the local users, still
+exists within the configuration, however they are not used if the mode has been
+changed from local to radius. Once changed back to local, it will use all local
+accounts again.
+
+```none
+set service ipoe-server authentication mode radius
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius server \<server\> key \<secret\>
+
+Configure RADIUS *\<server\>* and its required shared *\<secret\>* for
+communicating with the RADIUS server.
+```
+
+Since the RADIUS server would be a single point of failure, multiple RADIUS
+servers can be setup and will be used subsequentially.
+For example:
+
+```none
+set service ipoe-server authentication radius server 10.0.0.1 key 'foo'
+set service ipoe-server authentication radius server 10.0.0.2 key 'foo'
+```
+
+:::{note}
+Some RADIUS severs use an access control list which allows or denies
+queries, make sure to add your VyOS router to the allowed client list.
+:::
+
+
+### RADIUS source address
+
+
+If you are using OSPF as IGP, always the closest interface connected to the
+RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests
+to a single source IP e.g. the loopback interface.
+
+```{cfgcmd} set service ipoe-server authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queries.
+```
+
+:::{note}
+The ``source-address`` must be configured on one of VyOS interface.
+Best practice would be a loopback or dummy interface.
+:::
+
+
+### RADIUS advanced options
+
+```{cfgcmd} set service ipoe-server authentication radius server \<server\> port \<port\>
+
+Configure RADIUS *\<server\>* and its required port for authentication requests.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius server \<server\> fail-time \<time\>
+
+Mark RADIUS server as offline for this given *\<time\>* in seconds.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius server \<server\> disable
+
+Temporary disable this RADIUS server.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius acct-timeout \<timeout\>
+
+Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius dynamic-author server \<address\>
+
+Specifies IP address for Dynamic Authorization Extension server (DM/CoA).
+This IP must exist on any VyOS interface or it can be ``0.0.0.0``.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius dynamic-author port \<port\>
+
+UDP port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius dynamic-author key \<secret\>
+
+Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius max-try \<number\>
+
+Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius timeout \<timeout\>
+
+Timeout to wait response from server (seconds)
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius nas-identifier \<identifier\>
+
+Value to send to RADIUS server in NAS-Identifier attribute and to be matched
+in DM/CoA requests.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius nas-ip-address \<address\>
+
+Value to send to RADIUS server in NAS-IP-Address attribute and to be matched
+in DM/CoA requests. Also DM/CoA server will bind to that address.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queries.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius rate-limit attribute \<attribute\>
+
+Specifies which RADIUS server attribute contains the rate limit information.
+The default attribute is *Filter-Id*.
+```
+
+:::{note}
+If you set a custom RADIUS attribute you must define it on both
+dictionaries at RADIUS server and client.
+:::
+
+```{cfgcmd} set service ipoe-server authentication radius rate-limit enable
+
+Enables bandwidth shaping via RADIUS.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication radius rate-limit vendor
+
+Specifies the vendor dictionary, dictionary needs to be in
+/usr/share/accel-ppp/radius.
+```
+
+Received RADIUS attributes have a higher priority than parameters defined within
+the CLI configuration, refer to the explanation below.
+
+
+### Allocation clients ip addresses by RADIUS
+
+
+If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP
+address will be allocated to the client and the option ``default-pool`` within the CLI
+config is being ignored.
+
+
+If the RADIUS server sends the attribute ``Framed-Pool``, IP address will be allocated
+from a predefined IP pool whose name equals the attribute value.
+
+
+If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, IPv6 address
+will be allocated from a predefined IPv6 pool ``prefix`` whose name equals the attribute value.
+
+
+If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, IPv6
+delegation prefix will be allocated from a predefined IPv6 pool ``delegate``
+whose name equals the attribute value.
+
+
+:::{note}
+``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in
+RFC6911. If they are not defined in your RADIUS server, add new [dictionary].
+:::
+
+
+User interface can be put to VRF context via RADIUS Access-Accept packet, or change
+it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. It is custom [ACCEL-PPP attribute].
+Define it in your RADIUS server.
+
+
+## IPv6
+
+```{cfgcmd} set service ipoe-server client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\>  mask \<number-of-bits\>
+
+Use this command to set the IPv6 address pool from which an IPoE client
+will get an IPv6 prefix of your defined length (mask) to terminate the
+IPoE endpoint at their side. The mask length can be set from 48 to 128
+bit long, the default value is 64.
+```
+
+
+```{cfgcmd} set service ipoe-server client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\>  delegation-prefix \<number-of-bits\>
+
+Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on
+IPoE. You will have to set your IPv6 pool and the length of the
+delegation prefix. From the defined IPv6 pool you will be handing out
+networks of the defined length (delegation-prefix). The length of the
+delegation prefix can be set from 32 to 64 bit long.
+```
+
+
+```{cfgcmd} set service ipoe-server default-ipv6-pool \<IPv6-POOL-NAME\>
+
+Use this command to define default IPv6 address pool name.
+```
+
+
+```none
+set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56'
+set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64'
+set service ipoe-server default-ipv6-pool IPv6-POOL
+```
+
+## Scripting
+
+```{cfgcmd} set service ipoe-server extended-scripts on-change \<path_to_script\>
+
+Script to run when session interface changed by RADIUS CoA handling
+```
+
+
+```{cfgcmd} set service ipoe-server extended-scripts on-down \<path_to_script\>
+
+Script to run when session interface going to terminate
+```
+
+
+```{cfgcmd} set service ipoe-server extended-scripts on-pre-up \<path_to_script\>
+
+Script to run before session interface comes up
+```
+
+
+```{cfgcmd} set service ipoe-server extended-scripts on-up \<path_to_script\>
+
+Script to run when session interface is completely configured and started
+```
+
+## Advanced Options
+
+
+### Authentication Advanced Options
+
+```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> vlan  \<vlan-id\>
+
+VLAN monitor for automatic creation of VLAN interfaces for specific user on specific \<interface\>
+```
+
+
+```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit  download \<bandwidth\>
+
+Download bandwidth limit in kbit/s for user on interface *\<interface\>*.
+```
+
+
+```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit  upload \<bandwidth\>
+
+Upload bandwidth limit in kbit/s for for user on interface *\<interface\>*.
+```
+
+### Client IP Pool Advanced Options
+
+```{cfgcmd} set service ipoe-server client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\>
+
+Use this command to define the next address pool name.
+```
+
+### Advanced Interface Options
+
+```{cfgcmd} set service ipoe-server interface \<interface\> client-subnet \<x.x.x.x/x\>
+
+Specify local range of ip address to give to dhcp clients. First IP in range is router IP.
+If you need more customization use *client-ip-pool*
+```
+
+
+```{cfgcmd} set service ipoe-server interface \<interface\> external-dhcp dhcp-relay \<x.x.x.x\>
+
+Specify DHCPv4 relay IP address to pass requests to. If specified giaddr is also needed.
+```
+
+
+```{cfgcmd} set service ipoe-server interface \<interface\> external-dhcp giaddr \<x.x.x.x\>
+
+Specifies relay agent IP addre
+```
+
+### Global Advanced options
+
+```{cfgcmd} set service ipoe-server description \<description\>
+
+Set description.
+```
+```{cfgcmd} set service ipoe-server limits burst \<value\>
+
+Burst count
+```
+```{cfgcmd} set service ipoe-server limits connection-limit \<value\>
+
+Acceptable rate of connections (e.g. 1/min, 60/sec)
+```
+```{cfgcmd} set service ipoe-server limits timeout \<value\>
+
+Timeout in seconds
+```
+```{cfgcmd} set service ipoe-server max-concurrent-sessions
+
+Maximum number of concurrent session start attempts
+```
+```{cfgcmd} set service ipoe-server name-server \<address\>
+
+Connected client should use *\<address\>* as their DNS server. This
+command accepts both IPv4 and IPv6 addresses. Up to two nameservers
+can be configured for IPv4, up to three for IPv6.
+```
+```{cfgcmd} set service ipoe-server shaper fwmark \<1-2147483647\>
+
+Match firewall mark value
+```
+```{cfgcmd} set service ipoe-server snmp master-agent
+
+Enable SNMP
+```
+
+## Monitoring
+
+```{opcmd} show ipoe-server sessions
+
+Use this command to locally check the active sessions in the IPoE
+server.
+```
+```none
+vyos@vyos:~$ show ipoe-server sessions
+ifname  | username |    calling-sid    |     ip      | rate-limit | type | comp | state  |  uptime
+----------+----------+-------------------+-------------+------------+------+------+--------+----------
+ eth1.100 | eth1.100 | 0c:98:bd:b8:00:01 | 192.168.0.3 |            | ipoe |      | active | 03:03:58
+```
+
+```none
+vyos@vyos:~$ show ipoe-server statistics
+uptime: 0.03:31:36
+cpu: 0%
+mem(rss/virt): 6044/101360 kB
+core:
+  mempool_allocated: 148628
+  mempool_available: 144748
+  thread_count: 1
+  thread_active: 1
+  context_count: 10
+  context_sleeping: 0
+  context_pending: 0
+  md_handler_count: 6
+  md_handler_pending: 0
+  timer_count: 1
+  timer_pending: 0
+sessions:
+  starting: 0
+  active: 1
+  finishing: 0
+ipoe:
+  starting: 0
+  active: 1
+  delayed: 0
+```
+
+## Troubleshooting
+
+```none
+vyos@vyos:~$ show log ipoe-server
+
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:: recv [DHCPv4 Discover xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Discover> <Request-IP 192.168.0.3> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>]
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: eth1.100: authentication succeeded
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Offer xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Offer> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>]
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: recv [DHCPv4 Request xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Request> <Server-ID 192.168.0.1> <Request-IP 192.168.0.4> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>]
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: activate session
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: no free IPv6 address
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: session started
+Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Ack xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Ack> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>]
+```
+
+[accel-ppp]: https://accel-ppp.org/
+[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
+[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911
diff --git a/docs/configuration/service/lldp.md b/docs/configuration/service/lldp.md
new file mode 100644
index 00000000..7fdba6c8
--- /dev/null
+++ b/docs/configuration/service/lldp.md
@@ -0,0 +1,154 @@
+(lldp)=
+
+# LLDP
+
+{abbr}`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer
+protocol in the Internet Protocol Suite used by network devices for advertising
+their identity, capabilities, and neighbors on an IEEE 802 local area network,
+principally wired Ethernet. The protocol is formally referred to by the IEEE
+as Station and Media Access Control Connectivity Discovery specified in IEEE
+802.1AB and IEEE 802.3-2012 section 6 clause 79.
+
+LLDP performs functions similar to several proprietary protocols, such as
+{abbr}`CDP (Cisco Discovery Protocol)`,
+{abbr}`FDP (Foundry Discovery Protocol)`,
+{abbr}`NDP (Nortel Discovery Protocol)` and {abbr}`LLTD (Link Layer Topology
+Discovery)`.
+
+Information gathered with LLDP is stored in the device as a {abbr}`MIB
+(Management Information Database)` and can be queried with {abbr}`SNMP (Simple
+Network Management Protocol)` as specified in {rfc}`2922`. The topology of an
+LLDP-enabled network can be discovered by crawling the hosts and querying this
+database. Information that may be retrieved include:
+
+- System Name and Description
+- Port name and description
+- VLAN name
+- IP management address
+- System capabilities (switching, routing, etc.)
+- MAC/PHY information
+- MDI power
+- Link aggregation
+
+## Configuration
+
+```{cfgcmd} set service lldp
+
+Enable LLDP service
+```
+
+```{cfgcmd} set service lldp management-address \<address\>
+
+Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses
+can be defined. Only addresses connected to the system will be transmitted.
+```
+
+```{cfgcmd} set service lldp interface \<interface\>
+
+Enable transmission of LLDP information on given \<interface\>. You can also
+say ``all`` here so LLDP is turned on on every interface.
+```
+
+```{cfgcmd} set service lldp interface \<interface\> mode [disable|rx-tx|rx|tx]
+
+Configure the administrative status of the given port.
+
+By default, all ports are configured to be in rx-tx mode. This means they
+can receive and transmit LLDP frames.
+
+In rx mode, they won't emit any frames. In tx mode, they won't receive
+any frames. In disabled mode, no frame will be sent and any incoming frame
+will be discarded.
+```
+
+```{cfgcmd} set service lldp snmp
+
+Enable SNMP queries of the LLDP database
+```
+
+```{cfgcmd} set service lldp legacy-protocols \<cdp|edp|fdp|sonmp\>
+
+Enable given legacy protocol on this LLDP instance. Legacy protocols include:
+* ``cdp`` - Listen for CDP for Cisco routers/switches
+* ``edp`` - Listen for EDP for Extreme routers/switches
+* ``fdp`` - Listen for FDP for Foundry routers/switches
+* ``sonmp`` - Listen for SONMP for Nortel routers/switches
+```
+
+
+## Operation
+
+```{opcmd} show lldp neighbors
+
+Displays information about all neighbors discovered via LLDP.
+
+:::{code-block} none
+vyos@vyos:~$ show lldp neighbors
+Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station
+                  D - Docsis, T - Telephone, O - Other
+
+Device ID                 Local     Proto  Cap   Platform             Port ID
+---------                 -----     -----  ---   --------             -------
+BR2.vyos.net              eth0      LLDP   R     VyOS 1.2.4           eth1
+BR3.vyos.net              eth0      LLDP   RB    VyOS 1.2.4           eth2
+SW1.vyos.net              eth0      LLDP   B     Cisco IOS Software   GigabitEthernet0/6
+:::
+```
+
+```{opcmd} show lldp neighbors detail
+
+Get detailed information about LLDP neighbors.
+
+:::{code-block} none
+vyos@vyos:~$ show lldp neighbors detail
+-------------------------------------------------------------------------------
+LLDP neighbors:
+-------------------------------------------------------------------------------
+Interface:    eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33
+Chassis:
+  ChassisID:    mac 00:53:00:01:02:c9
+  SysName:      BR2.vyos.net
+  SysDescr:     VyOS 1.3-rolling-201912230217
+  MgmtIP:       192.0.2.1
+  MgmtIP:       2001:db8::ffff
+  Capability:   Bridge, on
+  Capability:   Router, on
+  Capability:   Wlan, off
+  Capability:   Station, off
+Port:
+  PortID:       mac 00:53:00:01:02:c9
+  PortDescr:    eth0
+  TTL:          120
+  PMD autoneg:  supported: no, enabled: no
+      MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable
+VLAN:         201 eth0.201
+VLAN:         205 eth0.205
+LLDP-MED:
+  Device Type:  Network Connectivity Device
+  Capability:   Capabilities, yes
+  Capability:   Policy, yes
+  Capability:   Location, yes
+  Capability:   MDI/PSE, yes
+  Capability:   MDI/PD, yes
+  Capability:   Inventory, yes
+  Inventory:
+      Hardware Revision: None
+      Software Revision: 4.19.89-amd64-vyos
+      Firmware Revision: 6.00
+      Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7
+      Manufacturer: VMware, Inc.
+      Model:        VMware Virtual Platform
+      Asset ID:     No Asset Tag
+-------------------------------------------------------------------------------
+:::
+```
+
+```{opcmd} show lldp neighbors interface \<interface\>
+
+Show LLDP neighbors connected via interface \<interface\>.
+```
+
+```{opcmd} show log lldp
+
+Used for troubleshooting.
+```
\ No newline at end of file
diff --git a/docs/configuration/service/mdns.md b/docs/configuration/service/mdns.md
new file mode 100644
index 00000000..088bca3c
--- /dev/null
+++ b/docs/configuration/service/mdns.md
@@ -0,0 +1,131 @@
+# mDNS Repeater
+
+Starting with VyOS 1.2 a {abbr}`mDNS (Multicast DNS)` repeater functionality is
+provided. Additional information can be obtained from
+<https://en.wikipedia.org/wiki/Multicast_DNS>.
+
+Multicast DNS uses the reserved address `224.0.0.251`, which is
+"administratively scoped" and does not leave the subnet. mDNS repeater
+retransmits mDNS packets from one interface to other interfaces. This enables
+support for devices using mDNS discovery (like network printers, Apple Airplay,
+Chromecast, various IP based home-automation devices etc) across multiple VLANs.
+
+Since the mDNS protocol sends the {abbr}`AA(Authoritative Answer)` records in
+the packet itself, the repeater does not need to forge the source address.
+Instead, the source address is of the interface that repeats the packet.
+
+:::{note}
+You can not run this in a VRRP setup, if multiple mDNS repeaters
+are launched in a subnet you will experience the mDNS packet storm death!
+:::
+
+## Configuration
+
+```{cfgcmd} set service mdns repeater interface \<interface\>
+
+To enable mDNS repeater you need to configure at least two interfaces so that
+all incoming mDNS packets from one interface configured here can be
+re-broadcasted to any other interface(s) configured under this section.
+```
+
+```{cfgcmd} set service mdns repeater disable
+
+mDNS repeater can be temporarily disabled without deleting the service using
+```
+
+```{cfgcmd} set service mdns repeater ip-version \<ipv4 | ipv6 | both\>
+
+mDNS repeater can be enabled either on IPv4 socket or on IPv6 socket or both
+to re-broadcast. By default, mDNS repeater will listen on both IPv4 and IPv6.
+```
+
+```{cfgcmd} set service mdns repeater allow-service \<service\>
+
+mDNS repeater can be configured to re-broadcast only specific services. By
+default, all services are re-broadcasted.
+```
+
+```{cfgcmd} set service mdns repeater browse-domain \<domain\>
+
+Allow listing additional custom domains to be browsed (in addition to the
+default ``local``) so that they can be reflected.
+```
+
+```{cfgcmd} set service mdns repeater cache-entries \<entries\>
+
+Specify how many resource records are cached per interface. Bigger values
+allow mDNS work correctly in large LANs but also increase memory consumption.
+
+Defaults to: 4096
+```
+
+
+## Firewall recommendations
+
+Unlike typical routed traffic, mDNS packets relayed between interfaces do not
+traverse the FORWARD hook chain in the firewall. Instead, they are processed
+through the following hooks:
+> - **INPUT**: For packets received by the local system
+> - **OUTPUT**: For packets sent from the local system
+
+To control or allow mDNS packet forwarding via the relay, you must define
+appropriate rules in the INPUT and OUTPUT directions. Rules in the FORWARD
+direction will have no effect on mDNS relay traffic.
+
+```none
+set firewall ipv4 input filter rule 10 action 'accept'
+set firewall ipv4 input filter rule 10 destination address '224.0.0.251'
+set firewall ipv4 input filter rule 10 destination port '5353'
+set firewall ipv4 input filter rule 10 protocol 'udp'
+set firewall ipv4 output filter rule 10 action 'accept'
+set firewall ipv4 output filter rule 10 destination address '224.0.0.251'
+set firewall ipv4 output filter rule 10 destination port '5353'
+set firewall ipv4 output filter rule 10 protocol 'udp'
+```
+
+
+## Example
+
+To listen on both `eth0` and `eth1` mDNS packets and also repeat packets
+received on `eth0` to `eth1` (and vice-versa) use the following commands:
+
+```none
+set service mdns repeater interface 'eth0'
+set service mdns repeater interface 'eth1'
+```
+
+To allow only specific services, for example `_airplay._tcp` or `_ipp._tcp`,
+(instead of all services) to be re-broadcasted, use the following command:
+
+```none
+set service mdns repeater allow-service '_airplay._tcp'
+set service mdns repeater allow-service '_ipp._tcp'
+```
+
+To allow listing additional custom domain, for example
+`openthread.thread.home.arpa`, so that it can reflected in addition to the
+default `local`, use the following command:
+
+```none
+set service mdns repeater browse-domain 'openthread.thread.home.arpa'
+```
+
+
+## Operation
+
+```{opcmd} restart mdns repeater
+
+Restart mDNS repeater service.
+```
+
+```{opcmd} show log mdns repeater
+
+Show logs for mDNS repeater service.
+```
+
+```{opcmd} monitor log mdns repeater
+
+Follow the logs for mDNS repeater service.
+```
+
+[multicast dns]: <https://en.wikipedia.org/wiki/Multicast_DNS>
diff --git a/docs/configuration/service/monitoring.md b/docs/configuration/service/monitoring.md
new file mode 100644
index 00000000..93bd40e6
--- /dev/null
+++ b/docs/configuration/service/monitoring.md
@@ -0,0 +1,334 @@
+# Monitoring
+
+VyOS supports monitoring through Telegraf as well as through Prometheus exporters.
+
+## Telegraf
+
+Telegraf is the open source server agent to help you collect metrics, events
+and logs from your routers.
+
+The following Telegraf plugins are configurable to export metrics and logs:
+: - Azure Data Explorer
+  - Prometheus Client
+  - Splunk
+  - InfluxDB
+  - Loki
+
+### Azure data explorer
+
+Telegraf output plugin [azure-data-explorer].
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer authentication client-id \<client-id\>
+
+   Authentication application client-id.
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer authentication client-secret \<client-secret\>
+
+Authentication application client-secret.
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer authentication tenant-id \<tenant-id\>
+
+Authentication application tenant-id
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer database \<name\>
+
+Remote database name.
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer group-metrics \<single-table | table-per-metric\>
+
+Type of metrics grouping when push to Azure Data Explorer. The default is
+``table-per-metric``.
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer table \<name\>
+
+Name of the single table Only if set group-metrics single-table.
+```
+
+
+```{cfgcmd} set service monitoring telegraf azure-data-explorer url \<url\>
+
+Remote URL.
+```
+
+### Prometheus client
+
+Telegraf output plugin [prometheus-client]
+This plugin allows export of Telegraf metrics to Prometheus,
+for Prometheus native metrics through exporters see section below.
+
+```{cfgcmd} set service monitoring telegraf prometheus-client
+
+   Output plugin Prometheus client
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client allow-from \<prefix\>
+
+Networks allowed to query this server
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client authentication username \<username\>
+
+HTTP basic authentication username
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client authentication password \<password\>
+
+HTTP basic authentication username
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client listen-address \<address\>
+
+Local IP addresses to listen on
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client metric-version \<1 | 2\>
+
+Metrics version, the default is ``2``
+```
+
+
+```{cfgcmd} set service monitoring telegraf prometheus-client port \<port\>
+
+Port number used by connection, default is ``9273``
+```
+
+Example:
+
+```none
+set service monitoring telegraf prometheus-client
+```
+
+
+```none
+vyos@r14:~$ curl --silent localhost:9273/metrics | egrep -v "#" |  grep cpu_usage_system
+cpu_usage_system{cpu="cpu-total",host="r14"} 0.20040080160320556
+cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915
+cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655
+```
+
+### Splunk
+
+
+Telegraf output plugin [splunk] HTTP Event Collector.
+
+```{cfgcmd} set service monitoring telegraf splunk authentication insecure
+
+Use TLS but skip host validation
+```
+
+
+```{cfgcmd} set service monitoring telegraf splunk authentication token \<token\>
+
+Authorization token
+```
+
+
+```{cfgcmd} set service monitoring telegraf splunk authentication url \<url\>
+
+Remote URL to Splunk collector
+```
+
+Example:
+
+```none
+set service monitoring telegraf splunk authentication insecure
+set service monitoring telegraf splunk authentication token 'xxxxf5b8-xxxx-452a-xxxx-43828911xxxx'
+set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector'
+```
+
+### InfluxDB
+
+
+Telegraf output plugin [influxdb] to write metrics to `InfluxDB` via HTTP.
+
+```{cfgcmd} set service monitoring telegraf influxdb authentication organization \<organization\>
+
+Authentication organization name
+```
+
+
+```{cfgcmd} set service monitoring telegraf influxdb authentication token \<token\>
+
+Authentication token
+```
+
+
+```{cfgcmd} set service monitoring telegraf bucket \<bucket\>
+
+Remote ``InfluxDB`` bucket name
+```
+
+
+```{cfgcmd} set service monitoring telegraf influxdb port \<port\>
+
+Remote port
+```
+
+
+```{cfgcmd} set service monitoring telegraf influxdb url \<url\>
+
+Remote URL
+```
+
+Example:
+
+```none
+set service monitoring telegraf influxdb authentication organization 'vyos'
+set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...=='
+set service monitoring telegraf influxdb bucket 'bucket_vyos'
+set service monitoring telegraf influxdb port '8086'
+set service monitoring telegraf influxdb url 'http://r1.influxdb2.local'
+```
+
+### Loki
+
+Telegraf can be used to send logs to [loki] using tags as labels.
+
+```{cfgcmd} set service monitoring telegraf loki port \<port\>
+
+   Remote Loki port
+
+   Default is 3100
+```
+
+
+```{cfgcmd} set service monitoring telegraf loki url \<url\>
+
+Remote Loki url
+```
+
+
+```{cfgcmd} set service monitoring telegraf loki authentication username \<username\>
+```
+
+```{cfgcmd} set service monitoring telegraf loki authentication password \<password\>
+
+HTTP basic authentication.
+
+If either is set both must be set.
+```
+
+```{cfgcmd} set service monitoring telegraf loki metric-name-label \<label\>
+
+Label to use for the metric name when sending metrics.
+
+If set to an empty string, the label will not be added.
+This is NOT recommended, as it makes it impossible to differentiate
+between multiple metrics.
+```
+
+## Prometheus
+
+
+The following Prometheus exporters are configurable to export metrics:
+: - Node Exporter
+  - FRR Exporter
+
+
+### Node Exporter
+
+
+Prometheus [node_exporter] which provides a wide range of hardware and OS metrics.
+
+```{cfgcmd} set service monitoring prometheus node-exporter listen-address \<address\>
+
+Configure the address node_exporter is listening on.
+```
+
+```{cfgcmd} set service monitoring prometheus node-exporter port \<port\>
+
+Configure the port number node_exporter is listening on.
+```
+
+```{cfgcmd} set service monitoring prometheus node-exporter vrf \<name\>
+
+Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+```{cfgcmd} set service monitoring prometheus node-exporter collectors textfile
+
+Configure textfile collector to export custom metrics read from
+`/run/node_exporter/collector`
+```
+
+### FRR Exporter
+
+Prometheus [frr_exporter] which provides free range routing metrics.
+
+```{cfgcmd} set service monitoring prometheus frr-exporter listen-address \<address\>
+
+Configure the address frr_exporter is listening on.
+
+```
+
+```{cfgcmd} set service monitoring prometheus frr-exporter port \<port\>
+
+Configure the port number frr_exporter is listening on.
+```
+
+```{cfgcmd} set service monitoring prometheus frr-exporter vrf \<name\>
+
+Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+### Blackbox Exporter
+
+Prometheus [blackbox_exporter] which allows probing of endpoints over
+HTTP, HTTPS, DNS, TCP, ICMP and gRPC .
+
+```{cfgcmd} set service monitoring prometheus blackbox-exporter listen-address \<address\>
+
+Configure the address blackbox_exporter is listening on.
+```
+```{cfgcmd} set service monitoring prometheus blackbox-exporter port \<port\>
+
+Configure the port number blackbox_exporter is listening on.
+```
+```{cfgcmd} set service monitoring prometheus blackbox-exporter vrf \<name\>
+
+Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+#### Configuring modules
+
+Blackbox exporter can be configured with different modules for probing DNS or ICMP.
+
+DNS module example:
+
+```none
+set service monitoring prometheus blackbox-exporter modules dns name dns4 preferred-ip-protocol ipv4
+set service monitoring prometheus blackbox-exporter modules dns name dns4 query-name vyos.io
+set service monitoring prometheus blackbox-exporter modules dns name dns4 query-type A
+```
+
+ICMP module example:
+
+```none
+set service monitoring prometheus blackbox-exporter modules icmp name ping6 preferred-ip-protocol ipv6
+set service monitoring prometheus blackbox-exporter modules icmp name ping6 ip-protocol-fallback
+set service monitoring prometheus blackbox-exporter modules icmp name ping6 timeout 3
+```
+
+[azure-data-explorer]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer>
+[blackbox_exporter]: <https://github.com/prometheus/blackbox_exporter>
+[frr_exporter]: <https://github.com/tynany/frr_exporter>
+[influxdb]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/influxdb_v2>
+[loki]: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/loki
+[node_exporter]: <https://github.com/prometheus/node_exporter>
+[prometheus-client]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client>
+[splunk]: <https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html>
diff --git a/docs/configuration/service/ntp.md b/docs/configuration/service/ntp.md
new file mode 100644
index 00000000..c8c1dee3
--- /dev/null
+++ b/docs/configuration/service/ntp.md
@@ -0,0 +1,202 @@
+(ntp)=
+
+# NTP
+
+{abbr}`NTP (Network Time Protocol`) is a networking protocol for clock
+synchronization between computer systems over packet-switched, variable-latency
+data networks. In operation since before 1985, NTP is one of the oldest Internet
+protocols in current use.
+
+NTP is intended to synchronize all participating computers to within a few
+milliseconds of {abbr}`UTC (Coordinated Universal Time)`. It uses the
+intersection algorithm, a modified version of Marzullo's algorithm, to select
+accurate time servers and is designed to mitigate the effects of variable
+network latency. NTP can usually maintain time to within tens of milliseconds
+over the public Internet, and can achieve better than one millisecond accuracy
+in local area networks under ideal conditions. Asymmetric routes and network
+congestion can cause errors of 100 ms or more.
+
+The protocol is usually described in terms of a client-server model, but can as
+easily be used in peer-to-peer relationships where both peers consider the other
+to be a potential time source. Implementations send and receive timestamps using
+{abbr}`UDP (User Datagram Protocol)` on port number 123.
+
+NTP supplies a warning of any impending leap second adjustment, but no
+information about local time zones or daylight saving time is transmitted.
+
+The current protocol is version 4 (NTPv4), which is a proposed standard as
+documented in {rfc}`5905`. It is backward compatible with version 3, specified
+in {rfc}`1305`.
+
+:::{note}
+VyOS 1.4 uses chrony instead of ntpd (see {vytask}`T3008`) which will
+no longer accept anonymous NTP requests as in VyOS 1.3. All configurations
+will be migrated to keep the anonymous functionality. For new setups if you
+have clients using your VyOS installation as NTP server, you must specify
+the `allow-client` directive.
+:::
+
+## Configuration
+
+```{cfgcmd} set service ntp server \<address\>
+
+   Configure one or more servers for synchronisation. Server name can be either
+   an IP address or {abbr}`FQDN (Fully Qualified Domain Name)`.
+
+   There are 3 default NTP server set. You are able to change them.
+
+   * ``time1.vyos.net``
+   * ``time2.vyos.net``
+   * ``time3.vyos.net``
+```
+
+
+```{cfgcmd} set service ntp server \<address\> \<noselect | nts | pool | prefer | ptp | interleave\>
+
+Configure one or more attributes to the given NTP server.
+
+* ``noselect`` marks the server as unused, except for display purposes. The
+server is discarded by the selection algorithm.
+
+* ``nts`` enables Network Time Security (NTS) for the server as specified
+in {rfc}`8915`
+
+* ``pool`` mobilizes persistent client mode association with a number of
+remote servers.
+
+* ``prefer`` marks the server as preferred. All other things being equal,
+this host will be chosen for synchronization among a set of correctly
+operating hosts.
+
+* ``ptp`` enables the PTP transport for this server (see {ref}`ptp-transport`).
+
+* ``interleave`` enables NTP interleaved mode (see [draft-ntp-interleaved-modes]), which can improve
+synchronization accuracy and stability when supported by both parties.
+```
+
+
+```{cfgcmd} set service ntp listen-address \<address\>
+
+NTP process will only listen on the specified IP address. You must specify
+the `<address>` and optionally the permitted clients. Multiple listen
+addresses for same IP family is no longer supported. Only one IPv4 and one
+IPv6 address can be configured, using separate commands for each.
+```
+
+
+```{cfgcmd} set service ntp allow-client address \<address\>
+
+List of networks or client addresses permitted to contact this NTP server.
+
+Multiple networks/client IP addresses can be configured.
+```
+
+
+```{cfgcmd} set service ntp vrf \<name\>
+
+Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+
+```{cfgcmd} set service ntp leap-second [ignore|smear|system|timezone]
+
+Define how to handle leap-seconds.
+
+* `ignore`: No correction is applied to the clock for the leap second. The
+clock will be corrected later in normal operation when new measurements are
+made and the estimated offset includes the one second error.
+
+* `smear`: When smearing a leap second, the leap status is suppressed on the
+server and the served time is corrected slowly by slewing instead of
+stepping. The clients do not need any special configuration as they do not
+know there is any leap second and they follow the server time which
+eventually brings them back to UTC. Care must be taken to ensure they use
+only NTP servers which smear the leap second in exactly the same way for
+synchronisation.
+
+* `system`: When inserting a leap second, the kernel steps the system clock
+backwards by one second when the clock gets to 00:00:00 UTC. When deleting
+a leap second, it steps forward by one second when the clock gets to
+23:59:59 UTC.
+
+* `timezone`: This directive specifies a timezone in the system timezone
+database which chronyd can use to determine when will the next leap second
+occur and what is the current offset between TAI and UTC. It will
+periodically check if 23:59:59 and 23:59:60 are valid times in the
+timezone. This normally works with the right/UTC timezone which is the
+default
+```
+
+## Hardware Timestamping of NTP Packets
+
+
+The chrony daemon on VyOS can leverage NIC hardware capabilities to record the
+exact time packets are received on the interface, as well as when packets were
+actually transmitted. This provides improved accuracy and stability when the
+system is under load, as queuing and OS context switching can introduce a
+variable delay between when the packet is received on the network and when it
+is actually processed by the NTP daemon.
+
+
+Hardware timestamping depends on NIC support. Some NICs can be configured to
+apply timestamps to any incoming packet, while others only support applying
+timestamps to specific protocols (e.g. PTP).
+
+
+When timestamping is enabled on an interface, chrony's default behavior is to
+try to configure the interface to only timestamp NTP packets. If this mode is
+not supported, chrony will attempt to set it to timestamp all packets. If
+neither option is supported (e.g. the NIC can only timestamp received PTP
+packets), chrony will leverage timestamping on transmitted packets only, which
+still provides some benefit.
+
+```{cfgcmd} set service ntp timestamp interface \<interface\>
+
+Configures hardware timestamping on the interface \<interface\>. The special
+value `all` can also be specified to enable timestamping on all interfaces
+that support it.
+
+Configure the timestamping behavior with the following option:
+
+* ``receive-filter [all|ntp|ptp|none]`` selects the receive filter mode,
+which controls which inbound packets the NIC applies timestamps to. The
+selected mode must be supported by the NIC, or timestamping will be
+disabled for the interface.
+```
+
+The following `receive-filter` modes can be selected:
+- *all*: All received packets will be timestamped.
+- *ntp*: Only received NTP protocol packets will be timestamped.
+- *ptp*: Only received PTP protocol packets will be timestamped. Combined with
+  the PTP transport for NTP packets, this can be leveraged to take advantage of
+  hardware timestamping on NICs that only support the ptp filter mode.
+- *none*: No received packets will be timestamped. Hardware timestamping of
+  transmitted packets will still be leveraged, if supported by the NIC.
+(ptp-transport)=
+
+## PTP Transport of NTP Packets
+
+The Precision Time Protocol (IEEE 1588) is a local network time synchronization
+protocol that provides high precision time synchronization by leveraging
+hardware clocks in NICs and other network elements. VyOS does not currently
+support standards-based PTP, which can be deployed independently of
+NTP.
+
+For networks consisting of VyOS and other Linux systems running relatively
+recent versions of the chrony daemon, NTP packets can be "tunneled" over
+PTP. NTP over PTP provides the best of both worlds, leveraging hardware support
+for timestamping PTP packets while retaining the configuration flexibility and
+fault tolerance of NTP.
+
+```{cfgcmd} set service ntp ptp
+
+Enables the NTP daemon PTP transport. The NTP daemon will listen on the
+configured PTP port. Note that one or more servers must be individually
+enabled for PTP before the daemon will synchronize over the transport.
+```
+```{cfgcmd} set service ntp ptp port \<port\>
+
+Configures the PTP port. By default, the standard port 319 is used.
+```
+
+[draft-ntp-interleaved-modes]: https://datatracker.ietf.org/doc/draft-ietf-ntp-interleaved-modes/07/
diff --git a/docs/configuration/service/pppoe-server.md b/docs/configuration/service/pppoe-server.md
new file mode 100644
index 00000000..805740e4
--- /dev/null
+++ b/docs/configuration/service/pppoe-server.md
@@ -0,0 +1,753 @@
+---
+lastproofread: '2022-09-17'
+---
+
+(pppoe-server)=
+
+# PPPoE Server
+
+VyOS utilizes [accel-ppp](https://accel-ppp.org/) to provide PPPoE server functionality. It can
+be used with local authentication or a connected RADIUS server.
+
+:::{note}
+Please be aware, due to an upstream bug, config
+changes/commits will restart the ppp daemon and will reset existing
+PPPoE connections from connected users, in order to become effective.
+:::
+
+## Configuring PPPoE Server
+
+```none
+set service pppoe-server access-concentrator PPPoE-Server
+set service pppoe-server authentication mode local
+set service pppoe-server authentication local-users username test password 'test'
+set service pppoe-server client-ip-pool PPPOE-POOL range 192.168.255.2-192.168.255.254
+set service pppoe-server default-pool 'PPPOE-POOL'
+set service pppoe-server gateway-address 192.168.255.1
+set service pppoe-server interface eth0
+```
+
+```{cfgcmd} set service pppoe-server access-concentrator \<name\>
+
+   Use this command to set a name for this PPPoE-server access
+   concentrator.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication mode \<local | radius\>
+
+Set authentication backend. The configured authentication backend is used
+for all queries.
+
+* **radius**: All authentication queries are handled by a configured RADIUS
+server.
+* **local**: All authentication queries are handled locally.
+* **noauth**: Authentication disabled.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication local-users username \<name\> password \<password\>
+
+Create `<user>` for local authentication on this system. The users password
+will be set to `<pass>`.
+```
+
+
+```{cfgcmd} set service pppoe-server client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\>
+
+Use this command to define the first IP address of a pool of
+addresses to be given to pppoe clients. If notation ``x.x.x.x-x.x.x.x``,
+it must be within a /24 subnet. If notation ``x.x.x.x/x`` is
+used there is possibility to set host/netmask.
+```
+
+
+```{cfgcmd} set service pppoe-server default-pool \<POOL-NAME\>
+
+Use this command to define default address pool name.
+```
+
+
+```{cfgcmd} set service pppoe-server interface \<interface\>
+
+Use this command to define the interface the PPPoE server will use to
+listen for PPPoE clients.
+```
+
+
+```{cfgcmd} set service pppoe-server gateway-address \<address\>
+
+Specifies single `<gateway>` IP address to be used as local address of PPP
+interfaces.
+```
+
+## Configuring RADIUS authentication
+
+To enable RADIUS based authentication, the authentication mode needs to be
+changed within the configuration. Previous settings like the local users, still
+exists within the configuration, however they are not used if the mode has been
+changed from local to radius. Once changed back to local, it will use all local
+accounts again.
+
+```none
+set service pppoe-server authentication mode radius
+```
+
+```{cfgcmd} set service pppoe-server authentication radius server \<server\> key \<secret\>
+
+Configure RADIUS `<server>` and its required shared `<secret>` for
+communicating with the RADIUS server.
+```
+
+Since the RADIUS server would be a single point of failure, multiple RADIUS
+servers can be setup and will be used subsequentially.
+For example:
+
+```none
+set service pppoe-server authentication radius server 10.0.0.1 key 'foo'
+set service pppoe-server authentication radius server 10.0.0.2 key 'foo'
+```
+
+:::{note}
+Some RADIUS severs use an access control list which allows or denies
+queries, make sure to add your VyOS router to the allowed client list.
+:::
+
+
+### RADIUS source address
+
+
+If you are using OSPF as IGP, always the closest interface connected to the
+RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests
+to a single source IP e.g. the loopback interface.
+
+```{cfgcmd} set service pppoe-server authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queries.
+```
+
+:::{note}
+The `source-address` must be configured on one of VyOS interface.
+Best practice would be a loopback or dummy interface.
+:::
+
+
+### RADIUS advanced options
+
+```{cfgcmd} set service pppoe-server authentication radius server \<server\> port \<port\>
+
+Configure RADIUS `<server>` and its required port for authentication requests.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius server \<server\> fail-time \<time\>
+
+Mark RADIUS server as offline for this given `<time>` in seconds.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius server \<server\> disable
+
+Temporary disable this RADIUS server.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius acct-timeout \<timeout\>
+
+Timeout to wait reply for Interim-Update packets. (default 3 seconds)
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius dynamic-author server \<address\>
+
+Specifies IP address for Dynamic Authorization Extension server (DM/CoA).
+This IP must exist on any VyOS interface or it can be ``0.0.0.0``.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius dynamic-author port \<port\>
+
+UDP port for Dynamic Authorization Extension server (DM/CoA)
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius dynamic-author key \<secret\>
+
+Secret for Dynamic Authorization Extension server (DM/CoA)
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius max-try \<number\>
+
+Maximum number of tries to send Access-Request/Accounting-Request queries
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius timeout \<timeout\>
+
+Timeout to wait response from server (seconds)
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius nas-identifier \<identifier\>
+
+Value to send to RADIUS server in NAS-Identifier attribute and to be matched
+in DM/CoA requests.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius nas-ip-address \<address\>
+
+Value to send to RADIUS server in NAS-IP-Address attribute and to be matched
+in DM/CoA requests. Also DM/CoA server will bind to that address.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius source-address \<address\>
+
+Source IPv4 address used in all RADIUS server queries.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius rate-limit attribute \<attribute\>
+
+Specifies which RADIUS server attribute contains the rate limit information.
+The default attribute is ``Filter-Id``.
+```
+
+:::{note}
+If you set a custom RADIUS attribute you must define it on both
+dictionaries at RADIUS server and client.
+:::
+
+```{cfgcmd} set service pppoe-server authentication radius rate-limit enable
+
+Enables bandwidth shaping via RADIUS.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication radius rate-limit vendor
+
+Specifies the vendor dictionary, dictionary needs to be in
+/usr/share/accel-ppp/radius.
+```
+
+Received RADIUS attributes have a higher priority than parameters defined within
+the CLI configuration, refer to the explanation below.
+
+
+### Allocation clients ip addresses by RADIUS
+
+
+If the RADIUS server sends the attribute `Framed-IP-Address` then this IP
+address will be allocated to the client and the option `default-pool`
+within the CLI config is being ignored.
+
+
+If the RADIUS server sends the attribute `Framed-Pool`, IP address will
+be allocated from a predefined IP pool whose name equals the attribute value.
+
+
+If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`,
+IPv6 address will be allocated from a predefined IPv6 pool `prefix`
+whose name equals the attribute value.
+
+
+If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`,
+IPv6 delegation prefix will be allocated from a predefined IPv6 pool `delegate`
+whose name equals the attribute value.
+
+
+:::{note}
+`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool`
+are defined in RFC6911. If they are not defined in your RADIUS server,
+add new [dictionary].
+:::
+
+
+User interface can be put to VRF context via RADIUS Access-Accept packet,
+or change it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes.
+It is custom [ACCEL-PPP attribute]. Define it in your RADIUS server.
+
+
+### Renaming clients interfaces by RADIUS
+
+
+If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be
+renamed.
+
+
+:::{note}
+The value of the attribute `NAS-Port-Id` must be less than 16
+characters, otherwise the interface won't be renamed.
+:::
+
+
+## Automatic VLAN Creation
+
+```{cfgcmd} set service pppoe-server interface \<interface\> vlan \<id | range\>
+
+VLAN's can be created by Accel-ppp on the fly via the use of a Kernel module
+named ``vlan_mon``, which is monitoring incoming vlans and creates the
+necessary VLAN if required and allowed. VyOS supports the use of either
+VLAN ID's or entire ranges, both values can be defined at the same time for
+an interface.
+
+When configured, PPPoE will create the necessary VLANs when required. Once
+the user session has been cancelled and the VLAN is not needed anymore, VyOS
+will remove it again.
+```
+
+
+```none
+set service pppoe-server interface eth3 vlan 100
+set service pppoe-server interface eth3 vlan 200
+set service pppoe-server interface eth3 vlan 500-1000
+set service pppoe-server interface eth3 vlan 2000-3000
+```
+
+## Bandwidth Shaping
+
+
+Bandwidth rate limits can be set for local users or RADIUS based
+attributes.
+
+
+### For Local Users
+
+```{cfgcmd} set service pppoe-server authentication local-users username \<user\> rate-limit download \<bandwidth\>
+
+Download bandwidth limit in kbit/s for `<user>`.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication local-users username \<user\> rate-limit upload \<bandwidth\>
+
+Upload bandwidth limit in kbit/s for `<user>`.
+```
+```none
+set service pppoe-server access-concentrator 'ACN'
+set service pppoe-server authentication local-users username foo password 'bar'
+set service pppoe-server authentication local-users username foo rate-limit download '20480'
+set service pppoe-server authentication local-users username foo rate-limit upload '10240'
+set service pppoe-server authentication mode 'local'
+set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100/24'
+set service pppoe-server default-pool 'IP-POOL'
+set service pppoe-server name-server '10.100.100.1'
+set service pppoe-server name-server '10.100.200.1'
+set service pppoe-server interface 'eth1'
+set service pppoe-server gateway-address '10.1.1.2'
+```
+
+Once the user is connected, the user session is using the set limits and
+can be displayed via `show pppoe-server sessions`.
+
+```none
+show pppoe-server sessions
+ifname | username |     ip     |    calling-sid    | rate-limit  | state  |  uptime  | rx-bytes | tx-bytes
+-------+----------+------------+-------------------+-------------+--------+----------+----------+----------
+ppp0   | foo      | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B    | 76 B
+```
+
+### For RADIUS users
+
+The current attribute `Filter-Id` is being used as default and can be
+setup within RADIUS:
+
+Filter-Id=2000/3000 (means 2000Kbit down-stream rate and 3000Kbit
+up-stream rate)
+
+The command below enables it, assuming the RADIUS connection has been
+setup and is working.
+
+```{cfgcmd} set service pppoe-server authentication radius rate-limit enable
+
+   Use this command to enable bandwidth shaping via RADIUS.
+```
+
+Other attributes can be used, but they have to be in one of the
+dictionaries in */usr/share/accel-ppp/radius*.
+
+
+## Load Balancing
+
+```{cfgcmd} set service pppoe-server pado-delay \<number-of-ms\> sessions \<number-of-sessions\>
+
+Use this command to enable the delay of PADO (PPPoE Active Discovery
+Offer) packets, which can be used as a session balancing mechanism
+with other PPPoE servers.
+```
+
+
+```none
+set service pppoe-server pado-delay 50 sessions '500'
+set service pppoe-server pado-delay 100 sessions '1000'
+set service pppoe-server pado-delay 300 sessions '3000'
+```
+
+In the example above, the first 499 sessions connect without delay. PADO
+packets will be delayed 50 ms for connection from 500 to 999, this trick
+allows other PPPoE servers send PADO faster and clients will connect to
+other servers. Last command says that this PPPoE server can serve only
+3000 clients.
+
+
+## IPv6
+
+```{cfgcmd} set service pppoe-server ppp-options ipv6 \<require | prefer | allow | deny\>
+
+Specifies IPv6 negotiation preference.
+
+* **require** - Require IPv6 negotiation
+* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects
+* **allow** - Negotiate IPv6 only if client requests
+* **deny** - Do not negotiate IPv6 (default value)
+```
+
+
+```{cfgcmd} set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\>
+
+Use this command to set the IPv6 address pool from which a PPPoE client
+will get an IPv6 prefix of your defined length (mask) to terminate the
+PPPoE endpoint at their side. The mask length can be set from 48 to 128
+bit long, the default value is 64.
+```
+
+
+```{cfgcmd} set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\>
+
+Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on
+PPPoE. You will have to set your IPv6 pool and the length of the
+delegation prefix. From the defined IPv6 pool you will be handing out
+networks of the defined length (delegation-prefix). The length of the
+delegation prefix can be set from 32 to 64 bit long.
+```
+
+
+```{cfgcmd} set service pppoe-server default-ipv6-pool \<IPv6-POOL-NAME\>
+
+Use this command to define default IPv6 address pool name.
+```
+
+
+```none
+set service pppoe-server ppp-options ipv6 allow
+set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56'
+set service pppoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64'
+set service pppoe-server default-ipv6-pool IPv6-POOL
+```
+
+### IPv6 Advanced Options
+
+```{cfgcmd} set service pppoe-server ppp-options ipv6-accept-peer-interface-id
+
+Accept peer interface identifier. By default is not defined.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<random | x:x:x:x\>
+
+Specifies fixed or random interface identifier for IPv6.
+By default is fixed.
+
+* **random** - Random interface identifier for IPv6
+* **x:x:x:x** - Specify interface identifier for IPv6
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<random | x:x:x:x\>
+
+Specifies peer interface identifier for IPv6. By default is fixed.
+
+* **random** - Random interface identifier for IPv6
+* **x:x:x:x** - Specify interface identifier for IPv6
+* **ipv4-addr** - Calculate interface identifier from IPv4 address.
+* **calling-sid** - Calculate interface identifier from calling-station-id.
+```
+
+## Scripting
+
+```{cfgcmd} set service pppoe-server extended-scripts on-change \<path_to_script\>
+
+Script to run when session interface changed by RADIUS CoA handling
+```
+
+
+```{cfgcmd} set service pppoe-server extended-scripts on-down \<path_to_script\>
+
+Script to run when session interface going to terminate
+```
+
+
+```{cfgcmd} set service pppoe-server extended-scripts on-pre-up \<path_to_script\>
+
+Script to run before session interface comes up
+```
+
+
+```{cfgcmd} set service pppoe-server extended-scripts on-up \<path_to_script\>
+
+Script to run when session interface is completely configured and started
+```
+
+## Advanced Options
+
+
+### Authentication Advanced Options
+
+```{cfgcmd} set service pppoe-server authentication local-users username \<user\> disable
+
+Disable `<user>` account.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication local-users username \<user\> static-ip \<address\>
+
+Assign static IP address to `<user>` account.
+```
+
+
+```{cfgcmd} set service pppoe-server authentication protocols \<pap | chap | mschap | mschap-v2\>
+
+Require the peer to authenticate itself using one of the following protocols:
+pap, chap, mschap, mschap-v2.
+```
+
+### Client IP Pool Advanced Options
+
+```{cfgcmd} set service pppoe-server client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\>
+
+Use this command to define the next address pool name.
+```
+
+### PPP Advanced Options
+
+```{cfgcmd} set service pppoe-server ppp-options disable-ccp
+
+Disable Compression Control Protocol (CCP).
+CCP is enabled by default.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options interface-cache \<number\>
+
+Specifies number of interfaces to keep in cache. It means that don’t
+destroy interface after corresponding session is destroyed, instead
+place it to cache and use it later for new sessions repeatedly.
+This should reduce kernel-level interface creation/deletion rate lack.
+Default value is **0**.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options ipv4 \<require | prefer | allow | deny\>
+
+Specifies IPv4 negotiation preference.
+
+* **require** - Require IPv4 negotiation
+* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects
+* **allow** - Negotiate IPv4 only if client requests (Default value)
+* **deny** - Do not negotiate IPv4
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options lcp-echo-failure \<number\>
+
+Defines the maximum `<number>` of unanswered echo requests. Upon reaching the
+value `<number>`, the session will be reset. Default value is **3**.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options lcp-echo-interval \<interval\>
+
+If this option is specified and is greater than 0, then the PPP module will
+send LCP pings of the echo request every `<interval>` seconds.
+Default value is **30**.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options lcp-echo-timeout
+
+Specifies timeout in seconds to wait for any peer activity. If this option
+specified it turns on adaptive lcp echo functionality and "lcp-echo-failure"
+is not used. Default value is **0**.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options min-mtu \<number\>
+
+Defines minimum acceptable MTU. If client will try to negotiate less then
+specified MTU then it will be NAKed or disconnected if rejects greater MTU.
+Default value is **100**.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options mppe \<require | prefer | deny\>
+
+Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation
+preference.
+
+* **require** - ask client for mppe, if it rejects drop connection
+* **prefer** - ask client for mppe, if it rejects don't fail. (Default value)
+* **deny** - deny mppe
+
+Default behavior - don't ask client for mppe, but allow it if client wants.
+Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy
+attribute.
+```
+
+
+```{cfgcmd} set service pppoe-server ppp-options mru \<number\>
+
+Defines preferred MRU. By default is not defined.
+```
+
+### Global Advanced options
+
+```{cfgcmd} set service pppoe-server description \<description\>
+
+Set description.
+```
+
+
+```{cfgcmd} set service pppoe-server limits burst \<value\>
+
+Burst count
+```
+
+
+```{cfgcmd} set service pppoe-server limits connection-limit \<value\>
+
+Acceptable rate of connections (e.g. 1/min, 60/sec)
+```
+
+
+```{cfgcmd} set service pppoe-server limits timeout \<value\>
+
+Timeout in seconds
+```
+
+
+```{cfgcmd} set service pppoe-server mtu
+
+Maximum Transmission Unit (MTU) (default: **1492**)
+```
+
+
+```{cfgcmd} set service pppoe-server max-concurrent-sessions
+
+Maximum number of concurrent session start attempts
+```
+
+
+```{cfgcmd} set service pppoe-server name-server \<address\>
+
+Connected client should use `<address>` as their DNS server. This
+command accepts both IPv4 and IPv6 addresses. Up to two nameservers
+can be configured for IPv4, up to three for IPv6.
+```
+
+
+```{cfgcmd} set service pppoe-server service-name \<names\>
+
+Specifies Service-Name to respond. If absent any Service-Name is
+acceptable and client’s Service-Name will be sent back. Also possible
+set multiple service-names: `sn1,sn2,sn3`
+```
+
+Per default the user session is being replaced if a second
+authentication request succeeds. Such session requests can be either
+denied or allowed entirely, which would allow multiple sessions for a
+user in the latter case. If it is denied, the second session is being
+rejected even if the authentication succeeds, the user has to terminate
+its first session and can then authentication again.
+
+```{cfgcmd} set service pppoe-server session-control
+
+* **disable**: Disables session control.
+* **deny**: Deny second session authorization.
+* **replace**: Terminate first session when second is authorized **(default)**
+```
+
+
+```{cfgcmd} set service pppoe-server shaper fwmark \<1-2147483647\>
+
+Match firewall mark value
+```
+
+
+```{cfgcmd} set service pppoe-server snmp master-agent
+
+Enable SNMP
+```
+
+
+```{cfgcmd} set service pppoe-server wins-server \<address\>
+
+Windows Internet Name Service (WINS) servers propagated to client
+```
+
+## Monitoring
+
+```{opcmd} show pppoe-server sessions
+
+Use this command to locally check the active sessions in the PPPoE
+server.
+```
+```none
+show pppoe-server sessions
+ifname | username |     ip     |    calling-sid    | rate-limit  | state  |  uptime  | rx-bytes | tx-bytes
+-------+----------+------------+-------------------+-------------+--------+----------+----------+----------
+ppp0   | foo      | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B    | 76 B
+```
+
+## Examples
+### IPv4
+
+The example below uses ACN as access-concentrator name, assigns an
+address from the pool 10.1.1.100-111, terminates at the local endpoint
+10.1.1.1 and serves requests only on eth1.
+
+```none
+set service pppoe-server access-concentrator 'ACN'
+set service pppoe-server authentication local-users username foo password 'bar'
+set service pppoe-server authentication mode 'local'
+set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100-10.1.1.111'
+set service pppoe-server default-pool 'IP-POOL'
+set service pppoe-server interface eth1
+set service pppoe-server gateway-address '10.1.1.2'
+set service pppoe-server name-server '10.100.100.1'
+set service pppoe-server name-server '10.100.200.1'
+```
+
+### Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation
+
+The example below covers a dual-stack configuration.
+
+```none
+set service pppoe-server authentication local-users username test password 'test'
+set service pppoe-server authentication mode 'local'
+set service pppoe-server client-ip-pool IP-POOL range '192.168.0.1/24'
+set service pppoe-server default-pool 'IP-POOL'
+set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56'
+set service pppoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64'
+set service pppoe-server default-ipv6-pool IPv6-POOL
+set service pppoe-server ppp-options ipv6 allow
+set service pppoe-server name-server '10.1.1.1'
+set service pppoe-server name-server '2001:db8:4860::8888'
+set service pppoe-server interface 'eth2'
+set service pppoe-server gateway-address '10.100.100.1'
+```
+
+The client, once successfully authenticated, will receive an IPv4 and an
+IPv6 /64 address to terminate the PPPoE endpoint on the client side and
+a /56 subnet for the clients internal use.
+
+```none
+vyos@pppoe-server:~$ sh pppoe-server sessions
+ ifname | username |     ip      |            ip6           |       ip6-dp        |    calling-sid    | rate-limit | state  |  uptime  | rx-bytes | tx-bytes
+--------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+----------
+ ppp0   | test     | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb |            | active | 00:00:49 | 875 B    | 2.1 KiB
+```
+
+[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
+[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911
diff --git a/docs/configuration/service/router-advert.md b/docs/configuration/service/router-advert.md
new file mode 100644
index 00000000..10753105
--- /dev/null
+++ b/docs/configuration/service/router-advert.md
@@ -0,0 +1,121 @@
+(router-advert)=
+
+# Router Advertisements
+
+{abbr}`RAs (Router advertisements)` are described in {rfc}`4861#section-4.6.2`.
+They are part of what is known as {abbr}`SLAAC (Stateless Address
+Autoconfiguration)`.
+
+Supported interface types:
+
+> - bonding
+> - bridge
+> - ethernet
+> - geneve
+> - l2tpv3
+> - openvpn
+> - pseudo-ethernet
+> - tunnel
+> - vxlan
+> - wireguard
+> - wireless
+> - wwan
+
+## Configuration
+
+```{cfgcmd} set service router-advert interface \<interface\> ...
+```
+
+```{eval-rst}
+.. csv-table::
+   :header: "Field", "VyOS Option", "Description"
+   :widths: 10, 10, 20
+
+   "Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets"
+   """Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration"
+   """Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information"
+   "MTU","link-mtu","Link MTU value placed in RAs, excluded in RAs if unset"
+   "Router Lifetime","default-lifetime","Lifetime associated with the default router in units of seconds"
+   "Reachable Time","reachable-time","Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation"
+   "Retransmit Timer","retrans-timer","Time in milliseconds between retransmitted Neighbor Solicitation messages"
+   "Default Router Preference","default-preference","Preference associated with the default router"
+   "Interval", "interval", "Min and max intervals between unsolicited multicast RAs"
+   "DNSSL", "dnssl", "DNS search list to advertise"
+   "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106"
+   "Auto Ignore Prefix", "auto-ignore", "Exclude a prefix from being advertised when the wildcard ::/64 prefix is used"
+   "Captive Portal", "captive-portal", "Advertise a URL pointing to an RFC 8908-compliant API to tell hosts that they are behind a captive portal"
+```
+
+### Advertising a Prefix
+
+```{cfgcmd} set service router-advert interface \<interface\> prefix \<prefix/mask\>
+
+:::{note}
+You can also opt for using ::/64 as prefix for your {abbr}`RAs (Router
+Advertisements)`. This is a special wildcard prefix that will emit {abbr}`RAs (Router Advertisements)` for every prefix assigned to the interface.
+This comes in handy when using dynamically obtained prefixes from DHCPv6-PD.
+:::
+```
+```{eval-rst}
+.. csv-table::
+    :header: "VyOS Field", "Description"
+    :widths: 10,30
+
+    "decrement-lifetime", "Lifetime is decremented by the number of seconds since the last RA - use in conjunction with a DHCPv6-PD prefix"
+    "deprecate-prefix", "Upon shutdown, this option will deprecate the prefix by announcing it in the shutdown RA"
+    "no-autonomous-flag","Prefix can not be used for stateless address auto-configuration"
+    "no-on-link-flag","Prefix can not be used for on-link determination"
+    "preferred-lifetime","Time in seconds that the prefix will remain preferred (default 4 hours)"
+    "valid-lifetime","Time in seconds that the prefix will remain valid (default: 30 days)"
+```
+
+### Advertising a NAT64 Prefix
+
+```{cfgcmd} set service router-advert interface \<interface\> nat64prefix \<prefix/mask\>
+
+Enable PREF64 option as outlined in {rfc}`8781`.
+
+NAT64 prefix mask must be one of: /32, /40, /48, /56, /64 or 96.
+
+:::{note}
+The well known NAT64 prefix is ``64:ff9b::/96``
+:::
+```
+```{eval-rst}
+.. csv-table::
+    :header: "VyOS Field", "Description"
+    :widths: 10,30
+
+    "valid-lifetime","Time in seconds that the prefix will remain valid (default: 65528 seconds)"
+```
+
+### Disabling Advertisements
+
+To disable advertisements without deleting the configuration:
+
+```{cfgcmd} set service router-advert interface \<interface\> no-send-advert
+
+If set, the router will no longer send periodic router advertisements and
+will not respond to router solicitations.
+```
+
+```{cfgcmd} set service router-advert interface \<interface\> no-send-interval
+
+Advertisement Interval Option (specified by Mobile IPv6) is always included in
+Router Advertisements unless this option is set.
+```
+
+## Example
+
+Your LAN connected on eth0 uses prefix `2001:db8:beef:2::/64` with the router
+beeing `2001:db8:beef:2::1`
+
+```none
+set interfaces ethernet eth0 address 2001:db8:beef:2::1/64
+
+set service router-advert interface eth0 default-preference 'high'
+set service router-advert interface eth0 name-server '2001:db8::1'
+set service router-advert interface eth0 name-server '2001:db8::2'
+set service router-advert interface eth0 other-config-flag
+set service router-advert interface eth0 prefix 2001:db8:beef:2::/64
+```
diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/rst-broadcast-relay.rst
index f64bb208..f64bb208 100644
--- a/docs/configuration/service/broadcast-relay.rst
+++ b/docs/configuration/service/rst-broadcast-relay.rst
diff --git a/docs/configuration/service/config-sync.rst b/docs/configuration/service/rst-config-sync.rst
index a8984a0d..a8984a0d 100644
--- a/docs/configuration/service/config-sync.rst
+++ b/docs/configuration/service/rst-config-sync.rst
diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/rst-conntrack-sync.rst
index 2527407e..2527407e 100644
--- a/docs/configuration/service/conntrack-sync.rst
+++ b/docs/configuration/service/rst-conntrack-sync.rst
diff --git a/docs/configuration/service/console-server.rst b/docs/configuration/service/rst-console-server.rst
index c9ea7f77..c9ea7f77 100644
--- a/docs/configuration/service/console-server.rst
+++ b/docs/configuration/service/rst-console-server.rst
diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/rst-dhcp-relay.rst
index 6a1b02f2..6a1b02f2 100644
--- a/docs/configuration/service/dhcp-relay.rst
+++ b/docs/configuration/service/rst-dhcp-relay.rst
diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/rst-dhcp-server.rst
index 09f40b37..09f40b37 100644
--- a/docs/configuration/service/dhcp-server.rst
+++ b/docs/configuration/service/rst-dhcp-server.rst
diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/rst-dns.rst
index 365e7885..365e7885 100644
--- a/docs/configuration/service/dns.rst
+++ b/docs/configuration/service/rst-dns.rst
diff --git a/docs/configuration/service/eventhandler.rst b/docs/configuration/service/rst-eventhandler.rst
index 9f4ebb04..9f4ebb04 100644
--- a/docs/configuration/service/eventhandler.rst
+++ b/docs/configuration/service/rst-eventhandler.rst
diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/rst-https.rst
index e72e8e8b..e72e8e8b 100644
--- a/docs/configuration/service/https.rst
+++ b/docs/configuration/service/rst-https.rst
diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/rst-index.rst
index fb6f8413..fb6f8413 100644
--- a/docs/configuration/service/index.rst
+++ b/docs/configuration/service/rst-index.rst
diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/rst-ipoe-server.rst
index 5d7acd5a..5d7acd5a 100644
--- a/docs/configuration/service/ipoe-server.rst
+++ b/docs/configuration/service/rst-ipoe-server.rst
diff --git a/docs/configuration/service/lldp.rst b/docs/configuration/service/rst-lldp.rst
index 8aee6183..8aee6183 100644
--- a/docs/configuration/service/lldp.rst
+++ b/docs/configuration/service/rst-lldp.rst
diff --git a/docs/configuration/service/mdns.rst b/docs/configuration/service/rst-mdns.rst
index 8a26722e..8a26722e 100644
--- a/docs/configuration/service/mdns.rst
+++ b/docs/configuration/service/rst-mdns.rst
diff --git a/docs/configuration/service/monitoring.rst b/docs/configuration/service/rst-monitoring.rst
index 8faf0eb8..8faf0eb8 100644
--- a/docs/configuration/service/monitoring.rst
+++ b/docs/configuration/service/rst-monitoring.rst
diff --git a/docs/configuration/service/ntp.rst b/docs/configuration/service/rst-ntp.rst
index f4ccb4b1..f4ccb4b1 100644
--- a/docs/configuration/service/ntp.rst
+++ b/docs/configuration/service/rst-ntp.rst
diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/rst-pppoe-server.rst
index f763536a..f763536a 100644
--- a/docs/configuration/service/pppoe-server.rst
+++ b/docs/configuration/service/rst-pppoe-server.rst
diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/rst-router-advert.rst
index 80f5ae30..80f5ae30 100644
--- a/docs/configuration/service/router-advert.rst
+++ b/docs/configuration/service/rst-router-advert.rst
diff --git a/docs/configuration/service/salt-minion.rst b/docs/configuration/service/rst-salt-minion.rst
index 8638246b..8638246b 100644
--- a/docs/configuration/service/salt-minion.rst
+++ b/docs/configuration/service/rst-salt-minion.rst
diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/rst-snmp.rst
index 6dc13240..6dc13240 100644
--- a/docs/configuration/service/snmp.rst
+++ b/docs/configuration/service/rst-snmp.rst
diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/rst-ssh.rst
index 11f58201..11f58201 100644
--- a/docs/configuration/service/ssh.rst
+++ b/docs/configuration/service/rst-ssh.rst
diff --git a/docs/configuration/service/suricata.rst b/docs/configuration/service/rst-suricata.rst
index b72bc52a..b72bc52a 100644
--- a/docs/configuration/service/suricata.rst
+++ b/docs/configuration/service/rst-suricata.rst
diff --git a/docs/configuration/service/tftp-server.rst b/docs/configuration/service/rst-tftp-server.rst
index 84acf3d4..84acf3d4 100644
--- a/docs/configuration/service/tftp-server.rst
+++ b/docs/configuration/service/rst-tftp-server.rst
diff --git a/docs/configuration/service/webproxy.rst b/docs/configuration/service/rst-webproxy.rst
index a6c5ff0a..a6c5ff0a 100644
--- a/docs/configuration/service/webproxy.rst
+++ b/docs/configuration/service/rst-webproxy.rst
diff --git a/docs/configuration/service/salt-minion.md b/docs/configuration/service/salt-minion.md
new file mode 100644
index 00000000..e430f4fc
--- /dev/null
+++ b/docs/configuration/service/salt-minion.md
@@ -0,0 +1,51 @@
+(saltminion)=
+
+# Salt-Minion
+
+[SaltStack] is Python-based, open-source
+software for event-driven IT automation, remote task execution, and
+configuration management. Supporting the "infrastructure as code"
+approach to data center system and network deployment and management,
+configuration automation, SecOps orchestration, vulnerability remediation,
+and hybrid cloud control.
+
+## Requirements
+
+To use the Salt-Minion, a running Salt-Master is required. You can find more
+in the [Salt Project Documentation](https://docs.saltproject.io/en/latest/contents.html)
+
+## Configuration
+
+```{cfgcmd} set service salt-minion hash \<type\>
+
+   The hash type used when discovering file on master server (default: sha256)
+```
+
+
+```{cfgcmd} set service salt-minion id \<id\>
+
+Explicitly declare ID for this minion to use (default: hostname)
+```
+
+
+```{cfgcmd} set service salt-minion interval \<1-1440\>
+
+Interval in minutes between updates (default: 60)
+```
+
+
+```{cfgcmd} set service salt-minion master \<hostname | IP\>
+
+The hostname or IP address of the master
+```
+
+
+```{cfgcmd} set service salt-minion master-key \<key\>
+
+URL with signature of master for auth reply verification
+```
+
+Please take a look in the Automation section to find some useful
+Examples.
+
+[saltstack]: https://saltproject.io/
diff --git a/docs/configuration/service/snmp.md b/docs/configuration/service/snmp.md
new file mode 100644
index 00000000..ac0429ff
--- /dev/null
+++ b/docs/configuration/service/snmp.md
@@ -0,0 +1,258 @@
+(snmp)=
+
+# SNMP
+
+{abbr}`SNMP (Simple Network Management Protocol)` is an Internet Standard
+protocol for collecting and organizing information about managed devices on
+IP networks and for modifying that information to change device behavior.
+Devices that typically support SNMP include cable modems, routers, switches,
+servers, workstations, printers, and more.
+
+SNMP is widely used in network management for network monitoring. SNMP exposes
+management data in the form of variables on the managed systems organized in
+a management information base ([MIB]) which describe the system status and
+configuration. These variables can then be remotely queried (and, in some
+circumstances, manipulated) by managing applications.
+
+Three significant versions of SNMP have been developed and deployed. SNMPv1 is
+the original version of the protocol. More recent versions, SNMPv2c and SNMPv3,
+feature improvements in performance, flexibility and security.
+
+SNMP is a component of the Internet Protocol Suite as defined by the Internet
+Engineering Task Force (IETF). It consists of a set of standards for network
+management, including an application layer protocol, a database schema, and a
+set of data objects.
+
+## Overview and basic concepts
+
+In typical uses of SNMP, one or more administrative computers called managers
+have the task of monitoring or managing a group of hosts or devices on a
+computer network. Each managed system executes a software component called an
+agent which reports information via SNMP to the manager.
+
+An SNMP-managed network consists of three key components:
+
+- Managed devices
+- Agent - software which runs on managed devices
+- Network management station (NMS) - software which runs on the manager
+
+A managed device is a network node that implements an SNMP interface that
+allows unidirectional (read-only) or bidirectional (read and write) access to
+node-specific information. Managed devices exchange node-specific information
+with the NMSs. Sometimes called network elements, the managed devices can be
+any type of device, including, but not limited to, routers, access servers,
+switches, cable modems, bridges, hubs, IP telephones, IP video cameras,
+computer hosts, and printers.
+
+An agent is a network-management software module that resides on a managed
+device. An agent has local knowledge of management information and translates
+that information to or from an SNMP-specific form.
+
+A network management station executes applications that monitor and control
+managed devices. NMSs provide the bulk of the processing and memory resources
+required for network management. One or more NMSs may exist on any managed
+network.
+
+:::{figure} /_static/images/service_snmp_communication_principles_diagram.webp
+:alt: Principle of SNMP Communication
+:scale: 20 %
+
+Image thankfully borrowed from
+<https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG>
+which is under the GNU Free Documentation License
+:::
+
+:::{note}
+VyOS SNMP supports both IPv4 and IPv6.
+:::
+
+## SNMP Protocol Versions
+
+VyOS itself supports [SNMPv2] (version 2) and [SNMPv3] (version 3) where the
+later is recommended because of improved security (optional authentication and
+encryption).
+
+### SNMPv2
+
+SNMPv2 is the original and most commonly used version. For authorizing clients,
+SNMP uses the concept of communities. Communities may have authorization set
+to read only (this is most common) or to read and write (this option is not
+actively used in VyOS).
+
+SNMP can work synchronously or asynchronously. In synchronous communication,
+the monitoring system queries the router periodically. In asynchronous, the
+router sends notification to the "trap" (the monitoring host).
+
+SNMPv2 does not support any authentication mechanisms, other than client source
+address, so you should specify addresses of clients allowed to monitor the
+router. Note that SNMPv2 also supports no encryption and always sends data in
+plain text.
+
+#### Example
+
+```none
+# Define a community
+set service snmp community routers authorization ro
+
+# Allow monitoring access from the entire network
+set service snmp community routers network 192.0.2.0/24
+set service snmp community routers network 2001::db8:ffff:eeee::/64
+
+# Allow monitoring access from specific addresses
+set service snmp community routers client 203.0.113.10
+set service snmp community routers client 203.0.113.20
+
+# Define optional router information
+set service snmp location "UK, London"
+set service snmp contact "admin@example.com"
+
+# Trap target if you want asynchronous communication
+set service snmp trap-target 203.0.113.10
+
+# Listen only on specific IP addresses (port defaults to 161)
+set service snmp listen-address 172.16.254.36 port 161
+set service snmp listen-address 2001:db8::f00::1
+```
+
+
+### SNMPv3
+
+SNMPv3 (version 3 of the SNMP protocol) introduced a whole slew of new security
+related features that have been missing from the previous versions. Security
+was one of the biggest weakness of SNMP until v3. Authentication in SNMP
+Versions 1 and 2 amounts to nothing more than a password (community string)
+sent in clear text between a manager and agent. Each SNMPv3 message contains
+security parameters which are encoded as an octet string. The meaning of these
+security parameters depends on the security model being used.
+
+The security approach in SNMPv3 targets:
+
+- Confidentiality – Encryption of packets to prevent snooping by an
+  unauthorized source.
+- Integrity – Message integrity to ensure that a packet has not been tampered
+  while in transit including an optional packet replay protection mechanism.
+- Authentication – to verify that the message is from a valid source.
+
+(snmp-v3-example)=
+
+#### Example
+
+- Let SNMP daemon listen only on IP address 192.0.2.1
+- Configure new SNMP user named "vyos" with password "vyos12345678"
+- New user will use SHA/AES for authentication and privacy
+
+```none
+set service snmp listen-address 192.0.2.1
+set service snmp location 'VyOS Datacenter'
+set service snmp v3 engineid '000000000000000000000002'
+set service snmp v3 group default mode 'ro'
+set service snmp v3 group default view 'default'
+set service snmp v3 user vyos auth plaintext-password 'vyos12345678'
+set service snmp v3 user vyos auth type 'sha'
+set service snmp v3 user vyos group 'default'
+set service snmp v3 user vyos privacy plaintext-password 'vyos12345678'
+set service snmp v3 user vyos privacy type 'aes'
+set service snmp v3 view default oid 1
+```
+
+After commit the plaintext passwords will be hashed and stored in your
+configuration. The resulting CLI config will look like:
+
+```none
+vyos@vyos# show service snmp
+ listen-address 192.0.2.1 {
+ }
+ location "VyOS Datacenter"
+ v3 {
+     engineid 000000000000000000000002
+     group default {
+         mode ro
+         view default
+     }
+     user vyos {
+         auth {
+             encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe
+             type sha
+         }
+         group default
+         privacy {
+             encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe
+             type aes
+         }
+     }
+     view default {
+         oid 1 {
+         }
+     }
+ }
+```
+
+You can test the SNMPv3 functionality from any linux based system, just run the
+following command: `snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES
+-X vyos12345678 -l authPriv 192.0.2.1 .1`
+
+## VyOS MIBs
+
+All SNMP MIBs are located in each image of VyOS here: `/usr/share/snmp/mibs/`
+
+You are be able to download the files using SCP, once the SSH service
+has been activated like so
+
+```none
+scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs
+```
+
+
+## SNMP Extensions
+
+To extend SNMP agent functionality, custom scripts can be executed every time
+the agent is being called. This can be achieved by using
+`arbitrary extensioncommands`. The first step is to create a functional
+script of course, then upload it to your VyOS instance via the command
+`scp your_script.sh vyos@your_router:/config/user-data`.
+Once the script is uploaded, it needs to be configured via the command below.
+
+```none
+set service snmp script-extensions extension-name my-extension script your_script.sh
+commit
+```
+
+The OID `.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116`, once called, will
+contain the output of the extension.
+
+```none
+root@vyos:/home/vyos# snmpwalk -v2c  -c public 127.0.0.1 nsExtendOutput1
+NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello
+NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello
+NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1
+NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0
+```
+
+
+## SolarWinds
+
+If you happen to use SolarWinds Orion as NMS you can also use the Device
+Templates Management. A template for VyOS can be easily imported.
+
+Create a file named `VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands` using the
+following content:
+
+```none
+<Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641">
+    <Commands>
+        <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/>
+        <Command Name="Reboot" Value="reboot${CRLF}Yes"/>
+        <Command Name="EnterConfigMode" Value="configure"/>
+        <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/>
+        <Command Name="DownloadConfig" Value="show configuration commands"/>
+        <Command Name="SaveConfig" Value="commit${CRLF}save"/>
+        <Command Name="Version" Value="show version"/>
+        <Command Name="MenuBased" Value="False"/>
+        <Command Name="VirtualPrompt" Value=":~"/>
+    </Commands>
+</Configuration-Management>
+```
+
+[mib]: <https://en.wikipedia.org/wiki/Management_information_base>
+[snmpv2]: <https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2>
+[snmpv3]: <https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3>
diff --git a/docs/configuration/service/ssh.md b/docs/configuration/service/ssh.md
new file mode 100644
index 00000000..d873cbee
--- /dev/null
+++ b/docs/configuration/service/ssh.md
@@ -0,0 +1,366 @@
+(ssh)=
+
+# SSH
+
+{abbr}`SSH (Secure Shell)` is a cryptographic network protocol for operating
+network services securely over an unsecured network. The standard TCP port for
+SSH is 22. The best known example application is for remote login to computer
+systems by users.
+
+SSH provides a secure channel over an unsecured network in a client-server
+architecture, connecting an SSH client application with an SSH server. Common
+applications include remote command-line login and remote command execution,
+but any network service can be secured with SSH. The protocol specification
+distinguishes between two major versions, referred to as SSH-1 and SSH-2.
+
+The most visible application of the protocol is for access to shell accounts
+on Unix-like operating systems, but it sees some limited use on Windows as
+well. In 2015, Microsoft announced that they would include native support for
+SSH in a future release.
+
+SSH was designed as a replacement for Telnet and for unsecured remote shell
+protocols such as the Berkeley rlogin, rsh, and rexec protocols.
+Those protocols send information, notably passwords, in plaintext,
+rendering them susceptible to interception and disclosure using packet
+analysis. The encryption used by SSH is intended to provide confidentiality
+and integrity of data over an unsecured network, such as the Internet.
+
+:::{note}
+VyOS 1.1 supported login as user `root`. This has been removed due
+to tighter security in VyOS 1.2.
+:::
+
+:::{seealso}
+SSH {ref}`ssh_key_based_authentication`
+:::
+
+## Configuration
+
+```{cfgcmd} set service ssh port \<port\>
+
+Enabling SSH only requires you to specify the port ``<port>`` you want SSH to
+listen on. By default, SSH runs on port 22.
+```
+
+
+```{cfgcmd} set service ssh listen-address \<address\>
+
+Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be
+defined.
+```
+
+
+```{cfgcmd} set service ssh cipher \<cipher\>
+
+Define allowed ciphers used for the SSH connection. A number of allowed
+ciphers can be specified, use multiple occurrences to allow multiple ciphers.
+
+List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``,
+``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``,
+``aes128-gcm@openssh.com``, ``aes256-gcm@openssh.com``,
+``chacha20-poly1305@openssh.com``
+```
+
+
+```{cfgcmd} set service ssh disable-password-authentication
+
+Disable password based authentication. Login via SSH keys only. This hardens
+security!
+```
+
+
+```{cfgcmd} set service ssh fido pin-required
+
+Require FIDO2 keys to attest that a user has been verified (e.g. via a PIN).
+```
+
+
+````{cfgcmd} set service ssh fido touch-required
+
+Require FIDO2 keys to attest that a user is physically present.
+
+VyOS supports SSH authentication using FIDO2-backed keys generated by OpenSSH.
+Two FIDO2 key types are supported by OpenSSH: ``ed25519-sk``, ``ecdsa-sk``
+
+Generic FIDO2-backed SSH key generation example:
+
+:::{code-block} none
+ssh-keygen -t ecdsa-sk -O verify-required -C "fido2-ssh-key"
+:::
+
+```{eval-rst}
+During key generation, OpenSSH will:
+    * Request user presence (for example, a physical touch or confirmation)
+    * Optionally request user verification (PIN), if supported by the authenticator
+    * Create a local key handle file and a corresponding public key (``.pub``)
+```
+
+The private key material never leaves the authenticator device.
+
+VyOS configuration example:
+
+:::{code-block} none
+# Generate a FIDO2 SSH key on the client system
+# Copy the public key to the VyOS instance
+set system login user vyos authentication public-keys fido key '<public-key>'
+set system login user vyos authentication public-keys fido type 'sk-ecdsa-sha2-nistp256@openssh.com'
+set service ssh fido touch-required
+:::
+
+You can now log into the system using: ``ssh -i ~/.ssh/id_fido_key vyos@192.0.2.1``
+````
+
+
+```{cfgcmd} set service ssh disable-host-validation
+
+Disable the host validation through reverse DNS lookups - can speedup login
+time when reverse lookup is not possible.
+```
+
+
+```{cfgcmd} set service ssh mac \<mac\>
+
+Specifies the available {abbr}`MAC (Message Authentication Code)` algorithms.
+The MAC algorithm is used in protocol version 2 for data integrity protection.
+Multiple algorithms can be provided by using multiple commands, defining
+one algorithm per command.
+
+List of supported MACs: ``hmac-md5``, ``hmac-md5-96``, ``hmac-ripemd160``,
+``hmac-sha1``, ``hmac-sha1-96``, ``hmac-sha2-256``, ``hmac-sha2-512``,
+``umac-64@openssh.com``, ``umac-128@openssh.com``,
+``hmac-md5-etm@openssh.com``, ``hmac-md5-96-etm@openssh.com``,
+``hmac-ripemd160-etm@openssh.com``, ``hmac-sha1-etm@openssh.com``,
+``hmac-sha1-96-etm@openssh.com``, ``hmac-sha2-256-etm@openssh.com``,
+``hmac-sha2-512-etm@openssh.com``, ``umac-64-etm@openssh.com``,
+``umac-128-etm@openssh.com``
+```
+
+
+```{cfgcmd} set service ssh access-control \<allow | deny\> \<group | user\> \<name\>
+
+Add access-control directive to allow or deny users and groups. Directives
+are processed in the following order of precedence: ``deny-users``,
+``allow-users``, ``deny-groups`` and ``allow-groups``.
+```
+
+
+```{cfgcmd} set service ssh client-keepalive-interval \<interval\>
+
+Specify timeout interval for keepalive message in seconds.
+```
+
+
+```{cfgcmd} set service ssh key-exchange \<kex\>
+
+Specify allowed {abbr}`KEX (Key Exchange)` algorithms.
+
+List of supported algorithms: ``diffie-hellman-group1-sha1``,
+``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``,
+``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``,
+``diffie-hellman-group-exchange-sha1``,
+``diffie-hellman-group-exchange-sha256``,
+``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``,
+``curve25519-sha256`` and ``curve25519-sha256@libssh.org``.
+```
+
+
+```{cfgcmd} set service ssh loglevel \<quiet | fatal | error | info | verbose\>
+
+Set the ``sshd`` log level. The default is ``info``.
+```
+
+
+```{cfgcmd} set service ssh vrf \<name\>
+
+Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance.
+```
+
+
+```{cfgcmd} set service ssh pubkey-accepted-algorithm \<name\>
+
+Specifies the signature algorithms that will be accepted for public key
+authentication
+
+List of supported algorithms: ``ssh-ed25519``,
+``ssh-ed25519-cert-v01@openssh.com``, ``sk-ssh-ed25519@openssh.com``,
+``sk-ssh-ed25519-cert-v01@openssh.com``, ``ecdsa-sha2-nistp256``,
+``ecdsa-sha2-nistp256-cert-v01@openssh.com``, ``ecdsa-sha2-nistp384``,
+``ecdsa-sha2-nistp384-cert-v01@openssh.com``, ``ecdsa-sha2-nistp521``,
+``ecdsa-sha2-nistp521-cert-v01@openssh.com``,
+``sk-ecdsa-sha2-nistp256@openssh.com``,
+``sk-ecdsa-sha2-nistp256-cert-v01@openssh.com``,
+``webauthn-sk-ecdsa-sha2-nistp256@openssh.com``,
+``ssh-dss``, ``ssh-dss-cert-v01@openssh.com``, ``ssh-rsa``,
+``ssh-rsa-cert-v01@openssh.com``, ``rsa-sha2-256``,
+``rsa-sha2-256-cert-v01@openssh.com``, ``rsa-sha2-512``,
+``rsa-sha2-512-cert-v01@openssh.com``
+```
+
+
+```{cfgcmd} set service ssh trusted-user-ca \<name\>
+
+Specify the name of the OpenSSH key-pair that acts as certificate authority
+and will be used to verify user certificates.
+
+You can use it by adding the OpenSSH key-pair under the PKI subsystem.
+
+Example:
+
+:::{code-block} none
+# Generate key-pair acting as CA
+$ ssh-keygen -f vyos-ssh-ca.key
+
+# Generate key for user: vyos_testca
+$ ssh-keygen -f vyos_testca  -C "vyos_tesca@vyos.net"
+
+# Sign public key from user vyos_testca and insert principal names: vyos, vyos_testca
+# with a key lifetime of two weeks - after which the key is unusable
+$ ssh-keygen -s vyos-ssh-ca.key -I vyos_testca@vyos.net -n vyos,vyos_testca -V +2w vyos_testca.pub
+
+$ set system login user vyos_testca
+$ set pki openssh test_ca public key AAAAB3N.....
+$ set pki openssh test_ca public type ssh-rsa
+$ set service ssh trusted-user-ca test_ca
+:::
+You can now log into the system using: ``ssh -i vyos_testca vyos_testca@vyos.test.com``
+```
+
+## Dynamic-protection
+
+Protects host from brute-force attacks against
+SSH. Log messages are parsed, line-by-line, for recognized patterns. If an
+attack, such as several login failures within a few seconds, is detected, the
+offending IP is blocked. Offenders are unblocked after a set interval.
+
+```{cfgcmd} set service ssh dynamic-protection
+
+Allow ``ssh`` dynamic-protection.
+```
+```{cfgcmd} set service ssh dynamic-protection allow-from \<address | prefix\>
+
+Whitelist of addresses and networks. Always allow inbound connections from
+these systems.
+```
+```{cfgcmd} set service ssh dynamic-protection block-time \<sec\>
+
+Block source IP in seconds. Subsequent blocks increase by a factor of 1.5
+The default is 120.
+```
+```{cfgcmd} set service ssh dynamic-protection detect-time \<sec\>
+
+Remember source IP in seconds before reset their score. The default is 1800.
+```
+```{cfgcmd} set service ssh dynamic-protection threshold \<sec\>
+
+Block source IP when their cumulative attack score exceeds threshold. The
+default is 30.
+```
+
+(ssh-operation)=
+
+## Operation
+
+```{opcmd} restart ssh
+
+Restart the SSH daemon process, the current session is not affected, only the
+background daemon is restarted.
+```
+```{opcmd} generate ssh server-key
+
+Re-generated the public/private keyportion which SSH uses to secure
+connections.
+
+:::{note}
+Already learned known_hosts files of clients need an update as the
+public key will change.
+:::
+```
+```{opcmd} generate ssh client-key /path/to/private_key
+
+Re-generated a known pub/private keyfile which can be used to connect to
+other services (e.g. RPKI cache).
+
+Example:
+
+:::{code-block} none
+vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki
+Generating public/private rsa key pair.
+Your identification has been saved in /config/auth/id_rsa_rpki.
+Your public key has been saved in /config/auth/id_rsa_rpki.pub.
+The key fingerprint is:
+SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q vyos@vyos
+The key's randomart image is:
++---[RSA 2048]----+
+|         oo      |
+|          ..o    |
+|       . o.o.. o.|
+|       o+ooo  o.o|
+|        Eo*  =.o |
+|       o = +.o*+ |
+|        = o *.o.o|
+|       o * +.o+.+|
+|        =.. o=.oo|
++----[SHA256]-----+
+:::
+Two new files ``/config/auth/id_rsa_rpki`` and
+``/config/auth/id_rsa_rpki.pub``
+will be created.
+```
+```{opcmd} generate public-key-command user \<username\> path \<location\>
+
+> Generate the configuration mode commands to add a public key for
+> {ref}`ssh_key_based_authentication`.
+> ``<location>`` can be a local path or a URL pointing at a remote file.
+>
+> Supported remote protocols are FTP, FTPS, HTTP, HTTPS, SCP/SFTP and TFTP.
+
+Example:
+
+:::{code-block} none
+alyssa@vyos:~$ generate public-key-command user alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub
+# To add this key as an embedded key, run the following commands:
+configure
+set system login user alyssa authentication public-keys alyssa@example.net key AAA...
+set system login user alyssa authentication public-keys alyssa@example.net type ssh-rsa
+commit
+save
+exit
+
+ben@vyos:~$ generate public-key-command user ben path ~/.ssh/id_rsa.pub
+# To add this key as an embedded key, run the following commands:
+configure
+set system login user ben authentication public-keys ben@vyos key AAA...
+set system login user ben authentication public-keys ben@vyos type ssh-dss
+commit
+save
+exit
+:::
+```
+```{opcmd} show log ssh
+
+Show SSH server log.
+```
+```{opcmd} monitor log ssh
+
+Follow the SSH server log.
+```
+```{opcmd} show log ssh dynamic-protection
+
+Show SSH dynamic-protection log.
+```
+```{opcmd} monitor log ssh dynamic-protection
+
+Follow the SSH dynamic-protection log.
+```
+```{opcmd} show ssh dynamic-protection
+
+Show list of IPs currently blocked by SSH dynamic-protection.
+```
+```{opcmd} show ssh fingerprints
+
+Show SSH server public key fingerprints.
+```
+```{opcmd} show ssh fingerprints ascii
+
+Show SSH server public key fingerprints, including a visual ASCII art representation.
+```
\ No newline at end of file
diff --git a/docs/configuration/service/suricata.md b/docs/configuration/service/suricata.md
new file mode 100644
index 00000000..ca9ae968
--- /dev/null
+++ b/docs/configuration/service/suricata.md
@@ -0,0 +1,93 @@
+(suricata)=
+
+# suricata
+
+Suricata and VyOS are powerful tools for ensuring network security and traffic management.
+Suricata is an open-source intrusion detection and prevention system (IDS/IPS) that analyzes network packets in real-time.
+
+## Suricata Features
+
+Intrusion Detection (IDS): Analyzes network traffic and detects suspicious activities, attacks, and malicious traffic.
+Intrusion Prevention (IPS): Blocks or modifies suspicious traffic in real-time, preventing attacks before they penetrate the network.
+Network Security Monitoring (NSM): Collects and analyzes network data to detect anomalies and identify threats.
+Multi-Protocol Support: Suricata supports analysis of various network protocols such as HTTP, FTP, SMB, and many others.
+In configuration mode, the commands are as follows:
+
+```none
+vyos@vyos# set service suricata
+Possible completions:
++> address-group        Address group name
++  interface            Interface to use
+ > log                  Suricata log outputs
++> port-group           Port group name
+```
+
+These commands create a flexible interface for configuring the Suricata service, allowing users to specify addresses, ports,
+and logging parameters.
+
+After completing the service configuration in configuration mode, the main configuration file suricata.yaml is created,
+into which all specified parameters are added. Then, to ensure proper operation, the command {opcmd}`update suricata` must be run
+from operational mode, waiting for Suricata to update all its rules, which are used for analyzing traffic for threats and attacks.
+
+## Configuration
+
+```{cfgcmd} set service suricata address-group \<text\> \<address | group\>
+
+   Address groups are useful when you need to create rules that apply to specific IP addresses.
+   For example, if you want to create a rule that monitors traffic going to or from a specific IP address,
+   you can use the group name instead of the actual IP address. This simplifies rule management and makes the
+   configuration more flexible.
+
+   * ``address`` IP address or subnet.
+
+   * ``group``  Address group.
+```
+
+
+```{cfgcmd} set service suricata port-group \<text\> \<address | group\>
+
+Port groups are useful when you need to create rules that apply to specific ports.
+For example, if you want to create a rule that monitors traffic directed to a specific port or group of ports,
+you can use the group name instead of the actual port. This also simplifies rule management and makes
+the configuration more flexible.
+
+* ``port``  Port number.
+
+* ``group``  Port group.
+```
+
+
+```{cfgcmd} set service suricata interface \<text\>
+
+The interface that will be monitored by the Suricata service.
+```
+```{cfgcmd} set service suricata log eve \<filename | filetype | type\>
+
+   Configuration of the logging file.
+
+   * ``filename``  Log file (default: eve.json).
+
+   * ``filetype``  EVE logging destination (default: regular).
+
+   * ``type``  Log types.
+```
+
+## Operation Mode
+
+```{cfgcmd} update suricata
+
+Checks for the existence of the Suricata configuration file, updates the service,
+and then restarts it. If the configuration file is not found, a message indicates that Suricata is not configured.
+```
+```{cfgcmd} restart suricata
+
+Restarts the service. It checks if the Suricata service is active before attempting to restart it.
+If it is not active, a message indicates that the service is not configured. This command is used when adding new rules manually.
+```
+
+## Conclusion
+
+Using address and port groups allows you to make your Suricata configuration more flexible and manageable.
+Instead of specifying IP addresses and ports directly in each rule, you can define them once in the vars section and then
+reference them by group names. This is especially useful in large networks and complex configurations where multiple IP addresses
+and ports need to be monitored.
diff --git a/docs/configuration/service/tftp-server.md b/docs/configuration/service/tftp-server.md
new file mode 100644
index 00000000..f4a6c34c
--- /dev/null
+++ b/docs/configuration/service/tftp-server.md
@@ -0,0 +1,78 @@
+(tftp-server)=
+
+# TFTP Server
+
+{abbr}`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file
+transfer protocol which allows a client to get a file from or put a file onto
+a remote host. One of its primary uses is in the early stages of nodes booting
+from a local area network. TFTP has been used for this application because it
+is very simple to implement.
+
+## Configuration
+
+```{cfgcmd} set service tftp-server directory \<directory\>
+
+Enable TFTP service by specifying the `<directory>` which will be used to serve
+files.
+```
+
+:::{hint}
+Choose your `directory` location carefully or you will loose the
+content on image upgrades. Any directory under `/config` is save at this
+will be migrated.
+:::
+
+```{cfgcmd} set service tftp-server listen-address \<address\>
+
+Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and
+IPv6 addresses can be given. There will be one TFTP server instances listening
+on each IP address.
+```
+
+```{cfgcmd} set service tftp-server listen-address \<address\> vrf \<name\>
+```
+
+Additional option to run TFTP server in the {abbr}`VRF (Virtual Routing and Forwarding)` context
+
+:::{note}
+Configuring a listen-address is essential for the service to work.
+:::
+```{cfgcmd} set service tftp-server allow-upload
+
+Optional, if you want to enable uploads, else TFTP server will act as a
+read-only server.
+```
+
+### Example
+
+Provide TFTP server listening on both IPv4 and IPv6 addresses `192.0.2.1` and
+`2001:db8::1` serving the content from `/config/tftpboot`. Uploading via
+TFTP to this server is disabled.
+
+The resulting configuration will look like:
+
+```none
+vyos@vyos# show service
+ tftp-server {
+    directory /config/tftpboot
+    listen-address 2001:db8::1
+    listen-address 192.0.2.1
+ }
+```
+
+### Verification
+
+Client:
+
+```none
+vyos@RTR2:~$ tftp -p -l /config/config.boot -r backup 192.0.2.1
+backup1             100% |******************************|   723  0:00:00 ETA
+```
+
+Server:
+
+```none
+vyos@RTR1# ls -ltr /config/tftpboot/
+total 1
+-rw-rw-rw- 1 tftp tftp  1995 May 19 16:02 backup
+```
diff --git a/docs/configuration/service/webproxy.md b/docs/configuration/service/webproxy.md
new file mode 100644
index 00000000..28156b2b
--- /dev/null
+++ b/docs/configuration/service/webproxy.md
@@ -0,0 +1,459 @@
+(webproxy)=
+
+# Webproxy
+
+The proxy service in VyOS is based on [Squid] and some related modules.
+
+[Squid] is a caching and forwarding HTTP web proxy. It has a wide variety of
+uses, including speeding up a web server by caching repeated requests, caching
+web, DNS and other computer network lookups for a group of people sharing
+network resources, and aiding security by filtering traffic. Although primarily
+used for HTTP and FTP, Squid includes limited support for several other
+protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does not
+support the SOCKS protocol.
+
+URL Filtering is provided by [SquidGuard].
+
+## Configuration
+
+```{cfgcmd} set service webproxy append-domain \<domain\>
+
+Use this command to specify a domain name to be appended to domain-names
+within URLs that do not include a dot ``.`` the domain is appended.
+
+Example: to be appended is set to ``vyos.net`` and the URL received is
+``www/foo.html``, the system will use the generated, final URL of
+``www.vyos.net/foo.html``.
+
+:::{code-block} none
+set service webproxy append-domain vyos.net
+:::
+```
+
+
+```{cfgcmd} set service webproxy cache-size \<size\>
+
+The size of the on-disk Proxy cache is user configurable. The Proxies default
+cache-size is configured to 100 MB.
+
+Unit of this command is MB.
+
+:::{code-block} none
+set service webproxy cache-size 1024
+:::
+```
+
+
+```{cfgcmd} set service webproxy default-port \<port\>
+
+Specify the port used on which the proxy service is listening for requests.
+This port is the default port used for the specified listen-address.
+
+Default port is 3128.
+
+:::{code-block} none
+set service webproxy default-port 8080
+:::
+```
+
+
+```{cfgcmd} set service webproxy domain-block \<domain\>
+
+Used to block specific domains by the Proxy. Specifying "vyos.net" will block
+all access to vyos.net, and specifying ".xxx" will block all access to URLs
+having an URL ending on .xxx.
+
+:::{code-block} none
+set service webproxy domain-block vyos.net
+:::
+```
+
+
+```{cfgcmd} set service webproxy domain-noncache \<domain\>
+
+Allow access to sites in a domain without retrieving them from the Proxy
+cache. Specifying "vyos.net" will allow access to vyos.net but the pages
+accessed will not be cached. It useful for working around problems with
+"If-Modified-Since" checking at certain sites.
+
+:::{code-block} none
+set service webproxy domain-noncache vyos.net
+:::
+```
+
+
+```{cfgcmd} set service webproxy listen-address \<address\>
+
+Specifies proxy service listening address. The listen address is the IP
+address on which the web proxy service listens for client requests.
+
+For security, the listen address should only be used on internal/trusted
+networks!
+
+:::{code-block} none
+set service webproxy listen-address 192.0.2.1
+:::
+```
+
+
+```{cfgcmd} set service webproxy listen-address \<address\> disable-transparent
+
+Disables web proxy transparent mode at a listening address.
+
+In transparent proxy mode, all traffic arriving on port 80 and destined for
+the Internet is automatically forwarded through the proxy. This allows
+immediate proxy forwarding without configuring client browsers.
+
+Non-transparent proxying requires that the client browsers be configured with
+the proxy settings before requests are redirected. The advantage of this is
+that the client web browser can detect that a proxy is in use and can behave
+accordingly. In addition, web-transmitted malware can sometimes be blocked by
+a non-transparent web proxy, since they are not aware of the proxy settings.
+
+:::{code-block} none
+set service webproxy listen-address 192.0.2.1 disable-transparent
+:::
+```
+
+
+```{cfgcmd} set service webproxy listen-address \<address\> port \<port\>
+
+Sets the listening port for a listening address. This overrides the default
+port of 3128 on the specific listen address.
+
+:::{code-block} none
+set service webproxy listen-address 192.0.2.1 port 8080
+:::
+```
+```{cfgcmd} set service webproxy reply-block-mime \<mime\>
+
+Used to block a specific mime-type.
+
+:::{code-block} none
+# block all PDFs
+set service webproxy reply-block-mime application/pdf
+:::
+```
+```{cfgcmd} set service webproxy reply-body-max-size \<size\>
+
+Specifies the maximum size of a reply body in KB, used to limit the reply
+size.
+
+All reply sizes are accepted by default.
+
+:::{code-block} none
+set service webproxy reply-body-max-size 2048
+:::
+```
+
+
+```{cfgcmd} set service webproxy safe-ports \<port\>
+
+Add new port to Safe-ports acl. Ports included by default in Safe-ports acl:
+21, 70, 80, 210, 280, 443, 488, 591, 777, 873, 1025-65535
+```
+
+
+```{cfgcmd} set service webproxy ssl-safe-ports \<port\>
+
+Add new port to SSL-ports acl. Ports included by default in SSL-ports acl:
+443
+```
+
+### Authentication
+
+The embedded Squid proxy can use LDAP to authenticate users against a company
+wide directory. The following configuration is an example of how to use Active
+Directory as authentication backend. Queries are done via LDAP.
+
+```{cfgcmd} set service webproxy authentication children \<number\>
+
+Maximum number of authenticator processes to spawn. If you start too few
+Squid will have to wait for them to process a backlog of credential
+verifications, slowing it down. When password verifications are done via a
+(slow) network you are likely to need lots of authenticator processes.
+
+This defaults to 5.
+
+:::{code-block} none
+set service webproxy authentication children 10
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication credentials-ttl \<time\>
+
+Specifies how long squid assumes an externally validated username:password
+pair is valid for - in other words how often the helper program is called for
+that user. Set this low to force revalidation with short lived passwords.
+
+Time is in minutes and defaults to 60.
+
+:::{code-block} none
+set service webproxy authentication credentials-ttl 120
+:::
+```
+```{cfgcmd} set service webproxy authentication method \<ldap\>
+
+Proxy authentication method, currently only LDAP is supported.
+
+:::{code-block} none
+set service webproxy authentication method ldap
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication realm
+
+Specifies the protection scope (aka realm name) which is to be reported to
+the client for the authentication scheme. It is commonly part of the text
+the user will see when prompted for their username and password.
+
+:::{code-block} none
+set service webproxy authentication realm "VyOS proxy auth"
+:::
+```
+
+#### LDAP
+
+```{cfgcmd} set service webproxy authentication ldap base-dn \<base-dn\>
+
+Specifies the base DN under which the users are located.
+
+:::{code-block} none
+set service webproxy authentication ldap base-dn DC=vyos,DC=net
+:::
+```
+```{cfgcmd} set service webproxy authentication ldap bind-dn \<bind-dn\>
+
+The DN and password to bind as while performing searches.
+
+:::{code-block} none
+set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap filter-expression \<expr\>
+
+LDAP search filter to locate the user DN. Required if the users are in a
+hierarchy below the base DN, or if the login name is not what builds the user
+specific part of the users DN.
+
+The search filter can contain up to 15 occurrences of %s which will be
+replaced by the username, as in "uid=%s" for {rfc}`2037` directories. For a
+detailed description of LDAP search filter syntax see {rfc}`2254`.
+
+:::{code-block} none
+set service webproxy authentication ldap filter-expression (cn=%s)
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap password \<password\>
+
+The DN and password to bind as while performing searches. As the password
+needs to be printed in plain text in your Squid configuration it is strongly
+recommended to use a account with minimal associated privileges. This to limit
+the damage in case someone could get hold of a copy of your Squid
+configuration file.
+
+:::{code-block} none
+set service webproxy authentication ldap password vyos
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap persistent-connection
+
+Use a persistent LDAP connection. Normally the LDAP connection is only open
+while validating a username to preserve resources at the LDAP server. This
+option causes the LDAP connection to be kept open, allowing it to be reused
+for further user validations.
+
+Recommended for larger installations.
+
+:::{code-block} none
+set service webproxy authentication ldap persistent-connection
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap port \<port\>
+
+Specify an alternate TCP port where the ldap server is listening if other than
+the default LDAP port 389.
+
+:::{code-block} none
+set service webproxy authentication ldap port 389
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap server \<server\>
+
+Specify the LDAP server to connect to.
+
+:::{code-block} none
+set service webproxy authentication ldap server ldap.vyos.net
+:::
+```
+```{cfgcmd} set service webproxy authentication ldap use-ssl
+
+Use TLS encryption.
+
+:::{code-block} none
+set service webproxy authentication ldap use-ssl
+:::
+```
+```{cfgcmd} set service webproxy authentication ldap username-attribute \<attr\>
+
+Specifies the name of the DN attribute that contains the username/login.
+Combined with the base DN to construct the users DN when no search filter is
+specified (filter-expression).
+
+Defaults to 'uid'
+
+:::{note}
+This can only be done if all your users are located directly under
+the same position in the LDAP tree and the login name is used for naming
+each user object. If your LDAP tree does not match these criterias or if you
+want to filter who are valid users then you need to use a search filter to
+search for your users DN (filter-expression).
+:::
+
+:::{code-block} none
+set service webproxy authentication ldap username-attribute uid
+:::
+```
+
+
+```{cfgcmd} set service webproxy authentication ldap version \<2 | 3\>
+
+LDAP protocol version. Defaults to 3 if not specified.
+
+:::{code-block} none
+set service webproxy authentication ldap version 2
+:::
+```
+
+### URL filtering
+
+```{include} /_include/need_improvement.txt
+```
+```{cfgcmd} set service webproxy url-filtering disable
+
+Disables web filtering without discarding configuration.
+
+:::{code-block} none
+set service webproxy url-filtering disable
+:::
+```
+
+## Operation
+
+```{include} /_include/need_improvement.txt
+```
+
+### Filtering
+#### Update
+
+If you want to use existing blacklists you have to create/download a database
+first. Otherwise you will not be able to commit the config changes.
+
+```{opcmd} update webproxy blacklists
+
+Download/Update complete blacklist
+
+:::{code-block} none
+vyos@vyos:~$ update webproxy blacklists
+Warning: No url-filtering blacklist installed
+Would you like to download a default blacklist? [confirm][y]
+Connecting to ftp.univ-tlse1.fr (193.49.48.249:21)
+blacklists.gz        100% |*************************************************************************************************************| 17.0M  0:00:00 ETA
+Uncompressing blacklist...
+Checking permissions...
+Skip link for   [ads] -> [publicite]
+Building DB for [adult/domains] - 2467177 entries
+Building DB for [adult/urls] - 67798 entries
+Skip link for   [aggressive] -> [agressif]
+Building DB for [agressif/domains] - 348 entries
+Building DB for [agressif/urls] - 36 entries
+Building DB for [arjel/domains] - 69 entries
+...
+Building DB for [webmail/domains] - 374 entries
+Building DB for [webmail/urls] - 9 entries
+The webproxy daemon must be restarted
+Would you like to restart it now? [confirm][y]
+[ ok ] Restarting squid (via systemctl): squid.service.
+vyos@vyos:~$
+:::
+```
+```{opcmd} update webproxy blacklists category \<category\>
+
+Download/Update partial blacklist.
+
+Use tab completion to get a list of categories.
+```
+
+- To auto update the blacklist files
+
+  `set service webproxy url-filtering squidguard auto-update update-hour 23`
+
+- To configure blocking add the following to the configuration
+
+  `set service webproxy url-filtering squidguard block-category ads`
+
+  `set service webproxy url-filtering squidguard block-category malware`
+
+#### Bypassing the webproxy
+
+```{include} /_include/need_improvement.txt
+```
+
+Some services don't work correctly when being handled via a web proxy.
+So sometimes it is useful to bypass a transparent proxy:
+
+- To bypass the proxy for every request that is directed to a specific
+  destination:
+
+  `set service webproxy whitelist destination-address 198.51.100.33`
+
+  `set service webproxy whitelist destination-address 192.0.2.0/24`
+
+- To bypass the proxy for every request that is coming from a specific source:
+
+  `set service webproxy whitelist source-address 192.168.1.2`
+
+  `set service webproxy whitelist source-address 192.168.2.0/24`
+
+  (This can be useful when a called service has many and/or often changing
+  destination addresses - e.g. Netflix.)
+
+## Examples
+
+```none
+vyos@vyos# show service webproxy
+ authentication {
+     children 5
+     credentials-ttl 60
+     ldap {
+         base-dn DC=example,DC=local
+         bind-dn CN=proxyuser,CN=Users,DC=example,DC=local
+         filter-expression (cn=%s)
+         password Qwert1234
+         server ldap.example.local
+         username-attribute cn
+     }
+     method ldap
+     realm "VyOS Webproxy"
+ }
+ cache-size 100
+ default-port 3128
+ listen-address 192.168.188.103 {
+     disable-transparent
+ }
+```
+
+[squid]: http://www.squid-cache.org/
+[squidguard]: http://www.squidguard.org/