usr.sbin/rtadvd/rtadvd.conf.5

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