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_hostidlength     integer 12                      Host ID length of dynamically created leases,
  99                                                         allowed values: 12 - 64 (bits).
 100 dhcpv6_na               bool    1                       DHCPv6 stateful addressing hands out IA_NA -
 101                                                                 Internet Address - Network Address
 102 dhcpv6_pd               bool    1                       DHCPv6 stateful addressing hands out IA_PD -
 103                                                                 Internet Address - Prefix Delegation
 104 dhcpv6_pd_min_len       integer -                       Minimum prefix length to delegate with IA_PD
 105                                                         (value is adjusted if needed to be greater
 106                                                         than the interface prefix length).  Range [1,62]
 107 router                  list    <local address>         Routers to announce
 108                                                         accepts IPv4 only
 109 dns                     list    <local address>         DNS servers to announce
 110                                                         accepts IPv4 and IPv6
 111 dns_service             bool    1                       Announce the address of interface as DNS service
 112                                                         if the list of dns is empty
 113 domain                  list    <local search domain>   Search domains to announce
 114
 115 leasetime               string  12h                     DHCPv4 address leasetime
 116 start                   integer 100                     DHCPv4 pool start
 117 limit                   integer 150                     DHCPv4 pool size
 118 preferred_lifetime      string  12h                     Value for the preferred lifetime
 119                                                         for a prefix
 120 ra_default              integer 0                       Override default route
 121                         0: default, 1: ignore no public address, 2: ignore all
 122 ra_flags                list    other-config            List of RA flags to be
 123                                                         advertised in RA messages
 124                         [managed-config other-config home-agent none]
 125 ra_slaac                bool    1                       Announce slaac for a prefix
 126 ra_offlink              bool    0                       Announce prefixes off-link
 127 ra_preference           string  medium                  Route(r) preference
 128                         [medium|high|low]
 129 ra_maxinterval          integer 600                     Maximum time allowed between
 130                                                         sending unsolicited RA
 131 ra_mininterval          integer 200                     Minimum time allowed between
 132                                                         sending unsolicited RA
 133 ra_lifetime             integer 1800                    Value to be placed in Router
 134                                                         Lifetime field of RA
 135 ra_useleasetime         bool    0                       Use configured leasetime as
 136                                                         limit for the preferred and
 137                                                         valid lifetime of a prefix
 138 ra_reachabletime        integer 0                       Reachable Time in milliseconds to be
 139                                                         advertised in RA messages
 140 ra_retranstime          integer 0                       Retransmit Time in milliseconds to be
 141                                                         advertised in RA messages
 142 ra_hoplimit             integer 0                       Current hoplimit to be advertised
 143                                                         in RA messages
 144 ra_mtu                  integer -                       MTU to be advertised in
 145                                                         RA messages
 146 ra_dns                  bool    1                       Announce DNS configuration in
 147                                                         RA messages (RFC8106)
 148 ra_pref64               string                          Announce PREF64 option
 149                         [IPv6 prefix]                   for NAT64 prefix (RFC8781)
 150 ndproxy_routing         bool    1                       Learn routes from NDP
 151 ndproxy_slave           bool    0                       NDProxy external slave
 152 prefix_filter           string  ::/0                    Only advertise on-link prefixes within
 153                         [IPv6 prefix]                   the provided IPv6 prefix; others are
 154                                                         filtered out.
 155 ntp                     list    <local address>         NTP servers to announce
 156                                                         accepts IPv4 and IPv6
 157
 158
 159 Sections of type host (static leases)
 160 Option          Type    Default                 Description
 161 ip              string                          IP-Address to lease
 162 mac             string                          MAC-address
 163 duid            string                          DUID in base16
 164 hostid          string                          IPv6 host identifier
 165 name            string                          Hostname
 166 leasetime       string                          DHCPv4/v6 leasetime
 167