make-secnet-sites: Introduce a notion of listish types.

[secnet] / README.make-secnet-sites

USAGE

	make-secnet-sites [-P PREFIX] [IN [OUT]]
	make-secnet-sites -u HEADER GRPDIR SITESFILE GROUP

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

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

	In the latter, `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.


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', `sha1', or `sha512', 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; required at site level.

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


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.