summaryrefslogtreecommitdiffabout
path: root/doc/wydawca.texi
authorSergey Poznyakoff <gray@gnu.org.ua>2009-02-26 15:39:08 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2009-02-26 15:39:08 (GMT)
commit514797c56e431f37de9a00834281f990a7b15c46 (patch) (side-by-side diff)
tree1f35e3b06d387e424f5a0d866390dccd34efd202 /doc/wydawca.texi
parent5b1f7f7213c1033211ce08307922e04044f872f4 (diff)
downloadwydawca-514797c56e431f37de9a00834281f990a7b15c46.tar.gz
wydawca-514797c56e431f37de9a00834281f990a7b15c46.tar.bz2
Minor fixes
Diffstat (limited to 'doc/wydawca.texi') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/wydawca.texi1035
1 files changed, 676 insertions, 359 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index ad274b2..589f2f7 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -31,7 +31,7 @@ Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA
-Copyright @copyright{} 2007 Sergey Poznyakoff
+Copyright @copyright{} 2007, 2009 Sergey Poznyakoff
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
@@ -59,13 +59,12 @@ Software Foundation raise funds for GNU development.''
@page
@contents
-@node Top, Intro, (dir), (dir)
-
-@ifinfo
-@chapter Wydawca
+@ifnottex
+@node Top
+@top Wydawca
This edition of the @cite{Wydawca Manual}, last updated @value{UPDATED},
documents Wydawca Version @value{VERSION}.
-@end ifinfo
+@end ifnottex
@menu
* Intro:: What is Wydawca
@@ -90,12 +89,11 @@ already listed, mentioned here so you can get to them in one step:
How to Configure @command{wydawca}.
-* include::
* syslog::
* sql::
* access methods::
* archivation::
-* directory pairs::
+* spool::
* statistics::
* notification::
@@ -109,7 +107,7 @@ Mail Notification
@end detailmenu
@end menu
-@node Intro, overview, Top, Top
+@node Intro
@chapter Introduction to Wydawca
@cindex introduction
Let's begin with a short synopsis. Suppose you run a developer's
@@ -150,21 +148,21 @@ signature @file{foo-1.0.tar.gz.sig}. Then he creates a special
@dfn{directive} file, that contains information about where the
distributed tarball must be placed, and clear-signs it using his
@acronym{PGP} key, thus obtaining file
-@file{foo-1.0.tar.gz.directive.asc}. Then he uploads these three files
+@file{foo-1.0.tar.gz.directive.asc}. Finally, he uploads these three files
(a @dfn{triplet}) to the upload site, storing them into the directory
@file{/incoming/ftp}.
@cindex release submission daemon
From now on, it is the responsibility of a @dfn{release submission daemon}
to scan the source directories, gather the triplets, verify them,
-and to move any files that had passed the verification successfully to
+and to move any files that had successfully passed verification to
their distribution sites.
@command{Wydawca} is such a release submission daemon. It is able to
-handle any number of @samp{source/destination} pairs, offers an
-extensible logging and mail notification mechanism, allowing both
-package maintainers and site administrators to be immediately notified
-about any occurring problems.
+handle any number of @samp{source/destination} pairs (called
+@dfn{spools}, offers an extensible logging and mail notification
+mechanism, allowing both package maintainers and site administrators
+to be immediately notified about any occurring problems.
@command{Wydawca} supports version 1.1 of directory file, as
described in
@@ -181,19 +179,20 @@ Standalone directives}.
The program is written entirely in @acronym{C}, is highly
effective and consumes little resources.
-@node overview, starting, Intro, Top
+@node overview
@chapter Operation Overview
@cindex operation
@cindex overview
Usually, @command{wydawca} is installed on the machine that receives
-release uploads and is run periodically as a cron-job. It supposes
-that both upload and distribution directories are accessible in the
-local file system hierarchy. If that is not the case (e.g. if upload
-and distribution sites are handled by different machines), one of them
-should be mounted using @acronym{NFS}. Future versions will contain
-special provisions for that case.
-
-@cindex directory pair
+release uploads. It may be run either periodically as a cron-job, or
+as a standalone daemon. It supposes that both upload and distribution
+directories are accessible in the local file system hierarchy. If that
+is not the case (e.g. if upload and distribution sites are handled by
+different machines), one of them should be mounted using
+@acronym{NFS}. Future versions will contain special provisions for
+that case.
+
+@cindex spool
@cindex upload directory
@cindex directory, upload
@cindex source directory
@@ -202,11 +201,11 @@ special provisions for that case.
@cindex directory, distribution
@cindex destination directory
@cindex directory, destination
- A configuration file supplies the utility with the set of
-@dfn{directory pairs}, i.e. pairs of upload and corresponding
-distribution directories. In @command{wydawca} terminology, upload
-directories are also called @dfn{source}, and distribution directories
--- @dfn{destination} directories. The file also supplies all the information
+ A configuration file defines a set of @dfn{spools}, i.e. pairs of
+upload and corresponding distribution directories. In
+@command{wydawca} terminology, upload directories are also called
+@dfn{source}, and distribution directories -- @dfn{destination}
+directories. The file also supplies all the information
necessary to access user and project databases.
When started, @command{wydawca} scans each source directory and
@@ -254,12 +253,13 @@ this stage of the processing, the uploaded files are actually moved to
their destination directories, requested symbolic links are created,
etc.
-@node starting, configuring, overview, Top
+@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
@@ -292,8 +292,7 @@ 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. Currently, its effect is
-the same as @option{--syslog}, but it may change in the future.
+@option{--cron} command line option anyway.
@anchor{debug}
@xopindex{debug, described}
@@ -334,179 +333,379 @@ $ wydawca -c new.cfg --dry-run
@option{--help} (@option{-h}) prints a short usage summary, and
@option{--version} (@option{-v}) prints program version number.
-@node configuring, wydawca.rc, starting, Top
+@node configuring
@chapter How to Configure @command{wydawca}.
-@UNREVISED
- The @command{wydawca} configuration file has a simple line-oriented
-syntax. Empty lines are ignored. Comments are introduced by a pound
-sign (@samp{#}): everything starting from the first occurrence of
-@samp{#} up to the end of line is ignored as well. Non-empty
-and non-comment lines must contain valid configuration statements.
-
- A @dfn{configuration statement} consists of a @dfn{command word}
-optionally followed by one or more @dfn{arguments}, separated by any
-amount of whitespace. There are @samp{simple} and @samp{compound}
-configuration statements. @dfn{Simple statements} occupy a single
-line, for example:
+ 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}).
+
+ 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
+@option{--lint} (@option{-t}) command line option. It causes
+@command{wydawca} to check configuration file for syntax errors and
+other inconsistencies and to exit with status 0 if no errors were
+detected, and withs status 1 otherwise.
+
+@opindex -E, introduced
+@xopindex{no-preprocessor, introduced}
+ Before parsing, configuration file is preprocessed using
+@command{m4} (@FIXME-pxref{Preprocessor}). To see the preprocessed
+configuration without actually parsing it, use @option{-E} command
+line option. To avoid preprocessing it, use
+@option{--no-preprocessor} option.
+
+@xopindex{config-help, introduced}
+ 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.
+* syslog::
+* sql::
+* access methods::
+* archivation::
+* spool::
+* statistics::
+* notification::
+@end menu
+
+@node Syntax
+@section Configuration file syntax
+
+ Wydawca configuration file consists of statements and comments.
+
+ There are three classes of lexical tokens: keywords, values, and
+separators. Blanks, tabs, newlines and comments, collectively called
+@dfn{white space} are ignored except as they serve to separate
+tokens. Some white space is required to separate otherwise adjacent
+keywords and values.
+
+@menu
+* Comments::
+* Pragmatic Comments::
+* Statements::
+@end menu
+
+@node Comments
+@subsection Comments
+@cindex Comments in a configuration file
+@cindex single-line comments
+ @dfn{Comments} may appear anywhere where white space may appear in the
+configuration file. There are two kinds of comments:
+single-line and multi-line comments. @dfn{Single-line} comments start
+with @samp{#} or @samp{//} and continue to the end of the line:
+
+@smallexample
+# This is a comment
+// This too is a comment
+@end smallexample
+
+@cindex multi-line comments
+ @dfn{Multi-line} or @dfn{C-style} comments start with the two
+characters @samp{/*} (slash, star) and continue until the first
+occurrence of @samp{*/} (star, slash).
+
+ Multi-line comments cannot be nested. However, single-line comments
+may well appear within multi-line ones.
+
+@node Pragmatic Comments
+@subsection Pragmatic Comments
+@cindex comments, pragmatic
+@cindex pragmatic comments
+ Pragmatic comments are similar to usual single-line comments,
+except that they cause some changes in the way the configuration is
+parsed. Pragmatic comments begin with a @samp{#} sign and end with the
+next physical newline character. Wydawca version @value{VERSION},
+understands the following pragmatic comments:
+
+@table @code
+@kwindex #include
+@item #include <@var{file}>
+@itemx #include @var{file}
+Include the contents of the file @var{file}. If @var{file} is an
+absolute file name, both forms are equivalent. Otherwise, the form
+with angle brackets searches for the file in the @dfn{include
+search path}, while the second one looks for it in the current working
+directory first, and, if not found there, in the include search
+path.
+
+The default include search path is:
+
+@enumerate 1
+@item @file{@var{prefix}/share/wydawca/@value{VERSION}/include}
+@item @file{@var{prefix}/share/wydawca/include}
+@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}).
+
+@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.
+
+@kwindex #line
+@item #line @var{num}
+@itemx #line @var{num} "@var{file}"
+ This line causes @command{wydawca} to believe, for purposes of error
+diagnostics, that the line number of the next source line is given by
+@var{num} and the current input file is named by @var{file}.
+If the latter is absent, the remembered file name does not change.
+
+@item # @var{num} "@var{file}"
+ This is a special form of @code{#line} statement, understood for
+compatibility with the @sc{c} preprocessor.
+@end table
+
+ In fact, these statements provide a rudimentary preprocessing
+features. For more sophisticated ways to modify configuration before
+parsing, see @FIXME-ref{Preprocessor}.
+
+@node Statements
+@subsection Statements
+@cindex statements, configuration file
+@cindex configuration file statements
+@cindex statement, simple
+@cindex simple statements
+ A @dfn{simple statement} consists of a keyword and value
+separated by any amount of whitespace. Simple statement is terminated
+with a semicolon (@samp{;}).
+
+ Examples of simple statements:
@smallexample
-syslog-print-priority yes
+daemon yes;
+pidfile /var/run/wydawca.pid;
@end smallexample
-If a simple statement is so long that it is inconvenient to keep it on
-a single line, it can be split over several lines by ending each line
-except the last one with a backslash character (@samp{\}). Notice,
-that the backslash character must immediately precede the terminating
-newline. For example, this is a single statement split over several lines:
+ A @dfn{keyword} begins with a letter and may contain letters,
+decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
+Examples of keywords are: @samp{group}, @samp{file-sweep-time}.
+
+ A @dfn{value} can be one of the following:
+
+@table @asis
+@item number
+ A number is a sequence of decimal digits.
+
+@item boolean
+@cindex boolean value
+ A boolean value is one of the following: @samp{yes}, @samp{true},
+@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no},
+@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}.
+
+@item unquoted string
+@cindex string, unquoted
+ An unquoted string may contain letters, digits, and any of the
+following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
+@samp{@@}, @samp{*}, @samp{:}.
+
+@item quoted string
+@cindex quoted string
+@cindex string, quoted
+@cindex escape sequence
+ A quoted string is any sequence of characters enclosed in
+double-quotes (@samp{"}). A backslash appearing within a quoted
+string introduces an @dfn{escape sequence}, which is replaced
+with a single character according to the following rules:
+
+@float Table, backslash-interpretation
+@caption{Backslash escapes}
+@multitable @columnfractions 0.30 .5
+@item Sequence @tab Replaced with
+@item \a @tab Audible bell character (@acronym{ASCII} 7)
+@item \b @tab Backspace character (@acronym{ASCII} 8)
+@item \f @tab Form-feed character (@acronym{ASCII} 12)
+@item \n @tab Newline character (@acronym{ASCII} 10)
+@item \r @tab Carriage return character (@acronym{ASCII} 13)
+@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
+@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
+@item \\ @tab A single backslash (@samp{\})
+@item \" @tab A double-quote.
+@end multitable
+@end float
+
+ In addition, the sequence @samp{\@var{newline}} is removed from
+the string. This allows to split long strings over several
+physical lines, e.g.:
@smallexample
@group
-user-data sql default SELECT realname, email \
- FROM user \
- WHERE user_name='%@{user@}'
+"a long string may be\
+ split over several lines"
@end group
@end smallexample
+ If the character following a backslash is not one of those specified
+above, the backslash is ignored and a warning is issued.
-A @dfn{compound statement} begins with a simple statement, occupies
-several lines, and ends with @code{end} statement, appearing on a line
-by itself. Within a compound statement any number of another
-statements (both simple and compound) may appear.
+ Two or more adjacent quoted strings are concatenated, which gives
+another way to split long strings over several lines to improve
+readability. The following fragment produces the same result as the
+example above:
-@cindex scope of a statement
-When a statement appears outside of any block statement, we say that
-it appears at @dfn{the top level} or @dfn{its scope is global}. When
-it appears within a block statement, we say that @dfn{it has block
-scope}.
+@smallexample
+@group
+"a long string may be"
+" split over several lines"
+@end group
+@end smallexample
- This subsection will guide you through the @command{wydawca}
-configuration on a step-by-step basis.
+@anchor{here-document}
+@item Here-document
+@cindex here-document
+ A @dfn{here-document} is a special construct that allows to introduce
+strings of text containing embedded newlines.
-@menu
-* include::
-* syslog::
-* sql::
-* access methods::
-* archivation::
-* directory pairs::
-* statistics::
-* notification::
-@end menu
+ The @code{<<@var{word}} construct instructs the parser to read all
+the following lines up to the line containing only @var{word}, with
+possible trailing blanks. Any lines thus read are concatenated
+together into a single string. For example:
-@node include
-@section Include Statement
-@cindex inclusion, configuration file
-@kwindex include
-@UNREVISED
-You can request inclusion of any file into your configuration file
-using @code{include} statement. Its only argument supplies the name of
-file to be included. For example:
+@smallexample
+@group
+<<EOT
+A multiline
+string
+EOT
+@end group
+@end smallexample
+
+ Body of a here-document is interpreted the same way as
+double-quoted string, unless @var{word} is preceded by a backslash
+(e.g. @samp{<<\EOT}) or enclosed in double-quotes, in which case
+the text is read as is, without interpretation of escape sequences.
+
+ If @var{word} is prefixed with @code{-} (a dash), then all leading
+tab characters are stripped from input lines and the line containing
+@var{word}. Furthermore, if @code{-} is followed by a single space,
+all leading whitespace is stripped from them. This allows to indent
+here-documents in a natural fashion. For example:
@smallexample
-include /etc/wydawca/msg
+@group
+<<- TEXT
+ All leading whitespace will be
+ ignored when reading these lines.
+TEXT
+@end group
@end smallexample
- The effect of the above statement is that the contents of file
-@file{/etc/wydawca/msg} is read and processed as if it were here,
-instead of the @code{include} statement.
-
- The include statement is especially useful if you wish to avoid
-keeping large static blocks of text in your configuration file, to
-make it more readable. An example of such large blocks of text are
-templates for notification messages (@pxref{notification}), which we
-suggest to keep in a separate file, and to include this file into the
-main configuration (this approach is used in the default configuration
-files).
-
-@cindex inclusion directory
-@cindex default inclusion directory
- The @code{include} argument may also be a relative
-file name (i.e. one not beginning with @samp{/}). In this case,
-@command{wydawca} will look for that file in its @dfn{inclusion
-directory}. By default, the inclusion directory is your system
-configuration directory. So, for example, in the default
-configuration, the following two statements are equivalent:
+ It is important that the terminating delimiter be the only token on
+its line. The only exception to this rule is allowed if a
+here-document appears as the last element of a statement. In this
+case a semicolon can be placed on the same line with its terminating
+delimiter, as in:
@smallexample
-include message/stat
-include /usr/local/etc/message/stat
+help-text <<-EOT
+ A sample help text.
+EOT;
@end smallexample
-@xopindex{include-directory, described}
-@sopindex{I, described}
- The value of the inclusion directory can be changed at run time,
-using the @option{--include-directory} (@option{-I}) command line
-option. This option takes an @emph{optional} argument, which means
-that if the argument is supplied, it must follow the short form of the
-option immediately, without any intervening whitespace, as in
-@option{-I/var/inc}. Similarly, when the long option form is used, the
-argument must be separated from it by a single equals sign, as in
-@option{--include-directory=/var/inc}.
-
- If an argument is given, this option instructs @command{wydawca} to
-use it as the new inclusion path. Otherwise, if argument is omitted,
-the include directory is defined as a directory part of the full
-file name of the configuration file. This form might be useful when
-debugging new configurations. For example, the following command
-runs @command{wydawca} in dry run mode, using configuration file
-@file{./test.rc}, and looking for include files in the current working
-directory:
+@item list
+@cindex list
+ A @dfn{list} is a comma-separated list of values. Lists are
+enclosed in parentheses. The following example shows a statement
+whose value is a list of strings:
@smallexample
-$ wydawca --config ./test.rc -I --dry-run
+alias (test,null);
@end smallexample
- Please notice, that unlike many other programs (e.g. @command{cc} or
-@command{make}), @command{wydawca} allows only one value of the
-inclusion directory: inclusion paths are not supported. If the command
-line contains several @option{-I} options, only the last of them takes
-effect.
+ In any case where a list is appropriate, a single value is allowed
+without being a member of a list: it is equivalent to a list with a
+single member. This means that, e.g.
+
+@smallexample
+alias test;
+@end smallexample
+
+@noindent
+is equivalent to
+
+@smallexample
+alias (test);
+@end smallexample
+@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,
+and a sequence of statements enclosed in curly braces, as shown in
+the example below:
+
+@smallexample
+@group
+spool download @{
+ source /home/ftp/incoming/ftp;
+ destination /home/ftp/pub;
+@}
+@end group
+@end smallexample
+ The closing curly brace may be followed by a semicolon, although
+this is not required.
+
@node syslog
@section Syslog Configuration Directives
@cindex syslog, configuration
-@kwindex syslog-facility
-@UNREVISED
+@kwindex syslog
+
Unless told otherwise, @command{wydawca} uses @code{syslog} to print
its diagnostic messages. By default, the program uses the
-@samp{local1} facility. To change this, use @code{syslog-facility}
-statement:
+@samp{local1} facility. The @code{syslog} statement allows to change that:
@smallexample
-syslog-facility local2
+syslog @{
+ facility local1;
+ tag wydawca;
+ print-priority yes;
+@}
@end smallexample
+@deffn {Configuration} facility @var{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}
- It takes a single argument, denoting the facility to use. Allowed
-values are: @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).
+ Configures the syslog facility to use. Allowed values are:
+@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
-@kwindex syslog-tag
+@deffn {Configuration} tag @var{string}
@cindex syslog tag, configuring
- Another thing you may wish to tune is the @dfn{syslog tag}, a string
-identifying each message issued by the program. By default it is a
-string @samp{wydawca}. To change it, use @code{syslog-tag} statement:
-
-@smallexample
-syslog-tag uploads
-@end smallexample
+ 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
-@kwindex syslog-print-priority
+@deffn {Configuration} print-priority @var{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
-syslog-print-priority yes
+print-priority yes;
@end smallexample
+@end deffn
@node sql
@section @acronym{SQL} Databases
@@ -514,9 +713,9 @@ syslog-print-priority yes
@cindex @acronym{SQL} databases
@cindex @command{MySQL} databases
@cindex database, @command{MySQL}
-@UNREVISED
-Several statements in configuration file may need to access
-@acronym{SQL} database. @command{Wydawca} can use any number of
+
+Several statements in configuration file may need to access an
+@acronym{SQL} database. @command{Wydawca} is able to use any number of
databases simultaneously, the only restriction being that they must be
@command{MySQL} databases (this restriction will be removed in future
releases).
@@ -527,52 +726,52 @@ following syntax:
@smallexample
@group
-sql @var{identifier}
- @var{statements}
-end
+sql @var{id} @{
+ host @var{hostname};
+ database @var{dbname};
+ user @var{username};
+ password @var{string};
+@}
@end group
@end smallexample
- Here, @var{identifier} is a string uniquely identifying this
+ Here, @var{id} is a string uniquely identifying this
database. It is used by another configuration statements (e.g. by
access methods, see the next section) to refer to this
-database. @var{statements} stand for a set of statements that
-determine access credentials for the database. Allowed statements are:
+database.
-@table @code
-@kwindex host
-@item host @var{hostname}[:@var{port-or-socket}]
+@deffn {Configuration} host @var{hostname}[:@var{port-or-socket}]
Set the hostname or @acronym{IP} address of the host running the
-database. The optional @var{port-or-socket} specifies port number (for
+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}.
@xref{sql-host}, for more information and examples.
+@end deffn
-@kwindex database
-@item database @var{name}
+@deffn {Configuration} database @var{name}
Specifies the database name.
+@end deffn
-@kwindex user
-@item user @var{name}
-Specifies the database user name.
+@deffn {Configuration} user @var{name}
+Sets the database user name.
+@end deffn
-@kwindex password
-@item password @var{string}
-Specifies the password for accessing the database.
-@end table
+@deffn {Configuration} password @var{string}
+Sets the password for accessing the database.
+@end deffn
@noindent
An example @code{sql} statement follows:
@smallexample
@group
-sql default
- host project.database.com:3306
- database savane
- user savane
- password guessme
-end
+sql default @{
+ host project.database.com:3306;
+ database savane;
+ user root;
+ password guessme;
+@}
@end group
@end smallexample
@@ -581,67 +780,84 @@ end
@cindex Access method
@cindex @acronym{PGP} key
@UNREVISED
-An @dfn{access method} defines how @command{wydawca} accesses some
-piece of information it needs while verifying the submission. This
-information can be, for example, the user's @acronym{PGP} key or his
-permissions on a project.
+An @dfn{access method} defines the ways to retrieve user information
+needed to verify the submission. This information can be, for example,
+the user's @acronym{PGP} key or his permissions on a project.
- @command{Wydawca} understands three types of access methods, only
-one of them being implemented right now. These methods are summarized
-in the table below:
+ Access methods are defined in configuration file using the
+following syntax:
+
+@smallexample
+access-method @var{method-name} @{
+ type @var{type};
+ query @var{string};
+ params (@var{param1},@var{param2},...);
+@}
+@end smallexample
+
+ Access method statements can appear either in the global scope of
+the configuration file, or inside a @code{spool} statement
+(@FIXME-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.
+
+There are four access methods, identified by the value of
+@var{method-name} tag:
+
+@table @asis
+@kwindex gpg-key
+@item gpg-key
+Retrieve the public @acronym{PGP} key of a user. This method must
+return exactly one string.
+
+@kwindex project-owner
+@item project-owner
+ Retrieve 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 user-data
+@item user-data
+ Return email address and real name of a user. This method must
+return one tuple, consisting of two columns: an email address and a user
+name, in this order.
+
+@kwindex verify-user
+@item verify-user
+ Verify if a user is allowed to make uploads for a certain project. This
+method must return the system name of the user if he is allowed to
+make uploads.
+@end table
+
+The sub-statements of @code{access-method} are:
+
+@deffn {Configuration} type @var{name}
+Defines the type of this method. @var{Name} is one of the following:
@table @asis
-@kwindex builtin@r{, access method type}
+@kwindex builtin
@item builtin
- This method is reserved for future use.
+ The data are supplied in the configuration file.
-@kwindex sql@r{, access method type}
+@kwindex sql
@item sql
Retrieve data from an @acronym{SQL} database. Currently only
@command{MySQL} is supported.
-@kwindex external@r{, access method type}
+@kwindex external
@item external
Retrieve data using an external program. This method is reserved for
future use.
@end table
- Access methods are defined in configuration file using the
-following syntax:
-
-@smallexample
-@var{method-name} @var{type} @var{param1} @var{param2}
-@end smallexample
-
-@noindent
-where @var{method-name} is the predefined name of the access method,
-@var{type} is its type and @var{param1} and @var{param2} are
-@dfn{parameters}, that describe the method.
-
- Access method statements can appear either in the global scope of
-the configuration file, or inside a @code{directory} statement
-(@pxref{directory pairs}). Global definitions affect all directory
-pairs in the configuration file, and ones inside a @code{directory}
-statement override them for that particular directory pair.
+See below for a detailed description of these access methods.
+@end deffn
- There are four predefined methods, which are described later in this
-section. The @var{type} must currently always be @samp{sql}. The
-@var{param1} is an identifier of one of the preceding @code{sql} blocks
-(@pxref{sql}), which determines database name and user
-credentials needed to access it. The @var{param2} is an @acronym{SQL}
-statement that must be issued to obtain the requested data. Before
-execution, this statement undergoes @dfn{variable expansion}, whereby
-each occurrence of @code{%@{@var{name}@}} is replaced with the value
-of meta-variable @var{name} (if @var{name} consists of a single
-letter, the curly braces may be omitted).
-
- For example, following are two valid uses of macro-variables:
-@code{%u} and @code{%@{user@}}, the first of them expands to the value
-of macro variable @samp{u}, and the second one expands to the value of
-the variable @samp{user}. Undefined variables are not expanded, but
-are left in the query intact.
-
- The variables defined for use in access methods are:
+@deffn {Configuration} query @var{string}
+Sets the query used for retrieving the data. The @var{string} is
+subject to meta-variable expansion (@FIXME-pxref{meta-variables}). The
+following meta-variables are defined:
@table @code
@kwindex u
@@ -659,85 +875,127 @@ submitted. It is defined as the value of directive
@code{directory}, or, in case this value contains slashes, the
shortest initial prefix of that value, not containing slashes.
@end table
+@end deffn
+
+@deffn {Configuration} params (@var{param1}, @var{param2}, ...)
+Supplies additional parameters for the method.
+@end deffn
+
+@menu
+* sql type::
+* builtin type::
+* external type::
+@end menu
+
+@node sql type
+@subsection SQL Access Methods
+@cindex sql access type
+Access methods having the type @samp{sql} retrieve information from an
+@acronym{SQL} database (as of version @value{VERSION}, only
+@samp{MySQL} databases are supported).
+
+The @code{query} statement supplies the @acronym{SQL} query to
+execute. Normally, it should be a @code{SELECT} query.
+
+The @code{params} statement must supply a single parameter --
+an identifier of one of the preceding @code{sql} blocks (@pxref{sql}),
+which determines database name and user credentials needed to access it.
@cindex Savane
- The rest of this section describes the access methods (referred to
-by @var{method-name} in the syntax above) used by
-@command{wydawca}. They are illustrated by example definitions, based
+ The following sub-nodes contain sample definitions of all four
+access methods using the @code{sql} type. They are based
on the database structure used in
@uref{http://gna.org/projects/savane, @command{Savane} system}.
-@deffn {Access Method} gpg-key
-@cindex @acronym{PGP} public key, retrieving
-@cindex public @acronym{PGP} key, retrieving
+@menu
+* gpg-key-sql::
+* project-owner-sql::
+* user-data-sql::
+* verify-user-sql::
+@end menu
+
+@node gpg-key-sql
+@subsubsection Gpg-key: an SQL Implementation
+@cindex gpg-key
Retrieve the public @acronym{PGP} key of a user. This method must
return exactly one string.
- The sample definition is:
-
@smallexample
-gpg-key sql default SELECT gpg_key \
- FROM user \
- WHERE user_name='%@{user@}'
+access-method gpg-key @{
+ type sql;
+ params (default);
+ query "SELECT gpg_key FROM user WHERE user_name='$@{user@}'";
+@}
@end smallexample
-@end deffn
-@deffn {Access Method} project-owner
+@node project-owner-sql
+@subsubsection Project-owner: an SQL Implementation
+@cindex project-owner
Retrieve 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.
@smallexample
-@group
-project-owner sql default 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 \
- AND user_group.admin_flags = 'A' \
- AND groups.unix_group_name='%@{project@}'
-@end group
+access-method project-owner @{
+ 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 "
+ "AND user_group.admin_flags = 'A' "
+ "AND groups.unix_group_name = '$@{project@}'";
+@}
@end smallexample
-@end deffn
-@deffn {Access Method} user-data
+@node user-data-sql
+@subsubsection User-data-sql: an SQL Implementation
+@cindex user-data
Return email address and real name of a user. This method must
return one tuple, consisting of two columns: an email address and a user
name, in this order.
@smallexample
-@group
-user-data sql default SELECT email, realname \
- FROM user \
- WHERE user_name='%@{user@}'
-@end group
+access-method user-data @{
+ type sql;
+ params (default);
+ query "SELECT email, realname FROM user WHERE user_name='$@{user@}'";
+@}
@end smallexample
-@end deffn
-@deffn {Access Method} verify-user
- Verify if a user is allowed to make uploads for a certain project. This
-method must return the system name of the user if he is allowed to
-make uploads.
-
- The following definition allows uploads only for project
-administrators:
+@node verify-user-sql
+@subsubsection Verify-user-sql: an SQL Implementation
+@cindex verify-user-sql
@smallexample
-@group
-verify-user sql default SELECT user.user_name \
- 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 groups.unix_group_name='%@{project@}' \
- AND user.user_name='%@{user@}'
-@end group
+access-method verify-user @{
+ type sql;
+ params (default);
+ query "SELECT user.user_name "
+ "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 groups.unix_group_name='$@{project@}' "
+ "AND user.user_name='$@{user@}'";
+@}
@end smallexample
-@end deffn
+
+@node builtin type
+@subsection Built-in access methods
+@cindex builtin access type
+@WRITEME
+
+@node external type
+@subsection External access methods
+@cindex external access type
+
+As of version @value{VERSION} this access type is not yet
+implemented.
@node archivation
@section Archivation
@cindex archivation, defined
-@UNREVISED
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,
@@ -752,11 +1010,18 @@ 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
-directory pairs, or within a @code{directory} block (@pxref{directory
-pairs}), where it affects only the given directory pair.
+spools, or within a @code{spool} block (@FIXME-pxref{spool}),
+where it affects only the given spool.
+
+@kwindex archive
+@smallexample
+archive @var{type} @{
+ name @var{file-or-dir};
+ backup @var{type};
+@}
+@end smallexample
- This statement takes several arguments. The first argument specifies
-the archivation type:
+ The @var{type} argument specifies the archivation type:
@table @asis
@kwindex none@r{, archivation}
@@ -765,18 +1030,25 @@ the archivation type:
@kwindex tar@r{, archivation}
@item tar
- Use @command{tar} archive.
+ Add to a @command{tar} archive.
@kwindex directory@r{, archivation}
@item directory
- Use a separate directory or a directory hierarchy.
+ Store file in a separate directory.
@end table
- When the archivation type @asis{tar} is used, the second argument to
-@code{archive} sets the full name of the tar archive to use, e.g.:
+@deffn {Configuration} name @var{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.:
@smallexample
-archive tar /var/spool/uploads/archive.tar
+archive tar @{
+ name /var/spool/uploads/archive.tar;
+@}
@end smallexample
The file being archived is appended to the archive using
@@ -791,14 +1063,16 @@ Files with the Same Name, Multiple Files with the Same Name, tar,
your search path. If you wish to use a particular binary, you may
specify its full file name using @code{tar-program} statement.
- The archivation type @samp{directory} means that archive copies will
-be stored in a directory specified by the second argument to
-@code{archive}. If it begins with a slash (i.e. represents an absolute
+ The @samp{directory} archivation type means that archive copies will
+be stored in a directory specified by the @code{name} statement.
+If it begins with a slash (i.e. represents an absolute
file name), an exact copy of the distribution directory hierarchy will
be created under it. For example, given this configuration:
@smallexample
-archive directory /var/backups/gnu
+archive directory @{
+ name /var/backups/gnu;
+@}
@end smallexample
@noindent
@@ -807,12 +1081,14 @@ all files from @file{/home/@/ftp/@/gnu/@/tar} will be archived in
@file{/home/@/ftp/@/gnu/@/tar/@/old}
will be archived in @file{/var/@/backups/@/gnu/@/tar/@/old}, etc.
- If the directory name does not begin with a slash, it will be located
-immediately under the corresponding distribution directory. Following
-our example, the following @code{directory} settings:
+ If the directory name does not begin with a slash, it will be created
+under the corresponding distribution directory. For example,
+the following archivation settings:
@smallexample
-archive directory .archive
+archive directory @{
+ name .archive;
+@}
@end smallexample
@noindent
@@ -821,14 +1097,15 @@ 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 {Configuration} backup @var{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. The third argument to @code{archive} specifies how to handle
-the existing copy, in other words, how to @dfn{backup} it. This
-argument corresponds to the Emacs variable @samp{version-control}, and
-it accepts the same values as in Emacs. The following table describes them:
+exists. This statement specifies how to handle the existing copy, in
+other words, how to @dfn{backup} it. The @var{type} argument
+corresponds to the @samp{version-control} Emacs variable. The
+following table describes its possible values:
@table @samp
@item t
@@ -852,21 +1129,18 @@ Always make simple backups.
@end table
-@vindex VERSION_CONTROL
- If no backup method is given, the value of the @env{VERSION_CONTROL}
-environment variable will be used. And if @env{VERSION_CONTROL} is
-not set, the @samp{existing} is used by default.
+ If no backup method is given, @samp{existing} is assumed
+@end deffn
@cindex implicit signature archivation
@cindex signature files, archivation
- Usually signature files (i.e. the ones ending with @samp{.sig}) should
-be located in the same directory as the files they belong to. To
-enforce this rule, @command{wydawca} implements
-@dfn{implicit signature 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}),
+ Signature files (i.e. the ones ending with @samp{.sig}) are usually
+located in the same directory as the files they sign. To enforce this
+rule, @command{wydawca} implements @dfn{implicit signature
+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}}.
@@ -875,74 +1149,118 @@ exists. If so, it is archived along with @file{@var{file}}.
the @code{archive-signatures} statement to disable it, e.g.:
@smallexample
-archive-signatures no
+archive-signatures no;
@end smallexample
-@node directory pairs
-@section directory pairs
-@cindex directory pair
-@kwindex directory
+@node spool
+@section Distribution Spool
+@cindex distribution spool
+@kwindex spool
@cindex defining source and distribution directories
@cindex distribution directory, defining
@cindex source directory, defining
@kwindex source
@kwindex destination
@UNREVISED
-A @dfn{directory pair} definition is a core of @command{wydawca}
-configuration. It defines the location of the source directory and the
-corresponding distribution (or @dfn{destination}) directory. It may
-also set the archivation type being used for that directory and
-various access methods, thus overriding the global settings. The
-directory pair definition begins with the @code{directory} keyword,
-optionally followed by the @acronym{URL} of the distribution
-directory. This @acronym{URL}, if specified, is used in diagnostic
-messages regarding this directory pair. Following the @code{directory}
-keyword is a list of statements describing the pair. At least two
-statements are required: @code{source}, specifying location of the
-source directory and @code{destination}, which specifies location of
-the destination directory. Apart from these obligatory statements, a
-@code{directory} block may contain an @code{archive} statement
-(@pxref{archivation}) and access method definitions (@pxref{access
-methods}). Any of these statements, if present, overrides the
-corresponding global definition for this directory pair. A
-@code{directory} statement ends with the @code{end} keyword on a
-separate line.
+A @dfn{distribution spool} defines the location of the source directory
+and the corresponding distribution (or @dfn{destination})
+directory. It may also set the archivation type being used for that
+directory, various access methods and notifications, thus overriding
+global settings.
+
+Distribution spool is defined in the configuration file by the
+@code{spool} block statement:
+
+@smallexample
+spool @var{tag} @{
+ url @var{url};
+ alias (@var{aliases});
+ source @var{dir};
+ destination @var{dir};
+ file-sweep-time @var{interval};
+ access-method @dots{}
+ archive @dots{}
+ notify-event @dots{}
+@}
+@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
+meta-substitutions (@FIXME-pxref{meta-variables, spool}).
+
+@deffn {Configuration} url @var{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 {Configuration} source @var{dir}
+Specifies the location of the source directory.
+@end deffn
+
+@deffn {Configuration} destination @var{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:
+
+@table @asis
+@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
+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
+
+ The @code{source} and @code{destination} statements are mandatory.
+
+ A @code{spool} block may also contain an @code{archive} statement
+(@pxref{archivation}), access method definitions (@pxref{access
+methods}) and notification statements (@pxref{notification}). Any of
+these statements, if present, override corresponding global definition
+for this spool.
For example, the following definition says that valid uploads to
@file{/home/ftp/incoming/ftp} should be transferred to @file{/home/ftp/gnu}:
@smallexample
@group
-directory ftp://ftp.gnu.org.ua
- source /home/ftp/incoming/ftp
- destination /home/ftp/gnu
-end
+spool ftp @{
+ url ftp://ftp.gnu.org.ua;
+ source /home/ftp/incoming/ftp;
+ destination /home/ftp/gnu;
+@}
@end group
@end smallexample
@noindent
-This directory pair will be using the archivation type and access methods
-defined globally.
+This spool defines no particular archivation type, access method or
+notifications, so it will inherit these settings from the global
+configuration.
- The following example shows the same directory pair block, that
-additionally sets its own archivation method:
+ The following example shows the same spool, that additionally sets
+its own archivation method:
@smallexample
@group
-directory ftp://ftp.gnu.org.ua
- source /home/ftp/incoming/ftp
- destination /home/ftp/gnu
- archive directory .archive
-end
+spool ftp @{
+ url ftp://ftp.gnu.org.ua;
+ source /home/ftp/incoming/ftp;
+ destination /home/ftp/gnu;
+ archive directory @{
+ name .archive;
+ backup numbered;
+ @}
+@}
@end group
@end smallexample
- The distribution directory is implicitly supposed to be located on
-the same machine as the upload directory. If they are located on
-different machines, one of the directories should be mounted using
-@acronym{NFS}. Future @command{wydawca} versions will contain special
-provisions for such case.
-
@node statistics
@section Statistics
@cindex statistics
@@ -1495,7 +1813,7 @@ end
notify-event success user user-success
@end smallexample
-@node wydawca.rc, invocation, configuring, Top
+@node wydawca.rc
@chapter @command{Wydawca} configuration file.
@cindex configuration statements, reference
@UNREVISED
@@ -1756,7 +2074,7 @@ defining source and distribution directories, and @var{statements} are
any optional archive and/or access method definitions, overriding the
global ones for this directory pair.
-@xref{directory pairs}, for more information.
+@xref{spool}, for more information.
The following statements must be present in a @code{directory} block:
@@ -1844,7 +2162,7 @@ Sets the mailer @acronym{URL} to use.
@xref{mailer}, for more information on mailers.
@end deffn
-@node invocation, Reporting Bugs, wydawca.rc, Top
+@node invocation
@chapter @command{Wydawca} invocation summary.
@cindex invocation
@cindex command line options
@@ -1892,13 +2210,11 @@ implies @option{--debug --stderr}.
@xref{dry-run, The dry-run mode}.
@opsummary{include-directory}
-@item --include-directory[=@var{dir}]
+@item --include-directory=@var{dir}
@itemx -I[@var{dir}]
-If @var{dir} is supplied it is set as the current inclusion
-directory. Otherwise, the inclusion directory is set to the directory
-part of the configuration file used.
+Add @var{dir} to include search path.
-@xref{include, File inclusion}.
+@FIXME-xref{include, File inclusion}.
@opsummary{lint}
@item --lint
@@ -1919,7 +2235,7 @@ Print a concise usage summary and exit.
Print the program version and exit.
@end table
-@node Reporting Bugs, Copying This Manual, invocation, Top
+@node Reporting Bugs
@chapter How to Report a Bug
Email bug reports to @email{bug-wydawca@@gnu.org.ua}.
@@ -1937,10 +2253,11 @@ file along with your bug report. This file is created after running
@command{./configure} in @command{wydawca} source root directory.
@end itemize
-@node Copying This Manual, Concept Index, Reporting Bugs, Top
+@node Copying This Manual
+@appendix GNU Free Documentation License
@include fdl.texi
-@node Concept Index, , Copying This Manual, Top
+@node Concept Index
@comment node-name, next, previous, up
@unnumbered Concept Index

Return to:

Send suggestions and report system problems to the System administrator.