usr.sbin/rrenumd/rrenumd.conf.5

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