|
Packit |
1bcf14 |
.\" dhclient-script.8
|
|
Packit |
1bcf14 |
.\"
|
|
Packit |
1bcf14 |
.\" Copyright (c) 2012,2014,2016 by Internet Systems Consortium, Inc. ("ISC")
|
|
Packit |
1bcf14 |
.\" Copyright (c) 2009-2010 by Internet Systems Consortium, Inc. ("ISC")
|
|
Packit |
1bcf14 |
.\" Copyright (c) 2004-2005 by Internet Systems Consortium, Inc. ("ISC")
|
|
Packit |
1bcf14 |
.\" Copyright (c) 1996-2003 by Internet Software Consortium
|
|
Packit |
1bcf14 |
.\"
|
|
Packit |
1bcf14 |
.\" Permission to use, copy, modify, and distribute this software for any
|
|
Packit |
1bcf14 |
.\" purpose with or without fee is hereby granted, provided that the above
|
|
Packit |
1bcf14 |
.\" copyright notice and this permission notice appear in all copies.
|
|
Packit |
1bcf14 |
.\"
|
|
Packit |
1bcf14 |
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
|
|
Packit |
1bcf14 |
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
Packit |
1bcf14 |
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
|
|
Packit |
1bcf14 |
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
Packit |
1bcf14 |
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
Packit |
1bcf14 |
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
|
|
Packit |
1bcf14 |
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
Packit |
1bcf14 |
.\"
|
|
Packit |
1bcf14 |
.\" Internet Systems Consortium, Inc.
|
|
Packit |
1bcf14 |
.\" 950 Charter Street
|
|
Packit |
1bcf14 |
.\" Redwood City, CA 94063
|
|
Packit |
1bcf14 |
.\" <info@isc.org>
|
|
Packit |
1bcf14 |
.\" https://www.isc.org/
|
|
Packit |
1bcf14 |
.\"
|
|
Packit |
1bcf14 |
.\" Support and other services are available for ISC products - see
|
|
Packit |
1bcf14 |
.\" https://www.isc.org for more information or to learn more about ISC.
|
|
Packit |
1bcf14 |
.\"
|
|
Packit |
1bcf14 |
.\" $Id: dhclient-script.8,v 1.14 2010/07/02 23:09:14 sar Exp $
|
|
Packit |
1bcf14 |
.\"
|
|
Packit |
1bcf14 |
.TH dhclient-script 8
|
|
Packit |
1bcf14 |
.SH NAME
|
|
Packit |
1bcf14 |
dhclient-script - DHCP client network configuration script
|
|
Packit |
1bcf14 |
.SH DESCRIPTION
|
|
Packit |
1bcf14 |
The DHCP client network configuration script is invoked from time to
|
|
Packit |
1bcf14 |
time by \fBdhclient(8)\fR. This script is used by the dhcp client to
|
|
Packit |
1bcf14 |
set each interface's initial configuration prior to requesting an
|
|
Packit |
1bcf14 |
address, to test the address once it has been offered, and to set the
|
|
Packit |
1bcf14 |
interface's final configuration once a lease has been acquired. If no
|
|
Packit |
1bcf14 |
lease is acquired, the script is used to test predefined leases, if
|
|
Packit |
1bcf14 |
any, and also called once if no valid lease can be identified.
|
|
Packit |
1bcf14 |
.PP
|
|
Packit |
1bcf14 |
This script is not meant to be customized by the end user. If local
|
|
Packit |
1bcf14 |
customizations are needed, they should be possible using the enter and
|
|
Packit |
1bcf14 |
exit hooks provided (see HOOKS for details). These hooks will allow the
|
|
Packit |
1bcf14 |
user to override the default behaviour of the client in creating a
|
|
Packit |
1bcf14 |
.B /etc/resolv.conf
|
|
Packit Service |
671ddb |
file, and to handle DHCP options not handled by default.
|
|
Packit |
1bcf14 |
.PP
|
|
Packit |
1bcf14 |
No standard client script exists for some operating systems, even though
|
|
Packit |
1bcf14 |
the actual client may work, so a pioneering user may well need to create
|
|
Packit |
1bcf14 |
a new script or modify an existing one. In general, customizations specific
|
|
Packit |
1bcf14 |
to a particular computer should be done in the
|
|
Packit Service |
425adf |
.B /etc/dhcp/dhclient.conf
|
|
Packit |
1bcf14 |
file. If you find that you can't make such a customization without
|
|
Packit |
1bcf14 |
customizing
|
|
Packit Service |
425adf |
.B /etc/dhcp/dhclient.conf
|
|
Packit |
1bcf14 |
or using the enter and exit hooks, please submit a bug report.
|
|
Packit |
1bcf14 |
.SH HOOKS
|
|
Packit |
1bcf14 |
When it starts, the client script first defines a shell function,
|
|
Packit |
1bcf14 |
.B make_resolv_conf ,
|
|
Packit |
1bcf14 |
which is later used to create the
|
|
Packit |
1bcf14 |
.B /etc/resolv.conf
|
|
Packit |
1bcf14 |
file. To override the default behaviour, redefine this function in
|
|
Packit |
1bcf14 |
the enter hook script.
|
|
Packit |
1bcf14 |
.PP
|
|
Packit |
1bcf14 |
On after defining the make_resolv_conf function, the client script checks
|
|
Packit |
1bcf14 |
for the presence of an executable
|
|
Packit Service |
425adf |
.B /etc/dhcp/dhclient-enter-hooks
|
|
Packit |
1bcf14 |
script, and if present, it invokes the script inline, using the Bourne
|
|
Packit |
1bcf14 |
shell \'.\' command. The entire environment documented under OPERATION
|
|
Packit |
1bcf14 |
is available to this script, which may modify the environment if needed
|
|
Packit |
1bcf14 |
to change the behaviour of the script. If an error occurs during the
|
|
Packit |
1bcf14 |
execution of the script, it can set the exit_status variable to a nonzero
|
|
Packit |
1bcf14 |
value, and
|
|
Packit Service |
425adf |
.B /usr/sbin/dhclient-script
|
|
Packit |
1bcf14 |
will exit with that error code immediately after the client script exits.
|
|
Packit |
1bcf14 |
.PP
|
|
Packit |
1bcf14 |
After all processing has completed,
|
|
Packit Service |
425adf |
.B /usr/sbin/dhclient-script
|
|
Packit |
1bcf14 |
checks for the presence of an executable
|
|
Packit Service |
425adf |
.B /etc/dhcp/dhclient-exit-hooks
|
|
Packit |
1bcf14 |
script, which if present is invoked using the \'.\' command. The exit
|
|
Packit |
1bcf14 |
status of dhclient-script will be passed to dhclient-exit-hooks in the
|
|
Packit |
1bcf14 |
exit_status shell variable, and will always be zero if the script
|
|
Packit |
1bcf14 |
succeeded at the task for which it was invoked. The rest of the
|
|
Packit |
1bcf14 |
environment as described previously for dhclient-enter-hooks is also
|
|
Packit |
1bcf14 |
present. The
|
|
Packit Service |
425adf |
.B /etc/dhcp/dhclient-exit-hooks
|
|
Packit |
1bcf14 |
script can modify the valid of exit_status to change the exit status
|
|
Packit |
1bcf14 |
of dhclient-script.
|
|
Packit Service |
671ddb |
.PP
|
|
Packit Service |
671ddb |
Immediately after dhclient brings an interface UP with a new IP address,
|
|
Packit Service |
671ddb |
subnet mask, and routes, in the REBOOT/BOUND states, it will check for the
|
|
Packit Service |
671ddb |
existence of an executable
|
|
Packit Service |
425adf |
.B /etc/dhcp/dhclient-up-hooks
|
|
Packit Service |
671ddb |
script, and source it if found. This script can handle DHCP options in
|
|
Packit Service |
671ddb |
the environment that are not handled by default. A per-interface.
|
|
Packit Service |
425adf |
.B /etc/dhcp/dhclient-${IF}-up-hooks
|
|
Packit Service |
671ddb |
script will override the generic script and be sourced when interface
|
|
Packit Service |
671ddb |
$IF has been brought up.
|
|
Packit Service |
671ddb |
.PP
|
|
Packit Service |
671ddb |
Immediately before dhclient brings an interface DOWN, removing its IP
|
|
Packit Service |
671ddb |
address, subnet mask, and routes, in the STOP/RELEASE states, it will
|
|
Packit Service |
671ddb |
check for the existence of an executable
|
|
Packit Service |
425adf |
.B /etc/dhcp/dhclient-down-hooks
|
|
Packit Service |
671ddb |
script, and source it if found. This script can handle DHCP options in
|
|
Packit Service |
671ddb |
the environment that are not handled by default. A per-interface
|
|
Packit Service |
425adf |
.B /etc/dhcp/dhclient-${IF}-down-hooks
|
|
Packit Service |
671ddb |
script will override the generic script and be sourced when interface
|
|
Packit Service |
671ddb |
$IF is about to be brought down.
|
|
Packit |
1bcf14 |
.SH OPERATION
|
|
Packit |
1bcf14 |
When dhclient needs to invoke the client configuration script, it
|
|
Packit |
1bcf14 |
defines a set of variables in the environment, and then invokes
|
|
Packit Service |
425adf |
.B /usr/sbin/dhclient-script.
|
|
Packit |
1bcf14 |
In all cases, $reason is set to the name of the reason why the script
|
|
Packit |
1bcf14 |
has been invoked. The following reasons are currently defined:
|
|
Packit |
1bcf14 |
MEDIUM, PREINIT, BOUND, RENEW, REBIND, REBOOT, EXPIRE, FAIL, STOP, RELEASE,
|
|
Packit |
1bcf14 |
NBI and TIMEOUT.
|
|
Packit |
1bcf14 |
.PP
|
|
Packit |
1bcf14 |
.SH MEDIUM
|
|
Packit |
1bcf14 |
The DHCP client is requesting that an interface's media type
|
|
Packit |
1bcf14 |
be set. The interface name is passed in $interface, and the media
|
|
Packit |
1bcf14 |
type is passed in $medium.
|
|
Packit |
1bcf14 |
.SH PREINIT
|
|
Packit |
1bcf14 |
The DHCP client is requesting that an interface be configured as
|
|
Packit |
1bcf14 |
required in order to send packets prior to receiving an actual
|
|
Packit |
1bcf14 |
address. For clients which use the BSD socket library, this means
|
|
Packit |
1bcf14 |
configuring the interface with an IP address of 0.0.0.0 and a
|
|
Packit |
1bcf14 |
broadcast address of 255.255.255.255. For other clients, it may be
|
|
Packit |
1bcf14 |
possible to simply configure the interface up without actually giving
|
|
Packit |
1bcf14 |
it an IP address at all. The interface name is passed in $interface,
|
|
Packit |
1bcf14 |
and the media type in $medium.
|
|
Packit |
1bcf14 |
.PP
|
|
Packit |
1bcf14 |
If an IP alias has been declared in dhclient.conf, its address will be
|
|
Packit |
1bcf14 |
passed in $alias_ip_address, and that ip alias should be deleted from
|
|
Packit |
1bcf14 |
the interface, along with any routes to it.
|
|
Packit |
1bcf14 |
.SH BOUND
|
|
Packit |
1bcf14 |
The DHCP client has done an initial binding to a new address. The
|
|
Packit |
1bcf14 |
new ip address is passed in $new_ip_address, and the interface name is
|
|
Packit |
1bcf14 |
passed in $interface. The media type is passed in $medium. Any
|
|
Packit |
1bcf14 |
options acquired from the server are passed using the option name
|
|
Packit |
1bcf14 |
described in \fBdhcp-options\fR, except that dashes (\'-\') are replaced
|
|
Packit |
1bcf14 |
by underscores (\'_\') in order to make valid shell variables, and the
|
|
Packit |
1bcf14 |
variable names start with new_. So for example, the new subnet mask
|
|
Packit |
1bcf14 |
would be passed in $new_subnet_mask. Options from a non-default
|
|
Packit |
1bcf14 |
universe will have the universe name prepended to the option name, for
|
|
Packit |
1bcf14 |
example $new_dhcp6_server_id. The options that the client
|
|
Packit |
1bcf14 |
explicitly requested via a PRL or ORO option are passed with the same
|
|
Packit |
1bcf14 |
option name as above but prepended with requested_ and with a value of 1,
|
|
Packit |
1bcf14 |
for example requested_subnet_mask=1. No such variable is defined for
|
|
Packit |
1bcf14 |
options not requested by the client or options that don't require a
|
|
Packit |
1bcf14 |
request option, such as the ip address (*_ip_address) or expiration
|
|
Packit |
1bcf14 |
time (*_expiry).
|
|
Packit |
1bcf14 |
.PP
|
|
Packit |
1bcf14 |
Before actually configuring the address, dhclient-script should
|
|
Packit |
1bcf14 |
somehow ARP for it and exit with a nonzero status if it receives a
|
|
Packit |
1bcf14 |
reply. In this case, the client will send a DHCPDECLINE message to
|
|
Packit |
1bcf14 |
the server and acquire a different address. This may also be done in
|
|
Packit |
1bcf14 |
the RENEW, REBIND, or REBOOT states, but is not required, and indeed
|
|
Packit |
1bcf14 |
may not be desirable.
|
|
Packit |
1bcf14 |
.PP
|
|
Packit |
1bcf14 |
When a binding has been completed, a lot of network parameters are
|
|
Packit |
1bcf14 |
likely to need to be set up. A new /etc/resolv.conf needs to be
|
|
Packit |
1bcf14 |
created, using the values of $new_domain_name and
|
|
Packit |
1bcf14 |
$new_domain_name_servers (which may list more than one server,
|
|
Packit |
1bcf14 |
separated by spaces). A default route should be set using
|
|
Packit |
1bcf14 |
$new_routers, and static routes may need to be set up using
|
|
Packit |
1bcf14 |
$new_static_routes.
|
|
Packit |
1bcf14 |
.PP
|
|
Packit |
1bcf14 |
If an IP alias has been declared, it must be set up here. The alias
|
|
Packit |
1bcf14 |
IP address will be written as $alias_ip_address, and other DHCP
|
|
Packit |
1bcf14 |
options that are set for the alias (e.g., subnet mask) will be passed
|
|
Packit |
1bcf14 |
in variables named as described previously except starting with
|
|
Packit |
1bcf14 |
$alias_ instead of $new_. Care should be taken that the alias IP
|
|
Packit |
1bcf14 |
address not be used if it is identical to the bound IP address
|
|
Packit |
1bcf14 |
($new_ip_address), since the other alias parameters may be incorrect
|
|
Packit |
1bcf14 |
in this case.
|
|
Packit |
1bcf14 |
.SH RENEW
|
|
Packit |
1bcf14 |
When a binding has been renewed, the script is called as in BOUND,
|
|
Packit |
1bcf14 |
except that in addition to all the variables starting with $new_, and
|
|
Packit |
1bcf14 |
$requested_ there is another set of variables starting with $old_.
|
|
Packit |
1bcf14 |
Persistent settings that may have changed need to be deleted - for
|
|
Packit |
1bcf14 |
example, if a local route to the bound address is being configured,
|
|
Packit |
1bcf14 |
the old local route should be deleted. If the default route has changed,
|
|
Packit |
1bcf14 |
the old default route should be deleted. If the static routes have changed,
|
|
Packit |
1bcf14 |
the old ones should be deleted. Otherwise, processing can be done as with
|
|
Packit |
1bcf14 |
BOUND.
|
|
Packit |
1bcf14 |
.SH REBIND
|
|
Packit |
1bcf14 |
The DHCP client has rebound to a new DHCP server. This can be handled
|
|
Packit |
1bcf14 |
as with RENEW, except that if the IP address has changed, the ARP
|
|
Packit |
1bcf14 |
table should be cleared.
|
|
Packit |
1bcf14 |
.SH REBOOT
|
|
Packit |
1bcf14 |
The DHCP client has successfully reacquired its old address after a
|
|
Packit |
1bcf14 |
reboot. This can be processed as with BOUND.
|
|
Packit |
1bcf14 |
.SH EXPIRE
|
|
Packit |
1bcf14 |
The DHCP client has failed to renew its lease or acquire a new one,
|
|
Packit |
1bcf14 |
and the lease has expired. The IP address must be relinquished, and
|
|
Packit |
1bcf14 |
all related parameters should be deleted, as in RENEW and REBIND.
|
|
Packit |
1bcf14 |
.SH FAIL
|
|
Packit |
1bcf14 |
The DHCP client has been unable to contact any DHCP servers, and any
|
|
Packit |
1bcf14 |
leases that have been tested have not proved to be valid. The
|
|
Packit |
1bcf14 |
parameters from the last lease tested should be deconfigured. This
|
|
Packit |
1bcf14 |
can be handled in the same way as EXPIRE.
|
|
Packit |
1bcf14 |
.SH STOP
|
|
Packit |
1bcf14 |
The dhclient has been informed to shut down gracefully, the
|
|
Packit |
1bcf14 |
dhclient-script should unconfigure or shutdown the interface as
|
|
Packit |
1bcf14 |
appropriate.
|
|
Packit |
1bcf14 |
.SH RELEASE
|
|
Packit |
1bcf14 |
The dhclient has been executed using the -r flag, indicating that the
|
|
Packit |
1bcf14 |
administrator wishes it to release its lease(s). dhclient-script should
|
|
Packit |
1bcf14 |
unconfigure or shutdown the interface.
|
|
Packit |
1bcf14 |
.SH NBI
|
|
Packit |
1bcf14 |
No-Broadcast-Interfaces...dhclient was unable to find any interfaces
|
|
Packit |
1bcf14 |
upon which it believed it should commence DHCP. What dhclient-script
|
|
Packit |
1bcf14 |
should do in this situation is entirely up to the implementor.
|
|
Packit |
1bcf14 |
.SH TIMEOUT
|
|
Packit |
1bcf14 |
The DHCP client has been unable to contact any DHCP servers.
|
|
Packit |
1bcf14 |
However, an old lease has been identified, and its parameters have
|
|
Packit |
1bcf14 |
been passed in as with BOUND. The client configuration script should
|
|
Packit |
1bcf14 |
test these parameters and, if it has reason to believe they are valid,
|
|
Packit |
1bcf14 |
should exit with a value of zero. If not, it should exit with a
|
|
Packit |
1bcf14 |
nonzero value.
|
|
Packit |
1bcf14 |
.PP
|
|
Packit |
1bcf14 |
The usual way to test a lease is to set up the network as with REBIND
|
|
Packit |
1bcf14 |
(since this may be called to test more than one lease) and then ping
|
|
Packit |
1bcf14 |
the first router defined in $routers. If a response is received, the
|
|
Packit |
1bcf14 |
lease must be valid for the network to which the interface is
|
|
Packit |
1bcf14 |
currently connected. It would be more complete to try to ping all of
|
|
Packit |
1bcf14 |
the routers listed in $new_routers, as well as those listed in
|
|
Packit |
1bcf14 |
$new_static_routes, but current scripts do not do this.
|
|
Packit |
1bcf14 |
.SH FILES
|
|
Packit |
1bcf14 |
Each operating system should generally have its own script file,
|
|
Packit |
1bcf14 |
although the script files for similar operating systems may be similar
|
|
Packit |
1bcf14 |
or even identical. The script files included in Internet
|
|
Packit |
1bcf14 |
Systems Consortium DHCP distribution appear in the distribution tree
|
|
Packit |
1bcf14 |
under client/scripts, and bear the names of the operating systems on
|
|
Packit |
1bcf14 |
which they are intended to work.
|
|
Packit |
1bcf14 |
.SH BUGS
|
|
Packit |
1bcf14 |
If more than one interface is being used, there's no obvious way to
|
|
Packit |
1bcf14 |
avoid clashes between server-supplied configuration parameters - for
|
|
Packit |
1bcf14 |
example, the stock dhclient-script rewrites /etc/resolv.conf. If
|
|
Packit |
1bcf14 |
more than one interface is being configured, /etc/resolv.conf will be
|
|
Packit |
1bcf14 |
repeatedly initialized to the values provided by one server, and then
|
|
Packit |
1bcf14 |
the other. Assuming the information provided by both servers is
|
|
Packit |
1bcf14 |
valid, this shouldn't cause any real problems, but it could be
|
|
Packit |
1bcf14 |
confusing.
|
|
Packit Service |
2adf35 |
.PP
|
|
Packit Service |
2adf35 |
Normally, if dhclient was compiled with libcap-ng support,
|
|
Packit Service |
2adf35 |
dhclient drops most capabilities immediately upon startup.
|
|
Packit Service |
2adf35 |
While more secure, this greatly restricts the additional actions that
|
|
Packit Service |
2adf35 |
hooks in dhclient-script can take. For example, any daemons that
|
|
Packit Service |
2adf35 |
dhclient-script starts or restarts will inherit the restricted
|
|
Packit Service |
2adf35 |
capabilities as well, which may interfere with their correct operation.
|
|
Packit Service |
2adf35 |
Thus, the
|
|
Packit Service |
2adf35 |
.BI \-nc
|
|
Packit Service |
2adf35 |
option can be used to prevent dhclient from dropping capabilities.
|
|
Packit |
1bcf14 |
.SH SEE ALSO
|
|
Packit |
1bcf14 |
dhclient(8), dhcpd(8), dhcrelay(8), dhclient.conf(5) and
|
|
Packit |
1bcf14 |
dhclient.leases(5).
|
|
Packit |
1bcf14 |
.SH AUTHOR
|
|
Packit |
1bcf14 |
.B dhclient-script(8)
|
|
Packit |
1bcf14 |
To learn more about Internet Systems Consortium,
|
|
Packit |
1bcf14 |
see
|
|
Packit |
1bcf14 |
.B https://www.isc.org.
|