odhcpd - Embedded DHCP/DHCPv6/RA Server & Relay

Abstract

odhcpd is a daemon for serving and relaying IP management protocols to configure clients and downstream routers. It tries to follow the RFC 6204 requirements for IPv6 home routers.

odhcpd provides server services for DHCP, RA, stateless and stateful DHCPv6, prefix delegation and can be used to relay RA, DHCPv6 and NDP between routed (non-bridged) interfaces in case no delegated prefixes are available.

Features

1. Router Discovery support (solicitations and advertisements) with 2 modes:

   • server: RD server for slave interfaces

     • automatic detection of prefixes, delegated prefix and default routes, MTU
     • automatic reannouncement when changes to prefixes or routes occur

   • relay: RD relay between master and slave interfaces

     • support for rewriting announced DNS-server addresses in relay mode

2. DHCPv6-support with 2 modes of operation

   • server: stateless, stateful and PD-server mode

     • stateless and stateful address assignment
     • prefix delegation support
     • dynamic reconfiguration in case prefixes change
     • hostname detection and hosts-file creation

   • relay: mostly standards-compliant DHCPv6-relay

     • support for rewriting announced DNS-server addresses

3. DHCPv4-support

   • server: stateless and stateful mode

4. Proxy for Neighbor Discovery messages (solicitations and advertisements)

   • support for auto-learning routes to the local routing table
   • support for marking interfaces "external" not proxying NDP for them and only serving NDP for DAD and for traffic to the router itself [Warning: you should provide additional firewall rules for security]

5. IPv6 PxE Support

Compiling

odhcpd uses cmake:

• To prepare a Makefile use: cmake .
• To build / install use: make / make install afterwards.
• To build DEB or RPM packages use: make package afterwards.

Configuration

odhcpd uses a UCI configuration file in /etc/config/dhcp for configuration and may also receive information from ubus

Section of type odhcpd

Option	Type	Default	Description
legacy	bool	0	Enable DHCPv4 if start but no dhcpv4 option set
maindhcp	bool	0	Use odhcpd as the main DHCPv4 service
leasefile	string		DHCP/v6 lease/hostfile
leasetrigger	string		Lease trigger script
hostsfile	string		DHCP/v6 hostfile
loglevel	integer	6	Syslog level priority (0-7)
piofolder	string		Folder to store IPv6 prefix information (to detect stale prefixes, see RFC9096, §3.5)

Sections of type dhcp (configure DHCP / DHCPv6 / RA / NDP service)

Option	Type	Default	Description
interface	string	<name of UCI section>	logical OpenWrt interface
ifname	string	<resolved from logical>	physical network interface
networkid	string	same as ifname	compat. alias for ifname
master	bool	0	is a master interface for relaying
ra	string	disabled	Router Advert service [disabled|server|relay|hybrid]
dhcpv6	string	disabled	DHCPv6 service [disabled|server|relay|hybrid]
dhcpv4	string	disabled	DHCPv4 service [disabled|server]
ndp	string	disabled	Neighbor Discovery Proxy [disabled|relay|hybrid]
dynamicdhcp	bool	1	Dynamically create leases for DHCPv4 and DHCPv6
dhcpv4_forcereconf	bool	0	Force reconfiguration by sending force renew message even if the client did not include the force renew nonce capability option (RFC6704)
dhcpv6_assignall	bool	1	Assign all viable DHCPv6 addresses in statefull mode; if disabled only the DHCPv6 address having the longest preferred lifetime is assigned
dhcpv6_hostidlength	integer	12	Host ID length of dynamically created leases, allowed values: 12 - 64 (bits).
dhcpv6_na	bool	1	DHCPv6 stateful addressing hands out IA_NA - Internet Address - Network Address
dhcpv6_pd	bool	1	DHCPv6 stateful addressing hands out IA_PD - Internet Address - Prefix Delegation
dhcpv6_pd_min_len	integer	-	Minimum prefix length to delegate with IA_PD (value is adjusted if needed to be greater than the interface prefix length). Range [1,62]
router	list	<local address>	Routers to announce, accepts IPv4 only
dns	list	<local address>	DNS servers to announce, accepts IPv4 and IPv6
dnr	list	disabled	Encrypted DNS servers to announce, <priority> <domain name> [<comma separated IP addresses> <SvcParams (key=value)>...]
dns_service	bool	1	Announce the address of interface as DNS service if the list of dns is empty
domain	list	<local search domain>	Search domains to announce
leasetime	string	12h	DHCPv4 address leasetime
start	integer	100	DHCPv4 pool start
limit	integer	150	DHCPv4 pool size
max_preferred_lifetime	string	45m	Upper limit for the preferred lifetime for a prefix
max_valid_lifetime	string	90m	Upper limit for the valid lifetime for a prefix
ra_default	integer	0	Override default route - 0: default, 1: ignore no public address, 2: ignore all
ra_flags	list	other-config	List of RA flags to be advertised in RA messages [managed-config|other-config|home-agent|none]
ra_slaac	bool	1	Announce slaac for a prefix
ra_offlink	bool	0	Announce prefixes off-link
ra_preference	string	medium	Route(r) preference [medium|high|low]
ra_maxinterval	integer	600	Maximum time allowed between sending unsolicited RA
ra_mininterval	integer	200	Minimum time allowed between sending unsolicited RA
ra_lifetime	integer	2700	Value to be placed in Router Lifetime field of RA. Not recommended to be more than 2700 (RFC9096).
ra_reachabletime	integer	0	Reachable Time in milliseconds to be advertised in RA messages
ra_retranstime	integer	0	Retransmit Time in milliseconds to be advertised in RA messages
ra_hoplimit	integer	0	Current hoplimit to be advertised in RA messages
ra_mtu	integer	-	MTU to be advertised in RA messages
ra_dns	bool	1	Announce DNS configuration in RA messages (RFC8106)
ra_pref64	string	-	Announce PREF64 option for NAT64 prefix (RFC8781) [IPv6 prefix]
ndproxy_routing	bool	1	Learn routes from NDP
ndproxy_slave	bool	0	NDProxy external slave
ndp_from_link_local	bool	1	Use link-local source addresses for NDP operations (RFC 4861, §4.2 compliance) and macOS compatibility
prefix_filter	string	::/0	Only advertise on-link prefixes within the provided IPv6 prefix; others are filtered out. [IPv6 prefix]
ntp	list	<local address>	NTP servers to announce accepts IPv4 and IPv6

Sections of type host (static leases)

Option	Type	Default	Description
ip	string	(none)	IPv4 host address
mac	list|string	(none)	HexadecimalMACaddress(es)
duid	list|string	(none)	Hexadecimal DUID(s), or DUID%IAID(s)
hostid	string	(none)	IPv6hostidentifier
name	string	(none)	Hostname
leasetime	string	(none)	DHCPv4/v6leasetime

Sections of type boot6

Option	Type	Required	Description
url	string	yes	e.g. tftp://[fd11::1]/pxe.efi
arch	integer	no	the arch code. 07 is EFI. If not present, this boot6 will be the default.

ubus Interface

odhcpd currently exposes the following methods under the dhcp object path:

Method	Arguments	Description
ipv4leases	none	Lists all currently active DHCPv4 leases per interface
ipv6leases	none	Lists all currently active DHCPv6 leases per interface
ipv6ra	none	Lists announced IPv6 prefixes per interface
add_lease	options as in the cfg host section	Creates a new static lease, the arguments need to be formatted as a valid JSON string

These can be called by running e.g. ubus call dhcp ipv6leases on your OpenWrt device.

odhcpd currently broadcasts the following events via ubus:

Name	Parameters	Description
dhcp.ack	mac,ip,name,interface	A new DHCPv4 lease has been created
dhcp.release	mac,ip,name,interface	A DHCPv4 lease has been released by a client
dhcp.expire	mac,ip,name,interface	A DHCPv4 lease has expired

These can be observed by running e.g. ubus listen dhcp on your OpenWrt device.