Annotation of embedaddon/dhcp/client/dhclient-script.8, revision 1.1
1.1 ! misho 1: .\" dhclient-script.8
! 2: .\"
! 3: .\" Copyright (c) 2009-2010 by Internet Systems Consortium, Inc. ("ISC")
! 4: .\" Copyright (c) 2004-2005 by Internet Systems Consortium, Inc. ("ISC")
! 5: .\" Copyright (c) 1996-2003 by Internet Software Consortium
! 6: .\"
! 7: .\" Permission to use, copy, modify, and distribute this software for any
! 8: .\" purpose with or without fee is hereby granted, provided that the above
! 9: .\" copyright notice and this permission notice appear in all copies.
! 10: .\"
! 11: .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
! 12: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 13: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
! 14: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 15: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 16: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
! 17: .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 18: .\"
! 19: .\" Internet Systems Consortium, Inc.
! 20: .\" 950 Charter Street
! 21: .\" Redwood City, CA 94063
! 22: .\" <info@isc.org>
! 23: .\" https://www.isc.org/
! 24: .\"
! 25: .\" This software has been written for Internet Systems Consortium
! 26: .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
! 27: .\"
! 28: .\" Support and other services are available for ISC products - see
! 29: .\" https://www.isc.org for more information or to learn more about ISC.
! 30: .\"
! 31: .\" $Id: dhclient-script.8,v 1.11.762.3 2010-07-02 23:37:06 sar Exp $
! 32: .\"
! 33: .TH dhclient-script 8
! 34: .SH NAME
! 35: dhclient-script - DHCP client network configuration script
! 36: .SH DESCRIPTION
! 37: The DHCP client network configuration script is invoked from time to
! 38: time by \fBdhclient(8)\fR. This script is used by the dhcp client to
! 39: set each interface's initial configuration prior to requesting an
! 40: address, to test the address once it has been offered, and to set the
! 41: interface's final configuration once a lease has been acquired. If no
! 42: lease is acquired, the script is used to test predefined leases, if
! 43: any, and also called once if no valid lease can be identified.
! 44: .PP
! 45: This script is not meant to be customized by the end user. If local
! 46: customizations are needed, they should be possible using the enter and
! 47: exit hooks provided (see HOOKS for details). These hooks will allow the
! 48: user to override the default behaviour of the client in creating a
! 49: .B /etc/resolv.conf
! 50: file.
! 51: .PP
! 52: No standard client script exists for some operating systems, even though
! 53: the actual client may work, so a pioneering user may well need to create
! 54: a new script or modify an existing one. In general, customizations specific
! 55: to a particular computer should be done in the
! 56: .B ETCDIR/dhclient.conf
! 57: file. If you find that you can't make such a customization without
! 58: customizing
! 59: .B ETCDIR/dhclient.conf
! 60: or using the enter and exit hooks, please submit a bug report.
! 61: .SH HOOKS
! 62: When it starts, the client script first defines a shell function,
! 63: .B make_resolv_conf ,
! 64: which is later used to create the
! 65: .B /etc/resolv.conf
! 66: file. To override the default behaviour, redefine this function in
! 67: the enter hook script.
! 68: .PP
! 69: On after defining the make_resolv_conf function, the client script checks
! 70: for the presence of an executable
! 71: .B ETCDIR/dhclient-enter-hooks
! 72: script, and if present, it invokes the script inline, using the Bourne
! 73: shell \'.\' command. The entire environment documented under OPERATION
! 74: is available to this script, which may modify the environment if needed
! 75: to change the behaviour of the script. If an error occurs during the
! 76: execution of the script, it can set the exit_status variable to a nonzero
! 77: value, and
! 78: .B CLIENTBINDIR/dhclient-script
! 79: will exit with that error code immediately after the client script exits.
! 80: .PP
! 81: After all processing has completed,
! 82: .B CLIENTBINDIR/dhclient-script
! 83: checks for the presence of an executable
! 84: .B ETCDIR/dhclient-exit-hooks
! 85: script, which if present is invoked using the \'.\' command. The exit
! 86: status of dhclient-script will be passed to dhclient-exit-hooks in the
! 87: exit_status shell variable, and will always be zero if the script
! 88: succeeded at the task for which it was invoked. The rest of the
! 89: environment as described previously for dhclient-enter-hooks is also
! 90: present. The
! 91: .B ETCDIR/dhclient-exit-hooks
! 92: script can modify the valid of exit_status to change the exit status
! 93: of dhclient-script.
! 94: .SH OPERATION
! 95: When dhclient needs to invoke the client configuration script, it
! 96: defines a set of variables in the environment, and then invokes
! 97: .B CLIENTBINDIR/dhclient-script.
! 98: In all cases, $reason is set to the name of the reason why the script
! 99: has been invoked. The following reasons are currently defined:
! 100: MEDIUM, PREINIT, BOUND, RENEW, REBIND, REBOOT, EXPIRE, FAIL, STOP, RELEASE,
! 101: NBI and TIMEOUT.
! 102: .PP
! 103: .SH MEDIUM
! 104: The DHCP client is requesting that an interface's media type
! 105: be set. The interface name is passed in $interface, and the media
! 106: type is passed in $medium.
! 107: .SH PREINIT
! 108: The DHCP client is requesting that an interface be configured as
! 109: required in order to send packets prior to receiving an actual
! 110: address. For clients which use the BSD socket library, this means
! 111: configuring the interface with an IP address of 0.0.0.0 and a
! 112: broadcast address of 255.255.255.255. For other clients, it may be
! 113: possible to simply configure the interface up without actually giving
! 114: it an IP address at all. The interface name is passed in $interface,
! 115: and the media type in $medium.
! 116: .PP
! 117: If an IP alias has been declared in dhclient.conf, its address will be
! 118: passed in $alias_ip_address, and that ip alias should be deleted from
! 119: the interface, along with any routes to it.
! 120: .SH BOUND
! 121: The DHCP client has done an initial binding to a new address. The
! 122: new ip address is passed in $new_ip_address, and the interface name is
! 123: passed in $interface. The media type is passed in $medium. Any
! 124: options acquired from the server are passed using the option name
! 125: described in \fBdhcp-options\fR, except that dashes (\'-\') are replaced
! 126: by underscores (\'_\') in order to make valid shell variables, and the
! 127: variable names start with new_. So for example, the new subnet mask
! 128: would be passed in $new_subnet_mask.
! 129: .PP
! 130: Before actually configuring the address, dhclient-script should
! 131: somehow ARP for it and exit with a nonzero status if it receives a
! 132: reply. In this case, the client will send a DHCPDECLINE message to
! 133: the server and acquire a different address. This may also be done in
! 134: the RENEW, REBIND, or REBOOT states, but is not required, and indeed
! 135: may not be desirable.
! 136: .PP
! 137: When a binding has been completed, a lot of network parameters are
! 138: likely to need to be set up. A new /etc/resolv.conf needs to be
! 139: created, using the values of $new_domain_name and
! 140: $new_domain_name_servers (which may list more than one server,
! 141: separated by spaces). A default route should be set using
! 142: $new_routers, and static routes may need to be set up using
! 143: $new_static_routes.
! 144: .PP
! 145: If an IP alias has been declared, it must be set up here. The alias
! 146: IP address will be written as $alias_ip_address, and other DHCP
! 147: options that are set for the alias (e.g., subnet mask) will be passed
! 148: in variables named as described previously except starting with
! 149: $alias_ instead of $new_. Care should be taken that the alias IP
! 150: address not be used if it is identical to the bound IP address
! 151: ($new_ip_address), since the other alias parameters may be incorrect
! 152: in this case.
! 153: .SH RENEW
! 154: When a binding has been renewed, the script is called as in BOUND,
! 155: except that in addition to all the variables starting with $new_,
! 156: there is another set of variables starting with $old_. Persistent
! 157: settings that may have changed need to be deleted - for example, if a
! 158: local route to the bound address is being configured, the old local
! 159: route should be deleted. If the default route has changed, the old default
! 160: route should be deleted. If the static routes have changed, the old
! 161: ones should be deleted. Otherwise, processing can be done as with
! 162: BOUND.
! 163: .SH REBIND
! 164: The DHCP client has rebound to a new DHCP server. This can be handled
! 165: as with RENEW, except that if the IP address has changed, the ARP
! 166: table should be cleared.
! 167: .SH REBOOT
! 168: The DHCP client has successfully reacquired its old address after a
! 169: reboot. This can be processed as with BOUND.
! 170: .SH EXPIRE
! 171: The DHCP client has failed to renew its lease or acquire a new one,
! 172: and the lease has expired. The IP address must be relinquished, and
! 173: all related parameters should be deleted, as in RENEW and REBIND.
! 174: .SH FAIL
! 175: The DHCP client has been unable to contact any DHCP servers, and any
! 176: leases that have been tested have not proved to be valid. The
! 177: parameters from the last lease tested should be deconfigured. This
! 178: can be handled in the same way as EXPIRE.
! 179: .SH STOP
! 180: The dhclient has been informed to shut down gracefully, the
! 181: dhclient-script should unconfigure or shutdown the interface as
! 182: appropriate.
! 183: .SH RELEASE
! 184: The dhclient has been executed using the -r flag, indicating that the
! 185: administrator wishes it to release its lease(s). dhclient-script should
! 186: unconfigure or shutdown the interface.
! 187: .SH NBI
! 188: No-Broadcast-Interfaces...dhclient was unable to find any interfaces
! 189: upon which it believed it should commence DHCP. What dhclient-script
! 190: should do in this situation is entirely up to the implementor.
! 191: .SH TIMEOUT
! 192: The DHCP client has been unable to contact any DHCP servers.
! 193: However, an old lease has been identified, and its parameters have
! 194: been passed in as with BOUND. The client configuration script should
! 195: test these parameters and, if it has reason to believe they are valid,
! 196: should exit with a value of zero. If not, it should exit with a
! 197: nonzero value.
! 198: .PP
! 199: The usual way to test a lease is to set up the network as with REBIND
! 200: (since this may be called to test more than one lease) and then ping
! 201: the first router defined in $routers. If a response is received, the
! 202: lease must be valid for the network to which the interface is
! 203: currently connected. It would be more complete to try to ping all of
! 204: the routers listed in $new_routers, as well as those listed in
! 205: $new_static_routes, but current scripts do not do this.
! 206: .SH FILES
! 207: Each operating system should generally have its own script file,
! 208: although the script files for similar operating systems may be similar
! 209: or even identical. The script files included in Internet
! 210: Systems Consortium DHCP distribution appear in the distribution tree
! 211: under client/scripts, and bear the names of the operating systems on
! 212: which they are intended to work.
! 213: .SH BUGS
! 214: If more than one interface is being used, there's no obvious way to
! 215: avoid clashes between server-supplied configuration parameters - for
! 216: example, the stock dhclient-script rewrites /etc/resolv.conf. If
! 217: more than one interface is being configured, /etc/resolv.conf will be
! 218: repeatedly initialized to the values provided by one server, and then
! 219: the other. Assuming the information provided by both servers is
! 220: valid, this shouldn't cause any real problems, but it could be
! 221: confusing.
! 222: .SH SEE ALSO
! 223: dhclient(8), dhcpd(8), dhcrelay(8), dhclient.conf(5) and
! 224: dhclient.leases(5).
! 225: .SH AUTHOR
! 226: .B dhclient-script(8)
! 227: has been written for Internet Systems Consortium
! 228: by Ted Lemon in cooperation with Vixie
! 229: Enterprises. To learn more about Internet Systems Consortium,
! 230: see
! 231: .B https://www.isc.org.
! 232: To learn more about Vixie
! 233: Enterprises, see
! 234: .B http://www.vix.com.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to dhclient-script.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / client