Merge pull request #414 from KF5JWC/master

Split dhcp-relay docs out of dhcp-server page (Was: "Remove empty, duplicate "dhcp-relay" page")

1 files changed, 159 insertions, 2 deletions

diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst
index 445519b3..5355a0fd 100644
--- a/docs/configuration/service/dhcp-relay.rst
+++ b/docs/configuration/service/dhcp-relay.rst
@@ -1,2 +1,159 @@
-dhcp-relay
-##########
\ No newline at end of file
+.. _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.
+
+**********
+IPv4 relay
+**********
+
+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.
+
+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.
+
+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
+      }
+
+Operation
+=========
+
+.. opcmd:: restart dhcp relay-agent
+
+   Restart DHCP relay service
+
+**********
+IPv6 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.
+
+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.
+
+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
+      }
+
+Operation
+=========
+
+.. opcmd:: restart dhcpv6 relay-agent
+
+   Restart DHCPv6 relay agent immediately.