1 .\" SPDX-License-Identifier: BSD-2-Clause
3 .\" Copyright (c) 2006-2020 Roy Marples
4 .\" All rights reserved
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
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
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
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
76 .Fl U , Fl Fl dumplease
85 is an implementation of the DHCP client specified in
88 gets the host information
90 IP address, routes, etc
92 from a DHCP server and configures the network
95 machine on which it is running.
97 then runs the configuration script which writes DNS information to
99 if available, otherwise directly to
100 .Pa /etc/resolv.conf .
101 If the hostname is currently blank, (null) or localhost, or
103 is YES or TRUE or 1 then
105 sets the hostname to the one supplied by the DHCP server.
107 then daemonises and waits for the lease renewal time to lapse.
108 It will then attempt to renew its lease and reconfigure if the new lease
109 changes when the lease begins to expire or the DHCP server sends a message
112 If any interface reports a working carrier then
114 will try to obtain a lease before forking to the background,
115 otherwise it will fork right away.
116 This behaviour can be modified with the
117 .Fl b , Fl Fl background
123 is also an implementation of the BOOTP client specified in
127 is also an implementation of the IPv6 Router Solicitor as specified in
133 is also an implementation of the IPv6 Privacy Extensions to AutoConf as
136 This feature needs to be enabled in the kernel and
141 is also an implementation of the DHCPv6 client as specified in
145 only starts DHCPv6 when instructed to do so by an IPV6 Router Advertisement.
146 If no Identity Association is configured,
147 then a Non-temporary Address is requested.
148 .Ss Local Link configuration
151 failed to obtain a lease, it probes for a valid IPv4LL address
153 aka ZeroConf, aka APIPA
155 Once obtained it restarts the process of looking for a DHCP server to get a
160 nearly always succeeds and returns an exit code of 0.
161 In the rare case it fails, it normally means that there is a reverse ARP proxy
162 installed which always defeats IPv4LL probing.
163 To disable this behaviour, you can use the
164 .Fl L , Fl Fl noipv4ll
166 .Ss Multiple interfaces
167 If a list of interfaces are given on the command line, then
169 only works with those interfaces, otherwise
171 discovers available Ethernet interfaces that can be configured.
174 not limited to one interface on the command line,
175 it is running in Master mode.
178 project expects dhcpcd to be running this way.
180 If a single interface is given then
182 only works for that interface and runs as a separate instance to other
186 option is enabled in this instance to maintain compatibility with older
188 Using a single interface also affects the
194 options, where the same interface will need to be specified, as a lack of an
195 interface will imply Master mode which this is not.
196 To force starting in Master mode with only one interface, the
200 Interfaces are preferred by carrier, DHCP lease/IPv4LL and then lowest metric.
201 For systems that support route metrics, each route will be tagged with the
204 changes the routes to use the interface with the same route and the lowest
206 See options below for controlling which interfaces we allow and deny through
209 Non-ethernet interfaces and some virtual ethernet interfaces
210 such as TAP and bridge are ignored by default,
211 as is the FireWire interface.
212 To work with these devices they either need to be specified on the command line,
214 .Fl Fl allowinterfaces
215 or have an interface directive in
216 .Pa @SYSCONFDIR@/dhcpcd.conf .
217 .Ss Hooking into events
221 or the script specified by the
224 This script runs each script found in
227 The default installation supplies the scripts
233 You can disable each script by using the
237 .Xr dhcpcd-run-hooks 8
238 for details on how these scripts work.
240 currently ignores the exit code of the script.
242 More scripts are supplied in
243 .Pa @DATADIR@/dhcpcd/hooks
244 and need to be copied to
246 if you intend to use them.
247 For example, you could install
248 .Pa 29-lookup-hostname
251 can lookup the hostname of the IP address in DNS if no hostname
252 is given by the lease and one is not already set.
254 You can fine-tune the behaviour of
256 with the following options:
257 .Bl -tag -width indent
258 .It Fl b , Fl Fl background
259 Background immediately.
260 This is useful for startup scripts which don't disable link messages for
262 .It Fl c , Fl Fl script Ar script
265 instead of the default
267 .It Fl D , Fl Fl duid Op Ar ll | lt | uuid | value
268 Use a DHCP Unique Identifier.
269 If a system UUID is available, that will be used to create a DUID-UUID,
270 otheriwse if persistent storage is available then a DUID-LLT
271 (link local address + time) is generated,
272 otherwise DUID-LL is generated (link local address).
273 The DUID type can be hinted as an optional parameter if the file
283 will be converted from 00:11:22:33 format.
284 This, plus the IAID will be used as the
285 .Fl I , Fl Fl clientid .
286 The DUID generated will be held in
288 and should not be copied to other hosts.
289 This file also takes precedence over the above rules except for setting a value.
290 .It Fl d , Fl Fl debug
291 Echo debug messages to the stderr and syslog.
292 .It Fl E , Fl Fl lastlease
295 cannot obtain a lease, then try to use the last lease acquired for the
297 .It Fl Fl lastleaseextend
298 Same as the above, but the lease will be retained even if it expires.
300 will give it up if any other host tries to claim it for their own via ARP.
301 This violates RFC 2131, section 3.7, which states the lease should be
302 dropped once it has expired.
303 .It Fl e , Fl Fl env Ar value
306 to the environment for use in
307 .Xr dhcpcd-run-hooks 8 .
308 For example, you can force the hostname hook to always set the hostname with
310 .Va force_hostname=YES .
311 .It Fl g , Fl Fl reconfigure
313 will re-apply IP address, routing and run
314 .Xr dhcpcd-run-hooks 8
316 This is useful so that a 3rd party such as PPP or VPN can change the routing
317 table and / or DNS, etc and then instruct
319 to put things back afterwards.
321 does not read a new configuration when this happens - you should rebind if you
322 need that functionality.
323 .It Fl F , Fl Fl fqdn Ar fqdn
324 Requests that the DHCP server updates DNS using FQDN instead of just a
328 are disable, none, ptr and both.
330 itself never does any DNS updates.
332 encodes the FQDN hostname as specified in
334 .It Fl f , Fl Fl config Ar file
335 Specify a config to load instead of
336 .Pa @SYSCONFDIR@/dhcpcd.conf .
338 always processes the config file before any command line options.
339 .It Fl h , Fl Fl hostname Ar hostname
342 to the DHCP server so it can be registered in DNS.
345 is an empty string then the current system hostname is sent.
348 is a FQDN (i.e., contains a .) then it will be encoded as such.
349 .It Fl I , Fl Fl clientid Ar clientid
352 If the string is of the format 01:02:03 then it is encoded as hex.
353 For interfaces whose hardware address is longer than 8 bytes, or if the
355 is an empty string then
359 of the hardware family and the hardware address.
360 .It Fl i , Fl Fl vendorclassid Ar vendorclassid
365 dhcpcd-<version>:<os>:<machine>:<platform>.
367 .D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386
368 If not set then none is sent.
369 Some badly configured DHCP servers reject unknown vendorclassids.
370 To work around it, try and impersonate Windows by using the MSFT vendorclassid.
371 .It Fl j , Fl Fl logfile Ar logfile
372 Writes to the specified
384 .It Fl k , Fl Fl release Op Ar interface
385 This causes an existing
387 process running on the
389 to release its lease and de-configure the
392 .Fl p , Fl Fl persistent
396 is specified then this applies to all interfaces in Master mode.
397 If no interfaces are left running,
400 .It Fl l , Fl Fl leasetime Ar seconds
401 Request a lease time of
404 represents an infinite lease time.
407 does not request any lease time and leaves it in the hands of the
409 .It Fl M , Fl Fl master
412 in Master mode even if only one interface specified on the command line.
413 See the Multiple Interfaces section above.
414 .It Fl m , Fl Fl metric Ar metric
415 Metrics are used to prefer an interface over another one, lowest wins.
417 will supply a default metic of 200 +
418 .Xr if_nametoindex 3 .
419 An extra 100 will be added for wireless interfaces.
420 .It Fl n , Fl Fl rebind Op Ar interface
423 to reload its configuration and rebind the specified
427 is specified then this applies to all interfaces in Master mode.
430 is not running, then it starts up as normal.
431 .It Fl N , Fl Fl renew Op Ar interface
434 to renew existing addresses on the specified
438 is specified then this applies to all interfaces in Master mode.
441 is not running, then it starts up as normal.
444 option above, the configuration for
447 .It Fl o , Fl Fl option Ar option
452 .It Fl p , Fl Fl persistent
454 normally de-configures the
456 and configuration when it exits.
457 Sometimes, this isn't desirable if, for example, you have root mounted over
458 NFS or SSH clients connect to this host and they need to be notified of
459 the host shutting down.
460 You can use this option to stop this from happening.
461 .It Fl r , Fl Fl request Ar address
464 in the DHCP DISCOVER message.
465 There is no guarantee this is the address the DHCP server will actually give.
468 is given then the first address currently assigned to the
471 .It Fl s , Fl Fl inform Ar address Ns Op Ar /cidr Ns Op Ar /broadcast_address
473 .Fl r , Fl Fl request
474 as above, but sends a DHCP INFORM instead of DISCOVER/REQUEST.
475 This does not get a lease as such, just notifies the DHCP server of the
478 You should also include the optional
480 network number in case the address is not already configured on the interface.
482 remains running and pretends it has an infinite lease.
484 will not de-configure the interface when it exits.
487 fails to contact a DHCP server then it returns a failure instead of falling
490 Performs a DHCPv6 Information Request.
491 No address is requested or specified, but all other DHCPv6 options are allowed.
492 This is normally performed automatically when the IPv6 Router Advertises
493 that the client should perform this operation.
494 This option is only needed when
496 is not processing IPv6RA messages and the need for DHCPv6 Information Request
498 .It Fl S , Fl Fl static Ar value
499 Configures a static DHCP
505 will not attempt to obtain a lease and just use the value for the address with
506 an infinite lease time.
508 Here is an example which configures a static address, routes and DNS.
509 .D1 dhcpcd -S ip_address=192.168.0.10/24 \e
510 .D1 -S routers=192.168.0.1 \e
511 .D1 -S domain_name_servers=192.168.0.1 \e
514 You cannot presently set static DHCPv6 values.
518 .It Fl t , Fl Fl timeout Ar seconds
521 instead of the default 30.
526 to wait forever to get a lease.
529 is working on a single interface then
531 will exit when a timeout occurs, otherwise
533 will fork into the background.
534 .It Fl u , Fl Fl userclass Ar class
535 Tags the DHCPv4 message with the userclass
537 DHCP servers use this to give members of the class DHCP options other than the
538 default, without having to know things like hardware address or hostname.
539 .It Fl v , Fl Fl vendor Ar code , Ns Ar value
540 Add an encapsulated vendor option.
542 should be between 1 and 254 inclusive.
543 To add a raw vendor string, omit
548 Set the vendor option 01 with an IP address.
549 .D1 dhcpcd \-v 01,192.168.0.2 eth0
550 Set the vendor option 02 with a hex code.
551 .D1 dhcpcd \-v 02,01:02:03:04:05 eth0
552 Set the vendor option 03 with an IP address as a string.
553 .D1 dhcpcd \-v 03,\e"192.168.0.2\e" eth0
554 Set un-encapsulated vendor option to hello world.
555 .D1 dhcpcd \-v ,"hello world" eth0
557 Display both program version and copyright information.
559 then exits before doing any configuration.
561 Wait for an address to be assigned before forking to the background.
562 Does not take an argument, unlike the below option.
563 .It Fl Fl waitip Ns = Ns Op 4 | 6
564 Wait for an address to be assigned before forking to the background.
565 4 means wait for an IPv4 address to be assigned.
566 6 means wait for an IPv6 address to be assigned.
567 If no argument is given,
569 will wait for any address protocol to be assigned.
570 It is possible to wait for more than one address protocol and
572 will only fork to the background when all waiting conditions are satisfied.
573 .It Fl x , Fl Fl exit Op Ar interface
574 This will signal an existing
576 process running on the
581 is specified, then the above is applied to all interfaces in Master mode.
583 .Fl p , Fl Fl persistent
584 option to control configuration persistence on exit,
585 which is enabled by default in
588 then waits until this process has exited.
589 .It Fl y , Fl Fl reboot Ar seconds
592 seconds before moving to the discover phase if we have an old lease to use.
595 seconds before starting fallback states from the discover phase.
596 IPv4LL is started when the first
599 The default is 5 seconds.
600 A setting of 0 seconds causes
602 to skip the reboot phase and go straight into discover.
603 This has no effect on DHCPv6 other than skipping the reboot phase.
605 .Ss Restricting behaviour
607 will try to do as much as it can by default.
608 However, there are sometimes situations where you don't want the things to be
609 configured exactly how the DHCP server wants.
610 Here are some options that deal with turning these bits off.
614 is restricted to a single interface then the interface also needs to be
615 specified when asking
617 to exit using the commandline.
618 If the protocol is restricted as well then the protocol needs to be included
619 with the exit instruction.
620 .Bl -tag -width indent
621 .It Fl 1 , Fl Fl oneshot
622 Exit after configuring an interface.
625 option to specify which protocol(s) to configure before exiting.
626 .It Fl 4 , Fl Fl ipv4only
628 .It Fl 6 , Fl Fl ipv6only
630 .It Fl A , Fl Fl noarp
631 Don't request or claim the address by ARP.
632 This also disables IPv4LL.
633 .It Fl B , Fl Fl nobackground
634 Don't run in the background when we acquire a lease.
635 This is mainly useful for running under the control of another process, such
636 as a debugger or a network manager.
637 .It Fl C , Fl Fl nohook Ar script
638 Don't run this hook script.
639 Matches full name, or prefixed with 2 numbers optionally ending with
644 from touching your DNS settings you would do:-
645 .D1 dhcpcd -C resolv.conf eth0
646 .It Fl G , Fl Fl nogateway
647 Don't set any default routes.
648 .It Fl H , Fl Fl xidhwaddr
649 Use the last four bytes of the hardware address as the DHCP xid instead
650 of a randomly generated number.
651 .It Fl J , Fl Fl broadcast
652 Instructs the DHCP server to broadcast replies back to the client.
653 Normally this is only set for non-Ethernet interfaces,
654 such as FireWire and InfiniBand.
657 will set this automatically.
658 .It Fl K , Fl Fl nolink
659 Don't receive link messages for carrier status.
660 You should only have to use this with buggy device drivers or running
662 through a network manager.
663 .It Fl L , Fl Fl noipv4ll
664 Don't use IPv4LL (aka APIPA, aka Bonjour, aka ZeroConf).
665 .It Fl O , Fl Fl nooption Ar option
668 from the DHCP message before processing.
669 .It Fl P , Fl Fl printpidfile
673 will use based on commmand-line arguments to stdout.
674 .It Fl Q , Fl Fl require Ar option
677 to be present in all DHCP messages, otherwise the message is ignored.
680 only responds to DHCP servers and not BOOTP servers, you can
682 .Ar dhcp_message_type .
683 .It Fl q , Fl Fl quiet
686 on the command line, only warnings and errors will be displayed.
687 If this option is used another time then all console output is disabled.
688 These messages are still logged via
690 .It Fl T , Fl Fl test
691 On receipt of DHCP messages just call
693 with the reason of TEST which echos the DHCP variables found in the message
695 The interface configuration isn't touched and neither are any configuration
699 option is not sent in TEST mode so that the server does not lease an address.
700 To test INFORM the interface needs to be configured with the desired address
703 .It Fl U , Fl Fl dumplease Op Ar interface
704 Dumps the current lease for the
709 is given then all interfaces are dumped.
714 flags to specify an address family.
715 If a lease is piped in via standard input then that is dumped.
716 In this case, specifying an address family is mandatory.
717 .It Fl V , Fl Fl variables
718 Display a list of option codes, the associated variable and encoding for use in
719 .Xr dhcpcd-run-hooks 8 .
720 Variables are prefixed with new_ and old_ unless the option number is -.
721 Variables without an option are part of the DHCP message and cannot be
723 .It Fl W , Fl Fl whitelist Ar address Ns Op /cidr
724 Only accept packets from
725 .Ar address Ns Op /cidr .
726 .Fl X , Fl Fl blacklist
728 .Fl W , Fl Fl whitelist
730 .It Fl X , Fl Fl blacklist Ar address Ns Op Ar /cidr
731 Ignore all packets from
732 .Ar address Ns Op Ar /cidr .
733 .It Fl Z , Fl Fl denyinterfaces Ar pattern
734 When discovering interfaces, the interface name must not match
736 which is a space or comma separated list of patterns passed to
738 .It Fl z , Fl Fl allowinterfaces Ar pattern
739 When discovering interfaces, the interface name must match
741 which is a space or comma separated list of patterns passed to
743 If the same interface is matched in
744 .Fl Z , Fl Fl denyinterfaces
745 then it is still denied.
747 Don't start any interfaces other than those specified on the command line.
750 to be started in Master mode and then wait for subsequent
752 commands to start each interface as required.
756 to configure the system.
757 This is the default behaviour and sets
758 .Ev if_configured=true .
759 .It Fl Fl noconfigure
761 will not configure the system at all.
762 This is only of use if the
766 calls at each network event configures the system instead.
767 This is different from
769 mode in that it's not one shot and the only change to the environment is the
771 .Ev if_configured=false .
777 .Sh 3RDPARTY LINK MANAGEMENT
778 Some interfaces require configuration by 3rd parties, such as PPP or VPN.
779 When an interface configuration in
781 is marked as STATIC or INFORM without an address then
783 will monitor the interface until an address is added or removed from it and
785 For point to point interfaces (like PPP), a default route to its
786 destination is automatically added to the configuration.
787 If the point to point interface is configured for INFORM, then
789 unicasts INFORM to the destination, otherwise it defaults to STATIC.
792 requires a Berkley Packet Filter, or BPF device on BSD based systems and a
793 Linux Socket Filter, or LPF device on Linux based systems for all IPv4
798 to a single interface and optionally address family via the command-line
799 then all further calls to
801 to rebind, reconfigure or exit need to include the same restrictive flags
804 knows which process to signal.
806 Some DHCP servers implement ClientID filtering.
809 is replacing an in-use DHCP client then you might need to adjust the clientid
813 If using a DUID in place of the ClientID, edit
818 .It Pa @SYSCONFDIR@/dhcpcd.conf
819 Configuration file for dhcpcd.
820 If you always use the same options, put them here.
822 Bourne shell script that is run to configure or de-configure an interface.
823 .It Pa @LIBDIR@/dhcpcd/dev
828 A directory containing bourne shell scripts that are run by the above script.
829 Each script can be disabled by using the
831 option described above.
833 Text file that holds the DUID used to identify the host.
834 .It Pa @DBDIR@/secret
835 Text file that holds a secret key known only to the host.
836 .It Pa @DBDIR@/ Ns Ar interface Ns Ar -ssid Ns .lease
837 The actual DHCP message sent by the server.
838 We use this when reading the last
839 lease and use the file's mtime as when it was issued.
840 .It Pa @DBDIR@/ Ns Ar interface Ns Ar -ssid Ns .lease6
841 The actual DHCPv6 message sent by the server.
842 We use this when reading the last
843 lease and use the file's mtime as when it was issued.
844 .It Pa @DBDIR@/rdm_monotonic
845 Stores the monotonic counter used in the
847 field in Authentication Options.
851 running on all interfaces.
852 .It Pa @RUNDIR@/ Ns Ar interface Ns .pid
858 Control socket to the master daemon.
859 .It Pa @RUNDIR@/unpriv.sock
860 Unprivileged socket to the master daemon, only allows state retrieval.
861 .It Pa @RUNDIR@/ Ns Ar interface Ns .sock
862 Control socket to per interface daemon.
866 .Xr if_nametoindex 3 ,
869 .Xr dhcpcd-run-hooks 8 ,
872 RFC\ 951, RFC\ 1534, RFC\ 2104, RFC\ 2131, RFC\ 2132, RFC\ 2563, RFC\ 2855,
873 RFC\ 3004, RFC\ 3118, RFC\ 3203, RFC\ 3315, RFC\ 3361, RFC\ 3633, RFC\ 3396,
874 RFC\ 3397, RFC\ 3442, RFC\ 3495, RFC\ 3925, RFC\ 3927, RFC\ 4039, RFC\ 4075,
875 RFC\ 4242, RFC\ 4361, RFC\ 4390, RFC\ 4702, RFC\ 4074, RFC\ 4861, RFC\ 4833,
876 RFC\ 4941, RFC\ 5227, RFC\ 5942, RFC\ 5969, RFC\ 6106, RFC\ 6334, RFC\ 6355,
877 RFC\ 6603, RFC\ 6704, RFC\ 7217, RFC\ 7550, RFC\ 7844.
879 .An Roy Marples Aq Mt roy@marples.name
881 Please report them to
882 .Lk http://roy.marples.name/projects/dhcpcd
projects / dragonfly.git / blob