1.\" $NetBSD: rtadvd.conf.5,v 1.18 2012/12/11 16:37:23 roy Exp $ 2.\" $KAME: rtadvd.conf.5,v 1.50 2005/01/14 05:30:59 jinmei Exp $ 3.\" 4.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 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 project nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd December 11, 2012 32.Dt RTADVD.CONF 5 33.Os 34.Sh NAME 35.Nm rtadvd.conf 36.Nd config file for router advertisement daemon 37.Sh DESCRIPTION 38This file describes how the router advertisement packets must be constructed 39for each of the interfaces. 40.Pp 41As described in 42.Xr rtadvd 8 , 43you do not have to set this configuration file up at all, 44unless you need some special configurations. 45You may even omit the file as a whole. 46In such cases, the 47.Nm rtadvd 48daemon will automatically configure itself using default values 49specified in the specification. 50.Pp 51It obeys the famous 52.Xr capfile 5 53file format. 54Each line in the file describes a network interface. 55Fields are separated by a colon 56.Pq Sq \&: , 57and each field contains one capability description. 58Lines may be concatenated by the 59.Sq \e 60character. 61The comment marker is the 62.Sq \&# 63character. 64.Sh CAPABILITIES 65Capabilities describe the value to be filled into ICMPv6 router 66advertisement messages and to control 67.Xr rtadvd 8 68behavior. 69Therefore, you are encouraged to read IETF neighbor discovery documents 70if you would like to modify the sample configuration file. 71.Pp 72Note that almost all items have default values. 73If you omit an item, the default value of the item will be used. 74.Pp 75There are two items which control the interval of sending router advertisements. 76These items can be omitted, then 77.Nm rtadvd 78will use the default values. 79.Bl -tag -width indent 80.It Cm \&maxinterval 81(num) The maximum time allowed between sending unsolicited 82multicast router advertisements 83.Pq unit: seconds . 84The default value is 600. 85Its value must be no less than 4 seconds 86and no greater than 1800 seconds. 87.It Cm \&mininterval 88(num) The minimum time allowed between sending unsolicited multicast 89router advertisements 90.Pq unit: seconds . 91The default value is the one third of value of 92.Cm maxinterval . 93Its value must be no less than 3 seconds and no greater than .75 * 94the value of 95.Cm maxinterval . 96.El 97.Pp 98The following items are for ICMPv6 router advertisement message 99header. 100These items can be omitted, then 101.Nm rtadvd 102will use the default values. 103.Bl -tag -width indent 104.It Cm \&chlim 105(num) The value for Cur Hop Limit field. 106The default value is 64. 107.It Cm \&raflags 108(str or num) A 8-bit flags field in router advertisement message header. 109This field can be specified either as a case-sensitive string or as an 110integer. 111A sting consists of characters each of which corresponds to a 112particular flag bit(s). 113An integer should be the logical OR of all enabled bits. 114Bit 7 115.Po 116.Li 'm' or 0x80 117.Pc 118means Managed address configuration flag bit, 119and Bit 6 120.Po 121.Li 'o' or 0x40 122.Pc 123means Other stateful configuration flag bit. 124Bit 4 125.Po 126.Li 0x10 127.Pc 128and Bit 3 129.Po 130.Li 0x08 131.Pc 132are used to encode router preference. 133Bits 01 134.Po 135or 'h' 136.Pc 137means high, 00 means medium, and 11 138.Po 139or 'l' 140.Pc 141means low. 142Bits 10 is reserved, and must not be specified. 143There is no character to specify the medium preference explicitly. 144The default value of the entire flag is 0 145.Po 146or a null string, 147.Pc 148which means no additional 149configuration methods, and the medium router preference. 150.It Cm \&rltime 151(num) Router lifetime field 152.Pq unit: seconds . 153The value must be either zero or between 154the value of 155.Cm maxinterval 156and 9000. 157When 158.Nm rtadvd 159runs on a host, this value must explicitly set 0 on all the 160advertising interfaces as described in 161.Xr rtadvd 8 . 162The default value is 1800. 163.It Cm \&rtime 164(num) Reachable time field 165.Pq unit: milliseconds . 166The default value is 0, which means unspecified by this router. 167.It Cm \&retrans 168(num) Retrans Timer field 169.Pq unit: milliseconds . 170The default value is 0, which means unspecified by this router. 171.El 172.Pp 173The following items are for ICMPv6 prefix information option, 174which will be attached to router advertisement header. 175These items can be omitted, then 176.Nm rtadvd 177will automatically get appropriate prefixes from the kernel's routing table, 178and advertise the prefixes with the default parameters, unless the 179.Cm noifprefix 180flag is specified. 181Keywords other than 182.Cm clockskew 183and 184.Cm noifprefix 185can be augmented with a number, like 186.Dq Li prefix2 , 187to specify multiple prefixes. 188.Bl -tag -width indent 189.It Cm \&noifprefix 190(bool) Specified whether 191.Nm rtadvd 192should gather prefix information from the interface if no 193.Cm addr 194is specified. 195If no 196.Cm addr 197is given, and 198.Cm noifprefix 199is set, 200.Nm rtadvd 201will send RA packets with no prefix information. 202.It Cm \&clockskew 203(num) Time skew to adjust link propagation delays and clock skews 204between routers on the link 205.Pq unit: seconds . 206This value is used in consistency check for locally-configured and 207advertised prefix lifetimes, and has its meaning when the local router 208configures a prefix on the link with a lifetime that decrements in 209real time. 210If the value is 0, it means the consistency check will be skipped 211for such prefixes. 212The default value is 0. 213.It Cm \&prefixlen 214(num) Prefix length field. 215The default value is 64. 216.It Cm \&pinfoflags 217(str or num) A 8-bit flags field in prefix information option. 218This field can be specified either as a case-sensitive string or as an 219integer. 220A sting consists of characters each of which corresponds to a 221particular flag bit(s). 222An integer should be the logical OR of all enabled bits. 223Bit 7 224.Po 225.Li 'l' or 0x80 226.Pc 227means On-link flag bit, 228and Bit 6 229.Po 230.Li 'a' or 0x40 231.Pc 232means Autonomous address-configuration flag bit. 233The default value is "la" or 0xc0, i.e., both bits are set. 234.It Cm \&addr 235(str) The address filled into Prefix field. 236Since 237.Dq \&: 238is used for 239.Xr capfile 5 240file format as well as IPv6 numeric address, the field MUST be quoted by 241doublequote character. 242.It Cm \&vltime 243(num) Valid lifetime field 244.Pq unit: seconds . 245The default value is 2592000 (30 days). 246.It Cm \&vltimedecr 247(bool) This item means the advertised valid lifetime will decrement 248in real time, which is disabled by default. 249.It Cm \&pltime 250(num) Preferred lifetime field 251.Pq unit: seconds . 252The default value is 604800 (7 days). 253.It Cm \&pltimedecr 254(bool) This item means the advertised preferred lifetime will decrement 255in real time, which is disabled by default. 256.El 257.Pp 258The following item is for ICMPv6 MTU option, 259which will be attached to router advertisement header. 260This item can be omitted, then 261.Nm rtadvd 262will use the default value. 263.Bl -tag -width indent 264.It Cm \&mtu 265(num or str) MTU (maximum transmission unit) field. 266If 0 is specified, it means that the option will not be included. 267The default value is 0. 268If the special string 269.Dq auto 270is specified for this item, MTU option will be included and its value 271will be set to the interface MTU automatically. 272.El 273.Pp 274The following item controls ICMPv6 source link-layer address option, 275which will be attached to router advertisement header. 276As noted above, you can just omit the item, then 277.Nm rtadvd 278will use the default value. 279.Bl -tag -width indent 280.It Cm \&nolladdr 281(bool) By default 282.Po 283if 284.Cm \&nolladdr 285is not specified 286.Pc , 287.Xr rtadvd 8 288will try to get link-layer address for the interface from the kernel, 289and attach that in source link-layer address option. 290If this capability exists, 291.Xr rtadvd 8 292will not attach source link-layer address option to 293router advertisement packets. 294.El 295.Pp 296The following items are for ICMPv6 route information option, 297which will be attached to router advertisement header. 298These items are optional. 299Each items can be augmented with number, like 300.Dq Li rtplen2 , 301to specify multiple routes. 302.Bl -tag -width indent 303.It Cm \&rtprefix 304(str) The prefix filled into the Prefix field of route information option. 305Since 306.Dq \&: 307is used for 308.Xr capfile 5 309file format as well as IPv6 numeric address, the field MUST be quoted by 310doublequote character. 311.It Cm \&rtplen 312(num) Prefix length field in route information option. 313The default value is 64. 314.It Cm \&rtflags 315(str or num) A 8-bit flags field in route information option. 316Currently only the preference values are defined. 317The notation is same as that of the raflags field. 318Bit 4 319.Po 320.Li 0x10 321.Pc 322and Bit 3 323.Po 324.Li 0x08 325.Pc 326are used to encode the route preference for the route. 327The default value is 0x00, i.e. medium preference. 328.It Cm \&rtltime 329(num) route lifetime field in route information option. 330.Pq unit: seconds . 331Since the specification does not define the default value of this 332item, the value for this item should be specified by hand. 333However, 334.Nm rtadvd 335allows this item to be unspecified, and uses the router lifetime 336as the default value in such a case, just for compatibility with an 337old version of the program. 338.El 339.Pp 340In the above list, each keyword beginning with 341.Dq Li rt 342could be replaced with the one beginning with 343.Dq Li rtr 344for backward compatibility reason. 345For example, 346.Cm rtrplen 347is accepted instead of 348.Cm rtplen . 349However, keywords that start with 350.Dq Li rtr 351have basically been obsoleted, and should not be used any more. 352.Pp 353The following items are for ICMPv6 Recursive DNS Server Option and 354DNS Search List Option 355.Pq RFC 6106 , 356which will be attached to router advertisement header. 357These items are optional. 358.Bl -tag -width indent 359.It Cm \&rdnss 360(str) The IPv6 address of one or more recursive DNS servers. 361The argument must be inside double quotes. 362Multiple DNS servers can be specified in a comma-separated string. 363If different lifetimes are needed for different servers, 364separate entries can be given by using 365.Cm rdnss , 366.Cm rdnss0 , 367.Cm rdnss1 , 368.Cm rdnss2 ... 369options with corresponding 370.Cm rdnssltime , 371.Cm rdnssltime0 , 372.Cm rdnssltime1 , 373.Cm rdnssltime2 ... 374entries. 375Note that the maximum number of servers depends on the receiver side. 376See also the 377.Xr resolv.conf 5 378manual page for the resolver implementation. 379.It Cm \&rdnssltime 380The lifetime of the 381.Cm rdnss 382DNS server entries. 383The default value is 3/2 of the interval time. 384.It Cm \&dnssl 385(str) One or more domain names in a comma-separated string. 386These domain names will be used when making DNS queries on a 387non-fully-qualified domain name. 388If different lifetimes are needed for different domains, separate entries 389can be given by using 390.Cm dnssl , 391.Cm dnssl0 , 392.Cm dnssl1 , 393.Cm dnssl2 ... 394options with corresponding 395.Cm dnsslltime , 396.Cm dnsslltime0 , 397.Cm dnsslltime1 , 398.Cm dnsslltime2 ... 399entries. 400Note that the maximum number of names depends on the receiver side. 401See also the 402.Xr resolv.conf 5 403manual page for the resolver implementation. 404.It Cm \&dnsslltime 405The lifetime of the 406.Cm dnssl 407DNS search list entries. 408The default value is 3/2 of the interval time. 409.El 410.Pp 411You can also refer one line from another by using 412.Cm tc 413capability. 414See 415.Xr capfile 5 416for details on the capability. 417.Sh EXAMPLES 418As presented above, all of the advertised parameters have default values 419defined in specifications, and hence you usually do not have to set them 420by hand, unless you need special non-default values. 421It can cause interoperability problem if you use an ill-configured 422parameter. 423.Pp 424To override a configuration parameter, you can specify the parameter alone. 425With the following configuration, 426.Xr rtadvd 8 427overrides the router lifetime parameter for the 428.Li ne0 429interface. 430.Bd -literal 431ne0:\\ 432 :rltime#0: 433.Ed 434.Pp 435The following example manually configures prefixes advertised from the 436.Li ef0 437interface. 438The configuration must be used with the 439.Fl s 440option to 441.Xr rtadvd 8 . 442.Bd -literal 443ef0:\\ 444 :addr="2001:db8:ffff:1000::":prefixlen#64: 445.Ed 446.Pp 447The following example configures the 448.Li wlan0 449interface and adds two DNS servers and a DNS domain search options 450using the default option lifetime values. 451.Bd -literal -offset 452wlan0:\\ 453 :addr="2001:db8:ffff:1000::":prefixlen#64:\\ 454 :rdnss="2001:db8:ffff::10,2001:db8:ffff::2:43":\\ 455 :dnssl="example.com": 456.Ed 457.Pp 458The following example presents the default values in an explicit manner. 459The configuration is provided just for reference purposes; 460YOU DO NOT NEED TO HAVE IT AT ALL. 461.Bd -literal 462default:\\ 463 :chlim#64:raflags#0:rltime#1800:rtime#0:retrans#0:\\ 464 :pinfoflags="la":vltime#2592000:pltime#604800:mtu#0: 465ef0:\\ 466 :addr="2001:db8:ffff:1000::":prefixlen#64:tc=default: 467.Ed 468.Sh SEE ALSO 469.Xr capfile 5 , 470.Xr rtadvd 8 , 471.Xr rtsol 8 472.Pp 473Thomas Narten, Erik Nordmark and W. A. Simpson, 474.Do 475Neighbor Discovery for IP version 6 (IPv6) 476.Dc , 477RFC 2461 478.Pp 479Richard Draves, 480.Do 481Default Router Preferences and More-Specific Routes 482.Dc , 483RFC 4191 484.Pp 485J. Jeong, S. Park, L. Beloeil, S. Madanapalli 486.Do 487IPv6 Router Advertisement Options for DNS Configuration 488.Dc , 489RFC 6106 490.Sh HISTORY 491The 492.Xr rtadvd 8 493and the configuration file 494.Nm 495first appeared in WIDE Hydrangea IPv6 protocol stack kit. 496.\" .Sh BUGS 497.\" (to be written) 498