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