[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.

	If a property has already been defined on an item, then it is an
	error to try to redefine it.

	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; 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.
Commit	Line	Data
6b27510e MW	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	INPUT SYNTAX
	38
	39	The input files have a simple line-based syntax. Blank lines,
	40	and lines beginning with a `#' character, are ignored. Other
	41	lines consist of a keyword followed by arguments, and separated
	42	by horizontal whitespace. There is no quoting, and it is not
	43	possible to include horizontal whitespace in an argument.
	44
	45	An input file describes a number of virtual private networks
	46	(`VPNs'). Each VPN consists of a number of locations, and each
	47	location consists of a number of sites, thus forming (together
	48	with the root) a fixed four-level hierarchy. The root, VPNs,
	49	locations, and sites can each have a number of properties
	50	attached to them: each level in the hierarchy has a different
	51	set of permissable properties.
	52
	53	Most keywords define properties on a `current' item in the
	54	hierarchy. Some change which item is current, possibly creating
	55	a new item. A few are special.
	56
	57	First, the navigation keywords.
	58
	59	vpn NAME
	60	Switch to the VPN called NAME, which is a direct child
	61	of the root, creating it if necessary. Subsequent
	62	properties, up until the next navigation keyword, are
	63	attached directly to the VPN.
	64
65	A VPN item becomes a dictionary named `NAME' within the
66	`PREFIXvpn-data' dictionary in the generated output.
67
68	location NAME [GROUP]
69	Switch to the location called NAME, which is a direct
70	child of the most recently mentioned VPN, creating it if
71	necessary. The GROUP name may be omitted (and is anyway
72	ignored) if the location already exists. It is an error
73	if there is no current VPN. Subsequent properties, up
74	until the next navigation keyword, are attached directly
75	to the location.
76
77	A location item becomes a dictionary named `NAME' within
78	its parent VPN's dictionary in the generated output.
79
80	site NAME
81	Switch to the site called NAME, which is a direct
82	child of the most recently mentioned location, creating
83	it if necessary. It is an error if there is no current
84	location. Subsequent properties, up until the next
85	navigation keyword, are attached directly to the site.
86
87	A location item becomes a dictionary named `NAME' within
88	its parent location's dictionary in the generated
89	output.
90
91	Now, the special keywords.
92
93	include FILE
94	Read lines from FILE, as if they'd appeared at this
95	point in the input. If the FILE name is relative, it is
96	interpreted relative to the directory containing the
97	most recently opened file. (This seems to be a bug.)
98
99	The `include' keyword is only permitted before the
100	`end-defintions' marker in a HEADER file processed using
101	the `-u' option.
102
103	end-definitions
104	After this keyword, the following restrictions apply.
105
106	* The `include' keyword can no longer be used.
107
108	* It is not permitted to define new VPNs and
109	locations.
110
111	* It is not permitted to append new items to root,
112	VPN, and location properties which are already
113	defined. (Assigning new properties is permitted.)
114
8644ac83 MW	115	* It is not permitted to define new VPN-level
	116	properties.
	117
6b27510e MW	118	Finally, the properties.
	119
	120	If a property has already been defined on an item, then it is an
	121	error to try to redefine it.
	122
	123	Mostly, properties are written to corresponding assignments in
	124	the generated Secnet configuration file, . The entries below
	125	describe how properties are translated into assignments.
	126
	127	contact EMAIL
	128	Becomes a `Contact address' comment in the output.
	129	Acceptable at all levels; required separately at VPN and
	130	location levels.
	131
	132	dh P G
	133	Assigns a Diffie--Hellman closure to the `dh' key,
	134	constructed as `diffie-hellman(P, G)'. Acceptable at all
	135	levels; required at site level.
	136
	137	hash HASH-NAME
	138	Assigns the HASH-NAME to the `hash' key. The HASH-NAME
	139	must be one of `md5' or `sha1', and the corresponding
	140	hash closure is used. Acceptable at all levels;
	141	required at site level.
	142
	143	key-lifetime INT
	144	setup-timeout INT
	145	setup-retries INT
	146	wait-time INT
	147	renegotiate-time INT
	148	Assign integers to the like-named key. Acceptable at
	149	all levels.
	150
	151	restrict-nets NETWORK NETWORK ...
	152	This item and its descendents may only define `networks'
	153	and `peer' properties with addresses within the listed
	154	NETWORKs, each of which has the form IPADDR/MASK, where
	155	the IPADDR is an IPv4 address in dotted-quad form, and
	156	the MASK is either a netmask in dotted-quad form or a
	157	prefix length. Becomes a comment n the output.
	158	Acceptable at all levels.
	159
	160	networks NETWORK NETWORK ...
	161	Assigns a list of NETWORKs to the `routes' key in a
	162	netlink application (see below). See `restrict-nets'
	163	for the syntax of a NETWORK. Acceptable only at site
	164	level; required at site level.
	165
	166	address HOSTNAME PORT
	167	Assigns HOSTNAME to the `address' key and PORT (an
	168	integer) to the `port' key. Acceptable only at site
	169	level. May be omitted for mobile sites.
	170
	171	peer IPADDR
	172	Assigns IPADDR to the `ptp-address' key in a netlink
	173	application (see below). IPADDR must be an IPv4 address
	174	in dotted-quad form. Acceptable only at site level;
	175	required at site level.
	176
	177	pubkey HUNOZ E N
	178	Assigns a public-key closure to the `key' key,
	179	constructed as `rsa-public(E, N)'. The argument HUNOZ
	180	must be an integer, but is otherwise ignored; it's
	181	conventionally the length of N in bits. Acceptable only
182	at site level; required at site level.
183
184	mobile BOOL
185	Assigns BOOL to the `mobile' key. Acceptable only at
186	site level, but optional.
187
188
189	OUTPUT STRUCTURE
190
191	The program produces a Secnet configuration fragment with the
192	structure described below, suitable for inclusion using the
193	`include' keyword.
194
195	PREFIXvpn-data {
196	VPN {
197	# Contact email address: EMAIL
198	[ # restrict-nets: NETWORKS ]
199	[ VPN-PROPERTIES ]
200	LOCATION {
201	# Contact email address: EMAIL
202	[ # restrict-nets: NETWORKS ]
203	[ LOCATION-PROPERTIES ]
204	SITE {
205	[ # Contact email address: EMAIL ]
206	[ # restrict-nets: NETWORKS ]
207	name "VPN/LOCATION/NAME";
208	SITE-PROPERTIES
209	link netlink {
210	routes NETWORK ...;
211	ptp-address IPADDR;
212	};
213	};
214	[ MORE SITES ... ]
215	};
216	[ MORE LOCATIONS ... ]
217	};
218	[ MORE VPNS ... ]
219	};
220
221	PREFIXvpn {
222	VPN {
223	LOCATION PREFIXvpn-data/VPN/LOCATION/SITE, ...;
224	[ MORE LOCATIONS ]
225	all-sites LOCATION, ...;
226	};
227	};
228
229	PREFIXall-sites PREFIXvpn/VPN/all-sites, ...;
230
231	Note in particular the implicit dependency on a pure closure
232	named `netlink' used to set the `link' key in each site
233	definition. Usually, this will be constructed by a partial
234	application of the built-in `userv-ipif' or `tun' closures.