| blob | 9309250aa4814a69110ae6da83baa8f89617a7e8 |
1 .\" SPDX-License-Identifier: BSD-2-Clause
2 .\"
3 .\" Copyright (c) 2006-2020 Roy Marples
4 .\" All rights reserved
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" SUCH DAMAGE.
26 .\"
27 .Dd September 2, 2020
28 .Dt DHCPCD 8
29 .Os
30 .Sh NAME
31 .Nm dhcpcd
32 .Nd a DHCP client
33 .Sh SYNOPSIS
34 .Nm
35 .Op Fl 146ABbDdEGgHJKLMNPpqTV
36 .Op Fl C , Fl Fl nohook Ar hook
37 .Op Fl c , Fl Fl script Ar script
38 .Op Fl e , Fl Fl env Ar value
39 .Op Fl F , Fl Fl fqdn Ar FQDN
40 .Op Fl f , Fl Fl config Ar file
41 .Op Fl h , Fl Fl hostname Ar hostname
42 .Op Fl I , Fl Fl clientid Ar clientid
43 .Op Fl i , Fl Fl vendorclassid Ar vendorclassid
44 .Op Fl j , Fl Fl logfile Ar logfile
45 .Op Fl l , Fl Fl leasetime Ar seconds
46 .Op Fl m , Fl Fl metric Ar metric
47 .Op Fl O , Fl Fl nooption Ar option
48 .Op Fl o , Fl Fl option Ar option
49 .Op Fl Q , Fl Fl require Ar option
50 .Op Fl r , Fl Fl request Ar address
51 .Op Fl S , Fl Fl static Ar value
52 .Op Fl s , Fl Fl inform Ar address Ns Op Ar /cidr Ns Op Ar /broadcast_address
53 .Op Fl Fl inform6
54 .Op Fl t , Fl Fl timeout Ar seconds
55 .Op Fl u , Fl Fl userclass Ar class
56 .Op Fl v , Fl Fl vendor Ar code , Ar value
57 .Op Fl W , Fl Fl whitelist Ar address Ns Op Ar /cidr
58 .Op Fl w
59 .Op Fl Fl waitip Ns = Ns Op 4 | 6
60 .Op Fl y , Fl Fl reboot Ar seconds
61 .Op Fl X , Fl Fl blacklist Ar address Ns Op Ar /cidr
62 .Op Fl Z , Fl Fl denyinterfaces Ar pattern
63 .Op Fl z , Fl Fl allowinterfaces Ar pattern
64 .Op Fl Fl inactive
65 .Op interface
66 .Op ...
67 .Nm
68 .Fl n , Fl Fl rebind
69 .Op interface
70 .Nm
71 .Fl k , Fl Fl release
72 .Op interface
73 .Nm
74 .Fl U , Fl Fl dumplease
75 .Op Ar interface
76 .Nm
77 .Fl Fl version
78 .Nm
79 .Fl x , Fl Fl exit
80 .Op interface
81 .Sh DESCRIPTION
82 .Nm
83 is an implementation of the DHCP client specified in
84 .Li RFC 2131 .
85 .Nm
86 gets the host information
87 .Po
88 IP address, routes, etc
89 .Pc
90 from a DHCP server and configures the network
91 .Ar interface
92 of the
93 machine on which it is running.
94 .Nm
95 then runs the configuration script which writes DNS information to
96 .Xr resolvconf 8 ,
97 if available, otherwise directly to
98 .Pa /etc/resolv.conf .
99 If the hostname is currently blank, (null) or localhost, or
100 .Va force_hostname
101 is YES or TRUE or 1 then
102 .Nm
103 sets the hostname to the one supplied by the DHCP server.
104 .Nm
105 then daemonises and waits for the lease renewal time to lapse.
106 It will then attempt to renew its lease and reconfigure if the new lease
107 changes when the lease begins to expire or the DHCP server sends a message
108 to renew early.
109 .Pp
110 If any interface reports a working carrier then
111 .Nm
112 will try to obtain a lease before forking to the background,
113 otherwise it will fork right away.
114 This behaviour can be modified with the
115 .Fl b , Fl Fl background
116 and
117 .Fl w , Fl Fl waitip
118 options.
119 .Pp
120 .Nm
121 is also an implementation of the BOOTP client specified in
122 .Li RFC 951 .
123 .Pp
124 .Nm
125 is also an implementation of the IPv6 Router Solicitor as specified in
126 .Li RFC 4861
127 and
128 .Li RFC 6106 .
129 .Pp
130 .Nm
131 is also an implementation of the IPv6 Privacy Extensions to AutoConf as
132 specified in
133 .Li RFC 4941 .
134 This feature needs to be enabled in the kernel and
135 .Nm
136 will start using it.
137 .Pp
138 .Nm
139 is also an implementation of the DHCPv6 client as specified in
140 .Li RFC 3315 .
141 By default,
142 .Nm
143 only starts DHCPv6 when instructed to do so by an IPV6 Router Advertisement.
144 If no Identity Association is configured,
145 then a Non-temporary Address is requested.
146 .Ss Local Link configuration
147 If
148 .Nm
149 failed to obtain a lease, it probes for a valid IPv4LL address
150 .Po
151 aka ZeroConf, aka APIPA
152 .Pc .
153 Once obtained it restarts the process of looking for a DHCP server to get a
154 proper address.
155 .Pp
156 When using IPv4LL,
157 .Nm
158 nearly always succeeds and returns an exit code of 0.
159 In the rare case it fails, it normally means that there is a reverse ARP proxy
160 installed which always defeats IPv4LL probing.
161 To disable this behaviour, you can use the
162 .Fl L , Fl Fl noipv4ll
163 option.
164 .Ss Multiple interfaces
165 If a list of interfaces are given on the command line, then
166 .Nm
167 only works with those interfaces, otherwise
168 .Nm
169 discovers available Ethernet interfaces that can be configured.
170 When
171 .Nm
172 not limited to one interface on the command line,
173 it is running in Master mode.
174 The
175 .Nm dhcpcd-ui
176 project expects dhcpcd to be running this way.
177 .Pp
178 If a single interface is given then
179 .Nm
180 only works for that interface and runs as a separate instance to other
181 .Nm
182 processes.
183 .Fl w , Fl Fl waitip
184 option is enabled in this instance to maintain compatibility with older
185 versions.
186 Using a single interface also affects the
187 .Fl k ,
188 .Fl N ,
189 .Fl n
190 and
191 .Fl x
192 options, where the same interface will need to be specified, as a lack of an
193 interface will imply Master mode which this is not.
194 To force starting in Master mode with only one interface, the
195 .Fl M , Fl Fl master
196 option can be used.
197 .Pp
198 Interfaces are preferred by carrier, DHCP lease/IPv4LL and then lowest metric.
199 For systems that support route metrics, each route will be tagged with the
200 metric, otherwise
201 .Nm
202 changes the routes to use the interface with the same route and the lowest
203 metric.
204 See options below for controlling which interfaces we allow and deny through
205 the use of patterns.
206 .Pp
207 Non-ethernet interfaces and some virtual ethernet interfaces
208 such as TAP and bridge are ignored by default,
209 as is the FireWire interface.
210 To work with these devices they either need to be specified on the command line,
211 be listed in
212 .Fl Fl allowinterfaces
213 or have an interface directive in
214 .Pa @SYSCONFDIR@/dhcpcd.conf .
215 .Ss Hooking into events
216 .Nm
217 runs
218 .Pa @SCRIPT@ ,
219 or the script specified by the
220 .Fl c , Fl Fl script
221 option.
222 This script runs each script found in
223 .Pa @HOOKDIR@
224 in a lexical order.
225 The default installation supplies the scripts
226 .Pa 01-test ,
227 .Pa 02-dump ,
228 .Pa 20-resolv.conf
229 and
230 .Pa 30-hostname .
231 You can disable each script by using the
232 .Fl C , Fl Fl nohook
233 option.
234 See
235 .Xr dhcpcd-run-hooks 8
236 for details on how these scripts work.
237 .Nm
238 currently ignores the exit code of the script.
239 .Pp
240 More scripts are supplied in
241 .Pa @DATADIR@/dhcpcd/hooks
242 and need to be copied to
243 .Pa @HOOKDIR@
244 if you intend to use them.
245 For example, you could install
246 .Pa 29-lookup-hostname
247 so that
248 .Nm
249 can lookup the hostname of the IP address in DNS if no hostname
250 is given by the lease and one is not already set.
251 .Ss Fine tuning
252 You can fine-tune the behaviour of
253 .Nm
254 with the following options:
255 .Bl -tag -width indent
256 .It Fl b , Fl Fl background
257 Background immediately.
258 This is useful for startup scripts which don't disable link messages for
259 carrier status.
260 .It Fl c , Fl Fl script Ar script
261 Use this
262 .Ar script
263 instead of the default
264 .Pa @SCRIPT@ .
265 .It Fl D , Fl Fl duid
266 Use a DHCP Unique Identifier.
267 If a system UUID is available, that will be used to create a DUID-UUID,
268 otheriwse if persistent storage is available then a DUID-LLT
269 (link local address + time) is generated,
270 otherwise DUID-LL is generated (link local address).
271 This, plus the IAID will be used as the
272 .Fl I , Fl Fl clientid .
273 The DUID generated will be held in
274 .Pa @DBDIR@/duid
275 and should not be copied to other hosts.
276 This file also takes precedence over the above rules.
277 .It Fl d , Fl Fl debug
278 Echo debug messages to the stderr and syslog.
279 .It Fl E , Fl Fl lastlease
280 If
281 .Nm
282 cannot obtain a lease, then try to use the last lease acquired for the
283 interface.
284 .It Fl Fl lastleaseextend
285 Same as the above, but the lease will be retained even if it expires.
286 .Nm
287 will give it up if any other host tries to claim it for their own via ARP.
288 This violates RFC 2131, section 3.7, which states the lease should be
289 dropped once it has expired.
290 .It Fl e , Fl Fl env Ar value
291 Push
292 .Ar value
293 to the environment for use in
294 .Xr dhcpcd-run-hooks 8 .
295 For example, you can force the hostname hook to always set the hostname with
296 .Fl e
297 .Va force_hostname=YES .
298 .It Fl g , Fl Fl reconfigure
299 .Nm
300 will re-apply IP address, routing and run
301 .Xr dhcpcd-run-hooks 8
302 for each interface.
303 This is useful so that a 3rd party such as PPP or VPN can change the routing
304 table and / or DNS, etc and then instruct
305 .Nm
306 to put things back afterwards.
307 .Nm
308 does not read a new configuration when this happens - you should rebind if you
309 need that functionality.
310 .It Fl F , Fl Fl fqdn Ar fqdn
311 Requests that the DHCP server updates DNS using FQDN instead of just a
312 hostname.
313 Valid values for
314 .Ar fqdn
315 are disable, none, ptr and both.
316 .Nm
317 itself never does any DNS updates.
318 .Nm
319 encodes the FQDN hostname as specified in
320 .Li RFC 1035 .
321 .It Fl f , Fl Fl config Ar file
322 Specify a config to load instead of
323 .Pa @SYSCONFDIR@/dhcpcd.conf .
324 .Nm
325 always processes the config file before any command line options.
326 .It Fl h , Fl Fl hostname Ar hostname
327 Sends
328 .Ar hostname
329 to the DHCP server so it can be registered in DNS.
330 If
331 .Ar hostname
332 is an empty string then the current system hostname is sent.
333 If
334 .Ar hostname
335 is a FQDN (i.e., contains a .) then it will be encoded as such.
336 .It Fl I , Fl Fl clientid Ar clientid
337 Send the
338 .Ar clientid .
339 If the string is of the format 01:02:03 then it is encoded as hex.
340 For interfaces whose hardware address is longer than 8 bytes, or if the
341 .Ar clientid
342 is an empty string then
343 .Nm
344 sends a default
345 .Ar clientid
346 of the hardware family and the hardware address.
347 .It Fl i , Fl Fl vendorclassid Ar vendorclassid
348 Override the DHCPv4
349 .Ar vendorclassid
350 field sent.
351 The default is
352 dhcpcd-<version>:<os>:<machine>:<platform>.
353 For example
354 .D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386
355 If not set then none is sent.
356 Some badly configured DHCP servers reject unknown vendorclassids.
357 To work around it, try and impersonate Windows by using the MSFT vendorclassid.
358 .It Fl j , Fl Fl logfile Ar logfile
359 Writes to the specified
360 .Ar logfile .
361 .Nm
362 still writes to
363 .Xr syslog 3 .
364 The
365 .Ar logfile
366 is reopened when
367 .Nm
368 receives the
369 .Dv SIGUSR2
370 signal.
371 .It Fl k , Fl Fl release Op Ar interface
372 This causes an existing
373 .Nm
374 process running on the
375 .Ar interface
376 to release its lease and de-configure the
377 .Ar interface
378 regardless of the
379 .Fl p , Fl Fl persistent
380 option.
381 If no
382 .Ar interface
383 is specified then this applies to all interfaces in Master mode.
384 If no interfaces are left running,
385 .Nm
386 will exit.
387 .It Fl l , Fl Fl leasetime Ar seconds
388 Request a lease time of
389 .Ar seconds .
390 .Ar -1
391 represents an infinite lease time.
392 By default
393 .Nm
394 does not request any lease time and leaves it in the hands of the
395 DHCP server.
396 .It Fl M , Fl Fl master
397 Start
398 .Nm
399 in Master mode even if only one interface specified on the command line.
400 See the Multiple Interfaces section above.
401 .It Fl m , Fl Fl metric Ar metric
402 Metrics are used to prefer an interface over another one, lowest wins.
403 .Nm
404 will supply a default metic of 200 +
405 .Xr if_nametoindex 3 .
406 An extra 100 will be added for wireless interfaces.
407 .It Fl n , Fl Fl rebind Op Ar interface
408 Notifies
409 .Nm
410 to reload its configuration and rebind the specified
411 .Ar interface .
412 If no
413 .Ar interface
414 is specified then this applies to all interfaces in Master mode.
415 If
416 .Nm
417 is not running, then it starts up as normal.
418 .It Fl N , Fl Fl renew Op Ar interface
419 Notifies
420 .Nm
421 to renew existing addresses on the specified
422 .Ar interface .
423 If no
424 .Ar interface
425 is specified then this applies to all interfaces in Master mode.
426 If
427 .Nm
428 is not running, then it starts up as normal.
429 Unlike the
430 .Fl n , Fl Fl rebind
431 option above, the configuration for
432 .Nm
433 is not reloaded.
434 .It Fl o , Fl Fl option Ar option
435 Request the DHCP
436 .Ar option
437 variable for use in
438 .Pa @SCRIPT@ .
439 .It Fl p , Fl Fl persistent
440 .Nm
441 normally de-configures the
442 .Ar interface
443 and configuration when it exits.
444 Sometimes, this isn't desirable if, for example, you have root mounted over
445 NFS or SSH clients connect to this host and they need to be notified of
446 the host shutting down.
447 You can use this option to stop this from happening.
448 .It Fl r , Fl Fl request Ar address
449 Request the
450 .Ar address
451 in the DHCP DISCOVER message.
452 There is no guarantee this is the address the DHCP server will actually give.
453 If no
454 .Ar address
455 is given then the first address currently assigned to the
456 .Ar interface
457 is used.
458 .It Fl s , Fl Fl inform Ar address Ns Op Ar /cidr Ns Op Ar /broadcast_address
459 Behaves like
460 .Fl r , Fl Fl request
461 as above, but sends a DHCP INFORM instead of DISCOVER/REQUEST.
462 This does not get a lease as such, just notifies the DHCP server of the
463 .Ar address
464 in use.
465 You should also include the optional
466 .Ar cidr
467 network number in case the address is not already configured on the interface.
468 .Nm
469 remains running and pretends it has an infinite lease.
470 .Nm
471 will not de-configure the interface when it exits.
472 If
473 .Nm
474 fails to contact a DHCP server then it returns a failure instead of falling
475 back on IPv4LL.
476 .It Fl Fl inform6
477 Performs a DHCPv6 Information Request.
478 No address is requested or specified, but all other DHCPv6 options are allowed.
479 This is normally performed automatically when the IPv6 Router Advertises
480 that the client should perform this operation.
481 This option is only needed when
482 .Nm
483 is not processing IPv6RA messages and the need for DHCPv6 Information Request
484 exists.
485 .It Fl S , Fl Fl static Ar value
486 Configures a static DHCP
487 .Ar value .
488 If you set
489 .Ic ip_address
490 then
491 .Nm
492 will not attempt to obtain a lease and just use the value for the address with
493 an infinite lease time.
494 .Pp
495 Here is an example which configures a static address, routes and DNS.
496 .D1 dhcpcd -S ip_address=192.168.0.10/24 \e
497 .D1 -S routers=192.168.0.1 \e
498 .D1 -S domain_name_servers=192.168.0.1 \e
499 .D1 eth0
500 .Pp
501 You cannot presently set static DHCPv6 values.
502 Use the
503 .Fl e , Fl Fl env
504 option instead.
505 .It Fl t , Fl Fl timeout Ar seconds
506 Timeout after
507 .Ar seconds ,
508 instead of the default 30.
509 A setting of 0
510 .Ar seconds
511 causes
512 .Nm
513 to wait forever to get a lease.
514 If
515 .Nm
516 is working on a single interface then
517 .Nm
518 will exit when a timeout occurs, otherwise
519 .Nm
520 will fork into the background.
521 .It Fl u , Fl Fl userclass Ar class
522 Tags the DHCPv4 message with the userclass
523 .Ar class .
524 DHCP servers use this to give members of the class DHCP options other than the
525 default, without having to know things like hardware address or hostname.
526 .It Fl v , Fl Fl vendor Ar code , Ns Ar value
527 Add an encapsulated vendor option.
528 .Ar code
529 should be between 1 and 254 inclusive.
530 To add a raw vendor string, omit
531 .Ar code
532 but keep the comma.
533 Examples.
534 .Pp
535 Set the vendor option 01 with an IP address.
536 .D1 dhcpcd \-v 01,192.168.0.2 eth0
537 Set the vendor option 02 with a hex code.
538 .D1 dhcpcd \-v 02,01:02:03:04:05 eth0
539 Set the vendor option 03 with an IP address as a string.
540 .D1 dhcpcd \-v 03,\e"192.168.0.2\e" eth0
541 Set un-encapsulated vendor option to hello world.
542 .D1 dhcpcd \-v ,"hello world" eth0
543 .It Fl Fl version
544 Display both program version and copyright information.
545 .Nm
546 then exits before doing any configuration.
547 .It Fl w
548 Wait for an address to be assigned before forking to the background.
549 Does not take an argument, unlike the below option.
550 .It Fl Fl waitip Ns = Ns Op 4 | 6
551 Wait for an address to be assigned before forking to the background.
552 4 means wait for an IPv4 address to be assigned.
553 6 means wait for an IPv6 address to be assigned.
554 If no argument is given,
555 .Nm
556 will wait for any address protocol to be assigned.
557 It is possible to wait for more than one address protocol and
558 .Nm
559 will only fork to the background when all waiting conditions are satisfied.
560 .It Fl x , Fl Fl exit Op Ar interface
561 This will signal an existing
562 .Nm
563 process running on the
564 .Ar interface
565 to exit.
566 If no
567 .Ar interface
568 is specified, then the above is applied to all interfaces in Master mode.
569 See the
570 .Fl p , Fl Fl persistent
571 option to control configuration persistence on exit,
572 which is enabled by default in
573 .Xr dhcpcd.conf 5 .
574 .Nm
575 then waits until this process has exited.
576 .It Fl y , Fl Fl reboot Ar seconds
577 Allow
578 .Ar reboot
579 seconds before moving to the discover phase if we have an old lease to use.
580 Allow
581 .Ar reboot
582 seconds before starting fallback states from the discover phase.
583 IPv4LL is started when the first
584 .Ar reboot
585 timeout is reached.
586 The default is 5 seconds.
587 A setting of 0 seconds causes
588 .Nm
589 to skip the reboot phase and go straight into discover.
590 This has no effect on DHCPv6 other than skipping the reboot phase.
591 .El
592 .Ss Restricting behaviour
593 .Nm
594 will try to do as much as it can by default.
595 However, there are sometimes situations where you don't want the things to be
596 configured exactly how the DHCP server wants.
597 Here are some options that deal with turning these bits off.
598 .Pp
599 Note that when
600 .Nm
601 is restricted to a single interface then the interface also needs to be
602 specified when asking
603 .Nm
604 to exit using the commandline.
605 If the protocol is restricted as well then the protocol needs to be included
606 with the exit instruction.
607 .Bl -tag -width indent
608 .It Fl 1 , Fl Fl oneshot
609 Exit after configuring an interface.
610 Use the
611 .Fl w , Fl Fl waitip
612 option to specify which protocol(s) to configure before exiting.
613 .It Fl 4 , Fl Fl ipv4only
614 Configure IPv4 only.
615 .It Fl 6 , Fl Fl ipv6only
616 Configure IPv6 only.
617 .It Fl A , Fl Fl noarp
618 Don't request or claim the address by ARP.
619 This also disables IPv4LL.
620 .It Fl B , Fl Fl nobackground
621 Don't run in the background when we acquire a lease.
622 This is mainly useful for running under the control of another process, such
623 as a debugger or a network manager.
624 .It Fl C , Fl Fl nohook Ar script
625 Don't run this hook script.
626 Matches full name, or prefixed with 2 numbers optionally ending with
627 .Pa .sh .
628 .Pp
629 So to stop
630 .Nm
631 from touching your DNS settings you would do:-
632 .D1 dhcpcd -C resolv.conf eth0
633 .It Fl G , Fl Fl nogateway
634 Don't set any default routes.
635 .It Fl H , Fl Fl xidhwaddr
636 Use the last four bytes of the hardware address as the DHCP xid instead
637 of a randomly generated number.
638 .It Fl J , Fl Fl broadcast
639 Instructs the DHCP server to broadcast replies back to the client.
640 Normally this is only set for non-Ethernet interfaces,
641 such as FireWire and InfiniBand.
642 In most instances,
643 .Nm
644 will set this automatically.
645 .It Fl K , Fl Fl nolink
646 Don't receive link messages for carrier status.
647 You should only have to use this with buggy device drivers or running
648 .Nm
649 through a network manager.
650 .It Fl L , Fl Fl noipv4ll
651 Don't use IPv4LL (aka APIPA, aka Bonjour, aka ZeroConf).
652 .It Fl O , Fl Fl nooption Ar option
653 Removes the
654 .Ar option
655 from the DHCP message before processing.
656 .It Fl P , Fl Fl printpidfile
657 Print the
658 .Pa pidfile
659 .Nm
660 will use based on commmand-line arguments to stdout.
661 .It Fl Q , Fl Fl require Ar option
662 Requires the
663 .Ar option
664 to be present in all DHCP messages, otherwise the message is ignored.
665 To enforce that
666 .Nm
667 only responds to DHCP servers and not BOOTP servers, you can
668 .Fl Q
669 .Ar dhcp_message_type .
670 .It Fl q , Fl Fl quiet
671 Quiet
672 .Nm
673 on the command line, only warnings and errors will be displayed.
674 If this option is used another time then all console output is disabled.
675 These messages are still logged via
676 .Xr syslog 3 .
677 .It Fl T , Fl Fl test
678 On receipt of DHCP messages just call
679 .Pa @SCRIPT@
680 with the reason of TEST which echos the DHCP variables found in the message
681 to the console.
682 The interface configuration isn't touched and neither are any configuration
683 files.
684 The
685 .Ar rapid_commit
686 option is not sent in TEST mode so that the server does not lease an address.
687 To test INFORM the interface needs to be configured with the desired address
688 before starting
689 .Nm .
690 .It Fl U , Fl Fl dumplease Op Ar interface
691 Dumps the current lease for the
692 .Ar interface
693 to stdout.
694 If no
695 .Ar interface
696 is given then all interfaces are dumped.
697 Use the
698 .Fl 4
699 or
700 .Fl 6
701 flags to specify an address family.
702 If a lease is piped in via standard input then that is dumped.
703 In this case, specifying an address family is mandatory.
704 .It Fl V , Fl Fl variables
705 Display a list of option codes, the associated variable and encoding for use in
706 .Xr dhcpcd-run-hooks 8 .
707 Variables are prefixed with new_ and old_ unless the option number is -.
708 Variables without an option are part of the DHCP message and cannot be
709 directly requested.
710 .It Fl W , Fl Fl whitelist Ar address Ns Op /cidr
711 Only accept packets from
712 .Ar address Ns Op /cidr .
713 .Fl X , Fl Fl blacklist
714 is ignored if
715 .Fl W , Fl Fl whitelist
716 is set.
717 .It Fl X , Fl Fl blacklist Ar address Ns Op Ar /cidr
718 Ignore all packets from
719 .Ar address Ns Op Ar /cidr .
720 .It Fl Z , Fl Fl denyinterfaces Ar pattern
721 When discovering interfaces, the interface name must not match
722 .Ar pattern
723 which is a space or comma separated list of patterns passed to
724 .Xr fnmatch 3 .
725 .It Fl z , Fl Fl allowinterfaces Ar pattern
726 When discovering interfaces, the interface name must match
727 .Ar pattern
728 which is a space or comma separated list of patterns passed to
729 .Xr fnmatch 3 .
730 If the same interface is matched in
731 .Fl Z , Fl Fl denyinterfaces
732 then it is still denied.
733 .It Fl Fl inactive
734 Don't start any interfaces other than those specified on the command line.
735 This allows
736 .Nm
737 to be started in Master mode and then wait for subsequent
738 .Nm
739 commands to start each interface as required.
740 .It Fl Fl nodev
741 Don't load any
742 .Pa /dev
743 management modules.
744 .El
745 .Sh 3RDPARTY LINK MANAGEMENT
746 Some interfaces require configuration by 3rd parties, such as PPP or VPN.
747 When an interface configuration in
748 .Nm
749 is marked as STATIC or INFORM without an address then
750 .Nm
751 will monitor the interface until an address is added or removed from it and
752 act accordingly.
753 For point to point interfaces (like PPP), a default route to its
754 destination is automatically added to the configuration.
755 If the point to point interface is configured for INFORM, then
756 .Nm
757 unicasts INFORM to the destination, otherwise it defaults to STATIC.
758 .Sh NOTES
759 .Nm
760 requires a Berkley Packet Filter, or BPF device on BSD based systems and a
761 Linux Socket Filter, or LPF device on Linux based systems for all IPv4
762 configuration.
763 .Pp
764 If restricting
765 .Nm
766 to a single interface and optionally address family via the command-line
767 then all further calls to
768 .Nm
769 to rebind, reconfigure or exit need to include the same restrictive flags
770 so that
771 .Nm
772 knows which process to signal.
773 .Pp
774 Some DHCP servers implement ClientID filtering.
775 If
776 .Nm
777 is replacing an in-use DHCP client then you might need to adjust the clientid
778 option
779 .Nm
780 sends to match.
781 If using a DUID in place of the ClientID, edit
782 .Pa @DBDIR@/duid
783 accordingly.
784 .Sh FILES
785 .Bl -ohang
786 .It Pa @SYSCONFDIR@/dhcpcd.conf
787 Configuration file for dhcpcd.
788 If you always use the same options, put them here.
789 .It Pa @SCRIPT@
790 Bourne shell script that is run to configure or de-configure an interface.
791 .It Pa @LIBDIR@/dhcpcd/dev
792 Linux
793 .Pa /dev
794 management modules.
795 .It Pa @HOOKDIR@
796 A directory containing bourne shell scripts that are run by the above script.
797 Each script can be disabled by using the
798 .Fl C , Fl Fl nohook
799 option described above.
800 .It Pa @DBDIR@/duid
801 Text file that holds the DUID used to identify the host.
802 .It Pa @DBDIR@/secret
803 Text file that holds a secret key known only to the host.
804 .It Pa @DBDIR@/ Ns Ar interface Ns Ar -ssid Ns .lease
805 The actual DHCP message sent by the server.
806 We use this when reading the last
807 lease and use the file's mtime as when it was issued.
808 .It Pa @DBDIR@/ Ns Ar interface Ns Ar -ssid Ns .lease6
809 The actual DHCPv6 message sent by the server.
810 We use this when reading the last
811 lease and use the file's mtime as when it was issued.
812 .It Pa @DBDIR@/rdm_monotonic
813 Stores the monotonic counter used in the
814 .Ar replay
815 field in Authentication Options.
816 .It Pa @RUNDIR@/pid
817 Stores the PID of
818 .Nm
819 running on all interfaces.
820 .It Pa @RUNDIR@/ Ns Ar interface Ns .pid
821 Stores the PID of
822 .Nm
823 running on the
824 .Ar interface .
825 .It Pa @RUNDIR@/sock
826 Control socket to the master daemon.
827 .It Pa @RUNDIR@/unpriv.sock
828 Unprivileged socket to the master daemon, only allows state retrieval.
829 .It Pa @RUNDIR@/ Ns Ar interface Ns .sock
830 Control socket to per interface daemon.
831 .El
832 .Sh SEE ALSO
833 .Xr fnmatch 3 ,
834 .Xr if_nametoindex 3 ,
835 .Xr dhcpcd.conf 5 ,
836 .Xr resolv.conf 5 ,
837 .Xr dhcpcd-run-hooks 8 ,
838 .Xr resolvconf 8
839 .Sh STANDARDS
840 RFC\ 951, RFC\ 1534, RFC\ 2104, RFC\ 2131, RFC\ 2132, RFC\ 2563, RFC\ 2855,
841 RFC\ 3004, RFC\ 3118, RFC\ 3203, RFC\ 3315, RFC\ 3361, RFC\ 3633, RFC\ 3396,
842 RFC\ 3397, RFC\ 3442, RFC\ 3495, RFC\ 3925, RFC\ 3927, RFC\ 4039, RFC\ 4075,
843 RFC\ 4242, RFC\ 4361, RFC\ 4390, RFC\ 4702, RFC\ 4074, RFC\ 4861, RFC\ 4833,
844 RFC\ 4941, RFC\ 5227, RFC\ 5942, RFC\ 5969, RFC\ 6106, RFC\ 6334, RFC\ 6355,
845 RFC\ 6603, RFC\ 6704, RFC\ 7217, RFC\ 7550, RFC\ 7844.
846 .Sh AUTHORS
847 .An Roy Marples Aq Mt roy@marples.name
848 .Sh BUGS
849 If
850 .Nm
851 is running in a
852 .Xr chroot 2
853 then re-opening the
854 .Fl Fl logfile
855 from SIGUSR2 may not work.
856 .Pp
857 Please report them to
858 .Lk http://roy.marples.name/projects/dhcpcd