NAME¶
dhcpcd —
an RFC 2131 compliant DHCP
client
SYNOPSIS¶
| dhcpcd |
[-dknpAEGHMLNRSTY]
[-c, --script
script]
[-h, --hostname
hostname]
[-i, --classid
classid]
[-l, --leasetime
seconds]
[-m, --metric
metric]
[-r, --request
address]
[-t, --timeout
seconds]
[-u, --userclass
class]
[-F, --fqdn
FQDN] [-I,
--clientid clientid]
[-P, --pidfile
pidfile] interface |
| dhcpcd |
-k, --release
interface |
| 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 will then
write DNS information to
resolvconf(8), if available,
otherwise directly to
/etc/resolv.conf.
dhcpcd will also configure
/etc/yp.conf
and
/etc/ntpd.conf with NIS and NTP information if the DHCP
server provided them. If those file contents changed, then
dhcpcd will also attempt to restart the respective services
to notify them of the change. If the hostname is currenly blank, (null) or
localhost then
dhcpcd will set the hostname to the one
supplied by the DHCP server, or look it up in DNS if none supplied.
dhcpcd then daemonises and waits for the lease renewal time
to lapse. Then it attempts to renew its lease and reconfigure if the new lease
changes.
Local Link configuration¶
If
dhcpcd failed to obtain a lease, it will probe for a valid
IPv4LL address (aka Zeroconf, aka APIPA). Once obtained it will probe every 10
seconds for a DHCP server to get a proper address.
Even when
dhcpcd obtains a proper lease, it will still add a
Local Link route (165.254.0.0/16) so that the host can communicate with
clients using these addresses.
When using IPv4LL,
dhcpcd will always succeed and return a 0
exit code. To disable this behaviour, you can use the
-L,
--noipv4ll option.
Hooking into DHCP events¶
dhcpcd will run /etc/dhcpcd.sh, or the script specified by the
-c,
--script option. It will set $1 to a
shell compatible file that holds various configuration settings obtained from
the DHCP server and $2 to either up, down or new depending on the state of
dhcpcd.
dhcpcd ignores the exist code of
the script.
Fine tuning¶
You can fine tune the behaviour of
dhcpcd with the following
options :-
- -d,
--debug
- Echo debug and informational messages to the console.
Subsequent debug options stop dhcpcd from
daemonising.
- -h,
--hostname hostname
- By default, dhcpcd will send the current
hostname to the DHCP server so it can register in DNS. You can use this
option to specify the hostname sent, or an empty
string to stop any hostname from being sent.
- -i,
--classid classid
- Override the DHCP vendor classid
field we send. The default is dhcpcd-<version>.
- -k,
--release
- This causes an existing dhcpcd process
running on the interface to release it's lease,
deconfigure the interface and then exit.
- -l,
--leasetime seconds
- Request a specific lease time in
seconds. By default dhcpcd does
not request any lease time and leaves the it in the hands of the DHCP
server.
- -m,
--metric metric
- Added routes will use the metric on
systems where this is supported (presently only Linux). Route metrics
allow the addition of routes to the same destination across different
interfaces, the lower the metric the more it is preferred.
- -n,
--renew
- Notifies an existing dhcpcd process
running on the interface to renew it's lease. If
dhcpcd is not running, then it starts up as normal.
- -p,
--persistent
- dhcpcd normally deconfigures the
interface and configuration when it exits.
Sometimes, this isn't desirable if for example you have root mounted over
NFS. You can use this option to stop this from happening.
- -r,
--request
[address]
- dhcpcd normally sends a DHCP Broadcast to
find servers to offer an address. dhcpcd will then
request the address used. You can use this option to skip the broadcast
step and just request an address. The downside is if
you request an address the DHCP server does not know
about or the DHCP server is not authorative, it will remain silent. In
this situation, we go back to the init state and broadcast again. If no
address is given then we use the first address
currently assigned to the interface.
- -s,
--inform [address
[/ cidr]]
- Behaves exactly like -r,
--request as above, but sends a DHCP inform instead of a
request. This requires the interface to be configured first. This does not
get a lease as such, just notifies the DHCP server of the
address we are using.
- -t,
--timeout seconds
- Timeout after seconds, instead of the
default 20. A setting of 0 seconds causes
dhcpcd to wait forever to get a lease.
- -u,
--userclass class
- Tags the DHCP message with the userclass
class. DHCP servers use this give memebers of the
class DHCP options other than the default, without having to know things
like hardware address or hostname. infinityRequests that the DHCP server
updates DNS using FQDN instead of just a hostname. Valid values for
fqdn are none, ptr and both.
dhcpcd dhcpcd itself never does any DNS updates.
- -H,
---sethostname
- Forces dhcpcd to set the hostname as
supplied by the DHCP server. Because some OS's and users prefer to have
just the hostname, or the full FQDN more -H,
---sethostname options change the behaviour. Below is
the list of possible combinations:-
- -H
- set the hostname to the full FQDN.
- -HH
- strip the domain if it matches the dns domain.
- -HHH
- strip the domain regardless.
- -HHHH
- same as -H but force hostname lookup
via DNS.
- -HHHHH
- same as above, but strip the domain if it matches the
dns domain.
- -HHHHHH
- same as above, but strip the domain regardless.
- -I,
--clientid clientid
- Send clientid as a client identifier
string. If clientid matches a hardware address
format, such as 01:00:01:02:03:04:05 then we encode it as that, otherwise
as a string. You need to specify the hardware type in the first byte.
Ethernet is 01, and the hardware address in the example is
00:01:02:03:04:05. If the clientid is a blank
string, then we disable DUID support and use a
clientid as shown above.
- -S,
--mscsr
- Microsoft have their own code for Classless Static Routes
(RFC 3442). You can use this option to request this as well as the normal
CSR. Another instace of this option only requests the Microsoft CSR to
prevent DHCP message over-running its maximum size. DHCP server
administrators should update their CSR code from the Microsoft specific
one to the RFC compliant one as the content is fully compatible.
- -P,
--pidfile filename
- Write the PID to filename instead of
/var/run/dhcpcd-interface.pid.
Restriciting behaviour¶
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 the DHCP server wants. Here are some option that
deal with turning these bits off.
- -A,
--noarp
- Don't request or claim the address by ARP.
- -G,
--nogateway
- Don't set any default routes.
- -L,
--noipv4ll
- Don't use IPv4LL at all.
- -M,
--nomtu
- Don't set the MTU of the
interface.
- -N,
--nontp
- Don't touch /etc/ntpd.conf or restart the
ntp service.
- -R,
--nodns
- Don't send DNS information to resolvconf or touch
/etc/resolv.conf.
- -T,
--test
- On receipt of discover messages, simply print the contents
of the DHCP message to the console. dhcpcd will not
configure the interface, touch any files or restart
any services.
- -Y,
--nonis
- Don't touch /etc/yp.conf or restart the
ypbind service.
NOTES¶
Because
dhcpcd supports InfiniBand, we put a Node-specific
Client Identifier in the ClientID field. This is required by RFC 4390. It's
also required for DHCP IPv6 which
dhcpcd should support one
day. However, some DHCP servers have no idea what this is and reject the
message as they do not understand type 255. This is not conformant with RFC
2132 and the server should be fixed. Also, some DHCP server configurations
require an ethernet hardware address of 6 hexacdecimal numbers in the ClientID
which is the default behaviour of most other DHCP clients. If your DHCP server
is as desribed above, you should fix the server, or if that is not an option
you can compile DUID support out of
dhcpcd or use the
-I,
--clientid
clientid option and set
clientid
to ''.
ISC dhcpd, dnsmasq, udhcpd and Microsoft DHCP server 2003 default configurations
work just fine with the default
dhcpcd configuration.
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.
FILES¶
- /etc/dhcpcd.sh
- Bourne shell script that is run when we configure or
deconfigure an interface.
- /var/lib/dhcpcd/dhcpcd.duid
- Text file that holds the DUID used to identify the
host.
- /var/lib/dhcpcd/dhcpcd-interface.info
- Bourne shell file that holds the DHCP values used in
configuring the interface. This path is passed as the first argument to
/etc/dhcpcd.sh.
SEE ALSO¶
ntp(1),
resolv.conf(5),
resolvconf(8),
yp.conf(5),
ypbind(8)
STANDARDS¶
RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3397, RFC 3442, RFC 3927,
RFC 4361, RFC 4390, RFC 4702.
AUTHORS¶
Roy Marples ⟨roy@marples.name⟩
BUGS¶
Please report them to
http://bugs.marples.name
