1.\" $OpenBSD: dhcp-options.5,v 1.10 2009/01/13 21:11:57 sthen Exp $ 2.\" 3.\" Copyright (c) 1995, 1996, 1997, 1998 The Internet Software Consortium. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of The Internet Software Consortium nor the names 16.\" of its contributors may be used to endorse or promote products derived 17.\" from this software without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND 20.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 21.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 22.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 23.\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR 24.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 26.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 27.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 28.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" This software has been written for the Internet Software Consortium 34.\" by Ted Lemon <mellon@fugue.com> in cooperation with Vixie 35.\" Enterprises. To learn more about the Internet Software Consortium, 36.\" see ``http://www.isc.org/isc''. To learn more about Vixie 37.\" Enterprises, see ``http://www.vix.com''. 38.\" 39.Dd $Mdocdate: January 13 2009 $ 40.Dt DHCP-OPTIONS 5 41.Os 42.Sh NAME 43.Nm dhcp-options 44.Nd Dynamic Host Configuration Protocol options 45.Sh DESCRIPTION 46The Dynamic Host Configuration protocol allows the client to receive 47.Ic options 48from the DHCP server describing the network configuration and various 49services that are available on the network. 50When configuring 51.Xr dhcpd 8 52or 53.Xr dhclient 8 , 54options must often be declared. 55The syntax for declaring options, and the names and formats of the options 56that can be declared, are documented here. 57.Sh REFERENCE: OPTION STATEMENTS 58DHCP 59.Ic option 60statements always start with the 61.Ic option 62keyword, followed by an option name, followed by option data. 63The option names and data formats are described below. 64It is not necessary to exhaustively specify all DHCP options \- 65only those options which are needed by clients must be specified. 66.Pp 67Option data comes in a variety of formats, as defined below: 68.Pp 69The 70.Ar ip-address 71data type can be entered either as an explicit IP address 72(e.g., 239.254.197.10) or as a domain name (e.g., haagen.isc.org). 73A domain name must resolve to a single IP address. 74.Pp 75The 76.Ar int32 77data type specifies a signed 32-bit integer. 78The 79.Ar uint32 80data type specifies an unsigned 32-bit integer. 81The 82.Ar int16 83and 84.Ar uint16 85data types specify signed and unsigned 16-bit integers. 86The 87.Ar int8 88and 89.Ar uint8 90data types specify signed and unsigned 8-bit integers. 91Unsigned 8-bit integers are also sometimes referred to as octets. 92.Pp 93The 94.Ar string 95data type specifies an 96.Tn NVT 97.Pq Network Virtual Terminal 98.Tn ASCII 99string, which must be enclosed in double quotes \- for example, 100to specify a domain-name option, the syntax would be 101.Pp 102.Dl option domain-name \&"isc.org\&"; 103.Pp 104The 105.Ar flag 106data type specifies a boolean value. 107Booleans can be either true or false 108(or on or off, if that makes more sense to you). 109.Pp 110The 111.Ar data-string 112data type specifies either an 113.Tn NVT ASCII 114string enclosed in double quotes, or a series of octets specified in 115hexadecimal, separated by colons. 116For example: 117.Pp 118.Dl option dhcp-client-identifier \&"CLIENT-FOO\&"; 119or 120.Dl option dhcp-client-identifier 43:4c:49:45:4e:54:2d:46:4f:4f; 121.Pp 122The documentation for the various options mentioned below is taken 123from the IETF draft document on DHCP options, RFC 2132. 124Options which are not listed by name may be defined by the name 125.Pf option\- Ns Ar nnn , 126where 127.Ar nnn 128is the decimal number of the option code. 129These options may be followed either by a string, enclosed in quotes, or by 130a series of octets, expressed as two-digit hexadecimal numbers separated 131by colons. 132For example: 133.Bd -literal -offset indent 134option option-133 "my-option-133-text"; 135option option-129 1:54:c9:2b:47; 136.Ed 137.Pp 138Because 139.Xr dhcpd 8 140does not know the format of these undefined option codes, 141no checking is done to ensure the correctness of the entered data. 142.Pp 143The standard options are: 144.Ss RFC 1497 Vendor Extensions 145.Bl -tag -width Ds 146.It Ic option subnet-mask Ar ip-address ; 147The 148.Ic subnet-mask 149option specifies the client's subnet mask as per RFC 950. 150If no subnet-mask option is provided anywhere in scope, as a last resort 151.Xr dhcpd 8 152will use the subnet mask from the subnet declaration for the network on 153which an address is being assigned. 154However, 155.Em any 156subnet-mask option declaration that is in scope for the address being 157assigned will override the subnet mask specified in the subnet declaration. 158.It Ic option time-offset Ar int32 ; 159The 160.Ic time-offset 161option specifies the offset of the client's subnet in seconds from 162Coordinated Universal Time (UTC). 163.It Xo 164.Ic option routers Ar ip-address 165.Oo , Ar ip-address ... Oc ; 166.Xc 167The 168.Ic routers 169option specifies a list of IP addresses for routers on the client's subnet. 170Routers should be listed in order of preference. 171.It Xo 172.Ic option time-servers Ar ip-address 173.Oo , Ar ip-address ... Oc ; 174.Xc 175The 176.Ic time-server 177option specifies a list of RFC 868 time servers available to the client. 178Servers should be listed in order of preference. 179.It Xo 180.Ic option ien116-name-servers Ar ip-address 181.Oo , Ar ip-address ... Oc ; 182.Xc 183The 184.Ic ien116-name-servers 185option specifies a list of IEN 116 name servers available to the client. 186Servers should be listed in order of preference. 187.It Xo 188.Ic option domain-name-servers Ar ip-address 189.Oo , Ar ip-address ... Oc ; 190.Xc 191The 192.Ic domain-name-servers 193option specifies a list of Domain Name System name servers 194available to the client. 195Servers should be listed in order of preference. 196.It Xo 197.Ic option log-servers Ar ip-address 198.Oo , Ar ip-address ... Oc ; 199.Xc 200The 201.Ic log-servers 202option specifies a list of MIT-LCS UDP log servers available to the client. 203Servers should be listed in order of preference. 204.It Xo 205.Ic option cookie-servers Ar ip-address 206.Oo , Ar ip-address ... Oc ; 207.Xc 208The 209.Ic cookie-servers 210option specifies a list of RFC 865 cookie servers available to the client. 211Servers should be listed in order of preference. 212.It Xo 213.Ic option lpr-servers Ar ip-address 214.Oo , Ar ip-address ... Oc ; 215.Xc 216The 217.Ic lpr-servers 218option specifies a list of RFC 1179 line printer servers available to the 219client. 220Servers should be listed in order of preference. 221.It Xo 222.Ic option impress-servers Ar ip-address 223.Oo , Ar ip-address ... Oc ; 224.Xc 225The 226.Ic impress-servers 227option specifies a list of Imagen Impress servers available to the client. 228Servers should be listed in order of preference. 229.It Xo 230.Ic option resource-location-servers Ar ip-address 231.Oo , Ar ip-address ... Oc ; 232.Xc 233This option specifies a list of RFC 887 Resource Location servers available 234to the client. 235Servers should be listed in order of preference. 236.It Ic option host-name Ar string ; 237This option specifies the name of the client. 238The name may or may not be qualified with the local domain name 239(it is preferable to use the 240.Ic domain-name 241option to specify the domain name). 242See RFC 1035 for character set restrictions. 243.It Ic option boot-size Ar uint16 ; 244This option specifies the length in 512-octet blocks of the default 245boot image for the client. 246.It Ic option merit-dump Ar string ; 247This option specifies the pathname of a file to which the client's 248core image should be dumped in the event the client crashes. 249The path is formatted as a character string consisting of characters from 250the 251.Tn NVT ASCII 252character set. 253.It Ic option domain-name Ar string ; 254This option specifies the domain name that the client should use when 255resolving hostnames via the Domain Name System. 256.It Ic option swap-server Ar ip-address ; 257This specifies the IP address of the client's swap server. 258.It Ic option root-path Ar string ; 259This option specifies the pathname that contains the client's root disk. 260The path is formatted as a character string consisting of characters from 261the 262.Tn NVT ASCII 263character set. 264.El 265.Ss IP Layer Parameters per Host 266.Bl -tag -width Ds 267.It Ic option ip-forwarding Ar flag ; 268This option specifies whether the client should configure its IP layer 269for packet forwarding. 270A value of 0 means disable IP forwarding, and a value of 1 means enable 271IP forwarding. 272.It Ic option non-local-source-routing Ar flag ; 273This option specifies whether the client should configure its IP 274layer to allow forwarding of datagrams with non-local source routes. 275A value of 0 means disallow forwarding of such datagrams, and a value of 1 276means allow forwarding. 277.It Xo 278.Ic option policy-filter Ar ip-address ip-address 279.Oo , Ar ip-address ip-address ... Oc ; 280.Xc 281This option specifies policy filters for non-local source routing. 282The filters consist of a list of IP addresses and masks which specify 283destination/mask pairs with which to filter incoming source routes. 284.Pp 285Any source-routed datagram whose next-hop address does not match one 286of the filters should be discarded by the client. 287.Pp 288See RFC 1122 for further information. 289.It Ic option max-dgram-reassembly Ar uint16 ; 290This option specifies the maximum size datagram that the client should be 291prepared to reassemble. 292The minimum legal value is 576. 293.It Ic option default-ip-ttl Ar uint8 ; 294This option specifies the default time-to-live that the client should 295use on outgoing datagrams. 296.It Ic option path-mtu-aging-timeout Ar uint32 ; 297This option specifies the timeout (in seconds) to use when aging Path 298MTU values discovered by the mechanism defined in RFC 1191. 299.It Xo 300.Ic option path-mtu-plateau-table Ar uint16 301.Oo , Ar uint16 ... Oc ; 302.Xc 303This option specifies a table of MTU sizes to use when performing 304Path MTU Discovery as defined in RFC 1191. 305The table is formatted as a list of 16-bit unsigned integers, 306ordered from smallest to largest. 307The minimum MTU value cannot be smaller than 68. 308.El 309.Ss IP Layer Parameters per Interface 310.Bl -tag -width Ds 311.It Ic option interface-mtu Ar uint16 ; 312This option specifies the MTU to use on this interface. 313The minimum legal value for the MTU is 68. 314.It Ic option all-subnets-local Ar flag ; 315This option specifies whether or not the client may assume that all subnets 316of the IP network to which the client is connected use the same MTU as the 317subnet of that network to which the client is directly connected. 318A value of 1 indicates that all subnets share the same MTU. 319A value of 0 means that the client should assume that some subnets of the 320directly connected network may have smaller MTUs. 321.It Ic option broadcast-address Ar ip-address ; 322This option specifies the broadcast address in use on the client's subnet. 323Legal values for broadcast addresses are specified in section 3.2.1.3 of 324RFC 1122. 325.It Ic option perform-mask-discovery Ar flag ; 326This option specifies whether or not the client should perform subnet mask 327discovery using ICMP. 328A value of 0 indicates that the client should not perform mask discovery. 329A value of 1 means that the client should perform mask discovery. 330.It Ic option mask-supplier Ar flag ; 331This option specifies whether or not the client should respond to subnet mask 332requests using ICMP. 333A value of 0 indicates that the client should not respond. 334A value of 1 means that the client should respond. 335.It Ic option router-discovery Ar flag ; 336This option specifies whether or not the client should solicit routers using 337the Router Discovery mechanism defined in RFC 1256. 338A value of 0 indicates that the client should not perform router discovery. 339A value of 1 means that the client should perform router discovery. 340.It Ic option router-solicitation-address Ar ip-address ; 341This option specifies the address to which the client should transmit 342router solicitation requests. 343.It Xo 344.Ic option static-routes Ar ip-address ip-address 345.Oo , Ar ip-address ip-address ... Oc ; 346.Xc 347This option specifies a list of static routes that the client should 348install in its routing cache. 349If multiple routes to the same destination are specified, they are listed 350in descending order of priority. 351.Pp 352The routes consist of a list of IP address pairs. 353The first address is the destination address, 354and the second address is the router for the destination. 355.Pp 356The default route (0.0.0.0) is an illegal destination for a static route. 357To specify the default route, use the 358.Ic routers 359option. 360.El 361.Ss Link Layer Parameters per Interface 362.Bl -tag -width Ds 363.It Ic option trailer-encapsulation Ar flag ; 364This option specifies whether or not the client should negotiate the 365use of trailers (RFC 893) when using the ARP protocol. 366A value of 0 indicates that the client should not attempt to use trailers. 367A value of 1 means that the client should attempt to use trailers. 368.It Ic option arp-cache-timeout Ar uint32 ; 369This option specifies the timeout in seconds for ARP cache entries. 370.It Ic option ieee802-3-encapsulation Ar flag ; 371This option specifies whether or not the client should use Ethernet 372Version 2 (RFC 894) or IEEE 802.3 (RFC 1042) encapsulation if the 373interface is an Ethernet. 374A value of 0 indicates that the client should use RFC 894 encapsulation. 375A value of 1 means that the client should use RFC 1042 encapsulation. 376.El 377.Ss TCP Parameters 378.Bl -tag -width Ds 379.It Ic option default-tcp-ttl Ar uint8 ; 380This option specifies the default TTL that the client should use when 381sending TCP segments. 382The minimum value is 1. 383.It Ic option tcp-keepalive-interval Ar uint32 ; 384This option specifies the interval (in seconds) that the client TCP 385should wait before sending a keepalive message on a TCP connection. 386The time is specified as a 32-bit unsigned integer. 387A value of zero indicates that the client should not generate keepalive 388messages on connections unless specifically requested by an application. 389.It Ic option tcp-keepalive-garbage Ar flag ; 390This option specifies whether or not the client should send TCP keepalive 391messages with an octet of garbage for compatibility with older implementations. 392A value of 0 indicates that a garbage octet should not be sent. 393A value of 1 indicates that a garbage octet should be sent. 394.El 395.Ss Application and Service Parameters 396.Bl -tag -width Ds 397.It Ic option nis-domain Ar string ; 398This option specifies the name of the client's NIS (Sun Network Information 399Services) domain. 400The domain is formatted as a character string consisting of characters 401from the 402.Tn NVT ASCII 403character set. 404.It Xo 405.Ic option nis-servers Ar ip-address 406.Oo , Ar ip-address ... Oc ; 407.Xc 408This option specifies a list of IP addresses indicating NIS servers 409available to the client. 410Servers should be listed in order of preference. 411.It Xo 412.Ic option ntp-servers Ar ip-address 413.Oo , Ar ip-address ... Oc ; 414.Xc 415This option specifies a list of IP addresses indicating NTP (RFC 1305) 416servers available to the client. 417Servers should be listed in order of preference. 418.It Xo 419.Ic option netbios-name-servers Ar ip-address 420.Oo , Ar ip-address ... Oc ; 421.Xc 422The NetBIOS name server (NBNS) option specifies a list of RFC 1001/1002 423NBNS name servers listed in order of preference. 424NetBIOS Name Service is currently more commonly referred to as WINS. 425WINS servers can be specified using the 426.Ic netbios-name-servers 427option. 428.It Xo 429.Ic option netbios-dd-server Ar ip-address 430.Oo , Ar ip-address ... Oc ; 431.Xc 432The NetBIOS datagram distribution server (NBDD) option specifies a 433list of RFC 1001/1002 NBDD servers listed in order of preference. 434.It Ic option netbios-node-type Ar uint8 ; 435The NetBIOS node type option allows NetBIOS over TCP/IP clients which 436are configurable to be configured as described in RFC 1001/1002. 437The value is specified as a single octet which identifies the client type. 438.Pp 439Possible node types are: 440.Bl -tag -width Ds 441.It 1 442B-node: Broadcast - no WINS 443.It 2 444P-node: Peer - WINS only 445.It 4 446M-node: Mixed - broadcast, then WINS 447.It 8 448H-node: Hybrid - WINS, then broadcast 449.El 450.It Ic option netbios-scope Ar string ; 451The NetBIOS scope option specifies the NetBIOS over TCP/IP scope 452parameter for the client as specified in RFC 1001/1002. 453See RFC 1001, RFC 1002, and RFC 1035 for character-set restrictions. 454.It Xo 455.Ic option font-servers Ar ip-address 456.Oo , Ar ip-address ... Oc ; 457.Xc 458This option specifies a list of X Window System Font servers available 459to the client. 460Servers should be listed in order of preference. 461.It Xo 462.Ic option x-display-manager Ar ip-address 463.Oo , Ar ip-address ... Oc ; 464.Xc 465This option specifies a list of systems that are running the X Window 466System Display Manager and are available to the client. 467Addresses should be listed in order of preference. 468.It Ic option dhcp-client-identifier Ar data-string ; 469This option can be used to specify a DHCP client identifier in a 470host declaration, so that 471.Xr dhcpd 8 472can find the host record by matching against the client identifier. 473.It Ic option nisplus-domain Ar string ; 474This option specifies the name of the client's NIS+ domain. 475The domain is formatted as a character string consisting of characters 476from the 477.Tn NVT ASCII 478character set. 479.It Xo 480.Ic option nisplus-servers Ar ip-address 481.Oo , Ar ip-address ... Oc ; 482.Xc 483This option specifies a list of IP addresses indicating NIS+ servers 484available to the client. 485Servers should be listed in order of preference. 486.It Ic option tftp-server-name Ar string ; 487This option is used to identify a TFTP server and, if supported by the 488client, should have the same effect as the 489.Ic server-name 490declaration. 491BOOTP clients are unlikely to support this option. 492Some DHCP clients will support it, and others actually require it. 493.It Ic option bootfile-name Ar string ; 494This option is used to identify a bootstrap file. 495If supported by the client, it should have the same effect as the 496.Ic filename 497declaration. 498BOOTP clients are unlikely to support this option. 499Some DHCP clients will support it, and others actually require it. 500.It Xo 501.Ic option mobile-ip-home-agent Ar ip-address 502.Oo , Ar ip-address ... Oc ; 503.Xc 504This option specifies a list of IP addresses indicating mobile IP 505home agents available to the client. 506Agents should be listed in order of preference, although normally there 507will be only one such agent. 508.It Xo 509.Ic option smtp-server Ar ip-address 510.Oo , Ar ip-address ... Oc ; 511.Xc 512The 513.Ic smtp-server 514option specifies a list of SMTP servers available to the client. 515Servers should be listed in order of preference. 516.It Xo 517.Ic option pop-server Ar ip-address 518.Oo , Ar ip-address ... Oc ; 519.Xc 520The 521.Ic pop-server 522option specifies a list of POP3 servers available to the client. 523Servers should be listed in order of preference. 524.It Xo 525.Ic option nntp-server Ar ip-address 526.Oo , Ar ip-address ... Oc ; 527.Xc 528The 529.Ic nntp-server 530option specifies a list of NNTP servers available to the client. 531Servers should be listed in order of preference. 532.It Xo 533.Ic option www-server Ar ip-address 534.Oo , Ar ip-address ... Oc ; 535.Xc 536The 537.Ic www-server 538option specifies a list of WWW servers available to the client. 539Servers should be listed in order of preference. 540.It Xo 541.Ic option finger-server Ar ip-address 542.Oo , Ar ip-address ... Oc ; 543.Xc 544The 545.Ic finger-server 546option specifies a list of 547.Xr finger 1 548servers available to the client. 549Servers should be listed in order of preference. 550.It Xo 551.Ic option irc-server Ar ip-address 552.Oo , Ar ip-address ... Oc ; 553.Xc 554The 555.Ic irc-server 556option specifies a list of IRC servers available to the client. 557Servers should be listed in order of preference. 558.It Xo 559.Ic option streettalk-server Ar ip-address 560.Oo , Ar ip-address ... Oc ; 561.Xc 562The 563.Ic streettalk-server 564option specifies a list of StreetTalk servers available to the client. 565Servers should be listed in order of preference. 566.It Xo 567.Ic option streettalk-directory-assistance-server Ar ip-address 568.Oo , Ar ip-address ... Oc ; 569.Xc 570The StreetTalk Directory Assistance (STDA) server option specifies a 571list of STDA servers available to the client. 572Servers should be listed in order of preference. 573.It Xo 574.Ic option voip-configuration-server Ar ip-address 575.Oo , Ar ip-address ... Oc ; 576.Xc 577The 578.Ic voip-configuration-server 579option specifies a list of (normally TFTP) servers that VoIP clients 580may download their configuration information and software images 581from. 582Servers should be listed in order of preference. 583.El 584.Sh SEE ALSO 585.Xr dhclient.conf 5 , 586.Xr dhcpd.conf 5 , 587.Xr dhcpd.leases 5 , 588.Xr dhclient 8 , 589.Xr dhcpd 8 590.Pp 591RFC 2131, RFC 2132. 592.Sh AUTHORS 593.An -nosplit 594.Xr dhcpd 8 595was written by 596.An Ted Lemon Aq mellon@vix.com 597under a contract with Vixie Labs. 598.Pp 599The current implementation was reworked by 600.An Henning Brauer Aq henning@openbsd.org . 601