f9cbb117004294a738add82945f4b3365fa484f0
[project/odhcpd.git] / README
1 odhcpd - Embedded DHCP/DHCPv6/RA Server & Relay
2
3 ** Abstract **
4
5 odhcpd is a daemon for serving and relaying IP management protocols to
6 configure clients and downstream routers. It tries to follow the RFC 6204
7 requirements for IPv6 home routers.
8
9 odhcpd provides server services for DHCP, RA, stateless and stateful DHCPv6,
10 prefix delegation and can be used to relay RA, DHCPv6 and NDP between routed
11 (non-bridged) interfaces in case no delegated prefixes are available.
12
13
14 ** Features **
15
16 1. Router Discovery support (solicitations and advertisements) with 2 modes
17 server: RD server for slave interfaces
18 a) automatic detection of prefixes, delegated prefix and default routes, MTU
19 b) automatic reannouncement when changes to prefixes or routes occur
20
21 relay: RD relay between master and slave interfaces
22 a) support for rewriting announced DNS-server addresses in relay mode
23
24 2. DHCPv6-support with 2 modes of operation
25 server: stateless, stateful and PD-server mode
26 a) stateless and stateful address assignment
27 b) prefix delegation support
28 c) dynamic reconfiguration in case prefixes change
29 d) hostname detection and hosts-file creation
30
31 relay: mostly standards-compliant DHCPv6-relay
32 a) support for rewriting announced DNS-server addresses
33
34 3. DHCPv4-support
35 server: stateless and stateful mode
36
37 4. Proxy for Neighbor Discovery messages (solicitations and advertisements)
38 a) support for auto-learning routes to the local routing table
39 b) support for marking interfaces "external" not proxying NDP for them
40 and only serving NDP for DAD and for traffic to the router itself
41 [Warning: you should provide additional firewall rules for security]
42
43
44 ** Compiling **
45
46 odhcpd uses cmake:
47 * To prepare a Makefile use: "cmake ."
48 * To build / install use: "make" / "make install" afterwards.
49 * To build DEB or RPM packages use: "make package" afterwards.
50
51
52 ** Configuration **
53
54 odhcpd uses a UCI configuration file in /etc/config/dhcp for configuration
55 and may also receive information from ubus
56
57
58 Section of type odhcpd
59
60 Option Type Default Description
61 legacy bool 0 Enable DHCPv4 if start but
62 no dhcpv4 option set
63 maindhcp bool 0 Use odhcpd as the main DHCPv4
64 service
65 leasefile string DHCP/v6 lease/hostfile
66 leasetrigger string Lease trigger script
67 loglevel integer 6 Syslog level priority (0-7)
68
69
70 Sections of type dhcp (configure DHCP / DHCPv6 / RA / NDP service)
71
72 Option Type Default Description
73 interface string <name of UCI section> logical OpenWrt interface
74 ifname string <resolved from logical> physical network interface
75 networkid string same as ifname compat. alias for ifname
76 master bool 0 is a master interface
77 for relaying
78
79 ra string disabled Router Advert service
80 [disabled|server|relay|hybrid]
81 dhcpv6 string disabled DHCPv6 service
82 [disabled|server|relay|hybrid]
83 dhcpv4 string disabled DHCPv4 service
84 [disabled|server]
85 ndp string disabled Neighbor Discovery Proxy
86 [disabled|relay|hybrid]
87
88 dynamicdhcp bool 1 Dynamically create leases
89 for DHCPv4 and DHCPv6
90 dhcpv4_forcereconf bool 0 Force reconfiguration by sending
91 force renew message even if the client
92 did not include the force renew nonce
93 capability option (RFC6704)
94 dhcpv6_assignall bool 1 Assign all viable DHCPv6 addresses
95 in statefull mode; if disabled
96 only the DHCPv6 address having the
97 longest preferred lifetime is assigned
98 dhcpv6_na bool 1 DHCPv6 stateful addressing hands out IA_NA -
99 Internet Address - Network Address
100 dhcpv6_pd bool 1 DHCPv6 stateful addressing hands out IA_PD -
101 Internet Address - Prefix Delegation
102 router list <local address> Routers to announce
103 accepts IPv4 only
104 dns list <local address> DNS servers to announce
105 accepts IPv4 and IPv6
106 dns_service bool 1 Announce the address of interface as DNS service
107 if the list of dns is empty
108 domain list <local search domain> Search domains to announce
109
110 leasetime string 12h DHCPv4 address leasetime
111 start integer 100 DHCPv4 pool start
112 limit integer 150 DHCPv4 pool size
113 preferred_lifetime string 12h Value for the preferred lifetime
114 for a prefix
115 ra_default integer 0 Override default route
116 0: default, 1: ignore no public address, 2: ignore all
117 ra_flags list other-config List of RA flags to be
118 advertised in RA messages
119 [managed-config other-config home-agent none]
120 ra_slaac bool 1 Announce slaac for a prefix
121 ra_offlink bool 0 Announce prefixes off-link
122 ra_preference string medium Route(r) preference
123 [medium|high|low]
124 ra_maxinterval integer 600 Maximum time allowed between
125 sending unsolicited RA
126 ra_mininterval integer 200 Minimum time allowed between
127 sending unsolicited RA
128 ra_lifetime integer 1800 Value to be placed in Router
129 Lifetime field of RA
130 ra_useleasetime bool 0 Use configured leasetime as
131 limit for the preferred and
132 valid lifetime of a prefix
133 ra_reachabletime integer 0 Reachable Time in milliseconds to be
134 advertised in RA messages
135 ra_retranstime integer 0 Retransmit Time in milliseconds to be
136 advertised in RA messages
137 ra_hoplimit integer 0 Current hoplimit to be advertised
138 in RA messages
139 ra_mtu integer 0 MTU to be advertised in
140 RA messages
141 ra_dns bool 1 Announce DNS configuration in
142 RA messages (RFC8106)
143 ndproxy_routing bool 1 Learn routes from NDP
144 ndproxy_slave bool 0 NDProxy external slave
145 prefix_filter string ::/0 Only advertise on-link prefixes within
146 [IPv6 prefix] the provided IPv6 prefix; others are
147 filtered out.
148
149
150 Sections of type host (static leases)
151 Option Type Default Description
152 ip string IP-Address to lease
153 mac string MAC-address
154 duid string DUID in base16
155 hostid string IPv6 host identifier
156 name string Hostname
157 leasetime string DHCPv4/v6 leasetime
158