-.TH DHCPCD 8 "18 Jul 2007" "dhcpcd 3.1"
-.SH NAME
-dhcpcd \- DHCP client daemon
-.SH SYNOPSIS
-dhcpcd
-\%[\-dknpAEGHMLNRSTY]
-\%[\-c\ script]
-\%[\-h\ hostname]
-\%[\-i\ vendorClassID]
-\%[\-l\ leasetime]
-\%[\-m\ metric]
-\%[\-r\ ipaddr]
-\%[\-s\ ipaddr[/cidr]]
-\%[\-t\ timeout]
-\%[\-u\ userClass]
-\%[\-F\ none | ptr | both ]
-\%[\-I\ clientID ]
-\%[interface]
-.SH DESCRIPTION
-.B dhcpcd
+.\" Copyright 2006-2008 Roy Marples
+.\" All rights reserved
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd Jan 17, 2008
+.Dt DHCPCD 8 SMM
+.Sh NAME
+.Nm dhcpcd
+.Nd an RFC2131 compliant DHCP client
+.Sh SYNOPSIS
+.Nm
+.Op Fl dknpAEGHMLNRSTY
+.Op Fl c , -script Ar script
+.Op Fl h , -hostname Ar hostname
+.Op Fl i , -classid Ar classid
+.Op Fl l , -leasetime Ar seconds
+.Op Fl m , -metric Ar metric
+.Op Fl r , -request Ar address
+.Op Fl t , -timeout Ar seconds
+.Op Fl u , -userclass Ar class
+.Op Fl F , -fqdn Ar FQDN
+.Op Fl I , -clientid Ar clientid
+.Ar interface
+.Nm
+.Fl k , -release
+.Ar interface
+.Nm
+.Fl x , -exit
+.Ar interface
+.Sh DESCRIPTION
+.Nm
is an implementation of the DHCP client specified in
-.B RFC 2131.
-
-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 RFC 2131.
-
-If
-.B dhcpcd
-fails to get a lease then we attempt Dynamic Configuration of IPv4
-Link-Local Addresses unless the
-.B \-L
-option is given.
-
-.SH OPTIONS
-.TP
-.BI interface
-Specifies the network interface name (eth0, eth1, etc.).
-.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.
-Subsequent debug options stop \fBdhcpcd\fR from daemonising.
-.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.
-We send the current hostname by default. To send no hostname, use -h ''.
-.TP
-.BI \-i \ vendorClassID
-Specifies the vendor class identifier string. The default is dhcpcd-<version>.
-.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 DHCP_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. If we do not receive a lease time in the
-.B DHCP_OFFER
-message then we default to 1 hour.
-.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 \-r \ ipaddr
-Sends
-.B DHCP_REQUEST
-message requesting to lease IP address ipaddr.
-The ipaddr parameter must be in the form xxx.xxx.xxx.xxx.
-If we are not given an ipaddr then we try to use the first one assigned
-to the interface if present, otherwise the last address we leased for the
-interface, otherwise we return an error.
-This effectively doubles the timeout period, as if we fail to get
-this IP address then we enter the INIT state and try to get any
-IP address.
-.TP
-.BI \-s \ ipaddr[/cidr]
-Exactly like \fB-r\fR, but sends DHCP_INFORM instead. This requires the
-interface to be configured with the ipaddr/cidr first.
-When we DHCP_INFORM, we don't request or respect any lease times.
-However, we do re-inform by the lease time specified by
-.BI \-l
-if given.
-.TP
-.BI \-t \ timeout
-Specifies (in seconds ) for how long
-.B dhcpcd
-will try to get an IP address. The default is 20 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 \-x
-Sends
-.B SIGTERM
-signal to the
-.B dhcpcd
-process associated with the specified interface if one is currently running. If
-.B dhcpcd
-receives
-.B SIGTERM
-it will stop running, de-configure the interface and exit.
-(see also
-.B -k
+.Rs
+.%T "RFC 2131"
+.Re
+.Nm
+gets the host information
+.Po
+IP address, routes, etc
+.Pc
+from a DHCP server and configures the network
+.Ar interface
+of the
+machine on which it is running.
+.Nm
+will then write DNS information to
+.Xr resolvconf 8 ,
+if available, otherwise directly to
+.Pa /etc/resolv.conf .
+.Nm
+will also configure
+.Pa /etc/yp.conf
and
-.B -p
-)
-.TP
-.BI \-A
-Don't do an
-.B ARP
-check on the IP address.
-.TP
-.BI \-E
-Will read
-.I %%INFODIR%%/dhcpcd-<interface>.info
-file and use last known good lease if
-.B dhcpcd
-is unable to reach the DHCP server and the lease has not expired.
-This puts \fBdhcpcd\fR into the BOUND or REBINDING state depending on
-how long the lease has until expiry.
-.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 %%INFODIR%%/dhcpcd-<interface>.info
-file.
-.TP
-.BI \-G
-Prevents
-.B dhcpcd
-from installing default routes provided by DHCP server.
-.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. If no hostname is returned by the DHCP server then we attempt
-to lookup the hostname via DNS.
-More -H's control what we do with the FQDN returned by DNS.
-.IP
-.BI \-H
-set hostname to the full FQDN
-.br
-.BI \-HH
-strip the domain if it matches a given domain in our DHCP message
-.br
-.BI \-HHH
-strip the domain regardless
-.br
-.BI \-HHHH
-force hostname lookup even if given a hostname in our DHCP message
-.br
-.BI \-HHHHH
-same as above, but strip the domain if it matches
-.br
-.BI \-HHHHHH
-same as above, but strip the domain regardless
-.TP
-.BI \-I \ clientID
-Specifies the client identifier string. If not specified then
-.B dhcpcd
-will attempt to create a client identifier according to \fBRFC 4361\fR
-and store the DUID part in
-.I %%INFODIR%%/dhcpcd.duid\fR, otherwise
-.B dhcpcd
-uses the MAC address of the network interface. If \fB-I\fR is not given
-an option then we use the MAC address of the network interface.
-.TP
-.BI \-L
-Prevents dhcpcd from probing for IPV4LL addresses. IPV4LL is otherwise
-known as ZeroConf or APIPA and is \fBRFC 3927\fR.
-.TP
-.BI \-M
-Prevents
-.B dhcpcd
-from setting the \fIMTU\fR provided by the DHCP server.
-.TP
-.BI \-N
-Prevents
-.B dhcpcd
-from replacing
-.I /etc/ntp.conf
-.TP
-.BI \-R
-Prevents
-.B dhcpcd
-from replacing
-.I /etc/resolv.conf
-or using resolvconf.
-.TP
-.BI \-S
-Makes
-.B dhcpcd
-request Microsoft CSR option 249 as well as the normal CSR option 121.
-Subsquent
-.BI \-S
-options disable the requesting of the normal CSR if the dhcp message returned
-is too big.
-Ideally, DHCP servers should start responding to option 121 so
-that users don't have to deal with this mess.
-.TP
-.BI \-T
-dhcpcd sends out a DHCP_DISCOVER message and then prints the values returned to
-stdout. It does not configure the interface or touch the .info files.
-.TP
-.BI \-Y
-Prevents
-.B dhcpcd
-from replacing
-.I /etc/yp.conf
-
-.SH FILES
-.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
+.Pa /etc/ntpd.conf
+with NIS and NTP information if the DHCP server provided them.
+If those file contents changed, then
+.Nm
+will also attempt to restart the respective services to notify them of the
+change.
+If the hostname is currenly blank, (null) or localhost then
+.Nm
+will set the hostname to the one supplied by the DHCP server, or look it up
+in DNS if none supplied.
+.Nm
+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.
+.Ss Local Link configuration
+If
+.Nm
+failed to obtain a lease, it will probe for a valid IPv4LL address
+.Po
+aka Zerconf, aka APIPA
+.Pc .
+Once obtained it will probe every 10 seconds or so for a DHCP server to get a
+proper address.
+.Pp
+Even when
+.Nm
+obtains a proper lease, it will still add a Local Link route
+.Po
+165.254.0.0/16
+.Pc
+so that the host can communicate with clients using these addresses.
+.Pp
+When using IPv4LL,
+.Nm
+will always succeed and return a 0 exit code. To disable this behaviour, you
+can use the
+.Fl L , -noipv4ll
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.
-.TP
-.BI %%INFODIR%%/dhcpcd.duid
-file containing the generated DUID for dhcpcd to use.
-.TP
-.BI %%INFODIR%%/dhcpcd-<interface>.info
-file containing information provided by the DHCP server than can be used in
-shell scripts.
-.SH SEE ALSO
-.LP
-.I Dynamic Host Configuration Protocol,
-RFC 2131
-.LP
-.I DHCP Options and BOOTP Vendor Extensions,
-RFC 2132
-.LP
-.I Dynamic Configuration of IPv4 Link-Local Addresses,
-RFC 3927
-.LP
-.I DHCP FQDN Option specification,
-RFC 4702
-
-.SH BUGS
-Please report them to http://bugs.marples.name
-.PD 0
-
-.SH AUTHORS
-Roy Marples <roy@marples.name>
+.Ss Hooking into DHCP events
+.Nm
+will run @PREFIX@/etc/dhcpcd.sh, or the script specified by the
+.Fl 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
+.Nm .
+.Nm
+ignores the exist code of the script.
+.Ss Fine tuning
+You can fine tune the behaviour of
+.Nm
+with the following options :-
+.Bl -tag -width indent
+.It Fl d , -debug
+Echos debug and informational messages to the console.
+Subsequent debug options stop
+.Nm
+from daemonising.
+.It Fl h , -hostname Ar hostname
+By default,
+.Nm
+will send the current hostname to the DHCP server so it can register in DNS.
+You can use this option to specify the
+.Ar hostname
+sent, or an empty string to
+stop any
+.Ar hostname
+from being sent.
+.It Fl i , -classid Ar classid
+Override the DHCP vendor
+.Ar classid
+field we send. The default is
+dhcpcd-<version>.
+.It Fl k , -release
+This causes an existing
+.Nm
+process running on the
+.Ar interface
+to release it's lease, deconfigure the
+.Ar interface
+and then exit.
+.It Fl l , -leasetime Ar seconds
+Request a specific lease time in
+.Ar seconds .
+By default
+.Nm
+does not request any lease time and leaves the it in the hands of the
+DHCP server.
+.It Fl m , -metric Ar metric
+Added routes will use the
+.Ar metric
+on systems where this is supported
+.Po
+presently only Linux
+.Pc .
+Route metrics allow the addition of routes to the same destination across
+different interfaces, the lower the metric the more it is preferred.
+.It Fl n , -renew
+Notifies an existing
+.Nm
+process running on the
+.Ar interface
+to renew it's lease. If
+.Nm
+is not running, then it starts up as normal.
+.It Fl p , -persistent
+.Nm
+normally deconfigures the
+.Ar 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.
+.It Fl r , -request Op Ar address
+.Nm
+normally sends a DHCP Broadcast to find servers to offer an address.
+.Nm
+will then request the address used. You can use this option to skip the
+broadcast step and just request an
+.Ar address .
+The downside is if you request
+an
+.Ar 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
+.Ar address
+is given then we use the first address currently assigned to the
+.Ar interface .
+.It Fl s , -inform Op Ar address Op / Ar cidr
+Behaves exactly like
+.Fl 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
+.Ar address
+we are using.
+.It Fl t , -timeout Ar seconds
+Timeout after
+.Ar seconds ,
+instead of the default 20.
+A setting of 0
+.Ar seconds
+causes
+.Nm
+to wait forever to get a lease.
+.It Fl u , -userclass Ar class
+Tags the DHCP message with the userclass
+.Ar 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.
+.If Fl F , -fqdn Ar fqdn
+Requests that the DHCP server updates DNS using FQDN instead of just a
+hostname. Valid values for
+.Ar fqdn
+are none, ptr and both.
+.Nm
+dhcpcd itself never does any DNS updates.
+.It Fl H , --sethostname
+Forces
+.Nm
+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
+.Fl H , --sethostname
+options change the behaviour. Below is the list of possible combinations:-
+.Bl -tag -width indent
+.It Fl H
+set the hostname to the full FQDN.
+.It Fl HH
+strip the domain if it matches the dns domain.
+.It Fl HHH
+strip the domain regardless.
+.It Fl HHHH
+same as
+.Fl H
+but force hostname lookup via DNS.
+.It Fl HHHHH
+same as above, but strip the domain if it matches the dns domain.
+.It Fl HHHHHH
+same as above, but strip the domain regardless.
+.El
+.It Fl I , -clientid Ar clientid
+Send a
+.Ar clientid
+as a client identifier string.
+.It Fl S, -mscsr
+Microsoft have their own code for Classless Static Routes
+.Po
+RFC 3442
+.Pc .
+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.
+.El
+.Ss Restriciting behaviour
+.Nm
+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.
+.Bl -tag -width indent
+.It Fl A , -noarp
+Don't request and claim the address by ARP.
+.It Fl G , -nogateway
+Don't set any default routes.
+.It Fl L , -noipv4ll
+Don't use IPv4LL at all.
+.It Fl M , -nomtu
+Don't set the MTU of the
+.Ar interface .
+.It Fl N , -nontp
+Don't touch
+.Pa /etc/ntp.d.conf
+or restart the ntp service.
+.It Fl R , -nodns
+Don't send DNS information to resolvconf or touch
+.Pa /etc/resolv.conf .
+.It Fl T , -test
+On receipt of discover messages, simply print the contents of the DHCP
+message to the console.
+.Nm
+will not configure the
+.Ar interface ,
+touch any files or restart any services.
+.It Fl Y , -nonis
+Don't touch
+.Pa /etc/yp.conf
+or restart the ypbind service.
+.El
+.Sh NOTES
+Because
+.Nm
+supports InfiniBand, we put a Node-specific Client Identifier or DUID in the
+ClientID field. This is required by RFC 4390. It's also required for DHCP IPv6
+which
+.Nm
+should support one day. However, some DHCP servers have no idea what a DUID is
+and reject the message. Of course, RFC 2131 allowed for future use of the
+ClientID field and this is a future use. 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
+.Nm
+or use the
+.Fl I , -clientid Ar clientid
+option and set
+.Ar clientid
+to ''.
+.Pp
+ISC dhcpd, dnsmasq, udhcpd and Microsoft DHCP server 2003 default configurations
+work just fine with the default
+.Nm
+configuration.
+.Pp
+.Nm
+requires a Berkley Packet Filter, or BPF device on BSD based systems and a
+Packet Socket on Linux based systems.
+.Sh FILES
+.Bl -ohang
+.It Pa @PREFIX@/etc/dhcpcd.sh
+Bourne shell script that is run when we configure or deconfigure an interface.
+.It Pa @INFODIR@/dhcpcd.duid
+Text file that holds the DUID used to identify the host.
+.It Pa @INFODIR@/dhcpcd- Ns Ar interface Ns .info
+Bourne shell file that holds the DHCP values used in configuring the interface.
+This path is passed as the first argument to
+.Pa @PREFIX@/etc/dhcpcd.sh .
+.El
+.Sh SEE ALSO
+.Xr ntp 1 ,
+.Xr resolv.conf 5 ,
+.Xr resolvconf 8 ,
+.Xr yp.conf 5 ,
+.Xr ypbind 8
+.Sh STANDARDS
+RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3397, RFC 3442, RFC 3927,
+RFC 4361, RFC 4390, RFC 4702.
+.Sh AUTHORS
+.An "Roy Marples" Aq roy@marples.name
+.Sh BUGS
+Please report them to http://bugs.marples.name
projects / thirdparty / dhcpcd.git / commitdiff
