| 1 | .\" $OpenBSD: src/sbin/dhclient/dhclient.conf.5,v 1.21 2011/04/09 19:53:00 krw Exp $ |
| 2 | .\" |
| 3 | .\" Copyright (c) 1997 The Internet Software Consortium. |
| 4 | .\" All rights reserved. |
| 5 | .\" |
| 6 | .\" Redistribution and use in source and binary forms, with or without |
| 7 | .\" modification, are permitted provided that the following conditions |
| 8 | .\" are met: |
| 9 | .\" |
| 10 | .\" 1. Redistributions of source code must retain the above copyright |
| 11 | .\" notice, this list of conditions and the following disclaimer. |
| 12 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 13 | .\" notice, this list of conditions and the following disclaimer in the |
| 14 | .\" documentation and/or other materials provided with the distribution. |
| 15 | .\" 3. Neither the name of The Internet Software Consortium nor the names |
| 16 | .\" of its contributors may be used to endorse or promote products derived |
| 17 | .\" from this software without specific prior written permission. |
| 18 | .\" |
| 19 | .\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND |
| 20 | .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, |
| 21 | .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF |
| 22 | .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
| 23 | .\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR |
| 24 | .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 25 | .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 26 | .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF |
| 27 | .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND |
| 28 | .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, |
| 29 | .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT |
| 30 | .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 31 | .\" SUCH DAMAGE. |
| 32 | .\" |
| 33 | .\" This software has been written for the Internet Software Consortium |
| 34 | .\" by Ted Lemon <mellon@fugue.com> in cooperation with Vixie |
| 35 | .\" Enterprises. To learn more about the Internet Software Consortium, |
| 36 | .\" see ``http://www.isc.org/isc''. To learn more about Vixie |
| 37 | .\" Enterprises, see ``http://www.vix.com''. |
| 38 | .\" |
| 39 | .Dd August 4, 2012 |
| 40 | .Dt DHCLIENT.CONF 5 |
| 41 | .Os |
| 42 | .Sh NAME |
| 43 | .Nm dhclient.conf |
| 44 | .Nd DHCP client configuration file |
| 45 | .Sh DESCRIPTION |
| 46 | The |
| 47 | .Nm |
| 48 | file contains configuration information for |
| 49 | .Xr dhclient 8 , |
| 50 | the Internet Software Consortium DHCP Client. |
| 51 | .Pp |
| 52 | The |
| 53 | .Nm |
| 54 | file is a free-form ASCII text file. |
| 55 | It is parsed by the recursive-descent parser built into |
| 56 | .Xr dhclient 8 . |
| 57 | The file may contain extra tabs and newlines for formatting purposes. |
| 58 | Keywords in the file are case-insensitive. |
| 59 | Comments may be placed anywhere within the file (except within quotes). |
| 60 | Comments begin with the |
| 61 | .Sq # |
| 62 | character and end at the end of the line. |
| 63 | .Pp |
| 64 | The |
| 65 | .Nm |
| 66 | file can be used to configure the behaviour of the client in a wide variety |
| 67 | of ways: protocol timing, information requested from the server, information |
| 68 | required of the server, defaults to use if the server does not provide |
| 69 | certain information, values with which to override information provided by |
| 70 | the server, or values to prepend or append to information provided by the |
| 71 | server. |
| 72 | The configuration file can also be preinitialized with addresses to |
| 73 | use on networks that don't have DHCP servers. |
| 74 | .Sh PROTOCOL TIMING |
| 75 | The timing behaviour of the client need not be configured by the user. |
| 76 | If no timing configuration is provided by the user, a fairly |
| 77 | reasonable timing behaviour will be used by default \- one which |
| 78 | results in fairly timely updates without placing an inordinate load on |
| 79 | the server. |
| 80 | .Pp |
| 81 | The following statements can be used to adjust the timing behaviour of |
| 82 | the DHCP client if required, however: |
| 83 | .Bl -tag -width Ds |
| 84 | .It Ic timeout Ar time ; |
| 85 | The |
| 86 | .Ic timeout |
| 87 | statement determines the amount of time that must pass between the |
| 88 | time that the client begins to try to determine its address and the |
| 89 | time that it decides that it's not going to be able to contact a server. |
| 90 | By default, this timeout is sixty seconds. |
| 91 | After the timeout has passed, if there are any static leases defined in the |
| 92 | configuration file, or any leases remaining in the lease database that |
| 93 | have not yet expired, the client will loop through these leases |
| 94 | attempting to validate them, and if it finds one that appears to be |
| 95 | valid, it will use that lease's address. |
| 96 | If there are no valid static leases or unexpired leases in the lease database, |
| 97 | the client will restart the protocol after the defined retry interval. |
| 98 | .It Ic retry Ar time ; |
| 99 | The |
| 100 | .Ic retry |
| 101 | statement determines the time that must pass after the client has |
| 102 | determined that there is no DHCP server present before it tries again |
| 103 | to contact a DHCP server. |
| 104 | By default, this is five minutes. |
| 105 | .It Ic select-timeout Ar time ; |
| 106 | It is possible (some might say desirable) for there to be more than |
| 107 | one DHCP server serving any given network. |
| 108 | In this case, it is possible that a client may be sent more than one offer |
| 109 | in response to its initial lease discovery message. |
| 110 | It may be that one of these offers is preferable to the other |
| 111 | (e.g., one offer may have the address the client previously used, |
| 112 | and the other may not). |
| 113 | .Pp |
| 114 | The |
| 115 | .Ic select-timeout |
| 116 | is the time after the client sends its first lease discovery request |
| 117 | at which it stops waiting for offers from servers, assuming that it |
| 118 | has received at least one such offer. |
| 119 | If no offers have been received by the time the |
| 120 | .Ic select-timeout |
| 121 | has expired, the client will accept the first offer that arrives. |
| 122 | .Pp |
| 123 | By default, the |
| 124 | .Ic select-timeout |
| 125 | is zero seconds \- that is, the client will take the first offer it sees. |
| 126 | .It Ic reboot Ar time ; |
| 127 | When the client is restarted, it first tries to reacquire the last |
| 128 | address it had. |
| 129 | This is called the INIT-REBOOT state. |
| 130 | If it is still attached to the same network it was attached to when it last |
| 131 | ran, this is the quickest way to get started. |
| 132 | The |
| 133 | .Ic reboot |
| 134 | statement sets the time that must elapse after the client first tries |
| 135 | to reacquire its old address before it gives up and tries to discover |
| 136 | a new address. |
| 137 | By default, the reboot timeout is ten seconds. |
| 138 | .It Ic backoff-cutoff Ar time ; |
| 139 | The client uses an exponential backoff algorithm with some randomness, |
| 140 | so that if many clients try to configure themselves at the same time, |
| 141 | they will not make their requests in lockstep. |
| 142 | The |
| 143 | .Ic backoff-cutoff |
| 144 | statement determines the maximum amount of time that the client is |
| 145 | allowed to back off. |
| 146 | It defaults to fifteen seconds. |
| 147 | .It Ic initial-interval Ar time ; |
| 148 | The |
| 149 | .Ic initial-interval |
| 150 | statement sets the amount of time between the first attempt to reach a |
| 151 | server and the second attempt to reach a server. |
| 152 | Each time a message is sent, the interval between messages is incremented by |
| 153 | twice the current interval multiplied by a random number between zero and one. |
| 154 | If it is greater than the backoff-cutoff amount, it is set to that |
| 155 | amount. |
| 156 | It defaults to three seconds. |
| 157 | .It Ic link-timeout Ar time ; |
| 158 | The |
| 159 | .Ic link-timeout |
| 160 | statement sets the amount of time to wait for an interface link before timing |
| 161 | out. |
| 162 | The default value is ten seconds. |
| 163 | The value zero requests that |
| 164 | dhclient not wait for a link state change before timing out. |
| 165 | .El |
| 166 | .Sh LEASE REQUIREMENTS AND REQUESTS |
| 167 | The DHCP protocol allows the client to request that the server send it |
| 168 | specific information, and not send it other information that it is not |
| 169 | prepared to accept. |
| 170 | The protocol also allows the client to reject offers from servers if they |
| 171 | don't contain information the client needs, or if the information provided |
| 172 | is not satisfactory. |
| 173 | .Pp |
| 174 | There is a variety of data contained in offers that DHCP servers send |
| 175 | to DHCP clients. |
| 176 | The data that can be specifically requested is what are called |
| 177 | .Em DHCP Options . |
| 178 | DHCP Options are defined in |
| 179 | .Xr dhcp-options 5 . |
| 180 | .Bl -tag -width Ds |
| 181 | .It Xo |
| 182 | .Ic request Op Ar option |
| 183 | .Oo , Ar ... option Oc ; |
| 184 | .Xc |
| 185 | The |
| 186 | .Ic request |
| 187 | statement causes the client to request that any server responding to the |
| 188 | client send the client its values for the specified options. |
| 189 | Only the option names should be specified in the request statement \- not |
| 190 | option parameters. |
| 191 | .It Xo |
| 192 | .Ic require Op Ar option |
| 193 | .Oo , Ar ... option Oc ; |
| 194 | .Xc |
| 195 | The |
| 196 | .Ic require |
| 197 | statement lists options that must be sent in order for an offer to be accepted. |
| 198 | Offers that do not contain all the listed options will be ignored. |
| 199 | .It Xo |
| 200 | .Ic send No { Op Ar option declaration |
| 201 | .Oo , Ar ... option declaration Oc } |
| 202 | .Xc |
| 203 | The |
| 204 | .Ic send |
| 205 | statement causes the client to send the specified options to the server with |
| 206 | the specified values. |
| 207 | These are full option declarations as described in |
| 208 | .Xr dhcp-options 5 . |
| 209 | Options that are always sent in the DHCP protocol should not be specified |
| 210 | here. |
| 211 | One use for this statement is to send information to the server |
| 212 | that will allow it to differentiate between this client and other |
| 213 | clients or kinds of clients. |
| 214 | .El |
| 215 | .Sh OPTION MODIFIERS |
| 216 | Options in the lease can be modified before being passed to the client |
| 217 | configuration script, |
| 218 | .Xr dhclient-script 8 . |
| 219 | .Pp |
| 220 | The default client configuration script |
| 221 | processes only options 1 (subnet |
| 222 | mask), 3 (routers), 6 (domain name servers), 15 (domain-name). |
| 223 | Use of option modifiers on other options will have no effect unless |
| 224 | .Xr dhclient-script 8 |
| 225 | the client configuration script is modified. |
| 226 | .Pp |
| 227 | Several option modifiers are available. |
| 228 | .Bl -tag -width Ds |
| 229 | .It Xo |
| 230 | .Ic default No { Op Ar option declaration |
| 231 | .Oo , Ar ... option declaration Oc } |
| 232 | .Xc |
| 233 | If for some set of options the client should use the value supplied by |
| 234 | the server, but needs to use some default value if no value was supplied |
| 235 | by the server, these values can be defined in the |
| 236 | .Ic default |
| 237 | statement. |
| 238 | .It Xo |
| 239 | .Ic supersede No { Op Ar option declaration |
| 240 | .Oo , Ar ... option declaration Oc } |
| 241 | .Xc |
| 242 | If for some set of options the client should always use its own value |
| 243 | rather than any value supplied by the server, these values can be defined |
| 244 | in the |
| 245 | .Ic supersede |
| 246 | statement. |
| 247 | .It Xo |
| 248 | .Ic prepend No { Op Ar option declaration |
| 249 | .Oo , Ar ... option declaration Oc } |
| 250 | .Xc |
| 251 | If for some set of options the client should use a value you supply, |
| 252 | and then use the values supplied by the server, if any, |
| 253 | these values can be defined in the |
| 254 | .Ic prepend |
| 255 | statement. |
| 256 | The |
| 257 | .Ic prepend |
| 258 | statement can only be used for options which allow more than one value to |
| 259 | be given. |
| 260 | This restriction is not enforced \- if violated, the results are unpredictable. |
| 261 | .It Xo |
| 262 | .Ic append No { Op Ar option declaration |
| 263 | .Oo , Ar ... option declaration Oc } |
| 264 | .Xc |
| 265 | If for some set of options the client should first use the values |
| 266 | supplied by the server, if any, and then use values you supply, these |
| 267 | values can be defined in the |
| 268 | .Ic append |
| 269 | statement. |
| 270 | The |
| 271 | .Ic append |
| 272 | statement can only be used for options which allow more than one value to |
| 273 | be given. |
| 274 | This restriction is not enforced \- if you ignore it, |
| 275 | the behaviour will be unpredictable. |
| 276 | .El |
| 277 | .Sh LEASE DECLARATIONS |
| 278 | The lease declaration: |
| 279 | .Pp |
| 280 | .D1 Ic lease No { Ar lease-declaration Oo Ar ... lease-declaration Oc } |
| 281 | .Pp |
| 282 | The DHCP client may decide after some period of time (see |
| 283 | .Sx PROTOCOL TIMING ) |
| 284 | that it is not going to succeed in contacting a server. |
| 285 | At that time, it consults its own database of old leases and tests each one |
| 286 | that has not yet timed out by pinging the listed router for that lease to |
| 287 | see if that lease could work. |
| 288 | It is possible to define one or more |
| 289 | .Em fixed |
| 290 | leases in the client configuration file for networks where there is no DHCP |
| 291 | or BOOTP service, so that the client can still automatically configure its |
| 292 | address. |
| 293 | This is done with the |
| 294 | .Ic lease |
| 295 | statement. |
| 296 | .Pp |
| 297 | NOTE: the lease statement is also used in the |
| 298 | .Pa dhclient.leases |
| 299 | file in order to record leases that have been received from DHCP servers. |
| 300 | Some of the syntax for leases as described below is only needed in the |
| 301 | .Pa dhclient.leases |
| 302 | file. |
| 303 | Such syntax is documented here for completeness. |
| 304 | .Pp |
| 305 | A lease statement consists of the lease keyword, followed by a left |
| 306 | curly brace, followed by one or more lease declaration statements, |
| 307 | followed by a right curly brace. |
| 308 | The following lease declarations are possible: |
| 309 | .Bl -tag -width Ds |
| 310 | .It Ic bootp ; |
| 311 | The |
| 312 | .Ic bootp |
| 313 | statement is used to indicate that the lease was acquired using the |
| 314 | BOOTP protocol rather than the DHCP protocol. |
| 315 | It is never necessary to specify this in the client configuration file. |
| 316 | The client uses this syntax in its lease database file. |
| 317 | .It Ic interface Ar \&"string\&" ; |
| 318 | The |
| 319 | .Ic interface |
| 320 | lease statement is used to indicate the interface on which the lease is valid. |
| 321 | If set, this lease will only be tried on a particular interface. |
| 322 | When the client receives a lease from a server, it always records the |
| 323 | interface number on which it received that lease. |
| 324 | If predefined leases are specified in the |
| 325 | .Nm |
| 326 | file, the interface should also be specified, although this is not required. |
| 327 | .It Ic fixed-address Ar ip-address ; |
| 328 | The |
| 329 | .Ic fixed-address |
| 330 | statement is used to set the IP address of a particular lease. |
| 331 | This is required for all lease statements. |
| 332 | The IP address must be specified as a dotted quad (e.g., 12.34.56.78). |
| 333 | .It Ic filename Ar \&"string\&" ; |
| 334 | The |
| 335 | .Ic filename |
| 336 | statement specifies the name of the boot filename to use. |
| 337 | This is not used by the standard client configuration script, but is |
| 338 | included for completeness. |
| 339 | .It Ic server-name Ar \&"string\&" ; |
| 340 | The |
| 341 | .Ic server-name |
| 342 | statement specifies the name of the boot server name to use. |
| 343 | This is also not used by the standard client configuration script. |
| 344 | .It Ic option Ar option-declaration ; |
| 345 | The |
| 346 | .Ic option |
| 347 | statement is used to specify the value of an option supplied by the server, |
| 348 | or, in the case of predefined leases declared in |
| 349 | .Nm , |
| 350 | the value that the user wishes the client configuration script to use if the |
| 351 | predefined lease is used. |
| 352 | .It Ic renew Ar date ; |
| 353 | .It Ic rebind Ar date ; |
| 354 | .It Ic expire Ar date ; |
| 355 | The |
| 356 | .Ic renew |
| 357 | statement defines the time at which the DHCP client should begin trying to |
| 358 | contact its server to renew a lease that it is using. |
| 359 | The |
| 360 | .Ic rebind |
| 361 | statement defines the time at which the DHCP client should begin to try to |
| 362 | contact |
| 363 | .Em any |
| 364 | DHCP server in order to renew its lease. |
| 365 | The |
| 366 | .Ic expire |
| 367 | statement defines the time at which the DHCP client must stop using a lease |
| 368 | if it has not been able to contact a server in order to renew it. |
| 369 | .El |
| 370 | .Pp |
| 371 | These declarations are automatically set in leases acquired by the |
| 372 | DHCP client, but must also be configured in predefined leases \- a |
| 373 | predefined lease whose expiry time has passed will not be used by the |
| 374 | DHCP client. |
| 375 | .Pp |
| 376 | Dates are specified as follows: |
| 377 | .Bd -ragged -offset indent |
| 378 | .Ar <weekday> |
| 379 | .Sm off |
| 380 | .Ar <year> No / Ar <month> No / Ar <day> |
| 381 | .Ar <hour> : <minute> : <second> |
| 382 | .Sm on |
| 383 | .Ed |
| 384 | .Pp |
| 385 | The weekday is present to make it easy for a human to tell when a |
| 386 | lease expires \- it's specified as a number from zero to six, with zero |
| 387 | being Sunday. |
| 388 | When declaring a predefined lease, it can always be specified as zero. |
| 389 | The year is specified with the century, so it should generally be four |
| 390 | digits except for really long leases. |
| 391 | The month is specified as a number starting with 1 for January. |
| 392 | The day of the month is likewise specified starting with 1. |
| 393 | The hour is a number between 0 and 23, |
| 394 | the minute a number between 0 and 59, |
| 395 | and the second also a number between 0 and 59. |
| 396 | .Sh OTHER DECLARATIONS |
| 397 | .Bl -tag -width Ds |
| 398 | .It Ic reject Ar ip-address ; |
| 399 | The |
| 400 | .Ic reject |
| 401 | statement causes the DHCP client to reject offers from servers who use |
| 402 | the specified address as a server identifier. |
| 403 | This can be used to avoid being configured by rogue or misconfigured DHCP |
| 404 | servers, although it should be a last resort \- better to track down |
| 405 | the bad DHCP server and fix it. |
| 406 | .It Xo |
| 407 | .Ic interface Ar \&"name\&" No { Ar declarations |
| 408 | .Ar ... No } |
| 409 | .Xc |
| 410 | A client with more than one network interface may require different |
| 411 | behaviour depending on which interface is being configured. |
| 412 | All timing parameters and declarations other than lease |
| 413 | declarations can be enclosed in an interface declaration, and those |
| 414 | parameters will then be used only for the interface that matches the |
| 415 | specified name. |
| 416 | Interfaces for which there is no interface declaration will use the |
| 417 | parameters declared outside of any interface declaration, |
| 418 | or the default settings. |
| 419 | .It Ic script Ar \&"script-name\&" ; |
| 420 | The |
| 421 | .Ic script |
| 422 | statement is used to specify the pathname of the client configuration |
| 423 | script. |
| 424 | This script is used by the DHCP client to set each interface's initial |
| 425 | configuration prior to requesting an address, to test the address once it |
| 426 | has been offered, and to set the interface's final configuration once a |
| 427 | lease has been acquired. |
| 428 | If no lease is acquired, the script is used to test predefined leases, if |
| 429 | any, and also called once if no valid lease can be identified. |
| 430 | For more information, see |
| 431 | .Xr dhclient.leases 5 . |
| 432 | .El |
| 433 | .Sh EXAMPLES |
| 434 | The following configuration file is used on a laptop |
| 435 | which has one interface, ep0 (a 3Com 3C589C). |
| 436 | Booting intervals have been shortened somewhat from the default, because |
| 437 | the client is known to spend most of its time on networks with little DHCP |
| 438 | activity. |
| 439 | The laptop does roam to multiple networks. |
| 440 | .Bd -literal -offset indent |
| 441 | timeout 60; |
| 442 | retry 60; |
| 443 | reboot 10; |
| 444 | select-timeout 5; |
| 445 | initial-interval 2; |
| 446 | reject 192.33.137.209; |
| 447 | |
| 448 | interface "ep0" { |
| 449 | send host-name "andare.fugue.com"; |
| 450 | send dhcp-client-identifier 1:0:a0:24:ab:fb:9c; |
| 451 | send dhcp-lease-time 3600; |
| 452 | supersede domain-name "fugue.com rc.vix.com home.vix.com"; |
| 453 | prepend domain-name-servers 127.0.0.1; |
| 454 | request subnet-mask, broadcast-address, time-offset, routers, |
| 455 | domain-name, domain-name-servers, host-name; |
| 456 | require subnet-mask, domain-name-servers; |
| 457 | script "/etc/dhclient-script"; |
| 458 | } |
| 459 | .Ed |
| 460 | .Pp |
| 461 | This is a very complicated |
| 462 | .Nm |
| 463 | file \- in general, yours should be much simpler. |
| 464 | In many cases, it's sufficient to just create an empty |
| 465 | .Nm |
| 466 | file \- the defaults are usually fine. |
| 467 | .Sh SEE ALSO |
| 468 | .Xr dhclient.leases 5 , |
| 469 | .Xr dhclient-script 8 , |
| 470 | .Xr dhcp-options 5 , |
| 471 | .Xr dhcpd.conf 5 Pq Pa pkgsrc/net/isc-dhcpd4 , |
| 472 | .Xr dhclient 8 , |
| 473 | .Xr dhcpd 8 Pq Pa pkgsrc/net/isc-dhcpd4 |
| 474 | .Pp |
| 475 | RFC 2132, RFC 2131. |
| 476 | .Sh AUTHORS |
| 477 | .An -nosplit |
| 478 | .Xr dhclient 8 |
| 479 | was written by |
| 480 | .An Ted Lemon Aq mellon@vix.com |
| 481 | under a contract with Vixie Labs. |
| 482 | .Pp |
| 483 | The current implementation was reworked by |
| 484 | .An Henning Brauer Aq henning@openbsd.org . |