aboutsummaryrefslogtreecommitdiff
path: root/doc/wydawca.texi
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-22 02:06:55 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-22 02:06:55 +0200
commit6f49d439216e3067d3f2994221edb8ea16e2c74e (patch)
tree515173740b95a06faee97f11c0b14270c7c26ea5 /doc/wydawca.texi
parentb200591a7a85ddb90169b1791355af25b009fa1a (diff)
downloadwydawca-6f49d439216e3067d3f2994221edb8ea16e2c74e.tar.gz
wydawca-6f49d439216e3067d3f2994221edb8ea16e2c74e.tar.bz2
Fix documentation + minor changes.
* bootstrap.conf: Unconditionally update submodules. * configure.ac: Fix wording of an error message. * doc/Makefile.am (check-config) (check-sub-config): Fix regexps. * doc/wydawca.texi: Update. * src/cmdline.opt (selected_spools): New function, * src/config.c (spool_kw): Move "archive-signatures" to wydawca_kw. * src/wydawca.c (main): selected_spools implies cron_option. * src/wydawca.h (selected_spools): New proto.
Diffstat (limited to 'doc/wydawca.texi')
-rw-r--r--doc/wydawca.texi836
1 files changed, 596 insertions, 240 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 04b599f..201b960 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -256,7 +256,7 @@ Standalone directives}.
Each @dfn{incomplete} triplet, i.e. a triplet missing one or more
necessary files, is then verified by checking if the modification
date of its oldest file is older than a predefined amount of time
-(@FIXME-pxref{file-sweep-time}). If so, the triplet is considered
+(@pxref{general, file-sweep-time}). If so, the triplet is considered
@dfn{expired}, and all its files are removed. This gives users the
possibility to restart interrupted or otherwise broken uploads later.
@@ -285,13 +285,60 @@ this stage of the processing, the uploaded files are actually moved to
their destination directories, requested symbolic links are created,
etc.
+@menu
+* operation modes::
+@end menu
+
+@node operation modes
+@section Operation Modes
+@cindex operation mode
+ The program has two operation modes: @samp{cron mode} and
+@samp{daemon mode}.
+
+@cindex cron mode
+ In @dfn{cron mode}, @command{wydawca} runs in foreground and
+exits when it is done with processing all required spools. By default
+it processes all configured spools, unless a subset of them is
+specified in the command line. This is called @dfn{cron mode}, because
+this is the usual way for @command{wydawca} to be used as a cron job.
+
+@cindex daemon mode
+ In @dfn{daemon mode}, @command{wydawca} detaches itself from
+the conrolling terminal and runs in the background, listening on
+a preconfigured socket. The socket implements the @acronym{TCPMUX}
+protocol@footnote{@uref{http://www.rfc-editor.org/rfc/rfc1078.txt, RFC
+1078}.} and operates as follows:
+
+ After establishing connection, the remote party (the @dfn{client})
+sends the spool tag followed by a CRLF pair. The server
+scans its configuration for a spool that has the requested
+@acronym{ID}. If no such spool is found, the server replies
+with the string @samp{- Unknown service name}, followed by a CRLF pair
+and closes the connection.
+
+ If a matching spool is found, the server replies with @samp{+}
+acknowledgment, immediately followed by an optional message of
+explanation, and terminated with a CRLF. Upon receiving this
+acknowledgment, the client sends the user name of the user who
+did the upload. The following sample transaction illustrates
+this:
+
+@smallexample
+C: stable
+S: +OK. URL ftp://ftp.domain.net
+C: smith
+@end smallexample
+
+ When the user name is received, the server schedules a @dfn{job}
+for processing all triplets submitted by the given user to the
+given spool.
+
@node starting
@chapter How to invoke @command{wydawca}.
@cindex invocation
@anchor{config-file}
@xopindex{config-file, described}
@sopindex{c, described}
-@UNREVISED{}
@command{Wydawca} gets all information it needs from its
@dfn{configuration file} (@pxref{wydawca.rc}). The default
configuration file is @file{@var{sysconfdir}/wydawca.rc}, but if it is
@@ -313,31 +360,55 @@ error and exits with code 0 if the file is OK, or 1 otherwise.
Normally, @command{wydawca} attempts to detect automatically whether
it is run from an interactive console, and if so it prints its
diagnostics on the standard error. Otherwise, the diagnostics is
-directed to the @command{syslog}, and the facility to use is gotten from the
-@code{syslog-facility} configuration file statement
+directed to the @command{syslog}, using the facility given in
+the @code{syslog-facility} configuration file statement
(@pxref{syslog}). Two options are provided if you wish to disable this
autodetection: the option @option{--syslog} instructs the program to print
-all diagnostics using @command{syslog}, and the option
+all diagnostics via @command{syslog}, and the option
@option{--stderr} (or @option{-e}) instructs it to print everything on
the standard error.
@xopindex{cron, described}
- Usually you will run @command{wydawca} as a cron job. In that case,
-it seldom needs any additional arguments, but we suggest to use
-@option{--cron} command line option anyway.
+ The operation mode is configured in the configuration file. If the
+latter configures daemon mode, you can still instruct
+@command{wydawca} to run as a cron job by the @option{--cron} command
+line option. This may be needed, for example, to schedule a daily
+@command{wydawca} run when the main daemon instance is already
+running.
+
+@anchor{spool selection}
+ Usually @command{wydawca} attempts to process all the configured
+spools. You may instruct it to process only a subset of these
+by using the following options:
+
+@table @option
+@xopindex{spool, described}
+@item --spool=@var{tag}
+@itemx -S @var{tag}
+ Process only spool with the given tag.
+@item --source=@var{dir}
+@itemx -s @var{dir}
+ Process only spool with @var{dir} as the source directory.
+@end table
+
+ Any number of these options may be supplied, e.g.:
+
+@smallexample
+$ wydawca --spool=ftp --spool=test --source=/home/ftp/test-upload
+@end smallexample
@anchor{debug}
@xopindex{debug, described}
@sopindex{d, described}
- The @option{--debug} (@option{-d}) tells the program to increase its
-debugging level by 1. @dfn{Debugging level} determines the amount
-of information the program reports when it runs. By default it is 0,
-meaning to report only errors and other critical conditions. Raising
-it may be necessary when debugging new configurations. Each
+ The @option{--debug} (@option{-d}) option tells the program to increase its
+debugging level by 1. The @dfn{debugging level} determines amount
+of information the program reports when it runs. Default level is 0,
+which means that only errors and other critical conditions are
+reported. Raising it may be necessary when debugging new configurations. Each
@option{-d} option raises the level by one, so you can say
@command{wydawca -dd} to obtain level 2, for example. The maximum
-debugging level currently is 4, which prints an impractically big
-amount of information, which is useful mainly for @command{wydawca}
+debugging level (currently it is 4) prints an impractically big
+amount of information, and is useful mainly for @command{wydawca}
developers.
@anchor{dry-run}
@@ -345,13 +416,13 @@ developers.
@sopindex{n, described}
Yet another debugging facility is the @option{--dry-run}
(@option{-n}) option. It instructs @command{wydawca} to avoid doing any
-modifications to the disk contents, but to verbosely print any actions
-it would have taken. Its set the debugging level to 1 and directs the
-diagnostics output to the standard error, as if @option{--debug
---stderr} options have been given. You can raise debugging level
-further by supplying additional @option{--debug} options. The
-@option{--dry-run} option is useful when testing new configurations,
-for example:
+modifications to the disk contents, and to print a verbose description
+of any actions it would have taken. It sets the debugging level to 1
+and directs the diagnostics output to the standard error, as if
+@option{--debug --stderr} options were given. You can raise
+debugging level further by supplying additional @option{--debug}
+options. The @option{--dry-run} option is useful when testing new
+configurations, for example:
@smallexample
$ wydawca -c new.cfg --dry-run
@@ -371,7 +442,7 @@ $ wydawca -c new.cfg --dry-run
@dfn{configuration file} @file{wydawca.rc}. By default it is located
in @var{$sysconfidr} (i.e., in most cases @file{/usr/local/etc}, or
@file{/etc}), but an alternative location may be specified using
-@option{--config} command line option (@FIXME-pxref{--config}).
+@option{--config} command line option (@pxref{starting, config-file}).
If any errors are encountered in the configuration file, the program
reports them on its error output and exits with a non-zero status.
@@ -398,6 +469,11 @@ directives any time by running @command{wydawca --config-help}.
@menu
* Syntax:: Configuration file syntax.
+* general::
+* user privileges::
+* daemon::
+* tcp-wrapper::
+* locking::
* syslog::
* sql::
* dictionaries::
@@ -479,7 +555,8 @@ The default include search path is:
where @var{prefix} is the installation prefix.
New directories can be appended in front of it using @option{-I}
-(@option{--include-dir}) command line option (@FIXME-pxref{--include-dir}).
+(@option{--include-directory}) command line option
+(@pxref{Preprocessor, include-directory}).
@kwindex #include_once
@item #include_once <@var{file}>
@@ -708,6 +785,28 @@ is equivalent to
@smallexample
alias (test);
@end smallexample
+
+@anchor{time interval specification}
+@item time interval specification
+@cindex Time Interval Specification
+ The @dfn{time interval specification} is a string that defines an
+interval, much the same way we do this in English: it consists of one
+or more pairs @samp{number}-@samp{time unit}. For example, the
+following are valid interval specifications:
+
+@smallexample
+@group
+"1 hour"
+"2 hours 35 seconds"
+"1 year 7 months 2 weeks 2 days 11 hours 12 seconds"
+@end group
+@end smallexample
+
+@noindent
+The pairs can occur in any order, however unusual it may sound to a
+human ear, e.g. @samp{2 days 1 year}. If the @samp{time unit} is
+omitted, seconds are supposed.
+
@end table
@cindex statement, block
@@ -792,6 +891,203 @@ include files.
Use @var{command} instead of the default preprocessor.
@end table
+@node general
+@section General Settings
+
+@deffn {Config} foreground bool
+If @var{bool} is @samp{yes}, run in foreground. @xref{invocation,
+foreground}.
+@end deffn
+
+@deffn {Config} single-process bool
+Configure single process mode. Normally @command{wydawca}
+spawns podprocesses for handling incoming connections and spool jobs.
+This is disabled if @var{bool} is @samp{yes} (a so-called
+@dfn{single-processs mode}). This mode is designed for debugging
+purposes. Do not use it in production environments, because it
+severely impairs performance.
+@end deffn
+
+@deffn {Config} umask value
+Set the default umask. The @var{value} argument must be an octal number.
+@end deffn
+
+@deffn {Config} file-sweep-time time
+Consider triplet expired if its oldest file was created more than
+@var{time} seconds ago. @xref{time interval specification}, for the
+syntax of @var{time}.
+
+This parameter may also be set for each spool
+individually. @xref{spool, file-sweep-time}.
+@end deffn
+
+@acronym{gpg-homedir}
+@deffn {Config} gpg-homedir dir
+Set default @acronym{GPG} home directory. The keys for signing
+outgoing messages are looked up in this directory. @xref{statreports,
+gpg-sign}, and @ref{event notification, gpg-sign}.
+@end deffn
+
+@node user privileges
+@section User Privileges
+
+@command{Wydawca} refuses to run with the root privileges. You
+should configure its user privileges by using @code{user} and,
+optionally, @code{group} statements in its configuration file:
+
+@deffn {Config} user name
+Run with UID and GID of the user @var{name}.
+@end deffn
+
+@deffn {Config} group list
+Retain the supplementary groups from the @var{list}. The latter
+must contain group names. For example:
+
+@smallexample
+group (nogroup, ftp);
+@end smallexample
+@end deffn
+
+@node daemon
+@section Daemon Configuration
+@UNREVISED
+
+@deffn {Config} daemon bool
+Enable daemon mode.
+@end deffn
+
+@deffn {Config} listen url
+Define a socket to listen on. Allowed values for @var{url}
+are:
+
+@table @asis
+@findex /etc/services
+@item inet://@var{ip}:@var{port}
+Listen on IPv4@footnote{Support for IPv6 will be added in future
+versions.}. address @var{ip}. @var{Ip} may be given either in
+a dotted quad notation or as a symbolic host name. @var{Port} is
+either a decimal port name, or a service name from @file{/etc/services}.
+
+@item local://@var{file}
+@itemx file://@var{file}
+@itemx unix://@var{file}
+Listen on the @acronym{UNIX} socket file @var{file}, which is either
+an absolute or relative file name.
+@end table
+@end deffn
+
+@deffn {Config} all-spools name
+Declare a special service name, which will be treated as a request to
+process all spools.
+@end deffn
+
+@deffn {Config} wakeup-interval time
+Specifies the wake-up interval for the daemon. If no connections
+are requested during @var{time}, the server will wake up
+and sweep all the configured spools. It is useful for periodical
+removal of expired triplets. See also @code{file-sweep-time}
+statement (@pxref{general, file-sweep-time}).
+
+@xref{time interval specification}, for the syntax of @var{time}.
+@end deffn
+
+@deffn {Config} pidfile file
+Store master process @acronym{PID} in @var{file}. Default pidfile
+location is @file{@var{localstatedir}/run/wydawca.pid}.
+@FIXME{weird location}.
+@end deffn
+
+@node tcp-wrapper
+@section TCP Wrappers
+
+Access to the socket specified in @code{listen} statement is
+controlled by the @code{tcp-wrapper} block statement:
+
+@deffn {Config} tcp-wrapper @{ @dots{} @}
+@smallexample
+tcp-wrapper @{
+ enable @var{arg:@i{boolean}};
+ daemon @var{name:@i{string}};
+ allow-table @var{file:@i{string}};
+ deny-table @var{file:@i{string}};
+ allow-syslog-priority @var{prio:@i{string}};
+ deny-syslog-priority @var{prio:@i{string}};
+@}
+@end smallexample
+@end deffn
+
+This statement is available only if @command{wydawca} was compiled
+with support for TCP wrappers.
+
+@deffn {Config: tcp-wrapper} enable bool
+Enable or disable the use of TCP wrappers.
+@end deffn
+
+@deffn {Config: tcp-wrapper} daemon name
+Set the @dfn{daemon name}. It is the name before the colon in
+the access control file, that marks the line controlling access to
+@command{wydawca}. The default is @samp{wydawca}.
+@end deffn
+
+@findex /etc/hosts.allow
+@deffn {Config: tcp-wrapper} allow-table file
+File name of the positive access control file. By default
+@file{/etc/hosts.allow}.
+@end deffn
+
+@deffn {Config: tcp-wrapper} deny-table file
+File name of the negative access control file. By default
+@file{/etc/hosts.deny}.
+@end deffn
+
+@deffn {Config: tcp-wrapper} allow-syslog-priority prio
+Log allowed accesses via the given @command{syslog} priority.
+@end deffn
+
+@deffn {Config: tcp-wrapper} deny-syslog-priority prio
+Log denied accesses via the given @command{syslog} priority.
+@end deffn
+
+Allowed values for @var{prio} in the @samp{allow-syslog-priority}
+and @samp{deny-syslog-priority} statements are: @samp{emerg},
+@samp{alert}, @samp{crit}, @samp{err}, @samp{warning}, @samp{notice},
+@samp{info}, and @samp{debug}.
+
+@node locking
+@section Locking Configuration
+@UNREVISED
+
+@deffn {Config} locking @{ @dots{} @}
+@smallexample
+locking @{
+ enable @var{arg:@i{boolean}};
+ directory @var{dir:@i{string}};
+ expire-time @var{time:@i{interval}};
+ timeout @var{time:@i{interval}};
+@}
+@end smallexample
+@end deffn
+
+@deffn {Config: locking} enable bool
+Enable or disable locking.
+@end deffn
+
+@deffn {Config: locking} directory dir
+Sets directory for lock files. The default is
+@file{@var{localstatedir}/@/lock/@/wydawca}.
+@end deffn
+
+@deffn {Config: locking} expire-time time
+Sets expiration interval for lock files. An existing lock file
+older than @var{time} is considered stale and removed.
+
+@xref{time interval specification}, for the syntax of @var{time}.
+@end deffn
+
+@deffn {Config: locking} timeout time
+Timeout for acquring locks.
+@end deffn
+
@node syslog
@section Syslog Configuration Directives
@cindex syslog, configuration
@@ -811,7 +1107,7 @@ syslog @{
@end deffn
-@deffn {Config: syslog} facility @var{name}
+@deffn {Config: syslog} facility name
@kwindex authpriv@r{, syslog facility}
@kwindex cron@r{, syslog facility}
@kwindex daemon@r{, syslog facility}
@@ -825,14 +1121,14 @@ case-insensitive and may be optionally prefixed with @samp{log_}
(case-insensitive as well).
@end deffn
-@deffn {Config: syslog} tag @var{string}
+@deffn {Config: syslog} tag string
@cindex syslog tag, configuring
This statement sets the @dfn{syslog tag}, a string
identifying each message issued by the program. By default, the
name of the program (@samp{wydawca}) is used.
@end deffn
-@deffn {Config: syslog} print-priority @var{bool}
+@deffn {Config: syslog} print-priority bool
@cindex syslog priority, printing in diagnostics
In addition to priority segregation, provided by @command{syslog},
you can instruct @command{wydawca} to prefix each syslog message with
@@ -886,19 +1182,19 @@ omitted. If, however, it is present, it must be @samp{localhost}.
@FIXME-xref{sql-host}, for more information and examples.
@end deffn
-@deffn {Config: sql} database @var{name}
+@deffn {Config: sql} database name
Specifies the database name.
@end deffn
-@deffn {Config: sql} user @var{name}
+@deffn {Config: sql} user name
Sets the database user name.
@end deffn
-@deffn {Config: sql} password @var{string}
+@deffn {Config: sql} password string
Sets the password for accessing the database.
@end deffn
-@deffn {Config: sql} ssl-ca @var{file}
+@deffn {Config: sql} ssl-ca file
Sets the pathname to the certificate authority file, if you
wish to use a secure connection to the server via SSL.
@end deffn
@@ -921,29 +1217,28 @@ sql default @{
@section Dictionaries
@cindex dictionaries
@cindex @acronym{PGP} key
-@UNREVISED
A @dfn{dictionary} defines the ways to retrieve user information
necessary to verify the submission. This information can be, for
example, the user's @acronym{PGP} key or his permissions on a project.
- Dictionary is defined in configuration file using the
+ A dictionary is defined in configuration file using the
following syntax:
-@deffn {Config} dictionary
+@deffn {Config} dictionary @{ @dots{} @}
@smallexample
dictionary @var{dict-id} @{
type @var{type};
query @var{string};
- params (@var{param1},@var{param2},...);
+ params (@var{param1},@var{param2},@dots{});
@}
@end smallexample
@end deffn
- A @code{dictionary} statement can appear either in the global scope of
+ The @code{dictionary} statement can appear either in the global scope of
the configuration file, or inside a @code{spool} statement
(@pxref{spool}). Global definitions affect all directory
pairs in the configuration file, and ones inside a @code{directory}
-statement override them for that particular directory pair.
+statement override them for that particular spool.
There are two dictionaries, identified by the value of
@var{dict-id} tag:
@@ -951,20 +1246,20 @@ There are two dictionaries, identified by the value of
@table @asis
@kwindex project-owner
@item project-owner
- Retrieve email addresses and real names of administrators (or
+ Keeps email addresses and real names of administrators (or
@dfn{owners}) of a project. It may return any number of rows, each one
consisting of two columns: an email address and a user name, in this
order.
@kwindex project-uploader
@item project-uploader
- Return system user names, real names, emails and GPG keys of
+ Keeps system user names, real names, emails and GPG keys of
the users that are allowed to make uploads for the project.
@end table
The sub-statements of @code{dictionary} are:
-@deffn {Config: dictionary} type @var{name}
+@deffn {Config: dictionary} type name
Defines the type of this dictionary. @var{Name} is one of the following:
@table @asis
@@ -986,7 +1281,7 @@ reserved for future use.
See below for a detailed description of these dictionary types.
@end deffn
-@deffn {Config: dictionary} query @var{string}
+@deffn {Config: dictionary} query string
Sets the query used for retrieving the data. The @var{string} is
subject to meta-variable interpretation (@pxref{meta-interpretation}). The
following meta-variables are defined:
@@ -1029,7 +1324,7 @@ defined only for @samp{project-owner} dictionaries.
@end table
@end deffn
-@deffn {Config: dictionary} params (@var{param1}, @var{param2}, ...)
+@deffn {Config: dictionary} params (param1, param2, @dots{})
Supplies additional parameters.
@end deffn
@@ -1089,7 +1384,7 @@ dictionary project-owner @{
@UNREVISED
@smallexample
-dictionary project-owner @{
+dictionary project-uploader @{
type sql;
params (default);
query "SELECT user.email, user.realname "
@@ -1133,7 +1428,7 @@ appear either in the global scope, in which case it affects all
spools, or within a @code{spool} block (@pxref{spool}),
where it affects only the given spool.
-@deffn {Config} archive @var{type}
+@deffn {Config} archive type
@smallexample
archive @var{type} @{
name @var{file-or-dir};
@@ -1158,7 +1453,7 @@ archive @var{type} @{
@end table
@end deffn
-@deffn {Config: archive} name @var{file-or-dir}
+@deffn {Config: archive} name file-or-dir
Specify the name of the tar archive (if type @samp{tar} is used) or
destination directory (if type @samp{directroy} is used).
@end deffn
@@ -1180,7 +1475,7 @@ using GNU tar @option{--occurrence} option (@pxref{multiple, Multiple
Files with the Same Name, Multiple Files with the Same Name, tar,
@acronym{GNU} tar: an archiver tool}).
-@deffn {Config} tar-program @var{name}
+@deffn {Config} tar-program name
By default, @code{wydawca} will search for @command{tar} binary in
your search path. If you wish to use a particular binary, you may
specify its full file name using @code{tar-program} statement.
@@ -1220,7 +1515,7 @@ directory @file{/home/@/ftp/@/gnu/@/tar/@/.archive}, files from
@file{/home/@/ftp/@/gnu/@/tar/@/old} --- in
@file{/home/@/ftp/@/gnu/@/tar/@/.archive/@/old}, etc.
-@deffn {Config: archive} backup @var{type}
+@deffn {Config: archive} backup type
@anchor{backup-methods}
@vindex version-control @r{Emacs variable}
When using the @samp{directory} archivation type, it may happen that the
@@ -1267,13 +1562,14 @@ directives,, maintain.info, Information For Maintainers of GNU Software}),
@command{wydawca} also checks if the file named @file{@var{file}.sig}
exists. If so, it is archived along with @file{@var{file}}.
-@kwindex archive-signatures
+@deffn {Config} archive-signatures bool
If implicit signature archivation is not needed, use
the @code{archive-signatures} statement to disable it, e.g.:
@smallexample
archive-signatures no;
@end smallexample
+@end deffn
@node spool
@section Distribution Spool
@@ -1281,19 +1577,14 @@ archive-signatures no;
@cindex defining source and distribution directories
@cindex distribution directory, defining
@cindex source directory, defining
-@kwindex source
-@kwindex destination
-@UNREVISED
A @dfn{distribution spool} defines the location of the source directory
and the corresponding distribution (or @dfn{destination})
-directory. It may also set archivation type,
-various dictionaries and notifications for that directory, thus overriding
-global settings.
+directory. It may also set archivation type, various dictionaries and
+notifications for that directory, thus overriding the global settings.
-Distribution spool is defined in the configuration file by the
-@code{spool} block statement:
+The @code{spool} block statement defines a distribution spool:
-@deffn {Config} spool @var{tag}
+@deffn {Config} spool tag @{ @dots{} @}
@smallexample
spool @var{tag} @{
url @var{url};
@@ -1312,16 +1603,21 @@ will be used in log messages, timers (@FIXME-pxref{timers}) and in
meta-variable interpretation (@pxref{meta-interpretation}).
@end deffn
-@deffn {Config: spool} url @var{string}
+@deffn {Config: spool} alias list
+Defines a list of @dfn{aliases}, i.e. alternative tag names for this
+spool.
+@end deffn
+
+@deffn {Config: spool} url string
Defines download @acronym{URL}, associated with this spool. Its value
may be used as @samp{$@{url@}} meta-variable in mail notifications.
@end deffn
-@deffn {Config: spool} source @var{dir}
+@deffn {Config: spool} source dir
Specifies the location of the source directory.
@end deffn
-@deffn {Config: spool} destination @var{dir}
+@deffn {Config: spool} destination dir
Specifies the type and location of the destination directory. The
@var{dir} argument must be either an absolute name of a directory on
the local file system, or a special @acronym{URL}. @command{Wydawca}
@@ -1335,7 +1631,7 @@ Equivalent to @var{dir-name} alone. Defines a destination directory
located on the local file system.
@item null:
-Defines a @dfn{null upload spool}. Null spools run implement all tests
+Defines a @dfn{null upload spool}. Null spools implement all tests
described in @ref{overview}, but do not do any actual copying. The
uploaded files are simply removed after checks are over. Null spools
are useful mainly for diagnostic purposes.
@@ -1350,11 +1646,18 @@ Configure spool-specific archivation. @xref{archivation}, for its
description.
@end deffn
-@deffn {Config: spool} dictionary @var{tag} @{ @dots{} @}
+@deffn {Config: spool} dictionary tag @{ @dots{} @}
Configure spool-specific dictionary. @xref{dictionaries}, for a
detailed discussion of this statement.
@end deffn
+@deffn {Config: spool} file-sweep-time time
+Set expiration time for triplets in this spool. A triplet is
+considered expired if its oldest file was created more than
+@var{time} seconds ago. This statement overrides the global
+@samp{file-sweep-time} setting (@pxref{general, file-sweep-time}).
+@end deffn
+
@deffn {Config: spool} notify-event @{ @dots{} @}
Configure spool-specific event notification. @xref{notification},
for a detailed discussion of this statement.
@@ -1488,7 +1791,7 @@ A symlink is created.
A symlink is removed.
@end table
-@deffn {Config} statistics @var{list}
+@deffn {Config} statistics list
The amount of information included in the statistics summary is
configured using the @code{statistics} statement. This statement takes
a list of arguments, each one being one of the keywords, described
@@ -1541,7 +1844,7 @@ previous section.
The sender email address for these notifications is set using the
@code{from-address} statement.
-@deffn {Config} from-address @var{address}
+@deffn {Config} from-address address
Set sender address for outgoing mails. E.g.:
@smallexample
@@ -1552,10 +1855,10 @@ from-address ftp-uploads@@gnu.org.ua;
It is not strictly necessary to specify the sender address. In the
absence of @code{from-address} statement, the sender email will be
constructed from the name of the user @command{wydawca} runs as
-(@FIXME-pxref{user privs}) and the full domain name of the machine it
+(@pxref{user privileges}) and the full domain name of the machine it
runs at.
-@deffn {Config} admin-address @var{email}
+@deffn {Config} admin-address email
Sets the admin email address or addresses. The statistics
notifications and any notifications configured to be sent to admins
will be forwarded to this address. The @var{email} argument is either
@@ -1593,7 +1896,7 @@ To send messages, @command{wydawca} uses a special logical entity
called a @dfn{mailer}. It is set in the configuration file using
@code{mailer} keyword.
-@deffn {Config} mailer @var{url}
+@deffn {Config} mailer url
Set mailer @acronym{URL}.
@end deffn
@@ -1698,10 +2001,10 @@ mailer "|/bin/nullmail localhost -F$@{sender@} $@{rcpt@}"
Each notification message is build from a message template, by
expanding meta-variables (@pxref{meta-interpretation}) within it.
The message text may be specified either in place within the
-configuration directive it belongs to (@FIXME-pxref{notification}), or
+configuration directive it belongs to (@pxref{notification}), or
defined by @code{define-message} statement.
-@deffn {Config} define-message @var{name} @var{text};
+@deffn {Config} define-message name text
Define message @var{name} to be @var{text}. This message can be
referred to from other configuration statements by @code{@@@var{name}}
notation.
@@ -1734,9 +2037,8 @@ EOT;
@node statreports
@subsection Statistic Reports
-@UNREVISED
-@deffn {Config} mail-statistics @{ ... @}
+@deffn {Config} mail-statistics @{ @dots{} @}
The @code{mail-statistics} statement configures the statistic reports
sent to the system administrator.
@@ -1744,11 +2046,12 @@ sent to the system administrator.
mail-statistics @{
message @var{text-or-id};
statistics @var{item-list};
+ gpg-sign @var{key};
@}
@end smallexample
@end deffn
-@deffn {Config: mail-statistics} message @var{text-or-id}
+@deffn {Config: mail-statistics} message text-or-id
Define the message text. The argument is either the message text
template, or a reference to a template previously defined by a
@code{define-message} (@pxref{templates}). The reference syntax is:
@@ -1761,7 +2064,7 @@ message @@@var{name};
where @var{name} is the message name as used in @code{define-message}.
@end deffn
-@deffn {Config: mail-statistics} statistics @var{item-list}
+@deffn {Config: mail-statistics} statistics item-list
The argument is a list of statistics keywords as described in
@ref{statistics}. A report will be sent only if statistics
counters for at least one of the requested categories are not
@@ -1774,6 +2077,12 @@ statistics (stat-msg, errors, access-violations, bad-signatures);
@end smallexample
@end deffn
+@deffn {Config: mail-statistics} gpg-sign key
+If this statement is present, the message will be signed using
+the supplied @acronym{GPG} @var{key}. The key is looked up in
+the @acronym{GPG} home directory (@pxref{gpg-homedir}).
+@end deffn
+
The statistics message is sent to addresses configured by
@code{admin-address} statement (@pxref{notification, admin-address}).
@@ -1842,24 +2151,26 @@ Wydawca
@node event notification
@subsection Event Notification
@cindex event notification
-@UNREVISED
+
A number of @dfn{events} are tracked during the execution. Any of
them can be used to trigger an email notification of any party
-concerned: the system administrator, project administrators, or
-the user that initiated the upload. These notifications are configured
+concerned: the system administrator, project administrators,
+the user that initiated the upload, or any other recipients, specified
+by their email addresses. These notifications are configured
using the @code{notify-event} statement:
-@deffn {Config} notify-event @{ ... @}
+@deffn {Config} notify-event @{ @dots{} @}
@smallexample
notify-event @{
event @var{ev-id};
recipient @var{who};
message @var{text-or-id};
+ gpg-key @var{key};
@}
@end smallexample
@end deffn
-@deffn {Config: notify-event} event @var{ev-id}
+@deffn {Config: notify-event} event ev-id
Send notification when the event @var{ev-id} occurs. The following
table describes the available @var{ev-id}s:
@@ -1884,11 +2195,18 @@ uploader.
@end table
@end deffn
-@deffn {Config: notify-event} recipient @var{who}
+@deffn {Config: notify-event} recipient who
Determines who should receive the notification. The following values
for @var{who} are allowed:
@table @code
+@kwindex read
+@kwindex message
+@item read
+@itemx message
+Read recipients from the @samp{To}, @samp{Cc} and @samp{Bcc} headers
+of the message.
+
@kwindex admin
@item admin
The system administrator, as defined in @code{admin-address} statement
@@ -1902,10 +2220,22 @@ dictionary (@pxref{dictionaries}).
@kwindex user
@item user
-The user who uploaded files.
+User name of the user who uploaded files.
@end table
@end deffn
+@deffn {Config: notify-event} message text-or-id
+Define the message text. The argument is either the message text
+template, or a reference to a template previously defined by a
+@code{define-message} (@pxref{templates}).
+@end deffn
+
+@deffn {Config: notify-event} gpg-sign key
+If this statement is present, the message will be signed using
+the supplied @acronym{GPG} @var{key}. The key is looked up in
+the @acronym{GPG} home directory (@pxref{gpg-homedir}).
+@end deffn
+
For example, the following two statements instruct @command{wydawca}
to email notifications about any @code{bad-directive-signature} event to
project administrators and to the user who did the upload, using two
@@ -2059,236 +2389,247 @@ EOT;
@node wydawca.rc
@chapter @command{Wydawca} configuration file.
@cindex configuration statements, reference
-@WRITEME
+ This chapter summarizes the configuration statements. For each
+statement, a reference to its detailed description is provided.
@smallexample
-# Configuration file structure for wydawca.
-# For more information, use `info wydawca configuration'.
-
-# Enable daemon mode
-daemon @var{arg:@i{<boolean>}};
+# @r{Enable daemon mode.}
+# @xref{daemon}.
+daemon @var{arg:@i{boolean}};
-# Start in foreground even in daemon mode
-foreground @var{arg:@i{<boolean>}};
+# @r{Start in foreground even in daemon mode.}
+# @xref{general, foreground}.
+foreground @var{arg:@i{boolean}};
-# Do not spawn subprocesses
-single-process @var{arg:@i{<boolean>}};
+# @r{Do not spawn subprocesses.}
+# @xref{general, single-process}.
+single-process @var{arg:@i{boolean}};
-# Set wake-up interval
-wakeup-interval @var{time:@i{<string>}};
+# @r{Set wake-up interval.}
+# @xref{general, wakeup-interval}.
+wakeup-interval @var{time:@i{string}};
-# Set pid file name
-pidfile @var{file:@i{<string>}};
+# @r{Set pid file name.}
+# @xref{general, pidfile}.
+pidfile @var{file:@i{string}};
-# Run with UID and GID of this user
-user @var{name:@i{<string>}};
+# @r{Run with UID and GID of this user.}
+# @xref{user privileges}.
+user @var{name:@i{string}};
-# Retain these supplementary groups
-group @var{arg:@i{<list of string>}};
+# @r{Retain these supplementary groups:}
+# @xref{user privileges}.
+group @var{arg:@i{list of string}};
-# Configure locking
+# @r{Configure locking}
+# @xref{locking}.
locking @{
- # Enable or disable locking
- enable @var{arg:@i{<boolean>}};
+ # @r{Enable or disable locking.}
+ enable @var{arg:@i{boolean}};
- # Set directory for lock files
- directory @var{dir:@i{<string>}};
+ # @r{Set directory for lock files.}
+ directory @var{dir:@i{string}};
- # Define lock expiration interval
- expire-time @var{interval:@i{<string>}};
+ # @r{Define lock expiration interval.}
+ expire-time @var{time:@i{interval}};
- # Number of times to retry locking
- retry-attempts @var{n:@i{<number>}};
-
- # Delay between locking attempts
- retry-interval @var{interval:@i{<string>}};
+ # @r{Locking timeout.}
+ timeout @var{time:@i{interval}};
@}
-# Listen on this address
-listen @var{socket:@i{<sock-addr>}};
+# @r{Listen on this address.}
+# @xref{daemon, listen}.
+listen @var{socket:@i{sock-addr}};
-# Configure TCP wrappers
+# @r{Configure TCP wrappers.}
+# @xref{tcp-wrapper}.
tcp-wrapper @{
- # Enable TCP wrapper access control. Default is "yes".
- enable @var{arg:@i{<boolean>}};
+ # @r{Enable TCP wrapper access control. Default is @samp{yes}}.
+ enable @var{arg:@i{boolean}};
- # Set daemon name for TCP wrapper lookups. Default is program name.
- daemon @var{name:@i{<string>}};
+ # @r{Set daemon name for TCP wrapper lookups. Default is program name.}
+ daemon @var{name:@i{string}};
- # Use file for positive client address access control (default:
- # /etc/hosts.allow).
- allow-table @var{file:@i{<string>}};
+ # @r{Use @var{file} for positive client address access control.}
+ # @r{(default: @file{/etc/hosts.allow}).}
+ allow-table @var{file:@i{string}};
- # Use file for negative client address access control (default:
- # /etc/hosts.deny).
- deny-table @var{file:@i{<string>}};
+ # @r{Use @var{file} for negative client address access control.}
+ # @r{(default: @file{/etc/hosts.deny}).}
+ deny-table @var{file:@i{string}};
- # Log host allows at this syslog priority.
- allow-syslog-priority @var{prio:@i{<string>}};
+ # @r{Log host allows at this syslog priority.}
+ allow-syslog-priority @var{prio:@i{string}};
- # Log host denies at this syslog priority.
- deny-syslog-priority @var{prio:@i{<string>}};
+ # @r{Log host denies at this syslog priority.}
+ deny-syslog-priority @var{prio:@i{string}};
@}
-#