.\" $Id: dhclient.8,v 1.36 2011/04/15 21:58:12 sar Exp $
.\"
-.\" Copyright (c) 2004,2007-2011 by Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (c) 2004,2007-2012 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 1996-2003 by Internet Software Consortium
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.PP
The DHCP protocol allows a host to contact a central server which
maintains a list of IP addresses which may be assigned on one or more
-subnets. A DHCP client may request an address from this pool, and
-then use it on a temporary basis for communication on network. The
+subnets. A DHCP client may request an address from this pool, and
+then use it on a temporary basis for communication on network. The
DHCP protocol also provides a mechanism whereby a client can learn
important details about the network to which it is attached, such as
the location of a default router, the location of a name server, and
options.
.PP
On startup, \fBdhclient\fR reads the dhclient.conf
-for configuration instructions. It then gets a list of all the
-network interfaces that are configured in the current system. For
+for configuration instructions. It then gets a list of all the
+network interfaces that are configured in the current system. For
each interface, it attempts to configure the interface using the DHCP
protocol.
.PP
In order to keep track of leases across system reboots and server
restarts, \fBdhclient\fR keeps a list of leases it has been assigned in the
-dhclient.leases file. On startup, after reading the dhclient.conf
+dhclient.leases file. On startup, after reading the dhclient.conf
file, \fBdhclient\fR reads the dhclient.leases file to refresh its memory
about what leases it has been assigned.
.PP
When a new lease is acquired, it is appended to the end of the
-dhclient.leases file. In order to prevent the file from becoming
+dhclient.leases file. In order to prevent the file from becoming
arbitrarily large, from time to time \fBdhclient\fR creates a new
dhclient.leases file from its in-core lease database. The old version
of the dhclient.leases file is retained under the name
.PP
Old leases are kept around in case the DHCP server is unavailable when
\fBdhclient\fR is first invoked (generally during the initial system boot
-process). In that event, old leases from the dhclient.leases file
+process). In that event, old leases from the dhclient.leases file
which have not yet expired are tested, and if they are determined to
be valid, they are used until either they expire or the DHCP server
becomes available.
.PP
A mobile host which may sometimes need to access a network on which no
DHCP server exists may be preloaded with a lease for a fixed
-address on that network. When all attempts to contact a DHCP server
+address on that network. When all attempts to contact a DHCP server
have failed, \fBdhclient\fR will try to validate the static lease, and if it
succeeds, will use that lease until it is restarted.
.PP
A mobile host may also travel to some networks on which DHCP is not
-available but BOOTP is. In that case, it may be advantageous to
+available but BOOTP is. In that case, it may be advantageous to
arrange with the network administrator for an entry on the BOOTP
database, so that the host can boot quickly on that network rather
than cycling through the list of old leases.
possible, and attempt to configure each interface.
.PP
It is also possible to specify interfaces by name in the dhclient.conf
-file. If interfaces are specified in this way, then the client will
+file. If interfaces are specified in this way, then the client will
only configure interfaces that are either specified in the
configuration file or on the command line, and will ignore all other
interfaces.
to configure. On laptop computers and other computers with
hot-swappable I/O buses, it is possible that a broadcast interface may
be added after system startup. This flag can be used to cause the client
-not to exit when it doesn't find any such interfaces. The
+not to exit when it doesn't find any such interfaces. The
.B omshell(1)
program can then be used to notify the client when a network interface
has been added or removed, so that the client can attempt to configure an IP
current status and make changes to it.
.PP
Rather than implementing the underlying OMAPI protocol directly, user
-programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a
+programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a
wrapper that handles some of the housekeeping chores that OMAPI does
-not do automatically. Dhcpctl and OMAPI are documented in
+not do automatically. Dhcpctl and OMAPI are documented in
\fBdhcpctl(3)\fR
-and \fBomapi(3)\fR. Most things you'd want to do with the client can
+and \fBomapi(3)\fR. Most things you'd want to do with the client can
be done directly using the \fBomshell(1)\fR command, rather than
having to write a special program.
.SH THE CONTROL OBJECT
The control object allows you to shut the client down, releasing all
leases that it holds and deleting any DNS records it may have added.
It also allows you to pause the client - this unconfigures any
-interfaces the client is using. You can then restart it, which
-causes it to reconfigure those interfaces. You would normally pause
+interfaces the client is using. You can then restart it, which
+causes it to reconfigure those interfaces. You would normally pause
the client prior to going into hibernation or sleep on a laptop
-computer. You would then resume it after the power comes back.
+computer. You would then resume it after the power comes back.
This allows PC cards to be shut down while the computer is hibernating
or sleeping, and then reinitialized to their previous state once the
computer comes out of hibernation or sleep.
.PP
-The control object has one attribute - the state attribute. To shut
-the client down, set its state attribute to 2. It will automatically
-do a DHCPRELEASE. To pause it, set its state attribute to 3. To
+The control object has one attribute - the state attribute. To shut
+the client down, set its state attribute to 2. It will automatically
+do a DHCPRELEASE. To pause it, set its state attribute to 3. To
resume it, set its state attribute to 4.
.PP
.SH ENVIRONMENT VARIABLES
The current version owes much to Elliot's Linux enhancements, but
was substantially reorganized and partially rewritten by Ted Lemon
so as to use the same networking framework that the Internet Systems
-Consortium DHCP server uses. Much system-specific configuration code
+Consortium DHCP server uses. Much system-specific configuration code
was moved into a shell script so that as support for more operating
systems is added, it will not be necessary to port and maintain
system-specific configuration code to these operating systems - instead,
.IR dhclient,
the Internet Systems 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
+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
+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
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
+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
+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 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.
+to contact a DHCP server. By default, this is five minutes.
.PP
.I The
.B select-timeout
\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
+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
+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
.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
+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.
\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
+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
+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.
+a new address. By default, the reboot timeout is ten seconds.
.PP
.I The
.B backoff-cutoff
.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
+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, the actual value will be evaluated randomly between
-1/2 to 1 1/2 times the \fItime\fR specified. It defaults to fifteen
+1/2 to 1 1/2 times the \fItime\fR specified. It defaults to fifteen
seconds.
.PP
.I The
.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
+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
.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 DHCPv4 client
+options. Only the option names should be specified in the request
+statement - not option parameters. By default, the DHCPv4 client
requests the subnet-mask, broadcast-address, time-offset, routers,
domain-name, domain-name-servers and host-name options while the DHCPv6
client requests the dhcp6 name-servers and domain-search options. Note
and these options will not be requested.
.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
+at all. To do this, simply write the request statement but specify
no parameters:
.PP
.nf
\fB[ also ] require [ [ \fIoption-space\fR . ] \fIoption\fR ] [\fB,\fI ... ]\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
+offer to be accepted. Offers that do not contain all the listed
options will be ignored. There is no default require list.
.PP
.nf
clients or kinds of clients.
.SH DYNAMIC DNS
The client now has some very limited support for doing DNS updates
-when a lease is acquired. This is prototypical, and probably doesn't
-do what you want. It also only works if you happen to have control
+when a lease is acquired. This is prototypical, and probably doesn't
+do what you want. It also only works if you happen to have control
over your DNS server, which isn't very likely.
.PP
Note that everything in this section is true whether you are using DHCPv4
or DHCPv6. The exact same syntax is used for both.
.PP
To make it work, you have to declare a key and zone as in the DHCP
-server (see \fBdhcpd.conf\fR(5) for details). You also need to
+server (see \fBdhcpd.conf\fR(5) for details). You also need to
configure the fqdn option on the client, as follows:
.PP
.nf
.fi
.PP
The \fIfqdn.fqdn\fR option \fBMUST\fR be a fully-qualified domain
-name. You \fBMUST\fR define a zone statement for the zone to be
-updated. The \fIfqdn.encoded\fR option may need to be set to
+name. You \fBMUST\fR define a zone statement for the zone to be
+updated. The \fIfqdn.encoded\fR option may need to be set to
\fIon\fR or \fIoff\fR, depending on the DHCP server you are using.
.PP
.I The
DHCP client do the update directly (for example, if you want to
use SIG(0) authentication, which is not supported directly by the
DHCP client, you can instruct the client not to do the update using
-the \fBdo-forward-updates\fR statement. \fIFlag\fR should be \fBtrue\fR
+the \fBdo-forward-updates\fR statement. \fIFlag\fR should be \fBtrue\fR
if you want the DHCP client to do the update, and \fBfalse\fR if
-you don't want the DHCP client to do the update. By default, the DHCP
+you don't want the DHCP client to do the update. By default, the DHCP
client will do the DNS update.
.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
+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
supply, and then use the values supplied by
the server, if any, these values can be defined in the
.B prepend
-statement. The
+statement. The
.B prepend
statement can only be used for options which
-allow more than one value to be given. This restriction is not
+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
supplied by the server, if any, and then use values you supply, these
values can be defined in the
.B append
-statement. The
+statement. The
.B append
statement can only be used for options which
-allow more than one value to be given. This restriction is not
+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
.PP
The DHCP client may decide after some period of time (see \fBPROTOCOL
TIMING\fR) that it is not going to succeed in contacting a
-server. At that time, it consults its own database of old leases and
+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
+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
+client can still automatically configure its address. This is done
with the
.B lease
statement.
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
+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
+followed by a right curly brace. The following lease declarations
are possible:
.PP
\fBbootp;\fR
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
+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
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
+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
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
+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
+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
.PP
The
.B server-name
-statement specifies the name of the boot server name to use. This is
+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
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
+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
+any, and also called once if no valid lease can be identified. For
more information, see
.B dhclient-script(8).
.PP
statement is used to specify which option space should be used for
decoding the vendor-encapsulate-options option if one is received.
The \fIdhcp-vendor-identifier\fR can be used to request a specific
-class of vendor options from the server. See
+class of vendor options from the server. See
.B dhcp-options(5)
for details.
.PP
.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
+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
+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
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 Systems
+permanent IP address even while roaming. The Internet Systems
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
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. A medium statement should never be included in an alias
declaration.
.SH OTHER DECLARATIONS
\fBdb-time-format\fR [ \fIdefault\fR | \fIlocal\fR ] \fB;\fR
\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
+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
+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
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
+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 separate
+identifiers must be different. You must also provide a separate
client script for the pseudo-interface to do what you want with the IP
-address. For example:
+address. For example:
.PP
.nf
interface "ep0" {
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
+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
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
+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
+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 packets). Once an
+acquisition (the DHCPDISCOVER and DHCPOFFER packets). 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
+media type. The lease must expire before the client will go back to
cycling through media types.
.PP
\fBhardware\fR \fIlink-type mac-address\fR\fB;\fR
.PP
.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
+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
+spend most of its time on networks with little DHCP activity. The
laptop does roam to multiple networks.
.nf
}
.fi
This is a very complicated dhclient.conf file - in general, yours
-should be much simpler. In many cases, it's sufficient to just
+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), dhcp-eval(5), dhclient.leases(5), dhcpd(8), dhcpd.conf(5),
.SH AUTHOR
.B dhclient(8)
was written by Ted Lemon
-under a contract with Vixie Labs. Funding
+under a contract with Vixie Labs. Funding
for this project was provided by Internet Systems Consortium.
Information about Internet Systems Consortium can be found at
.B https://www.isc.org.
.\" $Id: dhcp-eval.5,v 1.33 2012/05/17 15:50:14 sar Exp $
.\"
-.\" Copyright (c) 2009-2011 by Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (c) 2009-2012 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 2004,2007 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 1996-2003 by Internet Software Consortium
.\"
.SH DESCRIPTION
The Internet Systems Consortium DHCP client and server both provide
the ability to perform conditional behavior depending on the contents
-of packets they receive. The syntax for specifying this conditional
+of packets they receive. The syntax for specifying this conditional
behaviour is documented here.
.SH REFERENCE: CONDITIONAL BEHAVIOUR
Conditional behaviour is specified using the if statement and the else
-or elsif statements. A conditional statement can appear anywhere
+or elsif statements. A conditional statement can appear anywhere
that a regular statement (e.g., an option statement) can appear, and
-can enclose one or more such statements. A typical conditional
+can enclose one or more such statements. A typical conditional
statement in a server might be:
.PP
.nf
if option dhcp-user-class = "accounting" {
max-lease-time 17600;
option domain-name "accounting.example.org";
- option domain-name-servers ns1.accounting.example.org,
+ option domain-name-servers ns1.accounting.example.org,
ns2.accounting.example.org;
} elsif option dhcp-user-class = "sales" {
max-lease-time 17600;
option domain-name "sales.example.org";
- option domain-name-servers ns1.sales.example.org,
+ option domain-name-servers ns1.sales.example.org,
ns2.sales.example.org;
} elsif option dhcp-user-class = "engineering" {
max-lease-time 17600;
option domain-name "engineering.example.org";
- option domain-name-servers ns1.engineering.example.org,
+ option domain-name-servers ns1.engineering.example.org,
ns2.engineering.example.org;
} else {
max-lease-time 600;
option domain-name "misc.example.org";
- option domain-name-servers ns1.misc.example.org,
+ option domain-name-servers ns1.misc.example.org,
ns2.misc.example.org;
}
.fi
.PP
.nf
# example.org filters DNS at its firewall, so we have to use their DNS
-# servers when we connect to their network. If we are not at
+# servers when we connect to their network. If we are not at
# example.org, prefer our own DNS server.
if not option domain-name = "example.org" {
prepend domain-name-servers 127.0.0.1;
}
-.fi
+.fi
.PP
The
.B if
statement and the
.B elsif
continuation statement both take boolean expressions as their
-arguments. That is, they take expressions that, when evaluated,
-produce a boolean result. If the expression evaluates to true, then
-the statements enclosed in braces following the
+arguments. That is, they take expressions that, when evaluated,
+produce a boolean result. If the expression evaluates to true, then
+the statements enclosed in braces following the
.B if
statement are executed, and all subsequent
.B elsif
and
.B else
-clauses are skipped. Otherwise, each subsequent
+clauses are skipped. Otherwise, each subsequent
.B elsif
clause's expression is checked, until an elsif clause is encountered
-whose test evaluates to true. If such a clause is found, the
+whose test evaluates to true. If such a clause is found, the
statements in braces following it are executed, and then any
subsequent
.B elsif
and
.B else
-clauses are skipped. If all the
+clauses are skipped. If all the
.B if
and
.B elsif
.B else
clause, the statements enclosed in braces following the
.B else
-are evaluated. Boolean expressions that evaluate to null are
+are evaluated. Boolean expressions that evaluate to null are
treated as false in conditionals.
.SH BOOLEAN EXPRESSIONS
The following is the current list of boolean expressions that are
.RS 0.25i
.PP
The \fB=\fR operator compares the values of two data expressions,
-returning true if they are the same, false if they are not. If
+returning true if they are the same, false if they are not. If
either the left-hand side or the right-hand side are null, the
result is also null.
.RE
extended regex(7) matching of the values of two data expressions, returning
true if \fIdata-expression-1\fR matches against the regular expression
evaluated by \fIdata-expression-2\fR, or false if it does not match or
-encounters some error. If either the left-hand side or the right-hand side
+encounters some error. If either the left-hand side or the right-hand side
are null or empty strings, the result is also false. The \fB~~\fR operator
differs from the \fB~=\fR operator in that it is case-insensitive.
.RE
.RS 0.25i
The \fBnot\fR operator evaluates to true if \fIboolean-expression\fR
evaluates to false, and returns false if \fIboolean-expression\fR evaluates
-to true. If \fIboolean-expression\fR evaluates to null, the result
+to true. If \fIboolean-expression\fR evaluates to null, the result
is also null.
.RE
.PP
.RE
.SH DATA EXPRESSIONS
Several of the boolean expressions above depend on the results of
-evaluating data expressions. A list of these expressions is provided
+evaluating data expressions. A list of these expressions is provided
here.
.PP
.B substring (\fIdata-expr\fB, \fIoffset\fB, \fIlength\fB)\fR
.PP
.RS 0.25i
The \fBsuffix\fR operator evaluates \fIdata-expr\fR and returns the
-last \fIlength\fR bytes of the result of that evaluation. \fILength\fR
+last \fIlength\fR bytes of the result of that evaluation. \fILength\fR
is a numeric expression. If \fIdata-expr\fR or \fIlength\fR evaluate
to null, then the result is also null. If \fIsuffix\fR evaluates to a
number greater than the length of the evaluated data, then the
.PP
.RS 0.25i
The \fBlcase\fR function returns the result of evaluating
-\fIdata-expr\fR converted to lower case. If \fIdata-expr\fR evaluates
+\fIdata-expr\fR converted to lower case. If \fIdata-expr\fR evaluates
to null, then the result is also null.
.RE
.PP
.PP
.RS 0.25i
The \fBucase\fR function returns the result of evaluating
-\fIdata-expr\fR converted to upper case. If \fIdata-expr\fR evaluates
+\fIdata-expr\fR converted to upper case. If \fIdata-expr\fR evaluates
to null, then the result is also null.
.RE
.PP
.RS 0.25i
The \fBhardware\fR operator returns a data string whose first element
is the type of network interface indicated in packet being considered,
-and whose subsequent elements are client's link-layer address. If
+and whose subsequent elements are client's link-layer address. If
there is no packet, or if the RFC2131 \fIhlen\fR field is invalid,
-then the result is null. Hardware types include ethernet (1),
-token-ring (6), and fddi (8). Hardware types are specified by the
+then the result is null. Hardware types include ethernet (1),
+token-ring (6), and fddi (8). Hardware types are specified by the
IETF, and details on how the type numbers are defined can be found in
RFC2131 (in the ISC DHCP distribution, this is included in the doc/
subdirectory).
.RS 0.25i
The \fBpacket\fR operator returns the specified portion of the packet
being considered, or null in contexts where no packet is being
-considered. \fIOffset\fR and \fIlength\fR are applied to the
+considered. \fIOffset\fR and \fIlength\fR are applied to the
contents packet as in the \fBsubstring\fR operator.
.RE
.PP
.PP
.RS 0.25i
A string, enclosed in quotes, may be specified as a data expression,
-and returns the text between the quotes, encoded in ASCII. The
+and returns the text between the quotes, encoded in ASCII. The
backslash ('\\') character is treated specially, as in C programming: '\\t'
means TAB, '\\r' means carriage return, '\\n' means newline, and '\\b' means
-bell. Any octal value can be specified with '\\nnn', where nnn is any
+bell. Any octal value can be specified with '\\nnn', where nnn is any
positive octal number less than 0400. Any hexadecimal value can be
specified with '\\xnn', where nn is any positive hexadecimal number less
than or equal to 0xff.
.B concat (\fIdata-expr1\fB, ..., \fIdata-exprN\fB)\fR
.RS 0.25i
The expressions are evaluated, and the results of each evaluation are
-concatenated in the sequence that the subexpressions are listed. If
+concatenated in the sequence that the subexpressions are listed. If
any subexpression evaluates to null, the result of the concatenation
is null.
.RE
.RS 0.25i
The two expressions are evaluated, and then the result of evaluating
the data expression is reversed in place, using hunks of the size
-specified in the numeric expression. For example, if the numeric
-expression evaluates to four, and the data expression evaluates to
+specified in the numeric expression. For example, if the numeric
+expression evaluates to four, and the data expression evaluates to
twelve bytes of data, then the reverse expression will evaluate to
twelve bytes of data, consisting of the last four bytes of the the
input data, followed by the middle four bytes, followed by the first
.RS 0.25i
Converts the result of evaluating data-expr2 into a text string
containing one number for each element of the result of evaluating
-data-expr2. Each number is separated from the other by the result of
-evaluating data-expr1. The result of evaluating numeric-expr1
+data-expr2. Each number is separated from the other by the result of
+evaluating data-expr1. The result of evaluating numeric-expr1
specifies the base (2 through 16) into which the numbers should be
-converted. The result of evaluating numeric-expr2 specifies the
+converted. The result of evaluating numeric-expr2 specifies the
width in bits of each number, which may be either 8, 16 or 32.
.PP
As an example of the preceding three types of expressions, to produce
.B pick-first-value (\fIdata-expr1\fR [ ... \fIexpr\fRn ] \fB)\fR
.RS 0.25i
The pick-first-value function takes any number of data expressions as
-its arguments. Each expression is evaluated, starting with the first
+its arguments. Each expression is evaluated, starting with the first
in the list, until an expression is found that does not evaluate to a
-null value. That expression is returned, and none of the subsequent
-expressions are evaluated. If all expressions evaluate to a null
+null value. That expression is returned, and none of the subsequent
+expressions are evaluated. If all expressions evaluate to a null
value, the null value is returned.
.RE
.PP
.RS 0.25i
The host-decl-name function returns the name of the host declaration
that matched the client whose request is currently being processed, if
-any. If no host declaration matched, the result is the null value.
+any. If no host declaration matched, the result is the null value.
.RE
.SH NUMERIC EXPRESSIONS
-Numeric expressions are expressions that evaluate to an integer. In
+Numeric expressions are expressions that evaluate to an integer. In
general, the maximum size of such an integer should not be assumed to
be representable in fewer than 32 bits, but the precision of such
integers may be more than 32 bits.
.RS 0.25i
The \fBextract-int\fR operator extracts an integer value in network
byte order from the result of evaluating the specified data
-expression. Width is the width in bits of the integer to extract.
-Currently, the only supported widths are 8, 16 and 32. If the
+expression. Width is the width in bits of the integer to extract.
+Currently, the only supported widths are 8, 16 and 32. If the
evaluation of the data expression doesn't provide sufficient bits to
extract an integer of the specified size, the null value is returned.
.RE
.B client-state
.PP
.RS 0.25i
-The current state of the client instance being processed. This is
-only useful in DHCP client configuration files. Possible values are:
+The current state of the client instance being processed. This is
+only useful in DHCP client configuration files. Possible values are:
.TP 2
.I \(bu
Booting - DHCP client is in the INIT state, and does not yet have an
-IP address. The next message transmitted will be a DHCPDISCOVER,
+IP address. The next message transmitted will be a DHCPDISCOVER,
which will be broadcast.
.TP
.I \(bu
-Reboot - DHCP client is in the INIT-REBOOT state. It has an IP
-address, but is not yet using it. The next message to be transmitted
-will be a DHCPREQUEST, which will be broadcast. If no response is
+Reboot - DHCP client is in the INIT-REBOOT state. It has an IP
+address, but is not yet using it. The next message to be transmitted
+will be a DHCPREQUEST, which will be broadcast. If no response is
heard, the client will bind to its address and move to the BOUND state.
.TP
.I \(bu
Select - DHCP client is in the SELECTING state - it has received at
least one DHCPOFFER message, but is waiting to see if it may receive
-other DHCPOFFER messages from other servers. No messages are sent in
+other DHCPOFFER messages from other servers. No messages are sent in
the SELECTING state.
.TP
.I \(bu
Request - DHCP client is in the REQUESTING state - it has received at
least one DHCPOFFER message, and has chosen which one it will
-request. The next message to be sent will be a DHCPREQUEST message,
+request. The next message to be sent will be a DHCPREQUEST message,
which will be broadcast.
.TP
.I \(bu
-Bound - DHCP client is in the BOUND state - it has an IP address. No
+Bound - DHCP client is in the BOUND state - it has an IP address. No
messages are transmitted in this state.
.TP
.I \(bu
Renew - DHCP client is in the RENEWING state - it has an IP address,
-and is trying to contact the server to renew it. The next message to
+and is trying to contact the server to renew it. The next message to
be sent will be a DHCPREQUEST message, which will be unicast directly
to the server.
.TP
.I \(bu
Rebind - DHCP client is in the REBINDING state - it has an IP address,
-and is trying to contact any server to renew it. The next message to
+and is trying to contact any server to renew it. The next message to
be sent will be a DHCPREQUEST, which will be broadcast.
.RE
.SH REFERENCE: ACTION EXPRESSIONS
such.
.PP
It is possible to use the execute statement in any context, not only
-on events. If you put it in a regular scope in the configuration file
+on events. If you put it in a regular scope in the configuration file
you will execute that command every time a scope is evaluated.
.RE
.SH REFERENCE: DYNAMIC DNS UPDATES
.\" $Id: dhcp-options.5,v 1.50 2011/05/20 13:48:32 tomasz Exp $
.\"
+.\" Copyright (c) 2012 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 2004-2010 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 1996-2003 by Internet Software Consortium
.\"
The Dynamic Host Configuration protocol allows the client to receive
.B options
from the DHCP server describing the network configuration and various
-services that are available on the network. When configuring
+services that are available on the network. When configuring
.B dhcpd(8)
or
.B dhclient(8) ,
-options must often be declared. The syntax for declaring options,
+options must often be declared. The syntax for declaring options,
and the names and formats of the options that can be declared, are
documented here.
.SH REFERENCE: OPTION STATEMENTS
.PP
DHCP \fIoption\fR statements always start with the \fIoption\fR
keyword, followed by an option name, followed by option data. The
-option names and data formats are described below. It is not
+option names and data formats are described below. It is not
necessary to exhaustively specify all DHCP options - only those
options which are needed by clients must be specified.
.PP
.PP
The
.B int32
-data type specifies a signed 32-bit integer. The
+data type specifies a signed 32-bit integer. The
.B uint32
-data type specifies an unsigned 32-bit integer. The
+data type specifies an unsigned 32-bit integer. The
.B int16
and
.B uint16
-data types specify signed and unsigned 16-bit integers. The
+data types specify signed and unsigned 16-bit integers. The
.B int8
and
.B uint8
The
.B domain-name
data type specifies a domain name, which must not be
-enclosed in double quotes. This data type is not used for any
-existing DHCP options. The domain name is stored just as if it were
+enclosed in double quotes. This data type is not used for any
+existing DHCP options. The domain name is stored just as if it were
a text option.
.PP
The
.PP
The
.B flag
-data type specifies a boolean value. Booleans can be either true or
+data type specifies a boolean value. Booleans can be either true or
false (or on or off, if that makes more sense to you).
.PP
The
.B string
data type specifies either an NVT ASCII string
enclosed in double quotes, or a series of octets specified in
-hexadecimal, separated by colons. For example:
+hexadecimal, separated by colons. For example:
.nf
.sp 1
option dhcp-client-identifier "CLIENT-FOO";
.fi
.SH SETTING OPTION VALUES USING EXPRESSIONS
Sometimes it's helpful to be able to set the value of a DHCP option
-based on some value that the client has sent. To do this, you can
-use expression evaluation. The
+based on some value that the client has sent. To do this, you can
+use expression evaluation. The
.B dhcp-eval(5)
-manual page describes how to write expressions. To assign the result
+manual page describes how to write expressions. To assign the result
of an evaluation to an option, define the option as follows:
.nf
.sp 1
.PP
Please be aware that some DHCP clients, when configured with client
identifiers that are ASCII text, will prepend a zero to the ASCII
-text. So you may need to write:
+text. So you may need to write:
.nf
option dhcp-client-identifier "\\0foo";
This option is used in a client request (DHCPDISCOVER or DHCPREQUEST)
to allow the client to request a lease time for the IP address. In a
server reply (DHCPOFFER), a DHCP server uses this option to specify
-the lease time it is willing to offer.
+the lease time it is willing to offer.
.PP
This option is not directly user configurable in the server; refer to the
\fImax-lease-time\fR and \fIdefault-lease-time\fR server options in
.RS 0.25i
.PP
This option, when sent by the client, specifies the maximum size of
-any response that the server sends to the client. When specified on
+any response that the server sends to the client. When specified on
the server, if the client did not send a dhcp-max-message-size option,
-the size specified on the server is used. This works for BOOTP as
+the size specified on the server is used. This works for BOOTP as
well as DHCP responses.
.RE
.PP
5 DHCPACK
6 DHCPNAK
7 DHCPRELEASE
- 8 DHCPINFORM
+ 8 DHCPINFORM
.fi
.PP
This option is not user configurable.
.nf
1 the \'file\' field is used to hold options
2 the \'sname\' field is used to hold options
- 3 both fields are used to hold options
+ 3 both fields are used to hold options
.fi
.PP
This option is not user configurable.
.RS 0.25i
.PP
This option, when sent by the client, specifies which options the
-client wishes the server to return. Normally, in the ISC DHCP
-client, this is done using the \fIrequest\fR statement. If this
+client wishes the server to return. Normally, in the ISC DHCP
+client, this is done using the \fIrequest\fR statement. If this
option is not specified by the client, the DHCP server will normally
return every option that is valid in scope and that fits into the
-reply. When this option is specified on the server, the server
-returns the specified options. This can be used to force a client to
+reply. When this option is specified on the server, the server
+returns the specified options. This can be used to force a client to
take options that it hasn't requested, and it can also be used to
tailor the response of the DHCP server for clients that may need a
more limited set of options than those the server would normally
.RS 0.25i
.PP
This option is used by the client in a DHCPDISCOVER to
-request that a particular IP address be assigned.
+request that a particular IP address be assigned.
.PP
This option is not user configurable.
.PP
.PP
The value of this option is the IP address of the server.
.PP
-This option is not directly user configurable. See the
+This option is not directly user configurable. See the
\fIserver-identifier\fR server option in
.B \fIdhcpd.conf(5).
.PP
.B option \fBinterface-mtu\fR \fIuint16\fR\fB;\fR
.RS 0.25i
.PP
-This option specifies the MTU to use on this interface. The minimum
+This option specifies the MTU to use on this interface. The minimum
legal value for the MTU is 68.
.RE
.PP
.RS 0.25i
.PP
The NetBIOS name server (NBNS) option specifies a list of RFC
-1001/1002 NBNS name servers listed in order of preference. NetBIOS
-Name Service is currently more commonly referred to as WINS. WINS
+1001/1002 NBNS name servers listed in order of preference. NetBIOS
+Name Service is currently more commonly referred to as WINS. WINS
servers can be specified using the netbios-name-servers option.
.RE
.PP
.RS 0.25i
.PP
A sequence of suboptions for NetWare/IP clients - see RFC2242 for
-details. Normally this option is set by specifying specific
+details. Normally this option is set by specifying specific
NetWare/IP suboptions - see the NETWARE/IP SUBOPTIONS section for more
information.
.RE
.PP
This option specifies two things: the IP addresses of one or more
Service Location Protocol Directory Agents, and whether the use of
-these addresses is mandatory. If the initial boolean value is true,
-the SLP agent should just use the IP addresses given. If the value
+these addresses is mandatory. If the initial boolean value is true,
+the SLP agent should just use the IP addresses given. If the value
is false, the SLP agent may additionally do active or passive
multicast discovery of SLP agents (see RFC2165 for details).
.PP
the list provided in this option.
.PP
The text string should be a comma-separated list of scopes that the
-SLP agent should use. It may be omitted, in which case the SLP Agent
+SLP agent should use. It may be omitted, in which case the SLP Agent
will use the aggregated list of scopes of all directory agents known
to the SLP agent.
.RE
The default route (0.0.0.0) is an illegal destination for a static
route. To specify the default route, use the
.B routers
-option. Also, please note that this option is not intended for
-classless IP routing - it does not include a subnet mask. Since
+option. Also, please note that this option is not intended for
+classless IP routing - it does not include a subnet mask. Since
classless IP routing is now the most widely deployed routing standard,
this option is virtually useless, and is not implemented by any of the
popular DHCP clients, for example the Microsoft DHCP client.
.PP
This option is used to identify a TFTP server and, if supported by the
client, should have the same effect as the \fBserver-name\fR
-declaration. BOOTP clients are unlikely to support this option.
+declaration. BOOTP clients are unlikely to support this option.
Some DHCP clients will support it, and others actually require it.
.RE
.PP
includes a URL that does not contain a port component, the normal
default port is assumed (i.e., port 80 for http and port 443 for
https). If the list includes a URL that does not contain a path
-component, the path /uap is assumed. If more than one URL is
+component, the path /uap is assumed. If more than one URL is
specified in this list, the URLs are separated by spaces.
.RE
.PP
.RS 0.25i
.PP
This option is used by some DHCP clients as a way for users to
-specify identifying information to the client. This can be used in a
+specify identifying information to the client. This can be used in a
similar way to the vendor-class-identifier option, but the value of
-the option is specified by the user, not the vendor. Most recent
+the option is specified by the user, not the vendor. Most recent
DHCP clients have a way in the user interface to specify the value for
this identifier, usually as a text string.
.RE
This option is used by some DHCP clients to identify the vendor
type and possibly the configuration of a DHCP client. The information
is a string of bytes whose contents are specific to the vendor and are
-not specified in a standard. To see what vendor class identifier
+not specified in a standard. To see what vendor class identifier
clients are sending, you can write the following in your DHCP server
configuration file:
.nf
The vendor-class-identifier option is normally used by the DHCP server
to determine the options that are returned in the
.B vendor-encapsulated-options
-option. Please see the VENDOR ENCAPSULATED OPTIONS section later in this
+option. Please see the VENDOR ENCAPSULATED OPTIONS section later in this
manual page for further information.
.RE
.PP
.PP
The \fBvendor-encapsulated-options\fR option can contain either a
single vendor-specific value or one or more vendor-specific
-suboptions. This option is not normally specified in the DHCP server
+suboptions. This option is not normally specified in the DHCP server
configuration file - instead, a vendor class is defined for each
vendor, vendor class suboptions are defined, values for those
suboptions are defined, and the DHCP server makes up a response on
.SH RELAY AGENT INFORMATION OPTION
An IETF draft, draft-ietf-dhc-agent-options-11.txt, defines a series
of encapsulated options that a relay agent can add to a DHCP packet
-when relaying it to the DHCP server. The server can then make
+when relaying it to the DHCP server. The server can then make
address allocation decisions (or whatever other decisions it wants)
-based on these options. The server also returns these options in any
+based on these options. The server also returns these options in any
replies it sends through the relay agent, so that the relay agent can
use the information in these options for delivery or accounting
purposes.
.PP
-The current draft defines two options. To reference
+The current draft defines two options. To reference
these options in the dhcp server, specify the option space name,
-"agent", followed by a period, followed by the option name. It is
+"agent", followed by a period, followed by the option name. It is
not normally useful to define values for these options in the server,
-although it is permissible. These options are not supported in the
+although it is permissible. These options are not supported in the
client.
.PP
.B option \fBagent.circuit-id\fR \fIstring\fR\fB;\fR
The circuit-id suboption encodes an agent-local identifier of the
circuit from which a DHCP client-to-server packet was received. It is
intended for use by agents in relaying DHCP responses back to the
-proper circuit. The format of this option is currently defined to be
+proper circuit. The format of this option is currently defined to be
vendor-dependent, and will probably remain that way, although the
current draft allows for for the possibility of standardizing the
format in the future.
.RS 0.25i
.PP
The remote-id suboption encodes information about the remote host end
-of a circuit. Examples of what it might contain include caller ID
+of a circuit. Examples of what it might contain include caller ID
information, username information, remote ATM address, cable modem ID,
-and similar things. In principal, the meaning is not well-specified,
+and similar things. In principal, the meaning is not well-specified,
and it should generally be assumed to be an opaque object that is
administratively guaranteed to be unique to a particular remote end of
a circuit.
.SH THE CLIENT FQDN SUBOPTIONS
The Client FQDN option, currently defined in the Internet Draft
draft-ietf-dhc-fqdn-option-00.txt is not a standard yet, but is in
-sufficiently wide use already that we have implemented it. Due to
+sufficiently wide use already that we have implemented it. Due to
the complexity of the option format, we have implemented it as a
-suboption space rather than a single option. In general this
+suboption space rather than a single option. In general this
option should not be configured by the user - instead it should be
used as part of an automatic DNS update system.
.PP
.RS 0.25i
.PP
When the client sends this, if it is true, it means the client will not
-attempt to update its A record. When sent by the server to the client,
+attempt to update its A record. When sent by the server to the client,
it means that the client \fIshould not\fR update its own A record.
.RE
.PP
.RS 0.25i
.PP
When the client sends this to the server, it is requesting that the server
-update its A record. When sent by the server, it means that the server
+update its A record. When sent by the server, it means that the server
has updated (or is about to update) the client's A record.
.RE
.PP
.RS 0.25i
.PP
If true, this indicates that the domain name included in the option is
-encoded in DNS wire format, rather than as plain ASCII text. The client
+encoded in DNS wire format, rather than as plain ASCII text. The client
normally sets this to false if it doesn't support DNS wire format in the
-FQDN option. The server should always send back the same value that the
-client sent. When this value is set on the configuration side, it controls
+FQDN option. The server should always send back the same value that the
+client sent. When this value is set on the configuration side, it controls
the format in which the \fIfqdn.fqdn\fR suboption is encoded.
.RE
.PP
.B option fqdn.fqdn \fItext\fB;
.RS 0.25i
.PP
-Specifies the domain name that the client wishes to use. This can be a
-fully-qualified domain name, or a single label. If there is no trailing
+Specifies the domain name that the client wishes to use. This can be a
+fully-qualified domain name, or a single label. If there is no trailing
\'.\' character in the name, it is not fully-qualified, and the server will
generally update that name in some locally-defined domain.
.RE
and \fBconfig-option\fR operators in an expression, in which case it returns
all labels after the first label in the \fBfqdn.fqdn\fR suboption - for
example, if the value of \fBfqdn.fqdn\fR is "foo.example.com.",
-then \fBfqdn.hostname\fR will be "example.com.". If this suboption value
+then \fBfqdn.hostname\fR will be "example.com.". If this suboption value
is not set, it means that an unqualified name was sent in the fqdn option,
or that no fqdn option was sent at all.
.RE
.RS 0.25i
.PP
If true, the client should use the NetWare Nearest Server Query to
-locate a NetWare/IP server. The behaviour of the Novell client if
+locate a NetWare/IP server. The behaviour of the Novell client if
this suboption is false, or is not present, is not specified.
.PP
.RE
.RS 0.25i
.PP
If true, the NetWare/IP client should support NetWare/IP version 1.1
-compatibility. This is only needed if the client will be contacting
+compatibility. This is only needed if the client will be contacting
Netware/IP version 1.1 servers.
.RE
.PP
.RS 0.25i
.PP
Specifies the IP address of the Primary Domain SAP/RIP Service server
-(DSS) for this NetWare/IP domain. The NetWare/IP administration
+(DSS) for this NetWare/IP domain. The NetWare/IP administration
utility uses this value as Primary DSS server when configuring a
secondary DSS server.
.RE
.RE
.SH DEFINING NEW OPTIONS
The Internet Systems Consortium DHCP client and server provide the
-capability to define new options. Each DHCP option has a name, a
-code, and a structure. The name is used by you to refer to the
-option. The code is a number, used by the DHCP server and client to
-refer to an option. The structure describes what the contents of an
+capability to define new options. Each DHCP option has a name, a
+code, and a structure. The name is used by you to refer to the
+option. The code is a number, used by the DHCP server and client to
+refer to an option. The structure describes what the contents of an
option looks like.
.PP
To define a new option, you need to choose a name for it that is not
in use for some other option - for example, you can't use "host-name"
because the DHCP protocol already defines a host-name option, which is
-documented earlier in this manual page. If an option name doesn't
+documented earlier in this manual page. If an option name doesn't
appear in this manual page, you can use it, but it's probably a good
idea to put some kind of unique string at the beginning so you can be
-sure that future options don't take your name. For example, you
+sure that future options don't take your name. For example, you
might define an option, "local-host-name", feeling some confidence
that no official DHCP option name will ever start with "local".
.PP
spaces, please contact your vendor and inform them about rfc3942.
.PP
The structure of an option is simply the format in which the option
-data appears. The ISC DHCP server currently supports a few simple
+data appears. The ISC DHCP server currently supports a few simple
types, like integers, booleans, strings and IP addresses, and it also
supports the ability to define arrays of single types or arrays of
fixed sequences of types.
and
.I new-code
should be the name you have chosen for the new option and the code you
-have chosen. The
+have chosen. The
.I definition
should be the definition of the structure of the option.
.PP
.B ;
.PP
An option of type boolean is a flag with a value of either on or off
-(or true or false). So an example use of the boolean type would be:
+(or true or false). So an example use of the boolean type would be:
.nf
option use-zephyr code 180 = boolean;
.B ;
.PP
The \fIsign\fR token should either be blank, \fIunsigned\fR
-or \fIsigned\fR. The width can be either 8, 16 or 32, and refers to
-the number of bits in the integer. So for example, the following two
+or \fIsigned\fR. The width can be either 8, 16 or 32, and refers to
+the number of bits in the integer. So for example, the following two
lines show a definition of the sql-connection-max option and its use:
.nf
.B text
.B ;
.PP
-An option whose type is text will encode an ASCII text string. For
+An option whose type is text will encode an ASCII text string. For
example:
.nf
An option whose type is a data string is essentially just a collection
of bytes, and can be specified either as quoted text, like the text
type, or as a list of hexadecimal contents separated by colons whose
-values must be between 0 and FF. For example:
+values must be between 0 and FF. For example:
.nf
option sql-identification-token code 195 = string;
.B ;
.PP
An option whose type is \fBencapsulate\fR will encapsulate the
-contents of the option space specified in \fIidentifier\fR. Examples
+contents of the option space specified in \fIidentifier\fR. Examples
of encapsulated options in the DHCP protocol as it currently exists
include the vendor-encapsulated-options option, the netware-suboptions
option and the relay-agent-information option.
.PP
Options can contain arrays of any of the above types except for the
text and data string types, which aren't currently supported in
-arrays. An example of an array definition is as follows:
+arrays. An example of an array definition is as follows:
.nf
option kerberos-servers code 200 = array of ip-address;
.B RECORDS
.PP
Options can also contain data structures consisting of a sequence of
-data types, which is sometimes called a record type. For example:
+data types, which is sometimes called a record type. For example:
.nf
option contrived-001 code 201 = { boolean, integer 32, text };
to your vendor's documentation in order to form options to their
specification.
.PP
-The value of these options can be set in one of two ways. The first
+The value of these options can be set in one of two ways. The first
way is to simply specify the data directly, using a text string or a
colon-separated list of hexadecimal values. For help in forming these
strings, please refer to \fBRFC2132\fR for the DHCPv4 \fBVendor Specific
.fi
.PP
The second way of setting the value of these options is to have the DHCP
-server generate a vendor-specific option buffer. To do this, you
+server generate a vendor-specific option buffer. To do this, you
must do four things: define an option space, define some options in
that option space, provide values for them, and specify that that
option space should be used to generate the relevant option.
this value was fixed at 9973.
.PP
The name can then be used in option definitions, as described earlier in
-this document. For example:
+this document. For example:
.nf
option space SUNW code width 1 length width 1 hash size 3;
.fi
Once you have defined an option space and the format of some options,
you can set up scopes that define values for those options, and you
-can say when to use them. For example, suppose you want to handle
-two different classes of clients. Using the option space definition
+can say when to use them. For example, suppose you want to handle
+two different classes of clients. Using the option space definition
shown in the previous example, you can send different option values to
different clients based on the vendor-class-identifier option that the
clients send, as follows:
.\" $Id: omshell.1,v 1.6 2009/11/24 02:06:56 sar Exp $
.\"
+.\" Copyright (c) 2012 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 2004,2009 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 2001-2003 by Internet Software Consortium
.\"
.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
.\" To learn more about Internet Systems Consortium, see
.\" ``https://www.isc.org/''. To learn more about Vixie Enterprises,
-.\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see
+.\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see
.\" ``http://www.nominum.com''.
.TH omshell 1
.SH NAME
query, and possibly change, the ISC DHCP Server's state via OMAPI, the Object
Management API. By using OMAPI and omshell, you do not have to stop, make
changes, and then restart the DHCP server, but can make the changes
-while the server is running. Omshell provides a way of accessing
+while the server is running. Omshell provides a way of accessing
OMAPI.
.PP
OMAPI is simply a communications mechanism that allows you to
-manipulate objects. In order to actually \fIuse\fR omshell, you
+manipulate objects. In order to actually \fIuse\fR omshell, you
.I must
understand what objects are available and how to use them.
Documentation for OMAPI objects can be found in the documentation for
.SH RESETTING ATTRIBUTES
.PP
If you want to remove an attribute from an object, you can do this with the
-\fBunset\fR command. Once you have unset an attribute, you must use the
+\fBunset\fR command. Once you have unset an attribute, you must use the
\fBupdate\fR command to update the remote object. So, if the host "some-host"
from the previous example will not have a static IP address anymore, the
commands in omshell would look like this:
.\" dhcrelay.8
.\"
-.\" Copyright (c) 2009-2011 by Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (c) 2009-2012 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 2004,2007 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 1997-2003 by Internet Software Consortium
.\"
.TP
-a
Append an agent option field to each request before forwarding it to
-the server. Agent option fields in responses sent from servers to
+the server. Agent option fields in responses sent from servers to
clients will be stripped before forwarding such responses back to the
client. The agent option field will contain two agent options: the Circuit
ID suboption and the Remote ID suboption. Currently, the Circuit ID will
.\" dhcpd.8
.\"
-.\" Copyright (c) 2009-2011 by Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (c) 2009-2012 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 2004-2007 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 1996-2003 by Internet Software Consortium
.\"
.PP
The DHCP protocol allows a host which is unknown to the network
administrator to be automatically assigned a new IP address out of a
-pool of IP addresses for its network. In order for this to work, the
+pool of IP addresses for its network. In order for this to work, the
network administrator allocates address pools in each subnet and
enters them into the dhcpd.conf(5) file.
.PP
.PP
In order to keep track of leases across system reboots and server
restarts, dhcpd keeps a list of leases it has assigned in the
-dhcpd.leases(5) file. Before dhcpd grants a lease to a host, it
+dhcpd.leases(5) file. Before dhcpd grants a lease to a host, it
records the lease in this file and makes sure that the contents of the
-file are flushed to disk. This ensures that even in the event of a
+file are flushed to disk. This ensures that even in the event of a
system crash, dhcpd will not forget about a lease that it has
-assigned. On startup, after reading the dhcpd.conf file, dhcpd
+assigned. On startup, after reading the dhcpd.conf file, dhcpd
reads the dhcpd.leases file to refresh its memory about what leases
have been assigned.
.PP
New leases are appended to the end of the dhcpd.leases
-file. In order to prevent the file from becoming arbitrarily large,
+file. In order to prevent the file from becoming arbitrarily large,
from time to time dhcpd creates a new dhcpd.leases file from its
in-core lease database. Once this file has been written to disk, the
old file is renamed
.IR dhcpd.leases~ ,
-and the new file is renamed dhcpd.leases. If the system crashes in
+and the new file is renamed dhcpd.leases. If the system crashes in
the middle of this process, whichever dhcpd.leases file remains will
contain all the lease information, so there is no need for a special
crash recovery process.
.PP
BOOTP support is also provided by this server. Unlike DHCP, the BOOTP
protocol does not provide a protocol for recovering
-dynamically-assigned addresses once they are no longer needed. It is
+dynamically-assigned addresses once they are no longer needed. It is
still possible to dynamically assign addresses to BOOTP clients, but
-some administrative process for reclaiming addresses is required. By
+some administrative process for reclaiming addresses is required. By
default, leases are granted to BOOTP clients in perpetuity, although
the network administrator may set an earlier cutoff date or a shorter
lease length for BOOTP leases if that makes sense.
BOOTP client, permanently assigning an address to each client.
.PP
Whenever changes are made to the dhcpd.conf file, dhcpd must be
-restarted. To restart dhcpd, send a SIGTERM (signal 15) to the
+restarted. To restart dhcpd, send a SIGTERM (signal 15) to the
process ID contained in
.IR RUNDIR/dhcpd.pid ,
and then re-invoke dhcpd. Because the DHCP server database is not as
lightweight as a BOOTP database, dhcpd does not automatically restart
itself when it sees a change to the dhcpd.conf file.
.PP
-Note: We get a lot of complaints about this. We realize that it would
+Note: We get a lot of complaints about this. We realize that it would
be nice if one could send a SIGHUP to the server and have it reload
-the database. This is not technically impossible, but it would
+the database. This is not technically impossible, but it would
require a great deal of work, our resources are extremely limited, and
-they can be better spent elsewhere. So please don't complain about
+they can be better spent elsewhere. So please don't complain about
this on the mailing list unless you're prepared to fund a project to
implement this feature, or prepared to do it yourself.
.SH COMMAND LINE
Send log messages to the standard error descriptor.
This can be useful for debugging, and also at sites where a
complete log of all dhcp activity must be kept but syslogd is not
-reliable or otherwise cannot be used. Normally,
+reliable or otherwise cannot be used. Normally,
.B dhcpd
will log all
output using the \fBsyslog(3)\fR function with the log facility set to
.BI \-t
Test the configuration file. The server tests the configuration file
for correct syntax, but will not attempt to perform any network
-operations. This can be used to test a new configuration file
+operations. This can be used to test a new configuration file
automatically before installing it.
.TP
.BI \-T
Test the lease file. The server tests the lease file
for correct syntax, but will not attempt to perform any network
-operations. This can be used to test a new leaes file
+operations. This can be used to test a new leaes file
automatically before installing it.
.TP
.BI \-tf \ tracefile
option it will not check for an existing server process.
.PP
.SH CONFIGURATION
-The syntax of the dhcpd.conf(5) file is discussed separately. This
+The syntax of the dhcpd.conf(5) file is discussed separately. This
section should be used as an overview of the configuration process,
and the dhcpd.conf(5) documentation should be consulted for detailed
reference information.
.PP
.SH Subnets
dhcpd needs to know the subnet numbers and netmasks of all subnets for
-which it will be providing service. In addition, in order to
+which it will be providing service. In addition, in order to
dynamically allocate addresses, it must be assigned one or more ranges
of addresses on each subnet which it can in turn assign to client
-hosts as they boot. Thus, a very simple configuration providing DHCP
+hosts as they boot. Thus, a very simple configuration providing DHCP
support might look like this:
.nf
.sp 1
.PP
.SH Lease Lengths
DHCP leases can be assigned almost any length from zero seconds to
-infinity. What lease length makes sense for any given subnet, or for
+infinity. What lease length makes sense for any given subnet, or for
any given installation, will vary depending on the kinds of hosts
being served.
.PP
For example, in an office environment where systems are added from
time to time and removed from time to time, but move relatively
infrequently, it might make sense to allow lease times of a month or
-more. In a final test environment on a manufacturing floor, it may
+more. In a final test environment on a manufacturing floor, it may
make more sense to assign a maximum lease length of 30 minutes -
enough time to go through a simple test procedure on a network
appliance before packaging it up for delivery.
.PP
It is possible to specify two lease lengths: the default length that
will be assigned if a client doesn't ask for any particular lease
-length, and a maximum lease length. These are specified as clauses
+length, and a maximum lease length. These are specified as clauses
to the subnet command:
.nf
.sp 1
.PP
This particular subnet declaration specifies a default lease time of
600 seconds (ten minutes), and a maximum lease time of 7200 seconds
-(two hours). Other common values would be 86400 (one day), 604800
+(two hours). Other common values would be 86400 (one day), 604800
(one week) and 2592000 (30 days).
.PP
Each subnet need not have the same lease\(emin the case of an office
default and maximum lease times on each subnet.
.SH BOOTP Support
Each BOOTP client must be explicitly declared in the dhcpd.conf
-file. A very basic client declaration will specify the client
+file. A very basic client declaration will specify the client
network interface's hardware address and the IP address to assign to
-that client. If the client needs to be able to load a boot file from
-the server, that file's name must be specified. A simple bootp
+that client. If the client needs to be able to load a boot file from
+the server, that file's name must be specified. A simple bootp
client declaration might look like this:
.nf
.sp 1
and so on).
.PP
These options can be specified on a per-subnet basis, and, for BOOTP
-clients, also on a per-client basis. In the event that a BOOTP
+clients, also on a per-client basis. In the event that a BOOTP
client declaration specifies options that are also specified in its
subnet declaration, the options specified in the client declaration
-take precedence. A reasonably complete DHCP configuration might
+take precedence. A reasonably complete DHCP configuration might
look something like this:
.nf
.sp 1
examine the server's current status and make changes to it.
.PP
Rather than implementing the underlying OMAPI protocol directly, user
-programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a
+programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a
wrapper that handles some of the housekeeping chores that OMAPI does
-not do automatically. Dhcpctl and OMAPI are documented in \fBdhcpctl(3)\fR
+not do automatically. Dhcpctl and OMAPI are documented in \fBdhcpctl(3)\fR
and \fBomapi(3)\fR.
.PP
-OMAPI exports objects, which can then be examined and modified. The
+OMAPI exports objects, which can then be examined and modified. The
DHCP server exports the following objects: lease, host,
-failover-state and group. Each object has a number of methods that
-are provided: lookup, create, and destroy. In addition, it is
+failover-state and group. Each object has a number of methods that
+are provided: lookup, create, and destroy. In addition, it is
possible to look at attributes that are stored on objects, and in some
cases to modify those attributes.
.SH THE LEASE OBJECT
.SH THE HOST OBJECT
Hosts can be created, destroyed, looked up, examined and modified.
If a host declaration is created or deleted using OMAPI, that
-information will be recorded in the dhcpd.leases file. It is
+information will be recorded in the dhcpd.leases file. It is
permissible to delete host declarations that are declared in the
dhcpd.conf file.
.PP
.PP
.B name \fIdata\fR lookup, examine, modify
.RS 0.5i
-the name of the host declaration. This name must be unique among all
+the name of the host declaration. This name must be unique among all
host declarations.
.RE
.PP
.B hardware-type \fIinteger\fR lookup, examine, modify
.RS 0.5i
the type of the network interface that will be used to match the
-client, if any. Only valid if hardware-address is also present.
+client, if any. Only valid if hardware-address is also present.
.RE
.PP
.B dhcp-client-identifier \fIdata\fR lookup, examine, modify
.B ip-address \fIdata\fR examine, modify
.RS 0.5i
a fixed IP address which is reserved for a DHCP client that matches
-this host declaration. The IP address will only be assigned to the
+this host declaration. The IP address will only be assigned to the
client if it is valid for the network segment to which the client is
connected.
.RE
.B known \fIinteger\fR examine, modify
.RS 0.5i
if nonzero, indicates that a client matching this host declaration
-will be treated as \fIknown\fR in pool permit lists. If zero, the
+will be treated as \fIknown\fR in pool permit lists. If zero, the
client will not be treated as known.
.RE
.SH THE GROUP OBJECT
.PP
Named groups currently can only be associated with
hosts - this allows one set of statements to be efficiently attached
-to more than one host declaration.
+to more than one host declaration.
.PP
Groups have the following attributes:
.PP
references this group is processed.
.RE
.SH THE CONTROL OBJECT
-The control object allows you to shut the server down. If the server
+The control object allows you to shut the server down. If the server
is doing failover with another peer, it will make a clean transition
into the shutdown state and notify its peer, so that the peer can go
into partner down, and then record the "recover" state in the lease
.B local-state \fIinteger\fR examine, modify
.RS 0.5i
Indicates the present state of the DHCP server in this failover
-relationship. Possible values for state are:
+relationship. Possible values for state are:
.RE
.RS 1i
.PP
In general it is not a good idea to make changes to this state.
However, in the case that the failover partner is known to be down, it
can be useful to set the DHCP server's failover state to partner
-down. At this point the DHCP server will take over service of the
+down. At this point the DHCP server will take over service of the
failover partner's leases as soon as possible, and will give out
-normal leases, not leases that are restricted by MCLT. If you do put
+normal leases, not leases that are restricted by MCLT. If you do put
the DHCP server into the partner-down when the other DHCP server is
not in the partner-down state, but is not reachable, IP address
-assignment conflicts are possible, even likely. Once a server has
+assignment conflicts are possible, even likely. Once a server has
been put into partner-down mode, its failover partner must not be
brought back online until communication is possible between the two
servers.
.B dhcpd(8)
was originally written by Ted Lemon under a contract with Vixie Labs.
Funding for this project was provided by Internet Systems
-Consortium. Version 3 of the DHCP server was funded by Nominum, Inc.
+Consortium. Version 3 of the DHCP server was funded by Nominum, Inc.
Information about Internet Systems Consortium is available at
.B https://www.isc.org/\fR.
.IR dhcpd,
the Internet Systems Consortium DHCP Server.
.PP
-The dhcpd.conf file is a free-form ASCII text file. It is parsed by
-the recursive-descent parser built into dhcpd. The file may contain
+The dhcpd.conf file is a free-form ASCII text file. It is parsed by
+the recursive-descent parser built into dhcpd. 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
+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 file essentially consists of a list of statements. Statements
+The file essentially consists of a list of statements. Statements
fall into two broad categories - parameters and declarations.
.PP
Parameter statements either say how to do something (e.g., how long a
Declarations are used to describe the topology of the
network, to describe clients on the network, to provide addresses that
can be assigned to clients, or to apply a group of parameters to a
-group of declarations. In any group of parameters and declarations,
+group of declarations. In any group of parameters and declarations,
all parameters must be specified before any declarations which depend
on those parameters may be specified.
.PP
Declarations about network topology include the \fIshared-network\fR
-and the \fIsubnet\fR declarations. If clients on a subnet are to be
+and the \fIsubnet\fR declarations. If clients on a subnet are to be
assigned addresses
dynamically, a \fIrange\fR declaration must appear within the
-\fIsubnet\fR declaration. For clients with statically assigned
+\fIsubnet\fR declaration. For clients with statically assigned
addresses, or for installations where only known clients will be
-served, each such client must have a \fIhost\fR declaration. If
+served, each such client must have a \fIhost\fR declaration. If
parameters are to be applied to a group of declarations which are not
related strictly on a per-subnet basis, the \fIgroup\fR declaration
can be used.
even if no addresses will be dynamically allocated on that subnet.
.PP
Some installations have physical networks on which more than one IP
-subnet operates. For example, if there is a site-wide requirement
+subnet operates. For example, if there is a site-wide requirement
that 8-bit subnet masks be used, but a department with a single
physical ethernet network expands to the point where it has more than
254 nodes, it may be necessary to run two 8-bit subnets on the same
-ethernet until such time as a new physical network can be added. In
+ethernet until such time as a new physical network can be added. In
this case, the \fIsubnet\fR declarations for these two networks must be
enclosed in a \fIshared-network\fR declaration.
.PP
Some sites may have departments which have clients on more than one
subnet, but it may be desirable to offer those clients a uniform set
of parameters which are different than what would be offered to
-clients from other departments on the same subnet. For clients which
+clients from other departments on the same subnet. For clients which
will be declared explicitly with \fIhost\fR declarations, these
declarations can be enclosed in a \fIgroup\fR declaration along with
-the parameters which are common to that department. For clients
+the parameters which are common to that department. For clients
whose addresses will be dynamically assigned, class declarations and
conditional declarations may be used to group parameter assignments
based on information the client sends.
consulting that client's \fIhost\fR declaration (if any), and then
consulting any \fIclass\fR declarations matching the client,
followed by the \fIpool\fR, \fIsubnet\fR and \fIshared-network\fR
-declarations for the IP address assigned to the client. Each of
+declarations for the IP address assigned to the client. Each of
these declarations itself appears within a lexical scope, and all
declarations at less specific lexical scopes are also consulted for
-client option declarations. Scopes are never considered
+client option declarations. Scopes are never considered
twice, and if parameters are declared in more than one scope, the
parameter declared in the most specific scope is the one that is
used.
When dhcpd tries to find a \fIhost\fR declaration for a client, it
first looks for a \fIhost\fR declaration which has a
\fIfixed-address\fR declaration that lists an IP address that is valid
-for the subnet or shared network on which the client is booting. If
+for the subnet or shared network on which the client is booting. If
it doesn't find any such entry, it tries to find an entry which has
no \fIfixed-address\fR declaration.
.SH EXAMPLES
.fi
.PP
Notice that at the beginning of the file, there's a place
-for global parameters. These might be things like the organization's
+for global parameters. These might be things like the organization's
domain name, the addresses of the name servers (if they are common to
-the entire organization), and so on. So, for example:
+the entire organization), and so on. So, for example:
.nf
option domain-name "isc.org";
.PP
The most obvious reason for having subnet-specific parameters as
shown in Figure 1 is that each subnet, of necessity, has its own
-router. So for the first subnet, for example, there should be
+router. So for the first subnet, for example, there should be
something like:
.nf
option routers 204.254.239.1;
.fi
.PP
-Note that the address here is specified numerically. This is not
+Note that the address here is specified numerically. This is not
required - if you have a different domain name for each interface on
your router, it's perfectly legitimate to use the domain name for that
-interface instead of the numeric address. However, in many cases
+interface instead of the numeric address. However, in many cases
there may be only one domain name for all of a router's IP addresses, and
it would not be appropriate to use that name here.
.PP
.fi
.PP
You may have noticed that while some parameters start with the
-\fIoption\fR keyword, some do not. Parameters starting with the
+\fIoption\fR keyword, some do not. Parameters starting with the
\fIoption\fR keyword correspond to actual DHCP options, while
parameters that do not start with the option keyword either control
the behavior of the DHCP server (e.g., how long a lease dhcpd will
give out), or specify client parameters that are not optional in the
DHCP protocol (for example, server-name and filename).
.PP
-In Figure 1, each host had \fIhost-specific parameters\fR. These
+In Figure 1, each host had \fIhost-specific parameters\fR. These
could include such things as the \fIhostname\fR option, the name of a
file to upload (the \fIfilename\fR parameter) and the address of the
server from which to upload the file (the \fInext-server\fR
-parameter). In general, any parameter can appear anywhere that
+parameter). In general, any parameter can appear anywhere that
parameters are allowed, and will be applied according to the scope in
which the parameter appears.
.PP
-Imagine that you have a site with a lot of NCD X-Terminals. These
+Imagine that you have a site with a lot of NCD X-Terminals. These
terminals come in a variety of models, and you want to specify the
-boot files for each model. One way to do this would be to have host
+boot files for each model. One way to do this would be to have host
declarations for each server and group them by model:
.nf
.B pool
declaration can be used to specify a pool of addresses that will be
treated differently than another pool of addresses, even on the same
-network segment or subnet. For example, you may want to provide a
+network segment or subnet. For example, you may want to provide a
large set of addresses that can be assigned to DHCP clients that are
registered to your DHCP server, while providing a smaller set of
addresses, possibly with short lease times, that are available for
-unknown clients. If you have a firewall, you may be able to arrange
+unknown clients. If you have a firewall, you may be able to arrange
for addresses from one pool to be allowed access to the Internet,
while addresses in another pool are not, thus encouraging users to
-register their DHCP clients. To do this, you would set up a pair of
+register their DHCP clients. To do this, you would set up a pair of
pool declarations:
.PP
.nf
that control which clients are allowed access to the pool and which
aren't. Each entry in a pool's permit list is introduced with the
.I allow
-or \fIdeny\fR keyword. If a pool has a permit list, then only those
+or \fIdeny\fR keyword. If a pool has a permit list, then only those
clients that match specific entries on the permit list will be
-eligible to be assigned addresses from the pool. If a pool has a
+eligible to be assigned addresses from the pool. If a pool has a
deny list, then only those clients that do not match any entries on
-the deny list will be eligible. If both permit and deny lists exist
+the deny list will be eligible. If both permit and deny lists exist
for a pool, then only clients that match the permit list and do not
match the deny list will be allowed access.
.SH DYNAMIC ADDRESS ALLOCATION
lists an IP address that is valid for the network segment to which the
client is connected. In this case, the DHCP server will never do
dynamic address allocation. In this case, the client is \fIrequired\fR
-to take the address specified in the host declaration. If the
+to take the address specified in the host declaration. If the
client sends a DHCPREQUEST for some other address, the server will respond
with a DHCPNAK.
.PP
receive the existing lease, then the server will look in the list of
address pools for the network segment to which the client is attached
for a lease that is not in use and that the client is permitted to
-have. It looks through each pool declaration in sequence (all
+have. It looks through each pool declaration in sequence (all
.I range
declarations that appear outside of pool declarations are grouped into
-a single pool with no permit list). If the permit list for the pool
+a single pool with no permit list). If the permit list for the pool
allows the client to be allocated an address from that pool, the pool
-is examined to see if there is an address available. If so, then the
-client is tentatively assigned that address. Otherwise, the next
-pool is tested. If no addresses are found that can be assigned to
+is examined to see if there is an address available. If so, then the
+client is tentatively assigned that address. Otherwise, the next
+pool is tested. If no addresses are found that can be assigned to
the client, no response is sent to the client.
.PP
If an address is found that the client is permitted to have, and that
has never been assigned to any client before, the address is
-immediately allocated to the client. If the address is available for
+immediately allocated to the client. If the address is available for
allocation but has been previously assigned to a different client, the
server will keep looking in hopes of finding an address that has never
before been assigned to a client.
.PP
The DHCP server generates the list of available IP addresses from a
-hash table. This means that the addresses are not sorted in any
+hash table. This means that the addresses are not sorted in any
particular order, and so it is not possible to predict the order in
-which the DHCP server will allocate IP addresses. Users of previous
+which the DHCP server will allocate IP addresses. Users of previous
versions of the ISC DHCP server may have become accustomed to the DHCP
server allocating IP addresses in ascending order, but this is no
longer possible, and there is no way to configure this behavior with
version 3 of the ISC DHCP server.
.SH IP ADDRESS CONFLICT PREVENTION
The DHCP server checks IP addresses to see if they are in use before
-allocating them to clients. It does this by sending an ICMP Echo
-request message to the IP address being allocated. If no ICMP Echo
+allocating them to clients. It does this by sending an ICMP Echo
+request message to the IP address being allocated. If no ICMP Echo
reply is received within a second, the address is assumed to be free.
This is only done for leases that have been specified in range
statements, and only when the lease is thought by the DHCP server to
.PP
If a response is received to an ICMP Echo request, the DHCP server
assumes that there is a configuration error - the IP address is in use
-by some host on the network that is not a DHCP client. It marks the
+by some host on the network that is not a DHCP client. It marks the
address as abandoned, and will not assign it to clients.
.PP
If a DHCP client tries to get an IP address, but none are available,
but there are abandoned IP addresses, then the DHCP server will
-attempt to reclaim an abandoned IP address. It marks one IP address
+attempt to reclaim an abandoned IP address. It marks one IP address
as free, and then does the same ICMP Echo request check described
-previously. If there is no answer to the ICMP Echo request, the
+previously. If there is no answer to the ICMP Echo request, the
address is assigned to the client.
.PP
The DHCP server does not cycle through abandoned IP addresses if the
-first IP address it tries to reclaim is free. Rather, when the next
+first IP address it tries to reclaim is free. Rather, when the next
DHCPDISCOVER comes in from the client, it will attempt a new
allocation using the same method described here, and will typically
try a new IP address.
.SH DHCP FAILOVER
This version of the ISC DHCP server supports the DHCP failover
-protocol as documented in draft-ietf-dhc-failover-12.txt. This is
+protocol as documented in draft-ietf-dhc-failover-12.txt. This is
not a final protocol document, and we have not done interoperability
testing with other vendors' implementations of this protocol, so you
must not assume that this implementation conforms to the standard.
peers are running the same version of the ISC DHCP server.
.PP
The failover protocol allows two DHCP servers (and no more than two)
-to share a common address pool. Each server will have about half of
+to share a common address pool. Each server will have about half of
the available IP addresses in the pool at any given time for
-allocation. If one server fails, the other server will continue to
+allocation. If one server fails, the other server will continue to
renew leases out of the pool, and will allocate new addresses out of
the roughly half of available addresses that it had when
communications with the other server were lost.
It is possible during a prolonged failure to tell the remaining server
that the other server is down, in which case the remaining server will
(over time) reclaim all the addresses the other server had available
-for allocation, and begin to reuse them. This is called putting the
+for allocation, and begin to reuse them. This is called putting the
server into the PARTNER-DOWN state.
.PP
You can put the server into the PARTNER-DOWN state either by using the
.B omshell (1)
command or by stopping the server, editing the last failover state
-declaration in the lease file, and restarting the server. If you use
+declaration in the lease file, and restarting the server. If you use
this last method, change the "my state" line to:
.PP
.nf
and the other server comes back up, the other server will not know
that the first server was in the PARTNER-DOWN state, and may issue
addresses previously issued by the other server to different clients,
-resulting in IP address conflicts. Before putting a server into
+resulting in IP address conflicts. Before putting a server into
PARTNER-DOWN state, therefore, make
.I sure
that the other server will not restart automatically.
.PP
The failover protocol defines a primary server role and a secondary
-server role. There are some differences in how primaries and
+server role. There are some differences in how primaries and
secondaries act, but most of the differences simply have to do with
providing a way for each peer to behave in the opposite way from the
-other. So one server must be configured as primary, and the other
+other. So one server must be configured as primary, and the other
must be configured as secondary, and it doesn't matter too much which
one is which.
.SH FAILOVER STARTUP
When a server starts that has not previously communicated with its
failover peer, it must establish communications with its failover peer
-and synchronize with it before it can serve clients. This can happen
+and synchronize with it before it can serve clients. This can happen
either because you have just configured your DHCP servers to perform
failover for the first time, or because one of your failover servers
has failed catastrophically and lost its database.
.PP
In the case where both servers detect that they have never before
communicated with their partner, they both come up in this recovery
-state and follow the procedure we have just described. In this case,
+state and follow the procedure we have just described. In this case,
no service will be provided to DHCP clients until MCLT has expired.
.SH CONFIGURING FAILOVER
In order to configure failover, you need to write a peer declaration
that configures the failover protocol, and you need to write peer
references in each pool declaration for which you want to do
-failover. You do not have to do failover for all pools on a given
-network segment. You must not tell one server it's doing failover
-on a particular address pool and tell the other it is not. You must
+failover. You do not have to do failover for all pools on a given
+network segment. You must not tell one server it's doing failover
+on a particular address pool and tell the other it is not. You must
not have any common address pools on which you are not doing
failover. A pool declaration that utilizes failover would look like this:
.PP
.PP
The \fBmax-response-delay\fR statement tells the DHCP server how
many seconds may pass without receiving a message from its failover
-peer before it assumes that connection has failed. This number
+peer before it assumes that connection has failed. This number
should be small enough that a transient network failure that breaks
the connection will not result in the servers being out of
communication for a long time, but large enough that the server isn't
-constantly making and breaking connections. This parameter must be
+constantly making and breaking connections. This parameter must be
specified.
.RE
.PP
.PP
The \fBmax-unacked-updates\fR statement tells the remote DHCP server how
many BNDUPD messages it can send before it receives a BNDACK
-from the local system. We don't have enough operational experience
-to say what a good value for this is, but 10 seems to work. This
+from the local system. We don't have enough operational experience
+to say what a good value for this is, but 10 seems to work. This
parameter must be specified.
.RE
.PP
.PP
.B mclt \fIseconds\fR\fB;\fR
.PP
-The \fBmclt\fR statement defines the Maximum Client Lead Time. It
+The \fBmclt\fR statement defines the Maximum Client Lead Time. It
must be specified on the primary, and may not be specified on the
-secondary. This is the length of time for which a lease may be
-renewed by either failover peer without contacting the other. The
+secondary. This is the length of time for which a lease may be
+renewed by either failover peer without contacting the other. The
longer you set this, the longer it will take for the running server to
-recover IP addresses after moving into PARTNER-DOWN state. The
+recover IP addresses after moving into PARTNER-DOWN state. The
shorter you set it, the more load your servers will experience when
-they are not communicating. A value of something like 3600 is
+they are not communicating. A value of something like 3600 is
probably reasonable, but again bear in mind that we have no real
operational experience with this.
.RE
.B split \fIindex\fR\fB;\fR
.PP
The split statement specifies the split between the primary and
-secondary for the purposes of load balancing. Whenever a client
+secondary for the purposes of load balancing. Whenever a client
makes a DHCP request, the DHCP server runs a hash on the client
identification, resulting in value from 0 to 255. This is used as
an index into a 256 bit field. If the bit at that index is set,
.PP
The hba statement specifies the split between the primary and
secondary as a bitmap rather than a cutoff, which theoretically allows
-for finer-grained control. In practice, there is probably no need
-for such fine-grained control, however. An example hba statement:
+for finer-grained control. In practice, there is probably no need
+for such fine-grained control, however. An example hba statement:
.PP
.nf
hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:
.RE
.SH CLIENT CLASSING
Clients can be separated into classes, and treated differently
-depending on what class they are in. This separation can be done
+depending on what class they are in. This separation can be done
either with a conditional statement, or with a match statement within
-the class declaration. It is possible to specify a limit on the
+the class declaration. It is possible to specify a limit on the
total number of clients within a particular class or subclass that may
hold leases at one time, and it is possible to specify automatic
subclassing based on the contents of the client packet.
.PP
Note that whether you use matching expressions or add statements (or
both) to classify clients, you must always write a class declaration
-for any class that you use. If there will be no match statement and
+for any class that you use. If there will be no match statement and
no in-scope statements for a class, the declaration should look like
this:
.PP
.fi
.SH SUBCLASSES
.PP
-In addition to classes, it is possible to declare subclasses. A
+In addition to classes, it is possible to declare subclasses. A
subclass is a class with the same name as a regular class, but with a
specific submatch expression which is hashed for quick matching.
This is essentially a speed hack - the main difference between five
classes with match expressions and one class with five subclasses is
-that it will be quicker to find the subclasses. Subclasses work as
+that it will be quicker to find the subclasses. Subclasses work as
follows:
.PP
.nf
The data following the class name in the subclass declaration is a
constant value to use in matching the match expression for the class.
When class matching is done, the server will evaluate the match
-expression and then look the result up in the hash table. If it
+expression and then look the result up in the hash table. If it
finds a match, the client is considered a member of both the class and
the subclass.
.PP
-Subclasses can be declared with or without scope. In the above
+Subclasses can be declared with or without scope. In the above
example, the sole purpose of the subclass is to allow some clients
access to one address pool, while other clients are given access to
-the other pool, so these subclasses are declared without scopes. If
+the other pool, so these subclasses are declared without scopes. If
part of the purpose of the subclass were to define different parameter
values for some clients, you might want to declare some subclasses
with scopes.
.SH PER-CLASS LIMITS ON DYNAMIC ADDRESS ALLOCATION
.PP
You may specify a limit to the number of clients in a class that can
-be assigned leases. The effect of this will be to make it difficult
-for a new client in a class to get an address. Once a class with
+be assigned leases. The effect of this will be to make it difficult
+for a new client in a class to get an address. Once a class with
such a limit has reached its limit, the only way a new client in that
class can get a lease is for an existing client to relinquish its
lease, either by letting it expire, or by sending a DHCPRELEASE
-packet. Classes with lease limits are specified as follows:
+packet. Classes with lease limits are specified as follows:
.PP
.nf
class "limited-1" {
It is possible to declare a
.I spawning class\fR.
A spawning class is a class that automatically produces subclasses
-based on what the client sends. The reason that spawning classes
+based on what the client sends. The reason that spawning classes
were created was to make it possible to create lease-limited classes
-on the fly. The envisioned application is a cable-modem environment
+on the fly. The envisioned application is a cable-modem environment
where the ISP wishes to provide clients at a particular site with more
than one IP address, but does not wish to provide such clients with
their own subnet, nor give them an unlimited number of IP addresses
.PP
Many cable modem head-end systems can be configured to add a Relay
Agent Information option to DHCP packets when relaying them to the
-DHCP server. These systems typically add a circuit ID or remote ID
-option that uniquely identifies the customer site. To take advantage
+DHCP server. These systems typically add a circuit ID or remote ID
+option that uniquely identifies the customer site. To take advantage
of this, you can write a class declaration as follows:
.PP
.nf
.fi
.PP
Now whenever a request comes in from a customer site, the circuit ID
-option will be checked against the class's hash table. If a subclass
+option will be checked against the class's hash table. If a subclass
is found that matches the circuit ID, the client will be classified in
-that subclass and treated accordingly. If no subclass is found
+that subclass and treated accordingly. If no subclass is found
matching the circuit ID, a new one will be created and logged in the
.B dhcpd.leases
-file, and the client will be classified in this new class. Once the
+file, and the client will be classified in this new class. Once the
client has been classified, it will be treated according to the rules
of the class, including, in this case, being subject to the per-site
limit of four leases.
.PP
In some cases, it may be useful to use one expression to assign a
client to a particular class, and a second expression to put it into a
-subclass of that class. This can be done by combining the \fBmatch
+subclass of that class. This can be done by combining the \fBmatch
if\fR and \fBspawn with\fR statements, or the \fBmatch if\fR and
-\fBmatch\fR statements. For example:
+\fBmatch\fR statements. For example:
.PP
.nf
class "jr-cable-modems" {
accept updates from the DHCP server.
.PP
Two DNS update schemes are currently implemented, and another is
-planned. The two that are currently implemented are the ad-hoc DNS
+planned. The two that are currently implemented are the ad-hoc DNS
update mode and the interim DHCP-DNS interaction draft update mode.
In the future we plan to add a third mode which will be the standard
DNS update method based on the RFCS for DHCP-DNS interaction and DHCID
the ISC DHCP server is a prototype design, which does not
have much to do with the standard update method that is being
standardized in the IETF DHC working group, but rather implements some
-very basic, yet useful, update capabilities. This mode
+very basic, yet useful, update capabilities. This mode
.B does not work
with the
.I failover protocol
servers updating the same set of DNS records.
.PP
For the ad-hoc DNS update method, the client's FQDN is derived in two
-parts. First, the hostname is determined. Then, the domain name is
+parts. First, the hostname is determined. Then, the domain name is
determined, and appended to the hostname.
.PP
The DHCP server determines the client's hostname by first looking for
The client's fully-qualified domain name, derived as we have
described, is used as the name on which an "A" record will be stored.
The A record will contain the IP address that the client was assigned
-in its lease. If there is already an A record with the same name in
+in its lease. If there is already an A record with the same name in
the DNS server, no update of either the A or PTR records will occur -
this prevents a client from claiming that its hostname is the name of
-some network server. For example, if you have a fileserver called
+some network server. For example, if you have a fileserver called
"fs.sneedville.edu", and the client claims its hostname is "fs", no
DNS update will be done for that client, and an error message will be
logged.
.PP
If the A record update succeeds, a PTR record update for the assigned
-IP address will be done, pointing to the A record. This update is
+IP address will be done, pointing to the A record. This update is
unconditional - it will be done even if another PTR record of the same
-name exists. Since the IP address has been assigned to the DHCP
+name exists. Since the IP address has been assigned to the DHCP
server, this should be safe.
.PP
Please note that the current implementation assumes clients only have
-a single network interface. A client with two network interfaces
-will see unpredictable behavior. This is considered a bug, and will
-be fixed in a later release. It may be helpful to enable the
+a single network interface. A client with two network interfaces
+will see unpredictable behavior. This is considered a bug, and will
+be fixed in a later release. It may be helpful to enable the
.I one-lease-per-client
parameter so that roaming clients do not trigger this same behavior.
.PP
The DHCP protocol normally involves a four-packet exchange - first the
client sends a DHCPDISCOVER message, then the server sends a
DHCPOFFER, then the client sends a DHCPREQUEST, then the server sends
-a DHCPACK. In the current version of the server, the server will do
+a DHCPACK. In the current version of the server, the server will do
a DNS update after it has received the DHCPREQUEST, and before it has
-sent the DHCPACK. It only sends the DNS update if it has not sent
+sent the DHCPACK. It only sends the DNS update if it has not sent
one for the client's address before, in order to minimize the impact
on the DHCP server.
.PP
When the client's lease expires, the DHCP server (if it is operating
at the time, or when next it operates) will remove the client's A and
-PTR records from the DNS database. If the client releases its lease
+PTR records from the DNS database. If the client releases its lease
by sending a DHCPRELEASE message, the server will likewise remove the
A and PTR records.
.SH THE INTERIM DNS UPDATE SCHEME
.PP
The first point to understand about this style of DNS update is that
unlike the ad-hoc style, the DHCP server does not necessarily
-always update both the A and the PTR records. The FQDN option
+always update both the A and the PTR records. The FQDN option
includes a flag which, when sent by the client, indicates that the
-client wishes to update its own A record. In that case, the server
+client wishes to update its own A record. In that case, the server
can be configured either to honor the client's intentions or ignore
-them. This is done with the statement \fIallow client-updates;\fR or
-the statement \fIignore client-updates;\fR. By default, client
+them. This is done with the statement \fIallow client-updates;\fR or
+the statement \fIignore client-updates;\fR. By default, client
updates are allowed.
.PP
If the server is configured to allow client updates, then if the
client sends a fully-qualified domain name in the FQDN option, the
server will use that name the client sent in the FQDN option to update
-the PTR record. For example, let us say that the client is a visitor
-from the "radish.org" domain, whose hostname is "jschmoe". The
-server is for the "example.org" domain. The DHCP client indicates in
-the FQDN option that its FQDN is "jschmoe.radish.org.". It also
-indicates that it wants to update its own A record. The DHCP server
+the PTR record. For example, let us say that the client is a visitor
+from the "radish.org" domain, whose hostname is "jschmoe". The
+server is for the "example.org" domain. The DHCP client indicates in
+the FQDN option that its FQDN is "jschmoe.radish.org.". It also
+indicates that it wants to update its own A record. The DHCP server
therefore does not attempt to set up an A record for the client, but
does set up a PTR record for the IP address that it assigns the
-client, pointing at jschmoe.radish.org. Once the DHCP client has an
+client, pointing at jschmoe.radish.org. Once the DHCP client has an
IP address, it can update its own A record, assuming that the
"radish.org" DNS server will allow it to do so.
.PP
or the hostname option (if present). It will use its own
domain name for the client, just as in the ad-hoc update scheme.
It will then update both the A and PTR record, using the name that it
-chose for the client. If the client sends a fully-qualified domain
+chose for the client. If the client sends a fully-qualified domain
name in the fqdn option, the server uses only the leftmost part of the
domain name - in the example above, "jschmoe" instead of
"jschmoe.radish.org".
scheme is that with the interim scheme, a method is used that
allows more than one DHCP server to update the DNS database without
accidentally deleting A records that shouldn't be deleted nor failing
-to add A records that should be added. The scheme works as follows:
+to add A records that should be added. The scheme works as follows:
.PP
When the DHCP server issues a client a new lease, it creates a text
string that is an MD5 hash over the DHCP client's identification (see
-draft-ietf-dnsext-dhcid-rr-??.txt for details). The update adds an A
+draft-ietf-dnsext-dhcid-rr-??.txt for details). The update adds an A
record with the name the server chose and a TXT record containing the
-hashed identifier string (hashid). If this update succeeds, the
+hashed identifier string (hashid). If this update succeeds, the
server is done.
.PP
If the update fails because the A record already exists, then the DHCP
server attempts to add the A record with the prerequisite that there
must be a TXT record in the same name as the new A record, and that
-TXT record's contents must be equal to hashid. If this update
-succeeds, then the client has its A record and PTR record. If it
+TXT record's contents must be equal to hashid. If this update
+succeeds, then the client has its A record and PTR record. If it
fails, then the name the client has been assigned (or requested) is in
-use, and can't be used by the client. At this point the DHCP server
+use, and can't be used by the client. At this point the DHCP server
gives up trying to do a DNS update for the client until the client
chooses a new name.
.PP
The interim DNS update scheme is called interim for two reasons.
-First, it does not quite follow the RFCs. The RFCs call for a
+First, it does not quite follow the RFCs. The RFCs call for a
new DHCID RRtype while he interim DNS update scheme uses a TXT record.
The ddns-resolution draft called for the DHCP server to put a DHCID RR
on the PTR record, but the \fIinterim\fR update method does not do this.
In addition to these differences, the server also does not update very
aggressively. Because each DNS update involves a round trip to the
DNS server, there is a cost associated with doing updates even if they
-do not actually modify the DNS database. So the DHCP server tracks
+do not actually modify the DNS database. So the DHCP server tracks
whether or not it has updated the record in the past (this information
is stored on the lease) and does not attempt to update records that it
thinks it has already updated.
This can lead to cases where the DHCP server adds a record, and then
the record is deleted through some other mechanism, but the server
never again updates the DNS because it thinks the data is already
-there. In this case the data can be removed from the lease through
+there. In this case the data can be removed from the lease through
operator intervention, and once this has been done, the DNS will be
updated the next time the client renews.
.SH DYNAMIC DNS UPDATE SECURITY
When you set your DNS server up to allow updates from the DHCP server,
you may be exposing it to unauthorized updates. To avoid this, you
should use TSIG signatures - a method of cryptographically signing
-updates using a shared secret key. As long as you protect the
-secrecy of this key, your updates should also be secure. Note,
+updates using a shared secret key. As long as you protect the
+secrecy of this key, your updates should also be secure. Note,
however, that the DHCP protocol itself provides no security, and that
clients can therefore provide information to the DHCP server which the
DHCP server will then use in its updates, with the constraints
.fi
.PP
You will also have to configure your DHCP server to do updates to
-these zones. To do so, you need to add something like this to your
+these zones. To do so, you need to add something like this to your
dhcpd.conf file:
.PP
.nf
.PP
Note that the zone declarations have to correspond to authority
records in your name server - in the above example, there must be an
-SOA record for "example.org." and for "17.10.10.in-addr.arpa.". For
+SOA record for "example.org." and for "17.10.10.in-addr.arpa.". For
example, if there were a subdomain "foo.example.org" with no separate
SOA, you could not write a zone declaration for "foo.example.org."
Also keep in mind that zone names in your DHCP configuration should end in a
.fi
.PP
You must create the /var/log/named-auth.info and
-/var/log/update-debug.log files before starting the name server. For
+/var/log/update-debug.log files before starting the name server. For
more information on configuring ISC BIND, consult the documentation
that accompanies it.
.SH REFERENCE: EVENTS
.PP
There are three kinds of events that can happen regarding a lease, and
it is possible to declare statements that occur when any of these
-events happen. These events are the commit event, when the server
+events happen. These events are the commit event, when the server
has made a commitment of a certain lease to a client, the release
event, when the client has released the server from its commitment,
and the expiry event, when the commitment expires.
To declare a set of statements to execute when an event happens, you
must use the \fBon\fR statement, followed by the name of the event,
followed by a series of statements to execute when the event happens,
-enclosed in braces. Events are used to implement DNS
+enclosed in braces. Events are used to implement DNS
updates, so you should not define your own event handlers if you are
using the built-in DNS update mechanism.
.PP
The built-in version of the DNS update mechanism is in a text
-string towards the top of server/dhcpd.c. If you want to use events
+string towards the top of server/dhcpd.c. If you want to use events
for things other than DNS updates, and you also want DNS updates, you
will have to start out by copying this code into your dhcpd.conf file
and modifying it.
client should boot.
.PP
.I Name
-should be the name of the shared network. This name is used when
+should be the name of the shared network. This name is used when
printing debugging messages, so it should be descriptive for the
-shared network. The name may have the syntax of a valid domain name
+shared network. The name may have the syntax of a valid domain name
(although it will never be used as such), or it may be any arbitrary
name, enclosed in quotes.
.PP
information to tell whether or not an IP address is on that subnet.
It may also be used to provide subnet-specific parameters and to
specify what addresses may be dynamically allocated to clients booting
-on that subnet. Such addresses are specified using the \fIrange\fR
+on that subnet. Such addresses are specified using the \fIrange\fR
declaration.
.PP
The
.I subnet-number
should be an IP address or domain name which resolves to the subnet
-number of the subnet being described. The
+number of the subnet being described. The
.I netmask
should be an IP address or domain name which resolves to the subnet mask
-of the subnet being described. The subnet number, together with the
+of the subnet being described. The subnet number, together with the
netmask, are sufficient to determine whether any given IP address is
on the specified subnet.
.PP
.fi
.PP
For any subnet on which addresses will be assigned dynamically, there
-must be at least one \fIrange\fR statement. The range statement
-gives the lowest and highest IP addresses in a range. All IP
+must be at least one \fIrange\fR statement. The range statement
+gives the lowest and highest IP addresses in a range. All IP
addresses in the range should be in the subnet in which the
-\fIrange\fR statement is declared. The \fIdynamic-bootp\fR flag may
+\fIrange\fR statement is declared. The \fIdynamic-bootp\fR flag may
be specified if addresses in the specified range may be dynamically
-assigned to BOOTP clients as well as DHCP clients. When specifying a
+assigned to BOOTP clients as well as DHCP clients. When specifying a
single address, \fIhigh-address\fR can be omitted.
.PP
.B The
\fIhost\fR declaration or the client does not provide a
\fRdhcp-client-identifier\fR option, by matching the \fIhardware\fR
parameter in the \fIhost\fR declaration to the network hardware
-address supplied by the client. BOOTP clients do not normally
+address supplied by the client. BOOTP clients do not normally
provide a \fIdhcp-client-identifier\fR, so the hardware address must
be used for all clients that may boot using the BOOTP protocol.
.PP
.B only
the \fIdhcp-client-identifier\fR option and the hardware address can be
used to match a host declaration, or the \fIhost-identifier option\fR
-parameter for DHCPv6 servers. For example, it is not possible to
-match a host declaration to a \fIhost-name\fR option. This is
+parameter for DHCPv6 servers. For example, it is not possible to
+match a host declaration to a \fIhost-name\fR option. This is
because the host-name option cannot be guaranteed to be unique for any
given client, whereas both the hardware address and
\fIdhcp-client-identifier\fR option are at least theoretically
.fi
.PP
The group statement is used simply to apply one or more parameters to
-a group of declarations. It can be used to group hosts, shared
+a group of declarations. It can be used to group hosts, shared
networks, subnets, or even other groups.
.SH REFERENCE: ALLOW AND DENY
The
different meanings depending on the context. In a pool context, these
keywords can be used to set up access lists for address allocation
pools. In other contexts, the keywords simply control general server
-behavior with respect to clients based on scope. In a non-pool
+behavior with respect to clients based on scope. In a non-pool
context, the
.I ignore
keyword can be used in place of the
\fBignore unknown-clients;\fR
.PP
The \fBunknown-clients\fR flag is used to tell dhcpd whether
-or not to dynamically assign addresses to unknown clients. Dynamic
+or not to dynamically assign addresses to unknown clients. Dynamic
address assignment to unknown clients is \fBallow\fRed by default.
An unknown client is simply a client that has no host declaration.
.PP
.PP
The \fBbooting\fR flag is used to tell dhcpd whether or not to respond
to queries from a particular client. This keyword only has meaning
-when it appears in a host declaration. By default, booting is
+when it appears in a host declaration. By default, booting is
\fBallow\fRed, but if it is disabled for a particular client, then
that client will not be able to get an address from the DHCP server.
.PP
.PP
Host declarations can match client messages based on the DHCP Client
Identifier option or based on the client's network hardware type and
-MAC address. If the MAC address is used, the host declaration will
+MAC address. If the MAC address is used, the host declaration will
match any client with that MAC address - even clients with different
-client identifiers. This doesn't normally happen, but is possible
+client identifiers. This doesn't normally happen, but is possible
when one computer has more than one operating system installed on it -
for example, Microsoft Windows and NetBSD or Linux.
.PP
The \fBduplicates\fR flag tells the DHCP server that if a request is
received from a client that matches the MAC address of a host
declaration, any other leases matching that MAC address should be
-discarded by the server, even if the UID is not the same. This is a
+discarded by the server, even if the UID is not the same. This is a
violation of the DHCP protocol, but can prevent clients whose client
identifiers change regularly from holding many leases at the same time.
By default, duplicates are \fBallow\fRed.
\fBignore declines;\fR
.PP
The DHCPDECLINE message is used by DHCP clients to indicate that the
-lease the server has offered is not valid. When the server receives
+lease the server has offered is not valid. When the server receives
a DHCPDECLINE for a particular address, it normally abandons that
address, assuming that some unauthorized system is using it.
Unfortunately, a malicious or buggy client can, using DHCPDECLINE
-messages, completely exhaust the DHCP server's allocation pool. The
+messages, completely exhaust the DHCP server's allocation pool. The
server will reclaim these leases, but while the client is running
through the pool, it may cause serious thrashing in the DNS, and it
will also cause the DHCP server to forget old DHCP client address
allocations.
.PP
The \fBdeclines\fR flag tells the DHCP server whether or not to honor
-DHCPDECLINE messages. If it is set to \fBdeny\fR or \fBignore\fR in
+DHCPDECLINE messages. If it is set to \fBdeny\fR or \fBignore\fR in
a particular scope, the DHCP server will not respond to DHCPDECLINE
messages.
.PP
.PP
The \fBclient-updates\fR flag tells the DHCP server whether or not to
honor the client's intention to do its own update of its A record.
-This is only relevant when doing \fIinterim\fR DNS updates. See the
+This is only relevant when doing \fIinterim\fR DNS updates. See the
documentation under the heading THE INTERIM DNS UPDATE SCHEME for
details.
.PP
DHCPDISCOVER or a DHCPREQUEST message - an address will be allocated
to the client (either the old address it's requesting, or a new
address) and then that address will be tested to see if it's okay to
-let the client have it. If the client requested it, and it's not
-okay, the server will send a DHCPNAK message. Otherwise, the server
-will simply not respond to the client. If it is okay to give the
+let the client have it. If the client requested it, and it's not
+okay, the server will send a DHCPNAK message. Otherwise, the server
+will simply not respond to the client. If it is okay to give the
address to the client, the server will send a DHCPACK message.
.PP
The primary motivation behind pool declarations is to have address
-allocation pools whose allocation policies are different. A client
+allocation pools whose allocation policies are different. A client
may be denied access to one pool, but allowed access to another pool
-on the same network segment. In order for this to work, access
+on the same network segment. In order for this to work, access
control has to be done during address allocation, not after address
allocation is done.
.PP
.PP
If specified, this statement either allows or prevents allocation from
this pool to any client that has been authenticated using the DHCP
-authentication protocol. This is not yet supported.
+authentication protocol. This is not yet supported.
.PP
\fBunauthenticated clients;\fR
.PP
If specified, this statement either allows or prevents allocation from
this pool to any client that has not been authenticated using the DHCP
-authentication protocol. This is not yet supported.
+authentication protocol. This is not yet supported.
.PP
\fBall clients;\fR
.PP
If specified, this statement either allows or prevents allocation from
-this pool to all clients. This can be used when you want to write a
+this pool to all clients. This can be used when you want to write a
pool declaration for some reason, but hold it in reserve, or when you
want to renumber your network quickly, and thus want the server to
force all clients that have been allocated addresses from this pool to
The DHCP and BOOTP protocols both require DHCP and BOOTP clients to
set the broadcast bit in the flags field of the BOOTP message header.
Unfortunately, some DHCP and BOOTP clients do not do this, and
-therefore may not receive responses from the DHCP server. The DHCP
+therefore may not receive responses from the DHCP server. The DHCP
server can be made to always broadcast its responses to clients by
setting this flag to \'on\' for the relevant scope; relevant scopes would be
inside a conditional statement, as a parameter for a class, or as a parameter
-for a host declaration. To avoid creating excess broadcast traffic on your
+for a host declaration. To avoid creating excess broadcast traffic on your
network, we recommend that you restrict the use of this option to as few
-clients as possible. For example, the Microsoft DHCP client is known not
+clients as possible. For example, the Microsoft DHCP client is known not
to have this problem, as are the OpenTransport and ISC DHCP clients.
.RE
.PP
.B always-reply-rfc1048 \fIflag\fR\fB;\fR
.PP
Some BOOTP clients expect RFC1048-style responses, but do not follow
-RFC1048 when sending their requests. You can tell that a client is
+RFC1048 when sending their requests. You can tell that a client is
having this problem if it is not getting the options you have
configured for it and if you see in the server log the message
"(non-rfc1048)" printed with each BOOTREQUEST that is logged.
If you want to send rfc1048 options to such a client, you can set the
.B always-reply-rfc1048
option in that client's host declaration, and the DHCP server will
-respond with an RFC-1048-style vendor options field. This flag can
+respond with an RFC-1048-style vendor options field. This flag can
be set in any scope, and will affect all clients covered by that
scope.
.RE
Network administrators setting up authoritative DHCP servers for their
networks should always write \fBauthoritative;\fR at the top of their
configuration file to indicate that the DHCP server \fIshould\fR send
-DHCPNAK messages to misconfigured clients. If this is not done,
+DHCPNAK messages to misconfigured clients. If this is not done,
clients will be unable to get a correct IP address after changing
subnets until their old lease has expired, which could take quite a
long time.
.PP
Usually, writing \fBauthoritative;\fR at the top level of the file
-should be sufficient. However, if a DHCP server is to be set up so
+should be sufficient. However, if a DHCP server is to be set up so
that it is aware of some networks for which it is authoritative and
some networks for which it is not, it may be more appropriate to
declare authority on a per-network-segment basis.
If the \fIboot-unknown-clients\fR statement is present and has a value
of \fIfalse\fR or \fIoff\fR, then clients for which there is no
.I host
-declaration will not be allowed to obtain IP addresses. If this
+declaration will not be allowed to obtain IP addresses. If this
statement is not present or has a value of \fItrue\fR or \fIon\fR,
then clients without host declarations will be allowed to obtain IP
addresses, as long as those addresses are not restricted by
.B ddns-hostname \fIname\fB;\fR
.PP
The \fIname\fR parameter should be the hostname that will be used in
-setting up the client's A and PTR records. If no ddns-hostname is
+setting up the client's A and PTR records. If no ddns-hostname is
specified in scope, then the server will derive the hostname
automatically, using an algorithm that varies for each of the
different update methods.
.B ddns-rev-domainname \fIname\fB;\fR
The \fIname\fR parameter should be the domain name that will be
appended to the client's reversed IP address to produce a name for use
-in the client's PTR record. By default, this is "in-addr.arpa.", but
+in the client's PTR record. By default, this is "in-addr.arpa.", but
the default can be overridden here.
.PP
The reversed IP address to which this domain name is appended is
always the IP address of the client, in dotted quad notation, reversed
- for example, if the IP address assigned to the client is
-10.17.92.74, then the reversed IP address is 74.92.17.10. So a
+10.17.92.74, then the reversed IP address is 74.92.17.10. So a
client with that IP address would, by default, be given a PTR record
of 10.17.92.74.in-addr.arpa.
.RE
\fBddns-updates \fIflag\fR\fB;\fR
.PP
The \fIddns-updates\fR parameter controls whether or not the server will
-attempt to do a DNS update when a lease is confirmed. Set this to \fIoff\fR
+attempt to do a DNS update when a lease is confirmed. Set this to \fIoff\fR
if the server should not attempt to do updates within a certain scope.
-The \fIddns-updates\fR parameter is on by default. To disable DNS
+The \fIddns-updates\fR parameter is on by default. To disable DNS
updates in all scopes, it is preferable to use the
\fIddns-update-style\fR statement, setting the style to \fInone\fR.
.RE
.PP
The \fIdo-forward-updates\fR statement instructs the DHCP server as
to whether it should attempt to update a DHCP client's A record
-when the client acquires or renews a lease. This statement has no
+when the client acquires or renews a lease. This statement has no
effect unless DNS updates are enabled and \fBddns-update-style\fR is
-set to \fBinterim\fR. Forward updates are enabled by default. If
+set to \fBinterim\fR. Forward updates are enabled by default. If
this statement is used to disable forward updates, the DHCP server
will never attempt to update the client's A record, and will only ever
attempt to update the client's PTR record if the client supplies an
.B dynamic-bootp-lease-length\fR \fIlength\fR\fB;\fR
.PP
The \fIdynamic-bootp-lease-length\fR statement is used to set the
-length of leases dynamically assigned to BOOTP clients. At some
+length of leases dynamically assigned to BOOTP clients. At some
sites, it may be possible to assume that a lease is no longer in
use if its holder has not used BOOTP or DHCP to get its address within
-a certain time period. The period is specified in \fIlength\fR as a
-number of seconds. If a client reboots using BOOTP during the
+a certain time period. The period is specified in \fIlength\fR as a
+number of seconds. If a client reboots using BOOTP during the
timeout period, the lease duration is reset to \fIlength\fR, so a
BOOTP client that boots frequently enough will never lose its lease.
Needless to say, this parameter should be adjusted with extreme
or not to look up the domain name corresponding to the IP address of
each address in the lease pool and use that address for the DHCP
\fIhostname\fR option. If \fIflag\fR is true, then this lookup is
-done for all addresses in the current scope. By default, or if
+done for all addresses in the current scope. By default, or if
\fIflag\fR is false, no lookups are done.
.RE
.PP
.I host
statement.
.I hardware-type
-must be the name of a physical hardware interface type. Currently,
+must be the name of a physical hardware interface type. Currently,
only the
.B ethernet
and
The
.I hardware-address
should be a set of hexadecimal octets (numbers from 0 through ff)
-separated by colons. The \fIhardware\fR statement may also be used
+separated by colons. The \fIhardware\fR statement may also be used
for DHCP clients.
.RE
.PP
.B lease-file-name \fIname\fB;\fR
.PP
.I Name
-should be the name of the DHCP server's lease file. By default, this
-is DBDIR/dhcpd.leases. This statement \fBmust\fR appear in the outer
+should be the name of the DHCP server's lease file. By default, this
+is DBDIR/dhcpd.leases. This statement \fBmust\fR appear in the outer
scope of the configuration file - if it appears in some other scope,
it will have no effect. Furthermore, it has no effect if overridden
by the
.B log-facility \fIfacility\fB;\fR
.PP
This statement causes the DHCP server to do all of its logging on the
-specified log facility once the dhcpd.conf file has been read. By
-default the DHCP server logs to the daemon facility. Possible log
+specified log facility once the dhcpd.conf file has been read. By
+default the DHCP server logs to the daemon facility. Possible log
facilities include auth, authpriv, cron, daemon, ftp, kern, lpr, mail,
mark, news, ntp, security, syslog, user, uucp, and local0 through
-local7. Not all of these facilities are available on all systems,
+local7. Not all of these facilities are available on all systems,
and there may be other facilities available on other systems.
.PP
In addition to setting this value, you may need to modify your
.I syslog.conf
-file to configure logging of the DHCP server. For example, you might
+file to configure logging of the DHCP server. For example, you might
add a line like this:
.PP
.nf
should be the minimum number of seconds since a client began trying to
acquire a new lease before the DHCP server will respond to its request.
The number of seconds is based on what the client reports, and the maximum
-value that the client can report is 255 seconds. Generally, setting this
+value that the client can report is 255 seconds. Generally, setting this
to one will result in the DHCP server not responding to the client's first
request, but always responding to its second request.
.PP
This can be used
to set up a secondary DHCP server which never offers an address to a client
-until the primary server has been given a chance to do so. If the primary
+until the primary server has been given a chance to do so. If the primary
server is down, the client will bind to the secondary server, but otherwise
-clients should always bind to the primary. Note that this does not, by
+clients should always bind to the primary. Note that this does not, by
itself, permit a primary server and a secondary server to share a pool of
dynamically-allocatable addresses.
.RE
.PP
The \fInext-server\fR statement is used to specify the host address of
the server from which the initial boot file (specified in the
-\fIfilename\fR statement) is to be loaded. \fIServer-name\fR should
+\fIfilename\fR statement) is to be loaded. \fIServer-name\fR should
be a numeric IP address or a domain name.
.RE
.PP
.B omapi-port\fR \fIport\fR\fB;\fR
.PP
The \fIomapi-port\fR statement causes the DHCP server to listen for
-OMAPI connections on the specified port. This statement is required
+OMAPI connections on the specified port. This statement is required
to enable the OMAPI protocol, which is used to examine and modify the
state of the DHCP server as it is running.
.RE
.PP
If this flag is enabled, whenever a client sends a DHCPREQUEST for a
particular lease, the server will automatically free any other leases
-the client holds. This presumes that when the client sends a
+the client holds. This presumes that when the client sends a
DHCPREQUEST, it has forgotten any lease not mentioned in the
DHCPREQUEST - i.e., the client has only a single network interface
.I and
it does not remember leases it's holding on networks to which it is
-not currently attached. Neither of these assumptions are guaranteed
+not currently attached. Neither of these assumptions are guaranteed
or provable, so we urge caution in the use of this statement.
.RE
.PP
.I name\fR\fB;\fR
.PP
.I Name
-should be the name of the DHCP server's process ID file. This is the
+should be the name of the DHCP server's process ID file. This is the
file in which the DHCP server's process ID is stored when the server
-starts. By default, this is RUNDIR/dhcpd.pid. Like the
+starts. By default, this is RUNDIR/dhcpd.pid. Like the
.I lease-file-name
statement, this statement must appear in the outer scope
of the configuration file. It has no effect if overridden by the
.PP
When the DHCP server is considering dynamically allocating an IP
address to a client, it first sends an ICMP Echo request (a \fIping\fR)
-to the address being assigned. It waits for a second, and if no
-ICMP Echo response has been heard, it assigns the address. If a
+to the address being assigned. It waits for a second, and if no
+ICMP Echo response has been heard, it assigns the address. If a
response \fIis\fR heard, the lease is abandoned, and the server does
not respond to the client.
.PP
This \fIping check\fR introduces a default one-second delay in responding
-to DHCPDISCOVER messages, which can be a problem for some clients. The
+to DHCPDISCOVER messages, which can be a problem for some clients. The
default delay of one second may be configured using the ping-timeout
parameter. The ping-check configuration parameter can be used to control
checking - if its value is false, no ping check is done.
.B server-identifier \fIhostname\fR\fB;\fR
.PP
The server-identifier statement can be used to define the value that
-is sent in the DHCP Server Identifier option for a given scope. The
+is sent in the DHCP Server Identifier option for a given scope. The
value specified \fBmust\fR be an IP address for the DHCP server, and
must be reachable by all clients served by a particular scope.
.PP
The use of the server-identifier statement is not recommended - the only
reason to use it is to force a value other than the default value to be
-sent on occasions where the default value would be incorrect. The default
+sent on occasions where the default value would be incorrect. The default
value is the first IP address associated with the physical network interface
on which the request arrived.
.PP
.B server-name "\fIname\fB";\fR
.PP
The \fIserver-name\fR statement can be used to inform the client of
-the name of the server from which it is booting. \fIName\fR should
+the name of the server from which it is booting. \fIName\fR should
be the name that will be provided to the client.
.RE
.PP
.B site-option-space "\fIname\fB";\fR
.PP
The \fIsite-option-space\fR statement can be used to determine from
-what option space site-local options will be taken. This can be used
+what option space site-local options will be taken. This can be used
in much the same way as the \fIvendor-option-space\fR statement.
Site-local options in DHCP are those options whose numeric codes are
-greater than 224. These options are intended for site-specific
+greater than 224. These options are intended for site-specific
uses, but are frequently used by vendors of embedded hardware that
-contains DHCP clients. Because site-specific options are allocated
+contains DHCP clients. Because site-specific options are allocated
on an ad hoc basis, it is quite possible that one vendor's DHCP client
might use the same option code that another vendor's client uses, for
-different purposes. The \fIsite-option-space\fR option can be used
+different purposes. The \fIsite-option-space\fR option can be used
to assign a different set of site-specific options for each such
vendor, using conditional evaluation (see \fBdhcp-eval (5)\fR for
details).
the server will record the relay agent information options sent during
the client's initial DHCPREQUEST message when the client was in the
SELECTING state and behave as if those options are included in all
-subsequent DHCPREQUEST messages sent in the RENEWING state. This
+subsequent DHCPREQUEST messages sent in the RENEWING state. This
works around a problem with relay agent information options, which is
that they usually not appear in DHCPREQUEST messages sent by the
client in the RENEWING state, because such messages are unicast
If the \fIupdate-optimization\fR parameter is false for a given client,
the server will attempt a DNS update for that client each time the
client renews its lease, rather than only attempting an update when it
-appears to be necessary. This will allow the DNS to heal from
+appears to be necessary. This will allow the DNS to heal from
database inconsistencies more easily, but the cost is that the DHCP
-server must do many more DNS updates. We recommend leaving this option
+server must do many more DNS updates. We recommend leaving this option
enabled, which is the default. This option only affects the behavior of
the interim DNS update scheme, and has no effect on the ad-hoc DNS update
-scheme. If this parameter is not specified, or is true, the DHCP server
+scheme. If this parameter is not specified, or is true, the DHCP server
will only update when the client information changes, the client gets a
different lease, or the client's lease expires.
.RE
The \fIupdate-static-leases\fR flag, if enabled, causes the DHCP
server to do DNS updates for clients even if those clients are being
assigned their IP address using a \fIfixed-address\fR statement - that
-is, the client is being given a static assignment. This can only
-work with the \fIinterim\fR DNS update scheme. It is not
+is, the client is being given a static assignment. This can only
+work with the \fIinterim\fR DNS update scheme. It is not
recommended because the DHCP server has no way to tell that the update
has been done, and therefore will not delete the record when it is not
-in use. Also, the server must attempt the update each time the
+in use. Also, the server must attempt the update each time the
client renews its lease, which could have a significant performance
impact in environments that place heavy demands on the DHCP server.
.RE
If the \fIuse-host-decl-names\fR parameter is true in a given scope,
then for every host declaration within that scope, the name provided
for the host declaration will be supplied to the client as its
-hostname. So, for example,
+hostname. So, for example,
.PP
.nf
group {
.PP
It should be noted here that most DHCP clients completely ignore the
host-name option sent by the DHCP server, and there is no way to
-configure them not to do this. So you generally have a choice of
+configure them not to do this. So you generally have a choice of
either not having any hostname to client IP address mapping that the
-client will recognize, or doing DNS updates. It is beyond
+client will recognize, or doing DNS updates. It is beyond
the scope of this document to describe how to make this
determination.
.RE
If the \fIuse-lease-addr-for-default-route\fR parameter is true in a
given scope, then instead of sending the value specified in the
routers option (or sending no value at all), the IP address of the
-lease being assigned is sent to the client. This supposedly causes
+lease being assigned is sent to the client. This supposedly causes
Win95 machines to ARP for all IP addresses, which can be helpful if
-your router is configured for proxy ARP. The use of this feature is
+your router is configured for proxy ARP. The use of this feature is
not recommended, because it won't work for many DHCP clients.
.RE
.PP
.B vendor-option-space \fIstring\fR\fB;\fR
.PP
The \fIvendor-option-space\fR parameter determines from what option
-space vendor options are taken. The use of this configuration
+space vendor options are taken. The use of this configuration
parameter is illustrated in the \fBdhcp-options(5)\fR manual page, in
the \fIVENDOR ENCAPSULATED OPTIONS\fR section.
.RE
.SH SETTING PARAMETER VALUES USING EXPRESSIONS
Sometimes it's helpful to be able to set the value of a DHCP server
-parameter based on some value that the client has sent. To do this,
-you can use expression evaluation. The
+parameter based on some value that the client has sent. To do this,
+you can use expression evaluation. The
.B dhcp-eval(5)
-manual page describes how to write expressions. To assign the result
+manual page describes how to write expressions. To assign the result
of an evaluation to an option, define the option as follows:
.nf
.sp 1
.SH AUTHOR
.B dhcpd.conf(5)
was written by Ted Lemon
-under a contract with Vixie Labs. Funding
+under a contract with Vixie Labs. Funding
for this project was provided by Internet Systems Consortium.
Information about Internet Systems Consortium can be found at
.B https://www.isc.org.
projects / thirdparty / dhcp.git / commitdiff
