README
1udhcp server/client package readme
2-------------------------
3
4The udhcp server/client package is primarily geared towards embedded
5systems. It does however, strive to be fully functional, and RFC
6compliant.
7
8
9compile time options
10-------------------
11
12The Makefile contains three of the compile time options:
13
14 DEBUG: If DEBUG is defined, udhcpd will output extra debugging
15 output, compile with -g, and not fork to the background when run.
16 SYSLOG: If SYSLOG is defined, udhcpd will log all its messages
17 syslog, otherwise, it will attempt to log them to stdout.
18
19 COMBINED_BINARY: If COMBINED_BINARY is define, one binary, udhcpd,
20 is created. If called as udhcpd, the dhcp server will be started.
21 If called as udhcpc, the dhcp client will be started.
22
23dhcpd.h contains the other two compile time options:
24
25 LEASE_TIME: The default lease time if not specified in the config
26 file.
27
28 DHCPD_CONFIG_FILE: The defualt config file to use.
29
30options.c contains a set of dhcp options for the client:
31
32 name[10]: The name of the option as it will appear in scripts
33
34 flags: The type of option, as well as if it will be requested
35 by the client (OPTION_REQ)
36
37 code: The DHCP code for this option
38
39
40busybox drop-in
41--------------
42udhcp is now a drop-in component for busybox (http://busybox.net).
43To update busybox to the latest revision, simply do a:
44
45cp *.[ch] README AUTHORS COPYING ChangeLog TODO \
46 <busybox_source>/networking/udhcp
47
48The only two files udhcp does not provide are config.in and
49Makefile.in, so these may need to be updated from time to time.
50
51
README.dumpleases
1udhcp lease dump (dumpleases)
2----------------------------
3
4dumpleases displays the leases written out by the udhcpd server. Lease
5times are stored in the file by time remaining in lease (for systems
6without clock that works when there is no power), or by the absolute
7time that it expires in seconds from epoch. dumpleases accepts the
8following command line options:
9
10-a, --absolute Interpret lease times as expiration time.
11-r, --remaining Interpret lease times as remaining time.
12-f, --file=FILE Read lease information from FILE.
13-h, --help Display help.
14
15Note that if udhcpd has not written a leases file recently, the output
16of may not be up to date.
17
18
README.udhcpc
1udhcp 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
37When an event occurs, udhcpc calls the action script. The script by
38default is /usr/share/udhcpc/default.script but this can be changed via
39the command line arguments. The three possible arguments to the script
40are:
41
42 deconfig: This argument is used when udhcpc starts, and
43 when a leases is lost. The script should put the interface in an
44 up, but deconfigured state, ie: ifconfig $interface 0.0.0.0.
45
46 bound: This argument is used when udhcpc moves from an
47 unbound, to a bound state. All of the paramaters are set in
48 enviromental variables, The script should configure the interface,
49 and set any other relavent parameters (default gateway, dns server,
50 etc).
51
52 renew: This argument is used when a DHCP lease is renewed. All of
53 the paramaters are set in enviromental variables. This argument is
54 used when the interface is already configured, so the IP address,
55 will not change, however, the other DHCP paramaters, such as the
56 default gateway, subnet mask, and dns server may change.
57
58 nak: This argument is used with udhcpc receives a NAK message.
59 The script with the deconfig argument will be called directly
60 afterwards, so no changes to the network interface are neccessary.
61 This hook is provided for purely informational purposes (the
62 message option may contain a reason for the NAK).
63
64The paramaters for enviromental variables are as follows:
65
66 $HOME - The set $HOME env or "/"
67 $PATH - the set $PATH env or "/bin:/usr/bin:/sbin:/usr/sbin"
68 $1 - What action the script should perform
69 interface - The interface this was obtained on
70 ip - The obtained IP
71 siaddr - The bootp next server option
72 sname - The bootp server name option
73 boot_file - The bootp boot file option
74 subnet - The assigend subnet mask
75 timezone - Offset in seconds from UTC
76 router - A list of routers
77 timesvr - A list of time servers
78 namesvr - A list of IEN 116 name servers
79 dns - A list of DNS server
80 logsvr - A list of MIT-LCS UDP log servers
81 cookiesvr - A list of RFC 865 cookie servers
82 lprsvr - A list of LPR servers
83 hostname - The assigned hostname
84 bootsize - The length in 512 octect blocks of the bootfile
85 domain - The domain name of the network
86 swapsvr - The IP address of the client's swap server
87 rootpath - The path name of the client's root disk
88 ipttl - The TTL to use for this network
89 mtu - The MTU to use for this network
90 broadcast - The broadcast address for this network
91 ntpsrv - A list of NTP servers
92 wins - A list of WINS servers
93 lease - The lease time, in seconds
94 dhcptype - DHCP message type (safely ignored)
95 serverid - The IP of the server
96 message - Reason for a DHCPNAK
97 tftp - The TFTP server name
98 bootfile - The bootfile name
99
100additional options are easily added in options.c.
101
102
103note on udhcpc's random seed
104---------------------------
105
106udhcpc will seed its random number generator (used for generating xid's)
107by reading /dev/urandom. If you have a lot of embedded systems on the same
108network, with no entropy, you can either seed /dev/urandom by a method of
109your own, or doing the following on startup:
110
111ifconfig eth0 > /dev/urandom
112
113in order to seed /dev/urandom with some data (mac address) unique to your
114system. If reading /dev/urandom fails, udhcpc will fall back to its old
115behavior of seeding with time(0).
116
117
118signals accepted by udhcpc
119-------------------------
120
121udhcpc also responds to SIGUSR1 and SIGUSR2. SIGUSR1 will force a renew state,
122and SIGUSR2 will force a release of the current lease, and cause udhcpc to
123go into an inactive state (until it is killed, or receives a SIGUSR1). You do
124not need to sleep between sending signals, as signals received are processed
125sequencially in the order they are received.
126
127
128compile time options
129-------------------
130
131options.c contains a set of dhcp options for the client:
132
133 name[10]: The name of the option as it will appear in scripts
134
135 flags: The type of option, as well as if it will be requested
136 by the client (OPTION_REQ)
137
138 code: The DHCP code for this option
139
140
README.udhcpd
1udhcp server (udhcpd)
2--------------------
3
4The only command line argument to udhcpd is an optional specifed
5config file. If no config file is specified, udhcpd uses the default
6config file, /etc/udhcpd.conf. Ex:
7
8udhcpd /etc/udhcpd.eth1.conf
9
10The udhcp server employs a number of simple config files:
11
12udhcpd.leases
13------------
14
15The udhcpd.leases behavior is designed for an embedded system. The
16file is written either every auto_time seconds, or when a SIGUSR1
17is received (the auto_time timer restarts if a SIGUSR1 is received).
18If you send a SIGTERM to udhcpd directly after a SIGUSR1, udhcpd will
19finish writing the leases file and wait for the aftermentioned script
20to be executed and finish before quiting, so you do not need to sleep
21between sending signals. When the file is written, a script can be
22optionally called to commit the file to flash. Lease times are stored
23in the file by time remaining in lease (for systems without clock
24that works when there is no power), or by the absolute time that it
25expires in seconds from epoch. In the remaining format, expired leases
26are stored as zero. The file is of the format:
27
2816 byte MAC
294 byte ip address
30u32 expire time
3116 byte MAC
324 byte ip address
33u32 expire time
34.
35etc.
36
37example: hexdump udhcpd.leases
38
390000000 1000 c95a 27d9 0000 0000 0000 0000 0000
400000010 a8c0 150a 0d00 2d29 5000 23fc 8566 0000
410000020 0000 0000 0000 0000 a8c0 140a 0d00 4e29
420000030
43
44
45udhcpd.conf
46----------
47
48The format is fairly simple, there is a sample file with all the
49available options and comments describing them in samples/udhcpd.conf
50
51compile time options
52-------------------
53
54dhcpd.h contains the other two compile time options:
55
56 LEASE_TIME: The default lease time if not specified in the config
57 file.
58
59 DHCPD_CONFIG_FILE: The defualt config file to use.
60