562 lines
21 KiB
Groff
562 lines
21 KiB
Groff
.\" dhclient.conf.5
|
|
.\"
|
|
.\" Copyright (c) 1996-1999 Internet Software Consortium.
|
|
.\" Use is subject to license terms which appear in the file named
|
|
.\" ISC-LICENSE that should have accompanied this file when you
|
|
.\" received it. If a file named ISC-LICENSE did not accompany this
|
|
.\" file, or you are not sure the one you have is correct, you may
|
|
.\" obtain an applicable copy of the license at:
|
|
.\"
|
|
.\" http://www.isc.org/isc-license-1.0.html.
|
|
.\"
|
|
.\" This file is part of the ISC DHCP distribution. The documentation
|
|
.\" associated with this file is listed in the file DOCUMENTATION,
|
|
.\" included in the top-level directory of this release.
|
|
.\"
|
|
.\" Support and other services are available for ISC products - see
|
|
.\" http://www.isc.org for more information.
|
|
.TH dhclient.conf 5
|
|
.SH NAME
|
|
dhclient.conf - DHCP client configuration file
|
|
.SH DESCRIPTION
|
|
The dhclient.conf file contains configuration information for
|
|
.IR dhclient,
|
|
the Internet Software Consortium DHCP Client.
|
|
.PP
|
|
The dhclient.conf file is a free-form ASCII text file. It is parsed by
|
|
the recursive-descent parser built into dhclient. The file may contain
|
|
extra tabs and newlines for formatting purposes. Keywords in the file
|
|
are case-insensitive. Comments may be placed anywhere within the
|
|
file (except within quotes). Comments begin with the # character and
|
|
end at the end of the line.
|
|
.PP
|
|
The dhclient.conf file can be used to configure the behaviour of the
|
|
client in a wide variety of ways: protocol timing, information
|
|
requested from the server, information required of the server,
|
|
defaults to use if the server does not provide certain information,
|
|
values with which to override information provided by the server, or
|
|
values to prepend or append to information provided by the server.
|
|
The configuration file can also be preinitialized with addresses to
|
|
use on networks that don't have DHCP servers.
|
|
.SH PROTOCOL TIMING
|
|
The timing behaviour of the client need not be configured by the user.
|
|
If no timing configuration is provided by the user, a fairly
|
|
reasonable timing behaviour will be used by default - one which
|
|
results in fairly timely updates without placing an inordinate load on
|
|
the server.
|
|
.PP
|
|
The following statements can be used to adjust the timing behaviour of
|
|
the DHCP client if required, however:
|
|
.PP
|
|
.I The
|
|
.B timeout
|
|
.I statement
|
|
.PP
|
|
.B timeout
|
|
.I time
|
|
.B ;
|
|
.PP
|
|
The
|
|
.I timeout
|
|
statement determines the amount of time that must pass between the
|
|
time that the client begins to try to determine its address and the
|
|
time that it decides that it's not going to be able to contact a
|
|
server. By default, this timeout is sixty seconds. After the
|
|
timeout has passed, if there are any static leases defined in the
|
|
configuration file, or any leases remaining in the lease database that
|
|
have not yet expired, the client will loop through these leases
|
|
attempting to validate them, and if it finds one that appears to be
|
|
valid, it will use that lease's address. If there are no valid
|
|
static leases or unexpired leases in the lease database, the client
|
|
will restart the protocol after the defined retry interval.
|
|
.PP
|
|
.I The
|
|
.B retry
|
|
.I statement
|
|
.PP
|
|
\fBretry \fItime\fR\fB;\fR
|
|
.PP
|
|
The
|
|
.I retry
|
|
statement determines the time that must pass after the client has
|
|
determined that there is no DHCP server present before it tries again
|
|
to contact a DHCP server. By default, this is five minutes.
|
|
.PP
|
|
.I The
|
|
.B select-timeout
|
|
.I statement
|
|
.PP
|
|
\fBselect-timeout \fItime\fR\fB;\fR
|
|
.PP
|
|
It is possible (some might say desirable) for there to be more than
|
|
one DHCP server serving any given network. In this case, it is
|
|
possible that a client may be sent more than one offer in response to
|
|
its initial lease discovery message. It may be that one of these
|
|
offers is preferable to the other (e.g., one offer may have the
|
|
address the client previously used, and the other may not).
|
|
.PP
|
|
The
|
|
.I select-timeout
|
|
is the time after the client sends its first lease discovery request
|
|
at which it stops waiting for offers from servers, assuming that it
|
|
has received at least one such offer. If no offers have been
|
|
received by the time the
|
|
.I select-timeout
|
|
has expired, the client will accept the first offer that arrives.
|
|
.PP
|
|
By default, the select-timeout is zero seconds - that is, the client
|
|
will take the first offer it sees.
|
|
.PP
|
|
.I The
|
|
.B reboot
|
|
.I statement
|
|
.PP
|
|
\fBreboot \fItime\fR\fB;\fR
|
|
.PP
|
|
When the client is restarted, it first tries to reacquire the last
|
|
address it had. This is called the INIT-REBOOT state. If it is
|
|
still attached to the same network it was attached to when it last
|
|
ran, this is the quickest way to get started. The
|
|
.I reboot
|
|
statement sets the time that must elapse after the client first tries
|
|
to reacquire its old address before it gives up and tries to discover
|
|
a new address. By default, the reboot timeout is ten seconds.
|
|
.PP
|
|
.I The
|
|
.B backoff-cutoff
|
|
.I statement
|
|
.PP
|
|
\fBbackoff-cutoff \fItime\fR\fB;\fR
|
|
.PP
|
|
The client uses an exponential backoff algorithm with some randomness,
|
|
so that if many clients try to configure themselves at the same time,
|
|
they will not make their requests in lockstep. The
|
|
.I backoff-cutoff
|
|
statement determines the maximum amount of time that the client is
|
|
allowed to back off. It defaults to two minutes.
|
|
.PP
|
|
.I The
|
|
.B initial-interval
|
|
.I statement
|
|
.PP
|
|
\fBinitial-interval \fItime\fR\fB;\fR
|
|
.PP
|
|
The
|
|
.I initial-interval
|
|
statement sets the amount of time between the first attempt to reach a
|
|
server and the second attempt to reach a server. Each time a message
|
|
is sent, the interval between messages is incremented by twice the
|
|
current interval multiplied by a random number between zero and one.
|
|
If it is greater than the backoff-cutoff amount, it is set to that
|
|
amount. It defaults to ten seconds.
|
|
.SH LEASE REQUIREMENTS AND REQUESTS
|
|
The DHCP protocol allows the client to request that the server send it
|
|
specific information, and not send it other information that it is not
|
|
prepared to accept. The protocol also allows the client to reject
|
|
offers from servers if they don't contain information the client
|
|
needs, or if the information provided is not satisfactory.
|
|
.PP
|
|
There is a variety of data contained in offers that DHCP servers send
|
|
to DHCP clients. The data that can be specifically requested is what
|
|
are called \fIDHCP Options\fR. DHCP Options are defined in
|
|
\fBdhcp-options(5)\fR.
|
|
.PP
|
|
.I The
|
|
.B request
|
|
.I statement
|
|
.PP
|
|
\fBrequest [ \fIoption\fR ] [\fB,\fI ... \fIoption\fR ]\fB;\fR
|
|
.PP
|
|
The request statement causes the client to request that any server
|
|
responding to the client send the client its values for the specified
|
|
options. Only the option names should be specified in the request
|
|
statement - not option parameters. By default, the DHCP server
|
|
requests the subnet-mask, broadcast-address, time-offset, routers,
|
|
domain-name, domain-name-servers and host-name options.
|
|
.PP
|
|
In some cases, it may be desirable to send no parameter request list
|
|
at all. To do this, simply write the request statement but specify
|
|
no parameters:
|
|
.PP
|
|
.nf
|
|
request;
|
|
.fi
|
|
.PP
|
|
.I The
|
|
.B require
|
|
.I statement
|
|
.PP
|
|
\fBrequire [ \fIoption\fR ] [\fB,\fI ... \fIoption ]\fB;\fR
|
|
.PP
|
|
The require statement lists options that must be sent in order for an
|
|
offer to be accepted. Offers that do not contain all the listed
|
|
options will be ignored.
|
|
.PP
|
|
.I The
|
|
.B send
|
|
.I statement
|
|
.PP
|
|
\fBsend { [ \fIoption declaration\fR ]
|
|
[\fB,\fI ... \fIoption declaration\fR ]\fB}\fR
|
|
.PP
|
|
The send statement causes the client to send the specified options to
|
|
the server with the specified values. These are full option
|
|
declarations as described in \fBdhcp-options(5)\fR. Options that are
|
|
always sent in the DHCP protocol should not be specified here, except
|
|
that the client can specify a \fBrequested-lease-time\fR option other
|
|
than the default requested lease time, which is two hours. The other
|
|
obvious use for this statement is to send information to the server
|
|
that will allow it to differentiate between this client and other
|
|
clients or kinds of clients.
|
|
.SH OPTION MODIFIERS
|
|
In some cases, a client may receive option data from the server which
|
|
is not really appropriate for that client, or may not receive
|
|
information that it needs, and for which a useful default value
|
|
exists. It may also receive information which is useful, but which
|
|
needs to be supplemented with local information. To handle these
|
|
needs, several option modifiers are available.
|
|
.PP
|
|
.I The
|
|
.B default
|
|
.I statement
|
|
.PP
|
|
\fBdefault [ \fIoption declaration\fR ] \fB;\fR
|
|
.PP
|
|
If for some option the client should use the value supplied by
|
|
the server, but needs to use some default value if no value was supplied
|
|
by the server, these values can be defined in the
|
|
.B default
|
|
statement.
|
|
.PP
|
|
.I The
|
|
.B supersede
|
|
.I statement
|
|
.PP
|
|
\fBsupersede [ \fIoption declaration\fR ] \fB;\fR
|
|
.PP
|
|
If for some option the client should always use a locally-configured
|
|
value or values rather than whatever is supplied by the server, these
|
|
values can be defined in the
|
|
.B supersede
|
|
statement.
|
|
.PP
|
|
.I The
|
|
.B prepend
|
|
.I statement
|
|
.PP
|
|
\fBprepend [ \fIoption declaration\fR ] \fB;\fR
|
|
.PP
|
|
If for some set of options the client should use a value you
|
|
supply, and then use the values supplied by
|
|
the server, if any, these values can be defined in the
|
|
.B prepend
|
|
statement. The
|
|
.B prepend
|
|
statement can only be used for options which
|
|
allow more than one value to be given. This restriction is not
|
|
enforced - if you ignore it, the behaviour will be unpredictable.
|
|
.PP
|
|
.I The
|
|
.B append
|
|
.I statement
|
|
.PP
|
|
\fBappend [ \fIoption declaration\fR ] \fB;\fR
|
|
.PP
|
|
If for some set of options the client should first use the values
|
|
supplied by the server, if any, and then use values you supply, these
|
|
values can be defined in the
|
|
.B append
|
|
statement. The
|
|
.B append
|
|
statement can only be used for options which
|
|
allow more than one value to be given. This restriction is not
|
|
enforced - if you ignore it, the behaviour will be unpredictable.
|
|
.SH LEASE DECLARATIONS
|
|
.PP
|
|
.I The
|
|
.B lease
|
|
.I declaration
|
|
.PP
|
|
\fBlease {\fR \fIlease-declaration\fR [ ... \fIlease-declaration ] \fB}\fR
|
|
.PP
|
|
The DHCP client may decide after some period of time (see \fBPROTOCOL
|
|
TIMING\fR) decide that it is not going to succeed in contacting a
|
|
server. At that time, it consults its own database of old leases and
|
|
tests each one that has not yet timed out by pinging the listed router
|
|
for that lease to see if that lease could work. It is possible to
|
|
define one or more \fIfixed\fR leases in the client configuration file
|
|
for networks where there is no DHCP or BOOTP service, so that the
|
|
client can still automatically configure its address. This is done
|
|
with the
|
|
.B lease
|
|
statement.
|
|
.PP
|
|
NOTE: the lease statement is also used in the dhclient.leases file in
|
|
order to record leases that have been received from DHCP servers.
|
|
Some of the syntax for leases as described below is only needed in the
|
|
dhclient.leases file. Such syntax is documented here for
|
|
completeness.
|
|
.PP
|
|
A lease statement consists of the lease keyword, followed by a left
|
|
curly brace, followed by one or more lease declaration statements,
|
|
followed by a right curly brace. The following lease declarations
|
|
are possible:
|
|
.PP
|
|
\fBbootp;\fR
|
|
.PP
|
|
The
|
|
.B bootp
|
|
statement is used to indicate that the lease was acquired using the
|
|
BOOTP protocol rather than the DHCP protocol. It is never necessary
|
|
to specify this in the client configuration file. The client uses
|
|
this syntax in its lease database file.
|
|
.PP
|
|
\fBinterface\fR \fB"\fR\fIstring\fR\fB";\fR
|
|
.PP
|
|
The
|
|
.B interface
|
|
lease statement is used to indicate the interface on which the lease
|
|
is valid. If set, this lease will only be tried on a particular
|
|
interface. When the client receives a lease from a server, it always
|
|
records the interface number on which it received that lease.
|
|
If predefined leases are specified in the dhclient.conf file, the
|
|
interface should also be specified, although this is not required.
|
|
.PP
|
|
\fBfixed-address\fR \fIip-address\fR\fB;\fR
|
|
.PP
|
|
The
|
|
.B fixed-address
|
|
statement is used to set the ip address of a particular lease. This
|
|
is required for all lease statements. The IP address must be
|
|
specified as a dotted quad (e.g., 12.34.56.78).
|
|
.PP
|
|
\fBfilename "\fR\fIstring\fR\fB";\fR
|
|
.PP
|
|
The
|
|
.B filename
|
|
statement specifies the name of the boot filename to use. This is
|
|
not used by the standard client configuration script, but is included
|
|
for completeness.
|
|
.PP
|
|
\fBserver-name "\fR\fIstring\fR\fB";\fR
|
|
.PP
|
|
The
|
|
.B server-name
|
|
statement specifies the name of the boot server name to use. This is
|
|
also not used by the standard client configuration script.
|
|
.PP
|
|
\fBoption\fR \fIoption-declaration\fR\fB;\fR
|
|
.PP
|
|
The
|
|
.B option
|
|
statement is used to specify the value of an option supplied by the
|
|
server, or, in the case of predefined leases declared in
|
|
dhclient.conf, the value that the user wishes the client configuration
|
|
script to use if the predefined lease is used.
|
|
.PP
|
|
\fBscript "\fIscript-name\fB";\fR
|
|
.PP
|
|
The
|
|
.B script
|
|
statement is used to specify the pathname of the dhcp client
|
|
configuration script. This script is used by the dhcp client to set
|
|
each interface's initial configuration prior to requesting an address,
|
|
to test the address once it has been offered, and to set the
|
|
interface's final configuration once a lease has been acquired. If
|
|
no lease is acquired, the script is used to test predefined leases, if
|
|
any, and also called once if no valid lease can be identified. For
|
|
more information, see
|
|
.B dhclient-script(8).
|
|
.PP
|
|
\fBmedium "\fImedia setup\fB";\fR
|
|
.PP
|
|
The
|
|
.B medium
|
|
statement can be used on systems where network interfaces cannot
|
|
automatically determine the type of network to which they are
|
|
connected. The media setup string is a system-dependent parameter
|
|
which is passed to the dhcp client configuration script when
|
|
initializing the interface. On Unix and Unix-like systems, the
|
|
argument is passed on the ifconfig command line when configuring te
|
|
interface.
|
|
.PP
|
|
The dhcp client automatically declares this parameter if it used a
|
|
media type (see the
|
|
.B media
|
|
statement) when configuring the interface in order to obtain a lease.
|
|
This statement should be used in predefined leases only if the network
|
|
interface requires media type configuration.
|
|
.PP
|
|
\fBrenew\fR \fIdate\fB;\fR
|
|
.PP
|
|
\fBrebind\fR \fIdate\fB;\fR
|
|
.PP
|
|
\fBexpire\fR \fIdate\fB;\fR
|
|
.PP
|
|
The \fBrenew\fR statement defines the time at which the dhcp client
|
|
should begin trying to contact its server to renew a lease that it is
|
|
using. The \fBrebind\fR statement defines the time at which the dhcp
|
|
client should begin to try to contact \fIany\fR dhcp server in order
|
|
to renew its lease. The \fBexpire\fR statement defines the time at
|
|
which the dhcp client must stop using a lease if it has not been able
|
|
to contact a server in order to renew it.
|
|
.PP
|
|
These declarations are automatically set in leases acquired by the
|
|
DHCP client, but must also be configured in predefined leases - a
|
|
predefined lease whose expiry time has passed will not be used by the
|
|
DHCP client.
|
|
.PP
|
|
Dates are specified as follows:
|
|
.PP
|
|
\fI<weekday> <year>\fB/\fI<month>\fB/\fI<day>
|
|
<hour>\fB:\fI<minute>\fB:\fI<second>\fR
|
|
.PP
|
|
The weekday is present to make it easy for a human to tell when a
|
|
lease expires - it's specified as a number from zero to six, with zero
|
|
being Sunday. When declaring a predefined lease, it can always be
|
|
specified as zero. The year is specified with the century, so it
|
|
should generally be four digits except for really long leases. The
|
|
month is specified as a number starting with 1 for January. The day
|
|
of the month is likewise specified starting with 1. The hour is a
|
|
number between 0 and 23, the minute a number between 0 and 59, and the
|
|
second also a number between 0 and 59.
|
|
.SH ALIAS DECLARATIONS
|
|
\fBalias { \fI declarations ... \fB}\fR
|
|
.PP
|
|
Some DHCP clients running TCP/IP roaming protocols may require that in
|
|
addition to the lease they may acquire via DHCP, their interface also
|
|
be configured with a predefined IP alias so that they can have a
|
|
permanent IP address even while roaming. The Internet Software
|
|
Consortium DHCP client doesn't support roaming with fixed addresses
|
|
directly, but in order to facilitate such experimentation, the dhcp
|
|
client can be set up to configure an IP alias using the
|
|
.B alias
|
|
declaration.
|
|
.PP
|
|
The alias declaration resembles a lease declaration, except that
|
|
options other than the subnet-mask option are ignored by the standard
|
|
client configuration script, and expiry times are ignored. A typical
|
|
alias declaration includes an interface declaration, a fixed-address
|
|
declaration for the IP alias address, and a subnet-mask option
|
|
declaration. A medium statement should never be included in an alias
|
|
declaration.
|
|
.SH OTHER DECLARATIONS
|
|
\fBreject \fIip-address\fB;\fR
|
|
.PP
|
|
The reject statement causes the DHCP client to reject offers from
|
|
servers who use the specified address as a server identifier. This
|
|
can be used to avoid being configured by rogue or misconfigured dhcp
|
|
servers, although it should be a last resort - better to track down
|
|
the bad DHCP server and fix it.
|
|
.PP
|
|
\fBinterface "\fIname\fB" { \fIdeclarations ... \fB }
|
|
.PP
|
|
A client with more than one network interface may require different
|
|
behaviour depending on which interface is being configured. All
|
|
timing parameters and declarations other than lease and alias
|
|
declarations can be enclosed in an interface declaration, and those
|
|
parameters will then be used only for the interface that matches the
|
|
specified name. Interfaces for which there is no interface
|
|
declaration will use the parameters declared outside of any interface
|
|
declaration, or the default settings.
|
|
.PP
|
|
\fBpseudo "\fIname\fR" "\fIreal-name\fB" { \fIdeclarations ... \fB }
|
|
.PP
|
|
Under some circumstances it can be useful to declare a pseudo-interface
|
|
and have the DHCP client acquire a configuration for that interface.
|
|
Each interface that the DHCP client is supporting normally has a DHCP
|
|
client state machine running on it to acquire and maintain its lease.
|
|
A pseudo-interface is just another state machine running on the
|
|
interface named \fIreal-name\fR, with its own lease and its own
|
|
state. If you use this feature, you must provide a client identifier
|
|
for both the pseudo-interface and the actual interface, and the two
|
|
identifiers must be different. You must also provide a seperate
|
|
client script for the pseudo-interface to do what you want with the IP
|
|
address. For example:
|
|
.PP
|
|
.nf
|
|
interface "ep0" {
|
|
send dhcp-client-identifier "my-client-ep0";
|
|
}
|
|
pseudo "secondary" "ep0" {
|
|
send dhcp-client-identifier "my-client-ep0-secondary";
|
|
script "/etc/dhclient-secondary";
|
|
}
|
|
.fi
|
|
.PP
|
|
The client script for the pseudo-interface should not configure the
|
|
interface up or down - essentially, all it needs to handle are the
|
|
states where a lease has been acquired or renewed, and the states
|
|
where a lease has expired. See \fBdhclient-script(8)\fR for more
|
|
information.
|
|
.PP
|
|
\fBmedia "\fImedia setup\fB"\fI [ \fB, "\fImedia setup\fB", \fI... ]\fB;\fR
|
|
.PP
|
|
The
|
|
.B media
|
|
statement defines one or more media configuration parameters which may
|
|
be tried while attempting to acquire an IP address. The dhcp client
|
|
will cycle through each media setup string on the list, configuring
|
|
the interface using that setup and attempting to boot, and then trying
|
|
the next one. This can be used for network interfaces which aren't
|
|
capable of sensing the media type unaided - whichever media type
|
|
succeeds in getting a request to the server and hearing the reply is
|
|
probably right (no guarantees).
|
|
.PP
|
|
The media setup is only used for the initial phase of address
|
|
acquisition (the DHCPDISCOVER and DHCPOFFER packtes). Once an
|
|
address has been acquired, the dhcp client will record it in its lease
|
|
database and will record the media type used to acquire the address.
|
|
Whenever the client tries to renew the lease, it will use that same
|
|
media type. The lease must expire before the client will go back to
|
|
cycling through media types.
|
|
.SH SAMPLE
|
|
The following configuration file is used on a laptop running NetBSD
|
|
1.3. The laptop has an IP alias of 192.5.5.213, and has one
|
|
interface, ep0 (a 3com 3C589C). Booting intervals have been
|
|
shortened somewhat from the default, because the client is known to
|
|
spend most of its time on networks with little DHCP activity. The
|
|
laptop does roam to multiple networks.
|
|
|
|
.nf
|
|
|
|
timeout 60;
|
|
retry 60;
|
|
reboot 10;
|
|
select-timeout 5;
|
|
initial-interval 2;
|
|
reject 192.33.137.209;
|
|
|
|
interface "ep0" {
|
|
send host-name "andare.fugue.com";
|
|
send dhcp-client-identifier 1:0:a0:24:ab:fb:9c;
|
|
send dhcp-lease-time 3600;
|
|
supersede domain-name "fugue.com rc.vix.com home.vix.com";
|
|
prepend domain-name-servers 127.0.0.1;
|
|
request subnet-mask, broadcast-address, time-offset, routers,
|
|
domain-name, domain-name-servers, host-name;
|
|
require subnet-mask, domain-name-servers;
|
|
script "/etc/dhclient-script";
|
|
media "media 10baseT/UTP", "media 10base2/BNC";
|
|
}
|
|
|
|
alias {
|
|
interface "ep0";
|
|
fixed-address 192.5.5.213;
|
|
option subnet-mask 255.255.255.255;
|
|
}
|
|
.fi
|
|
This is a very complicated dhclient.conf file - in general, yours
|
|
should be much simpler. In many cases, it's sufficient to just
|
|
create an empty dhclient.conf file - the defaults are usually fine.
|
|
.SH SEE ALSO
|
|
dhcp-options(5), dhclient.leases(5), dhcpd(8), dhcpd.conf(5), RFC2132,
|
|
RFC2131.
|
|
.SH AUTHOR
|
|
.B dhclient(8)
|
|
was written by Ted Lemon <mellon@vix.com>
|
|
under a contract with Vixie Labs. Funding
|
|
for this project was provided by the Internet Software Consortium.
|
|
Information about the Internet Software Consortium can be found at
|
|
.B http://www.isc.org/isc.
|