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