SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from Mandriva 2010 dhcp-client-4.1.1-6mdv2010.1.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 Systems 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, the actual value will be evaluated randomly between1/2 to 1 1/2 times the time specified. 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


 [ also ] request [ [ option-space . ] 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. Note that ifyou enter a 'request' statement, you over-ride this default and theseoptions will not be requested.

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;

In most cases, it is desirable to simply add one option to the requestlist which is of interest to the client in question. In this case, itis best to 'also request' the additional options:

        also request domain-search, dhcp6.sip-servers-addresses;

Therequirestatement


 [ also ] require [ [ option-space . ] 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. There is no default require list.

        require name-servers;        interface eth0 {                also require domain-search;        }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.
 

DHCPV6 OPERATION

The client does not yet have a default DHCPv6 Option Request Option (ORO),nor has it been integrated with the 'request' and 'require' syntax above.It is neccessary to configure an ORO then.

  send dhcp6.oro 1, 2, 7, 12, 13, 23, 24, 39;

The above ORO will request both identifiers (server, client), the preference,unicast, nameservers, domain-search, and FQDN(v6) options. 

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.

Note that everything in this section is true whether you are using DHCPv4or DHCPv6. The exact same syntax is used for both.

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;  also request fqdn, dhcp6.fqdn;

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 theinterface.

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 in one of two ways. The software will output times inthese two formats depending on if the db-time-format configurationparameter has been set to default or local.

If it is set to default, then date values appear 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.

If the db-time-format configuration was set to local, thenthe date values appear as follows:


 epoch <seconds-since-epoch>; # <day-name> <month-name><day-number> <hours>:<minutes>:<seconds> <year>

The seconds-since-epoch is as according to the system's local clock (oftenreferred to as "unix time"). The # symbol supplies a comment thatdescribes what actual time this is as according to the system's configuredtimezone, at the time the value was written. It is provided only for humaninspection, the epoch time is the only recommended value for machineinspection.

Note that when defining a static lease, one may use either time format onewishes, and need not include the comment or values after it.

If the time is infinite in duration, then the date is neverinstead of an actual date. 

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 SystemsConsortium 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


 db-time-format [ default | local ] ;

The db-time-format option determines which of two output methods areused for printing times in leases files. The default format providesday-and-time in UTC, whereas local uses a seconds-since-epoch to storethe time value, and helpfully places a local timezone time in a comment onthe same line. The formats are described in detail in this manpage, whithinthe LEASE DECLARATIONS section.


 reject cidr-ip-address [, ... cidr-ip-address ] ;

Therejectstatement causes the DHCP client to reject offers fromservers whose server identifier matches any of the specified hosts orsubnets. This can be used to avoid being configured by rogue ormisconfigured dhcp servers, although it should be a last resort -better to track down the bad DHCP server and fix it.

The cidr-ip-address configuration type is of theform ip-address[/prefixlen], where ip-address is adotted quad IP address, and prefixlen is the CIDR prefix length ofthe subnet, counting the number of significant bits in the netmask startingfrom the leftmost end. Example configuration syntax:

reject 192.168.0.0/16, 10.0.0.5;

The above example would cause offers from any server identifier in theentire RFC 1918 "Class C" network 192.168.0.0/16, or the specificsingle address 10.0.0.5, to be rejected.


 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.

Note well:ISC dhclient only maintains one list of interfaces, which is eitherdetermined at startup from command line arguments, or otherwise isautodetected. If you supplied the list of interfaces on the commandline, this configuration clause will add the named interface to thelist in such a way that will cause it to be configured by DHCP. Whichmay not be the result you had intended. This is an undesirable sideeffect that will be addressed in a future release.


 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 "CLIENTBINDIR/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. 

SEE ALSO

dhcp-options(5), dhcp-eval(5), dhclient.leases(5), dhcpd(8), dhcpd.conf(5),RFC2132, RFC2131. 

AUTHOR

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


 

Index

NAME
DESCRIPTION
PROTOCOL TIMING
LEASE REQUIREMENTS AND REQUESTS
DHCPV6 OPERATION
DYNAMIC DNS
OPTION MODIFIERS
LEASE DECLARATIONS
ALIAS DECLARATIONS
OTHER DECLARATIONS
SAMPLE
SEE ALSO
AUTHOR

This document was created byman2html,using the manual pages.