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