aboutsummaryrefslogtreecommitdiff
path: root/networking/udhcp/README
diff options
context:
space:
mode:
Diffstat (limited to 'networking/udhcp/README')
-rw-r--r--networking/udhcp/README197
1 files changed, 197 insertions, 0 deletions
diff --git a/networking/udhcp/README b/networking/udhcp/README
new file mode 100644
index 000000000..d3e5e3fbc
--- /dev/null
+++ b/networking/udhcp/README
@@ -0,0 +1,197 @@
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
8udhcp server (udhcpd)
9--------------------
10
11The only command line argument to udhcpd is an optional specifed
12config file. If no config file is specified, udhcpd uses the default
13config file, /etc/udhcpd.conf. Ex:
14
15udhcpd /etc/udhcpd.eth1.conf
16
17The udhcp server employs a number of simple config files:
18
19udhcpd.leases
20------------
21
22The udhcpd.leases behavior is designed for an embedded system. The
23file is written either every auto_time seconds, or when a SIGUSR1
24is received (the auto_time timer restarts if a SIGUSR1 is received).
25If you send a SIGTERM to udhcpd directly after a SIGUSR1, udhcpd will
26finish writing the leases file and wait for the aftermentioned script
27to be executed and finish before quiting, so you do not need to sleep
28between sending signals. When the file is written, a script can be
29optionally called to commit the file to flash. Lease times are stored
30in the file by time remaining in lease (for systems without clock
31that works when there is no power), or by the absolute time that it
32expires in seconds from epoch. In the remainig format, expired leases
33are stored as zero. The file is of the format:
34
3516 byte MAC
364 byte ip address
37u32 expire time
3816 byte MAC
394 byte ip address
40u32 expire time
41.
42etc.
43
44example: hexdump udhcpd.leases
45
460000000 1000 c95a 27d9 0000 0000 0000 0000 0000
470000010 a8c0 150a 0d00 2d29 5000 23fc 8566 0000
480000020 0000 0000 0000 0000 a8c0 140a 0d00 4e29
490000030
50
51
52udhcpd.conf
53----------
54
55The format is fairly simple, there is a sample file with all the
56available options and comments describing them in samples/udhcpd.conf
57
58
59udhcp client (udhcpc)
60--------------------
61
62The udhcp client negotiates a lease with the DHCP server and notifies
63a set of scripts when a leases is obtained or lost. The command line
64options for the udhcp client are:
65
66-c, --clientid=CLIENTID Client identifier
67-H, --hostname=HOSTNAME Client hostname
68-h, Alias for -H
69-f, --foreground Do not fork after getting lease
70-b, --background Fork to background if lease cannot be
71 immediately negotiated.
72-i, --interface=INTERFACE Interface to use (default: eth0)
73-n, --now Exit with failure if lease cannot be
74 immediately negotiated.
75-p, --pidfile=file Store process ID of daemon in file
76-q, --quit Quit after obtaining lease
77-r, --request=IP IP address to request (default: none)
78-s, --script=file Run file at dhcp events (default:
79 /usr/share/udhcpc/default.script)
80-v, --version Display version
81
82If the requested IP address cannot be obtained, the client accepts the
83address that the server offers.
84
85When an event occurs, udhcpc calls the action script. The script by
86default is /usr/share/udhcpc/default.script but this can be changed via
87the command line arguments. The three possible arguments to the script
88are:
89
90 deconfig: This argument is used when udhcpc starts, and
91 when a leases is lost. The script should put the interface in an
92 up, but deconfigured state, ie: ifconfig $interface 0.0.0.0.
93
94 bound: This argument is used when udhcpc moves from an
95 unbound, to a bound state. All of the paramaters are set in
96 enviromental variables, The script should configure the interface,
97 and set any other relavent parameters (default gateway, dns server,
98 etc).
99
100 renew: This argument is used when a DHCP lease is renewed. All of
101 the paramaters are set in enviromental variables. This argument is
102 used when the interface is already configured, so the IP address,
103 will not change, however, the other DHCP paramaters, such as the
104 default gateway, subnet mask, and dns server may change.
105
106 nak: This argument is used with udhcpc receives a NAK message.
107 The script with the deconfig argument will be called directly
108 afterwards, so no changes to the network interface are neccessary.
109 This hook is provided for purely informational purposes (the
110 message option may contain a reason for the NAK).
111
112The paramaters for enviromental variables are as follows:
113
114 $HOME - The set $HOME env or "/"
115 $PATH - the set $PATH env or "/bin:/usr/bin:/sbin:/usr/sbin"
116 $1 - What action the script should perform
117 interface - The interface this was obtained on
118 ip - The obtained IP
119 siaddr - The bootp next server option
120 sname - The bootp server name option
121 boot_file - The bootp boot file option
122 subnet - The assigend subnet mask
123 timezone - Offset in seconds from UTC
124 router - A list of routers
125 timesvr - A list of time servers
126 namesvr - A list of IEN 116 name servers
127 dns - A list of DNS server
128 logsvr - A list of MIT-LCS UDP log servers
129 cookiesvr - A list of RFC 865 cookie servers
130 lprsvr - A list of LPR servers
131 hostname - The assigned hostname
132 bootsize - The length in 512 octect blocks of the bootfile
133 domain - The domain name of the network
134 swapsvr - The IP address of the client's swap server
135 rootpath - The path name of the client's root disk
136 ipttl - The TTL to use for this network
137 mtu - The MTU to use for this network
138 broadcast - The broadcast address for this network
139 ntpsrv - A list of NTP servers
140 wins - A list of WINS servers
141 lease - The lease time, in seconds
142 dhcptype - DHCP message type (safely ignored)
143 serverid - The IP of the server
144 message - Reason for a DHCPNAK
145 tftp - The TFTP server name
146 bootfile - The bootfile name
147
148additional options are easily added in options.c.
149
150udhcpc also responds to SIGUSR1 and SIGUSR2. SIGUSR1 will force a renew state,
151and SIGUSR2 will force a release of the current lease, and cause udhcpc to
152go into an inactive state (until it is killed, or receives a SIGUSR1). You do
153not need to sleep between sending signals, as signals received are processed
154sequencially in the order they are received.
155
156
157
158compile time options
159-------------------
160
161The Makefile contains three of the compile time options:
162
163 DEBUG: If DEBUG is defined, udhcpd will output extra debugging
164 output, compile with -g, and not fork to the background when run.
165 SYSLOG: If SYSLOG is defined, udhcpd will log all its messages
166 syslog, otherwise, it will attempt to log them to stdout.
167
168 COMBINED_BINARY: If COMBINED_BINARY is define, one binary, udhcpd,
169 is created. If called as udhcpd, the dhcp server will be started.
170 If called as udhcpc, the dhcp client will be started.
171
172dhcpd.h contains the other two compile time options:
173
174 LEASE_TIME: The default lease time if not specified in the config
175 file.
176
177 DHCPD_CONFIG_FILE: The defualt config file to use.
178
179options.c contains a set of dhcp options for the client:
180
181 name[10]: The name of the option as it will appear in scripts
182
183 flags: The type of option, as well as if it will be requested
184 by the client (OPTION_REQ)
185
186 code: The DHCP code for this option
187
188busybox drop-in
189--------------
190udhcp is now a drop-in component for busybox (http://busybox.net).
191To update busybox to the latest revision, simply do a:
192
193cp *.[ch] README AUTHORS COPYING ChangeLog TODO \
194 <busybox_source>/networking/udhcp
195
196The only two files udhcp does not provide are config.in and
197Makefile.in, so these may need to be updated from time to time.