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