| Both sides previous revision Previous revision Next revision | Previous revision |
| docs:techref:odhcpd [2020/08/05 15:42] – added stateless/stateful info, content optimized vgaetera | docs:techref:odhcpd [2024/04/09 03:19] (current) – [Table] systemcrash |
|---|
| ====== odhcpd ====== | ====== odhcpd ====== |
| **Embedded DHCP/DHCPv6/RA Server & Relay** | See also: [[https://github.com/openwrt/odhcpd/blob/master/README|odhcpd upstream documentation]] |
| |
| Development is happening at: https://github.com/sbyx/odhcpd. This documentation was taken from the [[https://github.com/openwrt/odhcpd|project's README]]. [As of 10/28/2018 https://github.com/sbyx/odhcpd is "157 commits behind openwrt:master". Development seems to have moved to [[https://git.openwrt.org/?p=project/odhcpd.git;a=summary]] ] | odhcpd is an embedded DHCP/DHCPv6/RA server & NDP relay. |
| |
| ===== Abstract ===== | ===== Abstract ===== |
| odhcpd is a daemon for serving and relaying IP management protocols to | odhcpd is a daemon for serving and relaying IP management protocols to configure clients and downstream routers. |
| configure clients and downstream routers. It tries to follow the RFC 6204 | It tries to follow the [[https://datatracker.ietf.org/doc/html/rfc6204|RFC 6204]] requirements for IPv6 home routers. |
| requirements for IPv6 home routers. | |
| |
| odhcpd provides server services for DHCP, RA, stateless and stateful DHCPv6, | odhcpd provides server services for DHCP, RA, stateless SLAAC 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. |
| 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 ===== | ===== Features ===== |
| 1. Router Discovery support (solicitations and advertisements) with 2 modes | ==== Router Discovery (RD) ==== |
| server: RD server for slave interfaces | Router Discovery (RD) support (solicitations and advertisements) with 2 modes of operation: |
| a) automatic detection of prefixes, delegated prefix and default routes, MTU | - RD Server mode: Router Discovery (RD) server for slave interfaces: |
| b) automatic reannouncement when changes to prefixes or routes occur | - Automatic detection of prefixes, delegated prefix, default routes and MTU. |
| | - Automatic re-announcement of any changes in either prefixes or routes. |
| | - RD Relay mode: Router Discovery (RD) relay between master and slave interfaces. |
| | - Supports rewriting of the announced DNS server addresses. |
| |
| relay: RD relay between master and slave interfaces | ==== DHCPv6 ==== |
| a) support for rewriting announced DNS-server addresses in relay mode | DHCPv6 support with 2 modes of operation: |
| | - DHCPv6 Server mode: stateless, stateful and Prefix Delegation (PD) server mode: |
| 2. DHCPv6-support with 2 modes of operation | - Stateless and stateful address assignment. |
| server: stateless, stateful and PD-server mode | - Prefix delegation support. |
| a) stateless and stateful address assignment | - Dynamic reconfiguration of any changes in Prefix Delegation. |
| b) prefix delegation support | - Hostname detection and hosts-file creation. |
| c) dynamic reconfiguration in case prefixes change | - DHCPv6 Relay mode: A mostly standards-compliant DHCPv6-relay: |
| d) hostname detection and hosts-file creation | - Supports rewriting of the announced DNS server addresses. |
| |
| relay: mostly standards-compliant DHCPv6-relay | ==== DHCPv4 ==== |
| a) support for rewriting announced DNS-server addresses | - Stateless and stateful DHCPv4 server mode. |
| | |
| 3. DHCPv4-support | |
| server: stateless and stateful mode | |
| |
| 4. Proxy for Neighbor Discovery messages (solicitations and advertisments) | ==== Neighbor Discovery Proxy (NDP) ==== |
| a) support for auto-learning routes to the local routing table | Proxy for Neighbor Discovery solicitation and advertisement messages (NDP): |
| b) support for marking interfaces "external" not proxying NDP for them | - Supports auto-learning of routes to the local routing table. |
| and only serving NDP for DAD and for traffic to the router itself | - Supports marking interfaces as "external". |
| [Warning: you should provide additional firewall rules for security] | |
| |
| ===== Compiling ===== | Interfaces marked as "external" will not receive any proxyied NDP content and are only served with NDP for Duplicate Address Detection (DAD) and traffic to the router itself. |
| odhcpd uses cmake: | |
| * To prepare a Makefile use: "cmake ." | :!: Interfaces marked as external need additional firewall rules for security! |
| * To build / install use: "make" / "make install" afterwards. | |
| * To build DEB or RPM packages use: "make package" afterwards. | |
| |
| ===== Configuration ===== | ===== Configuration ===== |
| odhcpd uses a UCI configuration file in /etc/config/dhcp for configuration | odhcpd uses a UCI configuration file in ''/etc/config/dhcp'' for configuration and may also receive information from ubus. |
| and may also receive information from ubus | |
| |
| <code> | ==== odhcpd section ==== |
| Section of type odhcpd | Configuration for the odhcp daemon. |
| |
| Option Type Default Description | ^ Name ^ Type ^ Default ^ Description ^ |
| legacy bool 0 Enable DHCPv4 if start but | | ''legacy'' | boolean | ''0'' | Enable DHCPv4 if the 'dhcp' section contains a ''start'' option, but no ''dhcpv4'' option set. | |
| no dhcpv4 option set | | ''maindhcp'' | boolean | ''0'' | Use odhcpd as the main DHCPv4 service. | |
| leasefile string DHCP/v6 lease/hostfile | | ''leasefile'' | string | | Location of the lease/hostfile for DHCPv4 and DHCPv6. | |
| leasetrigger string Lease trigger script | | ''leasetrigger'' | string | | Location of the lease trigger script. | |
| | | ''loglevel'' | integer | ''6'' | Syslog level priority (0-7). 0=emer, 1=alert, 2=crit, 3=err, 4=warn, 5=notice, 6=info, 7=debug | |
| |
| Sections of type dhcp (configure DHCP / DHCPv6 / RA / NDP service) | ==== dhcp section ==== |
| | Configuration for DHCPv4, DHCPv6, RA and NDP services. |
| |
| Option Type Default Description | <sortable> |
| interface string <name of UCI section> logical OpenWrt interface | ^ Name ^ Type ^ Required ^ Default ^ Description ^ |
| ifname string <resolved from logical> physical network interface | | ''interface'' | string | | ''<name of UCI section>'' | Logical OpenWrt interface. | |
| networkid string same as ifname compat. alias for ifname | | ''ifname'' | string | | ''<resolved from logical>'' | Physical network interface. | |
| ignore bool 0 do not serve this interface | | ''networkid'' | string | | ''<same as ifname>'' | Alias of ''ifname'' for compatibility. | |
| unless overridden by ra, ndp, | | ''ignore'' | boolean | | ''0'' | Do not serve this interface unless overridden by ''ra'', ''ndp'', ''dhcpv4'' or ''dhcpv6'' options. | |
| dhcpv4 or dhcpv6 options | | ''master'' | boolean | | ''0'' | Is a master interface for relaying. | |
| master bool 0 is a master interface | | ''ra'' | string | | ''disabled'' | Router Advert service. Set to ''disabled'', ''server'', ''relay'' or ''hybrid''. | |
| for relaying | | ''dhcpv6'' | string | | ''disabled'' | DHCPv6 service. Set to ''disabled'', ''server'', ''relay'' or ''hybrid''. | |
| | | ''dhcpv4'' | string | | ''disabled'' | DHCPv4 service. Set to ''disabled'' or ''server''. | |
| | | ''ndp'' | string | | ''disabled'' | Neighbor Discovery Proxy. Set to ''disabled'', ''relay'' or ''hybrid''. | |
| | | ''dynamicdhcp'' | boolean | | ''1'' | Leases for DHCPv4 and DHCPv6 are created dynamically. | |
| | | ''dhcpv4_forcereconf'' | boolean | | ''0'' | Force reconfiguration by sending force renew message even if the client did not include the force renew nonce capability option ([[https://datatracker.ietf.org/doc/html/rfc6704|RFC 6704]]). | |
| | | ''dhcpv6_assignall'' | boolean | | ''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'' | boolean | | ''1'' | DHCPv6 stateful addressing hands out IA_NA - Internet Address - Network Address. | |
| | | ''dhcpv6_pd'' | boolean | | ''1'' | DHCPv6 stateful addressing hands out IA_PD - Internet Address - Prefix Delegation. | |
| | | ''router'' | list | | ''<local address>'' | Routers to announce accepts IPv4 only. | |
| | | ''dns'' | list | | ''<local address>'' | DNS servers to announce on the network. IPv4 and IPv6 addresses are accepted. | |
| | | ''dns_service'' | boolean | | ''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 on the network. | |
| | | ''leasetime'' | string | | ''12h'' | DHCPv4 address leasetime | |
| | | ''start'' | integer | | ''100'' | Starting address of the DHCPv4 pool. | |
| | | ''limit'' | integer | | ''150'' | Number of addresses in the DHCPv4 pool. | |
| | | ''preferred_lifetime'' | string | | ''12h'' | Value for the preferred lifetime for a prefix. | |
| | | ''ra_default'' | integer | | ''0'' | Override default route. Set to ''0'' (default), ''1'' (ignore, no public address) or ''2'' (ignore all). | |
| | | ''ra_flags'' | list | | ''other-config'' | List of RA flags to be advertised in RA messages:\\ ''managed-config'' - get address information from DHCPv6 server. If this flag is set, ''%%other-config%%'' flag is redundant.\\ ''other-config'' - get other configuration from DHCPv6 server (such as DNS servers). See [[https://datatracker.ietf.org/doc/html/rfc4861#section-4.2|here]] for details.\\ ''home-agent'' - see [[https://datatracker.ietf.org/doc/html/rfc3775#section-7.1|here]] for details.\\ ''none''.\\ OpenWrt since version 21.02 configures ''managed-config'' and ''other-config'' [[https://github.com/openwrt/openwrt/blob/openwrt-21.02/package/network/services/odhcpd/files/odhcpd.defaults#L49-L50|by default]]. | |
| | | ''ra_slaac'' | boolean | | ''1'' | Announce SLAAC for a prefix (that is, set the A flag in RA messages). | |
| | | ''ra_management'' | integer | no | ''1'' | :!: This option is [[commit>?p=project/odhcpd.git;a=commit;h=e73bf11dee1073aaaddc0dc67ca8c7d75ae3c6ad|deprecated]]. Use ''ra_flags'' and ''ra_slaac'' options instead. \\ RA management mode: no M-Flag but A-Flag (''0''), both M and A flags (''1''), M flag but not A flag (''2'') | |
| | | ''ra_offlink'' | boolean | | ''0'' | Announce prefixes off-link. | |
| | | ''ra_preference'' | string | | ''medium'' | Route preference ''medium'', ''high'' or ''low''. | |
| | | ''ra_maxinterval'' | integer | | ''600'' | Maximum time allowed between sending unsolicited Router Advertisements (RA). | |
| | | ''ra_mininterval'' | integer | | ''200'' | Minimum time allowed between sending unsolicited Router Advertisements (RA). | |
| | | ''ra_lifetime'' | integer | | ''1800'' | Router Lifetime published in Router Advertisement (RA) messages. | |
| | | ''ra_useleasetime'' | boolean | | ''0'' | If set, the configured DHCPv4 ''leasetime'' is used both as limit for the preferred and valid lifetime of an IPv6 prefix. | |
| | | ''ra_reachabletime'' | integer | | ''0'' | Reachable Time in milliseconds to be published in Router Advertisement (RA) messages'. | |
| | | ''ra_retranstime'' | integer | | ''0'' | Retransmit Time in milliseconds to be published in Router Advertisment (RA) messages. | |
| | | ''ra_hoplimit'' | integer | | ''0'' | The maximum hops to be published in Router Advertisement (RA) messages. | |
| | | ''ra_mtu'' | integer | | ''0'' | The MTU to be published in Router Advertisement (RA) messages. | |
| | | ''ra_dns'' | boolean | | ''1'' | Announce DNS configuration in RA messages ([[https://datatracker.ietf.org/doc/html/rfc8106|RFC 8106]]). | |
| | | ''ndproxy_routing'' | boolean | | ''1'' | Learn routes from NDP. | |
| | | ''ndproxy_slave'' | boolean | | ''0'' | NDProxy external slave. | |
| | | ''ndproxy_static'' | list | | | Static NDProxy prefixes. | |
| | | ''prefix_filter'' | string | | ''::/0'' | Only advertise on-link prefixes within the provided IPv6 prefix. Others are filtered out. | |
| | | ''ntp'' | list | | | DHCPv6 stateful option 56 to Announce NTP servers | |
| | </sortable> |
| |
| ra string disabled Router Advert service | ==== host section ==== |
| [disabled|server|relay|hybrid] | The ''host'' section is where static leases are defined. |
| 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 | ^ Name ^ Type ^ Required ^ Default ^ Description ^ |
| for DHCPv4 and DHCPv6 | | ''ip'' | string | yes | //(none)// | IP address to lease | |
| dns list <local address> DNS servers to announce | | ''mac'' | string | no | //(none)// | MAC address | |
| accepts IPv4 and IPv6 | | ''duid'' | string | no | //(none)// | DUID in base16 | |
| domain list <local search domain> Search domains to announce | | ''hostid'' | string | no | //(none)// | IPv6 host identifier | |
| | | ''name'' | string | no | //(none)// | Hostname | |
| | | ''leasetime'' | string | no | //(none)// | DHCPv4/v6 leasetime | |
| |
| leasetime string 12h DHCPv4 address leasetime | Example ''hostid='105ee0badc0de''' => IPv6 '::1:5ee:bad:c0de' |
| start integer 100 DHCPv4 pool start | |
| limit integer 150 DHCPv4 pool size | |
| | |
| ra_default integer 0 Override default route | |
| 0: default, 1: ignore no public address, 2: ignore all | |
| ra_management integer 1 RA management mode | |
| 0: no M-Flag but A-Flag, 1: both M and A, 2: M but not A | |
| A-Flag: SLAAC / stateless, M-Flag: DHCPv6 / stateful | |
| 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 1800 Value to be placed in Router | |
| Lifetime field of RA | |
| ra_useleasetime bool 0 Use configured leasetime as | |
| limit for the preferred and | |
| valid lifetime of a prefix | |
| 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 0 MTU to be advertised in | |
| RA messages | |
| | |
| ndproxy_routing bool 1 Learn routes from NDP | |
| ndproxy_slave bool 0 NDProxy external slave | |
| ndproxy_static list Static NDProxy prefixes | |
| | |
| Sections of type host (static leases) | |
| Option Type Default Description | |
| ip string IP-Address to lease | |
| mac string MAC-address | |
| duid string DUID in base16 | |
| hostid string IPv6 host identifier | |
| name string Hostname | |
| </code> | |
| |
| ===== ubus API ===== | ===== ubus API ===== |
| | Replace dnsmasq with odhcpd to access IPv4 leases. |
| | |
| <code bash> | <code bash> |
| ubus -v list dhcp | ubus -v list dhcp |
| ubus call dhcp ipv4leases | ubus call dhcp ipv4leases |
| ubus call dhcp ipv6leases | ubus call dhcp ipv6leases |
| | </code> |
| | |
| | ===== Compiling ===== |
| | odhcpd uses cmake. |
| | |
| | <code bash> |
| | # Prepare |
| | cmake . |
| | |
| | # Build/install |
| | make |
| | make install |
| | |
| | # Build DEB/RPM packages |
| | make package |
| </code> | </code> |
| |