usr.sbin/rrenumd/rrenumd.conf.5

   1 .\"     $KAME$
   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
  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 Parentheses (`(' 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. It is disabled by default.
  88 .\"
  89 .It Ic dest Ar dest-list Op Ar retrycmd ;
  90 Specifies destinations to which router renumbering messages should be
  91 sent.
  92 .Ar dest-list
  93 can be any combination of single or multiple numerical IPv6 addrs,
  94 or Full Qualified Domain Names.
  95 .Ar retrycmd
  96 has following syntax.
  97 .\"
  98 .Bl -tag -width Ds
  99 .It Ic retry Ar retry-num
 100 .Ar retry-num
 101 specifies how many router renumbering messages are sent repeatedly.
 102 .El
 103 .It Op Ic add|change|setglobal
 104 .Cm match-prefix Ar match-prefix-val
 105 .Op /match-prefix-len
 106 .Op Cm maxlen Ar maxlen-val
 107 .Op Cm minlen Ar minlen-val
 108 .Op Cm use-prefix Ar use-prefix-val
 109 .Op /use-prefix-len
 110 .Op Cm keeplen Ar keeplen-val
 111 .Op Ar use-prefix-values ;
 112 .Pp
 113 Specifies contents of sending router renumbering message with seqnum 0.
 114 If
 115 .Cm add|change|setglobal
 116 is not specified, then
 117 .Cm add
 118 is assumed.
 119 .Ar use-prefix-values
 120 has following syntax.
 121 .Pp
 122 {
 123 .Op Cm vltime Ar vltime-val
 124 .Op Cm pltime Ar pltime-val
 125 .Op Cm raf_onlink Cm on|off
 126 .Op Cm raf_auto Cm on|off
 127 .Op Cm rrf_decrprefd Cm on|off
 128 .Op Cm rrf_decrvalid Cm on|off
 129 }
 130 .Pp
 131 Each value has following meaning.
 132 .Pp
 133 .Bl -tag -width Ds -compact
 134 .It Cm match-prefix Ar match-prefix-val Op /match-prefix-len
 135 Specify
 136 .Ar match-prefix-val
 137 that is used for matching with preassigned prefixes to which
 138 .Cm add|change|setglobal
 139 command should be applied.
 140 .Ar /match-prefix-len
 141 Specify the starting part of
 142 .Ar match-prefix-val
 143 to be used for matching with preassigned prefixes, as decimal bit number.
 144 .It Cm maxlen Ar maxlen-val
 145 Specify the maximum length of prefixes which is allowed to be
 146 matched to
 147 .Ar match-prefix-val ,
 148 as decimal bit number.
 149 .It Cm minlen Ar minlen-val
 150 Specify the minimum length of prefixes which is allowed to be matched to
 151 .Ar match-prefix-val ,
 152 as decimal bit number.
 153 .It Cm use-prefix Ar use-prefix-val Op /usr-prefix-len
 154 Specify
 155 .Ar use-prefix-val
 156 that is used for prefixes to be added on
 157 .Cm add|change|setglobal
 158 command.
 159 .Ar /use-prefix-len
 160 Specify the starting part of
 161 .Ar use-prefix-val
 162 copied to the starting part of prefixes to be added on
 163 .Cm add|change|setglobal
 164 command, as decimal bit number.
 165 .It Cm keeplen Ar keeplen-val
 166 Specify the midium part of
 167 .Ar use-prefix-val
 168 just next to the starting part specified by
 169 .Ar use-prefix-len
 170 , as decimal bit number.
 171 Contiguous bits part in the same bit position of an existent prefix
 172 matched with
 173 .Ar match-prefix-val
 174 is copied to the same bit position of prefixes to be added.
 175 .It Cm vltime Ar vmtime-val
 176 Assign an
 177 .Ar time
 178 as prefix valid life time for a prefix to be added.
 179 Valid value for
 180 .Ar time
 181 is decimal seconds number or special format as "d00h00m00s00",
 182 where 00 can take any decimal number, and "d" means days, "h" means hours,
 183 "m" means minutes, "s" means seconds. And alternatively, special keyword
 184 "infinity" can be also be specified.
 185 .It Cm pltime Ar pltime-val
 186 Assign an
 187 .Ar time
 188 as prefix preferred life time for a prefix to be added.
 189 Valid value for
 190 .Ar time
 191 is same as for
 192 .Ar vltime-val .
 193 .It Cm raf_onlink Cm on|off
 194 Let the prefix to be added to have on-link or off-link nature
 195 for the assigned interface. If
 196 .Cm on
 197 is specified, the prefix have on-link nature. (e.g. the prefix
 198 belong to the link) If
 199 .Cm off
 200 is specified, the prefix have off-link nature. (e.g. the
 201 prefix does not belong to the link)
 202 .It Cm raf_auto Cm on|off
 203 Enable or disable the autonomous address auto configuration
 204 for the prefix to be added. If
 205 .Cm on
 206 is specified, autonomous address auto configuration is
 207 enabled. If
 208 .Cm off
 209 is specified, it is disabled.
 210 .It Cm rrf_decrprefd Cm on|off
 211 Enable or disable the decrementation of the pltime. If
 212 .Cm on
 213 is specified, decrementation of the pltime is enabled. If
 214 .Cm off
 215 is specified, decrementation of the pltime is disabled.
 216 .It Cm rrf_decrvalid Cm on|off
 217 Enable or disable the decrementation of the vltime. If
 218 .Cm on
 219 is specified, decrementation of the vltime is enabled. If
 220 .Cm off
 221 is specified, decrementation of the vltime is disabled.
 222 .El
 223 .\"
 224 .It seqnum Ar seqnum-val { Ar rrenum-cmd } ;
 225 Specifies contents of sending router renumbering message with some
 226 specific seqnum. Multiple of this statement can be specified if they
 227 have different
 228 .Ar seqnum-val
 229 each other.
 230 .Ar rrenum-cmd
 231 has just same syntax with above add|change|setglobal statement.
 232 .El
 233 .\"
 234 .Sh EXAMPLES
 235 For each configuration file example shown below, we suppose
 236 every IPv6 subnet has its own prefix beginning with
 237 fec0:0:0::/48 and with its own subnet number. (in this case,
 238 subnet number is 7th and 8th octet value of the prefix)
 239 .Pp
 240 If you want to assigne prefixes beginning with fec0:1:1::/48
 241 to each subnet, then following configuration will be enough,
 242 if each of your routers supports IPv6 multicast forwarding.
 243 The subnet number of the existing fec0:0:0::/48 prefix and the
 244 newly assigned fec0:1:1::/48 prefix will be same.
 245 .\"
 246 .Bd -literal -offset indent
 247 dest ff05::2;
 248
 249 add match-prefix fec0:0:0:: /48 use-prefix fec0:1:1:: /48 keeplen 16;
 250 .Ed
 251 .Pp
 252 .\"
 253 If your routers don't support IPv6 multicast forwarding,
 254 you'll need to specify each destination at
 255 .Cm dest
 256 command.
 257 .\"
 258 .Bd -literal -offset indent
 259 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;
 260
 261 add match-prefix fec0:0:0:: /48 use-prefix fec0:1:1:: /48 keeplen 16;
 262 .Ed
 263 .Pp
 264 .\"
 265 If you are going to do renumbering, then following procedure will be natural.
 266 .Bl -enum -offset indent
 267 .It
 268 Assigne new prefix.
 269 .It
 270 Set old prefix lifetimes to some appropriate transition
 271 period. In the followng example we use 1 week for valid
 272 lifetime, and 0 for preferred lifetime.
 273 Also, enable old prefix lifetime expiration.
 274 (By default, it is static and does not expire)
 275 .It
 276 After the transition period, old prefixes should become
 277 invalid, and may have been deleted.
 278 To make sure that they are deleted, send new router
 279 renumbering message, which specifies old prefixes as match
 280 prefix, and no use prefix.
 281 .El
 282 .Pp
 283 .\"
 284 The following configuration file will do 1 and 2.
 285 .\"
 286 .Bd -literal -offset indent
 287 dest ff05::2;
 288
 289 seqnum 0 {
 290         add match-prefix fec0:0:0:: /48 use-prefix fec0:2:2:: /48 keeplen 16;
 291         };
 292
 293 seqnum 1 {
 294         change match-prefix fec0:1:1:: /48 use-prefix fec0:1:1:: /48 keeplen 16 vltime d7 pltime 0 rrf_decrvalid on rrf_decrprefd on;
 295         };
 296 .Ed
 297 .Pp
 298 .\"
 299 And the following configuration file will do 3. (should be
 300 used for the router renumbering message to be sent 1 week
 301 afterward)
 302 .\"
 303 .Bd -literal -offset indent
 304 dest ff05::2;
 305
 306 change match-prefix fec0:1:1:: /48;
 307 .Ed
 308 .Pp
 309 .\"
 310 In the above example, only
 311 .Cm add
 312 and
 313 .Cm change
 314 commands are used, and there is no example for
 315 .Cm setglobal
 316 command.
 317 .Cm setglobal
 318 command is almost same with
 319 .Cm change
 320 command except that it deletes all pre-defined IPv6 global address.
 321 .Sh SEE ALSO
 322 .Xr rrenumd 8
 323 .Xr prefix 8
 324 .Sh HISTORY
 325 The
 326 .Nm
 327 configuration file was first appeared in KAME IPv6 protocol stack kit.
 328 .\" .Sh BUGS
 329 .\" (to be written)