| blob | ef7eb497033d5ee40caad7e6368bacbd707413a9 |
1 .\" $NetBSD: rtadvd.conf.5,v 1.13 2009/08/24 09:45:30 joerg 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 November 1, 2009
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 decrement
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 decrement
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 items are for ICMPv6 route information option,
280 which will be attached to router advertisement header.
281 These items are optional.
282 Each items can be augmented with number, like
283 .Dq Li rtplen2 ,
284 to specify multiple routes.
285 .Bl -tag -width indent
286 .It Cm \&rtprefix
287 (str) The prefix filled into the Prefix field of route information option.
288 Since
289 .Dq \&:
290 is used for
291 .Xr termcap 5
292 file format as well as IPv6 numeric address, the field MUST be quoted by
293 doublequote character.
294 .It Cm \&rtplen
295 (num) Prefix length field in route information option.
296 The default value is 64.
297 .It Cm \&rtflags
298 (str or num) A 8-bit flags field in route information option.
299 Currently only the preference values are defined.
300 The notation is same as that of the raflags field.
301 Bit 4
302 .Po
303 .Li 0x10
304 .Pc
305 and Bit 3
306 .Po
307 .Li 0x08
308 .Pc
309 are used to encode the route preference for the route.
310 The default value is 0x00, i.e. medium preference.
311 .It Cm \&rtltime
312 (num) route lifetime field in route information option.
313 .Pq unit: seconds .
314 Since the specification does not define the default value of this
315 item, the value for this item should be specified by hand.
316 However,
317 .Nm rtadvd
318 allows this item to be unspecified, and uses the router lifetime
319 as the default value in such a case, just for compatibility with an
320 old version of the program.
321 .El
322 .Pp
323 In the above list, each keyword beginning with
324 .Dq Li rt
325 could be replaced with the one beginning with
326 .Dq Li rtr
327 for backward compatibility reason.
328 For example,
329 .Cm rtrplen
330 is accepted instead of
331 .Cm rtplen .
332 However, keywords that start with
333 .Dq Li rtr
334 have basically been obsoleted, and should not be used any more.
335 .Pp
336 You can also refer one line from another by using
337 .Cm tc
338 capability.
339 See
340 .Xr termcap 5
341 for details on the capability.
342 .Sh EXAMPLES
343 As presented above, all of the advertised parameters have default values
344 defined in specifications, and hence you usually do not have to set them
345 by hand, unless you need special non-default values.
346 It can cause interoperability problem if you use an ill-configured
347 parameter.
348 .Pp
349 To override a configuration parameter, you can specify the parameter alone.
350 With the following configuration,
351 .Xr rtadvd 8
352 overrides the router lifetime parameter for the
353 .Li ne0
354 interface.
355 .Bd -literal
356 ne0:\\
357 :rltime#0:
358 .Ed
359 .Pp
360 The following example manually configures prefixes advertised from the
361 .Li ef0
362 interface.
363 The configuration must be used with the
364 .Fl s
365 option to
366 .Xr rtadvd 8 .
367 .Bd -literal
368 ef0:\\
369 :addr="2001:db8:ffff:1000::":prefixlen#64:
370 .Ed
371 .Pp
372 The following example presents the default values in an explicit manner.
373 The configuration is provided just for reference purposes;
374 YOU DO NOT NEED TO HAVE IT AT ALL.
375 .Bd -literal
376 default:\\
377 :chlim#64:raflags#0:rltime#1800:rtime#0:retrans#0:\\
378 :pinfoflags="la":vltime#2592000:pltime#604800:mtu#0:
379 ef0:\\
380 :addr="2001:db8:ffff:1000::":prefixlen#64:tc=default:
381 .Ed
382 .Sh SEE ALSO
383 .Xr termcap 5 ,
384 .Xr rtadvd 8 ,
385 .Xr rtsol 8
386 .Pp
387 Thomas Narten, Erik Nordmark and W. A. Simpson,
388 .Do
389 Neighbor Discovery for IP version 6 (IPv6)
390 .Dc ,
391 RFC 2461
392 .Pp
393 Richard Draves,
394 .Do
395 Default Router Preferences and More-Specific Routes
396 .Dc ,
397 RFC 4191
398 .Sh HISTORY
399 The
400 .Xr rtadvd 8
401 and the configuration file
402 .Nm
403 first appeared in WIDE Hydrangea IPv6 protocol stack kit.
404 .\" .Sh BUGS
405 .\" (to be written)