Dhcpcd

The dhcpcd client on a Raspberry Pi is pre-configured to allow easy and quick connection to a simple networks such as those found in homes and classrooms. Where a DHCP server is present, such as within a simple consumer router, then the client works flawlessly.

Advanced configurations

This ease of use appears to come at the expense of implementing more complex configurations. In my case, my home lab network has a local DNS server that resolves hosts in it's local namespace 'example', conditionally forwards to a subdomain 'subdomain.example', and forwards to Internet DNS servers for resolution of remote hosts.

Furthermore, as the Pi in question was to host a service, I wished to assign a static rather than dynamic IP address.

Crafting a working dhcpcd.conf file to fulfil the above was a challenge, and here is how I fixed it.

Problems encountered

  • Firstly, the documentation for dhcpcd is scant. I only came to the following fix by searching forums and trial and error.
  • Secondly, and most critically, the order in which the fields are key/value pairs are presented in the configuration file matters. They must follow the order described below in order to work properly.

If you get it wrong, as I initially did, impacts manifest variously, such as:

  • DHCP addressing applying, despite static addressing being present.
  • Static addressing applying but DNS lookups to local server fail. Local hosts cannot be resolved.
  • Local DNS lookup fails to resolve hosts in 'subdomain' despite specifying search suffix(es).

The fix

As root (or with sudo) open dhcpd.conf in your favourite text editor. Mine is nano:
nano /etc/dhcpcd.conf

Specify the the interface you wish to configure, in this example, eth0:
interface eth0
Set a static IP address and subnet mask for this interface in CIDR format:
static ip_address=192.168.0.123/24
Set the address of the default route (gateway) on your network:
static routers=192.168.0.1
Set a list of domain suffixes to be appended to unqualified hosts when looking-up against your local DNS server, separated by a space:
static domain_search=example subdomain.example
Set the domain suffix of this host:
static domain_name=example
Set the IP address your local DNS server(s):
static domain_name_servers=192.168.0.1

Viewed all together to cut-and-paste:

interface eth0
static ip_address=192.168.0.123/24
static routers=192.168.0.1
static domain_search=example subdomain.example
static domain_name=example
static domain_name_servers=192.168.0.1

Save dhcpcd.conf (Ctrl-O in Nano) then reboot your Pi with sudo reboot now
Following reboot:

  • The correct static IP address will be allocated.
  • DNS lookups will be sent to the DNS Server(s) specified.
  • Domain search suffixes will be applied, meaning hosts in subdomains can be resolved without providing a FQDN.

I hope this saves you some time and effort!