Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DHCLIENT.CONF(5)	  FreeBSD File Formats Manual	      DHCLIENT.CONF(5)

     dhclient.conf -- DHCP client configuration	file

     The dhclient.conf file contains configuration information for
     dhclient(8), the Internet Software	Consortium DHCP	Client.

     The dhclient.conf file is a free-form ASCII text file.  It	is parsed by
     the recursive-descent parser built	into dhclient(8).  The file may	con-
     tain extra	tabs and newlines for formatting purposes.  Keywords in	the
     file are case-insensitive.	 Comments may be placed	anywhere within	the
     file (except within quotes).  Comments begin with the `#' character and
     end at the	end of the line.

     The dhclient.conf file can	be used	to configure the behaviour of the
     client in a wide variety of ways: protocol	timing,	information requested
     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, or values to prepend or ap-
     pend to information provided by the server.  The configuration file can
     also be preinitialized with addresses to use on networks that do not have
     DHCP servers.

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

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

     timeout time;
	     The timeout statement determines the amount of time that must
	     pass between the time that	the client begins to try to determine
	     its address and the time that it decides that it is not going to
	     be	able to	contact	a server.  By default, this timeout is sixty
	     seconds.  After the timeout has passed, if	there are any static
	     leases defined in the configuration file, or any leases remaining
	     in	the lease database that	have not yet expired, the client will
	     loop through these	leases attempting to validate them, and	if it
	     finds one that appears to be valid, it will use that lease's ad-
	     dress.  If	there are no valid static leases or unexpired leases
	     in	the lease database, the	client will restart the	protocol after
	     the defined retry interval.

     retry time;
	     The retry statement determines the	time that must pass after the
	     client has	determined that	there is no DHCP server	present	before
	     it	tries again to contact a DHCP server.  By default, this	is
	     five minutes.

     select-timeout time;
	     It	is possible (some might	say desirable) for there to be more
	     than one DHCP server serving any given network.  In this case, it
	     is	possible that a	client may be sent more	than one offer in re-
	     sponse to its initial lease discovery message.  It	may be that
	     one of these offers is preferable to the other (e.g., one offer
	     may have the address the client previously	used, and the other
	     may not).

	     The select-timeout	is the time after the client sends its first
	     lease discovery request at	which it stops waiting for offers from
	     servers, assuming that it has received at least one such offer.
	     If	no offers have been received by	the time the select-timeout
	     has expired, the client will accept the first offer that arrives.

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

     reboot time;
	     When the client is	restarted, it first tries to reacquire the
	     last address it had.  This	is called the INIT-REBOOT state.  If
	     it	is still attached to the same network it was attached to when
	     it	last ran, this is the quickest way to get started.  The	reboot
	     statement sets the	time that must elapse after the	client first
	     tries to reacquire	its old	address	before it gives	up and tries
	     to	discover a new address.	 By default, the reboot	timeout	is ten

     backoff-cutoff time;
	     The client	uses an	exponential backoff algorithm with some	ran-
	     domness, so that if many clients try to configure themselves at
	     the same time, they will not make their requests in lockstep.
	     The backoff-cutoff	statement determines the maximum amount	of
	     time that the client is allowed to	back off.  It defaults to two

     initial-interval time;
	     The initial-interval statement sets the amount of time between
	     the first attempt to reach	a server and the second	attempt	to
	     reach a server.  Each time	a message is sent, the interval	be-
	     tween messages is incremented by twice the	current	interval mul-
	     tiplied by	a random number	between	zero and one.  If it is
	     greater than the backoff-cutoff amount, it	is set to that amount.
	     It	defaults to ten	seconds.

     The DHCP protocol allows the client to request that the server send it
     specific information, and not send	it other information that it is	not
     prepared to accept.  The protocol also allows the client to reject	offers
     from servers if they do not contain information the client	needs, or if
     the information provided is not satisfactory.

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

     request [option] [, ... option];
	     The request statement causes the client to	request	that any
	     server responding to the client send the client its values	for
	     the specified options.  Only the option names should be specified
	     in	the request statement -	not option parameters.

     require [option] [, ... option];
	     The require statement lists options that must be sent in order
	     for an offer to be	accepted.  Offers that do not contain all the
	     listed options will be ignored.

     send { [option declaration] [, ...	option declaration] }
	     The send statement	causes the client to send the specified	op-
	     tions to the server with the specified values.  These are full
	     option declarations as described in dhcp-options(5).  Options
	     that are always sent in the DHCP protocol should not be specified
	     here, except that the client can specify a	dhcp-lease-time	option
	     other than	the default requested lease time, which	is two hours.
	     The other obvious use for this statement is to send information
	     to	the server that	will allow it to differentiate between this
	     client and	other clients or kinds of clients.

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

     default { [option declaration] [, ... option declaration] }
	     If	for some set of	options	the client should use the value	sup-
	     plied by the server, but needs to use some	default	value if no
	     value was supplied	by the server, these values can	be defined in
	     the default statement.

     supersede { [option declaration] [, ... option declaration] }
	     If	for some set of	options	the client should always use its own
	     value rather than any value supplied by the server, these values
	     can be defined in the supersede statement.

	     Some options values have special meaning:

		     Any server-supplied interface MTU is ignored by the
		     client if a supersede zero	value is configured.

     prepend { [option declaration] [, ... option declaration] }
	     If	for some set of	options	the client should use a	value you sup-
	     ply, and then use the values supplied by the server, if any,
	     these values can be defined in the	prepend	statement.  The
	     prepend statement can only	be used	for options which allow	more
	     than one value to be given.  This restriction is not enforced -
	     if	violated, the results are unpredictable.

     append { [option declaration] [, ... option declaration] }
	     If	for some set of	options	the client should first	use the	values
	     supplied by the server, if	any, and then use values you supply,
	     these values can be defined in the	append statement.  The append
	     statement can only	be used	for options which allow	more than one
	     value to be given.	 This restriction is not enforced - if you ig-
	     nore it, the behaviour will be unpredictable.

     The lease declaration:

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

     The DHCP client may decide	after some period of time (see PROTOCOL
     TIMING) that it is	not going to succeed in	contacting a server.  At that
     time, it consults its own database	of old leases and tests	each one that
     has not yet timed out by pinging the listed router	for that lease to see
     if	that lease could work.	It is possible to define one or	more fixed
     leases in the client configuration	file for networks where	there is no
     DHCP or BOOTP service, so that the	client can still automatically config-
     ure its address.  This is done with the lease statement.

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

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

     bootp;  The bootp statement is used to indicate that the lease was	ac-
	     quired using the BOOTP protocol rather than the DHCP protocol.
	     It	is never necessary to specify this in the client configuration
	     file.  The	client uses this syntax	in its lease database file.

     interface "string";
	     The interface lease statement is used to indicate the interface
	     on	which the lease	is valid.  If set, this	lease will only	be
	     tried on a	particular interface.  When the	client receives	a
	     lease from	a server, it always records the	interface number on
	     which it received that lease.  If predefined leases are specified
	     in	the dhclient.conf file,	the interface should also be speci-
	     fied, although this is not	required.

     fixed-address ip-address;
	     The fixed-address statement is used to set	the IP address of a
	     particular	lease.	This is	required for all lease statements.
	     The IP address must be specified as a dotted quad (e.g.,

     filename "string";
	     The filename statement specifies the name of the boot filename to
	     use.  This	is not used by the standard client configuration
	     script, but is included for completeness.

     server-name "string";
	     The server-name statement specifies the name of the boot server
	     name to use.  This	is also	not used by the	standard client	con-
	     figuration	script.

     option option-declaration;
	     The option	statement is used to specify the value of an option
	     supplied by the server, or, in the	case of	predefined leases de-
	     clared in dhclient.conf, the value	that the user wishes the
	     client configuration script to use	if the predefined lease	is

     script "script-name";
	     The script	statement is used to specify the pathname of the DHCP
	     client configuration script.  This	script is used by the DHCP
	     client to set each	interface's initial configuration prior	to re-
	     questing an address, to test the address once it has been of-
	     fered, and	to set the interface's final configuration once	a
	     lease has been acquired.  If no lease is acquired,	the script is
	     used to test predefined leases, if	any, and also called once if
	     no	valid lease can	be identified.	For more information, see

     medium "media setup";
	     The medium	statement can be used on systems where network inter-
	     faces cannot automatically	determine the type of network to which
	     they are connected.  The media setup string is a system-dependent
	     parameter which is	passed to the DHCP client configuration	script
	     when initializing the interface.  On UNIX and UNIX-like systems,
	     the argument is passed on the ifconfig(8) command line when con-
	     figuring the interface.

	     The DHCP client automatically declares this parameter if it used
	     a media type (see the media statement) when configuring the in-
	     terface in	order to obtain	a lease.  This statement should	be
	     used in predefined	leases only if the network interface requires
	     media type	configuration.

     renew date;

     rebind date;

     expire date;
	     The renew statement defines the time at which the DHCP client
	     should begin trying to contact its	server to renew	a lease	that
	     it	is using.  The rebind statement	defines	the time at which the
	     DHCP client should	begin to try to	contact	any DHCP server	in or-
	     der to renew its lease.  The expire statement defines the time at
	     which the DHCP client must	stop using a lease if it has not been
	     able to contact a server in order to renew	it.

     These declarations	are automatically set in leases	acquired by the	DHCP
     client, but must also be configured in predefined leases -	a predefined
     lease whose expiry	time has passed	will not be used by the	DHCP 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 a lease
     expires - it is specified as a number from	zero to	six, with zero being
     Sunday.  When declaring a predefined lease, it can	always be specified as
     zero.  The	year is	specified with the century, so it should generally be
     four digits except	for really long	leases.	 The month is specified	as a
     number starting with 1 for	January.  The day of the month is likewise
     specified starting	with 1.	 The hour is a number between 0	and 23,	the
     minute a number between 0 and 59, and the second also a number between 0
     and 59.

     alias { declarations ... }

     Some DHCP clients running TCP/IP roaming protocols	may require that in
     addition to the lease they	may acquire via	DHCP, their interface also be
     configured	with a predefined IP alias so that they	can have a permanent
     IP	address	even while roaming.  The Internet Software Consortium DHCP
     client does not support roaming with fixed	addresses directly, but	in or-
     der to facilitate such experimentation, the DHCP client can be set	up to
     configure an IP alias using the alias declaration.

     The alias declaration resembles a lease declaration, except that options
     other than	the subnet-mask	option are ignored by the standard client con-
     figuration	script,	and expiry times are ignored.  A typical alias decla-
     ration includes an	interface declaration, a fixed-address declaration for
     the IP alias address, and a subnet-mask option declaration.  A medium
     statement should never be included	in an alias declaration.

     reject ip-address;
	     The reject	statement causes the DHCP client to reject offers from
	     servers who use the specified address as a	server identifier.
	     This can be used to avoid being configured	by rogue or misconfig-
	     ured DHCP servers,	although it should be a	last resort - better
	     to	track down the bad DHCP	server and fix it.

     interface "name" {	declarations ... }
	     A client with more	than one network interface may require differ-
	     ent behaviour depending on	which interface	is being configured.
	     All timing	parameters and declarations other than lease and alias
	     declarations can be enclosed in an	interface declaration, and
	     those parameters will then	be used	only for the interface that
	     matches the specified name.  Interfaces for which there is	no in-
	     terface declaration will use the parameters declared outside of
	     any interface declaration,	or the default settings.

     media "media setup" [, "media setup", ...];
	     The media statement defines one or	more media configuration pa-
	     rameters which may	be tried while attempting to acquire an	IP ad-
	     dress.  The DHCP client will cycle	through	each media setup
	     string on the list, configuring the interface using that setup
	     and attempting to boot, and then trying the next one.  This can
	     be	used for network interfaces which are not capable of sensing
	     the media type unaided - whichever	media type succeeds in getting
	     a request to the server and hearing the reply is probably right
	     (no guarantees).

	     The media setup is	only used for the initial phase	of address ac-
	     quisition (the DHCPDISCOVER and DHCPOFFER packets).  Once an ad-
	     dress has been acquired, the DHCP client will record it in	its
	     lease database and	will record the	media type used	to acquire the
	     address.  Whenever	the client tries to renew the lease, it	will
	     use that same media type.	The lease must expire before the
	     client will go back to cycling through media types.

     vlan-pcp code;
	     The vlan-pcp statement sets the PCP (Priority Code	Point) value
	     for the VLAN header.  This	requires the
	     sysctl to be set to 1.

     The following configuration file is used on a laptop which	has an IP
     alias of, and has one interface, ep0 (a 3Com 3C589C).	Boot-
     ing intervals have	been shortened somewhat	from the default, because the
     client is known to	spend most of its time on networks with	little DHCP
     activity.	The laptop does	roam to	multiple networks.

	   timeout 60;
	   retry 60;
	   reboot 10;
	   select-timeout 5;
	   initial-interval 2;

	   interface "ep0" {
	       send host-name "";
	       send dhcp-client-identifier 1:0:a0:24:ab:fb:9c;
	       send dhcp-lease-time 3600;
	       supersede domain-name "";
	       prepend domain-name-servers;
	       request subnet-mask, broadcast-address, time-offset, routers,
		       domain-name, domain-name-servers, host-name;
	       require subnet-mask, domain-name-servers;
	       script "/etc/dhclient-script";
	       media "media 10baseT/UTP", "media 10base2/BNC";

	   alias {
	     interface "ep0";
	     option subnet-mask;

     This is a very complicated	dhclient.conf file - in	general, yours should
     be	much simpler.  In many cases, it is sufficient to just create an empty
     dhclient.conf file	- the defaults are usually fine.

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

     RFC 2132, RFC 2131.

     The dhclient(8) utility was written by Ted	Lemon <> under a
     contract with Vixie Labs.

     The current implementation	was reworked by	Henning	Brauer

FreeBSD	13.0			 July 21, 2021			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help