xref: /freebsd/usr.sbin/rrenumd/rrenumd.conf.5 (revision 81ad6265) 
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
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.Ek
127.Pp
128Specifies contents of sending router renumbering message with seqnum 0.
129If
130.Cm add|change|setglobal
131is not specified, then
132.Cm add
133is assumed.
134.Ar use-prefix-values
135has following syntax.
136.Pp
137{
138.Op Cm vltime Ar vltime-val
139.Bk -words
140.Op Cm pltime Ar pltime-val
141.Ek
142.Bk -words
143.Op Cm raf_onlink Cm on|off
144.Ek
145.Bk -words
146.Op Cm raf_auto Cm on|off
147.Ek
148.Bk -words
149.Op Cm rrf_decrprefd Cm on|off
150.Ek
151.Bk -words
152.Op Cm rrf_decrvalid Cm on|off
153.Ek
154}
155.Pp
156Each value has following meaning.
157.Pp
158.Bl -tag -width Ds -compact
159.It Cm match-prefix Ar match-prefix-val Op /match-prefix-len
160Specify
161.Ar match-prefix-val
162that is used for matching with preassigned prefixes to which
163.Cm add|change|setglobal
164command should be applied.
165.Ar /match-prefix-len
166Specify the starting part of
167.Ar match-prefix-val
168to be used for matching with preassigned prefixes, as decimal bit number.
169.It Cm maxlen Ar maxlen-val
170Specify the maximum length of prefixes which is allowed to be
171matched to
172.Ar match-prefix-val ,
173as decimal bit number.
174.It Cm minlen Ar minlen-val
175Specify the minimum length of prefixes which is allowed to be matched to
176.Ar match-prefix-val ,
177as decimal bit number.
178.It Cm use-prefix Ar use-prefix-val Op /usr-prefix-len
179Specify
180.Ar use-prefix-val
181that is used for prefixes to be added on
182.Cm add|change|setglobal
183command.
184.Ar /use-prefix-len
185Specify the starting part of
186.Ar use-prefix-val
187copied to the starting part of prefixes to be added on
188.Cm add|change|setglobal
189command, as decimal bit number.
190.It Cm keeplen Ar keeplen-val
191Specify the medium part of
192.Ar use-prefix-val
193just next to the starting part specified by
194.Ar use-prefix-len ,
195as decimal bit number.
196Contiguous bits part in the same bit position of an existent prefix
197matched with
198.Ar match-prefix-val
199is copied to the same bit position of prefixes to be added.
200.It Cm vltime Ar vmtime-val
201Assign an
202.Ar time
203as prefix valid life time for a prefix to be added.
204Valid value for
205.Ar time
206is decimal seconds number or special format as "d00h00m00s00",
207where 00 can take any decimal number, and "d" means days, "h" means hours,
208"m" means minutes, "s" means seconds.
209And alternatively, special keyword
210"infinity" can be also be specified.
211.It Cm pltime Ar pltime-val
212Assign an
213.Ar time
214as prefix preferred life time for a prefix to be added.
215Valid value for
216.Ar time
217is same as for
218.Ar vltime-val .
219.It Cm raf_onlink Cm on|off
220Let the prefix to be added to have on-link or off-link nature
221for the assigned interface.
222If
223.Cm on
224is specified, the prefix have on-link nature
225(e.g.\& the prefix
226belong to the link).
227If
228.Cm off
229is specified, the prefix have off-link nature
230(e.g.\& the
231prefix does not belong to the link).
232.It Cm raf_auto Cm on|off
233Enable or disable the autonomous address auto configuration
234for the prefix to be added.
235If
236.Cm on
237is specified, autonomous address auto configuration is
238enabled.
239If
240.Cm off
241is specified, it is disabled.
242.It Cm rrf_decrprefd Cm on|off
243Enable or disable the decrementation of the pltime.
244If
245.Cm on
246is specified, decrementation of the pltime is enabled.
247If
248.Cm off
249is specified, decrementation of the pltime is disabled.
250.It Cm rrf_decrvalid Cm on|off
251Enable or disable the decrementation of the vltime.
252If
253.Cm on
254is specified, decrementation of the vltime is enabled.
255If
256.Cm off
257is specified, decrementation of the vltime is disabled.
258.El
259.\"
260.It seqnum Ar seqnum-val { Ar rrenum-cmd } ;
261Specifies contents of sending router renumbering message with some
262specific seqnum.
263Multiple of this statement can be specified if they
264have different
265.Ar seqnum-val
266each other.
267.Ar rrenum-cmd
268has just same syntax with above add|change|setglobal statement.
269.El
270.\"
271.Sh EXAMPLES
272For each configuration file example shown below, we suppose
273every IPv6 subnet has its own prefix beginning with
274fec0:0:0::/48 and with its own subnet number
275(in this case,
276subnet number is 7th and 8th octet value of the prefix).
277.Pp
278If you want to assign prefixes beginning with 3ffe:501:ffff::/48
279to each subnet, then following configuration will be enough,
280if each of your routers supports IPv6 multicast forwarding.
281The subnet number of the existing fec0:0:0::/48 prefix and the
282newly assigned 3ffe:501:ffff::/48 prefix will be same.
283.\"
284.Bd -literal -offset indent
285dest ff05::2;
286
287add match-prefix fec0:0:0:: /48 use-prefix 3ffe:501:ffff:: /48 keeplen 16;
288.Ed
289.Pp
290.\"
291If your routers do not support IPv6 multicast forwarding,
292you will need to specify each destination at
293.Cm dest
294command.
295.\"
296.Bd -literal -offset indent
297dest fec0:0:0:1:260:8ff:fe24:fb3a fec0:0:0:2:200:eff:fe2e:dfe1 fec0:0:0:3:5254:ff:fedc:5217;
298
299add match-prefix fec0:0:0:: /48 use-prefix 3ffe:501:ffff:: /48 keeplen 16;
300.Ed
301.Pp
302.\"
303If you are going to do renumbering, then following procedure will be natural.
304.Bl -enum -offset indent
305.It
306Assign a new prefix.
307.It
308Set old prefix lifetimes to some appropriate transition
309period.
310In the following example we use 1 week for valid
311lifetime, and 0 for preferred lifetime.
312Also, enable old prefix lifetime expiration
313(By default, it is static and does not expire).
314.It
315After the transition period, old prefixes should become
316invalid, and may have been deleted.
317To make sure that they are deleted, send new router
318renumbering message, which specifies old prefixes as match
319prefix, and no use prefix.
320.El
321.Pp
322.\"
323The following configuration file will do 1 and 2.
324.\"
325.Bd -literal -offset indent
326dest ff05::2;
327
328seqnum 0 {
329	add match-prefix fec0:0:0:: /48 use-prefix 3ffe:501:fffe:: /48 keeplen 16;
330	};
331
332seqnum 1 {
333	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;
334	};
335.Ed
336.Pp
337.\"
338And the following configuration file will do 3
339(should be
340used for the router renumbering message to be sent 1 week
341afterward).
342.\"
343.Bd -literal -offset indent
344dest ff05::2;
345
346change match-prefix 3ffe:501:ffff:: /48;
347.Ed
348.Pp
349.\"
350In the above example, only
351.Cm add
352and
353.Cm change
354commands are used, and there is no example for
355.Cm setglobal
356command.
357.Cm setglobal
358command is almost same with
359.Cm change
360command except that it deletes all pre-defined IPv6 global address.
361.Sh SEE ALSO
362.Xr prefix 8 ,
363.Xr rrenumd 8
364.Sh HISTORY
365The
366.Nm
367configuration file was first appeared in KAME IPv6 protocol stack kit.
368.\" .Sh BUGS
369.\" (to be written)
370