diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-22 02:06:55 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-22 02:06:55 +0200 |
commit | 6f49d439216e3067d3f2994221edb8ea16e2c74e (patch) | |
tree | 515173740b95a06faee97f11c0b14270c7c26ea5 /doc/wydawca.texi | |
parent | b200591a7a85ddb90169b1791355af25b009fa1a (diff) | |
download | wydawca-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.texi | 846 |
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 |