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