dhcpcd is a DHCP and DHCPv6 client. It is currently the most feature-rich open source DHCP client, see the home page for the full list of features.
- 1 Installation
- 2 Running
- 3 Configuration
- 4 Hooks
- 5 Tips and tricks
- 6 Troubleshooting
- 7 See also
Thepackage is part of the group, so it is likely already installed on your system.
To start the daemon for all network interfaces, start/enable
Using the template unit is recommended; see #dhcpcd and systemd network interfaces for details.
Alternatively, to start dhcpcd manually, run the following command:
# dhcpcd interface
In all of the above, you will be assigned a dynamic IP address. To assign a static IP address, see #Static profile.
The main configuration is done in
/etc/dhcpcd.conf. See for details. Some of the frequently used options are highlighted below.
DHCP static route(s)
If you need to add a static route client-side, create a new dhcpcd hook-script in
/usr/lib/dhcpcd/dhcpcd-hooks. The example shows a new hook-script which adds a static route to a VPN subnet on
10.11.12.0/24 via a gateway machine at
ip route add 10.11.12.0/24 via 192.168.192.5
40 prefix means that it is the final hook-script to run when dhcpcd starts.
DHCP Client Identifier
The DHCP client may be uniquely identified in different ways by the server:
- hostname (or the hostname value sent by the client),
- MAC address of the network interface controller through which the connection is being made, linked to this is the third,
- Identity Association ID (IAID), which is an abstraction layer to differentiate different use-cases and/or interfaces on a single host,
- DHCP Unique Identifier (DUID).
For a further description, see RFC 3315.
It depends on the DHCP-server configuration which options are optional or required to request a DHCP IP lease.
If the dhcpcd default configuration fails to obtain an IP, the following options are available to use in
hostnamesends the hostname set in
clientidsends the MAC address as identifier
iaid <interface>derives the IAID to use for DHCP discovery. It has to be used in an interface block (started by
interface <interface>, see ), but more frequently the next option is used:
duidtriggers using a combination of DUID and IAID as identifier.
The DUID value is set in
/etc/dhcpcd.duid. For efficient DHCP lease operation it is important that it is unique for the system and applies to all network interfaces alike, while the IAID represents an identifier for each of the systems' interfaces (see RFC 4361).
Care must be taken on a network running Dynamic DNS to ensure that all three IDs are unique. If duplicate DUID values are presented to the DNS server, e.g. in the case where a virtual machine has been cloned and the hostname and MAC have been made unique but the DUID has not been changed, then the result will be that as each client with the duplicated DUID requests a lease the server will remove the predecessor from the DNS record.
Configure a static profile for dhcpcd in
/etc/dhcpcd.conf, for example:
interface eth0 static ip_address=192.168.0.10/24 static routers=192.168.0.1 static domain_name_servers=192.168.0.1 188.8.131.52
More complicated configurations are possible, for example combining with the
arping option. See for details.
It is possible to configure a static profile within dhcpcd and fall back to it when DHCP lease fails. This is useful particularly for headless machines such as Raspberry Pi, where the static profile can be used as "recovery" profile to ensure that it is always possible to connect to the machine.
The following example configures a
static_eth0 profile with
192.168.1.23 as IP address,
192.168.1.1 as gateway and name server, and makes this profile fallback for interface
# define static profile profile static_eth0 static ip_address=192.168.1.23/24 static routers=192.168.1.1 static domain_name_servers=192.168.1.1 # fallback to static profile on eth0 interface eth0 fallback static_eth0
dhcpcd executes all scripts found in
/usr/lib/dhcpcd/dhcpcd-hooks/ in a lexical order. See [dead link 2017-06-04] and for details.
- Each script can be disabled using the
envoption can be used to set an environment variable for all hooks. For example, you can force the hostname hook to always set the hostname with
Enable this hook by creating a symbolic link (to ensure that always the current version is used, even after package updates):
# ln -s /usr/share/dhcpcd/hooks/10-wpa_supplicant /usr/lib/dhcpcd/dhcpcd-hooks/
10-wpa_supplicant hook, if enabled, automatically launches WPA supplicant on wireless interfaces. It is started only if:
- no wpa_supplicant process is already listening on that interface.
- a wpa_supplicant configuration file exists. dhcpcd checks
/etc/wpa_supplicant/wpa_supplicant-interface.conf /etc/wpa_supplicant/wpa_supplicant.conf /etc/wpa_supplicant-interface.conf /etc/wpa_supplicant.conf
by default, in that order, but a custom path can be set by adding
env wpa_supplicant_conf=configuration_file_path into
If you manage wireless connections with wpa_supplicant itself, the hook may create unwanted connection events. For example, if you stop wpa_supplicant the hook may bring the interface up again. Also, if you use netctl-auto[broken link: invalid section], wpa_supplicant is started automatically with
/run/network/wpa_supplicant_interface.conf for config, so starting it again from the hook is unnecessary and may result in boot-time parse errors of the
/etc/wpa_supplicant/wpa_supplicant.conf file, which only contains dummy values in the default packaged version.
To disable the hook, add
nohook wpa_supplicant to
Tips and tricks
Speed up DHCP by disabling ARP probing
dhcpcd contains an implementation of a recommendation of the DHCP standard (RFC2131 section 2.2) to check via ARP if the assigned IP address is really not taken. This seems mostly useless in home networks, so you can save about 5 seconds on every connect by adding the following line to
This is equivalent to passing
dhcpcd, and disables the described ARP probing, speeding up connections to networks with DHCP.
Remove old DHCP lease
interface is the name of the interface on which you have a lease, contains the actual DHCP lease reply sent by the DHCP server. It is used to determine the last lease from the server, and its
mtime attribute is used to determine when it was issued. This last lease information is then used to request the same IP address previously held on a network, if it is available. If you do not want that, simply delete this file.
If the DHCP server still assigns the same IP address, this may happen because it is configured to keep the assignment stable and recognizes the requesting DHCP client id or DUID (see #DHCP Client Identifier). You can test it by stopping dhcpcd and removing or renaming
/etc/dhcpcd.duid. dhcpcd will generate a new one on next run.
Keep in mind that the DUID is intended as persistent machine identifier across reboots and interfaces. If you are transferring the system to new computer, preserving this file should make it appear as old one.
Different IPs when multi-booting
If you are dualbooting Arch and OS X or Windows and want each to receive different IP addresses, you can exert control about the IPs leased by specifying a different DUID in each operating system installation.
In Windows (post XP) the DUID should be stored in the
On OS X it is directly accessible in
Network\adapter\dhcp preferences panel.
If you are using a dnsmasq DHCP server, the different DUIDs can be used in appropriate
dhcp-host= rules in its configuration.
If you are on a network with DHCPv4 that filters Client IDs based on MAC addresses, you may need to change the following line:
# Use the same DUID + IAID as set in DHCPv6 for DHCPv4 Client ID as per RFC4361. duid
# Use the hardware address of the interface for the Client ID (DHCPv4). clientid
Check DHCP problem by releasing IP first
A problem may occur when DHCP gets a wrong IP assignment, such as when two routers are tied together through a VPN. The router that is connected through the VPN may be assigning IP address. To fix it, as root, release the IP address:
# dhcpcd -k
Then request a new one:
You may have to run those two commands many times.
Problems with noncompliant routers
For some (noncompliant) routers, you will not be able to connect properly unless you comment the line
/etc/dhcpcd.conf. This should not cause issues unless you have multiple DHCP servers on your network (not typical); see this page for more information.
dhcpcd and systemd network interfaces
dhcpcd.service can be enabled without specifying an interface. This may, however, create a race condition at boot with systemd-udevd trying to apply a predictable network interface name:
error changing net interface name wlan0 to wlp4s0: Device or resource busy"
To avoid it, enable dhcpcd per interface it should bind to as described in #Running. The downside of the template unit is, however, that it does not support hot-plugging of a wired connection and will fail if the network cable is not connected. To work-around the failure, see #Timeout delay.
If dhcpcd operates on a single interface and fails to obtain a lease after 30 seconds (for example when the server is not ready or the cable not plugged), it will exit with an error.
To have dhcpcd wait indefinitely for one-time, set the
timeout option to
[Service] ExecStart= ExecStart=/usr/bin/dhcpcd -w -q -t 0 %I
To have it wait indefinetely, let the unit restart after it exited:
After making changes, reload the configuration.