diff options
Diffstat (limited to 'networking/udhcp/README')
-rw-r--r-- | networking/udhcp/README | 197 |
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 @@ | |||
1 | udhcp server/client package readme | ||
2 | ------------------------- | ||
3 | |||
4 | The udhcp server/client package is primarily geared towards embedded | ||
5 | systems. It does however, strive to be fully functional, and RFC | ||
6 | compliant. | ||
7 | |||
8 | udhcp server (udhcpd) | ||
9 | -------------------- | ||
10 | |||
11 | The only command line argument to udhcpd is an optional specifed | ||
12 | config file. If no config file is specified, udhcpd uses the default | ||
13 | config file, /etc/udhcpd.conf. Ex: | ||
14 | |||
15 | udhcpd /etc/udhcpd.eth1.conf | ||
16 | |||
17 | The udhcp server employs a number of simple config files: | ||
18 | |||
19 | udhcpd.leases | ||
20 | ------------ | ||
21 | |||
22 | The udhcpd.leases behavior is designed for an embedded system. The | ||
23 | file is written either every auto_time seconds, or when a SIGUSR1 | ||
24 | is received (the auto_time timer restarts if a SIGUSR1 is received). | ||
25 | If you send a SIGTERM to udhcpd directly after a SIGUSR1, udhcpd will | ||
26 | finish writing the leases file and wait for the aftermentioned script | ||
27 | to be executed and finish before quiting, so you do not need to sleep | ||
28 | between sending signals. When the file is written, a script can be | ||
29 | optionally called to commit the file to flash. Lease times are stored | ||
30 | in the file by time remaining in lease (for systems without clock | ||
31 | that works when there is no power), or by the absolute time that it | ||
32 | expires in seconds from epoch. In the remainig format, expired leases | ||
33 | are stored as zero. The file is of the format: | ||
34 | |||
35 | 16 byte MAC | ||
36 | 4 byte ip address | ||
37 | u32 expire time | ||
38 | 16 byte MAC | ||
39 | 4 byte ip address | ||
40 | u32 expire time | ||
41 | . | ||
42 | etc. | ||
43 | |||
44 | example: hexdump udhcpd.leases | ||
45 | |||
46 | 0000000 1000 c95a 27d9 0000 0000 0000 0000 0000 | ||
47 | 0000010 a8c0 150a 0d00 2d29 5000 23fc 8566 0000 | ||
48 | 0000020 0000 0000 0000 0000 a8c0 140a 0d00 4e29 | ||
49 | 0000030 | ||
50 | |||
51 | |||
52 | udhcpd.conf | ||
53 | ---------- | ||
54 | |||
55 | The format is fairly simple, there is a sample file with all the | ||
56 | available options and comments describing them in samples/udhcpd.conf | ||
57 | |||
58 | |||
59 | udhcp client (udhcpc) | ||
60 | -------------------- | ||
61 | |||
62 | The udhcp client negotiates a lease with the DHCP server and notifies | ||
63 | a set of scripts when a leases is obtained or lost. The command line | ||
64 | options 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 | |||
82 | If the requested IP address cannot be obtained, the client accepts the | ||
83 | address that the server offers. | ||
84 | |||
85 | When an event occurs, udhcpc calls the action script. The script by | ||
86 | default is /usr/share/udhcpc/default.script but this can be changed via | ||
87 | the command line arguments. The three possible arguments to the script | ||
88 | are: | ||
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 | |||
112 | The 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 | |||
148 | additional options are easily added in options.c. | ||
149 | |||
150 | udhcpc also responds to SIGUSR1 and SIGUSR2. SIGUSR1 will force a renew state, | ||
151 | and SIGUSR2 will force a release of the current lease, and cause udhcpc to | ||
152 | go into an inactive state (until it is killed, or receives a SIGUSR1). You do | ||
153 | not need to sleep between sending signals, as signals received are processed | ||
154 | sequencially in the order they are received. | ||
155 | |||
156 | |||
157 | |||
158 | compile time options | ||
159 | ------------------- | ||
160 | |||
161 | The 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 | |||
172 | dhcpd.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 | |||
179 | options.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 | |||
188 | busybox drop-in | ||
189 | -------------- | ||
190 | udhcp is now a drop-in component for busybox (http://busybox.net). | ||
191 | To update busybox to the latest revision, simply do a: | ||
192 | |||
193 | cp *.[ch] README AUTHORS COPYING ChangeLog TODO \ | ||
194 | <busybox_source>/networking/udhcp | ||
195 | |||
196 | The only two files udhcp does not provide are config.in and | ||
197 | Makefile.in, so these may need to be updated from time to time. | ||