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 swap-server Ar ip-address ; 269This specifies the IP address of the client's swap server. 270.It Ic option root-path Ar string ; 271This option specifies the pathname that contains the client's root disk. 272The path is formatted as a character string consisting of characters from 273the 274.Tn NVT ASCII 275character set. 276.El 277.Ss IP Layer Parameters per Host 278.Bl -tag -width indent 279.It Ic option ip-forwarding Ar flag ; 280This option specifies whether the client should configure its IP layer 281for packet forwarding. 282A value of 0 means disable IP forwarding, and a value of 1 means enable 283IP forwarding. 284.It Ic option non-local-source-routing Ar flag ; 285This option specifies whether the client should configure its IP 286layer to allow forwarding of datagrams with non-local source routes 287(see Section 3.3.5 of [4] for a discussion of this topic). 288A value of 0 means disallow forwarding of such datagrams, and a value of 1 289means allow forwarding. 290.It Xo 291.Ic option policy-filter Ar ip-address ip-address 292.Oo , Ar ip-address ip-address ... Oc ; 293.Xc 294This option specifies policy filters for non-local source routing. 295The filters consist of a list of IP addresses and masks which specify 296destination/mask pairs with which to filter incoming source routes. 297.Pp 298Any source-routed datagram whose next-hop address does not match one 299of the filters should be discarded by the client. 300.Pp 301See STD 3 (RFC 1122) for further information. 302.It Ic option max-dgram-reassembly Ar uint16 ; 303This option specifies the maximum size datagram that the client should be 304prepared to reassemble. 305The minimum legal value is 576. 306.It Ic option default-ip-ttl Ar uint8 ; 307This option specifies the default time-to-live that the client should 308use on outgoing datagrams. 309.It Ic option path-mtu-aging-timeout Ar uint32 ; 310This option specifies the timeout (in seconds) to use when aging Path 311MTU values discovered by the mechanism defined in RFC 1191. 312.It Xo 313.Ic option path-mtu-plateau-table Ar uint16 314.Oo , Ar uint16 ... Oc ; 315.Xc 316This option specifies a table of MTU sizes to use when performing 317Path MTU Discovery as defined in RFC 1191. 318The table is formatted as a list of 16-bit unsigned integers, 319ordered from smallest to largest. 320The minimum MTU value cannot be smaller than 68. 321.El 322.Ss IP Layer Parameters per Interface 323.Bl -tag -width indent 324.It Ic option interface-mtu Ar uint16 ; 325This option specifies the MTU to use on this interface. 326The minimum legal value for the MTU is 68. 327.It Ic option all-subnets-local Ar flag ; 328This option specifies whether or not the client may assume that all subnets 329of the IP network to which the client is connected use the same MTU as the 330subnet of that network to which the client is directly connected. 331A value of 1 indicates that all subnets share the same MTU. 332A value of 0 means that the client should assume that some subnets of the 333directly connected network may have smaller MTUs. 334.It Ic option broadcast-address Ar ip-address ; 335This option specifies the broadcast address in use on the client's subnet. 336Legal values for broadcast addresses are specified in section 3.2.1.3 of 337STD 3 (RFC 1122). 338.It Ic option perform-mask-discovery Ar flag ; 339This option specifies whether or not the client should perform subnet mask 340discovery using ICMP. 341A value of 0 indicates that the client should not perform mask discovery. 342A value of 1 means that the client should perform mask discovery. 343.It Ic option mask-supplier Ar flag ; 344This option specifies whether or not the client should respond to subnet mask 345requests using ICMP. 346A value of 0 indicates that the client should not respond. 347A value of 1 means that the client should respond. 348.It Ic option router-discovery Ar flag ; 349This option specifies whether or not the client should solicit routers using 350the Router Discovery mechanism defined in RFC 1256. 351A value of 0 indicates that the client should not perform router discovery. 352A value of 1 means that the client should perform router discovery. 353.It Ic option router-solicitation-address Ar ip-address ; 354This option specifies the address to which the client should transmit 355router solicitation requests. 356.It Xo 357.Ic option static-routes Ar ip-address ip-address 358.Oo , Ar ip-address ip-address ... Oc ; 359.Xc 360This option specifies a list of static routes that the client should 361install in its routing cache. 362If multiple routes to the same destination are specified, they are listed 363in descending order of priority. 364.Pp 365The routes consist of a list of IP address pairs. 366The first address is the destination address, 367and the second address is the router for the destination. 368.Pp 369The default route (0.0.0.0) is an illegal destination for a static route. 370To specify the default route, use the 371.Ic routers 372option. 373.El 374.Ss Link Layer Parameters per Interface 375.Bl -tag -width indent 376.It Ic option trailer-encapsulation Ar flag ; 377This option specifies whether or not the client should negotiate the 378use of trailers (RFC 893 [14]) when using the ARP protocol. 379A value of 0 indicates that the client should not attempt to use trailers. 380A value of 1 means that the client should attempt to use trailers. 381.It Ic option arp-cache-timeout Ar uint32 ; 382This option specifies the timeout in seconds for ARP cache entries. 383.It Ic option ieee802-3-encapsulation Ar flag ; 384This option specifies whether or not the client should use Ethernet 385Version 2 (RFC 894) or IEEE 802.3 (RFC 1042) encapsulation if the 386interface is an Ethernet. 387A value of 0 indicates that the client should use RFC 894 encapsulation. 388A value of 1 means that the client should use RFC 1042 encapsulation. 389.El 390.Ss TCP Parameters 391.Bl -tag -width indent 392.It Ic option default-tcp-ttl Ar uint8 ; 393This option specifies the default TTL that the client should use when 394sending TCP segments. 395The minimum value is 1. 396.It Ic option tcp-keepalive-interval Ar uint32 ; 397This option specifies the interval (in seconds) that the client TCP 398should wait before sending a keepalive message on a TCP connection. 399The time is specified as a 32-bit unsigned integer. 400A value of zero indicates that the client should not generate keepalive 401messages on connections unless specifically requested by an application. 402.It Ic option tcp-keepalive-garbage Ar flag ; 403This option specifies whether or not the client should send TCP keepalive 404messages with an octet of garbage for compatibility with older implementations. 405A value of 0 indicates that a garbage octet should not be sent. 406A value of 1 indicates that a garbage octet should be sent. 407.El 408.Ss Application and Service Parameters 409.Bl -tag -width indent 410.It Ic option nis-domain Ar string ; 411This option specifies the name of the client's NIS (Sun Network Information 412Services) domain. 413The domain is formatted as a character string consisting of characters 414from the 415.Tn NVT ASCII 416character set. 417.It Xo 418.Ic option nis-servers Ar ip-address 419.Oo , Ar ip-address ... Oc ; 420.Xc 421This option specifies a list of IP addresses indicating NIS servers 422available to the client. 423Servers should be listed in order of preference. 424.It Xo 425.Ic option ntp-servers Ar ip-address 426.Oo , Ar ip-address ... Oc ; 427.Xc 428This option specifies a list of IP addresses indicating NTP (RFC 1305) 429servers available to the client. 430Servers should be listed in order of preference. 431.It Xo 432.Ic option netbios-name-servers Ar ip-address 433.Oo , Ar ip-address ... Oc ; 434.Xc 435The NetBIOS name server (NBNS) option specifies a list of RFC 1001/1002 436NBNS name servers listed in order of preference. 437NetBIOS Name Service is currently more commonly referred to as WINS. 438WINS servers can be specified using the 439.Ic netbios-name-servers 440option. 441.It Xo 442.Ic option netbios-dd-server Ar ip-address 443.Oo , Ar ip-address ... Oc ; 444.Xc 445The NetBIOS datagram distribution server (NBDD) option specifies a 446list of RFC 1001/1002 NBDD servers listed in order of preference. 447.It Ic option netbios-node-type Ar uint8 ; 448The NetBIOS node type option allows NetBIOS over TCP/IP clients which 449are configurable to be configured as described in RFC 1001/1002. 450The value is specified as a single octet which identifies the client type. 451.Pp 452Possible node types are: 453.Bl -tag -width indent 454.It 1 455B-node: Broadcast - no WINS 456.It 2 457P-node: Peer - WINS only 458.It 4 459M-node: Mixed - broadcast, then WINS 460.It 8 461H-node: Hybrid - WINS, then broadcast 462.El 463.It Ic option netbios-scope Ar string ; 464The NetBIOS scope option specifies the NetBIOS over TCP/IP scope 465parameter for the client as specified in RFC 1001/1002. 466See RFC 1001, RFC 1002, and RFC 1035 for character-set restrictions. 467.It Xo 468.Ic option font-servers Ar ip-address 469.Oo , Ar ip-address ... Oc ; 470.Xc 471This option specifies a list of X Window System Font servers available 472to the client. 473Servers should be listed in order of preference. 474.It Xo 475.Ic option x-display-manager Ar ip-address 476.Oo , Ar ip-address ... Oc ; 477.Xc 478This option specifies a list of systems that are running the X Window 479System Display Manager and are available to the client. 480Addresses should be listed in order of preference. 481.It Ic option dhcp-client-identifier Ar data-string ; 482This option can be used to specify a DHCP client identifier in a 483host declaration, so that 484.Xr dhcpd 8 485can find the host record by matching against the client identifier. 486.It Ic option nisplus-domain Ar string ; 487This option specifies the name of the client's NIS+ domain. 488The domain is formatted as a character string consisting of characters 489from the 490.Tn NVT ASCII 491character set. 492.It Xo 493.Ic option nisplus-servers Ar ip-address 494.Oo , Ar ip-address ... Oc ; 495.Xc 496This option specifies a list of IP addresses indicating NIS+ servers 497available to the client. 498Servers should be listed in order of preference. 499.It Ic option tftp-server-name Ar string ; 500This option is used to identify a TFTP server and, if supported by the 501client, should have the same effect as the 502.Ic server-name 503declaration. 504BOOTP clients are unlikely to support this option. 505Some DHCP clients will support it, and others actually require it. 506.It Ic option bootfile-name Ar string ; 507This option is used to identify a bootstrap file. 508If supported by the client, it should have the same effect as the 509.Ic filename 510declaration. 511BOOTP clients are unlikely to support this option. 512Some DHCP clients will support it, and others actually require it. 513.It Xo 514.Ic option mobile-ip-home-agent Ar ip-address 515.Oo , Ar ip-address ... Oc ; 516.Xc 517This option specifies a list of IP addresses indicating mobile IP 518home agents available to the client. 519Agents should be listed in order of preference, although normally there 520will be only one such agent. 521.It Xo 522.Ic option smtp-server Ar ip-address 523.Oo , Ar ip-address ... Oc ; 524.Xc 525The 526.Ic smtp-server 527option specifies a list of SMTP servers available to the client. 528Servers should be listed in order of preference. 529.It Xo 530.Ic option pop-server Ar ip-address 531.Oo , Ar ip-address ... Oc ; 532.Xc 533The 534.Ic pop-server 535option specifies a list of POP3 servers available to the client. 536Servers should be listed in order of preference. 537.It Xo 538.Ic option nntp-server Ar ip-address 539.Oo , Ar ip-address ... Oc ; 540.Xc 541The 542.Ic nntp-server 543option specifies a list of NNTP servers available to the client. 544Servers should be listed in order of preference. 545.It Xo 546.Ic option www-server Ar ip-address 547.Oo , Ar ip-address ... Oc ; 548.Xc 549The 550.Ic www-server 551option specifies a list of WWW servers available to the client. 552Servers should be listed in order of preference. 553.It Xo 554.Ic option finger-server Ar ip-address 555.Oo , Ar ip-address ... Oc ; 556.Xc 557The 558.Ic finger-server 559option specifies a list of 560.Xr finger 1 561servers available to the client. 562Servers should be listed in order of preference. 563.It Xo 564.Ic option irc-server Ar ip-address 565.Oo , Ar ip-address ... Oc ; 566.Xc 567The 568.Ic irc-server 569option specifies a list of IRC servers available to the client. 570Servers should be listed in order of preference. 571.It Xo 572.Ic option streettalk-server Ar ip-address 573.Oo , Ar ip-address ... Oc ; 574.Xc 575The 576.Ic streettalk-server 577option specifies a list of StreetTalk servers available to the client. 578Servers should be listed in order of preference. 579.It Xo 580.Ic option streettalk-directory-assistance-server Ar ip-address 581.Oo , Ar ip-address ... Oc ; 582.Xc 583The StreetTalk Directory Assistance (STDA) server option specifies a 584list of STDA servers available to the client. 585Servers should be listed in order of preference. 586.El 587.Sh SEE ALSO 588.Xr dhclient.conf 5 , 589.Xr dhcpd.conf 5 , 590.Xr dhcpd.leases 5 , 591.Xr dhclient 8 , 592.Xr dhcpd 8 593.Rs 594.%R "RFC 2131, RFC 2132" 595.Re 596.Sh AUTHORS 597.An -nosplit 598The 599.Xr dhcpd 8 600utility 601was written by 602.An Ted Lemon Aq mellon@vix.com 603under a contract with Vixie Labs. 604.Pp 605The current implementation was reworked by 606.An Henning Brauer Aq henning@openbsd.org . 607