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

FreeBSD Manual Pages

  
 
  

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

NAME
       dhclient.conf --	DHCP client configuration file

DESCRIPTION
       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 re-
       quested 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 append to information provided by the server.  The configu-
       ration file can also be preinitialized with addresses to	 use  on  net-
       works that do not 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 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	deter-
	       mine 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 ex-
	       pired, 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	address.  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
	       response	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 seconds.

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

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

LEASE REQUIREMENTS AND REQUESTS
       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  of-
       fers  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	speci-
	       fied 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	speci-
	       fied 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.

       ignore [option] [, ... option];
	       The  ignore statement causes the	client to disregard the	speci-
	       fied options in any offer received, as though  the  server  had
	       never sent them at all.

OPTION MODIFIERS
       In  some	 cases,	a client may receive option data from the server which
       is not really appropriate for that client, or may not receive  informa-
       tion  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  val-
	       ues can be defined in the supersede statement.

	       Some options values have	special	meaning:

	       interface-mtu
		       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
	       supply, 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 val-
	       ues 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 en-
	       forced -	if you ignore it, the behaviour	will be	unpredictable.

LEASE DECLARATIONS
       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 auto-
       matically configure its address.	 This is done with  the	 lease	state-
       ment.

       NOTE:  the  lease statement is also used	in the dhclient.leases file in
       order 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, fol-
       lowed 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 configura-
	       tion 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	speci-
	       fied  in	 the  dhclient.conf file, the interface	should also be
	       specified, 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.,
	       12.34.56.78).

       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
	       declared	 in  dhclient.conf, the	value that the user wishes the
	       client configuration script to use if the predefined  lease  is
	       used.

       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  requesting an address, to test the address once it has been
	       offered,	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
	       dhclient.leases(5).

       medium "media setup";
	       The medium statement can	be used	on systems where  network  in-
	       terfaces	 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 configu-
	       ration  script  when  initializing  the interface.  On Unix and
	       Unix-like systems, the argument is passed  on  the  ifconfig(8)
	       command line when configuring the interface.

	       The  DHCP  client  automatically	 declares this parameter if it
	       used a media type (see the media	 statement)  when  configuring
	       the  interface  in  order  to  obtain  a	lease.	This statement
	       should be used in predefined leases only	if the network	inter-
	       face 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 order	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	gener-
       ally be four digits except for really long leases.  The month is	speci-
       fied  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
       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	perma-
       nent  IP	 address even while roaming.  The Internet Software Consortium
       DHCP client does	not support roaming with fixed addresses directly, but
       in order	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  op-
       tions  other  than  the	subnet-mask option are ignored by the standard
       client configuration script, and	expiry times are ignored.   A  typical
       alias  declaration  includes  an	interface declaration, a fixed-address
       declaration for the IP alias address, and a subnet-mask option declara-
       tion.  A	medium statement should	never be included in an	alias declara-
       tion.

OTHER DECLARATIONS
       reject ip-address;
	       The reject statement causes the DHCP client  to	reject	offers
	       from  servers who use the specified address as a	server identi-
	       fier.  This can be used to avoid	being configured by  rogue  or
	       misconfigured 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 dif-
	       ferent behaviour	depending on which interface is	being  config-
	       ured.   All timing parameters and declarations other than lease
	       and alias declarations can be enclosed in an interface declara-
	       tion, and those parameters will then be used only for  the  in-
	       terface	that matches the specified name.  Interfaces for which
	       there is	no interface declaration will use the  parameters  de-
	       clared  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
	       address.	  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 get-
	       ting 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
	       acquisition (the	DHCPDISCOVER and DHCPOFFER packets).  Once  an
	       address	has  been  acquired, the DHCP client will record it in
	       its lease database and will record the media type used  to  ac-
	       quire  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	net.link.vlan.mtag_pcp
	       sysctl to be set	to 1.

EXAMPLES
       The  following  configuration  file is used on a	laptop which has an IP
       alias of	192.5.5.213, and has  one  interface,  ep0  (a	3Com  3C589C).
       Booting	intervals  have	 been shortened	somewhat from the default, be-
       cause 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;
	     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	"/etc/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, yours
       should be much simpler.	In many	cases, it is sufficient	to just	create
       an empty	dhclient.conf file - the defaults are usually fine.

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

       RFC 2132, RFC 2131.

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

       The   current   implementation	was   reworked	 by   Henning	Brauer
       <henning@openbsd.org>.

FreeBSD	14.3			March 17, 2023		      DHCLIENT.CONF(5)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=dhclient.conf&sektion=5&manpath=FreeBSD+14.3-RELEASE+and+Ports>

home | help