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