USAGE

	make-secnet-sites [-P PREFIX] [--conf] [IN [OUTCONF]]
	make-secnet-sites --filter [IN [OUT]]
	make-secnet-sites -u|--userv HEADER GRPDIR SITESFILE GROUP

	The `-P' option sets the PREFIX string, mentioned below in
	`OUTPUT STRUCTURE'; the default is empty.

	In --conf mode, `make-secnet-sites' reads a single input
	file from IN (defaulting to standard input), and writes a Secnet
	configuration fragment to OUTCONF (defaulting to standard output).

	In --filter mode, `make-secnet-sites' reads a single input
	file from IN (defaulting to standard input), and writes a
	version of that sites file to OUT (defaulting to standard
	output).  The output is filtered according to --output-version.

	In --userv mode, `make-secnet-sites' expects to have been invoked
	via GNU Userv.  It verifies that GROUP is listed in the
	`USERV_GROUP' environment variable.  It then processes the
	HEADER input, which should say `end-defintions' somewhere, to
	enable restrictions, and then user input on standard input.  If
	the combination of the two is acceptable, it writes a copy of
	the user input to the file `GRPDIR/RGROUP' (the `R' is literal)
	preceded by a comment logging the time and the value of the
	`USERV_USER' environment variable, and writes a file named
	SITESFILE consisting of the concatenation of:

	  * a header comment logging the time and the value of the
	    `USERV_USER' environment variable, and a reminder that this
	    is `make-secnet-sites' input;

	  * the HEADER, with any `include' lines replaced by the files
	    they include; and

	  * each of the `GRPDIR/R*' files, in some arbitrary order.

	This SITESFILE can later be processed in the former mode to
	produce Secnet configuration.


OPTIONS

	--output-version NUMBER

		Write backward-compatible sites file output,
		targeting a particular sites format.  Values of
		NUMBER that are understood are:
		    1	The original format, pre signing key
			negotiation.
		    2	Signing key algorithm agility and negotiation.
		If NUMBER is higher than make-secnet-sites supports,
		it writes out what it can.

	--pubkeys-install

		Specifies that public keys are to be installed in the
		live pubkeys area (and not hardcoded in secnet conf
		files).  With this option, generated site configs
		refer to keys in PUBKEYS; also, the generated secnet
		configuration enables live peer public update.

	--pubkeys-single

		Specifies that one public key per site is to be
		written directly into the sites.conf output.  If
		--output-version=1, this is the rsa1 key 0000000000.
		Otherwise it is an error if there are multiple public
		keys defined for any site, in the input.
		--pubkeys-single is the default.

	--pubkeys-elide

		In the sites.conf output, just write the peer-keys
		entry referring to keys in PUBKEYS.  But do not write
		public keys anywhere.

	--pubkeys-dir PUBKEYS

		Specifies the live pubkeys area pathname.
		The default is /var/lib/secnet/pubkeys.

		Key files are named
			PUBKEYS/peer.<mangled-peer-name>[~...]
		mangled-peer-name is chosen by make-secnet-sites
			/ => ,

	--debug | -D

		Increase amount of debugging output.


INPUT SYNTAX

	The input files have a simple line-based syntax.  Blank lines,
	and lines beginning with a `#' character, are ignored.  Other
	lines consist of a keyword followed by arguments, and separated
	by horizontal whitespace.  There is no quoting, and it is not
	possible to include horizontal whitespace in an argument.

	An input file describes a number of virtual private networks
	(`VPNs').  Each VPN consists of a number of locations, and each
	location consists of a number of sites, thus forming (together
	with the root) a fixed four-level hierarchy.  The root, VPNs,
	locations, and sites can each have a number of properties
	attached to them: each level in the hierarchy has a different
	set of permissable properties.

	Most keywords define properties on a `current' item in the
	hierarchy.  Some change which item is current, possibly creating
	a new item.  A few are special.

	First, the navigation keywords.

	vpn NAME
		Switch to the VPN called NAME, which is a direct child
		of the root, creating it if necessary.  Subsequent
		properties, up until the next navigation keyword, are
		attached directly to the VPN.

		A VPN item becomes a dictionary named `NAME' within the
		`PREFIXvpn-data' dictionary in the generated output.

	location NAME [GROUP]
		Switch to the location called NAME, which is a direct
		child of the most recently mentioned VPN, creating it if
		necessary.  The GROUP name may be omitted (and is anyway
		ignored) if the location already exists.  It is an error
		if there is no current VPN.  Subsequent properties, up
		until the next navigation keyword, are attached directly
		to the location.

		A location item becomes a dictionary named `NAME' within
		its parent VPN's dictionary in the generated output.

	site NAME
		Switch to the site called NAME, which is a direct
		child of the most recently mentioned location, creating
		it if necessary.  It is an error if there is no current
		location.  Subsequent properties, up until the next
		navigation keyword, are attached directly to the site.

		A location item becomes a dictionary named `NAME' within
		its parent location's dictionary in the generated
		output.

	Now, the special keywords.

	include FILE
		Read lines from FILE, as if they'd appeared at this
		point in the input.  If the FILE name is relative, it is
		interpreted relative to the directory containing the
		most recently opened file.  (This seems to be a bug.)

		The `include' keyword is only permitted before the
		`end-defintions' marker in a HEADER file processed using
		the `-u' option.

	end-definitions
		After this keyword, the following restrictions apply.

		  * The `include' keyword can no longer be used.

		  * It is not permitted to define new VPNs and
		    locations.

		  * It is not permitted to append new items to root,
		    VPN, and location properties which are already
		    defined.  (Assigning new properties is permitted.)

		  * It is not permitted to define new VPN-level
		    properties.

	Finally, the properties.

	Usually, if a property has already been defined on an item, then
	it is an error to try to redefine it.  But some properties are
	list-like: the values are accumulated into a single list.

	Mostly, properties are written to corresponding assignments in
	the generated Secnet configuration file, .  The entries below
	describe how properties are translated into assignments.

	contact EMAIL
		Becomes a `Contact address' comment in the output.
		Acceptable at all levels; required separately at VPN and
		location levels.

	dh P G
		Assigns a Diffie--Hellman closure to the `dh' key,
		constructed as `diffie-hellman(P, G)'. Acceptable at all
		levels; required at site level.

	hash HASH-NAME
		Assigns the HASH-NAME to the `hash' key.  The HASH-NAME
		must be one of `md5' or `sha1', and the corresponding
		hash closure is used.  Acceptable at all levels;
		required at site level.

	key-lifetime INT
	setup-timeout INT
	setup-retries INT
	wait-time INT
	renegotiate-time INT
		Assign integers to the like-named key.  Acceptable at
		all levels.
		
	restrict-nets NETWORK NETWORK ...
		This item and its descendents may only define `networks'
		and `peer' properties with addresses within the listed
		NETWORKs, each of which has the form IPADDR/MASK, where
		the IPADDR is an IPv4 address in dotted-quad form, and
		the MASK is either a netmask in dotted-quad form or a
		prefix length.  Becomes a comment n the output.
		Acceptable at all levels.

	networks NETWORK NETWORK ...
		Assigns a list of NETWORKs to the `routes' key in a
		netlink application (see below).  See `restrict-nets'
		for the syntax of a NETWORK.  Acceptable only at site
		level; required at site level.

	address HOSTNAME PORT
		Assigns HOSTNAME to the `address' key and PORT (an
		integer) to the `port' key.  Acceptable only at site
		level.  May be omitted for mobile sites.

	peer IPADDR
		Assigns IPADDR to the `ptp-address' key in a netlink
		application (see below).  IPADDR must be an IPv4 address
		in dotted-quad form.  Acceptable only at site level;
		required at site level.

	pubkey HUNOZ E N
		Assigns a public-key closure to the `key' key,
		constructed as `rsa-public(E, N)'.  The argument HUNOZ
		must be an integer, but is otherwise ignored; it's
		conventionally the length of N in bits.
		Acceptable only at site level.  See `pub'.

	mobile BOOL
		Assigns BOOL to the `mobile' key.  Acceptable only at
		site level, but optional.

	Properties which can also appear in public key files.
	(named by `peer-keys' key to secnet sites closure.)
	These are acceptable to make-secnet-sites only at
	site level.  See also `Site long-term keys' in NOTES.

	pub ALG DATAB91S
		Defines a public key.  ALG is an algorithm name and
		DATA91S is the public key data, encoded according to
		secnet-base91 (see below).
		Gives make-public("ALG","DATAB91S") in sites.conf;
		at least one `pub' or `pubkey' must be specified.

	serial SETIDHEX
		Specifies the key set id (8 hex digits representing
		4 bytes: each pair is the value of the next byte).
		May appear at most once.  If not present, 00000000.

	pkg GROUPIDHEX
	pkgf GROUPIDHEX
		Specifies the key group id for subsequent keys.
		pkgf indicates a fallback group.
		May be repeated (with different id values).
		If not specified, 00000000.


OUTPUT STRUCTURE

	The program produces a Secnet configuration fragment with the
	structure described below, suitable for inclusion using the
	`include' keyword.

		PREFIXvpn-data {
		  VPN {
		    # Contact email address: EMAIL
		    [ # restrict-nets: NETWORKS ]
		    [ VPN-PROPERTIES ]
		    LOCATION {
		      # Contact email address: EMAIL
		      [ # restrict-nets: NETWORKS ]
		      [ LOCATION-PROPERTIES ]
		      SITE {
			[ # Contact email address: EMAIL ]
			[ # restrict-nets: NETWORKS ]
			name "VPN/LOCATION/NAME";
			SITE-PROPERTIES
			link netlink {
			  routes NETWORK ...;
			  ptp-address IPADDR;
			};
		      };
		      [ MORE SITES ... ]
		    };
		    [ MORE LOCATIONS ... ]
		  };
		  [ MORE VPNS ... ]
		};

		PREFIXvpn {
		  VPN {
		    LOCATION PREFIXvpn-data/VPN/LOCATION/SITE, ...;
		    [ MORE LOCATIONS ]
		    all-sites LOCATION, ...;
		  };
		};

		PREFIXall-sites PREFIXvpn/VPN/all-sites, ...;

	Note in particular the implicit dependency on a pure closure
	named `netlink' used to set the `link' key in each site
	definition.  Usually, this will be constructed by a partial
	application of the built-in `userv-ipif' or `tun' closures.




-- 
This file is part of secnet.
See LICENCE and this file CREDITS for full list of copyright holders.
SPDX-License-Identifier: GPL-3.0-or-later
There is NO WARRANTY.