netbox-dhcpd

README

netbox-dhcpd

A DHCP server using Netbox as source of truth for IP address management (IPAM).

It assigns IP addresses to hosts based on Netbox devices interfaces, and provides PXE boot parameters based on Netbox devices platforms.

Usage

DHCP

./netbox-dhcpd server -h netbox.domain.tld -t XXXNETBOX_TOKENXXX

Systemd

A sample systemd unit file are available in samples/netbox-dhcpd.service, you can deploy to /etc/systemd/system/netbox-dhcpd.service.

It get his config from environments variables in /etc/default/netbox-dhcpd, eg:

NETBOX_HOST=netbox.domain.tld
NETBOX_TOKEN=XXXNETBOX_TOKENXXX

You can activate it with:

systemctl daemon-reload
systemctl --now enable netbox-dhcpd

Logs can be read with journalctl:

journalctl -fu netbox-dhcpd

Netboot

Netboot is the ability to boot a live system or a system installer over the network.

Netbox-dhcpd use PXE and TFTP protocols and IPXE firmware for booting over the network.

And use Netbox for configure which host (Device in Netbox) must boot on which system.

PXE config

For booting over the network, your host UEFI need to be configured to do so (legacy BIOS are not supported by netbox-dhcpd).

You can do it for one boot only, generally by pressing F11 at host startup, or for all future boot (recommended options) by configuring pxe/network boot at first boot option in your UEFI.

TFTP server

For a working PXE boot, you need a TFTP server on the same host you running netbox-dhcpd.

On Debian you can install one with :

apt install tftpd-hpa

IPXE firmware

Then you need a IPXE binary named ipxe.efi which you can build with :

git clone https://github.com/ipxe/ipxe.git
cd ipxe/src
make -j$(nproc) bin-x86_64-efi/ipxe.efi
cp bin-x86_64-efi/ipxe.efi /srv/tftp
chmod 644 /srv/tftp/ipxe.efi

GRUB 2 firmware

For avoiding PXE wait and timeout when your host are configured for network boot at first boot option, you need a GRUB2 binary named localboot.efi configured to boot on first local disk found:

grub-mkstandalone -O x86_64-efi -o localboot.efi --modules="part_gpt fat chain part_msdos ext2 xfs efifwsetup" "boot/grub/grub.cfg=samples/grub2-efi-localboot.cfg"
cp localboot.efi /srv/tfp
chmod 644 /srv/tfp/localboot.efi

Netbox Device

Host to Netbox Device matching are done by comparing DHCP request MAC address and Netbox Device interfaces MAC addresses.

Netbox-dhcpd send DHCP parameters for network boot to host depending on Netbox Device Status and Platform.

Device with staged Status and Platform Slug rocky-linux-9-3 receive config to boot to /srv/tftp/rocky-linux-9-3.ipxe.

Device without configured Platform or with Status different from staged boot to /srv/tftp/localboot.efi.