.\" $Id$
.\"
.TH dhcpcd 8 "15 August 2006" "dhcpcd 3.0"

.SH NAME
dhcpcd \- DHCP client daemon

.SH SYNOPSIS
.in +.5i
.ti -.5i
dhcpcd
\%[\-adknpGHNRY]
\%[\-c\ script]
\%[\-h\ hostname]
\%[\-i\ vendorClassID]
\%[\-l\ leasetime]
\%[\-m\ metric]
\%[\-s\ ipaddr]
\%[\-t\ timeout]
\%[\-u\ userClass]
\%[\-F\ none | ptr | both]
\%[\-I\ clientID]
\%[interface]
.in -.5i
.SH DESCRIPTION
.B dhcpcd
is an implementation of the DHCP client specified in
.B RFC2131.

It gets the host information (IP address, netmask, broadcast address,
etc.) from a DHCP server and configures the network interface of the
machine on which it is running. It also tries to renew the lease time
according to
.B RFC2131.

.SH OPTIONS
.TP
.BI interface
Specifies the network interface name (eth0, eth1, etc.).
.TP
.BI \-a
Do an
.B ARP
check on the IP address give to us by the DHCP server. We may need to do this
if a client on the same network segment has the same IP address, however we do
not do this by default as most DHCP servers test the IP briefly with an ICMP
Echo request before assigning the IP address.
.TP
.BI \-c \ script
.B dhcpcd
will try to execute
.I script
instead of the default script
.I /etc/dhcpcd.sh
every time it configures or brings down the interface. See the
description of
.I dhcpcd.sh
script in
.B FILES
section below.
.TP
.BI \-d
Echos debugging and information messages to the console.
.TP
.BI \-h \ hostname
specifies a string used for the hostname option field when
.B dhcpcd
sends DHCP messages. Some DHCP servers, notably those used by
@Home Networks, require the hostname option
field containing a specific string in the DHCP messages from clients.
When combined with the -F switch, specifies the string used for the
FQDN option field instead of the hostname option field.
.TP
.BI \-i \ vendorClassID
Specifies the vendor class identifier string.
.B dhcpcd
uses the default vendor class identifier string (system name, system release,
and machine type) if it is not specified.
.TP
.BI \-k
Sends
.B SIGHUP
signal to the
.B dhcpcd
process associated with the specified interface if one is currently running. If
.B dhcpcd
receives
.B SIGHUP
it will send
.B DCHP_RELEASE
message to the server and destroy dhcpcd cache. In a case
.B dhcpcd
receives
.B SIGTERM
which is normally used by
.B shutdown(8)
when rebooting the system
.B dhcpcd
will not send
.B DHCP_RELEASE
and will not destroy cache. When system boots
.B dhcpcd
will use cache to request the same IP address
from DHCP server which was assigned before the
system went down. (see also
.B -p
)
.TP
.BI \-l \ leasetime
Specifies (in seconds) the recommended lease time to the server. (Note
that the server can override this value if it sees fit). This value is
used in the
.B DHCP_DISCOVER
message. Use -1 for an infinite lease time. We don't request a specific
lease time by default.
.TP
.BI \-m \ metric
Routes will be added with the given metric. The default is 0.
On some systems such as FreeBSD the interface is given the metric.
.TP
.BI \-n
Sends
.B SIGALRM
signal to the
.B dhcpcd
process that is currently running which
forces
.B dhcpcd
to try to renew the lease. If dhcpcd is not running, the flag
is ignored and
.B dhcpcd
follows the normal startup procedure.
.TP
.BI \-p
Stops
.B dhcpcd
from removing the interface configuration when it is terminated with the
.B SIGTERM
signal. This is useful when a host is running with an NFS-mounted root
filesystem over an interface controlled by DHCP. It should not be used
except in those circumstances, since if 
.B dhcp
is stopped it can no longer down an interface at the end of its
lease period when the lease is not renewed.
.TP
.BI \-s \ ipaddr
Sends DHCP_DISCOVER message to DHCP server requesting to lease ip address
ipaddr.
The ipaddr parameter must be in the form xxx.xxx.xxx.xxx.
.TP
.BI \-t \ timeout
Specifies (in seconds ) for how long
.B dhcpcd
will try to get an IP address. The default is 10 seconds.
.B dhcpcd
will not fork into background until it gets a valid IP address
in which case dhcpcd will return 0 to the parent process.
In a case
.B dhcpcd
times out before receiving a valid IP address from DHCP server
.B dhcpcd
will return exit code 1 to the parent process. Setting the timeout to
zero disables it: dhcp will keep trying forever to get a lease, and if
the lease is lost, it will try forever to get another.
.TP
.BI \-u \ userClass
Tags the  DHCP message with the specified user class. DHCP servers can use
these fields to send back different information instead of grouping by
fixed hardware addresses. You can specify more than one user class, but the
total length must be less than 255 characters, -1 character for each user
class.
.TP
.BI \-H
Forces
.B dhcpcd
to set hostname of the host to the hostname option supplied by DHCP server.
By default
.B dhcpcd
will NOT set hostname of the host to the hostname option
received from DHCP server unless the current hostname is blank, (none) or
localhost.
.TP
.BI \-F \ none | ptr | both
Forces
.B dhcpcd
to request the DHCP server update the DNS using the FQDN option
instead of the Hostname option. The name used by this option
is specified with the \fB-h\fP switch, which must be present. If
the \fB-h\fP switch is not present, the FQDN option is ignored.
The name should be fully qualified, although servers usually
accept a simple name.
.I both
requests that the DHCP server update both the A and PTR
records in the DNS.
.I ptr
requests that the DHCP server updates only the PTR record in
the DNS.
.I none
requests that the DHCP server perform no updates.
.B dhcpcd
does not perform any DNS update, even when the server is
requested to perform no updates.  This can be easily
implemented outside the client; all the necessary
information is recorded in the
.I /var/lib/dhcpcd/dhcpcd-<interface>.info
file.
.TP
.BI \-I \ clientID
Specifies the client identifier string.
.B dhcpcd
uses the default client identifier (MAC address of the network
interface) if it is not specified.
.TP
.BI \-N
Prevents
.B dhcpcd
from replacing existing
.I /etc/ntp.conf
file.
.TP
.BI \-R
Prevents
.B dhcpcd
from replacing existing using resolvconf or replacing
.I /etc/resolv.conf
file.
.TP
.BI \-Y
Prevents
.B dhcpcd
from replacing existing
.I /etc/yp.conf
file.
.TP
.BI \-G
Prevents
.B dhcpcd
from installing default routes provided by DHCP server.
.SH NOTES
.TP
.B dhcpcd
uses
.I LOCAL0
syslog facility for all logging. To catch
.B dhcpcd
debugging output add the following line to
.I /etc/syslog.conf
file:

local0.*     /var/log/dhcpcd.log

and then refresh syslogd daemon:

kill -1 `cat /var/run/syslogd.pid`

.SH FILES
.PD 0
.TP
.BI /var/lib/dhcpcd
Directory used for storing files information files created by
.B dhcpcd
that can be used by shell scripts.
.PD 1
.TP
.BI /etc/dhcpcd.sh
script file, which
.B dhcpcd
will try to execute whenever it configures or brings down the interface. The
path to this executable script can be changed with
.I \-c \ script 
option.
.B dhcpcd
passes 3 parameters to
.I dhcpcd.sh
script:
.TP
.I dhcpcd.sh infofile [up | down | new]
The first parameter infofile is the path to a file containing all DHCP
information we have. The second parameter value
.I up | down | new
mean the interface has been brought up with the same IP address as before ("up"), or
with the new IP address ("new"), or the interface has been brought down ("down").
.TP
.BI /etc/resolv.conf
file created by
.B dhcpcd
when the client receives DNS and domain name options.
If resolvconf is present on the system then we send the data to it instead
of overwriting resolv.conf
.TP
.BI /etc/yp.conf
file created by
.B dhcpcd
when the client receives NIS options.
.TP
.BI /etc/ntp.conf
file created by
.B dhcpcd
when the client receives NTP options.
.TP
.BI /var/run/dhcpcd-<interface>.pid
file containing the process id of
.B dhcpcd.
The word
.I <interface>
is actually replaced with the network interface name like
.I eth0
to which
.B dhcpcd
is attached.

.SH SEE ALSO
.BR dig (1),
.BR nslookup (8),
.BR nsupdate (8)
.LP
.I Dynamic Host Configuration Protocol,
RFC2132
.LP
.I DHCP Options and BOOTP Vendor Extensions,
RFC2132
.LP
.I Draft DHC FQDN Option specification,
draft-ietf-dhc-fqdn-option

.SH BUGS
Probably many.
Please report them to http://bugs.gentoo.org.
.PD 0

.SH AUTHORS
Roy Marples <uberlord@gentoo.org>