DHCP Server¶

The DHCPv4 server provides automatic IP address assignment and network configuration for clients. It supports address pools, static host assignments, and customizable DHCP options. It also serves as a DNS proxy for local subnets and can even forward queries to upstream DNS servers¹.

Note

When using the CLI, the system automatically enables essential options like DNS servers and default gateway based on the system's network configuration. These options can be disabled, changed or overridden, at any level: global, subnet, or per-host.

Basic Configuration¶

The following example configures a DHCP server for subnet 192.168.2.0/24 with an address pool:

admin@example:/> configure
admin@example:/config/> edit dhcp-server subnet 192.168.2.0/24
admin@example:/config/dhcp-server/…/192.168.2.0/24/> set pool start-address 192.168.2.100 end-address 192.168.2.200
admin@example:/config/dhcp-server/…/192.168.2.0/24/> leave

When setting up the server from the CLI, the system automatically adds a few default DHCP options that will be sent to clients: both DNS server and default gateway will use the system address on the matching interface.

admin@example:/> show running-config
  "infix-dhcp-server:dhcp-server": {
    "subnet": [
      {
        "subnet": "192.168.2.0/24",
        "option": [
          {
            "id": "dns-server",
            "address": "auto"
          },
          {
            "id": "router",
            "address": "auto"
          }
        ],
        "pool": {
          "start-address": "192.168.2.100",
          "end-address": "192.168.2.200"
        }
      }
    ]
  }

Important

Remember to set up an interface in this subnet, avoid using addresses in the DHCP pool, or reserved for static hosts. In Class C networks the router usually has address .1. Depending on the use-case, you may also want to set up routing.

Static Host Assignment¶

To reserve specific IP addresses for clients based on their MAC address, hostname, or client ID:

admin@example:/config/dhcp-server/…/192.168.2.0/24/> edit host 192.168.2.10
admin@example:/config/dhcp-server/…/192.168.2.10/> set match mac-address 00:11:22:33:44:55
admin@example:/config/dhcp-server/…/192.168.2.10/> set hostname printer
admin@example:/config/dhcp-server/…/192.168.2.10/> leave

Match hosts using a client identifier instead of MAC address:

admin@example:/config/dhcp-server/…/192.168.1.0/24/> edit host 192.168.1.50
admin@example:/config/dhcp-server/…/192.168.1.50/> edit match
admin@example:/config/dhcp-server/…/match/> set client-id hex c0:ff:ee
admin@example:/config/dhcp-server/…/match/> leave
admin@example:/config/dhcp-server/…/192.168.1.50/> set lease-time infinite
admin@example:/config/dhcp-server/…/192.168.1.50/> leave

The hex prefix here ensures matching of client ID is done using the hexadecimal octets c0:ff:ee, three bytes. Without the prefix the ASCII string "c0:ff:ee", eight bytes, is used.

Note

The DHCP server is fully RFC conformant, in the case of option 61 this means that using the hex prefix will require the client to set the htype field of the option to 00. See RFC 2132 for details.

Custom DHCP Options¶

Configure additional DHCP options globally, per subnet, or per host:

admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24
admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit option dns-server
admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/dns-server/> set address 8.8.8.8
admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/dns-server/> leave
admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit option ntp-server
admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/ntp-server/> set address 192.168.2.1
admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/ntp-server/> leave

When configuring, e.g., dns-server, or router options with the value auto, the system uses the IP address from the interface matching the subnet. For example:

admin@example:/> show interface
INTERFACE       PROTOCOL      STATE       DATA                                    
eth0            ethernet      UP          02:00:00:00:00:00
                ipv4                   192.168.1.1/24 (static)
eth1            ethernet      UP          02:00:00:00:00:01
                ipv4                   192.168.2.1/24 (static)

admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> edit option dns-server
admin@example:/config/dhcp-server/subnet/192.168.1.0/24/option/dns-server/> set address auto
admin@example:/config/dhcp-server/subnet/192.168.1.0/24/option/dns-server/> leave

In this case, clients in subnet 192.168.1.0/24 will receive 192.168.1.1 as their DNS server address.

Multiple Subnets¶

Configure DHCP for multiple networks:

admin@example:/> configure
admin@example:/config/> edit dhcp-server
admin@example:/config/dhcp-server/> edit subnet 192.168.1.0/24
admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> set pool start-address 192.168.1.100 end-address 192.168.1.200
admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> leave
admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24
admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> set pool start-address 192.168.2.100 end-address 192.168.2.200
admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> leave

Network Boot¶

Devices that boot over the network, or fall back to it when their own firmware is damaged, learn the name of the boot file and the address of the TFTP server from the DHCP server. These are set with boot, which can be given globally, per subnet, or per static host. The most specific scope wins.

admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24
admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> set boot file fallback.itb
admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> leave

By default the server address handed out is the system's own address on the interface facing the client, matching the built-in TFTP server. Set boot server-address to point clients at another server instead.

The boot file and server address are sent both in the BOOTP header fields, which BOOTP clients, bootloaders like U-Boot, and PXE ROMs read, and as DHCP options 66 and 67 to clients that request them. The two options cannot be set in the option list when boot is used.

Caution

Boot files are handed out over TFTP, which has no authentication. Anything below the server root can be read by any client, see TFTP Server.

To hand a single device a different image, e.g., during a staged rollout, set boot on its static host entry:

admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit host 192.168.2.10
admin@example:/config/dhcp-server/…/192.168.2.10/> set match mac-address 00:11:22:33:44:55
admin@example:/config/dhcp-server/…/192.168.2.10/> set boot file staging.itb
admin@example:/config/dhcp-server/…/192.168.2.10/> leave

Monitoring¶

View active leases and server statistics:

admin@example:/> show dhcp-server
IP ADDRESS       MAC                HOSTNAME            CLIENT ID             EXPIRES
192.168.2.22     00:a0:85:00:02:05                      00:c0:ff:ee           3591s
192.168.1.11     00:a0:85:00:04:06  foo                 01:00:a0:85:00:04:06  3591s

admin@example:/> show dhcp-server statistics
DHCP offers sent                : 6
DHCP ACK messages sent          : 5
DHCP NAK messages sent          : 0
DHCP decline messages received  : 0
DHCP discover messages received : 6
DHCP request messages received  : 5
DHCP release messages received  : 6
DHCP inform messages received   : 6

This requires the system DNS resolver to be configured. ↩