DHCP Server

Example Path: examples/DHCP/DHCPServer

DHCP Server

Overview

This example shows the minimal way to run a DHCP server on a NetBurner device. It hands out IP addresses from a single contiguous pool using the SDK's built-in allocator — no device classification, address profiles, or per-pool modes. If you just need "my NetBurner should be the DHCP server on this network," this is the starting point.

For a server that applies a custom allocation policy (NetBurner vs. other clients, multiple pools, per-device profiles, and a live web dashboard), see the DHCPServerAdvanced example.

WARNING: The Host Must Be Static in the Pool's Subnet

A DHCP server must have a stable IP address in the same subnet as the pool it serves.** This device (the server host) should use a static IP inside the pool's subnet (the configured PoolStart) — for example, host 192.168.1.2 for a 192.168.1.100+ pool.

Do not leave the host in plain DHCP-client mode for a real deployment. This example only serves when no other DHCP server is present — but in exactly that situation there is also nothing to lease this* device an address, so it falls back to an AutoIP (169.254.x.x) address. It would then hand out 192.168.1.x leases and advertise a gateway it isn't even on, and clients could not reach it. Running a DHCP server on a DHCP-assigned address is also fragile, because the server's own address could change.

Easiest correct configuration: set the address mode to DHCP w Fallback** with a fallback static IP in the pool's subnet. On a managed network the device takes a normal DHCP lease (and this example sits in standby); alone on a segment it falls back to its static address and serves correctly — the same binary works in both places with no manual reconfiguration.

To make this hard to miss, the web page and the serial console both display a prominent warning whenever this device's address is not in the pool's subnet.

How It Works

UserMain() does two things: it probes for an existing DHCP server, and only if none is found does it start its own.

1. Detect an existing server.** FindOtherDHCPServer() broadcasts a DHCP DISCOVER and waits a few seconds for a reply. If any server answers, one is already running on this network and we stay in standby (starting a second server would cause address conflicts). This is an active probe — it asks the network rather than guessing from local state, so it works regardless of how this device itself is addressed (DHCP or static). It is the same technique the DHCPServerAdvanced example uses, and what the one-call AddStandardDHCPServer() helper does internally.
2. Start the server.** If no other server replied, the example builds the built-in DHCP::BlockAllocator from the saved pool settings and starts serving:

DHCP::BlockAllocator *allocator = new DHCP::BlockAllocator((IPADDR4)gPool.start, PoolSize(), gLeases);
 
DHCP::DhcpInfo info{};                         // options handed to clients
info.netmask = (IPADDR4)gPool.netmask;
info.gateway = (IPADDR4)gPool.gateway;
info.dns_1   = (IPADDR4)gPool.dns;
allocator->UpdateDhcpInfo(&info);
allocator->SetLeaseTime((int)gPool.leaseHours);
allocator->AddInterface(GetFirstInterface());
gDhcpServer.AddLeaseAllocator(allocator);
pDHCPServerProcessFunction = DHCP::Server::ProcessMessage;   // hook it into the stack

The pool values come from gPool, a config_obj stored in the configuration server (see below), read once at boot. The lease block (gLeases) is sized to a compile-time maximum (MAX_POOL_SIZE); the configured PoolSize is clamped to it.

Because of the probe, the same binary is safe to load on a normal, already-served network — it stays in standby and serves only its status web page. Put it on a segment with no other DHCP server and it starts handing out leases. The decision is made once at boot; reboot to re-evaluate.

‍If you don't even need persistent settings, the SDK's one-call AddStandardDHCPServer() (in <dhcpd.h>) bundles the same probe with a fixed-size standard server in a single call.

Web Page

A single status page (index.html) reports whether the device is serving leases or in standby. The status is rendered on the device with a <!--CPPCALL ShowServerStatus--> tag (no JavaScript) — reload the page to refresh it.

Configuring the Address Pool

The pool settings live in a config_obj (DhcpPoolConfig gPool) registered in the configuration server under App Data as the record **DHCPServerPool**. They persist across reboots and are editable without recompiling** in the device's built-in configuration UI:

http://<device-ip>:20034/

Open that page ("Device Configuration") and navigate to App Data → DHCPServerPool; the fields there map 1:1 to the config_obj members. (The example's web page links to the configuration UI for you.)

Setting	Controls
PoolStart	First address handed out
PoolSize	Number of addresses in the pool (range = start .. start + size−1; clamped to MAX_POOL_SIZE)
Netmask	Netmask offered to clients
Gateway	Default gateway offered to clients
DNS	DNS server offered to clients
LeaseHours	Lease duration, in hours

The values in the DhcpPoolConfig class declaration in main.cpp are only the factory defaults. Changes made in the config UI are saved to flash and take effect on the next reboot (the allocator is built from the saved values at boot). For other allocation strategies the SDK also provides DHCP::SingleAllocator (one fixed address) and DHCP::MacPrefixAllocator (whitelist/blacklist a MAC range).

Important

Only run a DHCP server where it will not collide with an existing one. The active probe guards against that, but on an isolated segment with no other server it will start handing out addresses — make sure the configured PoolStart/Netmask match the subnet of the segment the device is on.

Related Examples

• DHCPServerAdvanced — custom policy-based allocation (device classes, profiles, per-pool Normal/Duplicate/Off modes) with a live AJAX lease dashboard.