xref: /freebsd/usr.sbin/rrenumd/rrenumd.conf.5 (revision 1b6c76a2fe091c74f08427e6c870851025a9cf67) 
1.\"	$KAME: rrenumd.conf.5,v 1.8 2001/02/06 02:17:23 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.\"     $FreeBSD$
31.\"
32.Dd November 5, 1998
33.Dt RRENUMD.CONF 5
34.Os KAME
35.Sh NAME
36.\"
37.Nm rrenumd.conf
38.Nd configuration file for router renumbering daemon
39.\"
40.Sh DESCRIPTION
41The rrenumd config file describes how the router renumbering packet
42must be constructed and to which destinations it should be sent.
43This file consists of a sequence of statements terminated by a semi-colon (`;').
44Statements are composed of tokens
45separated by white space, which can be any combination of blanks, tabs
46and newlines.
47This structure simplifies identification of
48the parts of the configuration associated with each other.
49Lines beginning with
50.Ql #
51are comments.
52.\"
53.Sh Meta Syntax
54Keywords and special characters that the parser expects exactly are
55displayed using the
56.Ic bold
57font.
58Parameters are specifying with
59.Ar underline .
60Parameters shown in
61square brackets (`[' and `]') are used to show optional
62keywords and parameters.
63The vertical bar (`|') is used to indicate
64between a choice of optional parameters.
65Curly braces (`{' and
66`}') are used to group keywords and parameters when necessary.
67.\"
68.Sh Interface specification
69There are some statements that may or have to specify interface.
70Interfaces are specified in the form of "name unit", such as
71.Ar lo0
72and
73.Ar ep1 .
74.\"
75.Sh Configuration Statements
76.Bl -tag -width Ds
77.\"
78.It Ic debug on|off ;
79Enables configuration file parser debugging.
80If
81.Ic on
82is specified,
83then debugging is enabled,
84If
85.Ic off
86is specified,
87then debugging is disabled.
88It is disabled by default.
89.\"
90.It Ic dest Ar dest-list Op Ar retrycmd ;
91Specifies destinations to which router renumbering messages should be
92sent.
93.Ar dest-list
94can be any combination of single or multiple numerical IPv6 addrs,
95or Full Qualified Domain Names.
96.Ar retrycmd
97has following syntax.
98.\"
99.Bl -tag -width Ds
100.It Ic retry Ar retry-num
101.Ar retry-num
102specifies how many router renumbering messages are sent repeatedly.
103.El
104.It Op Ic add|change|setglobal
105.Cm match-prefix Ar match-prefix-val
106.Bk -words
107.Op /match-prefix-len
108.Ek
109.Bk -words
110.Op Cm maxlen Ar maxlen-val
111.Ek
112.Bk -words
113.Op Cm minlen Ar minlen-val
114.Ek
115.Bk -words
116.Op Cm use-prefix Ar use-prefix-val
117.Ek
118.Bk -words
119.Op /use-prefix-len
120.Ek
121.Bk -words
122.Op Cm keeplen Ar keeplen-val
123.Ek
124.Bk -words
125.Op Ar use-prefix-values ;
126.Pp
127Specifies contents of sending router renumbering message with seqnum 0.
128If
129.Cm add|change|setglobal
130is not specified, then
131.Cm add
132is assumed.
133.Ar use-prefix-values
134has following syntax.
135.Pp
136{
137.Op Cm vltime Ar vltime-val
138.Bk -words
139.Op Cm pltime Ar pltime-val
140.Ek
141.Bk -words
142.Op Cm raf_onlink Cm on|off
143.Ek
144.Bk -words
145.Op Cm raf_auto Cm on|off
146.Ek
147.Bk -words
148.Op Cm rrf_decrprefd Cm on|off
149.Ek
150.Bk -words
151.Op Cm rrf_decrvalid Cm on|off
152.Ek
153}
154.Pp
155Each value has following meaning.
156.Pp
157.Bl -tag -width Ds -compact
158.It Cm match-prefix Ar match-prefix-val Op /match-prefix-len
159Specify
160.Ar match-prefix-val
161that is used for matching with preassigned prefixes to which
162.Cm add|change|setglobal
163command should be applied.
164.Ar /match-prefix-len
165Specify the starting part of
166.Ar match-prefix-val
167to be used for matching with preassigned prefixes, as decimal bit number.
168.It Cm maxlen Ar maxlen-val
169Specify the maximum length of prefixes which is allowed to be
170matched to
171.Ar match-prefix-val ,
172as decimal bit number.
173.It Cm minlen Ar minlen-val
174Specify the minimum length of prefixes which is allowed to be matched to
175.Ar match-prefix-val ,
176as decimal bit number.
177.It Cm use-prefix Ar use-prefix-val Op /usr-prefix-len
178Specify
179.Ar use-prefix-val
180that is used for prefixes to be added on
181.Cm add|change|setglobal
182command.
183.Ar /use-prefix-len
184Specify the starting part of
185.Ar use-prefix-val
186copied to the starting part of prefixes to be added on
187.Cm add|change|setglobal
188command, as decimal bit number.
189.It Cm keeplen Ar keeplen-val
190Specify the medium part of
191.Ar use-prefix-val
192just next to the starting part specified by
193.Ar use-prefix-len
194, as decimal bit number.
195Contiguous bits part in the same bit position of an existent prefix
196matched with
197.Ar match-prefix-val
198is copied to the same bit position of prefixes to be added.
199.It Cm vltime Ar vmtime-val
200Assign an
201.Ar time
202as prefix valid life time for a prefix to be added.
203Valid value for
204.Ar time
205is decimal seconds number or special format as "d00h00m00s00",
206where 00 can take any decimal number, and "d" means days, "h" means hours,
207"m" means minutes, "s" means seconds.
208And alternatively, special keyword
209"infinity" can be also be specified.
210.It Cm pltime Ar pltime-val
211Assign an
212.Ar time
213as prefix preferred life time for a prefix to be added.
214Valid value for
215.Ar time
216is same as for
217.Ar vltime-val .
218.It Cm raf_onlink Cm on|off
219Let the prefix to be added to have on-link or off-link nature
220for the assigned interface.
221If
222.Cm on
223is specified, the prefix have on-link nature
224(e.g. the prefix
225belong to the link).
226If
227.Cm off
228is specified, the prefix have off-link nature
229(e.g. the
230prefix does not belong to the link).
231.It Cm raf_auto Cm on|off
232Enable or disable the autonomous address auto configuration
233for the prefix to be added.
234If
235.Cm on
236is specified, autonomous address auto configuration is
237enabled.
238If
239.Cm off
240is specified, it is disabled.
241.It Cm rrf_decrprefd Cm on|off
242Enable or disable the decrementation of the pltime.
243If
244.Cm on
245is specified, decrementation of the pltime is enabled.
246If
247.Cm off
248is specified, decrementation of the pltime is disabled.
249.It Cm rrf_decrvalid Cm on|off
250Enable or disable the decrementation of the vltime.
251If
252.Cm on
253is specified, decrementation of the vltime is enabled.
254If
255.Cm off
256is specified, decrementation of the vltime is disabled.
257.El
258.\"
259.It seqnum Ar seqnum-val { Ar rrenum-cmd } ;
260Specifies contents of sending router renumbering message with some
261specific seqnum.
262Multiple of this statement can be specified if they
263have different
264.Ar seqnum-val
265each other.
266.Ar rrenum-cmd
267has just same syntax with above add|change|setglobal statement.
268.El
269.\"
270.Sh EXAMPLES
271For each configuration file example shown below, we suppose
272every IPv6 subnet has its own prefix beginning with
273fec0:0:0::/48 and with its own subnet number
274(in this case,
275subnet number is 7th and 8th octet value of the prefix).
276.Pp
277If you want to assign prefixes beginning with 3ffe:501:ffff::/48
278to each subnet, then following configuration will be enough,
279if each of your routers supports IPv6 multicast forwarding.
280The subnet number of the existing fec0:0:0::/48 prefix and the
281newly assigned 3ffe:501:ffff::/48 prefix will be same.
282.\"
283.Bd -literal -offset indent
284dest ff05::2;
285
286add match-prefix fec0:0:0:: /48 use-prefix 3ffe:501:ffff:: /48 keeplen 16;
287.Ed
288.Pp
289.\"
290If your routers don't support IPv6 multicast forwarding,
291you'll need to specify each destination at
292.Cm dest
293command.
294.\"
295.Bd -literal -offset indent
296dest fec0:0:0:1:260:8ff:fe24:fb3a fec0:0:0:2:200:eff:fe2e:dfe1 fec0:0:0:3:5254:ff:fedc:5217;
297
298add match-prefix fec0:0:0:: /48 use-prefix 3ffe:501:ffff:: /48 keeplen 16;
299.Ed
300.Pp
301.\"
302If you are going to do renumbering, then following procedure will be natural.
303.Bl -enum -offset indent
304.It
305Assign a new prefix.
306.It
307Set old prefix lifetimes to some appropriate transition
308period.
309In the followng example we use 1 week for valid
310lifetime, and 0 for preferred lifetime.
311Also, enable old prefix lifetime expiration
312(By default, it is static and does not expire).
313.It
314After the transition period, old prefixes should become
315invalid, and may have been deleted.
316To make sure that they are deleted, send new router
317renumbering message, which specifies old prefixes as match
318prefix, and no use prefix.
319.El
320.Pp
321.\"
322The following configuration file will do 1 and 2.
323.\"
324.Bd -literal -offset indent
325dest ff05::2;
326
327seqnum 0 {
328	add match-prefix fec0:0:0:: /48 use-prefix 3ffe:501:fffe:: /48 keeplen 16;
329	};
330
331seqnum 1 {
332	change match-prefix 3ffe:501:ffff:: /48 use-prefix 3ffe:501:ffff:: /48 keeplen 16 vltime d7 pltime 0 rrf_decrvalid on rrf_decrprefd on;
333	};
334.Ed
335.Pp
336.\"
337And the following configuration file will do 3
338(should be
339used for the router renumbering message to be sent 1 week
340afterward).
341.\"
342.Bd -literal -offset indent
343dest ff05::2;
344
345change match-prefix 3ffe:501:ffff:: /48;
346.Ed
347.Pp
348.\"
349In the above example, only
350.Cm add
351and
352.Cm change
353commands are used, and there is no example for
354.Cm setglobal
355command.
356.Cm setglobal
357command is almost same with
358.Cm change
359command except that it deletes all pre-defined IPv6 global address.
360.Sh SEE ALSO
361.Xr rrenumd 8 ,
362.Xr prefix 8
363.Sh HISTORY
364The
365.Nm
366configuration file was first appeared in KAME IPv6 protocol stack kit.
367.\" .Sh BUGS
368.\" (to be written)
369