DHCPCD(8)System Manager's ManualDHCPCD(8)
NAME
dhcpcd — a DHCP client
SYNOPSIS
dhcpcd [-146ABbDdEGgHJKLMNPpqTV] [-C-,-nohook hook] [-c-,-script script] [-e-,-env value] [-F-,-fqdn FQDN] [-f-,-config file] [-h-,-hostname hostname] [-I-,-clientid clientid] [-i-,-vendorclassid vendorclassid] [-j-,-logfile logfile] [-l-,-leasetime seconds] [-m-,-metric metric] [-O-,-nooption option] [-o-,-option option] [-Q-,-require option] [-r-,-request address] [-S-,-static value] [-s-,-inform address [/cidr [/broadcast_address]]] [-inform6] [-t-,-timeout seconds] [-u-,-userclass class] [-v-,-vendor code,]value] [-W-,-whitelist address [/cidr]] [-w] [-waitip-=[4 | [6] [-y-,-reboot seconds] [-X-,-blacklist address [/cidr]] [-Z-,-denyinterfaces pattern] [-z-,-allowinterfaces pattern] [-inactive] [interface] ...]
dhcpcd -n, --rebind [interface]
dhcpcd -k, --release [interface]
dhcpcd -U, --dumplease interface
dhcpcd -version
dhcpcd -x, --exit [interface]
DESCRIPTION
dhcpcd is an implementation of the DHCP client specified in RFC 2131 . dhcpcd gets the host information (IP address, routes, etc) from a DHCP server and configures the network interface of the machine on which it is running. dhcpcd then runs the configuration script which writes DNS information to resolvconf(8)
, if available, otherwise directly to /etc/resolv.conf. If the hostname is currently blank, (null) or localhost, or force_hostname is YES or TRUE or 1 then dhcpcd sets the hostname to the one supplied by the DHCP server. dhcpcd then daemonises and waits for the lease renewal time to lapse. It will then attempt to renew its lease and reconfigure if the new lease changes when the lease begins to expire or the DHCP server sends a message to renew early.
If any interface reports a working carrier then dhcpcd will try and obtain a lease before forking to the background, otherwise it will fork right away. This behaviour can be modified with the -b, --background and -w, --waitip options.
dhcpcd is also an implementation of the BOOTP client specified in RFC 951 .
dhcpcd is also an implementation of the IPv6 Router Solicitor as specified in RFC 4861 and RFC 6106 .
dhcpcd is also an implementation of the IPv6 Privacy Extensions to AutoConf as specified in RFC 4941 . This feature needs to be enabled in the kernel and dhcpcd will start using it.
dhcpcd is also an implementation of the DHCPv6 client as specified in RFC 3315 . By default, dhcpcd only starts DHCPv6 when instructed to do so by an IPV6 Router Advertisement. If no Identity Association is configured, then a Non-temporary Address is requested.
If dhcpcd failed to obtain a lease, it probes for a valid IPv4LL address (aka ZeroConf, aka APIPA). Once obtained it restarts the process of looking for a DHCP server to get a proper address. When using IPv4LL, dhcpcd nearly always succeeds and returns an exit code of 0. In the rare case it fails, it normally means that there is a reverse ARP proxy installed which always defeats IPv4LL probing. To disable this behaviour, you can use the -L, --noipv4ll option. If a list of interfaces are given on the command line, then dhcpcd only works with those interfaces, otherwise dhcpcd discovers available Ethernet interfaces that can be configured. When dhcpcd not limited to one interface on the command line, it is running in Master mode. The dhcpcd-ui project expects dhcpcd to be running this way. If a single interface is given then dhcpcd only works for that interface and runs as a separate instance to other dhcpcd processes. -w, --waitip option is enabled in this instance to maintain compatibility with older versions. Using a single interface also affects the -k, -N, -n and -x options, where the same interface will need to be specified, as a lack of an interface will imply Master mode which this is not. To force starting in Master mode with only one interface, the -M, --master option can be used. Interfaces are preferred by carrier, DHCP lease/IPv4LL and then lowest metric. For systems that support route metrics, each route will be tagged with the metric, otherwise dhcpcd changes the routes to use the interface with the same route and the lowest metric. See options below for controlling which interfaces we allow and deny through the use of patterns. Non-ethernet interfaces and some virtual ethernet interfaces such as TAP and bridge are ignored by default, as is the FireWire interface. To work with these devices they either need to be specified on the command line, be listed in -allowinterfaces or have an interface directive in /etc/dhcpcd.conf. dhcpcd runs /libexec/dhcpcd-run-hooks, or the script specified by the -c, --script option. This script runs each script found in /libexec/dhcpcd-hooks in a lexical order. The default installation supplies the scripts 01-test, 02-dump, 20-resolv.conf and 30-hostname. You can disable each script by using the -C, --nohook option. See More scripts are supplied in /usr/share/examples/dhcpcd/hooks and need to be copied to /libexec/dhcpcd-hooks if you intend to use them. For example, you could install 29-lookup-hostname so that dhcpcd can lookup the hostname of the IP address in DNS if no hostname is given by the lease and one is not already set. You can fine-tune the behaviour of dhcpcd with the following options: dhcpcd will try to do as much as it can by default. However, there are sometimes situations where you don't want the things to be configured exactly how the DHCP server wants. Here are some options that deal with turning these bits off. Note that when dhcpcd is restricted to a single interface then the interface also needs to be specified when asking dhcpcd to exit using the commandline. If the protocol is restricted as well then the protocol needs to be included with the exit instruction.Local Link configuration
Multiple interfaces
Hooking into events
dhcpcd-run-hooks(8)
for details on how these scripts work. dhcpcd currently ignores the exit code of the script.Fine tuning
dhcpcd-run-hooks(8)
. For example, you can force the hostname hook to always set the hostname with -e force_hostname=YES.dhcpcd-run-hooks(8)
for each interface. This is useful so that a 3rd party such as PPP or VPN can change the routing table and / or DNS, etc and then instruct dhcpcd to put things back afterwards. dhcpcd does not read a new configuration when this happens - you should rebind if you need that functionality.syslog(3)
. The logfile is reopened when dhcpcd receives the SIGUSR2 signal.if_nametoindex(3)
. An extra 100 will be added for wireless interfaces.dhcpcd.conf(5)
. dhcpcd then waits until this process has exited.Restricting behaviour
dhcpcd-run-hooks(8)
. Variables are prefixed with new_ and old_ unless the option number is -. Variables without an option are part of the DHCP message and cannot be directly requested.fnmatch(3)
.fnmatch(3)
. If the same interface is matched in -Z, --denyinterfaces then it is still denied.
3RDPARTY LINK MANAGEMENT
Some interfaces require configuration by 3rd parties, such as PPP or VPN. When an interface configuration in dhcpcd is marked as STATIC or INFORM without an address then dhcpcd will monitor the interface until an address is added or removed from it and act accordingly. For point to point interfaces (like PPP), a default route to its destination is automatically added to the configuration. If the point to point interface is configured for INFORM, then dhcpcd unicasts INFORM to the destination, otherwise it defaults to STATIC.
NOTES
dhcpcd requires a Berkley Packet Filter, or BPF device on BSD based systems and a Linux Socket Filter, or LPF device on Linux based systems for all IPv4 configuration.
If restricting dhcpcd to a single interface and optionally address family via the command-line then all further calls to dhcpcd to rebind, reconfigure or exit need to include the same restrictive flags so that dhcpcd knows which process to signal.
Some DHCP servers implement ClientID filtering. If dhcpcd is replacing an in-use DHCP client then you might need to adjust the clientid option dhcpcd sends to match. If using a DUID in place of the ClientID, edit /var/db/dhcpcd/duid accordingly.
FILES
XXX [ERROR!!!] 5 .Bl UNSUPPORTED
Configuration file for dhcpcd. If you always use the same options, put them here. Bourne shell script that is run to configure or de-configure an interface. Linux /devmanagement modules. A directory containing bourne shell scripts that are run by the above script. Each script can be disabled by using the -C, --nohookoption described above. Text file that holds the DUID used to identify the host. Text file that holds a secret key known only to the host. The actual DHCP message sent by the server. We use this when reading the last lease and use the file's mtime as when it was issued. The actual DHCPv6 message sent by the server. We use this when reading the last lease and use the file's mtime as when it was issued. Stores the monotonic counter used in the replayfield in Authentication Options. Stores the PID of dhcpcdrunning on all interfaces. Stores the PID of dhcpcdrunning on the interface. Control socket to the master daemon. Unprivileged socket to the master daemon, only allows state retrieval. Control socket to per interface daemon.
SEE ALSO
fnmatch(3)
, if_nametoindex(3)
, dhcpcd.conf(5)
, resolv.conf(5)
, dhcpcd-run-hooks(8)
, resolvconf(8)
STANDARDS
RFC\ 951, RFC\ 1534, RFC\ 2104, RFC\ 2131, RFC\ 2132, RFC\ 2563, RFC\ 2855, RFC\ 3004, RFC\ 3118, RFC\ 3203, RFC\ 3315, RFC\ 3361, RFC\ 3633, RFC\ 3396, RFC\ 3397, RFC\ 3442, RFC\ 3495, RFC\ 3925, RFC\ 3927, RFC\ 4039, RFC\ 4075, RFC\ 4242, RFC\ 4361, RFC\ 4390, RFC\ 4702, RFC\ 4074, RFC\ 4861, RFC\ 4833, RFC\ 4941, RFC\ 5227, RFC\ 5942, RFC\ 5969, RFC\ 6106, RFC\ 6334, RFC\ 6355, RFC\ 6603, RFC\ 6704, RFC\ 7217, RFC\ 7550.
AUTHORS
Roy Marples <roy@marples.name>
BUGS
Please report them to http://roy.marples.name/projects/dhcpcd
NetBSDOctober 9, 2019NetBSD