README.make-secnet-sites

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