From 6f49d439216e3067d3f2994221edb8ea16e2c74e Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Tue, 22 Dec 2009 02:06:55 +0200 Subject: 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. --- doc/wydawca.texi | 846 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 601 insertions(+), 245 deletions(-) (limited to 'doc/wydawca.texi') 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 + 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 + 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 + + 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,8 +2220,20 @@ 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} @@ -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'. +# @r{Enable daemon mode.} +# @xref{daemon}. +daemon @var{arg:@i{boolean}}; -# Enable daemon mode -daemon @var{arg:@i{}}; +# @r{Start in foreground even in daemon mode.} +# @xref{general, foreground}. +foreground @var{arg:@i{boolean}}; -# Start in foreground even in daemon mode -foreground @var{arg:@i{}}; +# @r{Do not spawn subprocesses.} +# @xref{general, single-process}. +single-process @var{arg:@i{boolean}}; -# Do not spawn subprocesses -single-process @var{arg:@i{}}; +# @r{Set wake-up interval.} +# @xref{general, wakeup-interval}. +wakeup-interval @var{time:@i{string}}; -# Set wake-up interval -wakeup-interval @var{time:@i{}}; +# @r{Set pid file name.} +# @xref{general, pidfile}. +pidfile @var{file:@i{string}}; -# Set pid file name -pidfile @var{file:@i{}}; +# @r{Run with UID and GID of this user.} +# @xref{user privileges}. +user @var{name:@i{string}}; -# Run with UID and GID of this user -user @var{name:@i{}}; +# @r{Retain these supplementary groups:} +# @xref{user privileges}. +group @var{arg:@i{list of string}}; -# Retain these supplementary groups -group @var{arg:@i{}}; - -# Configure locking +# @r{Configure locking} +# @xref{locking}. locking @{ - # Enable or disable locking - enable @var{arg:@i{}}; - - # Set directory for lock files - directory @var{dir:@i{}}; + # @r{Enable or disable locking.} + enable @var{arg:@i{boolean}}; - # Define lock expiration interval - expire-time @var{interval:@i{}}; + # @r{Set directory for lock files.} + directory @var{dir:@i{string}}; - # Number of times to retry locking - retry-attempts @var{n:@i{}}; + # @r{Define lock expiration interval.} + expire-time @var{time:@i{interval}}; - # Delay between locking attempts - retry-interval @var{interval:@i{}}; + # @r{Locking timeout.} + timeout @var{time:@i{interval}}; @} - -# Listen on this address -listen @var{socket:@i{}}; -# Configure TCP wrappers +# @r{Listen on this address.} +# @xref{daemon, listen}. +listen @var{socket:@i{sock-addr}}; + +# @r{Configure TCP wrappers.} +# @xref{tcp-wrapper}. tcp-wrapper @{ - # Enable TCP wrapper access control. Default is "yes". - enable @var{arg:@i{}}; + # @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{}}; + # @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{}}; + # @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{}}; + # @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{}}; + # @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{}}; + # @r{Log host denies at this syslog priority.} + deny-syslog-priority @var{prio:@i{string}}; @} -# Set mailer URL -mailer @var{url:@i{}}; +# @r{Set mailer URL.} +# @xref{mailer}. +mailer @var{url:@i{string}}; -# Set admin email address -admin-address @var{email:@i{}}; +# @r{Set admin email address.} +# @xref{notification, admin-address}. +admin-address @var{email:@i{string}}; -# Set sender email address -from-address @var{email:@i{}}; +# @r{Set sender email address.} +# @xref{notification, from-address}. +from-address @var{email:@i{string}}; -# Define file sweep time -file-sweep-time @var{interval:@i{}}; +# @r{Define file sweep time.} +# @xref{general, file-sweep-time}. +file-sweep-time @var{time:@i{interval}}; -# Set tar invocation command line -tar-program @var{prog:@i{}}; +# @r{Set tar invocation command line.} +# @xref{archivation, tar-program}. +tar-program @var{prog:@i{string}}; -# Set umask -umask @var{mask:@i{}}; +# @r{Set umask.} +# @xref{general, umask}. +umask @var{mask:@i{octal}}; -# Print these stats at the end of run -statistics @var{items:@i{}}; +# @r{Control implicit signature archivation}. +# @xref{archivation, archive-signatures}. +archive-signatures @var{arg:@i{boolean}}; -# Define SQL database -sql @var{id:@i{}} @{ - # Set SQL server hostname or IP address - host @var{host:@i{}}; +# @r{Print these stats at the end of each run.} +# @xref{statistics}. +statistics @var{items:@i{string}}; - # Set database name - database @var{dbname:@i{}}; +# @r{Service names that request scanning all spools.} +# @xref{daemon, all-spools}. +all-spools @var{arg:@i{list of string}}; - # Set SQL user name - user @var{name:@i{}}; +# @r{GPG home directory}. +# @xref{gpg-homedir}. +gpg-homedir @var{arg:@i{string}}; - # Set SQL user password - password @var{arg:@i{}}; -@} +# @r{Define SQL database}. +# @xref{sql}. +sql @var{id:@i{string}} @{ + # @r{Set SQL server hostname or IP address.} + host @var{host:@i{string}}; -# Configure syslog logging -syslog @{ - # Set syslog facility. Arg is one of the following: user, daemon, auth, - # authpriv, mail, cron, local0 through local7 (case-insensitive), or a - # facility number. - facility @var{name:@i{}}; + # @r{Set database name.} + database @var{dbname:@i{string}}; - # Tag syslog messages with this string - tag @var{string:@i{}}; - - # Prefix each message with its priority - print-priority @var{arg:@i{}}; -@} + # @r{Set SQL user name.} + user @var{name:@i{string}}; -# Define message text -define-message @var{ident:@i{}} @var{text:@i{}}; + # @r{Set SQL user password.} + password @var{arg:@i{string}}; -# Set up archivation -archive @var{type:@i{}} @{ - # Name of archive file or directory - name @var{file-or-dir:@i{}}; - - # Define backup type - backup @var{type:@i{}}; + # @r{File name of the Certificate Authority (CA) certificate.} + ssl-ca @var{file:@i{string}}; @} -# Send statistics -mail-statistics @{ - # Message text - message @var{text:@i{}}; +# @r{Configure syslog logging.} +# @xref{syslog}. +syslog @{ + # @r{Set syslog facility.} + facility @var{name:@i{string}}; + + # @r{Tag syslog messages with this string.} + tag @var{string:@i{string}}; - # Send mail if one or more of these items are set - statistics @var{items:@i{}}; + # @r{Prefix each message with its priority.} + print-priority @var{arg:@i{boolean}}; @} -# Configure notification -notify-event @{ - # Event on which to notify - event @var{ev-id:@i{}}; +# @r{Define message text.} +# @xref{templates}. +define-message @var{ident:@i{string}} @var{text:@i{string}}; - # Notify this recipient - recipient @var{who:@i{}}; +# @r{Set up archivation.} +# @xref{archivation}. +archive @var{type:@i{string}} @{ + # @r{Name of archive file or directory.} + name @var{file-or-dir:@i{string}}; - # Text of the notification or identifier of a defined message template - message @var{text-or-id:@i{}}; + # @r{Define backup type.} + # @xref{backup-methods}. + backup @var{type:@i{string}}; @} -# Define a dictionary -dictionary @var{ident} @{ - # Dictionary type - type @var{type:@i{}}; +# @r{Send statistics.} +# @xref{statreports}. +mail-statistics @{ + # @r{Message text.} + message @var{text:@i{string}}; - # Query template - query @var{string:@i{}}; + # @r{Send mail if one or more of these items are set.} + statistics @var{items:@i{string}}; - # Set dictionary parameters - params @var{arg:@i{}}; + # @r{Sign message with this key.} + gpg-sign @var{key:@i{string}}; @} -# Define distribution spool -spool @var{tag:@i{}} @{ - # URL corresponding to this spool - url @var{arg:@i{}}; +# @r{Configure notification.} +# @xref{notification}. +notify-event @{ + # @r{Event on which to notify.} + event @var{ev-id:@i{string}}; - # Aliases - alias @var{arg:@i{}}; + # @r{Notify this recipient.} + recipient @var{who:@i{string}}; - # Source directory - source @var{dir:@i{}}; + # @r{Text of the notification or identifier of} + # @r{a defined message template.} + message @var{text-or-id:@i{string}}; - # Destination directory - destination @var{dir:@i{}}; + # @r{Sign message with this key.} + gpg-sign @var{key:@i{string}}; +@} - # Define file sweep time - file-sweep-time @var{interval:@i{}}; +# @r{Define data dictionary.} +# @xref{dictionaries}. +dictionary @var{ident:@i{string}} @{ + # @r{Dictionary type}. + type @var{type:@i{string}}; - # Define a dictionary - dictionary @var{ident} @{ - # Dictionary type - type @var{type:@i{}}; + # @r{Query template.} + query @var{string:@i{string}}; - # Query template - query @var{string:@i{}}; + # @r{Set dictionary parameters.} + params @var{arg:@i{list of string}}; +@} - # Set dictionary parameters - params @var{arg:@i{}}; - @} +# @r{Define distribution spool.} +# @xref{spool}. +spool @var{tag:@i{string}} @{ + # @r{URL corresponding to this spool.} + url @var{arg:@i{string}}; - # Set up archivation - archive @var{type:@i{}} @{ - # Name of archive file or directory - name @var{file-or-dir:@i{}}; + # @r{Aliases.} + alias @var{arg:@i{list of string}}; - # Define backup type - backup @var{type:@i{}}; - @} + # @r{Source directory.} + source @var{dir:@i{string}}; - # Control implicit signature archivation - archive-signatures @var{arg:@i{}}; + # @r{Destination directory.} + destination @var{dir:@i{string}}; - # Configure notification - notify-event @{ - # Event on which to notify - event @var{ev-id:@i{}}; + # @r{Define file sweep time.} + file-sweep-time @var{time:@i{interval}}; - # Notify this recipient - recipient @var{who:@i{}}; + # @r{Define data dictionary.} + # @r{See above}. + dictionary @var{ident:@i{string}}> @{ @dots{} @} + + # @r{Set up archivation}. + archive @var{type:@i{string}} @{ @dots{} @} - # Text of the notification or identifier of a defined message template - message @var{text-or-id:@i{}}; - @} + # @r{Configure notification}. + notify-event @{ @dots{} @} @} -# Service names that request scanning all spools -all-spools @var{arg:@i{}}; - @end smallexample @node invocation @chapter @command{Wydawca} invocation summary. @cindex invocation @cindex command line options -@UNREVISED This chapter presents a short reference of all @command{wydawca} command line options, in alphabetical order. @@ -2304,8 +2645,7 @@ file. @opsummary{cron} @opsummary{syslog} @item --cron -@itemx --syslog -Log all diagnostics to syslog. +Run in cron mode. @xref{starting,, cron}. @xref{stderr, The @option{--syslog} option}. @@ -2332,7 +2672,7 @@ Dump configuration grammar traces. This is useful for debugging Dump lexical analyzer traces. This is useful for debugging @command{wydawca} configuration file parser. -@opsummary{stderr} +@opsummary{dry-run} @item --dry-run @itemx -n @dfn{Dry-run mode}: do nothing, print almost everything. This option @@ -2345,6 +2685,22 @@ implies @option{--debug --stderr}. @itemx -e Log to the standard error. +@xref{stderr, The @option{--stderr} option}. + +@opsummary{spool} +@item --spool=@var{tag} +@itemx -S @var{tag} +Process only spool with the given tag. @xref{spool selection}. + +@item --source=@var{dir} +@itemx -s @var{dir} +Process only spool with @var{dir} as the source directory. +@xref{spool selection}. + +@opsummary{syslog} +@item --syslog +Log all diagnostics to syslog. + @xref{stderr, The @option{--syslog} option}. @opsummary{force} -- cgit v1.2.1