Udhcpc

This page documents the working of default DHCP client udhcpc from Busybox.

Configuration

The default DHCP client udhcpc from BusyBox gets invoked by the networking scripts /sbin/ifup and /sbin/ifdown when "dhcp" is added to the interface name in the file /etc/network/interfaces.

The default behavior of udhcpc is driven by the script /usr/share/udhcpc/default.script

Entries in /etc/network/interfaces for DHCP interfaces will drive the udhcpc command line. For example,

Contents of /etc/network/interfaces

auto eth0 iface eth0 inet dhcp hostname myhostname

will set these parameters on the command line:

udhcpc -i eth0 -x hostname:myhostname

The hostname will send the DHCP option to the server to tell the server the name of this client.

By default, the inbuilt BusyBox DHCP client udhcpc requests a static set of options from the DHCP server. If you need to extend this set, you can do so by setting some additional command line options for the DHCP client, via the udhcpc_opts in your interface configuration. The following example requests the domain-search option:

Contents of /etc/network/interfaces

... auto eth0 iface eth0 inet dhcp udhcpc_opts -O search

For a complete list of command line options for udhcpc, see this document.

The default configuration of udhcpc may be overridden by /etc/udhcpc/udhcpc.conf. Also, if this file were ever customized, e.g. for any values discussed below, whenever its parent package busybox is updated, apk will note that the file had been modified and will opt not to overwrite it but rather will place its own newly-supplied udhcpc.conf file renamed as udhcpc.conf.apk-new . Be sure to compare both files and to preserve the required changes.

udhcpc.conf accepts the following key:value pairs:

key	default value	possible values	meaning
RESOLV_CONF	/etc/resolv.conf	no ; NO ; /tmp/resolv.conf ; -	do not overwrite or alternative path for resolv.conf
NO_DNS	-	<list of iface names>	Prevent overwriting of resolv.conf on a per-interface basis
NO_GATEWAY	-	<list of iface names>	List of interfaces where DHCP routes are ignored
IF_METRIC	-	<metric value>	offset value for routing metric
IF_PEER_DNS	yes	<anything but yes>	please use RESOLV_CONF or NO_DNS instead

Example /etc/udhcpc/udhcpc.conf:

Contents of /etc/udhcpc/udhcpc.conf

RESOLV_CONF="no" # Prevents overwriting of /etc/resolv.conf

Please see /usr/share/udhcpc/default.script for details on how the values are used.

Custom scripts can be added as /etc/udhcpc/pre-* and /etc/udhcpc/post-* to be run before/after deconfig/renew/bound DHCP events. The custom scripts must be set as executable by root, using chmod 744. Refer below for a sample custom script.

As another example for fine tuning, consider uncommenting and amending the #NO_DNS="eth1 wlan1" line there with the relevant interfaces, described so as to "Prevent overwriting of resolv.conf on a per-interface basis".

Troubleshooting

Todo: The section below needs testing and confirmation.

Change MTU for ADSL

As an example, /etc/udhcpc/post-bound/mtu could contain, to change the interface MTU from the default (1500) to 1492, which is useful if on ADSL that uses PPPoE (which uses 8 bytes for its own header):

r=$(/sbin/ip route | grep ^default | head -n 1) # Needs {{pkg|iproute2}} package, rather than busybox's "ip", to change mtu /sbin/ip route replace $r mtu 1492

I needed to restart my firewall (which replaces the iptables script from Alpine) when the client binds to a new IP, so I added the following line in the function bound(), right after 'resolvconf':

# rc-service iptables reload

The reload drops all firewall rules, re-acquires the Internal and external IPs, and re-writes the rules. I'm sure there is a better way.

'can't rename '/etc/resolv.conf.****': Operation not permitted'

Such notifications at bootup or when (re-)starting the networking service from a shell refer to a udhcpc script that attempts to overwrite /etc/resolv.conf with a transitory resolv.conf.**** file that it had created, but which fails due to the original file having been made immutable e.g. with doas chattr +i /etc/resolv.conf. The four digits in the .**** suffix refer to the pid number of the /usr/share/udhcpc/default.script, as in the following case:

$ doas rc-service networking restart
 * Starting networking ...
 *   lo ...                                                                [ ok ]
 *   eth0 ...
udhcpc: started, v1.37.0
udhcpc: broadcasting discover
udhcpc: broadcasting discover
udhcpc: broadcasting select for 192.168.1.2, server 192.168.1.1
udhcpc: lease of 192.168.1.2 obtained from 192.168.1.1, lease time 86400
mv: can't rename '/etc/resolv.conf.4175': Operation not permitted

Immutability was likely set manually by an administrator seeking to prevent one or more preferred DNS nameserver(s) from being overwritten in that file.

To preempt such reports, consider whether the use of immutability for /etc/resolv.conf is necessary, while conserving its contents: although the issue in itself is innocuous albeit leading udhcpc to leave behind such transitory files, it may also obstruct legitimate future updates of its stock file design locally. To forego such concerns for standard installations, instead of employing immutability, consider configuring the /etc/udhcpc/udhcpc.conf file, supplied since Alpine Linux v3.19, by setting RESOLV_CONF="no" so that udhcpc will not overwrite the file, or by setting which specific interfaces are not to overwrite it e.g. NO_DNS="eth1 wlan1". Immutability could then be removed with doas chattr -i /etc/resolv.conf .

Since /etc/resolv.conf.**** files accumulate unnecessarily is set each time that the udhcpc script is run, such files may be deleted, as in the following instruction. Be sure to add the full stop character ('.') before the asterisk ('*') so as to not delete the required /etc/resolv.conf file:

doas rm /etc/resolv.conf.*

See also

• Main Networking page
• Busybox udhcpc Readme