| blob | 1a40a4f6a186bd90a5c8c57a6e00d3774b693b63 |
1 .\" Copyright (c) 2006-2009 Roy Marples
2 .\" All rights reserved
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\"
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23 .\" SUCH DAMAGE.
24 .\"
25 .Dd October 25, 2009
26 .Dt DHCPCD 8 SMM
27 .Os
28 .Sh NAME
29 .Nm dhcpcd
30 .Nd an RFC 2131 compliant DHCP client
31 .Sh SYNOPSIS
32 .Nm
33 .Op Fl bdgknpqwABDEGKLTV
34 .Op Fl c , -script Ar script
35 .Op Fl e , -env Ar value
36 .Op Fl f , -config Ar file
37 .Op Fl h , -hostname Ar hostname
38 .Op Fl i , -vendorclassid Ar vendorclassid
39 .Op Fl l , -leasetime Ar seconds
40 .Op Fl m , -metric Ar metric
41 .Op Fl o , -option Ar option
42 .Op Fl r , -request Ar address
43 .Op Fl s , -inform Ar address Ns Op Ar /cidr
44 .Op Fl t , -timeout Ar seconds
45 .Op Fl u , -userclass Ar class
46 .Op Fl v , -vendor Ar code , Ar value
47 .Op Fl y , -reboot Ar seconds
48 .Op Fl z , -allowinterfaces Ar pattern
49 .Op Fl C , -nohook Ar hook
50 .Op Fl F , -fqdn Ar FQDN
51 .Op Fl I , -clientid Ar clientid
52 .Op Fl O , -nooption Ar option
53 .Op Fl Q , -require Ar option
54 .Op Fl S , -static Ar value
55 .Op Fl W , -whitelist Ar address Ns Op Ar /cidr
56 .Op Fl X , -blacklist Ar address Ns Op Ar /cidr
57 .Op Fl Z , -denyinterfaces Ar pattern
58 .Op interface
59 .Op ...
60 .Nm
61 .Fl k , -release
62 .Op interface
63 .Nm
64 .Fl x , -exit
65 .Op interface
66 .Sh DESCRIPTION
67 .Nm
68 is an implementation of the DHCP client specified in
69 .Li RFC 2131 .
70 .Nm
71 gets the host information
72 .Po
73 IP address, routes, etc
74 .Pc
75 from a DHCP server and configures the network
76 .Ar interface
77 of the
78 machine on which it is running.
79 .Nm
80 then runs the configuration script which writes DNS information to
81 .Xr resolvconf 8 ,
82 if available, otherwise directly to
83 .Pa /etc/resolv.conf .
84 If the hostname is currently blank, (null) or localhost, or
85 .Va force_hostname
86 is YES or TRUE or 1 then
87 .Nm
88 sets the hostname to the one supplied by the DHCP server.
89 .Nm
90 then daemonises and waits for the lease renewal time to lapse.
91 It will then attempt to renew its lease and reconfigure if the new lease
92 changes.
93 .Pp
94 .Nm
95 is also an implementation of the BOOTP client specified in
96 .Li RFC 951 .
97 .Ss Local Link configuration
98 If
99 .Nm
100 failed to obtain a lease, it probes for a valid IPv4LL address
101 .Po
102 aka ZeroConf, aka APIPA
103 .Pc .
104 Once obtained it restarts the process of looking for a DHCP server to get a
105 proper address.
106 .Pp
107 When using IPv4LL,
108 .Nm
109 nearly always succeeds and returns an exit code of 0.
110 In the rare case it fails, it normally means that there is a reverse ARP proxy
111 installed which always defeats IPv4LL probing.
112 To disable this behaviour, you can use the
113 .Fl L , -noipv4ll
114 option.
115 .Ss Multiple interfaces
116 If a list of interfaces are given on the command line, then
117 .Nm
118 only works with those interfaces, otherwise
119 .Nm
120 discovers available Ethernet interfaces.
121 If any interface reports a working carrier then
122 .Nm
123 will try and obtain a lease before forking to the background,
124 otherwise it will fork right away.
125 This behaviour can be modified with the
126 .Fl b , -background
127 and
128 .Fl w , -waitip
129 options.
130 .Pp
131 If a single interface is given then
132 .Nm
133 only works for that interface and runs as a separate instance.
134 The
135 .Fl w , -waitip
136 option is enabled in this instance to maintain compatability with older
137 versions.
138 .Pp
139 Interfaces are preferred by carrier, DHCP lease/IPv4LL and then lowest metric.
140 For systems that support route metrics, each route will be tagged with the
141 metric, otherwise
142 .Nm
143 changes the routes to use the interface with the same route and the lowest
144 metric.
145 See options below for controlling which interfaces we allow and deny through
146 the use of patterns.
147 .Ss Hooking into DHCP events
148 .Nm
149 runs
150 .Pa @SCRIPT@ ,
151 or the script specified by the
152 .Fl c , -script
153 option.
154 This script runs each script found in
155 .Pa @HOOKDIR@
156 in a lexical order.
157 The default installation supplies the scripts
158 .Pa 01-test ,
159 .Pa 10-mtu ,
160 .Pa 20-resolv.conf
161 and
162 .Pa 30-hostname .
163 You can disable each script by using the
164 .Fl C , -nohook
165 option.
166 See
167 .Xr dhcpcd-run-hooks 8
168 for details on how these scripts work.
169 .Nm
170 currently ignores the exit code of the script.
171 .Ss Fine tuning
172 You can fine-tune the behaviour of
173 .Nm
174 with the following options:
175 .Bl -tag -width indent
176 .It Fl b , -background
177 Background immediately.
178 This is useful for startup scripts which don't disable link messages for
179 carrier status.
180 .It Fl c , -script Ar script
181 Use this
182 .Ar script
183 instead of the default
184 .Pa @SCRIPT@ .
185 .It Fl d , -debug
186 Echo debug messages to the stderr and syslog.
187 .It Fl e , -env Ar value
188 Push
189 .Ar value
190 to the environment for use in
191 .Xr dhcpcd-run-hooks 8 .
192 For example, you can force the hostname hook to always set the hostname with
193 .Fl e
194 .Va force_hostname=YES .
195 .It Fl g , -reconfigure
196 .Nm
197 will re-apply IP address, routing and run
198 .Xr dhcpcd-run-hooks 8
199 for each interface.
200 This is useful so that a 3rd party such as PPP or VPN can change the routing
201 table and / or DNS, etc and then instruct
202 .Nm
203 to put things back afterwards.
204 .Nm
205 does not read a new configuration when this happens - you should rebind if you
206 need that functionality.
207 .It Fl f , -config Ar file
208 Specify a config to load instead of
209 .Pa @SYSCONFDIR@/dhcpcd.conf .
210 .Nm
211 always processes the config file before any command line options.
212 .It Fl h , -hostname Ar hostname
213 Sends
214 .Ar hostname
215 to the DHCP server so it can be registered in DNS.
216 If
217 .Ar hostname
218 is an empty string then the current system hostname is sent.
219 If
220 .Ar hostname
221 is a FQDN (ie, contains a .) then it will be encoded as such.
222 .It Fl i , -vendorclassid Ar vendorclassid
223 Override the
224 .Ar vendorclassid
225 field sent. The default is
226 dhcpcd <version>.
227 If not set then none is sent.
228 .It Fl k , -release
229 This causes an existing
230 .Nm
231 process running on the
232 .Ar interface
233 to release its lease, de-configure the
234 .Ar interface
235 and then exit.
236 .Nm
237 then waits until this process has exited.
238 .It Fl l , -leasetime Ar seconds
239 Request a specific lease time in
240 .Ar seconds .
241 By default
242 .Nm
243 does not request any lease time and leaves it in the hands of the
244 DHCP server.
245 .It Fl m , -metric Ar metric
246 Metrics are used to prefer an interface over another one, lowest wins.
247 .Nm
248 will supply a default metic of 200 +
249 .Xr if_nametoindex 3 .
250 An extra 100 will be added for wireless interfaces.
251 .It Fl o , -option Ar option
252 Request the DHCP
253 .Ar option
254 variable for use in
255 .Pa @SCRIPT@ .
256 .It Fl n , -rebind
257 Notifies an existing
258 .Nm
259 process running on the
260 .Ar interface
261 to rebind its lease.
262 .Nm
263 will not re-configure itself or use any other command line arguments.
264 .Nm
265 will timeout the rebind after 30 seconds at which point the lease will be
266 expired and
267 .Nm
268 will enter the discovery state to obtain a new lease.
269 Use the
270 .Fl t , -timeout
271 option to change this.
272 If
273 .Nm
274 is not running, then it starts up as normal.
275 This option used to be renew, but rebind is more accurate as we need to
276 broadcast the request instead of unicasting.
277 .It Fl p , -persistent
278 .Nm
279 normally de-configures the
280 .Ar interface
281 and configuration when it exits.
282 Sometimes, this isn't desirable if, for example, you have root mounted over
283 NFS.
284 You can use this option to stop this from happening.
285 .It Fl r , -request Op Ar address
286 .Nm
287 normally sends a DHCP DISCOVER to find servers to offer an address.
288 .Nm
289 then requests the address used.
290 You can use this option to skip the DISCOVER phase and just request the
291 .Ar address .
292 The downside is if you request an
293 .Ar address
294 the DHCP server does not know about or the DHCP server is not
295 authorative, it will remain silent.
296 In this situation, we go back to the init state and DISCOVER again.
297 If no
298 .Ar address
299 is given then the first address currently assigned to the
300 .Ar interface
301 is used.
302 .It Fl s , -inform Op Ar address Ns Op Ar /cidr
303 Behaves like
304 .Fl r , -request
305 as above, but sends a DHCP INFORM instead of a REQUEST.
306 This does not get a lease as such, just notifies the DHCP server of the
307 .Ar address
308 in use.
309 You should also include the optional
310 .Ar cidr
311 network number in case the address is not already configured on the interface.
312 .Nm
313 remains running and pretends it has an infinite lease.
314 .Nm
315 will not de-configure the interface when it exits.
316 If
317 .Nm
318 fails to contact a DHCP server then it returns a failure instead of falling
319 back on IPv4LL.
320 .It Fl t , -timeout Ar seconds
321 Timeout after
322 .Ar seconds ,
323 instead of the default 30.
324 A setting of 0
325 .Ar seconds
326 causes
327 .Nm
328 to wait forever to get a lease.
329 .It Fl u , -userclass Ar class
330 Tags the DHCP message with the userclass
331 .Ar class .
332 DHCP servers use this to give members of the class DHCP options other than the
333 default, without having to know things like hardware address or hostname.
334 .It Fl v , -vendor Ar code , Ns Ar value
335 Add an enscapulated vendor option.
336 .Ar code
337 should be between 1 and 254 inclusive.
338 To add a raw vendor string, omit
339 .Ar code
340 but keep the comma.
341 Examples.
342 .Pp
343 Set the vendor option 01 with an IP address.
344 .D1 dhcpcd \-v 01,192.168.0.2 eth0
345 Set the vendor option 02 with a hex code.
346 .D1 dhcpcd \-v 02,01:02:03:04:05 eth0
347 Set the vendor option 03 with an IP address as a string.
348 .D1 dhcpcd \-v 03,\e"192.168.0.2\e" eth0
349 Set un-encapulated vendor option to hello world.
350 .D1 dhcpcd \-v ,"hello world" eth0
351 .It Fl w , -waitip
352 Wait for an address to be assigned before forking to the background.
353 .It Fl x , -exit
354 This will signal an existing
355 .Nm
356 process running on the
357 .Ar interface
358 to de-configure the
359 .Ar interface
360 and exit.
361 .Nm
362 then waits until this process has exited.
363 .It Fl y , -reboot Ar seconds
364 Allow
365 .Ar reboot
366 seconds before moving to the discover phase if we have an old lease to use.
367 The default is 10 seconds.
368 A setting of 0 seconds causes
369 .Nm
370 to skip the reboot phase and go straight into discover.
371 .It Fl D , -duid
372 Generate an
373 .Li RFC 4361
374 compliant clientid.
375 This requires persistent storage and not all DHCP servers work with it so it
376 is not enabled by default.
377 .Nm
378 generates the DUID and stores it in
379 .Pa @SYSCONFDIR@/dhcpcd.duid .
380 This file should not be copied to other hosts.
381 .It Fl E , -lastlease
382 If
383 .Nm
384 cannot obtain a lease, then try to use the last lease acquired for the
385 interface.
386 If the
387 .Fl p, -persistent
388 option is not given then the lease is used if it hasn't expired.
389 .It Fl F , -fqdn Ar fqdn
390 Requests that the DHCP server updates DNS using FQDN instead of just a
391 hostname.
392 Valid values for
393 .Ar fqdn
394 are disable, none, ptr and both.
395 .Nm
396 itself never does any DNS updates.
397 .Nm
398 encodes the FQDN hostname as specified in
399 .Li RFC1035 .
400 .It Fl I , -clientid Ar clientid
401 Send the
402 .Ar clientid .
403 If the string is of the format 01:02:03 then it is encoded as hex.
404 For interfaces whose hardware address is longer than 8 bytes, or if the
405 .Ar clientid
406 is an empty string then
407 .Nm
408 sends a default
409 .Ar clientid
410 of the hardware family and the hardware address.
411 .El
412 .Ss Restricting behaviour
413 .Nm
414 will try to do as much as it can by default.
415 However, there are sometimes situations where you don't want the things to be
416 configured exactly how the the DHCP server wants.
417 Here are some options that deal with turning these bits off.
418 .Bl -tag -width indent
419 .It Fl q , -quiet
420 Quiet
421 .Nm
422 on the command line, only warnings and errors will be displayed.
423 The messages are still logged though.
424 .It Fl z , -allowinterfaces Ar pattern
425 When discovering interfaces, the interface name must match
426 .Ar pattern
427 which is a space or comma separated list of patterns passed to
428 .Xr fnmatch 3 .
429 If the same interface is matched in
430 .Fl Z , -denyinterfaces
431 then it is still denied.
432 .It Fl A , -noarp
433 Don't request or claim the address by ARP.
434 This also disables IPv4LL.
435 .It Fl B , -nobackground
436 Don't run in the background when we acquire a lease.
437 This is mainly useful for running under the control of another process, such
438 as a debugger or a network manager.
439 .It Fl C , -nohook Ar script
440 Don't run this hook script.
441 Matches full name, or prefixed with 2 numbers optionally ending with
442 .Pa .sh .
443 .Pp
444 So to stop
445 .Nm
446 from touching your DNS or MTU settings you would do:-
447 .D1 dhcpcd -C resolv.conf -C mtu eth0
448 .It Fl G , -nogateway
449 Don't set any default routes.
450 .It Fl K , -nolink
451 Don't receive link messages for carrier status.
452 You should only have to use this with buggy device drivers or running
453 .Nm
454 through a network manager.
455 .It Fl L , -noipv4ll
456 Don't use IPv4LL (aka APIPA, aka Bonjour, aka ZeroConf).
457 .It Fl O , -nooption Ar option
458 Don't request the specified option.
459 If no option given, then don't request any options other than those to
460 configure the interface and routing.
461 .It Fl Q , -require Ar option
462 Requires the
463 .Ar option
464 to be present in all DHCP messages, otherwise the message is ignored.
465 To enforce that
466 .Nm
467 only responds to DHCP servers and not BOOTP servers, you can
468 .Fl Q
469 .Ar dhcp_message_type .
470 .It Fl S, -static Ar value
471 Configures a static
472 .Ar value .
473 If you set
474 .Ic ip_address
475 then
476 .Nm
477 will not attempt to obtain a lease and just use the value for the address with
478 an infinite lease time.
479 .Pp
480 Here is an example which configures a static address, routes and dns.
481 .D1 dhcpcd -S ip_address=192.168.0.10/24 \e
482 .D1 -S routers=192.168.0.1 \e
483 .D1 -S domain_name_servers=192.168.0.1 \e
484 .D1 eth0
485 .It Fl T, -test
486 On receipt of DHCP messages just call
487 .Pa @SCRIPT@
488 with the reason of TEST which echos the DHCP variables found in the message
489 to the console.
490 The interface configuration isn't touched and neither are any configuration
491 files.
492 To test INFORM the interface needs to be configured with the desired address
493 before starting
494 .Nm .
495 .It Fl V, -variables
496 Display a list of option codes and the associated variable for use in
497 .Xr dhcpcd-run-hooks 8 .
498 Variables are prefixed with new_ and old_ unless the option number is -.
499 Variables without an option are part of the DHCP message and cannot be
500 directly requested.
501 .It Fl W, -whitelist Ar address Ns Op /cidr
502 Only accept packets from
503 .Ar address Ns Op /cidr .
504 .Fl X, -blacklist
505 is ignored if
506 .Fl W, -whitelist
507 is set.
508 .It Fl X, -blacklist Ar address Ns Op Ar /cidr
509 Ignore all packets from
510 .Ar address Ns Op Ar /cidr .
511 .It Fl Z , -denyinterfaces Ar pattern
512 When discovering interfaces, the interface name must not match
513 .Ar pattern
514 which is a space or comma separated list of patterns passed to
515 .Xr fnmatch 3 .
516 .El
517 .Sh 3RDPARTY LINK MANAGEMENT
518 Some interfaces require configuration by 3rd parties, such as PPP or VPN.
519 When an interface configuration in
520 .Nm
521 is marked as STATIC or INFORM without an address then
522 .Nm
523 will monitor the interface until an address is added or removed from it and
524 act accordingly.
525 For point to point interfaces (like PPP), a default route to its
526 destination is automatically added to the configuration.
527 If the point to point interface if configured for INFORM, then
528 .Nm
529 unicasts INFORM to the destination, otherwise it defaults to STATIC.
530 .Sh NOTES
531 .Nm
532 requires a Berkley Packet Filter, or BPF device on BSD based systems and a
533 Linux Socket Filter, or LPF device on Linux based systems.
534 .Sh FILES
535 .Bl -ohang
536 .It Pa @SYSCONFDIR@/dhcpcd.conf
537 Configuration file for dhcpcd.
538 If you always use the same options, put them here.
539 .It Pa @SYSCONFDIR@/dhcpcd.duid
540 Text file that holds the DUID used to identify the host.
541 .It Pa @SCRIPT@
542 Bourne shell script that is run to configure or de-configure an interface.
543 .It Pa @HOOKDIR@
544 A directory containing bourne shell scripts that are run by the above script.
545 Each script can be disabled by using the
546 .Fl C , -nohook
547 option described above.
548 .It Pa @DBDIR@/dhcpcd\- Ns Ar interface Ns .lease
549 The actual DHCP message send by the server. We use this when reading the last
550 lease and use the files mtime as when it was issued.
551 .It Pa /var/run/dhcpcd.pid
552 Stores the PID of
553 .Nm
554 running on all interfaces.
555 .It Pa /var/run/dhcpcd\- Ns Ar interface Ns .pid
556 Stores the PID of
557 .Nm
558 running on the
559 .Ar interface .
560 .El
561 .Sh SEE ALSO
562 .Xr dhcpcd.conf 5 ,
563 .Xr dhcpcd-run-hooks 8 ,
564 .Xr resolv.conf 5 ,
565 .Xr resolvconf 8 ,
566 .Xr if_nametoindex 3 ,
567 .Xr fnmatch 3
568 .Sh STANDARDS
569 RFC 951, RFC 1534, RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3396,
570 RFC 3397, RFC 3442, RFC 3927, RFC 4361, RFC 4390, RFC 4702.
571 .Sh AUTHORS
572 .An Roy Marples Aq roy@marples.name
573 .Sh BUGS
574 Please report them to http://roy.marples.name/projects/dhcpcd