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.texi846
1 files changed, 601 insertions, 245 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 04b599f..201b960 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -253,13 +253,13 @@ Standalone directives}.
@cindex incomplete triplet
@cindex triplet, expired
@cindex expired triplet
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.
@cindex dictionary
@cindex @acronym{PGP}
After completing these preliminary stages, @command{wydawca}
@@ -282,19 +282,66 @@ previous step, the triplet is rejected.
Finally, directives from the directive file are executed. On
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
located elsewhere, you can specify its new location with the
@option{--config-file} (@option{-c}) command line option.
@@ -310,51 +357,75 @@ error and exits with code 0 if the file is OK, or 1 otherwise.
@xopindex{stderr, described}
@sopindex{e, described}
@xopindex{syslog, described}
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}
@xopindex{dry-run, described}
@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
@end smallexample
@xopindex{help, described}
@@ -368,13 +439,13 @@ $ wydawca -c new.cfg --dry-run
@node configuring
@chapter How to Configure @command{wydawca}.
Upon startup, @command{wydawca} reads its settings from the
@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.
@xopindex{lint, introduced}
To test the configuration file without starting the server use
@@ -395,12 +466,17 @@ line option. To avoid preprocessing it, use
The rest of this section describes the configuration file syntax in
detail. You can receive a concise summary of all configuration
directives any time by running @command{wydawca --config-help}.
@menu
* Syntax:: Configuration file syntax.
+* general::
+* user privileges::
+* daemon::
+* tcp-wrapper::
+* locking::
* syslog::
* sql::
* dictionaries::
* archivation::
* spool::
* statistics::
@@ -476,13 +552,14 @@ The default include search path is:
@end enumerate
@noindent
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}>
@itemx #include_once @var{file}
Same as @code{#include}, except that, if the @var{file} has already
been included, it will not be included again.
@@ -705,12 +782,34 @@ alias test;
@noindent
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
@cindex block statement
A @dfn{block statement} introduces a logical group of
statements. It consists of a keyword, followed by an optional value,
@@ -789,12 +888,209 @@ include files.
@xopindex{preprocessor, defined}
@item --preprocessor=@var{command}
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
Unless told otherwise, @command{wydawca} uses @code{syslog} to print
its diagnostic messages. By default, the program uses the
@@ -808,13 +1104,13 @@ syslog @{
print-priority yes;
@}
@end smallexample
@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}
@kwindex ftp@r{, syslog facility}
@kwindex local0 @r{through} local7@r{, syslog facilities}
@kwindex mail@r{, syslog facility}
@@ -822,20 +1118,20 @@ syslog @{
@samp{auth}, @samp{authpriv}, @samp{cron}, @samp{daemon}, @samp{ftp},
@samp{local0} through @samp{local7}, and @samp{mail}. These names are
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
its priority. To do so, set:
@smallexample
@@ -883,25 +1179,25 @@ database. Optional @var{port-or-socket} specifies port number (for
@acronym{TCP} connections) or socket name (for @acronym{UNIX} sockets)
to use. In the latter case, the @var{hostname} and the colon may be
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
@noindent
An example @code{sql} statement follows:
@@ -918,56 +1214,55 @@ sql default @{
@end smallexample
@node dictionaries
@section Dictionaries
@cindex dictionaries
@cindex @acronym{PGP} key
-@UNREVISED
-A @dfn{dictionary} defines the ways to retrieve user information
+ 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:
@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
@kwindex builtin
@item builtin
The data are supplied in the configuration file.
@@ -983,13 +1278,13 @@ Defines the type of this dictionary. @var{Name} is one of the following:
reserved for future use.
@end table
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:
@table @code
@kwindex p
@@ -1026,13 +1321,13 @@ Spool source directory (@pxref{spool, source}).
@itemx user:name
The system name of the user that submitted the triplet. This is
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
@menu
* sql type::
* builtin type::
@@ -1086,13 +1381,13 @@ dictionary project-owner @{
@node project-uploader-sql
@subsubsection Project-uploader: an SQL Implementation
@cindex project-uploader-sql
@UNREVISED
@smallexample
-dictionary project-owner @{
+dictionary project-uploader @{
type sql;
params (default);
query "SELECT user.email, user.realname "
"FROM user,user_group,groups "
"WHERE user_group.user_id=user.user_id "
"AND user_group.group_id=groups.group_id "
@@ -1130,13 +1425,13 @@ their existing files.
@command{tar} file, and to a separate directory. The method to be used
is configured using @code{archive} statement. This statement can
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};
backup @var{type};
@}
@end smallexample
@@ -1155,13 +1450,13 @@ archive @var{type} @{
@kwindex directory@r{, archivation}
@item directory
Store file in a separate directory.
@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
If the archivation type @asis{tar} is used, the @code{name}
statement sets the full name of the tar archive to use, e.g.:
@@ -1177,13 +1472,13 @@ archive tar @{
Archive, Appending Files to an Archive, tar, @acronym{GNU} tar: an
archiver tool}). Any archived instance can subsequently be retrieved
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.
@end deffn
The @samp{directory} archivation type means that archive copies will
@@ -1217,13 +1512,13 @@ archive directory @{
@noindent
mean that files from @file{/home/@/ftp/@/gnu/@/tar} will be archived in the
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
archive file with the same name as the one about to be created already
exists. This statement specifies how to handle the existing copy, in
other words, how to @dfn{backup} it. The @var{type} argument
@@ -1264,39 +1559,35 @@ archivation} facility. It works as follows. When archivation of
@var{file} is requested by @code{archive: @var{file}} statement in the
directive file (@pxref{FTP Upload Directive File - v1.1, Standalone
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
@cindex distribution spool
@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
+ 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};
alias (@var{aliases});
source @var{dir};
destination @var{dir};
@@ -1309,22 +1600,27 @@ spool @var{tag} @{
The @var{tag} argument defines a unique identifier for this spool. It
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}
version @value{VERSION} supports two destination @acronym{URL}
schemes:
@@ -1332,13 +1628,13 @@ schemes:
@item file://@var{dir-name}
@itemx dir://@var{dir-name}
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.
@end table
@end deffn
@@ -1347,17 +1643,24 @@ definitions for this spool.
@deffn {Config: spool} archive @{ @dots{} @}
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.
@end deffn
The @code{source} and @code{destination} statements are mandatory.
@@ -1485,13 +1788,13 @@ A symlink is created.
@kwindex rmsymlinks@r{, statistics}
@item rmsymlinks
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
above. For example, the following statement causes only the
information about errors and warnings to be printed:
@@ -1538,27 +1841,27 @@ concern their projects. Additionally, the system administrator can
choose to obtain via email the execution statistics, described in the
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
from-address ftp-uploads@@gnu.org.ua;
@end smallexample
@end deffn
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
a @acronym{RFC} 822 email address, or a list of such addresses. For
example, the following statement configures a single admin address:
@@ -1590,13 +1893,13 @@ admin-address (root@@gnu.org.ua, ftp-adm@@gnu.org.ua);
@subsection Mailer
@cindex mailer
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
@cindex @acronym{URL}, mailer
@cindex mailer @acronym{URL}
A mailer @acronym{URL} consists of a scheme specification, followed
@@ -1695,16 +1998,16 @@ mailer "|/bin/nullmail localhost -F$@{sender@} $@{rcpt@}"
@cindex templates, notification messages
@cindex notification message template
@cindex message template
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.
@end deffn
The message text must be formatted as a valid RFC-822 message, i.e. it
@@ -1731,52 +2034,58 @@ define-message my-message <<EOT
This is a test message.
EOT;
@end smallexample
@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.
@smallexample
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:
@smallexample
message @@@var{name};
@end smallexample
@noindent
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
zero. For example, the following statement requires sending
notifications only if there occurred any errors or access violation
attempts, or any bad signature was uploaded:
@smallexample
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}).
@cindex meta-variables in admin notifications
The meta-variables available for use in statistics reports are:
@@ -1839,30 +2148,32 @@ Wydawca
@}
@end smallexample
@node event notification
@subsection Event Notification
@cindex event notification
-@UNREVISED
-A number of @dfn{events} are tracked during the execution. Any of
+
+ 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} noti