Skip to main content

Tool for testing IPv4 and IPv6 DHCP services

Project description


Tool for testing IPv4 and IPv6 DHCP services



dhcpdoctor sends DHCP requests and checks if it gets an offer from DHCP server. It supports BOOTP+DHCP for IPv4 (-4) and DHCPv6 for IPv6 (-6).

It can operate as a DHCP client by sending requests on the local network via broadcast/multicast or as a DHCP client and relay in one tool by unicasting requests to the specified IP address (-s). When relaying requests you can specify the relay address to send from (-f). By default the IP address of the interface request is sent from is used. When specifying custom relay from address, keep in mind that the DHCP server will send the response back to the address you specify here, so it must be an address on the machine you are running tests from.

You can specify a custom client MAC or DUID (-c). By default the MAC address of the interface to send request from is used.

You can specify the interface to send requests from with -i.

Program output and exit codes are Nagios/Icinga compatible. Response time from DHCP server is measured and returned as performance data.


dhcpdoctor needs needs Python 3.4 or later to run.

Since it uses scapy under the hood to craft, dissect, send and receive packets, it needs root permissions to run.


Via pip:

pip install dhcpdoctor

Icinga2 check command

You can use dhcpdoctor as a check command from Icinga2 or Nagios.

There is dhcpdoctor.conf config with a CheckCommand definition for Icinga2 you can use. A service that uses this check command might look like this:

apply Service "dhcpd6" {
    import "generic-service"
    check_command = "dhcpdoctor"
    vars.dhcpdoctor_ipv6 = true
    vars.dhcpdoctor_client_id = "00:11:11:11:11:11"
    assign where host.dhcpd6

If you are building an RPM from provided SPEC file, the CheckCommand config will be installed to /etc/icinga2/conf.d/check_commands/dhcpdoctor.conf.


We use poetry to manage Python dependencies and virtual environments.

To setup development virtual environment:

poetry install

Run the tool:

poetry run dhcpdoctor -h

Vagrant can be used to quickly spin-up VMs with DHCP servers to test against:

vagrant up
vagrant ssh dhcpdoctor
cd /vagrant
poetry run dhcpdoctor -h
vagrant destroy

See comments in Vagrantfile for more information.


poetry run bumpversion patch

Instead of patch you can give minor or major. This creates a commit and tag. Make sure to push it with git push --tags.

The script will bump the version for development or release as needed (based on whether we are on a git tag or not) and is called in CI jobs.


Here is how to build dhcpdoctor using pyinstaller into a single binary file and then package that into a RPM for Red-Hat based systems. The resulting binary is setuid root, because dhcpdoctor needs to work on privileged UDP ports, but is usually run as a special user when invoked from Nagios or Icinga.

pip3 install --upgrade bumpversion poetry pyinstaller
poetry install --no-dev
poetry run pip freeze | grep -v egg=dhcpdoctor > requirements.txt
pip3 install -r requirements.txt

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for dhcpdoctor, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size dhcpdoctor-1.0.0-py3-none-any.whl (18.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size dhcpdoctor-1.0.0.tar.gz (7.8 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page