From 8943fc9f877cbee3301a8261ddd27b4b1f15f174 Mon Sep 17 00:00:00 2001
From: rebortg <github@ghlr.de>
Date: Mon, 30 Nov 2020 20:53:36 +0100
Subject: arrange services and protocols

---
 docs/configuration/service/dhcp-server.rst | 776 +++++++++++++++++++++++++++++
 1 file changed, 776 insertions(+)
 create mode 100644 docs/configuration/service/dhcp-server.rst

(limited to 'docs/configuration/service/dhcp-server.rst')

diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst
new file mode 100644
index 00000000..56316793
--- /dev/null
+++ b/docs/configuration/service/dhcp-server.rst
@@ -0,0 +1,776 @@
+.. _dhcp:
+
+#############
+DHCP / DHCPv6
+#############
+
+VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment.
+
+.. _dhcp-server:
+
+DHCP 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 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> 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> dns-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> 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> 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).
+
+
+Failover
+^^^^^^^^
+
+VyOS provides support for DHCP failover. DHCP failover must be configured
+explicitly by the following statements.
+
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover local-address <address>
+
+   Local IP `<address>` used when communicating to the failover peer.
+
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover peer-address <address>
+
+   Remote peer IP `<address>` of the second DHCP server in this failover cluster.
+
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover name <name>
+
+   A generic `<name>` referencing this sync service.
+
+   .. note:: `<name>` must be identical on both sides!
+
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover 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 failover 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 failover peers whose communications traverse insecure networks, then we
+      recommend that you consider the use of VPN tunneling between them to ensure
+      that the failover 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 <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> 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.
+
+
+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
+   * - dns-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
+   * - smtp-server
+     - 69
+     - smtp-server
+     - IP address of SMTP server
+     - Y
+   * - pop-server
+     - 70
+     - pop-server
+     - IP address of POP3 server
+     - Y
+   * - domain-search
+     - 119
+     - domain-search
+     - Client domain search
+     - Y
+   * - static-route
+     - 121, 249
+     - rfc3442-static-route, windows-static-route
+     - Classless static route
+     - N
+   * - wpad-url
+     - 252
+     - wpad-url, wpad-url code 252 = text
+     - Web Proxy Autodiscovery (WPAD) URL
+     - N
+   * - lease
+     -
+     - default-lease-time, max-lease-time
+     - Lease timeout in seconds (default: 86400)
+     - N
+   * - range
+     -
+     - range
+     - DHCP lease range
+     - Y
+   * - exclude
+     -
+     -
+     - IP address to exclude from DHCP lease range
+     - Y
+   * - failover
+     -
+     -
+     - DHCP failover parameters
+     -
+   * - static-mapping
+     -
+     -
+     - Name of static mapping
+     - Y
+
+Multi: can be specified multiple times.
+
+
+Raw Parameters
+^^^^^^^^^^^^^^
+
+Raw parameters can be passed to shared-network-name, subnet and static-mapping:
+
+.. code-block:: none
+
+  set service dhcp-server shared-network-name <name> shared-network-parameters
+     <text>       Additional shared-network parameters for DHCP server.
+  set service dhcp-server shared-network-name <name> subnet <subnet> subnet-parameters
+     <text>       Additional subnet parameters for DHCP server.
+  set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> static-mapping-parameters
+     <text>       Additional static-mapping parameters for DHCP server.
+                  Will be placed inside the "host" block of the mapping.
+
+These parameters are passed as-is to isc-dhcp's dhcpd.conf under the
+configuration node they are defined in. They are not validated so an error in
+the raw parameters won't be caught by vyos's scripts and will cause dhcpd to
+fail to start. Always verify that the parameters are correct before committing
+the configuration. Refer to isc-dhcp's dhcpd.conf manual for more information:
+https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf
+
+Quotes can be used inside parameter values by replacing all quote characters
+with the string ``&quot;``. They will be replaced with literal quote characters
+when generating dhcpd.conf.
+
+
+Example
+^^^^^^^
+
+Quick-Start
+"""""""""""
+
+* We are offering address space in the `192.0.2.0/24` network.
+* We are using the network name `mypool`.
+
+.. code-block:: none
+
+  set service dhcp-server shared-network-name mypool authoritative
+  set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 default-router 192.0.2.1
+  set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 dns-server 192.0.2.1
+  set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 lease 86400
+  set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 range 0 start 192.0.2.100
+  set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 range 0 stop 192.0.2.199
+
+The generated config will look like:
+
+.. code-block:: none
+
+  vyos@vyos# show service dhcp-server shared-network-name mypool
+  authoritative
+  subnet 192.0.2.0/24 {
+      default-router 192.0.2.1
+      dns-server 192.0.2.1
+      lease 86400
+      range 0 {
+          start 192.0.2.100
+          stop 192.0.2.199
+      }
+  }
+
+
+Failover
+""""""""
+
+* Setup DHCP failover for network 192.0.2.0/24
+* Default gateway and DNS server is at `192.0.2.254`
+* The primary DHCP server uses address `192.168.189.252`
+* The secondary DHCP server uses address `192.168.189.253`
+* DHCP range spans from `192.168.189.10` - `192.168.189.250`
+
+**Primary**
+
+.. code-block:: none
+
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 default-router '192.0.2.254'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 dns-server '192.0.2.254'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 domain-name 'vyos.net'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover local-address '192.168.189.252'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover name 'NET-VYOS'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover peer-address '192.168.189.253'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover status 'primary'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.168.189.10'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.168.189.250'
+
+**Secondary**
+
+.. code-block:: none
+
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 default-router '192.0.2.254'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 dns-server '192.0.2.254'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 domain-name 'vyos.net'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover local-address '192.168.189.253'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover name 'NET-VYOS'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover peer-address '192.168.189.252'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover status 'primary'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.168.189.10'
+  set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.168.189.250'
+
+
+Raw Parameters
+""""""""""""""
+
+* Override static-mapping's dns-server with a custom one that will be sent only
+  to this host.
+* An option that takes a quoted string is set by replacing all quote characters
+  with the string ``&quot;`` inside the static-mapping-parameters value.
+  The resulting line in dhcpd.conf will be
+  ``option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";``.
+
+
+.. code-block:: none
+
+  set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;"
+  set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile &quot;pxelinux.cfg/01-00-15-17-44-2d-aa&quot;;"
+
+
+
+Operation Mode
+--------------
+
+.. opcmd:: restart dhcp server
+
+   Restart the DHCP server
+
+.. opcmd:: show dhcp server statistics
+
+   Show the DHCP server statistics:
+
+.. code-block:: 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:
+
+.. code-block:: none
+
+  vyos@vyos:~$ show dhcp server leases
+  IP address      Hardware address    State    Lease start          Lease expiration     Remaining   Pool         Hostname
+  --------------  ------------------  -------  -------------------  -------------------  ----------  -----------  ---------
+  192.0.2.104     aa:bb:cc:dd:ee:ff   active   2019/12/05 14:24:23  2019/12/06 02:24:23  6:05:35     dhcpexample  test1
+  192.0.2.115     ab:ac:ad:ae:af:bf   active   2019/12/05 18:02:37  2019/12/06 06:02:37  9:43:49     dhcpexample  test2
+
+.. hint:: Static mappings aren't shown. To show all states, use
+   ``show dhcp server leases state all``.
+
+.. opcmd:: show dhcp server leases pool <pool>
+
+   Show only leases in the specified pool.
+
+.. 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)
+
+DHCPv6 Server
+=============
+
+VyOS also provides DHCPv6 server functionality which is described in this
+section.
+
+Configuration Options
+---------------------
+
+.. 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 <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> 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> 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> nis-server <address>
+
+   Specify a NIS server address for DHCPv6 clients.
+
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nisplus-server <address>
+
+   Specify a NIS+ server address for DHCPv6 clients.
+
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sip-server <address | fqdn>
+
+   Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6
+   address of Fully Qualified Domain Name for all DHCPv6 clients.
+
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sntp-server-address <address>
+
+   A SNTP server address can be specified for DHCPv6 clients.
+
+Prefix Delegation
+^^^^^^^^^^^^^^^^^
+
+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 start <address> prefix-length <length>
+
+   Hand out prefixes of size `<length>` to clients in subnet `<prefix>` when
+   they request for prefix delegation.
+
+.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> prefix-delegation start <address> stop <address>
+
+   Delegate prefixes from the range indicated by the start and stop qualifier.
+
+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
+
+.. code-block:: none
+
+  set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 address-range start 2001:db8::100 stop 2001:db8::199
+  set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 name-server 2001:db8::ffff
+
+The configuration will look as follows:
+
+.. code-block:: none
+
+  show service dhcpv6-server
+      shared-network-name NET1 {
+          subnet 2001:db8::/64 {
+             address-range {
+                start 2001:db8::100 {
+                   stop 2001:db8::199
+                }
+             }
+             name-server 2001:db8::ffff
+          }
+      }
+
+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
+* 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.
+
+.. code-block:: 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 identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff
+
+The configuration will look as follows:
+
+.. code-block:: none
+
+  show service dhcp-server shared-network-name NET1
+     shared-network-name NET1 {
+         subnet 2001:db8::/64 {
+            name-server 2001:db8:111::111
+            address-range {
+                start 2001:db8::100 {
+                   stop 2001:db8::199 {
+                }
+            }
+            static-mapping client1 {
+               ipv6-address 2001:db8::101
+               identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff
+            }
+         }
+      }
+
+Operation Mode
+--------------
+
+.. opcmd:: restart dhcpv6 server
+
+   To restart the DHCPv6 server
+
+.. opcmd:: show dhcpv6 server status
+
+   To show the current status of the DHCPv6 server.
+
+.. opcmd:: show dhcpv6 server leases
+
+   Show statuses of all assigned leases:
+
+.. code-block:: none
+
+  vyos@vyos:~$ show dhcpv6 server leases
+  IPv6 address   State    Last communication    Lease expiration     Remaining    Type           Pool   IAID_DUID
+  -------------  -------  --------------------  -------------------  -----------  -------------  -----  --------------------------------------------
+  2001:db8::101  active   2019/12/05 19:40:10   2019/12/06 07:40:10  11:45:21     non-temporary  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      non-temporary  NET1   87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff
+
+.. hint:: Static mappings aren't shown. To show all states, use ``show dhcp
+   server leases state all``.
+
+.. 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)
+
+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.
+
+Configuration
+-------------
+
+.. cfgcmd:: set service dhcp-relay interface <interface>
+
+   Enable the DHCP relay service on the given interface.
+
+.. 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.
+
+Example
+-------
+
+* Listen for DHCP requests on interface ``eth1``.
+* DHCP server is located at IPv4 address 10.0.1.4.
+* Router receives DHCP client requests on ``eth1`` and relays them to the server at 10.0.1.4.
+
+.. figure:: /_static/images/service_dhcp-relay01.png
+   :scale: 80 %
+   :alt: DHCP relay example
+
+   DHCP relay example
+
+The generated configuration will look like:
+
+.. code-block:: none
+
+  show service dhcp-relay
+      interface eth1
+      server 10.0.1.4
+      relay-options {
+         relay-agents-packets discard
+      }
+
+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-packet <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.
+
+Operation
+---------
+
+.. opcmd:: restart dhcp relay-agent
+
+   Restart DHCP relay service
+
+DHCPv6 relay
+============
+
+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.
+
+Example
+^^^^^^^
+
+* DHCPv6 requests are received by the router on `listening interface` ``eth1``
+* Requests are forwarded through ``eth2`` as the `upstream interface`
+* External DHCPv6 server is at 2001:db8::4
+
+.. figure:: /_static/images/service_dhcpv6-relay01.png
+   :scale: 80 %
+   :alt: DHCPv6 relay example
+
+   DHCPv6 relay example
+
+The generated configuration will look like:
+
+.. code-block:: none
+
+  commit
+  show service dhcpv6-relay
+      listen-interface eth1 {
+      }
+      upstream-interface eth2 {
+         address 2001:db8::4
+      }
+
+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.
+
+Operation
+---------
+
+.. opcmd:: show dhcpv6 relay-agent status
+
+   Show the current status of the DHCPv6 relay agent:
+
+.. opcmd:: restart dhcpv6 relay-agent
+
+   Restart DHCPv6 relay agent immediately.
-- 
cgit v1.2.3