From c25c40dfa96dfeb022b203280c607c1f1835417b Mon Sep 17 00:00:00 2001 From: Robert Göhler Date: Sun, 24 Jan 2021 22:14:00 +0100 Subject: Migrate new file structure to crux (#435) * order workflows and add submodule * rename gitmodules file * delete docs/.gitignore * add vyos custom linter * correct __pycache__ in gitignore * add test-coverage.py * move draw.io folder * arrange changelog, install history and about * arrange: firewall * arrange: highavailability * arrange: loadbalancing * arrange: nat * arrange: services * sort configexamples and configuration interfaces * wireles: rename wireless * rearrange: Protocols and Policy * rearrange: Firewall and Zone Policy * rearrange: Interfaces * rearrange: Interfaces * rearrange: dynamic DNS * hostinfo: add page to index * rearrange: appendix * venv: add Pipfile * rearrange: contributing * index: remove debugging * rearrange: fix all figure and refs * rearrange: commandtree * fix: cli, openvpn, install headline level * protocols: change headline * firewall: move mss clamping * ip: separate ipv4 and ipv6 * arp: move to static page * igmp: rename multicast page * Update to year 2021 --- docs/configuration/service/dhcp-relay.rst | 165 ++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 docs/configuration/service/dhcp-relay.rst (limited to 'docs/configuration/service/dhcp-relay.rst') diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst new file mode 100644 index 00000000..0b838442 --- /dev/null +++ b/docs/configuration/service/dhcp-relay.rst @@ -0,0 +1,165 @@ + + +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. See +https://wiki.vyos.net/wiki/Network_address_setup. + +DHCP relay example +^^^^^^^^^^^^^^^^^^ + +.. figure:: /_static/images/service_dhcp-relay01.png + :scale: 80 % + :alt: DHCP relay example + + DHCP relay example + +In this example the interfaces used for the DHCP relay are eth1 and eth2. The +router receives DHCP client requests on eth1 and relays them through eth2 to +the DHCP server at 10.0.1.4. + +Configuration +^^^^^^^^^^^^^ + +Enable DHCP relay for eth1 and eth2: + +.. code-block:: none + + set service dhcp-relay interface eth1 + set service dhcp-relay interface eth2 + +Set the IP address of the DHCP server: + +.. code-block:: none + + set service dhcp-relay server 10.0.1.4 + +The router should discard DHCP packages already containing relay agent +information to ensure that only requests from DHCP clients are forwarded: + +.. code-block:: none + + set service dhcp-relay relay-options relay-agents-packets discard + +Commit the changes and show the results: + +.. code-block:: none + + commit + show service dhcp-relay + interface eth1 + interface eth2 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } + +The DHCP relay agent can be restarted with: + +.. code-block:: none + + restart dhcp relay-agent + +DHCPv6 relay example +^^^^^^^^^^^^^^^^^^^^ + +.. figure:: /_static/images/service_dhcpv6-relay01.png + :scale: 80 % + :alt: DHCPv6 relay example + + DHCPv6 relay example + +In this example DHCPv6 requests are received by the router on eth1 +(`listening interface`) and forwarded through eth2 (`upstream interface`) to +the external DHCPv6 server at 2001:db8:100::4. + +Configuration +************* + +Set eth1 to be the listening interface for the DHCPv6 relay: + +.. code-block:: none + + set service dhcpv6-relay listen-interface eth1 + +Set eth2 to be the upstream interface and specify the IPv6 address of +the DHCPv6 server: + +.. code-block:: none + + set service dhcpv6-relay upstream-interface eth2 address 2001:db8:100::4 + +Commit the changes and show results: + +.. code-block:: none + + commit + show service dhcpv6-relay + listen-interface eth1 { + } + upstream-interface eth2 { + address 2001:db8:100::4 + } + +Show the current status of the DHCPv6 relay agent: + +.. code-block:: none + + show dhcpv6 relay-agent status + +The DHCPv6 relay agent can be restarted with: + +.. code-block:: none + + restart dhcpv6 relay-agent + +Additional parameters +^^^^^^^^^^^^^^^^^^^^^ + +DHCP relay agent options +************************ + +Set the maximum hop count before packets are discarded. Range 0...255, +default 10. + +* :code:`set service dhcp-relay relay-options hop-count 'count'` + +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. + +* :code:`set service dhcp-relay relay-options max-size 'size'` + +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. + +* :code:`set service dhcp-relay relay-options relay-agents-packet 'policy'` + +DHCPv6 relay agent options +************************** + +Set maximum hop count before packets are discarded. Default: 10. + +* :code:`set service dhcpv6-relay max-hop-count 'count'` + +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. + +* :code:`set service dhcpv6-relay use-interface-id-option` -- cgit v1.2.3