| blob | e458379ed399c6a3e478d1ce94109f0820ac888a |
1 .\" $NetBSD: rtadvd.conf.5,v 1.18 2012/12/11 16:37:23 roy Exp $
2 .\" $KAME: rtadvd.conf.5,v 1.50 2005/01/14 05:30:59 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 December 11, 2012
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 capfile 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, unless the
179 .Cm noifprefix
180 flag is specified.
181 Keywords other than
182 .Cm clockskew
183 and
184 .Cm noifprefix
185 can be augmented with a number, like
186 .Dq Li prefix2 ,
187 to specify multiple prefixes.
188 .Bl -tag -width indent
189 .It Cm \&noifprefix
190 (bool) Specified whether
191 .Nm rtadvd
192 should gather prefix information from the interface if no
193 .Cm addr
194 is specified.
195 If no
196 .Cm addr
197 is given, and
198 .Cm noifprefix
199 is set,
200 .Nm rtadvd
201 will send RA packets with no prefix information.
202 .It Cm \&clockskew
203 (num) Time skew to adjust link propagation delays and clock skews
204 between routers on the link
205 .Pq unit: seconds .
206 This value is used in consistency check for locally-configured and
207 advertised prefix lifetimes, and has its meaning when the local router
208 configures a prefix on the link with a lifetime that decrements in
209 real time.
210 If the value is 0, it means the consistency check will be skipped
211 for such prefixes.
212 The default value is 0.
213 .It Cm \&prefixlen
214 (num) Prefix length field.
215 The default value is 64.
216 .It Cm \&pinfoflags
217 (str or num) A 8-bit flags field in prefix information option.
218 This field can be specified either as a case-sensitive string or as an
219 integer.
220 A sting consists of characters each of which corresponds to a
221 particular flag bit(s).
222 An integer should be the logical OR of all enabled bits.
223 Bit 7
224 .Po
225 .Li 'l' or 0x80
226 .Pc
227 means On-link flag bit,
228 and Bit 6
229 .Po
230 .Li 'a' or 0x40
231 .Pc
232 means Autonomous address-configuration flag bit.
233 The default value is "la" or 0xc0, i.e., both bits are set.
234 .It Cm \&addr
235 (str) The address filled into Prefix field.
236 Since
237 .Dq \&:
238 is used for
239 .Xr capfile 5
240 file format as well as IPv6 numeric address, the field MUST be quoted by
241 doublequote character.
242 .It Cm \&vltime
243 (num) Valid lifetime field
244 .Pq unit: seconds .
245 The default value is 2592000 (30 days).
246 .It Cm \&vltimedecr
247 (bool) This item means the advertised valid lifetime will decrement
248 in real time, which is disabled by default.
249 .It Cm \&pltime
250 (num) Preferred lifetime field
251 .Pq unit: seconds .
252 The default value is 604800 (7 days).
253 .It Cm \&pltimedecr
254 (bool) This item means the advertised preferred lifetime will decrement
255 in real time, which is disabled by default.
256 .El
257 .Pp
258 The following item is for ICMPv6 MTU option,
259 which will be attached to router advertisement header.
260 This item can be omitted, then
261 .Nm rtadvd
262 will use the default value.
263 .Bl -tag -width indent
264 .It Cm \&mtu
265 (num or str) MTU (maximum transmission unit) field.
266 If 0 is specified, it means that the option will not be included.
267 The default value is 0.
268 If the special string
269 .Dq auto
270 is specified for this item, MTU option will be included and its value
271 will be set to the interface MTU automatically.
272 .El
273 .Pp
274 The following item controls ICMPv6 source link-layer address option,
275 which will be attached to router advertisement header.
276 As noted above, you can just omit the item, then
277 .Nm rtadvd
278 will use the default value.
279 .Bl -tag -width indent
280 .It Cm \&nolladdr
281 (bool) By default
282 .Po
283 if
284 .Cm \&nolladdr
285 is not specified
286 .Pc ,
287 .Xr rtadvd 8
288 will try to get link-layer address for the interface from the kernel,
289 and attach that in source link-layer address option.
290 If this capability exists,
291 .Xr rtadvd 8
292 will not attach source link-layer address option to
293 router advertisement packets.
294 .El
295 .Pp
296 The following items are for ICMPv6 route information option,
297 which will be attached to router advertisement header.
298 These items are optional.
299 Each items can be augmented with number, like
300 .Dq Li rtplen2 ,
301 to specify multiple routes.
302 .Bl -tag -width indent
303 .It Cm \&rtprefix
304 (str) The prefix filled into the Prefix field of route information option.
305 Since
306 .Dq \&:
307 is used for
308 .Xr capfile 5
309 file format as well as IPv6 numeric address, the field MUST be quoted by
310 doublequote character.
311 .It Cm \&rtplen
312 (num) Prefix length field in route information option.
313 The default value is 64.
314 .It Cm \&rtflags
315 (str or num) A 8-bit flags field in route information option.
316 Currently only the preference values are defined.
317 The notation is same as that of the raflags field.
318 Bit 4
319 .Po
320 .Li 0x10
321 .Pc
322 and Bit 3
323 .Po
324 .Li 0x08
325 .Pc
326 are used to encode the route preference for the route.
327 The default value is 0x00, i.e. medium preference.
328 .It Cm \&rtltime
329 (num) route lifetime field in route information option.
330 .Pq unit: seconds .
331 Since the specification does not define the default value of this
332 item, the value for this item should be specified by hand.
333 However,
334 .Nm rtadvd
335 allows this item to be unspecified, and uses the router lifetime
336 as the default value in such a case, just for compatibility with an
337 old version of the program.
338 .El
339 .Pp
340 In the above list, each keyword beginning with
341 .Dq Li rt
342 could be replaced with the one beginning with
343 .Dq Li rtr
344 for backward compatibility reason.
345 For example,
346 .Cm rtrplen
347 is accepted instead of
348 .Cm rtplen .
349 However, keywords that start with
350 .Dq Li rtr
351 have basically been obsoleted, and should not be used any more.
352 .Pp
353 The following items are for ICMPv6 Recursive DNS Server Option and
354 DNS Search List Option
355 .Pq RFC 6106 ,
356 which will be attached to router advertisement header.
357 These items are optional.
358 .Bl -tag -width indent
359 .It Cm \&rdnss
360 (str) The IPv6 address of one or more recursive DNS servers.
361 The argument must be inside double quotes.
362 Multiple DNS servers can be specified in a comma-separated string.
363 If different lifetimes are needed for different servers,
364 separate entries can be given by using
365 .Cm rdnss ,
366 .Cm rdnss0 ,
367 .Cm rdnss1 ,
368 .Cm rdnss2 ...
369 options with corresponding
370 .Cm rdnssltime ,
371 .Cm rdnssltime0 ,
372 .Cm rdnssltime1 ,
373 .Cm rdnssltime2 ...
374 entries.
375 Note that the maximum number of servers depends on the receiver side.
376 See also the
377 .Xr resolv.conf 5
378 manual page for the resolver implementation.
379 .It Cm \&rdnssltime
380 The lifetime of the
381 .Cm rdnss
382 DNS server entries.
383 The default value is 3/2 of the interval time.
384 .It Cm \&dnssl
385 (str) One or more domain names in a comma-separated string.
386 These domain names will be used when making DNS queries on a
387 non-fully-qualified domain name.
388 If different lifetimes are needed for different domains, separate entries
389 can be given by using
390 .Cm dnssl ,
391 .Cm dnssl0 ,
392 .Cm dnssl1 ,
393 .Cm dnssl2 ...
394 options with corresponding
395 .Cm dnsslltime ,
396 .Cm dnsslltime0 ,
397 .Cm dnsslltime1 ,
398 .Cm dnsslltime2 ...
399 entries.
400 Note that the maximum number of names depends on the receiver side.
401 See also the
402 .Xr resolv.conf 5
403 manual page for the resolver implementation.
404 .It Cm \&dnsslltime
405 The lifetime of the
406 .Cm dnssl
407 DNS search list entries.
408 The default value is 3/2 of the interval time.
409 .El
410 .Pp
411 You can also refer one line from another by using
412 .Cm tc
413 capability.
414 See
415 .Xr capfile 5
416 for details on the capability.
417 .Sh EXAMPLES
418 As presented above, all of the advertised parameters have default values
419 defined in specifications, and hence you usually do not have to set them
420 by hand, unless you need special non-default values.
421 It can cause interoperability problem if you use an ill-configured
422 parameter.
423 .Pp
424 To override a configuration parameter, you can specify the parameter alone.
425 With the following configuration,
426 .Xr rtadvd 8
427 overrides the router lifetime parameter for the
428 .Li ne0
429 interface.
430 .Bd -literal
431 ne0:\\
432 :rltime#0:
433 .Ed
434 .Pp
435 The following example manually configures prefixes advertised from the
436 .Li ef0
437 interface.
438 The configuration must be used with the
439 .Fl s
440 option to
441 .Xr rtadvd 8 .
442 .Bd -literal
443 ef0:\\
444 :addr="2001:db8:ffff:1000::":prefixlen#64:
445 .Ed
446 .Pp
447 The following example configures the
448 .Li wlan0
449 interface and adds two DNS servers and a DNS domain search options
450 using the default option lifetime values.
451 .Bd -literal -offset
452 wlan0:\\
453 :addr="2001:db8:ffff:1000::":prefixlen#64:\\
454 :rdnss="2001:db8:ffff::10,2001:db8:ffff::2:43":\\
455 :dnssl="example.com":
456 .Ed
457 .Pp
458 The following example presents the default values in an explicit manner.
459 The configuration is provided just for reference purposes;
460 YOU DO NOT NEED TO HAVE IT AT ALL.
461 .Bd -literal
462 default:\\
463 :chlim#64:raflags#0:rltime#1800:rtime#0:retrans#0:\\
464 :pinfoflags="la":vltime#2592000:pltime#604800:mtu#0:
465 ef0:\\
466 :addr="2001:db8:ffff:1000::":prefixlen#64:tc=default:
467 .Ed
468 .Sh SEE ALSO
469 .Xr capfile 5 ,
470 .Xr rtadvd 8 ,
471 .Xr rtsol 8
472 .Pp
473 Thomas Narten, Erik Nordmark and W. A. Simpson,
474 .Do
475 Neighbor Discovery for IP version 6 (IPv6)
476 .Dc ,
477 RFC 2461
478 .Pp
479 Richard Draves,
480 .Do
481 Default Router Preferences and More-Specific Routes
482 .Dc ,
483 RFC 4191
484 .Pp
485 J. Jeong, S. Park, L. Beloeil, S. Madanapalli
486 .Do
487 IPv6 Router Advertisement Options for DNS Configuration
488 .Dc ,
489 RFC 6106
490 .Sh HISTORY
491 The
492 .Xr rtadvd 8
493 and the configuration file
494 .Nm
495 first appeared in WIDE Hydrangea IPv6 protocol stack kit.
496 .\" .Sh BUGS
497 .\" (to be written)