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