aboutsummaryrefslogtreecommitdiff
path: root/doc/wydawca.texi
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-22 14:16:19 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-22 14:16:19 +0200
commit18fee8d03201211170f2b8579921ce9da7c5a78b (patch)
treea799f907cb55a310b0c5dd8f2bad3f2dbde4ab2e /doc/wydawca.texi
parent6f49d439216e3067d3f2994221edb8ea16e2c74e (diff)
downloadwydawca-18fee8d03201211170f2b8579921ce9da7c5a78b.tar.gz
wydawca-18fee8d03201211170f2b8579921ce9da7c5a78b.tar.bz2
Finish documentation
* doc/Makefile.am (manual.tar.bz2) (man-tar): New rules. * doc/gendocs_template: Rewrite. * doc/wydawca.texi: Update. * doc/Config: New file.
Diffstat (limited to 'doc/wydawca.texi')
-rw-r--r--doc/wydawca.texi374
1 files changed, 263 insertions, 111 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 201b960..da58e41 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -87,9 +87,18 @@ already listed, mentioned here so you can get to them in one step:
@detailmenu
--- The Detailed Node Listing ---
+Operation Overview
+
+* operation modes::
+
How to Configure @command{wydawca}.
* Syntax:: Configuration file syntax.
+* general::
+* user privileges::
+* daemon::
+* tcp-wrapper::
+* locking::
* syslog::
* sql::
* dictionaries::
@@ -152,7 +161,7 @@ The following is a short summary of it: there is an @acronym{FTP}
@dfn{upload site}, which has two @dfn{source directories}, each one
corresponding to a certain distribution @acronym{URL}. For example,
-@multitable @columnfractions 0.4 0.4
+@multitable @columnfractions 0.4 0.6
@headitem Source Directory @tab Distribution Site
@item @file{/incoming/ftp} @tab @indicateurl{ftp.gnu.org}
@item @file{/incoming/alpha} @tab @indicateurl{alpha.gnu.org}
@@ -304,23 +313,23 @@ 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
+the controlling 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
+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
+@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
+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
+did the upload. The following sample transaction illustrates
this:
@smallexample
@@ -378,7 +387,7 @@ 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
+spools. You may instruct it to process only a subset of these
by using the following options:
@table @option
@@ -791,7 +800,7 @@ alias (test);
@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
+or more pairs @samp{number}-@samp{time unit}. For example, the
following are valid interval specifications:
@smallexample
@@ -804,7 +813,7 @@ following are valid interval specifications:
@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
+human ear, e.g. @samp{2 days 1 year}. If the @samp{time unit} is
omitted, seconds are supposed.
@end table
@@ -895,13 +904,13 @@ Use @var{command} instead of the default preprocessor.
@section General Settings
@deffn {Config} foreground bool
-If @var{bool} is @samp{yes}, run in foreground. @xref{invocation,
+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.
+spawns subprocesses 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
@@ -921,7 +930,7 @@ This parameter may also be set for each spool
individually. @xref{spool, file-sweep-time}.
@end deffn
-@acronym{gpg-homedir}
+@anchor{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,
@@ -950,14 +959,15 @@ group (nogroup, ftp);
@node daemon
@section Daemon Configuration
-@UNREVISED
+
+ Statements in this section configure the daemon mode.
@deffn {Config} daemon bool
Enable daemon mode.
@end deffn
@deffn {Config} listen url
-Define a socket to listen on. Allowed values for @var{url}
+Define a socket to listen on. Allowed values for @var{url}
are:
@table @asis
@@ -994,7 +1004,6 @@ statement (@pxref{general, file-sweep-time}).
@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
@@ -1055,7 +1064,11 @@ and @samp{deny-syslog-priority} statements are: @samp{emerg},
@node locking
@section Locking Configuration
-@UNREVISED
+ To avoid a possibility of two @command{wydawca} instances handling
+the same triplet, @command{wydawca} @dfn{locks} the spool before
+processing it. This is done by creating a @dfn{lock file}. The
+parameters of the locking subsystem are configured via the
+@code{locking} statement:
@deffn {Config} locking @{ @dots{} @}
@smallexample
@@ -1069,12 +1082,15 @@ locking @{
@end deffn
@deffn {Config: locking} enable bool
-Enable or disable locking.
+Enable or disable locking. By default it is enabled.
@end deffn
@deffn {Config: locking} directory dir
-Sets directory for lock files. The default is
-@file{@var{localstatedir}/@/lock/@/wydawca}.
+Sets directory for lock files. Make sure @var{dir} is writable
+for the user (or group) @command{wydawca} runs at (@pxref{user
+privileges}.
+
+The default directory is @file{@var{localstatedir}/@/lock/@/wydawca}.
@end deffn
@deffn {Config: locking} expire-time time
@@ -1085,7 +1101,10 @@ older than @var{time} is considered stale and removed.
@end deffn
@deffn {Config: locking} timeout time
-Timeout for acquring locks.
+Timeout for acquiring locks. If a lock file cannot be acquired during
+this time, @command{wydawca} reports error and exits.
+
+@xref{time interval specification}, for the syntax of @var{time}.
@end deffn
@node syslog
@@ -1179,7 +1198,6 @@ 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 name
@@ -1281,6 +1299,7 @@ reserved for future use.
See below for a detailed description of these dictionary types.
@end deffn
+@anchor{query}
@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
@@ -1381,7 +1400,10 @@ dictionary project-owner @{
@node project-uploader-sql
@subsubsection Project-uploader: an SQL Implementation
@cindex project-uploader-sql
-@UNREVISED
+
+ This dictionary assumes that the @samp{user} table has a special
+column, @samp{upload_flags}, whose value is @samp{Y} for those users
+who can do uploads for this project:
@smallexample
dictionary project-uploader @{
@@ -1391,7 +1413,7 @@ dictionary project-uploader @{
"FROM user,user_group,groups "
"WHERE user_group.user_id=user.user_id "
"AND user_group.group_id=groups.group_id "
- "AND user_group.admin_flags = 'A' "
+ "AND user_group.upload_flags = 'Y' "
"AND groups.unix_group_name = '$@{project@}'";
@}
@end smallexample
@@ -1399,7 +1421,110 @@ dictionary project-uploader @{
@node builtin type
@subsection Built-in Dictionary
@cindex builtin dictionary
-@WRITEME
+
+ @dfn{Builtin dictionaries} are small dictionaries that keep all data
+in their @code{params} list. They are designed mainly for testing
+purposes.
+
+ Look ups in builtin dictionaries are performed as follows:
+The @code{query} value is expanded (@pxref{query}). The resulting
+value is used as a @dfn{key} for lookup in @code{params} list.
+The list scanned as follows:
+
+@enumerate 1
+@item INIT
+
+Let @var{i} be the index of the current element in @code{params}.
+Set @var{i} to 0.
+
+@item GETEL
+
+Get the @var{i}th element.
+
+@item
+
+If it begins with a slash, interpret it as @dfn{comparison type
+indicator}. Its possible values are:
+
+@table @asis
+@item /exact
+Exact comparison. The key must be exactly equivalent to the
+dictionary field.
+
+@item /fnmatch
+Dictionary field is treated as an @dfn{fnmatch globbing
+pattern}. @xref{globbing pattern,,,glob(7),glob man page}.
+
+@item /regex
+Dictionary field is treated as a regular expression.
+Unless configured otherwise by flags (see below), @acronym{POSIX}
+extended regular expressions are used (@pxref{Extended
+regexps, Extended regular expressions, Extended regular expressions,
+sed, GNU sed}).
+@end table
+
+If that word ends with a comma, the characters following it
+are @dfn{flags}, defining the type of matching. Allowed flags
+are:
+
+@multitable @columnfractions 0.2 0.8
+@headitem Flag @tab Meaning
+@item i @tab Ignore case
+@item b @tab Use basic regular expressions
+@end multitable
+
+ For example, the string @samp{/exact,i} specifies case-insensitive
+exact comparison, the string @samp{/regex,bi} specifies
+case-insensitive basic regular expression matching, etc.
+
+ Go to step @samp{INCR}.
+
+@item COMP
+
+Compare the element with the key, using currently selected comparison
+method.
+
+@item
+
+If the element matches the key, add elements @code{@var{i}+1}
+through @code{@var{i}+@var{n}} to the result set. The value for
+@var{n} is selected as follows:
+
+@multitable @columnfractions 0.8 0.2
+@headitem Dictionary @tab @var{n}
+@item project-owner @tab 2
+@item project-uploader @tab 4
+@end multitable
+
+@item
+
+Set @code{@var{i} = @var{i} + @var{n}}
+
+@item INCR
+
+Set @code{@var{i} = @var{i} + 1}.
+
+@item LOOP
+
+If @var{i} is greater than the number of elements in @code{param},
+then stop. Otherwise, go to step @samp{GETEL}.
+@end enumerate
+
+ For example, the following defines the @samp{project-owner}
+dictionary, containing data for projects @samp{foo} and @samp{bar}:
+
+@smallexample
+@group
+dictionary project-owner @{
+ type builtin;
+ query "$@{project@}";
+ params ("/exact",
+ "foo", "foo-owner@@domain.net", "Foo Admin",
+ "bar", "smith@@other.net", "John Smith");
+@}
+@end group
+@end smallexample
+
@node external type
@subsection External Dictionary
@@ -1413,7 +1538,7 @@ implemented.
@cindex archivation, defined
There may be cases when project maintainers need to overwrite
existing distributed files with another ones, having the same names.
-(Note, hovewer, that this practice is not encouraged). In that case,
+(Note, however, that this practice is not encouraged). In that case,
@command{wydawca} needs to first @dfn{archive} the already existing
file, and then put the new one in its place. Moreover, the directive
file format allows maintainers to explicitly require archivation of
@@ -1599,7 +1724,7 @@ spool @var{tag} @{
@end smallexample
The @var{tag} argument defines a unique identifier for this spool. It
-will be used in log messages, timers (@FIXME-pxref{timers}) and in
+will be used in log messages, timers (@pxref{spool-timers}) and in
meta-variable interpretation (@pxref{meta-interpretation}).
@end deffn
@@ -2079,7 +2204,7 @@ statistics (stat-msg, errors, access-violations, bad-signatures);
@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 supplied @acronym{GPG} @var{key}. The key is looked up in
the @acronym{GPG} home directory (@pxref{gpg-homedir}).
@end deffn
@@ -2089,7 +2214,7 @@ The statistics message is sent to addresses configured by
@cindex meta-variables in admin notifications
The meta-variables available for use in statistics reports are:
-@multitable @columnfractions 0.50 0.50
+@multitable @columnfractions 0.30 0.70
@headitem Variable @tab Replaced with
@kwindex date
@item date @tab Current date and time in the current locale.
@@ -2124,7 +2249,32 @@ triplets.
@item stat:rmsymlinks @tab Number of symbolic links removed.
@end multitable
-@FIXME{timers: @code{timer:@var{id}:user} }
+@anchor{spool-timers}
+@cindex timers
+ The following special variables, called @dfn{timers}, are
+replaced with the real or @acronym{CPU} time (in seconds)
+used while processing a certain task:
+
+@multitable @columnfractions 0.30 0.70
+@kwindex timer:wydawca:real
+@item timer:wydawca:real @tab Real time spent in @command{wydawca}
+main code.
+@kwindex timer:wydawca:system
+@item timer:wydawca:system @tab System @acronym{CPU} time spent in
+@command{wydawca} main code.
+@kwindex timer:wydawca:user
+@item timer:wydawca:user @tab User @acronym{CPU} time spent in
+@command{wydawca} main code.
+@kwindex timer:@var{tag}:real
+@item timer:@var{tag}:real @tab Real time spent processing the
+@var{tag} spool.
+@kwindex timer:@var{tag}:system
+@item timer:@var{tag}:system @tab System @acronym{CPU} time spent
+processing the @var{tag} spool.
+@kwindex timer:@var{tag}:user
+@item timer:@var{tag}:user @tab User @acronym{CPU} time spent
+processing the @var{tag} spool.
+@end multitable
An example definition of the admin notification template follows:
@@ -2135,16 +2285,31 @@ mail-statistics @{
message <<EOT
Subject: Wydawca stats
-This is to notify you that my run on %@{date@}
+This is to notify you that my run on $@{date@}
caused the following results:
-errors ............................. %@{stat:errors@}
-warning ............................ %@{stat:warnings@}
-bad signatures ..................... %@{stat:bad_signatures@}
-access violation attempts .......... %@{stat:access_violations@}
+errors ............................. $@{stat:errors@}
+warning ............................ $@{stat:warnings@}
+bad signatures ..................... $@{stat:bad_signatures@}
+access violation attempts .......... $@{stat:access_violations@}
+
+Timings:
+Real ............................... $@{timer:wydawca:real@} \
+($@{timer:releases:real@} + \
+$@{timer:alpha:real@} + \
+$@{timer:test:real@})
+System ............................. $@{timer:wydawca:system@} \
+($@{timer:releases:system@} + \
+$@{timer:alpha:system@} + \
+$@{timer:test:system@})
+User ............................... $@{timer:wydawca:user@} \
+($@{timer:releases:user@} + \
+$@{timer:alpha:user@} + \
+$@{timer:test:user@})
Regards,
Wydawca
+EOT;
@}
@end smallexample
@@ -2232,7 +2397,7 @@ template, or a reference to a template previously defined by a
@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 supplied @acronym{GPG} @var{key}. The key is looked up in
the @acronym{GPG} home directory (@pxref{gpg-homedir}).
@end deffn
@@ -2258,100 +2423,87 @@ notify-event @{
The following macro-variables may be used in templates for these
notifications:
-@table @code
+@multitable @columnfractions 0.30 0.70
+@headitem Variable @tab Replaced with
@kwindex project
-@item project
-Project system name.
-
+@item project @tab Project system name.
@kwindex url
-@item url
-@acronym{URL} of the distribution site.
-
+@item url @tab @acronym{URL} of the distribution site.
@kwindex spool
-@item spool
-Name of the spool (@pxref{spool}).
-
+@item spool @tab Name of the spool (@pxref{spool}).
@kwindex dir
-@item dir
-Directory (relative to the project distribution root) where the
-files where uploaded.
-
+@item dir @tab Directory (relative to the project distribution
+root) where the files where uploaded.
@kwindex dest-dir
-@item dest-dir
-Value of the @code{destination} keyword.
-
+@item dest-dir @tab Value of the @code{destination} keyword.
@kwindex source-dir
-@item source-dir
-Value of the @code{source} keyword.
-
+@item source-dir @tab Value of the @code{source} keyword.
@kwindex triplet:full
-@item triplet:full
-A full listing of the uploaded triplet. It is equivalent to:
-
+@item triplet:full @tab A full listing of the uploaded
+triplet@footnote{It is equivalent to:
@smallexample
@group
-%@{triplet:dist@}
-%@{triplet:sig@}
-%@{triplet:dir@}
+$@{triplet:dist@}
+$@{triplet:sig@}
+$@{triplet:dir@}
@end group
@end smallexample
-
-See below for an example.
-
+}.
@kwindex triplet:upload
-@item triplet:upload
-Listing of the uploaded files (see below).
-
+@item triplet:upload @tab Listing of the uploaded files (see below).
@kwindex triplet:dist
-@item triplet:dist
-Listing of the main distribution file (see below).
-
+@item triplet:dist @tab Listing of the main distribution file (see below).
@kwindex triplet:sig
-@item triplet:sig
-Listing of the detached signature file (see below).
-
+@item triplet:sig @tab Listing of the detached signature file (see below).
@kwindex triplet:dir
-@item triplet:dir
-Listing of the directive file (see below).
-
-@kwindex user
+@item triplet:dir @tab Listing of the directive file (see below).
+@kwindex user
+@item user @tab System name of the user who uploaded the triplet.
@kwindex user:name
-@item user
-@itemx user:name
-System name of the user who uploaded the triplet.
-
+@item user:name @tab System name of the user who uploaded the triplet.
@kwindex user:real-name
-@item user:real-name
-Real name of the user who uploaded the triplet.
-
+@item user:real-name @tab Real name of the user who uploaded the triplet.
@kwindex user:email
-@item user:email
-Email of the user who uploaded the triplet.
-
-@item timer:wydawca:real
-@FIXME
-@item timer:wydawca:system
-@FIXME
-@item timer:wydawca:user
-@FIXME
-@item timer:triplet:real
-@FIXME
-@item timer:triplet:system
-@FIXME
-@item tumer:triplet:user
-@FIXME
-@item timer:spool:real
-@FIXME
-@item timer:spool:system
-@FIXME
-@item tumer:spool:user
-@FIXME
-@end table
+@item user:email @tab Email of the user who uploaded the triplet.
+@end multitable
+
+@cindex timers
+ The following @dfn{timers} (@pxref{spool-timers}) are defined:
+
+@multitable @columnfractions 0.30 0.70
+@headitem Variable @tab Replaced with
+@kwindex timer:wydawca:real
+@item timer:wydawca:real @tab Real time spent in @command{wydawca}
+main code.
+@kwindex timer:wydawca:system
+@item timer:wydawca:system @tab System @acronym{CPU} time spent in
+@command{wydawca} main code.
+@kwindex timer:wydawca:user
+@item timer:wydawca:user @tab User @acronym{CPU} time spent in
+@command{wydawca} main code.
+@kwindex timer:triplet:real
+@item timer:triplet:real @tab Real time spent processing this triplet.
+@kwindex timer:triplet:system
+@item timer:triplet:system @tab System @acronym{CPU} time spent
+processing this triplet.
+@kwindex timer:triplet:user
+@item timer:triplet:user @tab User @acronym{CPU} time spent
+processing this triplet.
+@kwindex timer:spool:real
+@item timer:spool:real @tab Real time spent while processing this
+spool.
+@kwindex timer:spool:system
+@item timer:spool:system @tab System @acronym{CPU} time spent while
+processing this spool.
+@kwindex timer:spool:user
+@item timer:spool:user @tab User @acronym{CPU} time spent while
+processing this spool.
+@end multitable
@dfn{Listings} referred to in the table above, are similar to those
produced by @code{ls} command, and include information
on file permissions, ownership, size and modification date. For
-example, here is a possible @code{%@{triplet:full@}} listing:
+example, here is a possible @code{$@{triplet:full@}} listing:
@smallexample
-rw-r--r-- gray users 2707278 2007-09-06 22:14:35 tar-1.18.tar.gz
@@ -2389,7 +2541,7 @@ EOT;
@node wydawca.rc
@chapter @command{Wydawca} configuration file.
@cindex configuration statements, reference
- This chapter summarizes the configuration statements. For each
+ This chapter summarizes the configuration statements. For each
statement, a reference to its detailed description is provided.
@smallexample
@@ -2645,7 +2797,7 @@ file.
@opsummary{cron}
@opsummary{syslog}
@item --cron
-Run in cron mode. @xref{starting,, cron}.
+Run in cron mode. @xref{starting,, cron}.
@xref{stderr, The @option{--syslog} option}.
@@ -2690,7 +2842,7 @@ Log to the standard error.
@opsummary{spool}
@item --spool=@var{tag}
@itemx -S @var{tag}
-Process only spool with the given tag. @xref{spool selection}.
+Process only spool with the given tag. @xref{spool selection}.
@item --source=@var{dir}
@itemx -s @var{dir}
@@ -2705,7 +2857,7 @@ Log all diagnostics to syslog.
@opsummary{force}
@item --force
-Force start-up, even if if the pid file already exists.
+Force start-up, even if if the PID file already exists.
@opsummary{foreground}
@item --foreground

Return to:

Send suggestions and report system problems to the System administrator.