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