X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=README.make-secnet-sites;h=cbf304e80eb3feb129ce72df6c59eefe6c1ef1c6;hb=49b56eafcd147185c28848a7c04e31a32c49a82e;hp=ea767e912f1616d05de31b8872280c1c18cf0d81;hpb=16bce837ffe3527d4e8ed306f4436a86891d6e60;p=secnet.git

diff --git a/README.make-secnet-sites b/README.make-secnet-sites
index ea767e9..cbf304e 100644
--- a/README.make-secnet-sites
+++ b/README.make-secnet-sites
@@ -1,16 +1,22 @@
 USAGE
 
-	make-secnet-sites [-P PREFIX] [IN [OUT]]
-	make-secnet-sites -u HEADER GRPDIR SITESFILE GROUP
+	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 the former mode, `make-secnet-sites' reads a single input
+	In --conf 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).
+	configuration fragment to OUTCONF (defaulting to standard output).
 
-	In the latter, `make-secnet-sites' expects to have been invoked
+	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
@@ -34,6 +40,57 @@ USAGE
 	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,
@@ -179,13 +236,37 @@ INPUT SYNTAX
 		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.
+		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