DHCPv4 Relay Agent High Level Design by ashutosh-agrawal · Pull Request #1938 · sonic-net/SONiC

ashutosh-agrawal · 2025-03-01T02:06:16Z

This document provides a high-level design for SONiC's new DHCPv4 relay agent, which addresses limitations of the existing ISC-DHCP implementation. The document outlines the architecture, new features and configuration of the new design, and also addresses the backward compatibility concerns related to transition from isc-dhcp.

Code PRs:
sonic-dhcp-relay
yang-model
sonic-buildimage
sonic-swss-common
Testplan HLD
sonic-mgmt test
CLIs

Signed-off-by: Ashutosh Agrawal <ashu@cisco.com>

mssonicbld · 2025-03-01T02:06:19Z

/azp run

azure-pipelines · 2025-03-01T02:06:25Z

No pipelines are associated with this pull request.

mssonicbld · 2025-03-01T02:07:33Z

/azp run

azure-pipelines · 2025-03-01T02:07:39Z

No pipelines are associated with this pull request.

mssonicbld · 2025-03-05T19:19:23Z

/azp run

azure-pipelines · 2025-03-05T19:19:30Z

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

mssonicbld · 2025-03-06T01:04:21Z

/azp run

azure-pipelines · 2025-03-06T01:04:27Z

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

mssonicbld · 2025-03-07T22:41:54Z

/azp run

azure-pipelines · 2025-03-07T22:42:00Z

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

doc/DHCPv4_relay/DHCPv4-relay-agent-High-Level-Design.md

yaqiangz · 2025-03-17T12:28:43Z

Hi @lolyu could you please help to check the dual tor part?

mssonicbld · 2025-03-31T23:15:01Z

/azp run

azure-pipelines · 2025-03-31T23:15:06Z

No pipelines are associated with this pull request.

doc/DHCPv4_relay/DHCPv4-relay-agent-High-Level-Design.md

lolyu

The dualtor part LGTM

AnantKishorSharma · 2025-04-15T07:11:45Z

Hi @yaqiangz , @saiarcot895 , @lguohan , could you please create the new repo mentioned in this HLD( https://github.com/sonic-net/sonic-dhcpv4-relay) to open code PR?

jasper-hou-micas · 2025-04-21T08:51:33Z

doc/DHCPv4_relay/images/DHCPv4_Relay_Basic_Flow.png

Maybe detailing the type of OFFER packet(unicast) is more friendly

doc/DHCPv4_relay/DHCPv4-relay-agent-High-Level-Design.md

AnantKishorSharma · 2025-07-01T03:36:09Z

doc/DHCPv4_relay/DHCPv4-relay-agent-High-Level-Design.md

+
+- **DHCP Acknowledgment (ACK):** The DHCP server responds with a DHCP Ack message, setting the destination IP address to the relay agent's IP address (giaddr). Upon receiving this message, the DHCP relay agent updates the packet's fields similar to the Offer message and forwards it as a unicast message to the DHCP client, completing the DHCP transaction.
+
+<div align="center"> <img src=images/DHCPv4_Relay_Basic_Flow.png width=600 /> </div>


offer packet from server to relay agent will also be unicast, typo?

AnantKishorSharma · 2025-07-01T03:36:16Z

doc/DHCPv4_relay/DHCPv4-relay-agent-High-Level-Design.md

+
+DHCPv4 relay process will run in the dhcp_relay container along with DHCPv6 processes and DhcpMon. A single instance of the process will handle DHCPv4 relay functionality of all the VLANs that are configured. This process will listen to Redis for all the necessary configuration updates and will not require restarting of the container. The design is split into 3 sub-modules and the following diagram provides an overview of how they interact with each other:
+
+<div align="center"> <img src=images/DHCPv4_Relay_sequence_diagram.png width=700 /> </div>


This diagram needs to be updated with the latest changes(COUNTERS_DB etc.)?

yaqiangz

LGTM

Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938). What I did Added dependency checks in SONiC config CLI to prevent deletion of interfaces, VRFs, and VLANs that are in use by DHCPv4 relay configurations. Added/updated unit tests. How I did it Implemented a new function check_dhcpv4_relay_dependencies to check if an interface or VRF is referenced in the DHCPV4_RELAY table. Called this function before allowing deletion of portchannels, loopbacks, VRFs, and VLANs. Modified the VLAN deletion logic to block removal if the VLAN is present in the DHCPV4_RELAY table. Extended the test suite to verify that deletion is blocked when dependencies exist and allowed after cleanup. How to verify it Run the updated unit tests: they now include cases where deletion of interfaces, VRFs, or VLANs in use by DHCPv4 relay is attempted and should fail. Manually test by configuring DHCPv4 relay on an interface/VRF/VLAN, then attempt to delete it using the CLI; the command should fail with an appropriate error message. After removing the DHCPv4 relay configuration, deletion should succeed.

Why I did it Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938). Docker changes PR : #22486 How I did it Included new commands to support dhcpv4_relay in dockers/docker-dhcp-relay folder. Corresponding cli-plugin-tests are included. How to verify it Configure sonic DHCPv4 agent as described in the feature HLD(sonic-net/SONiC#1938) Test it with real client/server with IPv4 or use the sonic-mgmt suite Co-authored-by: Prashant Srivastava <srivastavaprashant829@gmail.com>

Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938). What I did Added dependency checks in SONiC config CLI to prevent deletion of interfaces, VRFs, and VLANs that are in use by DHCPv4 relay configurations. Added/updated unit tests. How I did it Implemented a new function check_dhcpv4_relay_dependencies to check if an interface or VRF is referenced in the DHCPV4_RELAY table. Called this function before allowing deletion of portchannels, loopbacks, VRFs, and VLANs. Modified the VLAN deletion logic to block removal if the VLAN is present in the DHCPV4_RELAY table. Extended the test suite to verify that deletion is blocked when dependencies exist and allowed after cleanup. How to verify it Run the updated unit tests: they now include cases where deletion of interfaces, VRFs, or VLANs in use by DHCPv4 relay is attempted and should fail. Manually test by configuring DHCPv4 relay on an interface/VRF/VLAN, then attempt to delete it using the CLI; the command should fail with an appropriate error message. After removing the DHCPv4 relay configuration, deletion should succeed.

Why I did it Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938). Docker changes PR : sonic-net#22486 How I did it Included new commands to support dhcpv4_relay in dockers/docker-dhcp-relay folder. Corresponding cli-plugin-tests are included. How to verify it Configure sonic DHCPv4 agent as described in the feature HLD(sonic-net/SONiC#1938) Test it with real client/server with IPv4 or use the sonic-mgmt suite Co-authored-by: Prashant Srivastava <srivastavaprashant829@gmail.com>

Why I did it Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938). Docker changes PR : sonic-net#22486 How I did it Included new commands to support dhcpv4_relay in dockers/docker-dhcp-relay folder. Corresponding cli-plugin-tests are included. How to verify it Configure sonic DHCPv4 agent as described in the feature HLD(sonic-net/SONiC#1938) Test it with real client/server with IPv4 or use the sonic-mgmt suite Co-authored-by: Prashant Srivastava <srivastavaprashant829@gmail.com> Signed-off-by: Feng Pan <fenpan@microsoft.com>

Why I did it Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938) Work item tracking Microsoft ADO (number only): How I did it Edit supervisord template to start sonic DHCPv4 relay instance when configured to do so in Config DB. Align cfg unit test to the new change. How to verify it Configure sonic DHCPv4 agent as described in the feature HLD(sonic-net/SONiC#1938) Test it with real client/server with IPv4 or use the sonic-mgmt suite Signed-off-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Shivashankar C R <shivashankar.c.r@gmail.com> Co-authored-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: StormLiangMS <89824293+StormLiangMS@users.noreply.github.com>

Why I did it Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938) Work item tracking Microsoft ADO (number only): How I did it Edit supervisord template to start sonic DHCPv4 relay instance when configured to do so in Config DB. Align cfg unit test to the new change. How to verify it Configure sonic DHCPv4 agent as described in the feature HLD(sonic-net/SONiC#1938) Test it with real client/server with IPv4 or use the sonic-mgmt suite Signed-off-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Shivashankar C R <shivashankar.c.r@gmail.com> Co-authored-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: StormLiangMS <89824293+StormLiangMS@users.noreply.github.com> Signed-off-by: Dawei Huang <daweihuang@microsoft.com>

Why I did it Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938). Docker changes PR : sonic-net#22486 How I did it Included new commands to support dhcpv4_relay in dockers/docker-dhcp-relay folder. Corresponding cli-plugin-tests are included. How to verify it Configure sonic DHCPv4 agent as described in the feature HLD(sonic-net/SONiC#1938) Test it with real client/server with IPv4 or use the sonic-mgmt suite Co-authored-by: Prashant Srivastava <srivastavaprashant829@gmail.com> Signed-off-by: xiaweijiang <xiaweijiang@microsoft.com>

Why I did it Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938) Work item tracking Microsoft ADO (number only): How I did it Edit supervisord template to start sonic DHCPv4 relay instance when configured to do so in Config DB. Align cfg unit test to the new change. How to verify it Configure sonic DHCPv4 agent as described in the feature HLD(sonic-net/SONiC#1938) Test it with real client/server with IPv4 or use the sonic-mgmt suite Signed-off-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Shivashankar C R <shivashankar.c.r@gmail.com> Co-authored-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: StormLiangMS <89824293+StormLiangMS@users.noreply.github.com> Signed-off-by: xiaweijiang <xiaweijiang@microsoft.com>

Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938). What I did Added dependency checks in SONiC config CLI to prevent deletion of interfaces, VRFs, and VLANs that are in use by DHCPv4 relay configurations. Added/updated unit tests. How I did it Implemented a new function check_dhcpv4_relay_dependencies to check if an interface or VRF is referenced in the DHCPV4_RELAY table. Called this function before allowing deletion of portchannels, loopbacks, VRFs, and VLANs. Modified the VLAN deletion logic to block removal if the VLAN is present in the DHCPV4_RELAY table. Extended the test suite to verify that deletion is blocked when dependencies exist and allowed after cleanup. How to verify it Run the updated unit tests: they now include cases where deletion of interfaces, VRFs, or VLANs in use by DHCPv4 relay is attempted and should fail. Manually test by configuring DHCPv4 relay on an interface/VRF/VLAN, then attempt to delete it using the CLI; the command should fail with an appropriate error message. After removing the DHCPv4 relay configuration, deletion should succeed.

Why I did it Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938) Work item tracking Microsoft ADO (number only): How I did it Edit supervisord template to start sonic DHCPv4 relay instance when configured to do so in Config DB. Align cfg unit test to the new change. How to verify it Configure sonic DHCPv4 agent as described in the feature HLD(sonic-net/SONiC#1938) Test it with real client/server with IPv4 or use the sonic-mgmt suite Signed-off-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Shivashankar C R <shivashankar.c.r@gmail.com> Co-authored-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: StormLiangMS <89824293+StormLiangMS@users.noreply.github.com>

Why I did it Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938) Work item tracking Microsoft ADO (number only): How I did it Edit supervisord template to start sonic DHCPv4 relay instance when configured to do so in Config DB. Align cfg unit test to the new change. How to verify it Configure sonic DHCPv4 agent as described in the feature HLD(sonic-net/SONiC#1938) Test it with real client/server with IPv4 or use the sonic-mgmt suite Signed-off-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Shivashankar C R <shivashankar.c.r@gmail.com> Co-authored-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: StormLiangMS <89824293+StormLiangMS@users.noreply.github.com> Signed-off-by: Feng Pan <fenpan@microsoft.com>

* [dhcp_relay] sonic dhcp relay agent for IPv4 (#22486) Why I did it Currently SONiC uses the 'isc-dhcp-relay' package to allow DHCP relay functionality on IPv4 networks. With this PR we are adding sonic dhcp relay agent for IPv4 as described in this HLD(sonic-net/SONiC#1938) Work item tracking Microsoft ADO (number only): How I did it Edit supervisord template to start sonic DHCPv4 relay instance when configured to do so in Config DB. Align cfg unit test to the new change. How to verify it Configure sonic DHCPv4 agent as described in the feature HLD(sonic-net/SONiC#1938) Test it with real client/server with IPv4 or use the sonic-mgmt suite Signed-off-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Shivashankar C R <shivashankar.c.r@gmail.com> Co-authored-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: StormLiangMS <89824293+StormLiangMS@users.noreply.github.com> * Update sonic-dhcp-relay submodule to include boost dependency fixes Signed-off-by: Ashutosh Agrawal <ashu@cisco.com> --------- Signed-off-by: Ashutosh Agrawal <ashu@cisco.com> Co-authored-by: Anant <127479400+AnantKishorSharma@users.noreply.github.com> Co-authored-by: Shivashankar C R <shivashankar.c.r@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: StormLiangMS <89824293+StormLiangMS@users.noreply.github.com> Co-authored-by: Vineet Mittal <46945843+vmittal-msft@users.noreply.github.com>

ashutosh-agrawal added 2 commits February 12, 2025 11:11

Initial Version

1964c36

Signed-off-by: Ashutosh Agrawal <ashu@cisco.com>

Major updates

7b226cf

ashutosh-agrawal force-pushed the dhcpv4 branch from eb569d8 to 7b226cf Compare March 1, 2025 02:07

ashutosh-agrawal force-pushed the dhcpv4 branch from db9c526 to d54a120 Compare March 6, 2025 01:04

yaqiangz self-requested a review March 6, 2025 04:21

ashutosh-agrawal force-pushed the dhcpv4 branch from d54a120 to 369782f Compare March 7, 2025 22:41

yaqiangz reviewed Mar 17, 2025

View reviewed changes

yaqiangz requested a review from lolyu March 17, 2025 12:28

updates

1dba737

ashutosh-agrawal force-pushed the dhcpv4 branch from 369782f to 1dba737 Compare March 31, 2025 23:14

selva-nexthop reviewed Apr 8, 2025

View reviewed changes

lolyu previously approved these changes Apr 8, 2025

View reviewed changes

This was referenced Apr 16, 2025

[YANG] DHCPv4 Relay Yang Model sonic-net/sonic-buildimage#22338

Merged

Added Yang model generated CLI for DHCPv4 relay sonic-net/sonic-utilities#3858

Draft

jasper-hou-micas reviewed Apr 21, 2025

View reviewed changes

doc/DHCPv4_relay/images/DHCPv4_Relay_Basic_Flow.png

Copy link

jasper-hou-micas Apr 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe detailing the type of OFFER packet(unicast) is more friendly

jasper-hou-micas reviewed Apr 23, 2025

View reviewed changes

doc/DHCPv4_relay/DHCPv4-relay-agent-High-Level-Design.md Show resolved Hide resolved

doc/DHCPv4_relay/DHCPv4-relay-agent-High-Level-Design.md Show resolved Hide resolved

AnantKishorSharma reviewed Jul 1, 2025

View reviewed changes

cshivashgit mentioned this pull request Jul 7, 2025

[dhcp_relay] CLI: sonic dhcp relay agent for IPv4 sonic-net/sonic-buildimage#23242

Merged

9 tasks

ashutosh-agrawal mentioned this pull request Jul 14, 2025

isc-dhcp relay supports non-default vrf sonic-net/sonic-buildimage#23306

Open

8 tasks

cshivashgit mentioned this pull request Jul 29, 2025

[dhcp_relay]: sonic dhcp relay agent for IPv4 sonic-net/sonic-utilities#4004

Merged

yaqiangz approved these changes Aug 13, 2025

View reviewed changes

yaqiangz merged commit f415128 into sonic-net:master Aug 14, 2025
1 check passed

ashutosh-agrawal mentioned this pull request Feb 5, 2026

[202511] Backport PR #22486: sonic dhcp relay agent for IPv4 sonic-net/sonic-buildimage#25371

Merged


		- DHCP Acknowledgment (ACK): The DHCP server responds with a DHCP Ack message, setting the destination IP address to the relay agent's IP address (giaddr). Upon receiving this message, the DHCP relay agent updates the packet's fields similar to the Offer message and forwards it as a unicast message to the DHCP client, completing the DHCP transaction.

		<div align="center"> <img src=images/DHCPv4_Relay_Basic_Flow.png width=600 /> </div>


		DHCPv4 relay process will run in the dhcp_relay container along with DHCPv6 processes and DhcpMon. A single instance of the process will handle DHCPv4 relay functionality of all the VLANs that are configured. This process will listen to Redis for all the necessary configuration updates and will not require restarting of the container. The design is split into 3 sub-modules and the following diagram provides an overview of how they interact with each other:

		<div align="center"> <img src=images/DHCPv4_Relay_sequence_diagram.png width=700 /> </div>

Conversation

ashutosh-agrawal commented Mar 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mssonicbld commented Mar 1, 2025

Uh oh!

azure-pipelines bot commented Mar 1, 2025

Uh oh!

mssonicbld commented Mar 1, 2025

Uh oh!

azure-pipelines bot commented Mar 1, 2025

Uh oh!

mssonicbld commented Mar 5, 2025

Uh oh!

azure-pipelines bot commented Mar 5, 2025

Uh oh!

mssonicbld commented Mar 6, 2025

Uh oh!

azure-pipelines bot commented Mar 6, 2025

Uh oh!

mssonicbld commented Mar 7, 2025

Uh oh!

azure-pipelines bot commented Mar 7, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yaqiangz commented Mar 17, 2025

Uh oh!

mssonicbld commented Mar 31, 2025

Uh oh!

azure-pipelines bot commented Mar 31, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lolyu left a comment

Choose a reason for hiding this comment

Uh oh!

AnantKishorSharma commented Apr 15, 2025

Uh oh!

jasper-hou-micas Apr 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

AnantKishorSharma Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

AnantKishorSharma Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yaqiangz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

ashutosh-agrawal commented Mar 1, 2025 •

edited

Loading

AnantKishorSharma Jul 1, 2025 •

edited

Loading