MAN page from Mandrake 9.X dhcp-client-3.0-1.rc12.2mdk.i586.rpm

dhclient.conf

Section: File Formats (5)
Index

NAME

dhclient.conf - DHCP client configuration file

DESCRIPTION

The dhclient.conf file contains configuration information fordhclient,the Internet Software Consortium DHCP Client.

The dhclient.conf file is a free-form ASCII text file. It is parsed bythe recursive-descent parser built into dhclient. The file may containextra tabs and newlines for formatting purposes. Keywords in the fileare case-insensitive. Comments may be placed anywhere within thefile (except within quotes). Comments begin with the # character andend at the end of the line.

The dhclient.conf file can be used to configure the behaviour of theclient in a wide variety of ways: protocol timing, informationrequested from the server, information required of the server,defaults to use if the server does not provide certain information,values with which to override information provided by the server, orvalues to prepend or append to information provided by the server.The configuration file can also be preinitialized with addresses touse on networks that don't have DHCP servers.

PROTOCOL TIMING

The timing behaviour of the client need not be configured by the user.If no timing configuration is provided by the user, a fairlyreasonable timing behaviour will be used by default - one whichresults in fairly timely updates without placing an inordinate load onthe server.

The following statements can be used to adjust the timing behaviour ofthe DHCP client if required, however:

Thetimeoutstatement

timeouttime;

Thetimeoutstatement determines the amount of time that must pass between thetime that the client begins to try to determine its address and thetime that it decides that it's not going to be able to contact aserver. By default, this timeout is sixty seconds. After thetimeout has passed, if there are any static leases defined in theconfiguration file, or any leases remaining in the lease database thathave not yet expired, the client will loop through these leasesattempting to validate them, and if it finds one that appears to bevalid, it will use that lease's address. If there are no validstatic leases or unexpired leases in the lease database, the clientwill restart the protocol after the defined retry interval.

Theretrystatement

retry time;

Theretrystatement determines the time that must pass after the client hasdetermined that there is no DHCP server present before it tries againto contact a DHCP server. By default, this is five minutes.

Theselect-timeoutstatement

select-timeout time;

It is possible (some might say desirable) for there to be more thanone DHCP server serving any given network. In this case, it ispossible that a client may be sent more than one offer in response toits initial lease discovery message. It may be that one of theseoffers is preferable to the other (e.g., one offer may have theaddress the client previously used, and the other may not).

Theselect-timeoutis the time after the client sends its first lease discovery requestat which it stops waiting for offers from servers, assuming that ithas received at least one such offer. If no offers have beenreceived by the time theselect-timeouthas expired, the client will accept the first offer that arrives.

By default, the select-timeout is zero seconds - that is, the clientwill take the first offer it sees.

Therebootstatement

reboot time;

When the client is restarted, it first tries to reacquire the lastaddress it had. This is called the INIT-REBOOT state. If it isstill attached to the same network it was attached to when it lastran, this is the quickest way to get started. Therebootstatement sets the time that must elapse after the client first triesto reacquire its old address before it gives up and tries to discovera new address. By default, the reboot timeout is ten seconds.

Thebackoff-cutoffstatement

backoff-cutoff time;

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. Thebackoff-cutoffstatement determines the maximum amount of time that the client isallowed to back off. It defaults to two minutes.

Theinitial-intervalstatement

initial-interval time;

Theinitial-intervalstatement sets the amount of time between the first attempt to reach aserver and the second attempt to reach a server. Each time a messageis sent, the interval between messages is incremented by twice thecurrent interval multiplied by a random number between zero and one.If it is greater than the backoff-cutoff amount, it is set to thatamount. It defaults to ten seconds.

LEASE REQUIREMENTS AND REQUESTS

The DHCP protocol allows the client to request that the server send itspecific information, and not send it other information that it is notprepared to accept. The protocol also allows the client to rejectoffers from servers if they don't contain information the clientneeds, or if the information provided is not satisfactory.

There is a variety of data contained in offers that DHCP servers sendto DHCP clients. The data that can be specifically requested is whatare called DHCP Options. DHCP Options are defined in
dhcp-options(5).

Therequeststatement

request [ option ] [, ... option ];

The request statement causes the client to request that any serverresponding to the client send the client its values for the specifiedoptions. Only the option names should be specified in the requeststatement - not option parameters. By default, the DHCP serverrequests the subnet-mask, broadcast-address, time-offset, routers,domain-name, domain-name-servers and host-name options.

In some cases, it may be desirable to send no parameter request listat all. To do this, simply write the request statement but specifyno parameters:

        request;

Therequirestatement

require [ option ] [, ... option ];

The require statement lists options that must be sent in order for anoffer to be accepted. Offers that do not contain all the listedoptions will be ignored.

Thesendstatement

send { [ option declaration ][, ... option declaration ]}

The send statement causes the client to send the specified options tothe server with the specified values. These are full optiondeclarations as described in dhcp-options(5). Options that arealways sent in the DHCP protocol should not be specified here, exceptthat the client can specify a requested-lease-time option otherthan the default requested lease time, which is two hours. The otherobvious use for this statement is to send information to the serverthat will allow it to differentiate between this client and otherclients or kinds of clients.

DYNAMIC DNS

The client now has some very limited support for doing DNS updateswhen a lease is acquired. This is prototypical, and probably doesn'tdo what you want. It also only works if you happen to have controlover your DNS server, which isn't very likely.

To make it work, you have to declare a key and zone as in the DHCPserver (see dhcpd.conf(5) for details). You also need toconfigure the fqdn option on the client, as follows:

  send fqdn.fqdn "grosse.fugue.com.";  send fqdn.encoded on;  send fqdn.server-update off;

The fqdn.fqdn option MUST be a fully-qualified domainname. You MUST define a zone statement for the zone to beupdated. The fqdn.encoded option may need to be set toon or off, depending on the DHCP server you are using.

Thedo-forward-updatesstatement

do-forward-updates [ flag ] ;

If you want to do DNS updates in the DHCP clientscript (see dhclient-script(8)) rather than having theDHCP client do the update directly (for example, if you want touse SIG(0) authentication, which is not supported directly by theDHCP client, you can instruct the client not to do the update usingthe do-forward-updates statement. Flag should be trueif you want the DHCP client to do the update, and false ifyou don't want the DHCP client to do the update. By default, the DHCPclient will do the DNS update.

OPTION MODIFIERS

In some cases, a client may receive option data from the server whichis not really appropriate for that client, or may not receiveinformation that it needs, and for which a useful default valueexists. It may also receive information which is useful, but whichneeds to be supplemented with local information. To handle theseneeds, several option modifiers are available.

Thedefaultstatement

default [ option declaration ] ;

If for some option the client should use the value supplied bythe server, but needs to use some default value if no value was suppliedby the server, these values can be defined in thedefaultstatement.

Thesupersedestatement

supersede [ option declaration ] ;

If for some option the client should always use a locally-configuredvalue or values rather than whatever is supplied by the server, thesevalues can be defined in the supersedestatement.

Theprependstatement

prepend [ option declaration ] ;

If for some set of options the client should use a value yousupply, and then use the values supplied bythe server, if any, these values can be defined in theprependstatement. Theprependstatement can only be used for options whichallow more than one value to be given. This restriction is notenforced - if you ignore it, the behaviour will be unpredictable.

Theappendstatement

append [ option declaration ] ;

If for some set of options the client should first use the valuessupplied by the server, if any, and then use values you supply, thesevalues can be defined in theappendstatement. Theappendstatement can only be used for options whichallow more than one value to be given. This restriction is notenforced - if you ignore it, the behaviour will be unpredictable.

LEASE DECLARATIONS

Theleasedeclaration

lease { lease-declaration [ ... lease-declaration ] }

The DHCP client may decide after some period of time (see PROTOCOLTIMING) that it is not going to succeed in contacting aserver. At that time, it consults its own database of old leases andtests each one that has not yet timed out by pinging the listed routerfor that lease to see if that lease could work. It is possible todefine one or more fixed leases in the client configuration filefor networks where there is no DHCP or BOOTP service, so that theclient can still automatically configure its address. This is donewith theleasestatement.

NOTE: the lease statement is also used in the dhclient.leases file inorder to record leases that have been received from DHCP servers.Some of the syntax for leases as described below is only needed in thedhclient.leases file. Such syntax is documented here forcompleteness.

A lease statement consists of the lease keyword, followed by a leftcurly brace, followed by one or more lease declaration statements,followed by a right curly brace. The following lease declarationsare possible:

bootp;

Thebootpstatement is used to indicate that the lease was acquired using theBOOTP protocol rather than the DHCP protocol. It is never necessaryto specify this in the client configuration file. The client usesthis syntax in its lease database file.

interface "string";

Theinterfacelease statement is used to indicate the interface on which the leaseis valid. If set, this lease will only be tried on a particularinterface. When the client receives a lease from a server, it alwaysrecords the interface number on which it received that lease.If predefined leases are specified in the dhclient.conf file, theinterface should also be specified, although this is not required.

fixed-address ip-address;

Thefixed-addressstatement is used to set the ip address of a particular lease. Thisis required for all lease statements. The IP address must bespecified as a dotted quad (e.g., 12.34.56.78).

filename "string";

Thefilenamestatement specifies the name of the boot filename to use. This isnot used by the standard client configuration script, but is includedfor completeness.

server-name "string";

Theserver-namestatement specifies the name of the boot server name to use. This isalso not used by the standard client configuration script.

option option-declaration;

Theoptionstatement is used to specify the value of an option supplied by theserver, or, in the case of predefined leases declared indhclient.conf, the value that the user wishes the client configurationscript to use if the predefined lease is used.

script "script-name";

Thescriptstatement is used to specify the pathname of the dhcp clientconfiguration script. This script is used by the dhcp client to seteach interface's initial configuration prior to requesting an address,to test the address once it has been offered, and to set theinterface's final configuration once a lease has been acquired. Ifno lease is acquired, the script is used to test predefined leases, ifany, and also called once if no valid lease can be identified. Formore information, seedhclient-script(8).

vendor option space "name";

Thevendor option spacestatement is used to specify which option space should be used fordecoding the vendor-encapsulate-options option if one is received.The dhcp-vendor-identifier can be used to request a specificclass of vendor options from the server. Seedhcp-options(5)for details.

medium "media setup";

Themediumstatement can be used on systems where network interfaces cannotautomatically determine the type of network to which they areconnected. The media setup string is a system-dependent parameterwhich is passed to the dhcp client configuration script wheninitializing the interface. On Unix and Unix-like systems, theargument is passed on the ifconfig command line when configuring teinterface.

The dhcp client automatically declares this parameter if it uses amedia type (see themediastatement) when configuring the interface in order to obtain a lease.This statement should be used in predefined leases only if the networkinterface requires media type configuration.

renew date;

rebind date;

expire date;

The renew statement defines the time at which the dhcp clientshould begin trying to contact its server to renew a lease that it isusing. The rebind statement defines the time at which the dhcpclient should begin to try to contact any dhcp server in orderto renew its lease. The expire statement defines the time atwhich the dhcp client must stop using a lease if it has not been ableto contact a server in order to renew it.

These declarations are automatically set in leases acquired by theDHCP client, but must also be configured in predefined leases - apredefined lease whose expiry time has passed will not be used by theDHCP client.

Dates are specified as follows:

<weekday> <year>/<month>/<day><hour>:<minute>:<second>

The weekday is present to make it easy for a human to tell when alease expires - it's specified as a number from zero to six, with zerobeing Sunday. When declaring a predefined lease, it can always bespecified as zero. The year is specified with the century, so itshould generally be four digits except for really long leases. Themonth is specified as a number starting with 1 for January. The dayof the month is likewise specified starting with 1. The hour is anumber between 0 and 23, the minute a number between 0 and 59, and thesecond also a number between 0 and 59.

ALIAS DECLARATIONS

alias { declarations ... }

Some DHCP clients running TCP/IP roaming protocols may require that inaddition to the lease they may acquire via DHCP, their interface alsobe configured with a predefined IP alias so that they can have apermanent IP address even while roaming. The Internet SoftwareConsortium DHCP client doesn't support roaming with fixed addressesdirectly, but in order to facilitate such experimentation, the dhcpclient can be set up to configure an IP alias using thealiasdeclaration.

The alias declaration resembles a lease declaration, except thatoptions other than the subnet-mask option are ignored by the standardclient configuration script, and expiry times are ignored. A typicalalias declaration includes an interface declaration, a fixed-addressdeclaration for the IP alias address, and a subnet-mask optiondeclaration. A medium statement should never be included in an aliasdeclaration.

OTHER DECLARATIONS

reject ip-address;

Therejectstatement causes the DHCP client to reject offers fromservers who use the specified address as a server identifier. Thiscan be used to avoid being configured by rogue or misconfigured dhcpservers, although it should be a last resort - better to track downthe bad DHCP server and fix it.

interface "name" { declarations ... }

A client with more than one network interface may require differentbehaviour depending on which interface is being configured. Alltiming parameters and declarations other than lease and aliasdeclarations can be enclosed in an interface declaration, and thoseparameters will then be used only for the interface that matches thespecified name. Interfaces for which there is no interfacedeclaration will use the parameters declared outside of any interfacedeclaration, or the default settings.

pseudo "name" "real-name" { declarations ... }

Under some circumstances it can be useful to declare a pseudo-interface and have the DHCP client acquire a configuration for that interface.Each interface that the DHCP client is supporting normally has a DHCPclient state machine running on it to acquire and maintain its lease.A pseudo-interface is just another state machine running on theinterface named real-name, with its own lease and its ownstate. If you use this feature, you must provide a client identifierfor both the pseudo-interface and the actual interface, and the twoidentifiers must be different. You must also provide a separateclient script for the pseudo-interface to do what you want with the IPaddress. For example:

        interface "ep0" {                send dhcp-client-identifier "my-client-ep0";        }        pseudo "secondary" "ep0" {                send dhcp-client-identifier "my-client-ep0-secondary";                script "/etc/dhclient-secondary";        }

The client script for the pseudo-interface should not configure theinterface up or down - essentially, all it needs to handle are thestates where a lease has been acquired or renewed, and the stateswhere a lease has expired. See dhclient-script(8) for moreinformation.

media "media setup" [ , "media setup", ... ];

Themediastatement defines one or more media configuration parameters which maybe tried while attempting to acquire an IP address. The dhcp clientwill cycle through each media setup string on the list, configuringthe interface using that setup and attempting to boot, and then tryingthe next one. This can be used for network interfaces which aren'tcapable of sensing the media type unaided - whichever media typesucceeds in getting a request to the server and hearing the reply isprobably right (no guarantees).

The media setup is only used for the initial phase of addressacquisition (the DHCPDISCOVER and DHCPOFFER packets). Once anaddress has been acquired, the dhcp client will record it in its leasedatabase and will record the media type used to acquire the address.Whenever the client tries to renew the lease, it will use that samemedia type. The lease must expire before the client will go back tocycling through media types.

SAMPLE

The following configuration file is used on a laptop running NetBSD1.3. The laptop has an IP alias of 192.5.5.213, and has oneinterface, ep0 (a 3com 3C589C). Booting intervals have beenshortened somewhat from the default, because the client is known tospend most of its time on networks with little DHCP activity. Thelaptop does roam to multiple networks.

timeout 60;retry 60;reboot 10;select-timeout 5;initial-interval 2;reject 192.33.137.209;interface "ep0" {    send host-name "andare.fugue.com";    send dhcp-client-identifier 1:0:a0:24:ab:fb:9c;    send dhcp-lease-time 3600;    supersede domain-name "fugue.com rc.vix.com home.vix.com";    prepend domain-name-servers 127.0.0.1;    request subnet-mask, broadcast-address, time-offset, routers,            domain-name, domain-name-servers, host-name;    require subnet-mask, domain-name-servers;    script "/sbin/dhclient-script";    media "media 10baseT/UTP", "media 10base2/BNC";}alias {  interface "ep0";  fixed-address 192.5.5.213;  option subnet-mask 255.255.255.255;}

This is a very complicated dhclient.conf file - in general, yoursshould be much simpler. In many cases, it's sufficient to justcreate an empty dhclient.conf file - the defaults are usually fine.

AUTHOR

dhclient(8)was written by Ted Lemonunder a contract with Vixie Labs. Fundingfor this project was provided by the Internet Software Consortium.Information about the Internet Software Consortium can be found athttp://www.isc.org.

This document was created byman2html,using the manual pages.