.. _example_service_dhcp-relay_relay-modes:

###########
Relay-Modes
###########

This suite tests the ``relay-agents-packets`` configuration option,
which controls how the DHCP relay handles Option 82 (Relay Agent Information).
Option 82 is automatically added by relays to identify where DHCP requests
originated. The modes (append, replace, forward, discard) determine what
happens when a packet already contains Option 82 from another relay.
Each test verifies the client can obtain a DHCP lease with each mode.

************************************
Test Relay Agent Packets Append Mode
************************************

Description
===========

This test configures the relay with ``relay-agents-packets append``.
In append mode, the relay adds its Option 82 information to DHCP
requests. If the packet already has Option 82 from another relay,
the new information is appended to the existing option.
This is the default and safest mode for most deployments.

Scenario
========

.. include:: relay-modes/testrelayagentpacketsappendmode

.. raw:: html

  <hr>

*************************************
Test Relay Agent Packets Replace Mode
*************************************

Description
===========

This test configures the relay with ``relay-agents-packets replace``.
In replace mode, the relay overwrites any existing Option 82 with
its own information. This is useful in cascaded relay topologies
where only the last relay's information is relevant to the server.

Scenario
========

.. include:: relay-modes/testrelayagentpacketsreplacemode

.. raw:: html

  <hr>

*************************************
Test Relay Agent Packets Forward Mode
*************************************

Description
===========

This test configures the relay with ``relay-agents-packets forward``.
In forward mode, the relay passes DHCP packets through without
modifying Option 82. This preserves the original relay information,
which is useful when the first relay's circuit ID is needed for
billing or access control decisions.

Scenario
========

.. include:: relay-modes/testrelayagentpacketsforwardmode

.. raw:: html

  <hr>

*************************************
Test Relay Agent Packets Discard Mode
*************************************

Description
===========

This test configures the relay with ``relay-agents-packets discard``.
In discard mode, the relay drops packets that already contain
Option 82. This prevents relay loops in complex topologies.
The client still obtains an IP because its initial DHCPDISCOVER
does not contain Option 82 (only relayed packets would have it).

Scenario
========

.. include:: relay-modes/testrelayagentpacketsdiscardmode

.. raw:: html

  <hr>