The Dynamic Host Configuration Protocol (DHCP) is a protocol used by computers, or any network device, to automatically obtain an IP address and other related settings in order to access a network. Similar to RADIUS, DHCP is based on UDP requests and responses that can carry a wide range of attributes, or options as they are called in DHCP. Besides the typical options to assign IP Address, Default Router, and Domain Name Server, DHCP supports many standard and vendor specific options to configure devices on a network.

DHCP Support in FreeRADIUS

The latest FreeRADIUS server supports DHCP and JRadius, but not per default. Build FreeRADIUS with JRadius support, but also include DHCP by run the configure script with the --with-dhcp option. Additionally, after installation edit the main dictionary file (/usr/local/share/freeradius/dictionary if the default installation prefix is used) to include $INCLUDE dictionary.dhcp - you will find the line already in the dictionary file, just commented out. Next, enable the DHCP service in FreeRADIUS by copying the file etc/raddb/sites-available/dhcp to the etc/raddb/sites-enabled/ directory.

When FreeRADIUS received DHCP packets, it handles the packet very similarly to RADIUS packets - parsing the options into FreeRADIUS defined vendor specific attributes and invoking modules. Thus allowing for DHCP programming in any one of the supported FreeRADIUS modules (perl, python, sql, etc), including Java using the rlm_jradius module.

DHCP Support in JRadius

In the etc/raddb/sites-enabled/dhcp configuration file, enable the jradius module to handle the various DHCP requests of interest.

server dhcp {
  listen {
    ipaddr =
    port = 6700
    type = dhcp
  dhcp DHCP-Discover {
  dhcp DHCP-Request {
  dhcp DHCP-Decline {
  dhcp DHCP-Inform {

The above configuration will run a DHCP server on the localhost port 6700 and will invoke JRadius for the specified DHCP packet types.

Example DHCP JRadius Handler

A simple DHCP IP Pool handler is included, and pre-configured in the JRadius example server. The handler implements a simple IP address pool and takes care of all the DHCP logic. As you can see in the source code, it’s just like a RADIUS handler just using the DHCP vendor specific attributes. Here is the debug output of a successful DHCP request and response as seen in JRadius after going through the handler:

Class: class net.jradius.packet.DHCPDiscover
DHCP-Opcode = Client-Message
DHCP-Hardware-Type = Ethernet
DHCP-Hardware-Address-Length = 6
DHCP-Hop-Count = 0
DHCP-Transaction-Id = 570983689
DHCP-Number-of-Seconds = 0
DHCP-Flags = Unknown-0
DHCP-Client-IP-Address =
DHCP-Your-IP-Address =
DHCP-Server-IP-Address =
DHCP-Gateway-IP-Address =
DHCP-Client-Hardware-Address = [Data (length=6)](Binary)
DHCP-Message-Type = DHCP-Discover
DHCP-Parameter-Request-List = DHCP-Subnet-Mask
DHCP-Parameter-Request-List = DHCP-Router-Address
DHCP-Parameter-Request-List = DHCP-Domain-Name-Server
DHCP-Parameter-Request-List = DHCP-Domain-Name
DHCP-Parameter-Request-List = DHCP-Netinfo-Address
DHCP-Parameter-Request-List = DHCP-Netinfo-Tag
DHCP-Parameter-Request-List = DHCP-Directory-Agent
DHCP-Parameter-Request-List = DHCP-Service-Scope
DHCP-Parameter-Request-List = DHCP-LDAP
DHCP-Parameter-Request-List = Unknown-252
DHCP-DHCP-Maximum-Msg-Size = 1500
DHCP-Client-Identifier = [Data (length=7)](Binary)
DHCP-IP-Address-Lease-Time = 7776000
DHCP-Hostname = laptop

Class: class net.jradius.packet.DHCPOffer
DHCP-Message-Type := DHCP-Offer
DHCP-Your-IP-Address :=
DHCP-IP-Address-Lease-Time := 900
DHCP-DHCP-Server-Identifier :=
DHCP-Domain-Name-Server :=
DHCP-Subnet-Mask :=
DHCP-Router-Address :=

Example with CoovaChilli as Relay Agent

A DHCP server is built into CoovaChilli, but it can also be configured to relay DHCP requests to an external DHCP server. With CoovaChilli running on the same system as FreeRADIUS, the following configure is used for Chilli:

radiussecret testing123
dhcpif eth0
uamsecret uamsecret
dhcpgatewayport 6700

Where the last 3 options are the most relevant. Of course, your configuration will vary. Note that the DHCP relay and MAC authentication options are currently not playing well together, and that this is in general an experimental feature, as is DHCP support in FreeRADIUS and JRadius. Patches and bug reports are welcome in the forum and mailing lists.