changelog: work on documentation of changes since ea31544cc33a

[secnet.git] / README.make-secnet-sites

diff --git a/README.make-secnet-sites b/README.make-secnet-sites
index 579b9a56a74e33d72dd951ffc146fdb1dc7ae972..cbf304e80eb3feb129ce72df6c59eefe6c1ef1c6 100644 (file)
--- 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,14 +236,15 @@ 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.
 
@@ -194,13 +252,13 @@ INPUT SYNTAX
                Defines a public key.  ALG is an algorithm name and
                DATA91S is the public key data, encoded according to
                secnet-base91 (see below).
-               Not yet suported in make-secnet-sites.
+               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.
-               Not yet suported in make-secnet-sites.
 
        pkg GROUPIDHEX
        pkgf GROUPIDHEX
@@ -208,7 +266,6 @@ INPUT SYNTAX
                pkgf indicates a fallback group.
                May be repeated (with different id values).
                If not specified, 00000000.
-               Not yet suported in make-secnet-sites.
 
 
 OUTPUT STRUCTURE