Annotation of embedaddon/dhcp/client/dhclient-script.8, revision 1.1.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: .\"
1.1.1.1 ! misho 31: .\" $Id: dhclient-script.8,v 1.11.762.3 2010/07/02 23:37:06 sar Exp $
1.1 misho 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