You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Erik Hollensbe 7a600d7a8a ldhcpd v0.3.1 1 year ago
cmd Switched to new dhcpv4 library; tests are passing. 1 year ago
db Move to fork 1 year ago
dhcpd Search domains! 1 year ago
proto Search domains! 1 year ago
testutil some more testutil & tests for the handler database work 1 year ago
version Fixes to allow golangci-lint to run with our preferred configuration 1 year ago
.gitignore Add support for running golangci-lint inside the container 1 year ago
.golangci.yml The pasta of copy has attacked 1 year ago
LICENSE MIT License and including it in releases 1 year ago
Makefile Make test a part of the release process 1 year ago Search domains! 1 year ago
VERSION ldhcpd v0.3.1 1 year ago
box.rb More whitespace neurosis 1 year ago Upgrade to go-transport 0.1.0 for RSA & PKCS#1 support 1 year ago
example.conf Search domains! 1 year ago
go.mod Update dependencies, protobuf/grpc generated golang code 1 year ago
go.sum Update dependencies, protobuf/grpc generated golang code 1 year ago

Light DHCPd

This is a DHCP service/daemon with very few features. It provides basic dynamic IPv4 pool allocation as well as persistent, static leases. iPXE support does not exist yet, but is planned.

One thing Light DHCPd offers that is novel, is a remote control plane powered over GRPC, authenticated and encrypted by TLS client certificates. This control plane can be embedded into your orchestration code or you can use the provided command-line tool to manipulate it from your shell. There is a golang client, and the protobufs are included in the source tree if you wish to generate clients for other languages.

There is a small configuration file for managing dynamic leases and the overall network parameters (resolver, gateway).


Light DHCPd has been powering my network for over a week!

(Seriously, you do not want to use this in production yet.)

Development Instructions

  • make shell: This runs a docker shell. You can do a few things in here:
    • make test: This is context-dependent and will run properly in the container or outside of it, running the unit and functional tests in a container.
    • make interfaces: This sets up some dummy interfaces and plumbs them through a bridge; afterwards veth1 will be available for running a ldhcpd on, and veth3 will be available for running a dhclient on.
    • make start: will start the dhcpd.
    • make stop: stops it.
    • make get-ip: issues a ISC dhclient launch against the second veth pair to get an IP, allowing you to test interaction with a real client.

NOTE: The following instructions install on first run to build the images, will require sudo for that (but nothing else). If you don't want to run sudo to install box, install it in your $PATH somewhere and try again.

Assuming you're not crazy enough to try this on your own network, try this at your shell instead:

$ make shell
# <inside of container>
$ make interfaces
$ make install
$ sudo ldhcpd veth1 example.conf &
$ sudo dhclient -1 -v -d veth3
# ^C it to stop it
$ ip addr
# veth3 ->

If you want to boot the control plane only, without serving DHCP, try the -d flag.

Config File Rundown

# DNS servers

# network gateway

# Search domains (if not specified, the client will not get a default)
  - internal

# Dynamic Range of IPs to use in dynamic lease hand-outs, IP inclusive.

# Lease parameters:
# The duration is the duration of the lease; no other allocation can affect the
# IP you will get back while this lease is obtained.
# The grace period is the maximum amount of time the IP is available to the mac
# address; it is added to the duration. If another mac comes in and there are
# no available IPs, addresses in the grace period may be reclaimed to make
# room.
  duration: 24h
  grace_period: 8h

Making your certificate authority

We use mkcert to generate our certs.

You can use this script to generate a very basic CA that operates over localhost. Depending on your circumstances, you may need to run it as root.

This code also installs it into the paths expected by default in the daemon and client; be mindful of permissions and directory names!

CAROOT=/etc/ldhcpd mkcert -install # CA file will be /etc/ldhcpd/rootCA.pem
CAROOT=/etc/ldhcpd mkcert -cert-file /etc/ldhcpd/server.pem -key-file /etc/ldhcpd/server.key localhost
CAROOT=/etc/ldhcpd mkcert -client -cert-file /etc/ldhcpd/client.pem -key-file /etc/ldhcpd/client.key localhost

Other Notes

ldhcpd will suss out your subnet block from the interface you tell it to listen on. It is very important your interface is configured correctly. We make some checks, but no guarantees! Most importantly, ensure the subnet for ip is configured properly. Subnetting is a bit beyond this document's scope, but this is typically done by associating the IP with a CIDR address space that is less than 32.


2: ens18: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether a6:80:e0:5e:c5:46 brd ff:ff:ff:ff:ff:ff
    inet brd scope global ens18
       valid_lft forever preferred_lft forever
    inet6 2001:1::1/64 scope global
       valid_lft forever preferred_lft forever
    inet6 fe80::a480:e0ff:fe5e:c546/64 scope link
       valid_lft forever preferred_lft forever will get selected here to serve. Only one address like this may be configured for now. We may eventually address this, but for now if you need to serve two subnets, start two of ldhcpd on different interfaces.


These are the items planned for the near future of this project:

  • Per-Lease DNS and Gateway parameters
  • Hostname support:
    • Pushing hostnames
    • Recording hostnames from clients
  • Better, easier to use bridge for the GRPC client
  • PXE booting support
    • maybe with TFTP baked-in?



MIT License


Erik Hollensbe