usr.sbin/rtadvd/rtadvd.conf.5

   1 .\"     $FreeBSD: src/usr.sbin/rtadvd/rtadvd.conf.5,v 1.1.2.9 2002/12/29 16:35:43 schweikh Exp $
   2 .\"     $KAME: rtadvd.conf.5,v 1.35 2001/05/25 07:40:22 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 (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 (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 (num) Flags field in router advertisement message header.
 109 Bit 7
 110 .Pq Li 0x80
 111 means Managed address configuration flag bit,
 112 and Bit 6
 113 .Pq Li 0x40
 114 means Other stateful configuration flag bit.
 115 Bit 4
 116 .Pq Li 0x10
 117 and Bit 3
 118 .Pq Li 0x08
 119 are used to encode router preference.
 120 0x01 means high, 0x00 means medium, and 0x11 means low.
 121 The default value is 0.
 122 .It Cm \&rltime
 123 (num) Router lifetime field
 124 (unit: seconds).
 125 Its value must be no greater than 3600000.
 126 When
 127 .Nm rtadvd
 128 runs on a host, this value must explicitly set 0 on all the
 129 advertising interfaces as described in
 130 .Xr rtadvd 8 .
 131 The default value is 1800.
 132 .It Cm \&rtime
 133 (num) Reachable time field
 134 (unit: milliseconds).
 135 The default value is 0, which means unspecified by this router.
 136 .It Cm \&retrans
 137 (num) Retrans Timer field
 138 (unit: milliseconds).
 139 The default value is 0, which means unspecified by this router.
 140 .El
 141 .Pp
 142 The following items are for ICMPv6 prefix information option,
 143 which will be attached to router advertisement header.
 144 These items can be omitted, then
 145 .Nm rtadvd
 146 will automatically get appropriate prefixes from the kernel's routing table,
 147 and advertise the prefixes with the default parameters.
 148 .Bl -tag -width indent
 149 .It Cm \&clockskew
 150 (num) Time skew to adjust link propagation delays and clock skews
 151 between routers on the link
 152 (unit: seconds).
 153 This value is used in consistency check for locally-configured and
 154 advertised prefix lifetimes, and has its meaning when the local router
 155 configures a prefix on the link with a lifetime that decrements in
 156 real time.
 157 If the value is 0, it means the consistency check will be skipped
 158 for such prefixes.
 159 The default value is 0.
 160 .It Cm \&addrs
 161 (num) Number of prefixes.
 162 Its default is 0, so it must explicitly be set to positive values
 163 if you want to specify any prefix information option.
 164 If its value is 0,
 165 .Xr rtadvd 8
 166 looks up the system routing table and
 167 advertise the prefixes corresponding to interface routes
 168 on the interface.
 169 If its value is more than 1, you must specify the index of the prefix
 170 for each item below.
 171 Indices vary from 0 to N-1, where N is the
 172 value of
 173 .Cm addrs .
 174 Each index shall follow the name of each item, e.g.,
 175 .Dq prefixlen2 .
 176 .It Cm \&prefixlen
 177 (num) Prefix length field.
 178 The default value is 64.
 179 .It Cm \&pinfoflags
 180 (num) Flags field in prefix information option.
 181 Bit 7
 182 .Pq Li 0x80
 183 means On-link flag bit,
 184 and Bit 6
 185 .Pq Li 0x40
 186 means Autonomous address-configuration flag bit.
 187 The default value is 0xc0, i.e., both bits are set.
 188 .It Cm \&addr
 189 (str) The address filled into Prefix field.
 190 Since
 191 .Dq \&:
 192 is used for
 193 .Xr termcap 5
 194 file format as well as IPv6 numeric address, the field MUST be quoted by
 195 doublequote character.
 196 This field cannot be
 197 omitted if the value of
 198 .Cm addrs
 199 is more than 0.
 200 .It Cm \&vltime
 201 (num) Valid lifetime field
 202 (unit: seconds).
 203 The default value is 2592000 (30 days).
 204 .It Cm \&vltimedecr
 205 (bool) This item means the advertised valid lifetime will decrements
 206 in real time, which is disabled by default.
 207 .It Cm \&pltime
 208 (num) Preferred lifetime field
 209 (unit: seconds).
 210 The default value is 604800 (7 days).
 211 .It Cm \&pltimedecr
 212 (bool) This item means the advertised preferred lifetime will decrements
 213 in real time, which is disabled by default.
 214 .El
 215 .Pp
 216 The following item is for ICMPv6 MTU option,
 217 which will be attached to router advertisement header.
 218 This item can be omitted, then
 219 .Nm rtadvd
 220 will use the default value.
 221 .Bl -tag -width indent
 222 .It Cm \&mtu
 223 (num or str) MTU (maximum transmission unit) field.
 224 If 0 is specified, it means that the option will not be included.
 225 The default value is 0.
 226 If the special string
 227 .Dq auto
 228 is specified for this item, MTU option will be included and its value
 229 will be set to the interface MTU automatically.
 230 .El
 231 .Pp
 232 The following item controls ICMPv6 source link-layer address option,
 233 which will be attached to router advertisement header.
 234 As noted above, you can just omit the item, then
 235 .Nm rtadvd
 236 will use the default value.
 237 .Bl -tag -width indent
 238 .It Cm \&nolladdr
 239 (bool) By default
 240 (if
 241 .Cm \&nolladdr
 242 is not specified),
 243 .Xr rtadvd 8
 244 will try to get link-layer address for the interface from the kernel,
 245 and attach that in source link-layer address option.
 246 If this capability exists,
 247 .Xr rtadvd 8
 248 will not attach source link-layer address option to
 249 router advertisement packets.
 250 .El
 251 .Pp
 252 The following item controls ICMPV6 home agent information option,
 253 which was defined with mobile IPv6 support.
 254 It will be attached to router advertisement header just like other options do.
 255 .Bl -tag -width indent
 256 .It Cm \&hapref
 257 (num) Specifies home agent preference.
 258 If set to non-zero,
 259 .Cm \&hatime
 260 must be present as well.
 261 .It Cm \&hatime
 262 (num) Specifies home agent lifetime.
 263 .El
 264 .Pp
 265 When mobile IPv6 support is turned on for
 266 .Xr rtadvd 8 ,
 267 advertisement interval option will be attached to router advertisement
 268 packet, by configuring
 269 .Cm \&maxinterval
 270 explicitly.
 271 .Pp
 272 The following items are for ICMPv6 route information option,
 273 which will be attached to router advertisement header.
 274 These items are optional.
 275 .Bl -tag -width indent
 276 .It Cm \&routes
 277 (num) Number of routes.
 278 Its default is 0, so it must explicitly be set to positive values
 279 if you want to specify any route information option.
 280 If its value is 0, no route information is sent.
 281 If its value is more than 1, you must specify the index of the routes
 282 for each item below.
 283 Indices vary from 0 to N-1, where N is the
 284 value of
 285 .Cm routes .
 286 Each index shall follow the name of each item, e.g.,
 287 .Dq rtrplen2 .
 288 .It Cm \&rtrplen
 289 (num) Prefix length field in route information option.
 290 The default value is 64.
 291 .It Cm \&rtrflags
 292 (num) Flags field in route information option.
 293 Bit 4
 294 .Pq Li 0x10
 295 and
 296 and Bit 3
 297 .Pq Li 0x08
 298 are used to encode router preference for the route.
 299 The default value is 0x00, i.e. medium router preference.
 300 .It Cm \&rtrprefix
 301 (str) The prefix filled into the Prefix field of route information option.
 302 Since
 303 .Dq \&:
 304 is used for
 305 .Xr termcap 5
 306 file format as well as IPv6 numeric address, the field MUST be quoted by
 307 doublequote character.
 308 This field cannot be
 309 omitted if the value of
 310 .Cm addrs
 311 is more than 0.
 312 .It Cm \&rtrltime
 313 (num) route lifetime field in route information option.
 314 (unit: seconds).
 315 The default value is 2592000 (30 days). (not specified in draft-draves-router-selection-01.txt now)
 316 .El
 317 You can also refer one line from another by using
 318 .Cm tc
 319 capability.
 320 See
 321 .Xr termcap 5
 322 for details on the capability.
 323 .Sh EXAMPLES
 324 As presented above, all of the advertised parameters have default values
 325 defined in specifications, and hence you usually do not have to set them
 326 by hand, unless you need special non-default values.
 327 It can cause interoperability problem if you use an ill-configured
 328 parameter.
 329 .Pp
 330 To override a configuration parameter, you can specify the parameter alone.
 331 With the following configuration,
 332 .Xr rtadvd 8
 333 overrides the router lifetime parameter for the
 334 .Li ne0
 335 interface.
 336 .Bd -literal
 337 ne0:\\
 338         :rltime#0:
 339 .Ed
 340 .Pp
 341 The following example manually configures prefixes advertised from the
 342 .Li ef0
 343 interface.
 344 The configuration must be used with the
 345 .Fl s
 346 option to
 347 .Xr rtadvd 8 .
 348 .Bd -literal
 349 ef0:\\
 350         :addrs#1:addr="2001:db8:ffff:1000::":prefixlen#64:
 351 .Ed
 352 .Pp
 353 The following example presents the default values in an explicit manner.
 354 The configuration is provided just for reference purposes;
 355 YOU DO NOT NEED TO HAVE IT AT ALL.
 356 .Bd -literal
 357 default:\\
 358         :chlim#64:raflags#0:rltime#1800:rtime#0:retrans#0:\\
 359         :pinfoflags#192:vltime#2592000:pltime#604800:mtu#0:
 360 ef0:\\
 361         :addrs#1:addr="2001:db8:ffff:1000::":prefixlen#64:tc=default:
 362 .Ed
 363 .Sh SEE ALSO
 364 .Xr termcap 5 ,
 365 .Xr rtadvd 8 ,
 366 .Xr rtsol 8
 367 .Pp
 368 Thomas Narten, Erik Nordmark and W. A. Simpson,
 369 .Do
 370 Neighbor Discovery for IP version 6 (IPv6)
 371 .Dc ,
 372 RFC 2461
 373 .Pp
 374 Richard Draves,
 375 .Do
 376 Default Router Preferences and More-Specific Routes
 377 .Dc ,
 378 draft-ietf-ipngwg-router-selection-01.txt
 379 .Sh HISTORY
 380 The
 381 .Xr rtadvd 8
 382 and the configuration file
 383 .Nm
 384 first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 385 .\" .Sh BUGS
 386 .\" (to be written)