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