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