minix/commands/dhcpd/dhcpd.8

   1 .TH DHCPD 8
   2 .SH NAME
   3 dhcpd \- dynamic host configuration protocol daemon
   4 .SH SYNOPSIS
   5 .in +.5i
   6 .ti -.5i
   7 .B dhdpd
   8 .RB [ \-qar ]
   9 .RB [ \-t [\fIlevel\fP]]
  10 .RB [ \-d [\fIlevel\fP]]
  11 .RB [ \-f
  12 .IR configfile ]
  13 .RB [ \-c
  14 .IR cachefile ]
  15 .RB [ \-p
  16 .IR poolfile ]
  17 .RI [ host " ...]"
  18 .in -.5i
  19 .SH DESCRIPTION
  20 .de SP
  21 .if t .sp 0.4
  22 .if n .sp
  23 ..
  24 .B Dhcpd
  25 is a client and a server for the Dynamic Host Configuration Protocol.  As a
  26 client it collects DHCP data to configure the Ethernet networks with, and as
  27 a server it answers DHCP queries from other machines.
  28 .PP
  29 This manual page describes the operation of
  30 .BR dhcpd ,
  31 the associated configuration file is described in
  32 .BR dhcp.conf (5).
  33 (The latter, together with
  34 .BR boot (8),
  35 is of more practical value when it comes to getting a machine's networks
  36 interfaces up and running.  See the options section below for debugging DCHP
  37 problems.)
  38 .SS Initialization
  39 On a normal startup, i.e. none of the
  40 .BR \-q ,
  41 .BR \-a
  42 or
  43 .BR \-r
  44 options are given,
  45 .B dhcpd
  46 determines what IP devices are present, and which of those are Ethernets.
  47 For each network it looks for information in the configuration file as if
  48 it were a server answering a query for that network.  If any information is
  49 found then the IP address is configured and the information stored in the
  50 cache file.
  51 .SS "Client Operation"
  52 For each still unconfigured network a DHCP DISCOVER request is broadcast on
  53 that network.  If a DHCP OFFER reply is received then a DHCP REQUEST is
  54 broadcast for the IP address offered, and if a DHCP ACK is received then the
  55 network is configured and the information stored in the cache file.
  56 .PP
  57 If no reply is received then another query is sent after 4 seconds, and then
  58 again after 8 seconds, doubling each time until 64 seconds.  Every 64
  59 seconds thereafter a request is broadcast until a reply is received.
  60 .PP
  61 Once configured the DHCP lease, rebind and renew times are computed.  At the
  62 renew time a DHCP REQUEST is sent to the DHCP server to extend the lease.
  63 Normally we get an answer and refresh our information, but if no reply is
  64 received we wait for half the remaining time until the rebind time and keep
  65 retrying and halving the remaining time.  When the rebind time is reached
  66 the DHCP REQUEST is broadcast to try and reach some other DHCP server.
  67 Halving the remaining time again and again until the lease expires.  At that
  68 point we go back to square one and broadcast a DHCP DISCOVER.
  69 .PP
  70 If at any point a DHCP NAK is received we start over completely.  After a
  71 DHCP OFFER an ARP request is transmitted just before the DHCP REQUEST to
  72 check if the address offered is already in use.  If an ARP reply is received
  73 before the DHCP ACK then after the ACK we send a DHCP DECLINE to the server
  74 to tell that the address isn't what we want and again we start over.
  75 .SS "Router Discovery"
  76 The gateway offered by the DHCP server is made known to the TCP/IP server by
  77 sending an ICMP router advertisement to the local interface with a short
  78 lifetime and a low priority.  Then up to three router solicitations are
  79 broadcast three seconds apart to look for a router.  If a router answers
  80 with a router advertisement then we no longer worry about routing for that
  81 interface.  Otherwise the router information is refreshed before it expires
  82 and another solicitation is sent out.  This happens about twice an hour.
  83 .SS "Server Operation"
  84 Once all networks so marked are configured the daemon starts answering
  85 requests by other machines or relaying requests to other DHCP servers.
  86 DHCP requests are answered if information for a client
  87 can be found in the configuration file, or if a free address can be found in
  88 the pool file, or if a client rerequests an address it already owns.
  89 .PP
  90 If the daemon is both a server and a relay for a network then it will try
  91 to answer a request and only relay if it has no answer.
  92 .SS "Nothing more to do?"
  93 If the daemon finds out that all networks have an infinite lease (configured
  94 with a fixed address), there is no router information to keep warm, and
  95 it isn't a server then it simply exits.
  96 .SS "Asynchronous I/O?"
  97 MINIX 3 doesn't have the asynchronous I/O that Minix-vmd has, so under MINIX 3
  98 the daemon only works with one network at a time.  If it's stuck on the same
  99 network for 32 seconds then that network is closed and another network is
 100 tried for 32 seconds.  This usually works ok as a client, but as a server it
 101 can only handle one network.
 102 .SH OPTIONS
 103 .TP
 104 .B \-q
 105 Read and print the cache and pool file contents, showing DHCP information
 106 for each network, and the IP addresses in the pool with lease times and
 107 current/last owners of those addresses.
 108 .TP
 109 .B \-a
 110 Add the named hosts (or IP addresses) to the pool file.
 111 .TP
 112 .B \-r
 113 Remove hosts from the pool file.
 114 .TP
 115 .RB [ \-t [\fIlevel\fP]]
 116 Set the test level (by default 1).  At test level 1 all networks are seen as
 117 unconfigured, will not be configured and no data will be put in the cache.
 118 The program will just act as-if.  At test level 2 the interfaces will not be
 119 configured from the configuration file, the data must come from a remote
 120 server.  At level 3 the renewal, rebind and lease time will be 60, 120
 121 and 180 seconds.  At level 4 these times will be 60, 60, and 120.  At
 122 level 5 these times will be 60, 60, and 60.  These test levels are meant
 123 to debug the DHCP client code, and are best used with a high debug level.
 124 .TP
 125 .RB [ \-d [\fIlevel\fP]]
 126 Set the debug level (by default 1).  At debug level 1 the program shows
 127 Ethernet and IP addresses as they are determined or configured, DHCP
 128 messages sent and received with little detail (one line per message), and
 129 memory use.  At debug level 2 each DHCP packet is decoded and shown in
 130 detail.  At debug level 3 device opens and closes are shown.  The debugging
 131 level may also be increased by 1 at runtime by sending signal
 132 .BR SIGUSR1
 133 or turned off (set to 0) with
 134 .BR SIGUSR2 .
 135 .TP
 136 .BI \-f " configfile"
 137 Names the configuration file, by default
 138 .BR /etc/dhcp.conf .
 139 .TP
 140 .BI \-c " cachefile"
 141 Names the cache file, by default
 142 .BR /usr/adm/dhcp.cache .
 143 .TP
 144 .BI \-p " poolfile"
 145 Names the IP address pool, by default
 146 .BR /usr/adm/dhcp.pool .
 147 .SH "SEE ALSO"
 148 .BR RFC-2131 ,
 149 .BR RFC-1533 ,
 150 .BR dhcp.conf (5),
 151 .BR hosts (5),
 152 .BR ifconfig (8),
 153 .BR inet (8),
 154 .BR boot (8),
 155 .BR inetd (8),
 156 .BR nonamed (8).
 157 .SH DIAGNOSTICS
 158 .TP
 159 "'/etc/dhcp.conf', line ..."
 160 The program exits on any configuration file error.  You have to correct the
 161 error and restart the program.
 162 .TP
 163 "No lease set for address ..."
 164 There must be a lease time defined for addresses in the pool.  Correct and
 165 restart the program.
 166 .TP
 167 "###### declines #.#.#.# saying '...'"
 168 A client with the given client identifier (usually 01 followed by the client's
 169 Ethernet address) declines an IP address, hopefully with a message telling
 170 why.  This usually means that the IP address is already in use by another
 171 host.  This program, acting as a client, will tell what other host in its
 172 message, but Windows has no additional info alas.
 173 .TP
 174 "Got a NAK from #.#.#.# [through #.#.#.#] saying '...'"
 175 The server with the given IP address doesn't want us to have or keep the IP
 176 address we were offered or are rerequesting.  This could mean that the server
 177 has forgotten about us and has given our address to another machine.  This
 178 is bad if our lease hasn't yet expired.  There may be a relay involved, and
 179 there may even be a text message with precise information.
 180 .TP
 181 "#.#.#.# offered by #.#.#.# is already in use by #:#:#:#:#:#"
 182 We got an ARP reply for an offered address.  We won't accept it, and send
 183 out a DECLINE when we get an ACK.
 184 .TP
 185 "DHCP packet too big, ..."
 186 You've got way to much information in the configuration file, more than fits
 187 in a minimum size DHCP packet.  (Notify the author if you really need to send
 188 more information.  He doesn't think anyone needs to.)
 189 .TP
 190 "Pool table is corrupt"
 191 You will have to remove and refill the pool file.  Chaos may ensue if
 192 there are active clients and they don't use ARP to detect each other.
 193 (Most do.)
 194 .SH BUGS
 195 There is no randomization of timers.  Modern systems don't blink under the
 196 load of several clients broadcasting a few packets in sync.
 197 .PP
 198 There is no extra time spent waiting for an ARP reply.  It is assumed that
 199 any IP stack will immediately respond, so that the DHCP server can't
 200 possibly beat it at sending out an ACK.  (The DHCP server has to commit the
 201 lease to stable storage first anyway.)
 202 .PP
 203 Way more nonsense can be sent in a DHCP packet that MINIX 3 could do
 204 something with, but nobody does so we don't bother.
 205 .PP
 206 DHCP was invented by a rabid gerbil on speed.
 207 .SH AUTHOR
 208 Kees J. Bot <kjb@cs.vu.nl>