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