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 May 17, 1998
  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 sting 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 can be augmented with a number, like
 183 .Dq Li prefix2 ,
 184 to specify multiple prefixes.
 185 .Bl -tag -width indent
 186 .It Cm \&clockskew
 187 (num) Time skew to adjust link propagation delays and clock skews
 188 between routers on the link
 189 .Pq unit: seconds .
 190 This value is used in consistency check for locally-configured and
 191 advertised prefix lifetimes, and has its meaning when the local router
 192 configures a prefix on the link with a lifetime that decrements in
 193 real time.
 194 If the value is 0, it means the consistency check will be skipped
 195 for such prefixes.
 196 The default value is 0.
 197 .It Cm \&prefixlen
 198 (num) Prefix length field.
 199 The default value is 64.
 200 .It Cm \&pinfoflags
 201 (str or num) A 8-bit flags field in prefix information option.
 202 This field can be specified either as a case-sensitive string or as an
 203 integer.
 204 A sting consists of characters each of which corresponds to a
 205 particular flag bit(s).
 206 An integer should be the logical OR of all enabled bits.
 207 Bit 7
 208 .Po
 209 .Li 'l' or 0x80
 210 .Pc
 211 means On-link flag bit,
 212 and Bit 6
 213 .Po
 214 .Li 'a' or 0x40
 215 .Pc
 216 means Autonomous address-configuration flag bit.
 217 The default value is "la" or 0xc0, i.e., both bits are set.
 218 .It Cm \&addr
 219 (str) The address filled into Prefix field.
 220 Since
 221 .Dq \&:
 222 is used for
 223 .Xr termcap 5
 224 file format as well as IPv6 numeric address, the field MUST be quoted by
 225 doublequote character.
 226 .It Cm \&vltime
 227 (num) Valid lifetime field
 228 .Pq unit: seconds .
 229 The default value is 2592000 (30 days).
 230 .It Cm \&vltimedecr
 231 (bool) This item means the advertised valid lifetime will decrement
 232 in real time, which is disabled by default.
 233 .It Cm \&pltime
 234 (num) Preferred lifetime field
 235 .Pq unit: seconds .
 236 The default value is 604800 (7 days).
 237 .It Cm \&pltimedecr
 238 (bool) This item means the advertised preferred lifetime will decrement
 239 in real time, which is disabled by default.
 240 .El
 241 .Pp
 242 The following item is for ICMPv6 MTU option,
 243 which will be attached to router advertisement header.
 244 This item can be omitted, then
 245 .Nm rtadvd
 246 will use the default value.
 247 .Bl -tag -width indent
 248 .It Cm \&mtu
 249 (num or str) MTU (maximum transmission unit) field.
 250 If 0 is specified, it means that the option will not be included.
 251 The default value is 0.
 252 If the special string
 253 .Dq auto
 254 is specified for this item, MTU option will be included and its value
 255 will be set to the interface MTU automatically.
 256 .El
 257 .Pp
 258 The following item controls ICMPv6 source link-layer address option,
 259 which will be attached to router advertisement header.
 260 As noted above, you can just omit the item, then
 261 .Nm rtadvd
 262 will use the default value.
 263 .Bl -tag -width indent
 264 .It Cm \&nolladdr
 265 (bool) By default
 266 .Po
 267 if
 268 .Cm \&nolladdr
 269 is not specified
 270 .Pc ,
 271 .Xr rtadvd 8
 272 will try to get link-layer address for the interface from the kernel,
 273 and attach that in source link-layer address option.
 274 If this capability exists,
 275 .Xr rtadvd 8
 276 will not attach source link-layer address option to
 277 router advertisement packets.
 278 .El
 279 .Pp
 280 The following item controls ICMPv6 home agent information option,
 281 which was defined with mobile IPv6 support.
 282 It will be attached to router advertisement header just like other options do.
 283 .Bl -tag -width indent
 284 .It Cm \&hapref
 285 (num) Specifies home agent preference.
 286 If set to non-zero,
 287 .Cm \&hatime
 288 must be present as well.
 289 .It Cm \&hatime
 290 (num) Specifies home agent lifetime.
 291 .El
 292 .Pp
 293 When mobile IPv6 support is turned on for
 294 .Xr rtadvd 8 ,
 295 advertisement interval option will be attached to router advertisement
 296 packet, by configuring
 297 .Cm \&maxinterval
 298 explicitly.
 299 .Pp
 300 The following items are for ICMPv6 route information option,
 301 which will be attached to router advertisement header.
 302 These items are optional.
 303 Each items can be augmented with number, like
 304 .Dq Li rtplen2 ,
 305 to specify multiple routes.
 306 .Bl -tag -width indent
 307 .It Cm \&rtprefix
 308 (str) The prefix filled into the Prefix field of route information option.
 309 Since
 310 .Dq \&:
 311 is used for
 312 .Xr termcap 5
 313 file format as well as IPv6 numeric address, the field MUST be quoted by
 314 doublequote character.
 315 .It Cm \&rtplen
 316 (num) Prefix length field in route information option.
 317 The default value is 64.
 318 .It Cm \&rtflags
 319 (str or num) A 8-bit flags field in route information option.
 320 Currently only the preference values are defined.
 321 The notation is same as that of the raflags field.
 322 Bit 4
 323 .Po
 324 .Li 0x10
 325 .Pc
 326 and
 327 Bit 3
 328 .Po
 329 .Li 0x08
 330 .Pc
 331 are used to encode the route preference for the route.
 332 The default value is 0x00, i.e., medium preference.
 333 .It Cm \&rtltime
 334 (num) route lifetime field in route information option.
 335 .Pq unit: seconds .
 336 Since the specification does not define the default value of this
 337 item, the value for this item should be specified by hand.
 338 However,
 339 .Nm rtadvd
 340 allows this item to be unspecified, and uses the router lifetime
 341 as the default value in such a case, just for compatibility with an
 342 old version of the program.
 343 .El
 344 .Pp
 345 In the above list, each keyword beginning with
 346 .Dq Li rt
 347 could be replaced with the one beginning with
 348 .Dq Li rtr
 349 for backward compatibility reason.
 350 For example,
 351 .Cm rtrplen
 352 is accepted instead of
 353 .Cm rtplen .
 354 However, keywords that start with
 355 .Dq Li rtr
 356 have basically been obsoleted, and should not be used any more.
 357 .Pp
 358 You can also refer one line from another by using
 359 .Cm tc
 360 capability.
 361 See
 362 .Xr termcap 5
 363 for details on the capability.
 364 .Sh EXAMPLES
 365 As presented above, all of the advertised parameters have default values
 366 defined in specifications, and hence you usually do not have to set them
 367 by hand, unless you need special non-default values.
 368 It can cause interoperability problem if you use an ill-configured
 369 parameter.
 370 .Pp
 371 To override a configuration parameter, you can specify the parameter alone.
 372 With the following configuration,
 373 .Xr rtadvd 8
 374 overrides the router lifetime parameter for the
 375 .Li ne0
 376 interface.
 377 .Bd -literal -offset
 378 ne0:\\
 379         :rltime#0:
 380 .Ed
 381 .Pp
 382 The following example manually configures prefixes advertised from the
 383 .Li ef0
 384 interface.
 385 The configuration must be used with the
 386 .Fl s
 387 option to
 388 .Xr rtadvd 8 .
 389 .Bd -literal -offset
 390 ef0:\\
 391         :addr="3ffe:501:ffff:1000::":prefixlen#64:
 392 .Ed
 393 .Pp
 394 The following example presents the default values in an explicit manner.
 395 The configuration is provided just for reference purposes;
 396 YOU DO NOT NEED TO HAVE IT AT ALL.
 397 .Bd -literal -offset
 398 default:\\
 399         :chlim#64:raflags#0:rltime#1800:rtime#0:retrans#0:\\
 400         :pinfoflags="la":vltime#2592000:pltime#604800:mtu#0:
 401 ef0:\\
 402         :addr="3ffe:501:ffff:1000::":prefixlen#64:tc=default:
 403 .Ed
 404 .Sh SEE ALSO
 405 .Xr termcap 5 ,
 406 .Xr rtadvd 8 ,
 407 .Xr rtsol 8
 408 .Rs
 409 .%A Thomas Narten
 410 .%A Erik Nordmark
 411 .%A W. A. Simpson
 412 .%T Neighbor Discovery for IP version 6 (IPv6)
 413 .%R RFC 2461
 414 .Re
 415 .Rs
 416 .%A Richard Draves
 417 .%T Default Router Preferences and More-Specific Routes
 418 .%R draft-ietf-ipngwg-router-selection-xx.txt
 419 .Re
 420 .Sh HISTORY
 421 The
 422 .Xr rtadvd 8
 423 and the configuration file
 424 .Nm
 425 first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 426 .\" .Sh BUGS
 427 .\" (to be written)