1DHCPCD(8)                 BSD System Manager's Manual                DHCPCD(8)
2

NAME

4     dhcpcd — a DHCP client
5

SYNOPSIS

7     dhcpcd [-146ABbDdEGgHJKLMNPpqTV] [-C, --nohook hook]
8            [-c, --script script] [-e, --env value] [-F, --fqdn FQDN]
9            [-f, --config file] [-h, --hostname hostname]
10            [-I, --clientid clientid] [-i, --vendorclassid vendorclassid]
11            [-j, --logfile logfile] [-l, --leasetime seconds]
12            [-m, --metric metric] [-O, --nooption option]
13            [-o, --option option] [-Q, --require option]
14            [-r, --request address] [-S, --static value]
15            [-s, --inform address[/cidr]] [--inform6] [-t, --timeout seconds]
16            [-u, --userclass class] [-v, --vendor code, value]
17            [-W, --whitelist address[/cidr]] [-w] [--waitip [4 | 6]]
18            [-y, --reboot seconds] [-X, --blacklist address[/cidr]]
19            [-Z, --denyinterfaces pattern] [-z, --allowinterfaces pattern]
20            [--inactive] [interface] [...]
21     dhcpcd -n, --rebind [interface]
22     dhcpcd -k, --release [interface]
23     dhcpcd -U, --dumplease interface
24     dhcpcd --version
25     dhcpcd -x, --exit [interface]
26

DESCRIPTION

28     dhcpcd is an implementation of the DHCP client specified in RFC 2131.
29     dhcpcd gets the host information (IP address, routes, etc) from a DHCP
30     server and configures the network interface of the machine on which it is
31     running.  dhcpcd then runs the configuration script which writes DNS
32     information to resolvconf(8), if available, otherwise directly to
33     /etc/resolv.conf.  If the hostname is currently blank, (null) or local‐
34     host, or force_hostname is YES or TRUE or 1 then dhcpcd sets the hostname
35     to the one supplied by the DHCP server.  dhcpcd then daemonises and waits
36     for the lease renewal time to lapse.  It will then attempt to renew its
37     lease and reconfigure if the new lease changes when the lease beings to
38     expire or the DHCP server sends message to renew early.
39
40     If any interface reports a working carrier then dhcpcd will try and
41     obtain a lease before forking to the background, otherwise it will fork
42     right away.  This behaviour can be modified with the -b, --background and
43     -w, --waitip options.
44
45     dhcpcd is also an implementation of the BOOTP client specified in RFC
46     951.
47
48     dhcpcd is also an implementation of the IPv6 Router Solicitor as speci‐
49     fied in RFC 4861 and RFC 6106.
50
51     dhcpcd is also an implementation of the IPv6 Privacy Extensions to Auto‐
52     Conf as specified in RFC 4941.  This feature needs to be enabled in the
53     kernel and dhcpcd will start using it.
54
55     dhcpcd is also an implementation of the DHCPv6 client as specified in RFC
56     3315.  By default, dhcpcd only starts DHCPv6 when instructed to do so by
57     an IPV6 Router Advertisement.  If no Identity Association is configured,
58     then a Non-temporary Address is requested.
59
60   Local Link configuration
61     If dhcpcd failed to obtain a lease, it probes for a valid IPv4LL address
62     (aka ZeroConf, aka APIPA).  Once obtained it restarts the process of
63     looking for a DHCP server to get a proper address.
64
65     When using IPv4LL, dhcpcd nearly always succeeds and returns an exit code
66     of 0.  In the rare case it fails, it normally means that there is a
67     reverse ARP proxy installed which always defeats IPv4LL probing.  To dis‐
68     able this behaviour, you can use the -L, --noipv4ll option.
69
70   Multiple interfaces
71     If a list of interfaces are given on the command line, then dhcpcd only
72     works with those interfaces, otherwise dhcpcd discovers available Ether‐
73     net interfaces that can be configured.  When dhcpcd not limited to one
74     interface on the command line, it is running in Master mode.  The
75     dhcpcd-ui project expects dhcpcd to be running this way.
76
77     If a single interface is given then dhcpcd only works for that interface
78     and runs as a separate instance to other dhcpcd processes.  -w, --waitip
79     option is enabled in this instance to maintain compatibility with older
80     versions.  Using a single interface also affects the -k, -N, -n and -x
81     options where the same interface will need to be specified as a lack of
82     an interafce will imply Master mode which this is not.  To force starting
83     in Master mode with only one interface, the -M, --master option can be
84     used.
85
86     Interfaces are preferred by carrier, DHCP lease/IPv4LL and then lowest
87     metric.  For systems that support route metrics, each route will be
88     tagged with the metric, otherwise dhcpcd changes the routes to use the
89     interface with the same route and the lowest metric.  See options below
90     for controlling which interfaces we allow and deny through the use of
91     patterns.
92
93   Hooking into events
94     dhcpcd runs /usr/libexec/dhcpcd-run-hooks, or the script specified by the
95     -c, --script option.  This script runs each script found in
96     /usr/libexec/dhcpcd-hooks in a lexical order.  The default installation
97     supplies the scripts 01-test, 02-dump, 20-resolv.conf and 30-hostname.
98     You can disable each script by using the -C, --nohook option.  See
99     dhcpcd-run-hooks(8) for details on how these scripts work.  dhcpcd cur‐
100     rently ignores the exit code of the script.
101
102     More scripts are supplied in /usr/share/dhcpcd/hooks and need to be
103     copied to /usr/libexec/dhcpcd-hooks if you intend to use them.  For exam‐
104     ple, you could install 10-wpa_supplicant so that dhcpcd can ensure that
105     wpa_supplicant(8) is always running on a hot-plugged wireless interface.
106
107   Fine tuning
108     You can fine-tune the behaviour of dhcpcd with the following options:
109
110     -b, --background
111             Background immediately.  This is useful for startup scripts which
112             don't disable link messages for carrier status.
113
114     -c, --script script
115             Use this script instead of the default
116             /usr/libexec/dhcpcd-run-hooks.
117
118     -D, --duid
119             Generate an RFC 4361 compliant clientid.  This requires persis‐
120             tent storage and not all DHCP servers work with it so it is not
121             enabled by default.  dhcpcd generates the DUID and stores it in
122             /etc/dhcpcd.duid.  This file should not be copied to other hosts.
123
124     -d, --debug
125             Echo debug messages to the stderr and syslog.
126
127     -E, --lastlease
128             If dhcpcd cannot obtain a lease, then try to use the last lease
129             acquired for the interface.
130
131     --lastleaseextend
132             Same as the above, but he lease will be retained even if it
133             expires.  dhcpcd will give it up if any other host tries to claim
134             it for their own via ARP.  This is does violate RFC2131 section
135             3.7 which states the lease should be dropped once it has expired.
136
137     -e, --env value
138             Push value to the environment for use in dhcpcd-run-hooks(8).
139             For example, you can force the hostname hook to always set the
140             hostname with -e force_hostname=YES.
141
142     -g, --reconfigure
143             dhcpcd will re-apply IP address, routing and run
144             dhcpcd-run-hooks(8) for each interface.  This is useful so that a
145             3rd party such as PPP or VPN can change the routing table and /
146             or DNS, etc and then instruct dhcpcd to put things back after‐
147             wards.  dhcpcd does not read a new configuration when this hap‐
148             pens - you should rebind if you need that functionality.
149
150     -F, --fqdn fqdn
151             Requests that the DHCP server updates DNS using FQDN instead of
152             just a hostname.  Valid values for fqdn are disable, none, ptr
153             and both.  dhcpcd itself never does any DNS updates.  dhcpcd
154             encodes the FQDN hostname as specified in RFC1035.
155
156     -f, --config file
157             Specify a config to load instead of /etc/dhcpcd.conf.  dhcpcd
158             always processes the config file before any command line options.
159
160     -h, --hostname hostname
161             Sends hostname to the DHCP server so it can be registered in DNS.
162             If hostname is an empty string then the current system hostname
163             is sent.  If hostname is a FQDN (ie, contains a .) then it will
164             be encoded as such.
165
166     -I, --clientid clientid
167             Send the clientid.  If the string is of the format 01:02:03 then
168             it is encoded as hex.  For interfaces whose hardware address is
169             longer than 8 bytes, or if the clientid is an empty string then
170             dhcpcd sends a default clientid of the hardware family and the
171             hardware address.
172
173     -i, --vendorclassid vendorclassid
174             Override the DHCPv4 vendorclassid field sent.  The default is
175             dhcpcd-<version>:<os>:<machine>:<platform>.  For example
176                   dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386
177             If not set then none is sent.  Some badly configured DHCP servers
178             reject unknown vendorclassids.  To work around it, try and imper‐
179             sonate Windows by using the MSFT vendorclassid.
180
181     -j, --logfile logfile
182             Writes to the specified logfile rather than syslog(3).  The
183             logfile is truncated when opened and is reopened when dhcpcd
184             receives the SIGUSR2 signal.
185
186     -k, --release [interface]
187             This causes an existing dhcpcd process running on the interface
188             to release its lease and de-configure the interface regardless of
189             the -p, --persistent option.  If no interface is specified then
190             this applies to all interfaces in Master mode.  If no interfaces
191             are left running, dhcpcd will exit.
192
193     -l, --leasetime seconds
194             Request a specific lease time in seconds.  By default dhcpcd does
195             not request any lease time and leaves it in the hands of the DHCP
196             server.
197
198     -M, --master
199             Start dhcpcd in Master mode even if only one interface specified
200             on the command line.  See the Multiple Interfaces section above.
201
202     -m, --metric metric
203             Metrics are used to prefer an interface over another one, lowest
204             wins.  dhcpcd will supply a default metic of 200 +
205             if_nametoindex(3).  An extra 100 will be added for wireless
206             interfaces.
207
208     -n, --rebind [interface]
209             Notifies dhcpcd to reload its configuration and rebind the speci‐
210             fied interface.  If no interface is specified then this applies
211             to all interfaces in Master mode.  If dhcpcd is not running, then
212             it starts up as normal.  This may also cause wpa_supplicant(8) to
213             reload its configuration for each interface as well if the rele‐
214             vant hook script has been installed.
215
216     -N, --renew [interface]
217             Notifies dhcpcd to renew existing addresses on the specified
218             interface.  If no interface is specified then this applies to all
219             interfaces in Master mode.  If dhcpcd is not running, then it
220             starts up as normal.  Unlike the -n, --rebind option above, the
221             configuration for dhcpcd is not reloaded.
222
223     -o, --option option
224             Request the DHCP option variable for use in
225             /usr/libexec/dhcpcd-run-hooks.
226
227     -p, --persistent
228             dhcpcd normally de-configures the interface and configuration
229             when it exits.  Sometimes, this isn't desirable if, for example,
230             you have root mounted over NFS or SSH clients connect to this
231             host and they need to be notified of the host shutting down.  You
232             can use this option to stop this from happening.
233
234     -r, --request [address]
235             Request the address in the DHCP DISCOVER message.  There is no
236             guarantee this is the address the DHCP server will actually give.
237             If no address is given then the first address currently assigned
238             to the interface is used.
239
240     -s, --inform [address[/cidr]]
241             Behaves like -r, --request as above, but sends a DHCP INFORM
242             instead of DISCOVER/REQUEST.  This does not get a lease as such,
243             just notifies the DHCP server of the address in use.  You should
244             also include the optional cidr network number in case the address
245             is not already configured on the interface.  dhcpcd remains run‐
246             ning and pretends it has an infinite lease.  dhcpcd will not de-
247             configure the interface when it exits.  If dhcpcd fails to con‐
248             tact a DHCP server then it returns a failure instead of falling
249             back on IPv4LL.
250
251     --inform6
252             Performs a DHCPv6 Information Request.  No address is requested
253             or specified, but all other DHCPv6 options are allowed.  This is
254             normally performed automatically when the IPv6 Router Advertises
255             that the client should perform this operation.  This option is
256             only needed when dhcpcd is not processing IPv6RA messages and the
257             need for DHCPv6 Information Request exists.
258
259     -S, --static value
260             Configures a static DHCP value.  If you set ip_address then
261             dhcpcd will not attempt to obtain a lease and just use the value
262             for the address with an infinite lease time.
263
264             Here is an example which configures a static address, routes and
265             dns.
266                   dhcpcd -S ip_address=192.168.0.10/24 \
267                   -S routers=192.168.0.1 \
268                   -S domain_name_servers=192.168.0.1 \
269                   eth0
270
271             You cannot presently set static DHCPv6 values.  Use the -e, --env
272             option instead.
273
274     -t, --timeout seconds
275             Timeout after seconds, instead of the default 30.  A setting of 0
276             seconds causes dhcpcd to wait forever to get a lease.  If dhcpcd
277             is working on a single interface then dhcpcd will exit when a
278             timeout occurs, otherwise dhcpcd will fork into the background.
279
280     -u, --userclass class
281             Tags the DHCPv4 message with the userclass class.  DHCP servers
282             use this to give members of the class DHCP options other than the
283             default, without having to know things like hardware address or
284             hostname.
285
286     -v, --vendor code,value
287             Add an encapsulated vendor option.  code should be between 1 and
288             254 inclusive.  To add a raw vendor string, omit code but keep
289             the comma.  Examples.
290
291             Set the vendor option 01 with an IP address.
292                   dhcpcd -v 01,192.168.0.2 eth0
293             Set the vendor option 02 with a hex code.
294                   dhcpcd -v 02,01:02:03:04:05 eth0
295             Set the vendor option 03 with an IP address as a string.
296                   dhcpcd -v 03,\"192.168.0.2\" eth0
297             Set un-encapsulated vendor option to hello world.
298                   dhcpcd -v ,"hello world" eth0
299
300     --version
301             Display both program version and copyright information.  dhcpcd
302             then exits before doing any configuration.
303
304     -w      Wait for an address to be assigned before forking to the back‐
305             ground.  Does not take an argument, unlike the below option.  -fl
306             -waitip option.
307
308     --waitip [4 | 6]
309             Wait for an address to be assigned before forking to the back‐
310             ground.  4 means wait for an IPv4 address to be assigned.  6
311             means wait for an IPv6 address to be assigned.  If no argument is
312             given, dhcpcd will wait for any address protocol to be assigned.
313             It is possible to wait for more than one address protocol and
314             dhcpcd will only fork to the background when all waiting condi‐
315             tions are satisfied.
316
317     -x, --exit [interface]
318             This will signal an existing dhcpcd process running on the
319             interface to exit.  If no interface is specified, then the above
320             is applied to all interfaces in Master mode.  See the -p,
321             --persistent option to control configuration persistence on exit,
322             which is enabled by default in dhcpcd.conf(5).  dhcpcd then waits
323             until this process has exited.
324
325     -y, --reboot seconds
326             Allow reboot seconds before moving to the discover phase if we
327             have an old lease to use.  Allow reboot seconds before starting
328             fallback states from the discover phase.  IPv4LL is started when
329             the first reboot timeout is reached.  The default is 5 seconds.
330             A setting of 0 seconds causes dhcpcd to skip the reboot phase and
331             go straight into discover.  This has no effect on DHCPv6 other
332             than skipping the reboot phase.
333
334   Restricting behaviour
335     dhcpcd will try to do as much as it can by default.  However, there are
336     sometimes situations where you don't want the things to be configured
337     exactly how the the DHCP server wants.  Here are some options that deal
338     with turning these bits off.
339
340     -1, --oneshot
341             Exit after configuring an interface.  Use the -w, --waitip option
342             to specify which protocol(s) to configure before exiting.
343
344     -4, --ipv4only
345             Configure IPv4 only.
346
347     -6, --ipv6only
348             Configure IPv6 only.
349
350     -A, --noarp
351             Don't request or claim the address by ARP.  This also disables
352             IPv4LL.
353
354     -B, --nobackground
355             Don't run in the background when we acquire a lease.  This is
356             mainly useful for running under the control of another process,
357             such as a debugger or a network manager.
358
359     -C, --nohook script
360             Don't run this hook script.  Matches full name, or prefixed with
361             2 numbers optionally ending with .sh.
362
363             So to stop dhcpcd from touching your DNS settings you would do:-
364                   dhcpcd -C resolv.conf eth0
365
366     -G, --nogateway
367             Don't set any default routes.
368
369     -H, --xidhwaddr
370             Use the last four bytes of the hardware address as the DHCP xid
371             instead of a randomly generated number.
372
373     -J, --broadcast
374             Instructs the DHCP server to broadcast replies back to the
375             client.  Normally this is only set for non Ethernet interfaces,
376             such as FireWire and InfiniBand.  In most instances, dhcpcd will
377             set this automatically.
378
379     -K, --nolink
380             Don't receive link messages for carrier status.  You should only
381             have to use this with buggy device drivers or running dhcpcd
382             through a network manager.
383
384     -L, --noipv4ll
385             Don't use IPv4LL (aka APIPA, aka Bonjour, aka ZeroConf).
386
387     -O, --nooption option
388             Removes the option from the DHCP message before processing.
389
390     -P, --printpidfile
391             Print the pidfile dhcpcd will use based on commmand-line argu‐
392             ments to stdout.
393
394     -Q, --require option
395             Requires the option to be present in all DHCP messages, otherwise
396             the message is ignored.  To enforce that dhcpcd only responds to
397             DHCP servers and not BOOTP servers, you can -Q dhcp_message_type.
398
399     -q, --quiet
400             Quiet dhcpcd on the command line, only warnings and errors will
401             be displayed.  The messages are still logged though.
402
403     -T, --test
404             On receipt of DHCP messages just call
405             /usr/libexec/dhcpcd-run-hooks with the reason of TEST which echos
406             the DHCP variables found in the message to the console.  The
407             interface configuration isn't touched and neither are any config‐
408             uration files.  The rapid_commit option is not sent in TEST mode
409             so that the server does not lease an address.  To test INFORM the
410             interface needs to be configured with the desired address before
411             starting dhcpcd.
412
413     -U, --dumplease interface
414             Dumps the last lease for the interface to stdout.  If omitted,
415             standard input is used to read a DHCP wire formatted message.
416             Use the -4 or -6 flags to specify an address family.
417
418     -V, --variables
419             Display a list of option codes, the associated variable and
420             encoding for use in dhcpcd-run-hooks(8).  Variables are prefixed
421             with new_ and old_ unless the option number is -.  Variables
422             without an option are part of the DHCP message and cannot be
423             directly requested.
424
425     -W, --whitelist address[/cidr]
426             Only accept packets from address[/cidr].  -X, --blacklist is
427             ignored if -W, --whitelist is set.
428
429     -X, --blacklist address[/cidr]
430             Ignore all packets from address[/cidr].
431
432     -Z, --denyinterfaces pattern
433             When discovering interfaces, the interface name must not match
434             pattern which is a space or comma separated list of patterns
435             passed to fnmatch(3).
436
437     -z, --allowinterfaces pattern
438             When discovering interfaces, the interface name must match
439             pattern which is a space or comma separated list of patterns
440             passed to fnmatch(3).  If the same interface is matched in -Z,
441             --denyinterfaces then it is still denied.
442
443     --inactive
444             Don't start any interfaces other than those specified on the com‐
445             mand line.  This allows dhcpcd to be started in Master mode and
446             then wait for subsequent dhcpcd commands to start each interface
447             as required.
448
449     --nodev
450             Don't load any /dev management modules.
451
453     Some interfaces require configuration by 3rd parties, such as PPP or VPN.
454     When an interface configuration in dhcpcd is marked as STATIC or INFORM
455     without an address then dhcpcd will monitor the interface until an
456     address is added or removed from it and act accordingly.  For point to
457     point interfaces (like PPP), a default route to its destination is auto‐
458     matically added to the configuration.  If the point to point interface is
459     configured for INFORM, then dhcpcd unicasts INFORM to the destination,
460     otherwise it defaults to STATIC.
461

NOTES

463     dhcpcd requires a Berkley Packet Filter, or BPF device on BSD based sys‐
464     tems and a Linux Socket Filter, or LPF device on Linux based systems for
465     all IPv4 configuration.
466
467     If restricting dhcpcd to a single interface and optionally address family
468     via the command-line then all further calls to dhcpcd to rebind, recon‐
469     figure or exit need to include the same restrictive flags so that dhcpcd
470     knows which process to signal.
471

FILES

473     /etc/dhcpcd.conf
474     Configuration file for dhcpcd.  If you always use the same options, put
475     them here.
476
477     /etc/dhcpcd.duid
478     Text file that holds the DUID used to identify the host.
479
480     /etc/dhcpcd.secret
481     Text file that holds a secret key known only to the host.
482
483     /usr/libexec/dhcpcd-run-hooks
484     Bourne shell script that is run to configure or de-configure an inter‐
485     face.
486
487     /usr/lib64/dhcpcd/dev
488     /dev management modules.
489
490     /usr/libexec/dhcpcd-hooks
491     A directory containing bourne shell scripts that are run by the above
492     script.  Each script can be disabled by using the -C, --nohook option
493     described above.
494
495     /var/lib/dhcpcd/dhcpcd-interface-ssid.lease
496     The actual DHCP message sent by the server.  We use this when reading the
497     last lease and use the files mtime as when it was issued.
498
499     /var/lib/dhcpcd/dhcpcd-interface-ssid.lease6
500     The actual DHCPv6 message sent by the server.  We use this when reading
501     the last lease and use the files mtime as when it was issued.
502
503     /var/lib/dhcpcd/dhcpcd-rdm.monotonic
504     Stores the monotonic counter used in the replay field in Authentication
505     Options.
506
507     /var/run/dhcpcd.pid
508     Stores the PID of dhcpcd running on all interfaces.
509
510     /var/run/dhcpcd-interface.pid
511     Stores the PID of dhcpcd running on the interface.
512
513     /var/run/dhcpcd.sock
514     Control socket to the master daemon.
515
516     /var/run/dhcpcd.unpriv.sock
517     Unpriviledged socket to the master daemon, only allows state retrieval.
518
519     /var/run/dhcpcd-interface.sock
520     Control socket to per interface daemon.
521

SEE ALSO

523     fnmatch(3), if_nametoindex(3), dhcpcd.conf(5), resolv.conf(5),
524     dhcpcd-run-hooks(8), resolvconf(8)
525

STANDARDS

527     RFC 951, RFC 1534, RFC 2104, RFC 2131, RFC 2132, RFC 2563, RFC 2855,
528     RFC 3004, RFC 3118, RFC 3203, RFC 3315, RFC 3361, RFC 3633, RFC 3396,
529     RFC 3397, RFC 3442, RFC 3495, RFC 3925, RFC 3927, RFC 4039, RFC 4075,
530     RFC 4242, RFC 4361, RFC 4390, RFC 4702, RFC 4074, RFC 4861, RFC 4833,
531     RFC 4941, RFC 5227, RFC 5942, RFC 5969, RFC 6106, RFC 6334, RFC 6603,
532     RFC 6704, RFC 7217, RFC 7550.
533

AUTHORS

535     Roy Marples <roy@marples.name>
536

BUGS

538     Please report them to
539           http://roy.marples.name/projects/dhcpcd
540
541BSD                             August 15, 2016                            BSD
Impressum