| < export-control | Russ Allbery > Software > control-archive | process-control > |
(Generate config and doc files from hierarchy configs)
generate-files
generate-files reads hierarchy configuration fragments and PGP keys and generates control.ctl, PGPKEYS, and README.html (which is an HTML version of the PGPKEYS file and contains the same information) in the current directory. It is meant to be run from the root directory of a configuration tree for Netnews control messages.
The main source of input to this script is a directory of configuration fragments in config/. The format of those fragments is intended to be compatible with the new configuration syntax supported by INN (but not generally used within INN, at least yet). If you have an INN source tree available, see doc/config-* in the INN source for more details.
Briefly, the format consists of key/value pairs in one of the following two formats:
<key>: <value>
<key>: [ <value> <value> ... ]
In other words, keys take a single value or multiple values enclosed in
square brackets and separated by whitespace. The second form is called a
vector. Values that contain colons, whitespace, or double quotes must be
enclosed in double quotes. Values may not contain double quotes and
escaping isn't implemented inside values. Boolean values can be set with
yes, on, or true and no, off, or false.
The following keys are recognized:
The abbreviated hierarchy name, used for the heading of the corresponding
control.ctl entry. This should conventionally be the group prefix of
the hierarchy without a leading period and in all caps. If this
configuration file governs multiple hierarchies, each hierarchy should be
listed separated by & ; for example, FOO & BAR & BAZ for a
configuration file for foo.*, bar.*, and baz.*.
The type of the hierarchy. This should be one of public, private,
local, defunct, historic, or reserved. Public and historic
hierarchies will generate control.ctl entries that honor the control
messages. Reserved hierarchies will generate entries that drop all
control messages for that hierarchy. All others will generate
control.ctl entries with an action of mail for newgroup messages and
an action of doit for rmgroup messages.
A short English description of the hierarchy.
The control.ctl pattern for the affected hierarchies. This is one or
more wildmat patterns separated by |.
A vector of wildmat patterns matching control message senders. Even if there is only one control message sender for this hierarchy, it must be given in the form of a vector (enclosed in square brackets). This by default sets the sender pattern for newgroups, rmgroups, and checkgroups, but can be overridden by the following keys. It is also used for the control message sender in the PGPKEYS file.
Overrides sender and specifies the wildmat patterns matching newgroup senders. The value must be a vector.
Overrides sender and specifies the wildmat patterns matching rmgroup senders. The value must be a vector.
Overrides sender and specifies the wildmat patterns matching checkgroups senders. The value must be a vector.
A vector of contact addresses. These will be included in Contact comments in the control.ctl entry.
A URL for general information about the hierarchy. Since URLs contain colons, this must be in double-quotes. This will be included in a URL comment in the control.ctl entry.
A boolean value indicating whether this hierarchy uses PGP. The default
is no.
By default, if pgp is set to yes, a rule is added to drop all
non-signed control messages for this hierarchy. Set this key to no to
disable that behavior.
The user ID of the PGP key. The control message verification process for Netnews control messages matches the key ID (only the e-mail address portion in newer software, but the entire key ID in older software). In retrospect, this was a poor design choice and hex key IDs should have been used instead, but there's a ton of software out there written with that assumption. The value of this key should be that key ID, and must not contain whitespace. Conventionally, either the e-mail address of the control message sender or the name of the administrative newsgroup for the hierarchy is used as the key ID.
A URL from which one can retrieve the PGP key for the hierarchy from some authoritative source (in other words, not a keyserver). This value is put into a Key URL comment in control.ctl and into the PGPKEYS file. Since URLs contain colons, this value must be enclosed in double quotes.
The fingerprint of the PGP key. If this value is set, generate-files will verify during processing that the PGP key it finds for this hierarchy in the local keyring matches this fingerprint. If set, this value is also included in a Key Fingerprint comment in control.ctl.
The administrative group for the hierarchy (conventionally the group to which announcements of new newsgroups and possibly newsgroup lists are posted). This value is included in a comment in control.ctl and PGPKEYS if set.
A publicly accessible NNTP server that supports the LIST ACTIVE command to retrieve a list of current newsgroups in this hierarchy, suitable for pointing actsync at.
Unknown keys are silently ignored.
The configuration fragments to be used for generating the output files. They must follow the format described above.
Fragments of a control.ctl file that are included verbatim. If a file exists in this directory with the same name as one in the config/ directory, the file in this directory is used in preference. Files in this directory cannot provide input to the PGPKEYS file, so hierarchies that require special control.ctl entries but have PGP information should have a conventional configuration file with the PGP information and then a special fragment.
The initial portion of the PGPKEYS file. Any instances of @DATE@
will be replaced by the current date in YYYY-MM-DD format.
The initial portion of the README.html file. Any instances of
@DATE@ will be replaced by the current date in YYYY-MM-DD format.
The final portion of the README.html file. Any instances of @DATE@
will be replaced by the current date in YYYY-MM-DD format.
The initial portion of the control.ctl file. Any instances of
@DATE@ will be replaced by the current date in YYYY-MM-DD format.
A directory containing PGP keys. Each file in this directory corresponds to the hierarchy whose configuration file in config/ has the same name. The contents of the keys/* file is included verbatim in PGPKEYS.
For each hierarchy configuration containing a key-fingerprint parameter, generate-files runs gpg1 with its home directory pointing to this directory, asks for the fingerprint of that PGP key, and verifies that it matches key-fingerprint exactly (including whitespace, so that value must match GnuPG's output format). To generate this keyring in advance of running generate-files, run:
mkdir keyring
chmod 700 keyring
gpg1 --homedir=keyring --import --allow-non-selfsigned-uid keys/*
The --allow-non-selfsigned-uid parameter is only required if you want to support PGP keys that aren't self-signed. This is not secure, but some hierarchy keys are not self-signed.
Russ Allbery <eagle@eyrie.org>
actsync(8), control.ctl(5), gpg1(1), uwildmat(3)
This script is part of the control-archive package. The control-archive web page at <https://www.eyrie.org/~eagle/software/control-archive/> will have the current version of the package.
| < export-control | Russ Allbery > Software > control-archive | process-control > |