blob: d720a37cfdf8ef852062837a2d57a486db5647b7 [file] [log] [blame]
Russ Dillf5ecd432002-10-31 19:21:27 +00001udhcp client (udhcpc)
2--------------------
3
4The udhcp client negotiates a lease with the DHCP server and notifies
5a set of scripts when a leases is obtained or lost.
6
7
8command line options
9-------------------
10
11The command line options for the udhcp client are:
12
13-c, --clientid=CLIENTID Client identifier
14-H, --hostname=HOSTNAME Client hostname
15-h, Alias for -H
16-f, --foreground Do not fork after getting lease
17-b, --background Fork to background if lease cannot be
18 immediately negotiated.
19-i, --interface=INTERFACE Interface to use (default: eth0)
20-n, --now Exit with failure if lease cannot be
21 immediately negotiated.
22-p, --pidfile=file Store process ID of daemon in file
23-q, --quit Quit after obtaining lease
24-r, --request=IP IP address to request (default: none)
25-s, --script=file Run file at dhcp events (default:
26 /usr/share/udhcpc/default.script)
27-v, --version Display version
28
29
30If the requested IP address cannot be obtained, the client accepts the
31address that the server offers.
32
33
34udhcp client scripts
35-------------------
36
Russ Dillae01fa92002-11-19 00:41:09 +000037When an event occurs, udhcpc calls the action script. udhcpc never does
38any configuration of the network interface itself, but instead relies on
Eric Andersenc7bda1c2004-03-15 08:29:22 +000039a set of scripts. The script by default is
Russ Dillae01fa92002-11-19 00:41:09 +000040/usr/share/udhcpc/default.script but this can be changed via the command
41line arguments. The three possible arguments to the script are:
Russ Dillf5ecd432002-10-31 19:21:27 +000042
43 deconfig: This argument is used when udhcpc starts, and
Russ Dillae01fa92002-11-19 00:41:09 +000044 when a leases is lost. The script must put the interface in an
Russ Dillf5ecd432002-10-31 19:21:27 +000045 up, but deconfigured state, ie: ifconfig $interface 0.0.0.0.
Eric Andersenc7bda1c2004-03-15 08:29:22 +000046
Russ Dillf5ecd432002-10-31 19:21:27 +000047 bound: This argument is used when udhcpc moves from an
48 unbound, to a bound state. All of the paramaters are set in
49 enviromental variables, The script should configure the interface,
Eric Andersenc7bda1c2004-03-15 08:29:22 +000050 and set any other relavent parameters (default gateway, dns server,
Russ Dillf5ecd432002-10-31 19:21:27 +000051 etc).
Eric Andersenc7bda1c2004-03-15 08:29:22 +000052
Russ Dillf5ecd432002-10-31 19:21:27 +000053 renew: This argument is used when a DHCP lease is renewed. All of
54 the paramaters are set in enviromental variables. This argument is
55 used when the interface is already configured, so the IP address,
56 will not change, however, the other DHCP paramaters, such as the
57 default gateway, subnet mask, and dns server may change.
58
59 nak: This argument is used with udhcpc receives a NAK message.
60 The script with the deconfig argument will be called directly
61 afterwards, so no changes to the network interface are neccessary.
62 This hook is provided for purely informational purposes (the
63 message option may contain a reason for the NAK).
64
65The paramaters for enviromental variables are as follows:
66
67 $HOME - The set $HOME env or "/"
68 $PATH - the set $PATH env or "/bin:/usr/bin:/sbin:/usr/sbin"
69 $1 - What action the script should perform
70 interface - The interface this was obtained on
71 ip - The obtained IP
Russ Dill1eb7a172002-12-11 21:12:45 +000072 mask - The number of bits in the netmask (ie: 24)
Russ Dillf5ecd432002-10-31 19:21:27 +000073 siaddr - The bootp next server option
74 sname - The bootp server name option
75 boot_file - The bootp boot file option
76 subnet - The assigend subnet mask
77 timezone - Offset in seconds from UTC
78 router - A list of routers
79 timesvr - A list of time servers
80 namesvr - A list of IEN 116 name servers
81 dns - A list of DNS server
82 logsvr - A list of MIT-LCS UDP log servers
83 cookiesvr - A list of RFC 865 cookie servers
84 lprsvr - A list of LPR servers
85 hostname - The assigned hostname
86 bootsize - The length in 512 octect blocks of the bootfile
87 domain - The domain name of the network
88 swapsvr - The IP address of the client's swap server
89 rootpath - The path name of the client's root disk
90 ipttl - The TTL to use for this network
91 mtu - The MTU to use for this network
92 broadcast - The broadcast address for this network
93 ntpsrv - A list of NTP servers
94 wins - A list of WINS servers
95 lease - The lease time, in seconds
96 dhcptype - DHCP message type (safely ignored)
97 serverid - The IP of the server
98 message - Reason for a DHCPNAK
99 tftp - The TFTP server name
100 bootfile - The bootfile name
101
102additional options are easily added in options.c.
103
104
105note on udhcpc's random seed
106---------------------------
107
108udhcpc will seed its random number generator (used for generating xid's)
109by reading /dev/urandom. If you have a lot of embedded systems on the same
110network, with no entropy, you can either seed /dev/urandom by a method of
111your own, or doing the following on startup:
112
113ifconfig eth0 > /dev/urandom
114
115in order to seed /dev/urandom with some data (mac address) unique to your
116system. If reading /dev/urandom fails, udhcpc will fall back to its old
117behavior of seeding with time(0).
118
119
120signals accepted by udhcpc
121-------------------------
122
123udhcpc also responds to SIGUSR1 and SIGUSR2. SIGUSR1 will force a renew state,
124and SIGUSR2 will force a release of the current lease, and cause udhcpc to
125go into an inactive state (until it is killed, or receives a SIGUSR1). You do
126not need to sleep between sending signals, as signals received are processed
127sequencially in the order they are received.
128
129
130compile time options
131-------------------
132
133options.c contains a set of dhcp options for the client:
134
135 name[10]: The name of the option as it will appear in scripts
Eric Andersenc7bda1c2004-03-15 08:29:22 +0000136
Russ Dillf5ecd432002-10-31 19:21:27 +0000137 flags: The type of option, as well as if it will be requested
138 by the client (OPTION_REQ)
139
140 code: The DHCP code for this option
141