| Both sides previous revision Previous revision Next revision | Previous revision |
| docs:techref:odhcpd [2021/02/05 09:14] – [Abstract] missing “and” in sub-series mwynn | 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]] |
| | |
| | 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 and | 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 ===== |
| |
| ==== Router Discovery (RD) ==== | ==== Router Discovery (RD) ==== |
| |
| Router Discovery (RD) support (solicitations and advertisements) with 2 modes of operation: | Router Discovery (RD) support (solicitations and advertisements) with 2 modes of operation: |
| | - RD Server mode: Router Discovery (RD) server for slave interfaces: |
| - RD Server mode: Router Discovery (RD) server for slave interfaces: | - Automatic detection of prefixes, delegated prefix, default routes and MTU. |
| - Automatic detection of prefixes, delegated prefix, default routes and MTU. | - Automatic re-announcement of any changes in either prefixes or routes. |
| - Automatic re-announcement of any changes in either prefixes or routes. | - RD Relay mode: Router Discovery (RD) relay between master and slave interfaces. |
| - RD Relay mode: Router Discovery (RD) relay between master and slave interfaces. | - Supports rewriting of the announced DNS server addresses. |
| - Supports rewriting of the announced DNS servers addresses. | |
| |
| ==== DHCPv6 ==== | ==== DHCPv6 ==== |
| |
| DHCPv6 support with 2 modes of operation: | DHCPv6 support with 2 modes of operation: |
| | - DHCPv6 Server mode: stateless, stateful and Prefix Delegation (PD) server mode: |
| | - Stateless and stateful address assignment. |
| | - Prefix delegation support. |
| | - Dynamic reconfiguration of any changes in Prefix Delegation. |
| | - Hostname detection and hosts-file creation. |
| | - DHCPv6 Relay mode: A mostly standards-compliant DHCPv6-relay: |
| | - Supports rewriting of the announced DNS server addresses. |
| |
| - DHCPv6 Server mode: stateless, stateful and Prefix Delegation (PD) server mode: | ==== DHCPv4 ==== |
| - Stateless and stateful address assignment. | - Stateless and stateful DHCPv4 server mode. |
| - Prefix delegation support. | |
| - Dynamic reconfiguration of any changes in Prefix Delegation. | |
| - Hostname detection and hosts-file creation. | |
| - DHCPv6 Relay mode: A mostly standards-compliant DHCPv6-relay: | |
| - Supports rewriting of the announced DNS servers addresses. | |
| |
| ==== DHCPv4 ==== | |
| - Stateless and stateful DHCPv4 server mode. | |
| | |
| ==== Neighbor Discovery Proxy (NDP) ==== | ==== Neighbor Discovery Proxy (NDP) ==== |
| | Proxy for Neighbor Discovery solicitation and advertisement messages (NDP): |
| | - Supports auto-learning of routes to the local routing table. |
| | - Supports marking interfaces as "external". |
| |
| Proxy for Neighbor Discovery solicitation and advertisement messages (NDP): | 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. |
| - Supports auto-learning of routes to the local routing table. | |
| - Support marking interfaces as "external". | |
| | |
| 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. | |
| |
| Warning: Interfacs marked as external, need additional firewall rules for security! | :!: Interfaces marked as external need additional firewall rules for security! |
| |
| ===== 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. | |
| | |
| | |
| ==== odhcpd Section ==== | |
| |
| | ==== odhcpd section ==== |
| Configuration for the odhcp daemon. | Configuration for the odhcp daemon. |
| |
| ^ Name ^ Type ^ Default ^ Description ^ | ^ Name ^ Type ^ Default ^ Description ^ |
| | ''legacy'' | ''boolean'' | ''0'' | Enable DHCPv4 if the 'dhcp' section constains a ''start'' option, but no ''dhcpv4'' option set. | | | ''legacy'' | boolean | ''0'' | Enable DHCPv4 if the 'dhcp' section contains a ''start'' option, but no ''dhcpv4'' option set. | |
| | ''leasefile'' | ''string'' | | Location of the lease/hostfile for DHCPv4 and DHCPv6. | | | ''maindhcp'' | boolean | ''0'' | Use odhcpd as the main DHCPv4 service. | |
| | ''leasetrigger'' | ''string'' | | Location of the lease trigger script. | | | ''leasefile'' | string | | Location of the lease/hostfile for DHCPv4 and DHCPv6. | |
| | | ''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 | |
| ==== dhcp Section ==== | |
| |
| | ==== dhcp section ==== |
| Configuration for DHCPv4, DHCPv6, RA and NDP services. | Configuration for DHCPv4, DHCPv6, RA and NDP services. |
| |
| <sortable> | <sortable> |
| ^ Name ^ Type ^ Required ^ Default ^ Description ^ | ^ Name ^ Type ^ Required ^ Default ^ Description ^ |
| | ''interface'' | string | | ''<name of UCI section>'' | Logical OpenWrt interface. | | | ''interface'' | string | | ''<name of UCI section>'' | Logical OpenWrt interface. | |
| | ''ifname'' | string | | ''<resolved from logical>'' | Physical network interface. | | | ''ifname'' | string | | ''<resolved from logical>'' | Physical network interface. | |
| | ''networkid'' | string | | ''<same as ifname>'' | Alias of ''ifname'' for compatibility. | | | ''networkid'' | string | | ''<same as ifname>'' | Alias of ''ifname'' for compatibility. | |
| | ''ignore'' | boolean | | ''0'' | do not serve this interface unless overridden by ''ra'', ''ndp'', ''dhcpv4'' or ''dhcpv6'' options. | | | ''ignore'' | boolean | | ''0'' | Do not serve this interface unless overridden by ''ra'', ''ndp'', ''dhcpv4'' or ''dhcpv6'' options. | |
| | ''master'' | boolean | | ''0'' | is a master interface for relaying | | | ''master'' | boolean | | ''0'' | Is a master interface for relaying. | |
| | ''ra'' | string | | ''disabled'' | Router Advert service. Set to ''disabled'', ''server'', ''relay'' or ''hybrid''. | | | ''ra'' | string | | ''disabled'' | Router Advert service. Set to ''disabled'', ''server'', ''relay'' or ''hybrid''. | |
| | ''dhcpv6'' | string | | ''disabled'' | DHCPv6 service. Set to ''disabled'', ''server'', ''relay'' or ''hybrid''. | | | ''dhcpv6'' | string | | ''disabled'' | DHCPv6 service. Set to ''disabled'', ''server'', ''relay'' or ''hybrid''. | |
| | ''dhcpv4'' | string | | ''disabled'' | DHCPv4 service. Set to ''disabled'' or ''server''. | | | ''dhcpv4'' | string | | ''disabled'' | DHCPv4 service. Set to ''disabled'' or ''server''. | |
| | ''ndp'' | string | | ''disabled'' | Neighbor Discovery Proxy. Set to ''disabled'', ''relay'' or ''hybrid'' | | | ''ndp'' | string | | ''disabled'' | Neighbor Discovery Proxy. Set to ''disabled'', ''relay'' or ''hybrid''. | |
| | ''dynamicdhcp'' | boolean | | ''1'' | Leases for DHCPv4 and DHCPv6 are created dynamically. | | | ''dynamicdhcp'' | boolean | | ''1'' | Leases for DHCPv4 and DHCPv6 are created dynamically. | |
| | ''dns'' | list | | ''<local address>'' | DNS servers to announce on the network. IPv4 and IPv6 addresses are accepted. | | | ''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]]). | |
| | ''domain'' | list | | ''<local search domain>'' | Search domains to announce on the network. | | | ''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. | |
| | ''leasetime'' | string | | ''12h'' | DHCPv4 address leasetime | | | ''dhcpv6_hostidlength'' | integer | | ''12'' | Host ID length of dynamically created leases, allowed values: 12 - 64 (bits). | |
| | ''start'' | integer | | ''100'' | Starting address of the DHCPv4 pool. | | | ''dhcpv6_na'' | boolean | | ''1'' | DHCPv6 stateful addressing hands out IA_NA - Internet Address - Network Address. | |
| | ''limit'' | integer | | ''150'' | Number of addresses in the DHCPv4 pool. | | | ''dhcpv6_pd'' | boolean | | ''1'' | DHCPv6 stateful addressing hands out IA_PD - Internet Address - Prefix Delegation. | |
| | ''ra_default'' | integer | | ''0'' | Override default route- Set to ''0'' (default), ''1'' (ignore, no public address) or ''2'' (ignore all). | | | ''router'' | list | | ''<local address>'' | Routers to announce accepts IPv4 only. | |
| | ''ra_management'' | integer | | ''1'' | RA management mode. See the "RA Management Modes" table below. | | | ''dns'' | list | | ''<local address>'' | DNS servers to announce on the network. IPv4 and IPv6 addresses are accepted. | |
| | ''ra_offlink'' | boolean | | ''0'' | Announce prefixes off-link | | | ''dns_service'' | boolean | | ''1'' | Announce the address of interface as DNS service if the list of DNS is empty. | |
| | ''ra_preference'' | string | | ''medium'' | Route preference ''medium'', ''high'' or ''low'' | | | ''domain'' | list | | ''<local search domain>'' | Search domains to announce on the network. | |
| | ''ra_maxinterval'' | integer | | ''600'' | Maximum time allowed between sending unsolicited Router Advertisements (RA). | | | ''leasetime'' | string | | ''12h'' | DHCPv4 address leasetime | |
| | ''ra_mininterval'' | integer | | ''200'' | Minimum time allowed between sending unsolicited Router Advertisements (RA). | | | ''start'' | integer | | ''100'' | Starting address of the DHCPv4 pool. | |
| | ''ra_lifetime'' | integer | | ''1800'' | Router Lifetime published in Router Advertisement (RA) messages. | | | ''limit'' | integer | | ''150'' | Number of addresses in the DHCPv4 pool. | |
| | ''ra_useleasetime'' | boolean | | ''0'' | If set, the configured DHCPv4 ''leasetime'' is also used as limit and preferred lifetime of the IPv6 prefix. | | | ''preferred_lifetime'' | string | | ''12h'' | Value for the preferred lifetime for a prefix. | |
| | ''ra_reachabletime'' | integer | | ''0'' | Reachable Time in milliseconds to be published in Router Advertisement (RA) messages'. | | | ''ra_default'' | integer | | ''0'' | Override default route. Set to ''0'' (default), ''1'' (ignore, no public address) or ''2'' (ignore all). | |
| | ''ra_retranstime'' | integer | | ''0'' | Retransmit Time in milliseconds to be published in Router Advertisment (RA) messages. | | | ''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_hoplimit'' | integer | | ''0'' | The maximum hops to be published in Router Advertisement (RA) messages. | | | ''ra_slaac'' | boolean | | ''1'' | Announce SLAAC for a prefix (that is, set the A flag in RA messages). | |
| | ''ra_mtu'' | integer | | ''0'' | The MTU to be published in Router Advertisement (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'') | |
| | ''ndproxy_routing'' | boolean | | ''1'' | Learn routes from ND.P | | | ''ra_offlink'' | boolean | | ''0'' | Announce prefixes off-link. | |
| | ''ndproxy_slave'' | boolean | | ''0'' | NDProxy external slave. | | | ''ra_preference'' | string | | ''medium'' | Route preference ''medium'', ''high'' or ''low''. | |
| | ''ndproxy_static'' | list | | | Static NDProxy prefixes. | | | ''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> | </sortable> |
| |
| |
| === RA Management Modes === | |
| |
| ^ Mode ^ M Flag ^ A Flag ^ Description ^ | |
| |''0''|No|Yes|Only stateless (SLAAC) configuration enabled.| | |
| |''1''|Yes|Yes|Both stateless (SLAAC) and stateful (DHCPv6) configurations are enabled.| | |
| |''2''|Yes|No|Only statefull (DHCPv6) configuration is enabled.| | |
| |
| |
| ==== host section ==== | ==== host section ==== |
| |
| The ''host'' section is where static leases are defined. | The ''host'' section is where static leases are defined. |
| |
| ^ Name ^ Type ^ Required ^ Default ^ Description ^ | ^ Name ^ Type ^ Required ^ Default ^ Description ^ |
| |''ip''|string|Yes|None|IP-Address to lease| | | ''ip'' | string | yes | //(none)// | IP address to lease | |
| |''mac''|string|Optional|None|MAC-address| | | ''mac'' | string | no | //(none)// | MAC address | |
| |''duid''|string|No|None|DUID in base16| | | ''duid'' | string | no | //(none)// | DUID in base16 | |
| |''hostid''|string|No|None|IPv6 host identifier| | | ''hostid'' | string | no | //(none)// | IPv6 host identifier | |
| |''name''|string|No|None|Hostname| | | ''name'' | string | no | //(none)// | Hostname | |
| | | ''leasetime'' | string | no | //(none)// | DHCPv4/v6 leasetime | |
| |
| | Example ''hostid='105ee0badc0de''' => IPv6 '::1:5ee:bad:c0de' |
| |
| ===== ubus API ===== | ===== ubus API ===== |
| | Replace dnsmasq with odhcpd to access IPv4 leases. |
| | |
| <code bash> | <code bash> |
| ubus -v list dhcp | ubus -v list dhcp |
| |
| ===== Compiling ===== | ===== Compiling ===== |
| | odhcpd uses cmake. |
| |
| odhcpd uses cmake: | <code bash> |
| * To prepare a Makefile use: "cmake ." | # Prepare |
| * To build / install use: "make" / "make install" afterwards. | cmake . |
| * To build DEB or RPM packages use: "make package" afterwards. | |
| |
| ===== Documentation ===== | # Build/install |
| | make |
| | make install |
| |
| * [[https://git.openwrt.org/?p=project/odhcpd.git;a=blob_plain;f=README;hb=openwrt-19.07|README @ 19.07]] | # Build DEB/RPM packages |
| * [[https://github.com/openwrt/odhcpd/blob/master/README|README @ Snapshot]] | make package |
| | </code> |
| |