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

FreeBSD Manual Pages

  
 
  

home | help
dhcpd-options(5)	      File Formats Manual	      dhcpd-options(5)

NAME
       dhcp-options - Dynamic Host Configuration Protocol options

DESCRIPTION
       The  Dynamic  Host  Configuration protocol allows the client to receive
       options from the	DHCP server describing the network  configuration  and
       various	services that are available on the network.   When configuring
       dhcpd(8)	or dhclient(8) , options must often be declared.   The	syntax
       for  declaring  options,	 and the names and formats of the options that
       can be declared,	are documented here.

REFERENCE: OPTION STATEMENTS
       DHCP option statements always start with	the option  keyword,  followed
       by  an option name, followed by option data.  The option	names and data
       formats are described below.   It  is  not  necessary  to  exhaustively
       specify	all  DHCP  options  -  only  those options which are needed by
       clients must be specified.

       Option data comes in a variety of formats, as defined below:

       The ip-address data type	can be entered either as an  explicit  IP  ad-
       dress   (e.g.,	239.254.197.10)	 or  as	 a  domain  name  (e.g.,  haa-
       gen.isc.org).  When entering a domain name, be sure  that  that	domain
       name resolves to	a single IP address.

       The  int32  data	 type  specifies a signed 32-bit integer.   The	uint32
       data type specifies an unsigned 32-bit integer.	 The int16 and	uint16
       data  types specify signed and unsigned 16-bit integers.	  The int8 and
       uint8 data types	specify	signed and unsigned 8-bit integers.   Unsigned
       8-bit integers are also sometimes referred to as	octets.

       The  text  data	type  specifies	an NVT ASCII string, which must	be en-
       closed in double	quotes - for example, to specify a  root-path  option,
       the syntax would	be

       option root-path	"10.0.1.4:/var/tmp/rootfs";

       The  domain-name	 data type specifies a domain name, which must not en-
       closed in double	quotes.	  This data type is not	used for any  existing
       DHCP options.   The domain name is stored just as if it were a text op-
       tion.

       The flag	data type specifies a boolean value.   Booleans	can be	either
       true or false (or on or off, if that makes more sense to	you).

       The  string  data type specifies	either an NVT ASCII string enclosed in
       double quotes, or a series of octets specified  in  hexadecimal,	 sepa-
       rated by	colons.	  For example:

	 option	dhcp-client-identifier "CLIENT-FOO";
       or
	 option	dhcp-client-identifier 43:4c:49:45:54:2d:46:4f:4f;

SETTING	OPTION VALUES USING EXPRESSIONS
       Sometimes  it's	helpful	 to  be	able to	set the	value of a DHCP	option
       based on	some value that	the client has sent.   To do this, you can use
       expression  evaluation.	 The dhcp-eval(5) manual page describes	how to
       write expressions.   To assign the result of an evaluation  to  an  op-
       tion, define the	option as follows:

	 option	my-option = expression ;

       For example:

	 option	hostname = binary-to-ascii (16,	8, "-",
					    substring (hardware, 1, 6));

STANDARD DHCP OPTIONS
       The documentation for the various options mentioned below is taken from
       the latest IETF draft document on DHCP options.	Options	not listed be-
       low  may	not yet	be implemented,	but it is possible to use such options
       by defining them	in the configuration file.  Please  see	 the  DEFINING
       NEW OPTIONS heading later in this document for more information.

       Some  of	the options documented here are	automatically generated	by the
       DHCP server or by clients, and cannot be	configured by the  user.   The
       value  of  such	an option can be used in the configuration file	of the
       receiving DHCP protocol agent (server or	client), for example in	condi-
       tional  expressions. However, the value of the option cannot be used in
       the configuration file of the sending agent, because the	value  is  de-
       termined	 only  after the configuration file has	been processed.	In the
       following documentation,	such options will be shown as "not  user  con-
       figurable"

       The standard options are:

       option all-subnets-local	flag;

	 This  option  specifies whether or not	the client may assume that all
	 subnets of the	IP network to which the	client is  connected  use  the
	 same  MTU  as	the  subnet of that network to which the client	is di-
	 rectly	connected.  A value of true indicates that all	subnets	 share
	 the  same  MTU.  A value of false means that the client should	assume
	 that some subnets of the directly connected network may have  smaller
	 MTUs.

       option arp-cache-timeout	uint32;

	 This option specifies the timeout in seconds for ARP cache entries.

       option bootfile-name text;

	 This  option  is  used	to identify a bootstrap	file.  If supported by
	 the client, it	should have the	same effect as the  filename  declara-
	 tion.	 BOOTP clients are unlikely to support this option.  Some DHCP
	 clients will support it, and others actually require it.

       option boot-size	uint16;

	 This option specifies the length in 512-octet blocks of  the  default
	 boot image for	the client.

       option broadcast-address	ip-address;

	 This  option  specifies  the broadcast	address	in use on the client's
	 subnet.  Legal	values for broadcast addresses are specified  in  sec-
	 tion 3.2.1.3 of STD 3 (RFC1122).

       option cookie-servers ip-address	[, ip-address...  ];

	 The  cookie  server option specifies a	list of	RFC 865	cookie servers
	 available to the client.  Servers should be listed in order of	 pref-
	 erence.

       option default-ip-ttl uint8;

	 This option specifies the default time-to-live	that the client	should
	 use on	outgoing datagrams.

       option default-tcp-ttl uint8;

	 This option specifies the default TTL that the	client should use when
	 sending TCP segments.	The minimum value is 1.

       option dhcp-client-identifier string;

	 This option can be used to specify a DHCP client identifier in	a host
	 declaration, so that dhcpd can	 find  the  host  record  by  matching
	 against the client identifier.

	 Please	 be  aware that	some DHCP clients, when	configured with	client
	 identifiers that are ASCII text, will prepend a  zero	to  the	 ASCII
	 text.	 So you	may need to write:

	      option dhcp-client-identifier "\0foo";

	 rather	than:

	      option dhcp-client-identifier "foo";

       option dhcp-lease-time uint32;

	 This option is	used in	a client request (DHCPDISCOVER or DHCPREQUEST)
	 to allow the client to	request	a lease	time for the IP	address.  In a
	 server	 reply	(DHCPOFFER), a DHCP server uses	this option to specify
	 the lease time	it is willing to offer.

	 This option is	not directly user configurable in the server; refer to
	 the   max-lease-time	and   default-lease-time   server  options  in
	 dhcpd.conf(5).

       option dhcp-max-message-size uint16;

	 This option, when sent	by the client, specifies the maximum  size  of
	 any response that the server sends to the client.   When specified on
	 the server, if	the client did not send	 a  dhcp-max-message-size  op-
	 tion,	the  size  specified  on  the server is	used.	This works for
	 BOOTP as well as DHCP responses.

       option dhcp-message text;

	 This option is	used by	a DHCP server to provide an error message to a
	 DHCP  client in a DHCPNAK message in the event	of a failure. A	client
	 may use this option in	a DHCPDECLINE  message	to  indicate  why  the
	 client	declined the offered parameters.

	 This option is	not user configurable.

       option dhcp-message-type	uint8;

	 This  option,	sent  by both client and server, specifies the type of
	 DHCP message contained	in the DHCP packet. Possible values (taken di-
	 rectly	from RFC2132) are:

		      1	    DHCPDISCOVER
		      2	    DHCPOFFER
		      3	    DHCPREQUEST
		      4	    DHCPDECLINE
		      5	    DHCPACK
		      6	    DHCPNAK
		      7	    DHCPRELEASE
		      8	    DHCPINFORM

	 This option is	not user configurable.

       option dhcp-option-overload uint8;

	 This  option  is  used	 to  indicate  that the	DHCP 'sname' or	'file'
	 fields	are being overloaded by	using them to carry  DHCP  options.  A
	 DHCP  server  inserts this option if the returned parameters will ex-
	 ceed the usual	space allotted for options.

	 If this option	is present, the	client interprets the specified	 addi-
	 tional	 fields	 after it concludes interpretation of the standard op-
	 tion fields.

	 Legal values for this option are:

		      1	    the	'file' field is	used to	hold options
		      2	    the	'sname'	field is used to hold options
		      3	    both fields	are used to hold options

	 This option is	not user configurable.

       option dhcp-parameter-request-list uint16;

	 This option, when sent	by the client,	specifies  which  options  the
	 client	 wishes	 the  server  to  return.    Normally, in the ISC DHCP
	 client, this is done using the	request	statement.   If	this option is
	 not specified by the client, the DHCP server will normally return ev-
	 ery option that is valid in scope  and	 that  fits  into  the	reply.
	 When  this  option is specified on the	server,	the server returns the
	 specified options.   This can be used to force	a client to  take  op-
	 tions that it hasn't requested, and it	can also be used to tailor the
	 response of the DHCP server for clients that may need a more  limited
	 set of	options	than those the server would normally return.

       option dhcp-rebinding-time uint32;

	 This  option  specifies  the number of	seconds	from the time a	client
	 gets an address until the client transitions to the REBINDING state.

	 This option is	not user configurable.

       option dhcp-renewal-time	uint32;

	 This option specifies the number of seconds from the  time  a	client
	 gets an address until the client transitions to the RENEWING state.

	 This option is	not user configurable.

       option dhcp-requested-address ip-address;

	 This option is	used by	the client in a	DHCPDISCOVER to	request	that a
	 particular IP address be assigned.

	 This option is	not user configurable.

       option dhcp-server-identifier ip-address;

	 This option is	used in	DHCPOFFER and DHCPREQUEST  messages,  and  may
	 optionally  be	 included  in  the DHCPACK and DHCPNAK messages.  DHCP
	 servers include this option in	the DHCPOFFER in order	to  allow  the
	 client	 to  distinguish  between  lease offers.  DHCP clients use the
	 contents of the 'server identifier' field as the destination  address
	 for  any DHCP messages	unicast	to the DHCP server.  DHCP clients also
	 indicate which	of several lease offers	is being accepted by including
	 this option in	a DHCPREQUEST message.

	 The value of this option is the IP address of the server.

	 This option is	not directly user configurable.	See the	server-identi-
	 fier server option in dhcpd.conf(5).

       option domain-name text;

	 This option specifies the domain name that client should use when re-
	 solving hostnames via the Domain Name System.

       option domain-name-servers ip-address [,	ip-address...  ];

	 The domain-name-servers option	specifies a list of Domain Name	System
	 (STD 13, RFC 1035) name servers available  to	the  client.   Servers
	 should	be listed in order of preference.

       option extensions-path text;

	 This  option  specifies  the name of a	file containing	additional op-
	 tions to be interpreted according to the DHCP option format as	speci-
	 fied in RFC2132.

       option finger-server ip-address [, ip-address...	];

	 The Finger server option specifies a list of Finger servers available
	 to the	client.	 Servers should	be listed in order of preference.

       option font-servers ip-address [, ip-address...	];

	 This option specifies a list of X Window System Font  servers	avail-
	 able to the client. Servers should be listed in order of preference.

       option host-name	string;

	 This  option  specifies  the name of the client.  The name may	or may
	 not be	qualified with the local domain	name (it is preferable to  use
	 the domain-name option	to specify the domain name).  See RFC 1035 for
	 character set restrictions.  This option is only honored by dhclient-
	 script(8)  if	the  hostname for the client machine is	not set	(i.e.,
	 set to	the empty string in rc.conf(5) ).

       option ieee802-3-encapsulation flag;

	 This option specifies whether or not the client should	 use  Ethernet
	 Version 2 (RFC	894) or	IEEE 802.3 (RFC	1042) encapsulation if the in-
	 terface is an Ethernet.  A value of false indicates that  the	client
	 should	 use  RFC  894	encapsulation.	A value	of true	means that the
	 client	should use RFC 1042 encapsulation.

       option ien116-name-servers ip-address [,	ip-address...  ];

	 The ien116-name-servers option	specifies  a  list  of	IEN  116  name
	 servers  available  to	the client.  Servers should be listed in order
	 of preference.

       option impress-servers ip-address [, ip-address...  ];

	 The impress-server option specifies a list of Imagen Impress  servers
	 available  to the client.  Servers should be listed in	order of pref-
	 erence.

       option interface-mtu uint16;

	 This option specifies the MTU to use on this interface.   The minimum
	 legal value for the MTU is 68.

       option ip-forwarding flag;

	 This  option  specifies  whether  the	client should configure	its IP
	 layer for packet forwarding.  A value of false	means disable IP  for-
	 warding, and a	value of true means enable IP forwarding.

       option irc-server ip-address [, ip-address... ];

	 The  IRC  server  option specifies a list of IRC servers available to
	 the client.  Servers should be	listed in order	of preference.

       option log-servers ip-address [,	ip-address...  ];

	 The log-server	option specifies a list	of  MIT-LCS  UDP  log  servers
	 available  to the client.  Servers should be listed in	order of pref-
	 erence.

       option lpr-servers ip-address  [, ip-address...	];

	 The LPR server	option specifies a  list  of  RFC  1179	 line  printer
	 servers  available  to	the client.  Servers should be listed in order
	 of preference.

       option mask-supplier flag;

	 This option specifies whether or not the  client  should  respond  to
	 subnet	mask requests using ICMP.  A value of false indicates that the
	 client	should not respond.  A value of	true  means  that  the	client
	 should	respond.

       option max-dgram-reassembly uint16;

	 This  option  specifies  the  maximum	size  datagram that the	client
	 should	be prepared to reassemble.  The	minimum	legal value is 576.

       option merit-dump text;

	 This option specifies the path-name of	a file to which	 the  client's
	 core  image  should  be  dumped in the	event the client crashes.  The
	 path is formatted as a	character string consisting of characters from
	 the NVT ASCII character set.

       option mobile-ip-home-agent ip-address [, ip-address... ];

	 This  option  specifies  a  list of IP	addresses indicating mobile IP
	 home agents available to the client.  Agents should be	listed in  or-
	 der  of  preference,  although	 normally  there will be only one such
	 agent.

       option nds-context string;

	 The nds-context option	specifies the name of the initial Netware  Di-
	 rectory Service for an	NDS client.

       option nds-servers ip-address [,	ip-address... ];

	 The  nds-servers  option  specifies  a	 list  of  IP addresses	of NDS
	 servers.

       option nds-tree-name string;

	 The nds-context option	specifies NDS tree name	that  the  NDS	client
	 should	use.

       option netbios-dd-server	ip-address [, ip-address...  ];

	 The  NetBIOS  datagram	 distribution server (NBDD) option specifies a
	 list of RFC 1001/1002 NBDD servers listed in order of preference.

       option netbios-name-servers ip-address [, ip-address...];

	 The NetBIOS name  server  (NBNS)  option  specifies  a	 list  of  RFC
	 1001/1002  NBNS name servers listed in	order of preference.   NetBIOS
	 Name Service is currently more	commonly referred to as	 WINS.	  WINS
	 servers can be	specified using	the netbios-name-servers option.

       option netbios-node-type	uint8;

	 The NetBIOS node type option allows NetBIOS over TCP/IP clients which
	 are configurable to be	configured as described	in RFC 1001/1002.  The
	 value	is  specified  as  a  single octet which identifies the	client
	 type.

	 Possible node types are:

	 1    B-node: Broadcast	- no WINS

	 2    P-node: Peer - WINS only

	 4    M-node: Mixed - broadcast, then WINS

	 8    H-node: Hybrid - WINS, then broadcast

       option netbios-scope string;

	 The NetBIOS scope option specifies the	NetBIOS	over TCP/IP scope  pa-
	 rameter  for  the  client as specified	in RFC 1001/1002. See RFC1001,
	 RFC1002, and RFC1035 for character-set	restrictions.

       option nis-domain text;

	 This option specifies the name	of the client's	NIS (Sun  Network  In-
	 formation  Services)  domain.	The domain is formatted	as a character
	 string	consisting of characters from the NVT ASCII character set.

       option nis-servers ip-address [,	ip-address...  ];

	 This option specifies a list of IP addresses indicating  NIS  servers
	 available  to the client.  Servers should be listed in	order of pref-
	 erence.

       option nisplus-domain text;

	 This option specifies the name	of the client's	NIS+ domain.  The  do-
	 main is formatted as a	character string consisting of characters from
	 the NVT ASCII character set.

       option nisplus-servers ip-address [, ip-address...  ];

	 This option specifies a list of IP addresses indicating NIS+  servers
	 available  to the client.  Servers should be listed in	order of pref-
	 erence.

       option nntp-server ip-address [,	ip-address... ];

	 The NNTP server option	specifies a list of NNTP servesr available  to
	 the client.  Servers should be	listed in order	of preference.

       option non-local-source-routing flag;

	 This  option  specifies  whether  the	client should configure	its IP
	 layer to allow	forwarding of datagrams	with non-local	source	routes
	 (see  Section	3.3.5 of [4] for a discussion of this topic).  A value
	 of 0 means disallow forwarding	of such	datagrams, and a value of true
	 means allow forwarding.

       option ntp-servers ip-address [,	ip-address...  ];

	 This  option  specifies  a  list  of IP addresses indicating NTP (RFC
	 1035) servers available to the	client.	 Servers should	be  listed  in
	 order of preference.

       option nwip-domain string;

	 The  name  of	the  NetWare/IP	domain that a NetWare/IP client	should
	 use.

       option nwip-suboptions string;

	 A sequence of suboptions for NetWare/IP clients - see RFC2242 for de-
	 tails.	   Normally  this  option  is  set by specifying specific Net-
	 Ware/IP suboptions - see the NETWARE/IP SUBOPTIONS section  for  more
	 information.

       option path-mtu-aging-timeout uint32;

	 This option specifies the timeout (in seconds)	to use when aging Path
	 MTU values discovered by the mechanism	defined	in RFC 1191.

       option path-mtu-plateau-table uint16 [, uint16...  ];

	 This option specifies a table of MTU sizes  to	 use  when  performing
	 Path MTU Discovery as defined in RFC 1191.  The table is formatted as
	 a list	of 16-bit unsigned integers, ordered from smallest to largest.
	 The minimum MTU value cannot be smaller than 68.

       option perform-mask-discovery flag;

	 This option specifies whether or not the client should	perform	subnet
	 mask discovery	using ICMP.  A	value  of  false  indicates  that  the
	 client	should not perform mask	discovery.  A value of true means that
	 the client should perform mask	discovery.

       option policy-filter ip-address ip-address
			 [, ip-address ip-address...];

	 This option specifies policy filters for  non-local  source  routing.
	 The filters consist of	a list of IP addresses and masks which specify
	 destination/mask pairs	with which to filter incoming source routes.

	 Any source routed datagram whose next-hop address does	not match  one
	 of the	filters	should be discarded by the client.

	 See STD 3 (RFC1122) for further information.

       option pop-server ip-address [, ip-address... ];

	 The  POP3 server option specifies a list of POP3 servers available to
	 the client.  Servers should be	listed in order	of preference.

       option resource-location-servers	ip-address
				     [,	ip-address...];

	 This option specifies a list of RFC  887  Resource  Location  servers
	 available  to the client.  Servers should be listed in	order of pref-
	 erence.

       option root-path	text;

	 This option specifies the path-name that contains the	client's  root
	 disk.	 The  path  is	formatted  as a	character string consisting of
	 characters from the NVT ASCII character set.

       option router-discovery flag;

	 This option specifies	whether	 or  not  the  client  should  solicit
	 routers  using	the Router Discovery mechanism defined in RFC 1256.  A
	 value of false	indicates that the client should  not  perform	router
	 discovery.   A	 value	of  true  means	that the client	should perform
	 router	discovery.

       option router-solicitation-address ip-address;

	 This option specifies the address to which the	client should transmit
	 router	solicitation requests.

       option routers ip-address [, ip-address...  ];

	 The  routers  option  specifies a list	of IP addresses	for routers on
	 the client's subnet.  Routers should be listed	in  order  of  prefer-
	 ence.

       option slp-directory-agent boolean ip-address [,	ip-address... ];

	 This  option  specifies  two  things: the IP addresses	of one or more
	 Service Location Protocol Directory Agents, and whether  the  use  of
	 these addresses is mandatory.	 If the	initial	boolean	value is true,
	 the SLP agent should just use the IP addresses	given.	 If the	 value
	 is  false, the	SLP agent may additionally do active or	passive	multi-
	 cast discovery	of SLP agents (see RFC2165 for details).

	 Please	note that in this option and the slp-service-scope option, the
	 term  "SLP Agent" is being used to refer to a Service Location	Proto-
	 col agent running on a	machine	that is	 being	configured  using  the
	 DHCP protocol.

	 Also,	please	be  aware that some companies may refer	to SLP as NDS.
	 If you	have an	NDS directory agent whose address you need to  config-
	 ure, the slp-directory-agent option should work.

       option slp-service-scope	boolean	text;

	 The  Service  Location	 Protocol  Service  Scope Option specifies two
	 things: a list	of service scopes for SLP, and whether the use of this
	 list  is  mandatory.	If  the	initial	boolean	value is true, the SLP
	 agent should only use the list	of scopes  provided  in	 this  option;
	 otherwise,  it	 may use its own static	configuration in preference to
	 the list provided in this option.

	 The text string should	be a comma-separated list of scopes  that  the
	 SLP  agent  should  use.    It	 may be	omitted, in which case the SLP
	 Agent will use	the aggregated list of scopes of all directory	agents
	 known to the SLP agent.

       option smtp-server ip-address [,	ip-address... ];

	 The  SMTP server option specifies a list of SMTP servers available to
	 the client.  Servers should be	listed in order	of preference.

       option static-routes ip-address ip-address
			 [, ip-address ip-address...];

	 This option specifies a list of static	routes that the	client	should
	 install  in its routing cache.	 If multiple routes to the same	desti-
	 nation	are specified, they are	listed in descending order  of	prior-
	 ity.

	 The  routes consist of	a list of IP address pairs.  The first address
	 is the	destination address, and the second address is the router  for
	 the destination.

	 The  default  route  (0.0.0.0)	is an illegal destination for a	static
	 route.	 To specify the	default	route, use the routers option.	 Also,
	 please	note that this option is not intended for classless IP routing
	 - it does not include a subnet	mask.	Since classless	IP routing  is
	 now  the most widely deployed routing standard, this option is	virtu-
	 ally useless, and is not implemented  by  any	of  the	 popular  DHCP
	 clients, for example the Microsoft DHCP client.

       option streettalk-directory-assistance-server ip-address
						  [, ip-address...];

	 The  StreetTalk Directory Assistance (STDA) server option specifies a
	 list of STDA servers available	to  the	 client.   Servers  should  be
	 listed	in order of preference.

       option streettalk-server	ip-address [, ip-address... ];

	 The  StreetTalk  server option	specifies a list of StreetTalk servers
	 available to the client.  Servers should be listed in order of	 pref-
	 erence.

       option subnet-mask ip-address;

	 The  subnet mask option specifies the client's	subnet mask as per RFC
	 950.  If no subnet mask option	is provided anywhere in	 scope,	 as  a
	 last  resort  dhcpd will use the subnet mask from the subnet declara-
	 tion for the network on which an address is being assigned.  However,
	 any  subnet-mask  option declaration that is in scope for the address
	 being assigned	will override the subnet mask specified	in the	subnet
	 declaration.

       option subnet-selection string;

	 Sent  by  the client if an address is required	in a subnet other than
	 the one that would normally be	selected (based	on  the	 relaying  ad-
	 dress	of  the	 connected  subnet  the	request	is obtained from). See
	 RFC3011. Note that the	option number used by this server is 118; this
	 has  not  always  been	the defined number, and	some clients may use a
	 different value. Use of this option should be	regarded  as  slightly
	 experimental!

       This option is not user configurable in the server.

       option swap-server ip-address;

	 This specifies	the IP address of the client's swap server.

       option tcp-keepalive-garbage flag;

	 This  option  specifies  whether  or  not  the	client should send TCP
	 keepalive messages with an octet of garbage  for  compatibility  with
	 older	implementations.   A  value  of	false indicates	that a garbage
	 octet should not be sent. A value of true indicates  that  a  garbage
	 octet should be sent.

       option tcp-keepalive-interval uint32;

	 This  option  specifies the interval (in seconds) that	the client TCP
	 should	wait before sending a keepalive	message	on a  TCP  connection.
	 The  time is specified	as a 32-bit unsigned integer.  A value of zero
	 indicates that	the client should not generate keepalive  messages  on
	 connections unless specifically requested by an application.

       option tftp-server-name text;

	 This  option  is  used	to identify a TFTP server and, if supported by
	 the client, should have the same effect as the	 server-name  declara-
	 tion.	 BOOTP clients are unlikely to support this option.  Some DHCP
	 clients will support it, and others actually require it.

       option time-offset int32;

	 The time-offset option	specifies the offset of	the client's subnet in
	 seconds from Coordinated Universal Time (UTC).

       option time-servers ip-address [, ip-address...	];

	 The  time-server  option  specifies  a	 list  of RFC 868 time servers
	 available to the client.  Servers should be listed in order of	 pref-
	 erence.

       option trailer-encapsulation flag;

	 This  option specifies	whether	or not the client should negotiate the
	 use of	trailers (RFC 893 [14])	when using the ARP protocol.  A	 value
	 of 0 indicates	that the client	should not attempt to use trailers.  A
	 value of true means that the client should attempt to use trailers.

       option uap-servers text;

	 This option specifies a list of URLs, each pointing to	a user authen-
	 tication  service  that  is  capable of processing authentication re-
	 quests	encapsulated in	the User Authentication	Protocol  (UAP).   UAP
	 servers can accept either HTTP	1.1 or SSLv3 connections.  If the list
	 includes a URL	that does not contain a	port component,	the normal de-
	 fault	port  is  assumed  (i.e.,  port	 80  for http and port 443 for
	 https).  If the list includes a URL that does not contain a path com-
	 ponent, the path /uap is assumed.   If	more than one URL is specified
	 in this list, the URLs	are separated by spaces.

       option user-class string;

	 This option is	used by	some DHCP clients as a way for users to	 spec-
	 ify  identifying  information	to the client.	 This can be used in a
	 similar way to	the vendor-class-identifier option, but	the  value  of
	 the  option  is  specified by the user, not the vendor.   Most	recent
	 DHCP clients have a way in the	user interface to  specify  the	 value
	 for this identifier, usually as a text	string.

	 option	vendor-class-identifier	string;

	    This  option  is  used by some DHCP	clients	to identify the	vendor
	    type and possibly the configuration	of a DHCP client.  The	infor-
	    mation  is	a  string  of bytes whose contents are specific	to the
	    vendor and are not specified in a standard.	  To see  what	vendor
	    class  identifier a	clients	are sending, you can write the follow-
	    ing	in your	DHCP server configuration file:

	    set	vendor-class option vendor-class-identifier;

	    This will result in	all entries in the DHCP	server lease  database
	    file  for clients that sent	vendor-class-identifier	options	having
	    a set statement that looks something like this:

	    set	vendor-class "SUNW.Ultra-5_10";

	    The	vendor-class-identifier	option is normally used	 by  the  DHCP
	    server  to	determine the options that are returned	in the vendor-
	    encapsulated-options option.   Please see the VENDOR  ENCAPSULATED
	    OPTIONS section of the dhcpd.conf manual page for further informa-
	    tion.

	 option	vendor-encapsulated-options string;

	    The	vendor-encapsulated-options option can contain either a	single
	    vendor-specific  value  or one or more vendor-specific suboptions.
	    This option	is not normally	specified in the DHCP server  configu-
	    ration  file - instead, a vendor class is defined for each vendor,
	    vendor class suboptions are	defined, values	for  those  suboptions
	    are	 defined,  and the DHCP	server makes up	a response on that ba-
	    sis.

	    Some default behaviours for	well-known DHCP	client	vendors	 (cur-
	    rently, the	Microsoft Windows 2000 DHCP client) are	configured au-
	    tomatically, but otherwise this must be configured manually	-  see
	    the	 VENDOR	 ENCAPSULATED OPTIONS section of the dhcpd.conf	manual
	    page for details.

	 option	www-server ip-address [, ip-address... ];

	    The	WWW server option specifies a list of WWW servers available to
	    the	client.	 Servers should	be listed in order of preference.

	 option	x-display-manager ip-address [,	ip-address...  ];

	    This  option  specifies  a	list of	systems	that are running the X
	    Window System Display Manager and are  available  to  the  client.
	    Addresses should be	listed in order	of preference.

RELAY AGENT INFORMATION	OPTION
       An IETF draft, draft-ietf-dhc-agent-options-11.txt, defines a series of
       encapsulated options that a relay agent can add to a DHCP  packet  when
       relaying	 it to the DHCP	server.	  The server can then make address al-
       location	decisions (or whatever other  decisions	 it  wants)  based  on
       these  options.	  The server also returns these	options	in any replies
       it sends	through	the relay agent, so that the relay agent can  use  the
       information in these options for	delivery or accounting purposes.

       The  current draft defines two options.	 To reference these options in
       the dhcp	server,	specify	the option space name, "agent",	followed by  a
       period, followed	by the option name.   It is not	normally useful	to de-
       fine values for these options in	the server, although it	 is  permissi-
       ble.   These options are	not supported in the client.

       option agent.circuit-id string;

	 The  circuit-id  suboption  encodes  an agent-local identifier	of the
	 circuit from which a DHCP client-to-server packet was	received.   It
	 is  intended for use by agents	in relaying DHCP responses back	to the
	 proper	circuit.   The format of this option is	currently  defined  to
	 be  vendor-dependent, and will	probably remain	that way, although the
	 current draft allows for for the  possibility	of  standardizing  the
	 format	in the future.

       option agent.remote-id string;

	 The remote-id suboption encodes information about the remote host end
	 of a circuit.	 Examples of what it might contain include  caller  ID
	 information,  username	 information,  remote ATM address, cable modem
	 ID, and similar things.   In principal, the meaning is	not well-spec-
	 ified,	and it should generally	be assumed to be an opaque object that
	 is administratively guaranteed	to be unique to	 a  particular	remote
	 end of	a circuit.

THE CLIENT FQDN	SUBOPTIONS
       The  Client FQDN	option,	currently defined in the Internet Draft	draft-
       ietf-dhc-fqdn-option-00.txt is not a standard yet,  but	is  in	suffi-
       ciently wide use	already	that we	have implemented it.   Due to the com-
       plexity of the option format, we	have implemented  it  as  a  suboption
       space  rather than a single option.   In	general	this option should not
       be configured by	the user - instead it should be	used as	part of	an au-
       tomatic DNS update system.

       option fqdn.no-client-update flag;

	 When  the  client sends this, if it is	true, it means the client will
	 not attempt to	update its A record.   When sent by the	server to  the
	 client, it means that the client should not update its	own A record.

       option fqdn.server-update flag;

	 When  the  client sends this to the server, it	is requesting that the
	 server	update its A record.   When sent by the	server,	it means  that
	 the server has	updated	(or is about to	update)	the client's A record.

       option fqdn.encoded flag;

	 If  true,  this indicates that	the domain name	included in the	option
	 is encoded in DNS wire	format,	rather than as plain ASCII text.   The
	 client	 normally  sets	 this  to false	if it doesn't support DNS wire
	 format	in the FQDN option.   The server should	always send  back  the
	 same value that the client sent.   When this value is set on the con-
	 figuration side, it controls the format in which the fqdn.fqdn	subop-
	 tion is encoded.

       option fqdn.rcode1 flag;

       option fqdn.rcode1 flag;

	 These	options	 specify  the  result  of the updates of the A and PTR
	 records, respectively,	and are	only sent by the DHCP  server  to  the
	 DHCP client.  The values of these fields are those defined in the DNS
	 protocol specification.

       option fqdn.fqdn	text;

	 Specifies the domain name that	the client wishes to use.    This  can
	 be a fully-qualified domain name, or a	single label.	If there is no
	 trailing generally update that	name in	some locally-defined domain.

       option fqdn.hostname --never set--;

	 This option should never be set, but it can be	read  back  using  the
	 option	and config-option operators in an expression, in which case it
	 returns the first label in the	fqdn.fqdn suboption - for example,  if
	 the value of fqdn.fqdn	is "foo.example.com.", then fqdn.hostname will
	 be "foo".

       option fqdn.domainname --never set--;

	 This option should never be set, but it can be	read  back  using  the
	 option	and config-option operators in an expression, in which case it
	 returns all labels after the first label in the fqdn.fqdn suboption -
	 for  example,	if  the	value of fqdn.fqdn is "foo.example.com.", then
	 fqdn.hostname will be "example.com.".	 If this  suboption  value  is
	 not  set,  it means that an unqualified name was sent in the fqdn op-
	 tion, or that no fqdn option was sent at all.

       If you wish to use any of these suboptions, we strongly recommend  that
       you refer to the	Client FQDN option draft (or standard, when it becomes
       a standard) - the documentation here is sketchy and incomplete in  com-
       parison,	 and  is just intended for reference by	people who already un-
       derstand	the Client FQDN	option specification.

THE NETWARE/IP SUBOPTIONS
       RFC2242 defines a set of	encapsulated  options  for  Novell  NetWare/IP
       clients.	  To  use these	options	in the dhcp server, specify the	option
       space name, "nwip", followed by a period, followed by the option	 name.
       The following options can be specified:

       option nwip.nsq-broadcast flag;

	 If  true,  the	 client	should use the NetWare Nearest Server Query to
	 locate	a NetWare/IP server.   The behaviour of	the Novell  client  if
	 this suboption	is false, or is	not present, is	not specified.

       option nwip.preferred-dss ip-address [, ip-address... ];

	 This  suboption  specifies a list of up to five IP addresses, each of
	 which should be the IP	address	of a  NetWare  Domain  SAP/RIP	server
	 (DSS).

       option nwip.nearest-nwip-server ip-address
				    [, ip-address...];

	 This  suboption  specifies a list of up to five IP addresses, each of
	 which should be the IP	address	of a Nearest NetWare IP	server.

       option nwip.autoretries uint8;

	 Specifies the number of times that a NetWare/IP client	should attempt
	 to communicate	with a given DSS server	at startup.

       option nwip.autoretry-secs uint8;

	 Specifies  the	number of seconds that a Netware/IP client should wait
	 between retries when attempting to establish  communications  with  a
	 DSS server at startup.

       option nwip.nwip-1-1 uint8;

	 If  true, the NetWare/IP client should	support	NetWare/IP version 1.1
	 compatibility.	  This is only needed if the client will be contacting
	 Netware/IP version 1.1	servers.

       option nwip.primary-dss ip-address;

	 Specifies the IP address of the Primary Domain	SAP/RIP	Service	server
	 (DSS) for this	NetWare/IP  domain.    The  NetWare/IP	administration
	 utility uses this value as Primary DSS	server when configuring	a sec-
	 ondary	DSS server.

DEFINING NEW OPTIONS
       The Internet Software Consortium	DHCP client and	server provide the ca-
       pability	 to define new options.	  Each DHCP option has a name, a code,
       and a structure.	  The name is used by you  to  refer  to  the  option.
       The code	is a number, used by the DHCP server and client	to refer to an
       option.	 The structure describes what the contents of an option	 looks
       like.

       To define a new option, you need	to choose a name for it	that is	not in
       use for some other option - for example,	you can't use "host-name"  be-
       cause  the  DHCP	 protocol already defines a host-name option, which is
       documented earlier in this manual page.	 If an option name doesn't ap-
       pear in this manual page, you can use it, but it's probably a good idea
       to put some kind	of unique string at the	beginning so you can  be  sure
       that  future options don't take your name.   For	example, you might de-
       fine an option, "local-host-name", feeling some confidence that no  of-
       ficial DHCP option name will ever start with "local".

       Once  you  have	chosen a name, you must	choose a code.	For site-local
       options,	all codes between 128 and 254 are reserved for	DHCP  options,
       so  you	can pick any one of these.  In practice, some vendors have in-
       terpreted the protocol rather loosely and have used option code	values
       greater	than 128 themselves.   There's no real way to avoid this prob-
       lem, but	it's not likely	to cause too much trouble in practice.

       The structure of	an option is simply the	format	in  which  the	option
       data  appears.	 The  ISC  DHCP	server currently supports a few	simple
       types, like integers, booleans, strings and IP addresses, and  it  also
       supports	 the  ability  to  define  arrays of single types or arrays of
       fixed sequences of types.

       New options are declared	as follows:

       option new-name code new-code = definition ;

       The values of new-name and new-code should be the name you have	chosen
       for  the	 new  option  and  the	code you have chosen.	The definition
       should be the definition	of the structure of the	option.

       The following simple option type	definitions are	supported:

       BOOLEAN

       option new-name code new-code = boolean ;

       An option of type boolean is a flag with	a value	of either  on  or  off
       (or true	or false).   So	an example use of the boolean type would be:

       option use-zephyr code 180 = boolean;
       option use-zephyr on;

       INTEGER

       option new-name code new-code = sign integer width ;

       The  sign token should either be	blank, unsigned	or signed.   The width
       can be either 8,	16 or 32, and refers to	the number of bits in the  in-
       teger.	 So  for example, the following	two lines show a definition of
       the sql-connection-max option and its use:

       option sql-connection-max code 192 = unsigned integer 16;
       option sql-connection-max 1536;

       IP-ADDRESS

       option new-name code new-code = ip-address ;

       An option whose structure is an IP address can be expressed either as a
       domain name or as a dotted quad.	 So the	following is an	example	use of
       the ip-address type:

       option sql-server-address code 193 = ip-address;
       option sql-server-address sql.example.com;

       TEXT

       option new-name code new-code = text ;

       An option whose type is text will encode	an ASCII  text	string.	   For
       example:

       option sql-default-connection-name code 194 = text;
       option sql-default-connection-name "PRODZA";

       DATA STRING

       option new-name code new-code = string ;

       An  option whose	type is	a data string is essentially just a collection
       of bytes, and can be specified either as	quoted	text,  like  the  text
       type,  or  as  a	list of	hexadecimal contents separated by colons whose
       values must be between 0	and FF.	  For example:

       option sql-identification-token code 195	= string;
       option sql-identification-token 17:23:19:a6:42:ea:99:7c:22;

       ENCAPSULATION

       option new-name code new-code = encapsulate identifier ;

       An option whose type is encapsulate will	encapsulate  the  contents  of
       the  option  space  specified in	identifier.   Examples of encapsulated
       options in the DHCP protocol as it currently exists include the vendor-
       encapsulated-options  option, the netware-suboptions option and the re-
       lay-agent-information option.

       option space local;
       option local.demo code 1	= text;
       option local-encapsulation code 197 = encapsulate local;
       option local.demo "demo";

       ARRAYS

       Options can contain arrays of any of the	above  types  except  for  the
       text and	data string types, which aren't	currently supported in arrays.
       An example of an	array definition is as follows:

       option kerberos-servers code 200	= array	of ip-address;
       option kerberos-servers 10.20.10.1, 10.20.11.1;

       RECORDS

       Options can also	contain	data structures	consisting of  a  sequence  of
       data types, which is sometimes called a record type.   For example:

       option contrived-001 code 201 = { boolean, integer 32, text };
       option contrived-001 on 1772 "contrivance";

       It's  also possible to have options that	are arrays of records, for ex-
       ample:

       option new-static-routes	code 201 = array of {
	    ip-address,	ip-address, ip-address,	integer	8 };
       option static-routes
	    10.0.0.0 255.255.255.0 net-0-rtr.example.com 1,
	    10.0.1.0 255.255.255.0 net-1-rtr.example.com 1,
	    10.2.0.0 255.255.224.0 net-2-0-rtr.example.com 3;

VENDOR ENCAPSULATED OPTIONS
       The DHCP	 protocol  defines  the	  vendor-encapsulated-options  option,
       which  allows vendors to	define their own options that will be sent en-
       capsulated in a standard	DHCP option.   The format of the vendor-encap-
       sulated-options	option is either a series of bytes whose format	is not
       specified, or a sequence	of options, each of which consists of  a  sin-
       gle-byte	vendor-specific	option code, followed by a single-byte length,
       followed	by as many bytes of data as are	specified in the  length  (the
       length does not include itself or the option code).

       The value of this option	can be set in one of two ways.	 The first way
       is to simply specify the	data directly, using a text string or a	colon-
       separated list of hexadecimal values.   For example:

       option vendor-encapsulated-options
	   2:4:AC:11:41:1:
	   3:12:73:75:6e:64:68:63:70:2d:73:65:72:76:65:72:31:37:2d:31:
	   4:12:2f:65:78:70:6f:72:74:2f:72:6f:6f:74:2f:69:38:36:70:63;

       The  second way of setting the value of this option is to have the DHCP
       server generate a vendor-specific option	buffer.	  To do	this, you must
       do four things: define an option	space, define some options in that op-
       tion space, provide values for them, and	specify	that that option space
       should be used to generate the vendor-encapsulated-options option.

       To define a new option space in which vendor options can	be stored, use
       the option space	statement:

       option space name ;

       The name	can then be used in option definitions,	as  described  earlier
       in this document.   For example:

       option space SUNW;
       option SUNW.server-address code 2 = ip-address;
       option SUNW.server-name code 3 =	text;
       option SUNW.root-path code 4 = text;

       Once  you  have defined an option space and the format of some options,
       you can set up scopes that define values	for those options, and you can
       say  when  to  use  them.   For example,	suppose	you want to handle two
       different classes of clients.   Using the option	space definition shown
       in  the	previous example, you can send different option	values to dif-
       ferent clients based on the  vendor-class-identifier  option  that  the
       clients send, as	follows:

       class "vendor-classes" {
	 match option vendor-class-identifier;
       }

       option SUNW.server-address 172.17.65.1;
       option SUNW.server-name "sundhcp-server17-1";

       subclass	"vendor-classes" "SUNW.Ultra-5_10" {
	 vendor-option-space SUNW;
	 option	SUNW.root-path "/export/root/sparc";
       }

       subclass	"vendor-classes" "SUNW.i86pc" {
	 vendor-option-space SUNW;
	 option	SUNW.root-path "/export/root/i86pc";
       }

       As  you	can see	in the preceding example, regular scoping rules	apply,
       so you can define values	that are global	in the global scope, and  only
       define  values  that  are  specific  to a particular class in the local
       scope.	The vendor-option-space	declaration tells the DHCP  server  to
       use  options  in	the SUNW option	space to construct the vendor-encapsu-
       lated-options option.

SEE ALSO
       dhclient.conf(5), dhcp-eval(5), dhclient(8), RFC2132, RFC2131.

AUTHOR
       The Internet Software Consortium	DHCP Distribution was written  by  Ted
       Lemon  under  a contract	with Vixie Labs.  Funding for this project was
       provided	through	the Internet Software Consortium.   Information	 about
       the Internet Software Consortium	can be found at	http://www.isc.org.

							      dhcpd-options(5)

NAME | DESCRIPTION | REFERENCE: OPTION STATEMENTS | SETTING OPTION VALUES USING EXPRESSIONS | STANDARD DHCP OPTIONS | RELAY AGENT INFORMATION OPTION | THE CLIENT FQDN SUBOPTIONS | THE NETWARE/IP SUBOPTIONS | DEFINING NEW OPTIONS | VENDOR ENCAPSULATED OPTIONS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dhcp-options&sektion=5&manpath=FreeBSD+5.2.1-RELEASE>

home | help