NetBurner 3.5.8
PDF Version
DHCP Server - Advanced (Policy-Based)

Example Path: examples/DHCP/DHCPServerAdvanced

DHCP Server - Advanced (Policy-Based Allocation)

Overview

This NetBurner application demonstrates how to create and deploy a DHCP (Dynamic Host Configuration Protocol) Server on your NetBurner device. More than just handing out IP addresses, it shows how to implement a custom, policy-based allocation scheme: the server chooses which address range and which network options a client receives based on what kind of device it is and how an administrator has classified it. This makes it useful for standalone networks, provisioning/bring-up benches, and segregating device classes onto different subnets.

WARNING: The Host Must Be Static in the Served Subnet

A DHCP server must have a stable IP address in the same subnet as the pool it serves**, so it can be a reachable gateway/DNS for the addresses it hands out. This device (the server host) should use a static IP inside the subnet of the address pool(s)** it serves.

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 that situation there is also nothing to lease this device an address, so it falls back to an AutoIP (169.254.x.x) address and would hand out leases for a subnet it isn't on, with a gateway clients cannot reach. Running a server on a DHCP-assigned address is also fragile, since 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 served subnet. On a managed network it takes a normal DHCP lease (this example then sits in standby); alone on a segment it falls back to its static address and serves correctly.

Because this example can serve up to four pools (DHCPConfig_OtherClients, DHCPConfig_Profile1/2/3), the web dashboard and serial console surface this proactively:

  • Before any pool is configured, they show an informational planning note (showing the host's current IP and address mode) so you choose pool subnets and the host address together.
  • Once a configured pool's subnet excludes the host, that note escalates to a red warning.

If you intentionally serve multiple subnets, you must configure IP routing or a DHCP relay — a single interface can be directly on only one subnet.

Just Want a Basic DHCP Server?

If you only need to hand out addresses from a single contiguous range — no device classification, profiles, or per-pool modes — you do not need the custom allocator in this example. The SDK provides a ready-made DHCP::BlockAllocator, so a minimal server is only a few lines:

#include <dhcpd.h>
#include <netinterface.h>
#define LEASE_COUNT 50
static DHCP::DhcpLeaseData leaseBlock[LEASE_COUNT];
static DHCP::BlockAllocator allocator(AsciiToIp4("192.168.1.100"), LEASE_COUNT, leaseBlock);
static DHCP::Server dhcpServer;
extern DHCPProcessFunction *pDHCPServerProcessFunction FAST_IP_VAR;
void StartSimpleDhcpServer()
{
allocator.SetLeaseTime(1); // 1-hour leases
allocator.AddInterface(GetFirstInterface());
dhcpServer.AddLeaseAllocator(&allocator);
pDHCPServerProcessFunction = DHCP::Server::ProcessMessage;
}
DHCP::BlockAllocator
Basic allocator that handles multiple leases in a contiguous IP block.
Definition dhcpd.h:190
DHCP::Server
DHCP Server class Requires a lease allocator to be added in order to function.
Definition dhcpd.h:262
AsciiToIp4
IPADDR4 AsciiToIp4(const char *p)
Convert an ASCII IPv4 string to an IP address.
GetFirstInterface
int32_t GetFirstInterface(void)
Returns the Interface Number of the first registered network interface.
DHCP::DhcpLeaseData
Lease Data.
Definition dhcpd.h:63

Call StartSimpleDhcpServer() from UserMain() after init() and once the network is up. The built-in allocator handles offers, requests, renewals, and releases across the whole block. To control the netmask/gateway/DNS handed to clients, fill a DHCP::DhcpInfo and call allocator.UpdateDhcpInfo(&info). (As always, only run a DHCP server where it won't collide with an existing one.)

The SDK also provides DHCP::SingleAllocator (one fixed address) and DHCP::MacPrefixAllocator (whitelist/blacklist a MAC range) for slightly more control without writing your own allocator. For a complete, runnable version of this minimal approach, see the DHCPServer example. The rest of this document describes the advanced, custom-policy path that this example demonstrates with its own allocator.

Policy-Based Address Allocation

A normal DHCP server has one flat address pool. This example instead defines four configurable address-pool records and selects between them per client. Each record is a config_obj stored in the configuration server (so it survives reboots and is editable from the device's built-in configuration UI):

Record (config name) Used for
DHCPConfig_OtherClients All non-NetBurner clients (PCs, phones, anything else)
DHCPConfig_Profile1 NetBurner devices assigned to profile 1
DHCPConfig_Profile2 NetBurner devices assigned to profile 2
DHCPConfig_Profile3 NetBurner devices assigned to profile 3

Each record defines an address range (AddrStart-AddrEnd), the options handed to the client (Mask, Gate, DNS1, DNS2), a LeaseDuration, and a Mode (see below).

How a client is matched to a pool

  1. Device class. When a client requests a lease, bIsNetBurner() compares its MAC address against the NetBurner OUI prefix (00:03:F4:..., configurable via the NB_MAC / NB_MASK settings).
    • Non-NetBurner clients always draw from DHCPConfig_OtherClients.
    • NetBurner devices draw from one of the three NetBurner profiles.
  2. Profile (1, 2, or 3). Each NetBurner device is assigned a profile number. New devices start at the default profile (DefNBMode); an administrator can reassign any individual device - or set them all to the default - from the web dashboard. The profile selects DHCPConfig_Profile1, _Profile2, or _Profile3, which determines both the address range and the DHCP options that device receives.

For example, a production fleet can be placed on profile 1 (one subnet/gateway/DNS) while test units sit on profile 2 (a different subnet), all served by the same device.

Per-pool Mode

Each pool record has a Mode that controls how it answers requests:

  • Normal - assign the next free address from the pool's AddrStart-AddrEnd range. This is ordinary DHCP behavior.
  • Duplicate - always hand out the same fixed address (AddrStart) to every device assigned to that pool. Useful for bringing up or imaging a device at a known address, one at a time.
  • Off - refuse to offer a lease at all. This effectively quarantines or denies every device assigned to that pool.

Where this lives in the code

  • OneConfigRecord - the pool definition (range, options, mode, lease duration).
  • bIsNetBurner() - the device-class test (MAC prefix match).
  • GetSetNew() - selects the pool, applies the Off / Duplicate / Normal behavior, and allocates an address.
  • AllocRecord::GetDhcpInfo() - returns the selected pool's options for the granted lease.
  • SpecialAllocator - the custom DHCP::LeaseAllocator subclass that ties the policy together.

Features

  • DHCP Server Implementation: Creates a fully functional DHCP server that can assign IP addresses to network clients
  • Conflict Detection: Probes for an existing DHCP server at startup and, if one is found, stays in web-only standby instead of starting a second server — preventing address conflicts
  • Live Web Dashboard: A single-page web UI (index.html) that polls the device with fetch() and refreshes the lease tables automatically. It reads a JSON endpoint (leases.html, emitted by the EmitDhcpJson CPPCALL) and posts per-device mode changes back to the nbform handler without a full page reload.
  • Network Diagnostics: Built-in system diagnostics for troubleshooting
  • Multi-Interface Support: Can operate on different network interfaces

How It Works

Startup Sequence

  1. Network Initialization: The application initializes the network stack, starts the web server, and waits for an active network connection
  2. DHCP Server Detection: FindOtherDHCPServer() broadcasts a DHCP DISCOVER and waits briefly for a reply to learn whether another DHCP server is already active
  3. Decision (no user interaction):
    • Another server found -> the application does not start its own server. It stays in standby, serving only the web dashboard (which shows a "Standby - another DHCP server detected" status). This is what lets the example boot cleanly on a normal, DHCP-enabled network.
    • No other server found -> it starts its DHCP server on the interface and begins handing out leases.
  4. Continuous Operation: Runs indefinitely - serving leases (and the dashboard), or just the dashboard in standby

Key Components

  • FindOtherDHCPServer(): Implements network scanning to detect existing DHCP servers
    • Sends DHCP DISCOVER messages to probe for active servers
    • Uses a 5-second timeout to wait for responses
    • Returns true if another server is found, false otherwise
  • AddMyDHCPServer(): Initializes and starts the DHCP server functionality
    • Operates on the specified network interface
    • Handles DHCP client requests and IP address allocation
  • DhcpServCheck(): Callback function for processing DHCP responses during server detection

Usage

Compilation and Deployment

  1. Ensure you have the NetBurner development environment set up
  2. Include the necessary NetBurner libraries:
  3. Compile and flash to your NetBurner device

Operation

  1. Power on your NetBurner device
  2. The application will automatically:
    • Initialize network services
    • Check for existing DHCP servers
    • Prompt you if conflicts are detected
  3. If conflicts exist: Disable other DHCP servers on the network and press any key to retry
  4. Once running: The device will serve DHCP requests to network clients

Network Configuration

  • The DHCP server will operate on the first available network interface by default
  • Client devices connecting to the network will automatically receive IP addresses
  • The web server runs on port 80 for potential configuration access

Important Considerations

Standby vs. Serving (automatic)

There is no build flag to toggle the server on or off. At startup UserMain() calls FindOtherDHCPServer() and decides automatically:

  • A DHCP server is already on the network (e.g. your office/lab router): the example stays in standby** - it serves the web dashboard but does not hand out leases. The dashboard shows a "Standby - another DHCP server detected" status and empty lease tables. The serial console prints that it detected another server and is not starting its own.
  • No other DHCP server is present (an isolated segment): the example starts its DHCP server and begins serving leases; the dashboard shows "Serving leases" and the serial console reports it started.

This means you can load and review the web UI on a normal network without disrupting it, and the same binary will serve DHCP when placed on an isolated segment - no recompile needed. (The check runs once at boot; reboot the device after changing the network if you want it to re-evaluate.)

Production Deployment

  • Remove diagnostics: The code includes EnableSystemDiagnostics() which should be removed for production use
  • Security: Consider implementing access controls if deploying in production environments
  • Network planning: Ensure the IP address pool doesn't conflict with other network infrastructure

Network Conflicts

  • Multiple DHCP servers on the same network can cause IP address conflicts
  • Always verify no other DHCP servers are active before deployment
  • Common sources of DHCP servers include routers, other embedded devices, and server systems

Dependencies

  • NetBurner NNDK (NetBurner Network Development Kit)
  • Custom memory allocation module (MyAlloc.h)
  • Standard NetBurner networking libraries

Technical Details

  • Language: C++
  • Platform: NetBurner embedded devices
  • Threading: Uses NetBurner RTOS (Real-Time Operating System)
  • Network Stack: NetBurner TCP/IP stack
  • Memory Management: Custom buffer management for DHCP packets

Troubleshooting

Common Issues

  1. There is an active DHCP server on this net
    • Another DHCP server is detected on the network
    • Disable other DHCP servers or move to an isolated network segment
  2. Network timeout during startup
    • Check network connectivity and cable connections
    • Verify network interface configuration
  3. Clients not receiving IP addresses
    • Confirm DHCP server started successfully
    • Check network segmentation and VLAN configuration
    • Verify firewall settings aren't blocking DHCP traffic

Debug Information

The application outputs status messages to the console including:

  • Application name and NNDK revision information
  • DHCP server conflict detection results
  • Startup progress indicators

Related Configuration Examples

The DHCP address pools in this example are config_obj records stored in the configuration server (appdata), and the Configs web page links to the device's built-in configuration UI to edit them. For examples of serving a configuration interface from your own application web server, see the configuration-server web examples: