usr.sbin/rtadvd/rtadvd.conf.5

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