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