README.make-secnet-sites

   1 USAGE
   2
   3         make-secnet-sites [-P PREFIX] [IN [OUT]]
   4         make-secnet-sites -u HEADER GRPDIR SITESFILE GROUP
   5
   6         The `-P' option sets the PREFIX string, mentioned below in
   7         `OUTPUT STRUCTURE'; the default is empty.
   8
   9         In the former mode, `make-secnet-sites' reads a single input
  10         file from IN (defaulting to standard input), and writes a Secnet
  11         configuration fragment to OUT (defaulting to standard output).
  12
  13         In the latter, `make-secnet-sites' expects to have been invoked
  14         via GNU Userv.  It verifies that GROUP is listed in the
  15         `USERV_GROUP' environment variable.  It then processes the
  16         HEADER input, which should say `end-defintions' somewhere, to
  17         enable restrictions, and then user input on standard input.  If
  18         the combination of the two is acceptable, it writes a copy of
  19         the user input to the file `GRPDIR/RGROUP' (the `R' is literal)
  20         preceded by a comment logging the time and the value of the
  21         `USERV_USER' environment variable, and writes a file named
  22         SITESFILE consisting of the concatenation of:
  23
  24           * a header comment logging the time and the value of the
  25             `USERV_USER' environment variable, and a reminder that this
  26             is `make-secnet-sites' input;
  27
  28           * the HEADER, with any `include' lines replaced by the files
  29             they include; and
  30
  31           * each of the `GRPDIR/R*' files, in some arbitrary order.
  32
  33         This SITESFILE can later be processed in the former mode to
  34         produce Secnet configuration.
  35
  36
  37 OPTIONS
  38
  39         --output-version NUMBER
  40
  41                 Write backward-compatible sites file output,
  42                 targeting a particular sites format.  Values of
  43                 NUMBER that are understood are:
  44                     1   The original format, pre signing key
  45                         negotiation.
  46                 If NUMBER is higher than make-secnet-sites supports,
  47                 it writes out what it can.
  48
  49         --debug | -D
  50
  51                 Increase amount of debugging output.
  52
  53
  54 INPUT SYNTAX
  55
  56         The input files have a simple line-based syntax.  Blank lines,
  57         and lines beginning with a `#' character, are ignored.  Other
  58         lines consist of a keyword followed by arguments, and separated
  59         by horizontal whitespace.  There is no quoting, and it is not
  60         possible to include horizontal whitespace in an argument.
  61
  62         An input file describes a number of virtual private networks
  63         (`VPNs').  Each VPN consists of a number of locations, and each
  64         location consists of a number of sites, thus forming (together
  65         with the root) a fixed four-level hierarchy.  The root, VPNs,
  66         locations, and sites can each have a number of properties
  67         attached to them: each level in the hierarchy has a different
  68         set of permissable properties.
  69
  70         Most keywords define properties on a `current' item in the
  71         hierarchy.  Some change which item is current, possibly creating
  72         a new item.  A few are special.
  73
  74         First, the navigation keywords.
  75
  76         vpn NAME
  77                 Switch to the VPN called NAME, which is a direct child
  78                 of the root, creating it if necessary.  Subsequent
  79                 properties, up until the next navigation keyword, are
  80                 attached directly to the VPN.
  81
  82                 A VPN item becomes a dictionary named `NAME' within the
  83                 `PREFIXvpn-data' dictionary in the generated output.
  84
  85         location NAME [GROUP]
  86                 Switch to the location called NAME, which is a direct
  87                 child of the most recently mentioned VPN, creating it if
  88                 necessary.  The GROUP name may be omitted (and is anyway
  89                 ignored) if the location already exists.  It is an error
  90                 if there is no current VPN.  Subsequent properties, up
  91                 until the next navigation keyword, are attached directly
  92                 to the location.
  93
  94                 A location item becomes a dictionary named `NAME' within
  95                 its parent VPN's dictionary in the generated output.
  96
  97         site NAME
  98                 Switch to the site called NAME, which is a direct
  99                 child of the most recently mentioned location, creating
 100                 it if necessary.  It is an error if there is no current
 101                 location.  Subsequent properties, up until the next
 102                 navigation keyword, are attached directly to the site.
 103
 104                 A location item becomes a dictionary named `NAME' within
 105                 its parent location's dictionary in the generated
 106                 output.
 107
 108         Now, the special keywords.
 109
 110         include FILE
 111                 Read lines from FILE, as if they'd appeared at this
 112                 point in the input.  If the FILE name is relative, it is
 113                 interpreted relative to the directory containing the
 114                 most recently opened file.  (This seems to be a bug.)
 115
 116                 The `include' keyword is only permitted before the
 117                 `end-defintions' marker in a HEADER file processed using
 118                 the `-u' option.
 119
 120         end-definitions
 121                 After this keyword, the following restrictions apply.
 122
 123                   * The `include' keyword can no longer be used.
 124
 125                   * It is not permitted to define new VPNs and
 126                     locations.
 127
 128                   * It is not permitted to append new items to root,
 129                     VPN, and location properties which are already
 130                     defined.  (Assigning new properties is permitted.)
 131
 132                   * It is not permitted to define new VPN-level
 133                     properties.
 134
 135         Finally, the properties.
 136
 137         Usually, if a property has already been defined on an item, then
 138         it is an error to try to redefine it.  But some properties are
 139         list-like: the values are accumulated into a single list.
 140
 141         Mostly, properties are written to corresponding assignments in
 142         the generated Secnet configuration file, .  The entries below
 143         describe how properties are translated into assignments.
 144
 145         contact EMAIL
 146                 Becomes a `Contact address' comment in the output.
 147                 Acceptable at all levels; required separately at VPN and
 148                 location levels.
 149
 150         dh P G
 151                 Assigns a Diffie--Hellman closure to the `dh' key,
 152                 constructed as `diffie-hellman(P, G)'. Acceptable at all
 153                 levels; required at site level.
 154
 155         hash HASH-NAME
 156                 Assigns the HASH-NAME to the `hash' key.  The HASH-NAME
 157                 must be one of `md5' or `sha1', and the corresponding
 158                 hash closure is used.  Acceptable at all levels;
 159                 required at site level.
 160
 161         key-lifetime INT
 162         setup-timeout INT
 163         setup-retries INT
 164         wait-time INT
 165         renegotiate-time INT
 166                 Assign integers to the like-named key.  Acceptable at
 167                 all levels.
 168
 169         restrict-nets NETWORK NETWORK ...
 170                 This item and its descendents may only define `networks'
 171                 and `peer' properties with addresses within the listed
 172                 NETWORKs, each of which has the form IPADDR/MASK, where
 173                 the IPADDR is an IPv4 address in dotted-quad form, and
 174                 the MASK is either a netmask in dotted-quad form or a
 175                 prefix length.  Becomes a comment n the output.
 176                 Acceptable at all levels.
 177
 178         networks NETWORK NETWORK ...
 179                 Assigns a list of NETWORKs to the `routes' key in a
 180                 netlink application (see below).  See `restrict-nets'
 181                 for the syntax of a NETWORK.  Acceptable only at site
 182                 level; required at site level.
 183
 184         address HOSTNAME PORT
 185                 Assigns HOSTNAME to the `address' key and PORT (an
 186                 integer) to the `port' key.  Acceptable only at site
 187                 level.  May be omitted for mobile sites.
 188
 189         peer IPADDR
 190                 Assigns IPADDR to the `ptp-address' key in a netlink
 191                 application (see below).  IPADDR must be an IPv4 address
 192                 in dotted-quad form.  Acceptable only at site level;
 193                 required at site level.
 194
 195         pubkey HUNOZ E N
 196                 Assigns a public-key closure to the `key' key,
 197                 constructed as `rsa-public(E, N)'.  The argument HUNOZ
 198                 must be an integer, but is otherwise ignored; it's
 199                 conventionally the length of N in bits.  Acceptable only
 200                 at site level; required at site level.
 201
 202         mobile BOOL
 203                 Assigns BOOL to the `mobile' key.  Acceptable only at
 204                 site level, but optional.
 205
 206         Properties which can also appear in public key files.
 207         (named by `peer-keys' key to secnet sites closure.)
 208         These are acceptable to make-secnet-sites only at
 209         site level.  See also `Site long-term keys' in NOTES.
 210
 211         pub ALG DATAB91S
 212                 Defines a public key.  ALG is an algorithm name and
 213                 DATA91S is the public key data, encoded according to
 214                 secnet-base91 (see below).
 215                 Not yet suported in make-secnet-sites.
 216
 217         serial SETIDHEX
 218                 Specifies the key set id (8 hex digits representing
 219                 4 bytes: each pair is the value of the next byte).
 220                 May appear at most once.  If not present, 00000000.
 221                 Not yet suported in make-secnet-sites.
 222
 223         pkg GROUPIDHEX
 224         pkgf GROUPIDHEX
 225                 Specifies the key group id for subsequent keys.
 226                 pkgf indicates a fallback group.
 227                 May be repeated (with different id values).
 228                 If not specified, 00000000.
 229                 Not yet suported in make-secnet-sites.
 230
 231
 232 OUTPUT STRUCTURE
 233
 234         The program produces a Secnet configuration fragment with the
 235         structure described below, suitable for inclusion using the
 236         `include' keyword.
 237
 238                 PREFIXvpn-data {
 239                   VPN {
 240                     # Contact email address: EMAIL
 241                     [ # restrict-nets: NETWORKS ]
 242                     [ VPN-PROPERTIES ]
 243                     LOCATION {
 244                       # Contact email address: EMAIL
 245                       [ # restrict-nets: NETWORKS ]
 246                       [ LOCATION-PROPERTIES ]
 247                       SITE {
 248                         [ # Contact email address: EMAIL ]
 249                         [ # restrict-nets: NETWORKS ]
 250                         name "VPN/LOCATION/NAME";
 251                         SITE-PROPERTIES
 252                         link netlink {
 253                           routes NETWORK ...;
 254                           ptp-address IPADDR;
 255                         };
 256                       };
 257                       [ MORE SITES ... ]
 258                     };
 259                     [ MORE LOCATIONS ... ]
 260                   };
 261                   [ MORE VPNS ... ]
 262                 };
 263
 264                 PREFIXvpn {
 265                   VPN {
 266                     LOCATION PREFIXvpn-data/VPN/LOCATION/SITE, ...;
 267                     [ MORE LOCATIONS ]
 268                     all-sites LOCATION, ...;
 269                   };
 270                 };
 271
 272                 PREFIXall-sites PREFIXvpn/VPN/all-sites, ...;
 273
 274         Note in particular the implicit dependency on a pure closure
 275         named `netlink' used to set the `link' key in each site
 276         definition.  Usually, this will be constructed by a partial
 277         application of the built-in `userv-ipif' or `tun' closures.