b2f096aeb9
- support for link state notification (e.g. renew lease after carrier returned) - support to start go into background immediately - don't cleanup interface state. dhcpcd will leave the interface in the same state as before if the lease uses separate addresses. -p still stops it from removing the configured address on exit - various smaller bugfixes, optimisations and cleanups
396 lines
11 KiB
Groff
396 lines
11 KiB
Groff
.\" 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 Jul 18, 2008
|
|
.Dt DHCPCD 8 SMM
|
|
.Sh NAME
|
|
.Nm dhcpcd
|
|
.Nd an RFC 2131 compliant DHCP client
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl bdknpqABDEGKLSTV
|
|
.Op Fl c , -script Ar script
|
|
.Op Fl f , -config Ar file
|
|
.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 o , -option Ar option
|
|
.Op Fl r , -request Ar address
|
|
.Op Fl s , -inform Ar address Ns Op Ar /cidr
|
|
.Op Fl t , -timeout Ar seconds
|
|
.Op Fl u , -userclass Ar class
|
|
.Op Fl v , -vendor Ar code , Ar value
|
|
.Op Fl C , -nohook Ar hook
|
|
.Op Fl F , -fqdn Ar FQDN
|
|
.Op Fl I , -clientid Ar clientid
|
|
.Op Fl O , -nooption Ar option
|
|
.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
|
|
.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 .
|
|
If the hostname is currenly blank, (null) or localhost then
|
|
.Nm
|
|
will set the hostname to the one supplied by the DHCP server.
|
|
.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 Zeroconf, aka APIPA
|
|
.Pc .
|
|
Once obtained it will restart the process of looking for a DHCP server to get a
|
|
proper address.
|
|
.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.
|
|
.Ss Hooking into DHCP events
|
|
.Nm
|
|
will run
|
|
.Pa @SCRIPT@ ,
|
|
or the script specified by the
|
|
.Fl c , -script
|
|
option.
|
|
This script will run each script found in
|
|
.Pa @HOOKDIR@
|
|
in a lexical order.
|
|
The default installation supplies the scripts
|
|
.Pa 01-test ,
|
|
.Pa 10-mtu ,
|
|
.Pa 20-resolv.conf
|
|
and
|
|
.Pa 30-hostname .
|
|
You can disable each script by using the
|
|
.Fl C , -nohook
|
|
option.
|
|
See
|
|
.Xr dhcpcd-run-hooks 8
|
|
for details on how these scripts work.
|
|
.Nm
|
|
currently ignores the exit 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 b , -background
|
|
Background immediately.
|
|
This is useful for startup scripts which don't disable link messages for
|
|
carrier status.
|
|
.It Fl c , -script Ar script
|
|
Use this
|
|
.Ar script
|
|
instead of the default
|
|
.Pa @SCRIPT@ .
|
|
.It Fl d , -debug
|
|
Echo debug and informational messages to the console.
|
|
Subsequent debug options stop
|
|
.Nm
|
|
from daemonising.
|
|
.It Fl f , -config Ar file
|
|
Specify a config to load instead of
|
|
.Pa @SYSCONFDIR@/dhcpcd.conf .
|
|
.Nm
|
|
always processes the config file before any command line options.
|
|
.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
|
|
.Ar classid
|
|
field sent. The default is
|
|
dhcpcd <version>.
|
|
If not set then none is sent.
|
|
.It Fl k , -release
|
|
This causes an existing
|
|
.Nm
|
|
process running on the
|
|
.Ar interface
|
|
to release its 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 o , -option Ar option
|
|
Request the DHCP
|
|
.Ar option
|
|
variable for use in
|
|
.Pa @SCRIPT@ .
|
|
.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 the first address currently assigned to the
|
|
.Ar interface
|
|
is used.
|
|
.It Fl s , -inform Op Ar address Ns Op Ar /cidr
|
|
Behaves exactly like
|
|
.Fl r , -request
|
|
as above, but sends a DHCP INFORM instead of a REQUEST.
|
|
This does not get a lease as such, just notifies the DHCP server of the
|
|
.Ar address
|
|
in use.
|
|
.Nm
|
|
remains running and pretends it has an infinite lease.
|
|
.Nm
|
|
will not de-configure the interface when it exits.
|
|
If
|
|
.Nm
|
|
fails to contact a DHCP server then it returns a failure instead of falling
|
|
back on IPv4LL.
|
|
.It Fl t , -timeout Ar seconds
|
|
Timeout after
|
|
.Ar seconds ,
|
|
instead of the default 30.
|
|
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 members of the class DHCP options other than the
|
|
default, without having to know things like hardware address or hostname.
|
|
.It Fl v , -vendor Ar code , Ns Ar value
|
|
Add an enscapulated vendor option.
|
|
.Ar code
|
|
should be between 1 and 254 inclusive.
|
|
Examples.
|
|
.Pp
|
|
Set the vendor option 01 with an IP address.
|
|
.D1 dhcpcd -v 01,192.168.0.2 eth0
|
|
Set the vendor option 02 with a hex code.
|
|
.D1 dhcpcd -v 02,01:02:03:04:05 eth0
|
|
Do the above and set a third option with a string and not an IP address.
|
|
.D1 dhcpcd -v 01,192.168.0.2 -v 02,01:02:03:04:05 -v 03,\e"192.168.0.2\e" eth0
|
|
.It Fl x , -exit
|
|
This causes an existing
|
|
.Nm
|
|
process running on the
|
|
.Ar interface
|
|
to deconfigure the
|
|
.Ar interface
|
|
and exit.
|
|
.It Fl D , -duid
|
|
Generate an
|
|
.Rs
|
|
.%T "RFC 4361"
|
|
.Re
|
|
compliant clientid.
|
|
This requires persistent storage and not all DHCP servers work with it so it's
|
|
not enabled by default.
|
|
The DUID generated will be held in
|
|
.Pa @SYSCONFDIR@/dhcpcd.duid
|
|
and should not be copied to other hosts.
|
|
.It Fl E , -lastlease
|
|
If
|
|
.Nm
|
|
cannot obtain a lease, then try to use the last lease acquired for the
|
|
interface.
|
|
If the
|
|
.Fl p, -persistent
|
|
option is not given then the lease is used if it hasn't expired.
|
|
.It 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.
|
|
The current hostname or the hostname specified using the
|
|
.Fl h , -hostname
|
|
option must be a FQDN.
|
|
.Nm
|
|
itself never does any DNS updates.
|
|
.It Fl I , -clientid Ar clientid
|
|
Change the default clientid sent from the interface hardware address.
|
|
If the string is of the format 01:02:03 then it is encoded as hex.
|
|
If not set then none is sent.
|
|
.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 options that deal with turning these bits off.
|
|
.Bl -tag -width indent
|
|
.It Fl q , -quiet
|
|
Quiet
|
|
.Nm
|
|
on the command line, only warnings and errors will be displayed.
|
|
The messages are still logged though.
|
|
.It Fl A , -noarp
|
|
Don't request or claim the address by ARP.
|
|
This also disables IPv4LL.
|
|
.It Fl B , -nobackground
|
|
Don't run in the background when we acquire a lease.
|
|
This is mainly useful for running under the control of another process, such
|
|
as a debugger or a network manager.
|
|
.It Fl C , -nohook Ar script
|
|
Don't run this hook script.
|
|
Matches full name, or prefixed with 2 numbers optionally ending with
|
|
.Pa .sh .
|
|
.Pp
|
|
So to stop dhcpcd from touching your DNS or MTU settings you would do:-
|
|
.D1 dhcpcd -C resolv.conf -C mtu eth0
|
|
.It Fl G , -nogateway
|
|
Don't set any default routes.
|
|
.It Fl K , -nolink
|
|
Don't receive link messages for carrier status.
|
|
You should only have to use this with buggy device drivers or running
|
|
.Nm
|
|
through a network manager.
|
|
.It Fl L , -noipv4ll
|
|
Don't use IPv4LL (aka APIPA, aka Bonjour, aka ZeroConf).
|
|
.It Fl O , -nooption Ar option
|
|
Don't request the specified option.
|
|
If no option given, then don't request any options other than those to
|
|
configure the interface and routing.
|
|
.It Fl T, -test
|
|
On receipt of OFFER messages just call
|
|
.Pa @SCRIPT@
|
|
with the reason of TEST which echo's the DHCP variables found in the message
|
|
to the console.
|
|
The interface configuration isn't touched and neither are any configuration
|
|
files.
|
|
.It Fl V, -variables
|
|
Display a list of option codes and the associated variable for use in
|
|
.Xr dhcpcd-run-hooks 8 .
|
|
.El
|
|
.Sh NOTES
|
|
.Nm
|
|
requires a Berkley Packet Filter, or BPF device on BSD based systems and a
|
|
Linux Socket Filter, or LPF device on Linux based systems.
|
|
.Sh FILES
|
|
.Bl -ohang
|
|
.It Pa @SYSCONFDIR@/dhcpcd.conf
|
|
Configuration file for dhcpcd.
|
|
If you always use the same options, put them here.
|
|
.It Pa @SYSCONFDIR@/dhcpcd.duid
|
|
Text file that holds the DUID used to identify the host.
|
|
.It Pa @SCRIPT@
|
|
Bourne shell script that is run to configure or deconfigure an interface.
|
|
.It Pa @HOOKDIR@
|
|
A directory containing bourne shell scripts that are run by the above script.
|
|
Each script can be disabled by using the
|
|
.Fl C , -nohook
|
|
option described above.
|
|
.It Pa @DBDIR@/dhcpcd\- Ns Ar interface Ns .lease
|
|
The actual DHCP message send by the server. We use this when reading the last
|
|
lease and use the files mtime as when it was issued.
|
|
.It Pa /var/run/dhcpcd\- Ns Ar interface Ns .pid
|
|
Stores the PID of
|
|
.Nm
|
|
running on the
|
|
.Ar interface .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr dhcpcd.conf 5 ,
|
|
.Xr dhcpcd-run-hooks 8 ,
|
|
.Xr resolv.conf 5 ,
|
|
.Xr resolvconf 8 ,
|
|
.Sh STANDARDS
|
|
RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3396, RFC 3397,
|
|
RFC 3442, RFC 3927, RFC 4361, RFC 4390, RFC 4702.
|
|
.Sh AUTHORS
|
|
.An Roy Marples <roy@marples.name>
|
|
.Sh BUGS
|
|
Please report them to http://bugs.marples.name
|