dhcpv4: dhcpv4: move interface lease list insertion out of dhcpv4_assign
[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 ignore                  bool    0                       do not serve this interface
77                                                         unless overridden by ra, ndp,
78                                                         dhcpv4 or dhcpv6 options
79 master                  bool    0                       is a master interface
80                                                         for relaying
81
82 ra                      string  disabled                Router Advert service
83                         [disabled|server|relay|hybrid]
84 dhcpv6                  string  disabled                DHCPv6 service
85                         [disabled|server|relay|hybrid]
86 dhcpv4                  string  disabled                DHCPv4 service
87                         [disabled|server]
88 ndp                     string  disabled                Neighbor Discovery Proxy
89                         [disabled|relay|hybrid]
90
91 dynamicdhcp             bool    1                       Dynamically create leases
92                                                         for DHCPv4 and DHCPv6
93 dhcpv6_assignall        bool    1                       Assign all viable DHCPv6 addresses
94                                                         in statefull mode; if disabled
95                                                         only the DHCPv6 address having the
96                                                         longest preferred lifetime is assigned
97 router                  list    <local address>         Routers to announce
98                                                         accepts IPv4 only
99 dns                     list    <local address>         DNS servers to announce
100                                                         accepts IPv4 and IPv6
101 domain                  list    <local search domain>   Search domains to announce
102
103 leasetime               string  12h                     DHCPv4 address leasetime
104 start                   integer 100                     DHCPv4 pool start
105 limit                   integer 150                     DHCPv4 pool size
106
107 ra_default              integer 0                       Override default route
108                         0: default, 1: ignore no public address, 2: ignore all
109 ra_management           integer 1                       RA management mode
110                         0: no M-Flag but A-Flag, 1: both M and A, 2: M but not A
111 ra_offlink              bool    0                       Announce prefixes off-link
112 ra_preference           string  medium                  Route(r) preference
113                         [medium|high|low]
114 ra_maxinterval          integer 600                     Maximum time allowed between
115                                                         sending unsolicited RA
116 ra_mininterval          integer 200                     Minimum time allowed between
117                                                         sending unsolicited RA
118 ra_lifetime             integer 1800                    Value to be placed in Router
119                                                         Lifetime field of RA
120 ra_useleasetime         bool    0                       Use configured leasetime as
121                                                         limit for the preferred and
122                                                         valid lifetime of a prefix
123 ra_reachabletime        integer 0                       Reachable Time in milliseconds to be
124                                                         advertised in RA messages
125 ra_retranstime          integer 0                       Retransmit Time in milliseconds to be
126                                                         advertised in RA messages
127 ra_hoplimit             integer 0                       Current hoplimit to be advertised
128                                                         in RA messages
129 ra_mtu                  integer 0                       MTU to be advertised in
130                                                         RA messages
131 ndproxy_routing         bool    1                       Learn routes from NDP
132 ndproxy_slave           bool    0                       NDProxy external slave
133
134
135 Sections of type host (static leases)
136 Option          Type    Default                 Description
137 ip              string                          IP-Address to lease
138 mac             string                          MAC-address
139 duid            string                          DUID in base16
140 hostid          string                          IPv6 host identifier
141 name            string                          Hostname
142 leasetime       string                          DHCPv4/v6 leasetime
143