[PR #73] Add proxy-DHCP support #88

New issue

Open

opened 2026-02-27 14:47:44 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 14:47:44 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/netbootxyz/docker-netbootxyz/pull/73
Author: @rjocoleman
Created: 10/10/2024
Status: 🔄 Open

Base: master ← Head: proxydhcp

📝 Commits (6)

25ef084 use a config file for dnsmasq
f36963f add proxy-DHCP support via dnsmasq
b326528 Limit envsub to only variable being changed
7c93323 proxydhcp - get container IP differently
cfc13ac update example MENU_VERSION
43b5988 proxydhcp: capabilities and network mode

📊 Changes

6 files changed (+113 additions, -13 deletions)

View changed files

📝 README.md (+16 -8)
📝 docker-compose.yml.example (+5 -1)
➕ root/defaults/dnsmasq-dhcpproxy.conf (+66 -0)
➕ root/defaults/dnsmasq.conf (+5 -0)
📝 root/etc/supervisor.conf (+1 -1)
📝 root/init.sh (+20 -3)

📄 Description

This PR adds proxy-DHCP support:

What is proxy-DHCP?
Proxy-DHCP allows a secondary DHCP server to provide boot configuration (such as next-server and boot file) while the primary DHCP server continues to assign IP addresses. This is useful in environments where modifying the primary DHCP server is not feasible, or the primary DHCP server doesn't have a static IP.
How proxy-DHCP works
When a client sends out a DHCP request, the proxy-DHCP service will respond with boot options such as the next-server and boot filename, while leaving the IP address assignment to the primary DHCP server. This allows the client to chainload iPXE without requiring modifications to the existing DHCP server.
Pairs well with netboot.xyz PR #953
This PR works alongside #953, which adds support for proxy-DHCP in the iPXE menus, allowing users to press a key to select the proxy offer and load netboot.xyz from there.
How to use it
Set the DHCP_RANGE_START environment variable to the first IP in your network’s DHCP range. This will enable the optional proxy-DHCP mode. When enabled, dnsmasq calculates the range and handles proxy requests automatically.

Edit: Ensure the docker container is on the same network e.g. --network host (or ipvlan, macvlan) so that it can receive broadcast DHCP messages and respond with its own broadcasts.
Moved dnsmasq config to a file
To enable this functionality cleanly, the dnsmasq configuration has been moved into a config file, allowing for different config based on the presence of env DHCP_RANGE_START and substitution of some values via envsubst.
Proxy-DHCP behaviour
When DHCP_RANGE_START is set, the provided dnsmasq will behave in proxy-DHCP mode (in addition to tftp), with the following key sections in the configuration:
```
# DHCP Proxy range and enable verbose DHCP logging
dhcp-range=${DHCP_RANGE_START},proxy
log-dhcp
leasefile-ro

# Detect iPXE requests via user class (Option 175)
dhcp-match=set:ipxe-bios,175,33
dhcp-match=set:ipxe-efi,175,36

# Serve appropriate bootloaders for non-iPXE clients (initial PXE boot)
pxe-service=tag:bios,tag:!ipxe-ok,X86PC,"Legacy BIOS",netboot.xyz-undionly.kpxe
...
```
This configuration sets up the proxy-DHCP to respond only to PXE clients (non-iPXE), serving the appropriate bootloaders for BIOS, UEFI, ARM64, and Raspberry Pi clients, while iPXE clients will be served an HTTP boot script.
Dynamic IP handling with envsubst
The CONTAINER_IP is dynamically injected into the configuration using envsubst, after retrieving the container’s IP address at runtime from the container itself via init.sh. This ensures that the correct container next-server IP is set in the configuration.
User experience
Users can start the container with the relevant environment variables set (DHCP_RANGE_START and optionally others). When a DHCP request is detected, this container sends a proxy offer with the next-server and boot file. With PR #953, netboot.xyz will detect the proxy next-server, allowing users to press p to boot from the proxy-DHCP server.

As it depends on a new env var being added DHCP_RANGE_START, this should be backwards compatible.

Docs & resources:
https://www.ipxe.org/appnote/proxydhcp
https://gist.github.com/NiKiZe/5c181471b96ac37a069af0a76688944d
https://thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/netbootxyz/docker-netbootxyz/pull/73 **Author:** [@rjocoleman](https://github.com/rjocoleman) **Created:** 10/10/2024 **Status:** 🔄 Open **Base:** `master` ← **Head:** `proxydhcp` --- ### 📝 Commits (6) - [`25ef084`](https://github.com/netbootxyz/docker-netbootxyz/commit/25ef084bd057e049c766d44159e85cad0eba5cd2) use a config file for dnsmasq - [`f36963f`](https://github.com/netbootxyz/docker-netbootxyz/commit/f36963f39d27a2f15db060be4d1b4b243154501c) add proxy-DHCP support via dnsmasq - [`b326528`](https://github.com/netbootxyz/docker-netbootxyz/commit/b326528269eb1cf9aae218af328760f3d40e0893) Limit envsub to only variable being changed - [`7c93323`](https://github.com/netbootxyz/docker-netbootxyz/commit/7c933236a0bb1fa242891efeefd1feece1612ffa) proxydhcp - get container IP differently - [`cfc13ac`](https://github.com/netbootxyz/docker-netbootxyz/commit/cfc13acd26cf804f530b086a12d18d586f0f3fe8) update example MENU_VERSION - [`43b5988`](https://github.com/netbootxyz/docker-netbootxyz/commit/43b5988f304ff22a67202713150423b1c8030259) proxydhcp: capabilities and network mode ### 📊 Changes **6 files changed** (+113 additions, -13 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+16 -8) 📝 `docker-compose.yml.example` (+5 -1) ➕ `root/defaults/dnsmasq-dhcpproxy.conf` (+66 -0) ➕ `root/defaults/dnsmasq.conf` (+5 -0) 📝 `root/etc/supervisor.conf` (+1 -1) 📝 `root/init.sh` (+20 -3) </details> ### 📄 Description ### This PR adds proxy-DHCP support: - **What is proxy-DHCP?** Proxy-DHCP allows a secondary DHCP server to provide boot configuration (such as next-server and boot file) while the primary DHCP server continues to assign IP addresses. This is useful in environments where modifying the primary DHCP server is not feasible, or the primary DHCP server doesn't have a static IP. - **How proxy-DHCP works** When a client sends out a DHCP request, the proxy-DHCP service will respond with boot options such as the next-server and boot filename, while leaving the IP address assignment to the primary DHCP server. This allows the client to chainload iPXE without requiring modifications to the existing DHCP server. - **Pairs well with [netboot.xyz PR #953](https://github.com/netbootxyz/netboot.xyz/pull/953)** This PR works alongside #953, which adds support for proxy-DHCP in the iPXE menus, allowing users to press a key to select the proxy offer and load netboot.xyz from there. - **How to use it** Set the `DHCP_RANGE_START` environment variable to the first IP in your network’s DHCP range. This will enable the optional proxy-DHCP mode. When enabled, dnsmasq calculates the range and handles proxy requests automatically. Edit: Ensure the docker container is on the same network e.g. [`--network host`](https://docs.docker.com/engine/network/drivers/host/) (or [ipvlan](https://docs.docker.com/engine/network/drivers/ipvlan/), [macvlan](https://docs.docker.com/engine/network/drivers/macvlan/)) so that it can receive broadcast DHCP messages and respond with its own broadcasts. - **Moved dnsmasq config to a file** To enable this functionality cleanly, the dnsmasq configuration has been moved into a config file, allowing for different config based on the presence of env `DHCP_RANGE_START` and substitution of some values via envsubst. - **Proxy-DHCP behaviour** When `DHCP_RANGE_START` is set, the provided dnsmasq will behave in proxy-DHCP mode (in addition to tftp), with the following key sections in the configuration: ```bash # DHCP Proxy range and enable verbose DHCP logging dhcp-range=${DHCP_RANGE_START},proxy log-dhcp leasefile-ro # Detect iPXE requests via user class (Option 175) dhcp-match=set:ipxe-bios,175,33 dhcp-match=set:ipxe-efi,175,36 # Serve appropriate bootloaders for non-iPXE clients (initial PXE boot) pxe-service=tag:bios,tag:!ipxe-ok,X86PC,"Legacy BIOS",netboot.xyz-undionly.kpxe ... ``` This configuration sets up the proxy-DHCP to respond only to PXE clients (non-iPXE), serving the appropriate bootloaders for BIOS, UEFI, ARM64, and Raspberry Pi clients, while iPXE clients will be served an HTTP boot script. - **Dynamic IP handling with envsubst** The `CONTAINER_IP` is dynamically injected into the configuration using `envsubst`, after retrieving the container’s IP address at runtime from the container itself via `init.sh`. This ensures that the correct container next-server IP is set in the configuration. - **User experience** Users can start the container with the relevant environment variables set (`DHCP_RANGE_START` and optionally others). When a DHCP request is detected, this container sends a proxy offer with the next-server and boot file. With PR [#953](https://github.com/netbootxyz/netboot.xyz/pull/953), netboot.xyz will detect the proxy next-server, allowing users to press `p` to boot from the proxy-DHCP server. As it depends on a new env var being added `DHCP_RANGE_START`, this should be backwards compatible. Docs & resources: https://www.ipxe.org/appnote/proxydhcp https://gist.github.com/NiKiZe/5c181471b96ac37a069af0a76688944d https://thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>