Wydawca
1 Introduction to Wydawca
2 Operation Overview
3 How to invoke 'wydawca'.
4 How to Configure 'wydawca'.
5 'Wydawca' configuration file.
6 'Wydawca' invocation summary.
7 How to Report a Bug
Appendix A Architecture of the Wydawca
Appendix B GNU Free Documentation License
Concept Index
Wydawca
1 Introduction to Wydawca
2 Operation Overview
2.1 Operation Modes
3 How to invoke 'wydawca'.
4 How to Configure 'wydawca'.
4.1 Configuration file syntax
4.1.1 Comments
4.1.2 Pragmatic Comments
4.1.3 Statements
4.1.4 Preprocessor
4.2 General Settings
4.3 Upload Directive Versions
4.4 User Privileges
4.5 Daemon Configuration
4.6 TCP Wrappers
4.7 Syslog Configuration Directives
4.8 SQL Databases
4.9 Dictionaries
4.9.1 SQL Dictionary
4.9.1.1 Project-owner: an SQL Implementation
4.9.1.2 Project-uploader: an SQL Implementation
4.9.2 Built-in Dictionary
4.9.3 External Dictionary
4.10 Directory Setup
4.11 Archivation
4.12 Distribution Spool
4.13 Distribution Verification
4.14 Statistics
4.15 Notification Mechanism
4.15.1 modules
4.15.2 Event Notification
4.15.3 'mod_mailutils'- Mail Notification
4.15.3.1 Mailer
4.15.3.2 Message Templates
4.15.3.3 Statistic Reports
4.15.3.4 'module-config' for 'mod_mailutils'
4.15.3.5 Example of mod_mailutils configuration
4.15.4 'mod_logstat' - statistics logging
5 'Wydawca' configuration file.
6 'Wydawca' invocation summary.
7 How to Report a Bug
Appendix A Architecture of the Wydawca
Event timestamps in WY_stat
Appendix B GNU Free Documentation License
B.1 ADDENDUM: How to use this License for your documents
Concept Index
Wydawca
*******
This edition of the 'Wydawca Manual', last updated 6 January 2021,
documents Wydawca Version 4.0.3.
1 Introduction to Wydawca
*************************
Let's begin with a short synopsis. Suppose you run a developer's site,
such as e.g. 'gnu.org'. You have two "distribution URLs":
'ftp.gnu.org', which distributes stable versions of the software, and
'alpha.gnu.org', which distributes alpha and pre-test versions. Package
maintainers need a way of uploading their packages to one of these
sites. This is done using the "Automated FTP Upload" method described
in *note Automated FTP Uploads: (maintain)Automated FTP Uploads. The
following is a short summary of it: there is an FTP "upload site", which
has two "source directories", each one corresponding to a certain
distribution URL. For example,
Source Directory Distribution Site
--------------------------------------------------------------------------
'/incoming/ftp' 'ftp.gnu.org'
'/incoming/alpha' 'alpha.gnu.org'
If maintainer of the project 'foo' wishes to make a release of the
stable version 'foo-1.0.tar.gz', he first creates a detached signature
'foo-1.0.tar.gz.sig'. Then he creates a special "directive" file, which
contains information about where the distributed tarball must be placed,
and clear-signs it using his PGP key, thus obtaining the file
'foo-1.0.tar.gz.directive.asc'. Finally, he uploads these three files
(a "triplet") to the upload site, storing them into the directory
'/incoming/ftp'.
From now on, it is the responsibility of a "release submission
daemon" to scan source directories, gather triplets, verify them, and to
move any files that had successfully passed verification to their
distribution sites.
'Wydawca' is such a release submission daemon. It is able to handle
any number of 'source/destination' pairs (called "spools") in real time,
and offers extensible logging and notification mechanisms, allowing both
package maintainers and site administrators to be immediately notified
about any occurring problems.
'Wydawca' supports upload directive versions 1.1(1) and 1.2(2).
The program is written entirely in C, is highly effective and
consumes little resources.
---------- Footnotes ----------
(1) See Standalone directives
(http://www.gnu.org/prep/maintain/html_node/FTP-Upload-Directive-File-_002d-v1_002e1.html).
(2) See Standalone directives
(http://www.gnu.org/prep/maintain/html_node/FTP-Upload-Directive-File-_002d-v1_002e2.html).
2 Operation Overview
********************
Usually, 'wydawca' is installed on the machine that receives 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 NFS. Future
versions will contain special provisions for that case.
A configuration file defines a set of "spools", i.e. pairs of upload
and corresponding distribution directories. In 'wydawca' terminology,
upload directories are also called "source", and distribution
directories - "destination" directories. The configuration file
supplies also the information necessary to access user and project
databases.
When started, 'wydawca' scans each source directory and prepares a
list of files found there. Then, it compacts this list by looking for
"directive files" and re-arranging list members in "triplets". A
"directive file" is a special file that must be supplied with each
upload and contains instructions regarding the placement of the uploaded
files. A "triplet" is a standard entity, consisting of three files: a
clear-signed directive file, a file to be distributed, and a detached
signature of the latter. In some special cases, a clear-signed
directive file alone is valid. This happens when it contains only
"standalone directives"(1).
Each "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 (*note
file-sweep-time: general.). If so, the triplet is considered "expired",
and all its files are removed. This gives users the possibility to
restart interrupted or otherwise broken uploads later.
After completing these preliminary stages, 'wydawca' analyzes the
directive file and extracts the project name from it. Using this name
as a key, it searches in the "project dictionary" for a list of users
authorized to make uploads for this project. This list contains user
names and their corresponding public PGP keys. 'Wydawca' tries to
verify the directive file using each PGP key from this list, until a
matching key is found, or the list in exhausted. In the latter case,
the triplet is rejected. Otherwise, the key and its owner are
remembered for the next step.
In this step, the uploaded file and its detached signature are
verified. If they do not match the public key obtained in the previous
step, the triplet is rejected.
Finally, directives from the directive file are executed. On this
stage of the processing, the uploaded files are actually moved to their
destination directories, requested symbolic links are created, etc.
---------- Footnotes ----------
(1) Standalone directives
(http://www.gnu.org/prep/maintain/html_node/FTP-Upload-Directive-File-_002d-v1_002e1.html).
2.1 Operation Modes
===================
The program has two operation modes: 'cron mode' and 'daemon mode'.
In "cron mode", '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 "cron mode", because this is the usual way for
'wydawca' to be used as a cron job.
In "daemon mode", 'wydawca' detaches itself from the controlling
terminal and runs in the background. It watches for the incoming
uploads using one or both of the following methods.
On modern GNU/Linux systems 'wydawca' uses "inotify" API (*note
(inotify(7))monitoring file system events::), which enables it to react
on each upload immediately after a complete triplet is uploaded and to
clean up unfinished or incomplete uploads. This is a preferred mode of
operation.
On other systems, the daemon can be configured to listen on a socket
for upload notifications. This method can also be used together with
inotify, should the need be. This feature uses the TCPMUX protocol(1)
and operates as follows:
After establishing connection, the remote party (the "client") sends
the spool tag followed by a CRLF pair. The server scans its
configuration for a spool that has the requested ID. If no such spool
is found, the server replies with the string '- Unknown service name',
followed by a CRLF pair and closes the connection.
If a matching spool is found, the server replies with '+'
acknowledgment, immediately followed by an optional message of
explanation, and terminated with a CRLF. Upon receiving this
acknowledgment, the client sends the login name of the user who did the
upload(2). The following sample transaction illustrates this:
C: stable
S: +OK. URL ftp://ftp.domain.net
C: smith
When the user name is received, the server schedules a "job" for
processing all triplets in the given spool.
---------- Footnotes ----------
(1) RFC 1078 (http://www.rfc-editor.org/rfc/rfc1078.txt).
(2) The user name requirement is retained for backward compatibility.
In fact, it is not used, so that any word can be sent instead.
3 How to invoke 'wydawca'.
**************************
'Wydawca' gets all information it needs from its "configuration file"
(*note wydawca.conf::). The default configuration file is
'SYSCONFDIR/wydawca.conf', but if it is located elsewhere, you can
specify its new location with the '--config-file' ('-c') command line
option.
If you wish to check your configuration file for syntax errors, use
'--lint' ('-t') command line option. When given this option, 'wydawca'
prints all diagnostics on its standard error and exits with code 0 if
the file is OK, or 1 otherwise.
Normally, '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
'syslog', using the facility given in the 'syslog-facility'
configuration file statement (*note syslog::). Two options are provided
if you wish to disable this autodetection: the option '--syslog'
instructs the program to print all diagnostics via 'syslog', and the
option '--stderr' (or '-e') instructs it to print everything on the
standard error.
The operation mode can be configured in the configuration file or in
the command line. Command line options take precedence over
configuration settings. The cron mode is the default. It can also be
requested explicitly, using the '--cron' command line option.
Similarly, the '--daemon' option enables daemon mode.
Usually 'wydawca' attempts to process all the configured spools. You
can instruct it to process only a subset of these by using the following
options:
'--spool=TAG'
'-S TAG'
Process only spool with the given tag.
'--source=DIR'
'-s DIR'
Process only spool with DIR as the source directory.
Any number of these options may be supplied, e.g.:
$ wydawca --spool=ftp --spool=test --source=/home/ftp/test-upload
The '--debug' ('-d') option tells the program to set its debugging
level to the given integer value. "Debugging level" determines the
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. 'Wydawca' version 4.0.3 implements 4 distinct debugging
levels.
Yet another debugging facility is the '--dry-run' ('-n') option. It
instructs 'wydawca' to avoid doing any 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 '--debug=1 --stderr'
options were given. You can further control the debugging level by
supplying additional '--debug' options _after_ the '--dry-run' option.
The '--dry-run' option is useful when testing new configurations, for
example:
$ wydawca -c new.cfg --dry-run
In addition, the two usual informational options are available as
well: '--help' ('-h') prints a short usage summary, and '--version'
('-v') prints program version number.
4 How to Configure 'wydawca'.
*****************************
Upon startup, 'wydawca' reads its settings from the "configuration file"
'wydawca.conf'. By default it is located in $SYSCONFIDR (i.e., in most
cases '/usr/local/etc', or '/etc'), but an alternative location may be
specified using '--config-file' command line option (*note config-file:
starting.).
If any errors are encountered in the configuration file, the program
reports them on its error output and exits with a non-zero status.
To test the configuration file without starting the server use
'--lint' ('-t') command line option. It causes 'wydawca' to check
configuration file for syntax errors and other inconsistencies. If no
errors were detected, the program exits with code 0. Otherwise, the
exit code is 78.
Using this option together with '-d1' ('--debug=1'), causes 'wydawca'
to produce a dump of the configuration parse tree. Setting a higher
debugging level (e.g. '-d2' option) will additionally prefix each
statement in the dump with the file location where it appeared.
Before parsing, configuration file is preprocessed using 'm4' (*note
Preprocessor::). To see the preprocessed configuration without actually
parsing it, use the '-E' command line option. To avoid preprocessing
it, use '--no-preprocessor' option.
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 'wydawca --config-help'.
4.1 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
"white space" are ignored except as they serve to separate tokens. Some
white space is required to separate otherwise adjacent keywords and
values.
4.1.1 Comments
--------------
"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. "Single-line" comments start with '#' or '//' and
continue to the end of the line:
# This is a comment
// This too is a comment
"Multi-line" or "C-style" comments start with the two characters '/*'
(slash, star) and continue until the first occurrence of '*/' (star,
slash).
Multi-line comments cannot be nested. However, single-line comments
may well appear within multi-line ones.
4.1.2 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 '#' sign and end with the next physical
newline character. Wydawca version 4.0.3, understands the following
pragmatic comments:
'#include <FILE>'
'#include FILE'
Include the contents of the file FILE. If FILE is an absolute file
name, both forms are equivalent. Otherwise, the form with angle
brackets searches for the file in the "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:
1. 'PREFIX/share/wydawca/include'
2. 'PREFIX/share/wydawca/4.0.3/include'
where PREFIX is the installation prefix.
New directories can be appended in front of it using '-I'
('--include-directory') command line option (*note
include-directory: Preprocessor.).
'#include_once <FILE>'
'#include_once FILE'
Same as '#include', except that, if the FILE has already been
included, it will not be included again.
'#line NUM'
'#line NUM "FILE"'
This line causes 'wydawca' to believe, for purposes of error
diagnostics, that the line number of the next source line is given
by NUM and the current input file is named by FILE. If the latter
is absent, the remembered file name does not change.
'# NUM "FILE"'
This is a special form of '#line' statement, understood for
compatibility with the C preprocessor.
In fact, these statements provide a rudimentary preprocessing
features. For more sophisticated ways to modify configuration before
parsing, see *note Preprocessor::.
4.1.3 Statements
----------------
A "simple statement" consists of a keyword and value separated by any
amount of whitespace. Simple statement is terminated with a semicolon
(';').
Examples of simple statements:
daemon yes;
pidfile /var/run/wydawca.pid;
A "keyword" begins with a letter and may contain letters, decimal
digits, underscores ('_') and dashes ('-'). Examples of keywords are:
'group', 'file-sweep-time'.
A "value" can be one of the following:
number
A number is a sequence of decimal digits.
boolean
A boolean value is one of the following: 'yes', 'true', 't' or '1',
meaning "true", and 'no', 'false', 'nil', '0' meaning "false".
unquoted string
An unquoted string may contain letters, digits, and any of the
following characters: '_', '-', '.', '/', '@', '*', ':'.
quoted string
A quoted string is any sequence of characters enclosed in
double-quotes ('"'). A backslash appearing within a quoted string
introduces an "escape sequence", which is replaced with a single
character according to the following rules:
Sequence Replaced with
\a Audible bell character (ASCII 7)
\b Backspace character (ASCII 8)
\f Form-feed character (ASCII 12)
\n Newline character (ASCII 10)
\r Carriage return character (ASCII
13)
\t Horizontal tabulation character
(ASCII 9)
\v Vertical tabulation character
(ASCII 11)
\\ A single backslash ('\')
\" A double-quote.
Table 4.1: Backslash escapes
In addition, the sequence '\NEWLINE' is removed from the string.
This allows to split long strings over several physical lines,
e.g.:
"a long string may be\
split over several lines"
If the character following a backslash is not one of those
specified above, the backslash is ignored and a warning is issued.
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:
"a long string may be"
" split over several lines"
Depending on the context, the quoted string may be subject to
"variable expansion".
During variable expansion, references to variables in the string
are replaced with their actual values. A variable reference has
two basic forms:
$V
${V}
where V is the variable name. The notation in curly braces serves
several purposes. First, it should be used if the variable
reference is immediately followed by an alphanumeric symbol, which
will otherwise be considered part of it (as in '${home}dir').
Secondly, this form allows for specifying the action to take if the
variable is undefined or expands to an empty value.
The following special forms are recognized:
${VARIABLE:-WORD}
"Use Default Values". If VARIABLE is unset or null, the
expansion of WORD is substituted. Otherwise, the value of
VARIABLE is substituted.
${VARIABLE:=WORD}
"Assign Default Values". If VARIABLE is unset or null, the
expansion of WORD is assigned to variable. The value of
VARIABLE is then substituted.
The assigned value remains in effet during expansion of the
current string.
${VARIABLE:?WORD}
"Display Error if Null or Unset". If VARIABLE is null or
unset, the expansion of WORD (or a message to that effect if
WORD is not present) is output to the current logging channel.
Otherwise, the value of VARIABLE is substituted.
${VARIABLE:+WORD}
"Use Alternate Value". If VARIABLE is null or unset, nothing
is substituted, otherwise the expansion of WORD is
substituted.
These constructs test for a variable that is unset or null.
Omitting the colon results in a test only for a variable that is
unset.
If a string contains a reference to an undefined variable,
'wydawca' will report an error and abort. To gracefully handle
such cases, use the "default value construct", defined above.
Here-document
A "here-document" is a special construct that allows to introduce
strings of text containing embedded newlines.
The '<<WORD' construct instructs the parser to read all the
following lines up to the line containing only WORD, with possible
trailing blanks. Any lines thus read are concatenated together
into a single string. For example:
<<EOT
A multiline
string
EOT
Body of a here-document is interpreted the same way as
double-quoted string, unless WORD is preceded by a backslash (e.g.
'<<\EOT') or enclosed in double-quotes, in which case the text is
read as is, without interpretation of escape sequences.
If WORD is prefixed with '-' (a dash), then all leading tab
characters are stripped from input lines and the line containing
WORD. Furthermore, if '-' 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:
<<- TEXT
All leading whitespace will be
ignored when reading these lines.
TEXT
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:
help-text <<-EOT
A sample help text.
EOT;
list
A "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:
alias (test,null);
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.
alias test;
is equivalent to
alias (test);
time interval specification
The "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 'number'-'time unit'. For example, the following
are valid interval specifications:
"1 hour"
"2 hours 35 seconds"
"1 year 7 months 2 weeks 2 days 11 hours 12 seconds"
The pairs can occur in any order, however unusual it may sound to a
human ear, e.g. '2 days 1 year'. If the 'time unit' is omitted,
seconds are supposed.
A "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:
spool download {
source /home/ftp/incoming/ftp;
destination /home/ftp/pub;
}
The closing curly brace may be followed by a semicolon, although this
is not required.
4.1.4 Preprocessor
------------------
Before parsing its configuration file, 'wydawca' preprocesses it. The
built-in preprocessor handles only file inclusion and '#line' statements
(*note Pragmatic Comments::), while the rest of traditional
preprocessing facilities, such as macro expansion, is supported via
'm4', which is used as an external preprocessor.
The detailed description of 'm4' facilities lies far beyond the scope
of this document. You will find a complete user manual in *note GNU M4
manual: (m4)Top. For the rest of this subsection we assume the reader
is sufficiently acquainted with 'm4' macro processor.
The external preprocessor is invoked with '-s' flag, which instructs
it to include line synchronization information in its output. This
information is then used by the parser to display meaningful diagnostic.
An initial set of macro definitions is supplied by the 'pp-setup' file,
located in '$PREFIX/share/wydawca/VERSION/include' directory (where
VERSION means the version of Wydawca package).
The default 'pp-setup' file renames all 'm4' built-in macro names so
they all start with the prefix 'm4_'. This is similar to GNU m4
'--prefix-builtin' options, but has an advantage that it works with
non-GNU 'm4' implementations as well.
To examine the preprocessed configuration, use the '-E' option. The
output from 'm4' will be printed on the standard output and the program
will terminate.
Additional control over the preprocessor is provided via the
following command line options:
'--define=NAME[=VALUE]'
'-DNAME[=VALUE]'
Define the preprocessor symbol NAME as having VALUE, or empty.
'--include-directory=DIR'
'-IDIR'
Add DIR to the list of directories searched for preprocessor
include files.
'--no-preprocessor'
Disable preprocessor.
'--preprocessor=COMMAND'
Use COMMAND instead of the default preprocessor.
4.2 General Settings
====================
-- Config: foreground bool
If BOOL is 'yes', run in foreground. *Note foreground: invocation.
-- Config: umask value
Set the default umask. The VALUE argument must be an octal number.
-- Config: file-sweep-time time
Consider triplet expired if its oldest file was created more than
TIME seconds ago. *Note time interval specification::, for the
syntax of TIME. Default is 300 seconds.
This parameter may also be set for each spool individually. *Note
file-sweep-time: spool.
-- Config: gpg-homedir dir
Set default GPG home directory. The keys for signing outgoing
messages are looked up in this directory. *Note gpg-sign:
statreports, and *note gpg-sign: event notification.
4.3 Upload Directive Versions
=============================
At the time of this writing, FSF has published three versions of the
upload directives, numbered 1.0 through 1.2. The version 1.0 is
considered obsolete and was withdrawn in 2006. The only difference
between versions 1.1 and 1.2 is in handling of files that existed prior
to upload. The version 1.1 implied automatic archivation of the
existing files and their replacement with the newly uploaded versions.
The version 1.2 introduces a new keyword ('replace') for that purpose,
which determines its further actions.
For a detailed information about version 1.1, see Standalone
directives
(http://www.gnu.org/prep/maintain/html_node/FTP-Upload-Directive-File-_002d-v1_002e1.html).
The version 1.2 and its differences from 1.1 are discussed in
Standalone directives
(http://www.gnu.org/prep/maintain/html_node/FTP-Upload-Directive-File-_002d-v1_002e2.html).
By default, 'wydawca' supports both versions. The supported range of
versions can be abridged using the following configuration statements:
-- Config: min-version vn
Sets minimal allowed directive file version. The VN argument must
have the form 'MAJOR.MINOR' and can not be less than '1.1'.
-- Config: max-version vn
Sets maximal allowed directive file version.
For example, the following statements configure 'wydawca' to accept
only directive files of version 1.2:
min-version 1.2;
max-version 1.2;
4.4 User Privileges
===================
'Wydawca' refuses to run with the root privileges. You should configure
its user privileges by using 'user' and, optionally, 'group' statements
in its configuration file:
-- Config: user name
Run with UID and GID of the user NAME.
-- Config: group list
Retain the supplementary groups from the LIST. The latter must
contain group names. For example:
group (nogroup, ftp);
4.5 Daemon Configuration
========================
Statements in this section configure the daemon mode.
-- Config: daemon bool
Enable daemon mode.
-- Config: inotify bool
Enables or disables the "inotify" watcher. By default, inotify is
always enabled on GNU/Linux systems (unless disabled at the
configure time). It can also be configured for each spool
individually (*Note inotify: spool. *Note inotify::, for a
detailed description of this feature.
-- Config: listen url
Listen on this socket for incoming upload notifications (*note
upload notification::). Allowed values for URL are:
inet://IP:PORT
Listen on IPv4(1). address IP. IP may be given either in a
dotted quad notation or as a symbolic host name. PORT is
either a decimal port name, or a service name from
'/etc/services'.
local://FILE
file://FILE
unix://FILE
Listen on the UNIX socket file FILE, which is either an
absolute or relative file name.
-- Config: all-spools name
Declare a special service name, which, when used in a upload
notification request, will be treated as a request to process all
spools.
-- Config: max-connections n
Limits the number of upload notification connections allowed to be
open simultaneously. The default value is 16 connections.
-- Config: idle-timeout interval
Sets the idle timeout for upload notification connections. If a
connection stays idle for more than the given interval, it will be
closed forcibly. Default idle timout is 10 seconds.
*Note time interval specification::, for the syntax of INTERVAL.
-- Config: pidfile file
Store master process PID in FILE. Default pidfile location is
'LOCALSTATEDIR/run/wydawca.pid'.
---------- Footnotes ----------
(1) Support for IPv6 will be added in future versions.
4.6 TCP Wrappers
================
Access to the socket specified in 'listen' statement is controlled by
the 'tcp-wrapper' block statement:
-- Config: tcp-wrapper { ... }
tcp-wrapper {
enable ARG:BOOLEAN;
daemon NAME:STRING;
allow-table FILE:STRING;
deny-table FILE:STRING;
allow-syslog-priority PRIO:STRING;
deny-syslog-priority PRIO:STRING;
}
This statement is available only if 'wydawca' was compiled with
support for TCP wrappers.
-- Config: tcp-wrapper: enable bool
Enable or disable the use of TCP wrappers.
-- Config: tcp-wrapper: daemon name
Set the "daemon name". It is the name before the colon in the
access control file, that marks the line controlling access to
'wydawca'. The default is 'wydawca'.
-- Config: tcp-wrapper: allow-table file
File name of the positive access control file. By default
'/etc/hosts.allow'.
-- Config: tcp-wrapper: deny-table file
File name of the negative access control file. By default
'/etc/hosts.deny'.
-- Config: tcp-wrapper: allow-syslog-priority prio
Log allowed accesses via the given 'syslog' priority.
-- Config: tcp-wrapper: deny-syslog-priority prio
Log denied accesses via the given 'syslog' priority.
Allowed values for PRIO in the 'allow-syslog-priority' and
'deny-syslog-priority' statements are: 'emerg', 'alert', 'crit', 'err',
'warning', 'notice', 'info', and 'debug'.
4.7 Syslog Configuration Directives
===================================
Unless told otherwise, 'wydawca' uses 'syslog' to print its diagnostic
messages. By default, the program uses the 'daemon' facility. The
'syslog' statement allows to change that:
-- Config: syslog { ... }
syslog {
facility local1;
tag wydawca;
print-priority yes;
}
-- Config: syslog: facility name
Configures the syslog facility to use. Allowed values are: 'auth',
'authpriv', 'cron', 'daemon', 'ftp', 'local0' through 'local7', and
'mail'. These names are case-insensitive and may be optionally
prefixed with 'log_' (case-insensitive as well).
-- Config: syslog: tag string
This statement sets the "syslog tag", a string identifying each
message issued by the program. By default, the name of the program
('wydawca') is used.
-- Config: syslog: print-priority bool
In addition to priority segregation, provided by 'syslog', you can
instruct 'wydawca' to prefix each syslog message with its priority.
To do so, set:
print-priority yes;
4.8 SQL Databases
=================
Several statements in configuration file may need to access an SQL
database. 'Wydawca' is able to use any number of databases
simultaneously, the only restriction being that they must be 'MySQL'
databases (this restriction will be removed in future releases).
A database is defined using 'sql' block statement:
-- Config: sql ID { ... }
sql ID {
config-file FILE;
config-group GROUP;
host HOSTNAME;
database DBNAME;
user USERNAME;
password STRING;
ssl-ca STRING;
}
Here, ID is a string uniquely identifying this database. It is
used by other configuration statements (e.g. by dictionaries, see
the next section) to refer to this database.
-- Config: sql: config-file NAME
Set the name of the SQL configuration file to read.
-- Config: sql: config-group NAME
Set the name of the group in the SQL configuration file, from where
to read configuration options.
The statements above allow to keep all security-sensitive
information, such as SQL username and password, in an external
configuration file and thus to relax permission requirements for
'wydawca.conf'. The exact format of such external configuration file
depends on the flavor of SQL DBMS in use. As of version 4.0.3 'wydawca'
supports only 'MySQL', so the configuration file is what is called
"option file" in 'MySQL' parlance (*note Using Option Files:
(mysql)option-files.).
For example, suppose your 'wydawca.conf' contains the following:
sql default {
config-file /etc/wydawca.mysql;
config-group wydawca;
}
Then, the '/etc/wydawca.mysql' would contain the actual parameters for
accessing the database, e.g.:
[wydawca]
socket = /var/db/mysql.sock
database = savane
user = savane
pass = guessme
Another way to specify database credentials is by using the
statements described below. If you prefer this way, you will have to
tighten the permissions of 'wydawca.conf' so that no third person could
see the SQL password. The recommended permissions are '0600'.
-- Config: sql: host HOSTNAME[:PORT-OR-SOCKET]
Set the hostname or IP address of the host running the database.
Optional PORT-OR-SOCKET specifies port number (for TCP connections)
or socket name (for UNIX sockets) to use. In the latter case, the
HOSTNAME and the colon may be omitted. If, however, it is present,
it must be 'localhost'.
-- Config: sql: database name
Specifies the database name.
-- Config: sql: user name
Sets the database user name.
-- Config: sql: password string
Sets the password for accessing the database.
-- 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.
An example 'sql' statement follows:
sql default {
host db.example.org:3306;
database savane;
user root;
password guessme;
}
It is possible to combine both methods, e.g.:
sql default {
config-file /etc/wydawca.sql;
host db.example.org:3306;
database savane;
}
Then, 'wydawca' will attempt to obtain the missing information
(username and password, in this case) from the '/etc/wydawca.sql' file.
4.9 Dictionaries
================
A "dictionary" defines the ways to retrieve user information necessary
to verify the submission. This information can be, for example, the
user's PGP key or his permissions on a project.
A dictionary is defined in configuration file using the following
syntax:
-- Config: dictionary { ... }
dictionary DICT-ID {
type TYPE;
query STRING;
params (PARAM1,PARAM2,...);
}
The 'dictionary' statement can appear either in the global scope of
the configuration file, or inside a 'spool' statement (*note spool::).
Global definitions affect all spools in the configuration file, and ones
inside a 'spool' statement override them for that particular spool.
There are two dictionaries, identified by the value of DICT-ID tag:
project-owner
Keeps email addresses and real names of administrators (or
"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.
project-uploader
Keeps system user names, real names, emails and GPG keys of the
users that are allowed to make uploads for the project.
The sub-statements of 'dictionary' are:
-- Config: dictionary: type name
Defines the type of this dictionary. NAME is one of the following:
builtin
The data are supplied in the configuration file.
sql
Retrieve data from an SQL database. Currently only 'MySQL' is
supported.
external
Retrieve data using an external program. This dictionary type
is reserved for future use.
See below for a detailed description of these dictionary types.
-- Config: dictionary: query string
Sets the query used for retrieving the data. The STRING is subject
to variable expansion (*note variable expansion::). The following
variables are defined in this context:
'project'
The system name of the project for which the triplet is
submitted. The project name is obtained from the 'directory'
directive. If the value of this directive contains
subdirectories, the first (topmost) directory is used as
'project'.
'spool'
The name of the distribution spool where this upload
originates (*note spool::).
'url'
The URL of the spool, as set in the 'url' statement of the
'spool' block (*note url: spool.).
'dir'
Directory (relative to the project distribution root) where
the files are going to be uploaded.
'dest_dir'
Spool destination directory (*note destination: spool.).
'source_dir'
Spool source directory (*note source: spool.).
'user'
'user:name'
The system name of the user that submitted the triplet. This
is defined only for 'project-owner' dictionaries.
'comment'
The value of the 'comment' field from the directive file.
-- Config: dictionary: params (param1, param2, ...)
Supplies additional parameters.
4.9.1 SQL Dictionary
--------------------
Dictionaries of 'sql' type retrieve information from an SQL database (as
of version 4.0.3, only 'MySQL' databases are supported).
The 'query' statement supplies the SQL query to execute. Normally,
it should be a 'SELECT' query.
The 'params' statement must supply a single parameter - the
identifier of one of the preceding 'sql' blocks (*note sql::), which
determines database name and user credentials needed to access it.
The following sub-nodes contain sample definitions for the 'sql'
dictionaries. They are based on the database structure used in 'Savane'
system (http://savannah.nongnu.org/projects/savane-cleanup).
4.9.1.1 Project-owner: an SQL Implementation
............................................
This dictionary retrieves email addresses and real names of
administrators (or "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.
dictionary 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}'";
}
4.9.1.2 Project-uploader: an SQL Implementation
...............................................
This dictionary assumes that the 'user' table has a special column,
'upload_flags', whose value is 'Y' for those users who can do uploads
for this project:
dictionary project-uploader {
type sql;
params (default);
query "SELECT user.email, user.realname "
"FROM user,user_group,groups "
"WHERE user_group.user_id=user.user_id "
"AND user_group.group_id=groups.group_id "
"AND user_group.upload_flags = 'Y' "
"AND groups.unix_group_name = '${project}'";
}
4.9.2 Built-in Dictionary
-------------------------
"Builtin dictionaries" are small dictionaries that keep all data in
their 'params' list. They are designed mainly for testing purposes.
Look ups in builtin dictionaries are performed as follows: The
'query' value is expanded (*note query::). The resulting value is used
as a "key" for lookup in 'params' list. The list scanned as follows:
1. INIT
Let I be the index of the current element in 'params'. Set I to 0.
2. GETEL
Get the Ith element.
3.
If it begins with a slash, interpret it as "comparison type
indicator". Its possible values are:
/exact
Exact comparison. The key must be exactly equivalent to the
dictionary field.
/fnmatch
Dictionary field is treated as an "fnmatch globbing pattern".
*Note (glob(7))globbing pattern::.
/regex
Dictionary field is treated as a regular expression. Unless
configured otherwise by flags (see below), POSIX extended
regular expressions are used (*note Extended regular
expressions: (sed)Extended regexps.).
If that word ends with a comma, the characters following it are
"flags", defining the type of matching. Allowed flags are:
Flag Meaning
--------------------------------------------------------------------------
i Ignore case
b Use basic regular expressions
For example, the string '/exact,i' specifies case-insensitive exact
comparison, the string '/regex,bi' specifies case-insensitive basic
regular expression matching, etc.
Go to step 'INCR'.
4. COMP
Compare the element with the key, using currently selected
comparison method.
5.
If the element matches the key, add elements 'I+1' through 'I+N' to
the result set. The value for N is selected as follows:
Dictionary N
--------------------------------------------------------------------------
project-owner 2
project-uploader 4
6.
Set 'I = I + N'
7. INCR
Set 'I = I + 1'.
8. LOOP
If I is greater than the number of elements in 'param', then stop.
Otherwise, go to step 'GETEL'.
For example, the following defines the 'project-owner' dictionary,
containing data for projects 'foo' and 'bar':
dictionary project-owner {
type builtin;
query "${project}";
params ("/exact",
"foo", "foo-owner@domain.net", "Foo Admin",
"bar", "smith@other.net", "John Smith");
}
4.9.3 External Dictionary
-------------------------
As of version 4.0.3 this dictionary is not yet implemented.
4.10 Directory Setup
====================
'Wydawca' operates on three kinds of directories: spool source
directories (*note source: spool.), destination directories (*note
destination: spool.) and archive directories (*note archivation::). By
default, 'wydawca' assumes that all directories specified in its
configuration file already exist and have proper ownership and modes.
It will abort if it is not so.
You can configure 'wydawca' to create these directories as needed,
and to set up their ownership and modes automatically.
-- Config: create-directories bool
If set to 'yes', this statement instructs 'wydawca' to create any
missing directories.
-- Config: directory-mode mode
Specifies the mode for created directories (in octal). If the
directory already exists, its mode will be checked and if necessary
changed to MODE.
This statement is overridden by per-directory statements:
'source-mode' and 'destination-mode' statements in 'spool' block
(*note spool::) and 'directory-mode' statement in 'archive' block
(*note archivation::).
-- Config: directory-owner uid gid
Configures owner user and group IDs for source, destination and
archive directories.
The UID argument is either a numeric UID prefixed with a plus sign,
or a symbolic user name, which will be converted to the numeric UID
using the system user database. If a number without the '+' prefix
is supplied, it will first be looked in the password database as
the user name, and, if no such user is found, it will be used as
the numeric UID.
The same holds for the GID argument.
This statement is overridden by per-directory statements:
'source-owner' and 'destination-owner' statements in 'spool' block
(*note spool::) and 'directory-owner' statement in 'archive' block
(*note archivation::).
Notice, that both 'directory-mode' and 'directory-owner' apply only
to the last component of the created directory ('basename'). Any
intermediate directories are created with default mode and ownership.
4.11 Archivation
================
There may be cases when project maintainers need to overwrite existing
distributed files with another ones, having the same names. (Note,
however, that this practice is not encouraged). In that case, 'wydawca'
needs to first "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 their existing files.
'Wydawca' supports two basic archivation methods: to a 'tar' file,
and to a separate directory. The method to be used is configured using
'archive' statement. This statement can appear either in the global
scope, in which case it affects all spools, or within a 'spool' block
(*note spool::), where it affects only the given spool.
-- Config: archive type
archive TYPE {
# Name of archive file or directory
name FILE-OR-DIR;
# Define backup type
backup TYPE;
# mode for the archive directory
directory-mode MODE;
# owner user and group for the archive directory
directory-owner UID GID;
}
The TYPE argument specifies the archivation type:
none
Disable archivation.
tar
Add to a 'tar' archive.
directory
Store file in a separate directory.
-- Config: archive: name file-or-dir
Specify the name of the tar archive (if type 'tar' is used) or
destination directory (if type 'directroy' is used).
If the archivation type tar is used, the 'name' statement sets the
full name of the tar archive to use, e.g.:
archive tar {
name /var/spool/uploads/archive.tar;
}
The file being archived is appended to the archive using 'tar -r'
(*note Appending Files to an Archive: (tar)appending files.). Any
archived instance can subsequently be retrieved using GNU tar
'--occurrence' option (*note Multiple Files with the Same Name:
(tar)multiple.).
-- Config: tar-program name
By default, 'wydawca' will search for 'tar' binary in your search
path. If you wish to use a particular binary, you may specify its
full file name using 'tar-program' statement.
The 'directory' archivation type means that archive copies will be
stored in a directory specified by the '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:
archive directory {
name /var/backups/gnu;
}
all files from '/home/ftp/gnu/tar' will be archived in
'/var/backups/gnu/tar', and files from '/home/ftp/gnu/tar/old' will be
archived in '/var/backups/gnu/tar/old', etc.
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:
archive directory {
name .archive;
}
mean that files from '/home/ftp/gnu/tar' will be archived in the
directory '/home/ftp/gnu/tar/.archive', files from
'/home/ftp/gnu/tar/old' -- in '/home/ftp/gnu/tar/.archive/old', etc.
-- Config: archive: backup type
When using the 'directory' archivation type, it may happen that the
archive file with the same name as the one about to be created
already exists. This statement specifies how to handle the
existing copy, in other words, how to "backup" it. The TYPE
argument corresponds to the 'version-control' Emacs variable. The
following table describes its possible values:
't'
'numbered'
Always make numbered backups.
'nil'
'existing'
Make numbered backups of files that already have them, and
simple backups of the others.
'never'
'simple'
Always make simple backups.
If no backup method is given, 'existing' is assumed
-- Config: archive: directory-mode mode
Sets directory mode for creating the directory (octal). If the
directory already exists, its mode will be checked and if necessary
changed to MODE.
This statement overrides the global 'directory-mode' statement
(*note directory setup::).
-- Config: archive: directory-owner uid gid
Configures owner user and group IDs for created archive
directories. If the archive directory already exists, its
ownership will be checked and if necessary reverted to UID:GID.
*Note directory-owner: directory setup, for a discussion of the
syntax for UID and GID.
This statement overrides the global 'directory-mode' statement
(*note directory setup::).
Signature files (i.e. the ones ending with '.sig') are usually
located in the same directory as the files they sign. To enforce this
rule, 'wydawca' implements "implicit signature archivation" facility.
It works as follows. When archivation of FILE is requested by 'archive:
FILE' statement in the directive file, 'wydawca' also checks if the file
named 'FILE.sig' exists. If so, it is archived along with 'FILE'.
-- Config: archive-signatures bool
If implicit signature archivation is not needed, use the
'archive-signatures' statement to disable it, e.g.:
archive-signatures no;
4.12 Distribution Spool
=======================
A "distribution spool" defines the location of the source directory and
the corresponding distribution (or "destination") directory. It may
also set archivation type, various dictionaries and notifications for
that directory, thus overriding the global settings.
The 'spool' block statement defines a distribution spool:
-- Config: spool tag { ... }
spool TAG {
url URL;
alias (ALIASES);
inotify BOOL;
source DIR;
source-mode MODE;
source-owner UID GID;
destination DIR;
destination-mode MODE;
destination-owner UID GID;
file-sweep-time INTERVAL;
dictionary { ... }
archive { ... }
notify-event { ... }
}
The TAG argument defines a unique identifier for this spool. It
will be used in log messages and is available for variable
expansion (*note variable expansion::) as the '$spool' variable.
-- Config: spool: alias list
Defines a list of "aliases", i.e. alternative tag names for this
spool.
-- Config: spool: inotify bool
Enables or disables the "inotify" watcher for this spool. By
default, inotify is always enabled on GNU/Linux systems (unless
explicitly disabled at the configure time). *Note inotify::, for a
detailed description of this feature.
-- Config: spool: url string
Defines download URL, associated with this spool. Its value may be
used as the variable '$url' in mail notifications.
-- Config: spool: source dir
Specifies the location of the source directory.
-- Config: spool: source-mode mode
Sets directory mode for creating the source directory (octal). If
the directory already exists, its mode will be checked and if
necessary changed to MODE.
This statement overrides the global 'directory-mode' statement
(*note directory setup::).
-- Config: spool: source-owner uid gid
Configures owner user and group IDs for the source directory. If
the directory already exists, its ownership will be checked and if
necessary reverted to UID:GID.
*Note directory-owner: directory setup, for a discussion of the
syntax for UID and GID.
This statement overrides the global 'directory-mode' statement
(*note directory setup::).
-- Config: spool: destination dir
Specifies the type and location of the destination directory. The
DIR argument must be either an absolute name of a directory on the
local file system, or a special URL. 'Wydawca' version 4.0.3
supports two destination URL schemes:
file://DIR-NAME
dir://DIR-NAME
Equivalent to DIR-NAME alone. Defines a destination directory
located on the local file system.
null:
Defines a "null upload spool". Null spools implement all
tests described in *note 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.
The following two statements apply only if the destination is a local
directory ('file://' or 'dir://' URL scheme):
-- Config: spool: destination-mode mode
Sets directory mode for creating the destination directory (octal).
If the directory already exists, its mode will be checked and if
necessary changed to MODE.
This statement overrides the global 'directory-mode' statement
(*note directory setup::).
-- Config: spool: destination-owner uid gid
Configures the owner user and group IDs for the destination
directory. If the directory already exists, its ownership will be
checked and if necessary reverted to UID:GID.
*Note directory-owner: directory setup, for a discussion of the
syntax for UID and GID.
This statement overrides the global 'directory-mode' statement
(*note directory setup::).
The following statements, if present, override the corresponding
global definitions for this spool.
-- Config: spool: archive { ... }
Configure spool-specific archivation. *Note archivation::, for its
description.
-- Config: spool: dictionary tag { ... }
Configure spool-specific dictionary. *Note dictionaries::, for a
detailed discussion of this statement.
-- 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 TIME
seconds ago. This statement overrides the global 'file-sweep-time'
setting (*note file-sweep-time: general.).
-- Config: spool: notify-event { ... }
Configure spool-specific event notification. *Note notification::,
for a detailed discussion of this statement.
The 'source' and 'destination' statements are mandatory.
For example, the following definition says that valid uploads to
'/home/ftp/incoming/ftp' should be transferred to '/home/ftp/gnu':
spool ftp {
url ftp://ftp.gnu.org.ua;
source /home/ftp/incoming/ftp;
destination /home/ftp/gnu;
}
This spool defines no particular archivation type, dictionary or
notifications, so it will inherit these settings from the global
configuration.
The following example shows the same spool, that additionally sets
its own archivation method:
spool ftp {
url ftp://ftp.gnu.org.ua;
source /home/ftp/incoming/ftp;
destination /home/ftp/gnu;
archive directory {
name .archive;
backup numbered;
}
}
4.13 Distribution Verification
==============================
After the submission has been verified, 'wydawca' may also run an
additional check to verify whether the main file (normally, a tarball)
is OK to be distributed. To set up such "distribution verification",
add the following statement either in the global scope, or within a
'spool' declaration:
-- Config: check-script TEXT
-- Config:spool: check-script TEXT
Define the distribution verification script. The TEXT must be a
valid 'sh' program. It is executed without arguments, in a
temporary directory which contains a copy of the main distribution
file. The script can refer to the following environment variables:
-- Check Environment: WYDAWCA_SPOOL
Spool tag.
-- Check Environment: WYDAWCA_SOURCE
Spool source directory, as set by the 'source' statement
(*note tag: spool.).
-- Check Environment: WYDAWCA_DEST
Spool destination directory (*note destination: spool.).
-- Check Environment: WYDAWCA_URL
Spool URL (*note url: spool.).
-- Check Environment: WYDAWCA_TRIPLET_BASE
Base name of the triplet.
-- Check Environment: WYDAWCA_DIST_FILE
File name of the main distribution file.
Apart from these, the script inherits 'wydawca' environment.
The submission is accepted only if the script returns 0.
Otherwise, it is rejected and the 'check-failure' event (*note
event notification::) is generated.
In case of non-zero return, the script may return additional
diagnostics on the standard output. This diagnostics will be
available for use in notification messages via the '$check:diagn'
variable.
Additionally, the actual return code of the script, in decimal, is
available in the '$check:result' variable. If the script
terminates on a signal, the value of this variable is 'SIG+N',
where N is the signal number.
If both global and spool 'check-script's are defined, 'wydawca'
executes both scripts as if they were connected by a logical '&&', i.e.
per-spool script is executed only if the global one returned success
('0'). The submission is accepted only if both scripts returned '0'.
Since the script usually contains several lines, the 'config-script'
value is usually supplied using a here-document construct (*note
here-document::).
The following example illustrates the use of 'config-script' to catch
possible security holes in the distributed 'Makefile.in' files(1)
check-script <<EOT
case ${WYDAWCA_DIST_FILE} in
*.tar|*.tar.*)
if tar -xOf ${WYDAWCA_DIST_FILE} --occurrence=1 \
--wildcards --no-wildcards-match-slash '*/Makefile.in' | \
grep -q 'perm -777'; then
fmt <<_EOF_
The top-level Makefile.in in ${WYDAWCA_DIST_FILE} changes mode of
all the directories below the build tree to 777 before creating
the tarball. This constitutes a security hole (see CVE-2009-4029[1],
for more details).
Please, rebuild the package using a newer Automake (at least v. 1.11.1)
and resubmit.
_EOF_
cat <<_EOF_
--
[1] http://article.gmane.org/gmane.comp.sysutils.autotools.announce/131
_EOF_
exit 1
fi
;;
*)
;;
esac
exit 0
EOT;
---------- Footnotes ----------
(1) See
<http://article.gmane.org/gmane.comp.sysutils.autotools.announce/131>.
4.14 Statistics
===============
Periodically 'wydawca' produces statistic dumps. These dumps are
displayed on the diagnostic channel 'info' (and optionally mailed to the
admimistrator). The frequency with which they are produced is defined
by the 'stat-report-schedule' configuration statement.
-- Config: stat-report-schedule time
Schedules generation of statistic reports. The TIME argument is a
time specification in 'crontab' format (*note
(crontab(5))crontab::). By default, reports are generated hourly.
To create reports each three hours, set
stat-report-schedule "0 */3 * * *";
To create them at midnight, use
stat-report-schedule "@midnight";
*Note Event timestamps in WY_stat::, if statistic reports appear to
be generated one second prior to their scheduled time.
Statistic report is suppressed if there were no uploads since the
last report.
The following example illustrates what you might get if you
configured full statistic reports:
errors: 0
warnings: 2
bad signatures: 0
access violation attempts: 0
complete triplets: 6
incomplete triplets: 2
bad triplets: 0
expired triplets: 0
triplet successes: 6
files uploaded: 12
files archived: 2
symlinks created: 0
symlinks removed: 0
Each item in this report is configurable, and a unique configuration
keyword is associated with it. The statistic items and their
corresponding keywords are described in the table below:
'errors'
Any error that occurred during the run.
'warnings'
Any warning condition occurred during the run.
'bad-signatures'
A PGP signature not matches the public key for the user that issued
it.
'access-violations'
A user is attempting to upload files for some project, but it is
not authorized to do so.
'complete-triplets'
A complete triplet is registered.
'incomplete-triplets'
An incomplete triplet is registered, i.e. such that misses one or
more of its files. Notice, that a directive file alone is counted
as a complete triplet, provided that its signature verifies
correctly and that it does not contain 'file' directive.
'bad-triplets'
A triplet contains files owned by different users.
'expired_triplets'
A triplet has expired.
'triplet_success'
A triplet is processed successfully
'uploads'
An upload is processed successfully. An upload is defined as a
move of a file and its detached signature from the source to the
destination directory.
'archives'
An archivation is performed
'symlinks'
A symlink is created.
'rmsymlinks'
A symlink is removed.
There are two ways to enable statistic reports. The "built-in"
statistic output is enabled using the 'statistics' keyword.
-- Config: statistics list
The amount of information included in statistic report is
configured using the 'statistics' statement. This statement takes
a list of arguments, each one being one of the keywords, described
above. For example, the following statement causes only the
information about errors and warnings to be printed:
statistics (errors, warnings);
The output produced looks like:
errors: 0
warnings: 2
A special keyword 'none' can be used to suppress this output
altogether (which is the default), as in
statistics none;
Another special keyword is 'all'. It enables full statistic
report. This keyword may also be followed by any number of
statistic item names, which are in this case _excluded_ from the
summary. For example, to output all statistic data, except errors
and warnings one would set:
statistics (all, errors, warnings);
More elaborate output can be produced using the 'mod_logstat'
loadable module. *Note mod_logstat::, for a detailed discussion.
4.15 Notification Mechanism
===========================
While running, 'wydawca' keeps track of certain events occurring, such
as, for example, broken PGP signatures or file uploads attempted by
unauthorized users. It can issue notifications about such events using
the supplied loadable modules.
Configuration of notifications consists of two parts. First the
required loadable module must be loaded and configured. Then, configure
the notification itself.
4.15.1 modules
--------------
A "loadable module" is a piece of software that provides notification
mechanism for 'wydawca'. It is built as a UNIX dynamically loaded
library and placed in one of the preconfigured directories which
constitute a "library load path". To load a module, the following
statement is used:
-- Config: module NAME FILE
Load the module NAME from FILE. Other places of the configuration
file can refer to the module as NAME.
The FILE argument is a file name of the module (normally, a
'file.so' or 'file.la' file).
Unless FILE in the 'module' statement is an absolute file name, it
will be searched in the library load path, which is defined as:
1. Optional "prefix" search directories specified by the
'module-prepend-load-path' directive (see below).
2. 'Wydawca' module directory: '$PREFIX/lib/wydawca'.
3. Additional search directories specified by the 'module-load-path'
directive (see below).
4. The value of the environment variable 'LTDL_LIBRARY_PATH'.
5. The system dependent library search path (e.g. on GNU/Linux it is
defined by the file '/etc/ld.so.conf' and the environment variable
'LD_LIBRARY_PATH').
The value of 'LTDL_LIBRARY_PATH' and 'LD_LIBRARY_PATH' must be a
colon-separated list of absolute directory names, for example
'/usr/lib/mypkg:/lib/foo'.
In any of these directories, 'wydawca' first attempts to find and
load the given filename. If this fails, it tries to append the
following suffixes to it:
1. the libtool archive suffix: '.la'
2. the suffix used for native dynamic libraries on the host platform,
e.g., '.so', '.sl', etc.
The statements that modify the module search path are:
-- Config: module-load-path LIST
This directive adds the directories listed in its argument to the
module load path. Example:
module-load-path (/usr/lib/wydawca,/usr/local/wydawca/lib);
-- Config: module-prepend-load-path LIST
Same as above, but the directories from LIST are added to the
beginning of the module search list, rather than to its end. The
order of directories in LIST is preserved in both cases.
Once loaded, the module can be initialized. This is done in the
following block statement:
-- Config: module-init NAME { ... }
Initialize the module identified by NAME. The module must have
been previously loaded using the 'module' statement, as described
above. The statements between curly braces are module-specific
configuration statements. See the module descriptions below for a
detailed discussion of these.
To list module-specific configuration directives with a short usage
instructions, use the '--module-help' statement:
wydawca --module-help=FILE
If the FILE argument is the base module name (e.g. 'mod_mailutils'), it
will be looked in the default library load path (*note library search
path::). If it contains directory components, the FILE will be loaded
from the specified directory.
4.15.2 Event Notification
-------------------------
A number of "events" are tracked during the execution. Any of them can
be used to trigger the notification mechanism. It is configured using
the following statement:
-- Config: notify-event { ... }
notify-event {
# Event on which to notify
event EID;
# Name of the module to invoke on event
module MODNAME;
# Module-specific configuration data
module-config {
...
}
}
-- Config: notify-event: event EID
Trigger the notification when the event identified by EID occurs.
The identified EID is one of the following:
success
Successful upload.
bad-ownership
An unauthorized user attempted to upload files for their
project.
bad-directive-signature
The directive signature does not match the public key of the
uploader.
bad-detached-signature
The detached signature does not match the public key of the
uploader.
check-failure
Distribution verification failed. *Note verification::, for a
detailed description.
statistics
This event produces statistics about the recent jobs performed
by 'wydawca'. In daemon mode, it is scheduled periodically as
controlled by the 'stat-report-schedule' statement. In cron
mode it is emitted when all spools have been processed.
For compatibility with 'wydawca' versions prior to 3.1.95, the
event name 'finish' can be used instead of 'statistics'.
*Note statreports::, for a detailed discussion. See also
*note mod_logstat::.
-- Config: notify-event: module MODNAME
Identify the module responsible for the notification. The MODNAME
argument must have been previously initialized in a 'module'
statement (*note modules::).
-- Config: notify-event: module-config { ... }
This block provides module-specific configuration for MODNAME. Its
content depends on the module used for notification. The version
4.0.3 of 'wydawca' is shipped with two notification modules:
'mod_mailutils' for notifications via electronic mail, and
'mod_logstat' for logging the information via 'syslog'. These
modules are described in detail later.
4.15.3 'mod_mailutils'- Mail Notification
-----------------------------------------
Mail notification is configured using the 'mod_mailutils' module. To
load the module, add the following statement:
module mailutils mod_mailutils.so;
The 'module-init' section can contain the following statements:
-- mod_mailutils: from-address address
Set sender address for outgoing mails. E.g.:
from-address ftp-uploads@gnu.org.ua;
It is not strictly necessary to specify the sender address. In the
absence of 'from-address' statement, the sender email will be
constructed from the name of the user 'wydawca' runs as (*note user
privileges::) and the full domain name of the machine it runs at.
-- mod_mailutils: admin-address email
Sets the admin email address or addresses. The statistic
notifications and any notifications configured to be sent to admins
will be forwarded to this address. The EMAIL argument is either a
RFC 822 email address, or a list of such addresses. For example,
the following statement configures a single admin address:
admin-address root@gnu.org.ua;
The example below illustrates how to configure multiple addresses:
admin-address "root@gnu.org.ua,ftp-adm@gnu.org.ua";
Yet another way to configure them is:
admin-address (root@gnu.org.ua, ftp-adm@gnu.org.ua);
4.15.3.1 Mailer
...............
To send messages, 'mod_mailutils' uses a special logical entity called a
"mailer". It is set in the 'module-init' block using the 'mailer'
keyword.
-- mod_mailutils: mailer url
Set mailer URL.
A mailer URL consists of a scheme specification, followed by '://'
separator and additional data. The URLs supported by Wydawca version
4.0.3 are described in the table below. As usual, square brackets
indicate optional parts:
smtp://HOST[:PORT]
Use an SMTP server on HOST to relay messages. The HOST part is
either an IP address in dotted-quad notation or as a symbolic host
name. In the latter case, DNS system is be used to resolve it.
Optional PORT specifies port number or symbolic name (as defined in
'/etc/services'). It defaults to 25. For example:
mailer smtp://remote.server.net:24;
sendmail://PROGNAME
Use sendmail-compatible program PROGNAME. "Sendmail-compatible"
means that the program must be able to read an RFC-822 message from
its standard input and must support the following command line
options:
'-oi'
Do not treat '.' as message terminator.
'-f ADDR'
Use ADDR as the sender address.
'-t'
Get recipient addresses from the message.
Example:
mailer sendmail:///usr/sbin/exim;
sendmail:
This is a special form of the 'sendmail' mailer. It uses the
'sendmail' binary from the '_PATH_SENDMAIL' macro in your
'/usr/include/paths.h'. It is the default mailer.
prog://PROGNAME?QUERY
A "prog" mailer. This is a generalization of 'sendmail' mailer
that allows to use arbitrary external programs as mailers.
The full file name of the program is given in PROGNAME part. The
QUERY part is a list of arguments, separated by '&' signs.
Arguments may contain the following macro-substitutions:
'${sender}'
Expands to the sender email address.
'${rcpt}'
Expands to the recipient email addresses.
The program PROGNAME must read an RFC-822 message from its
standard input.
An example of 'prog' mailer definition:
mailer "prog:///bin/nullmail?localhost&-F${sender}&${rcpt}
When sending a mail, 'wydawca' will invoke:
/bin/nullmail localhost -FSENDER RCPT
where SENDER means the sender address, and RCPT stands for the
recipient email address.
'| PROG ARGS..'
Equivalent to the 'prog' mailer, described above, but written
in a more natural fashion. In this notation, the example
definition above becomes:
mailer "|/bin/nullmail localhost -F${sender} ${rcpt}"
4.15.3.2 Message Templates
..........................
Each notification message is built from a message template, by expanding
variables (*note variable expansion::) within it. The message text may
be specified either in place within the configuration directive it
belongs to (*note notification::), or defined by 'define-message'
statement.
-- mod_mailutils: define-message name text
Define message NAME to be TEXT. This message can be referred to
from other configuration statements by '@NAME' notation.
The message text must be formatted as a valid RFC-822 message, i.e.
it must consist of two parts, message headers and body, separated by a
single empty line. Therefore TEXT is usually a "here-document"
construct (*note here-document::). For example:
define-message my-message <<EOT
From: Wydawca
Subject: test
This is a test message.
EOT;
If you do not wish to supply any headers (which is unlikely, because
a mail should at least have a 'Subject' header), simply begin the
message text with an empty line, like this:
define-message my-message <<EOT
This is a test message.
EOT;
4.15.3.3 Statistic Reports
..........................
-- mod_mailutils: mail-statistics { ... }
The 'mail-statistics' statement in the 'module-init' section for
'mod_mailutils' configures the statistic reports sent to the system
administrator.
mail-statistics {
message TEXT-OR-ID;
statistics ITEM-LIST;
gpg-sign KEY;
}
To arrange for sending the reports, the configuration must contain
the following statement:
notify-event {
event statistics;
module mailutils;
}
-- 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
'define-message' (*note templates::). The reference syntax is:
message @NAME;
where NAME is the message name as used in 'define-message'.
-- mail-statistics: statistics item-list
The argument is a list of statistic item names as described in
*note statistics::. A report will be sent only if statistic
counters for at least one of the requested items are not zero. For
example, the following statement requires sending notifications
only if there occurred any errors or access violation attempts, or
any bad signature was uploaded:
statistics (errors, access-violations, bad-signatures);
-- mail-statistics: gpg-sign key
If this statement is present, the message will be signed using the
supplied GPG KEY. The key is looked up in the GPG home directory
(*note gpg-homedir::).
The statistics message is sent to addresses configured by
'admin-address' statement (*note admin-address: mod_mailutils.).
The variables available for use in statistic reports are:
Variable Replaced with
--------------------------------------------------------------------------
date Current date and time in the current locale.
stat:errors Number of errors detected.
stat:warnings Number of warnings reported.
stat:bad_signatures Number of bad signatures detected.
stat:access_violations Number of access violation attempts.
stat:complete_triplets Number of complete triplets processed.
stat:incomplete_tripletsNumber of incomplete triplets left in the source
directory.
stat:bad_triplets Number of bad triplets seen.
stat:expired_triplets Number of expired triplets.
stat:triplet_success Number of successfully processed triplets.
stat:uploads Number of successful uploads.
stat:archives Number of archivations performed.
stat:symlinks Number of symbolic links created.
stat:rmsymlinks Number of symbolic links removed.
stat:check_failures Number of verification failures
(*note verification::).
An example definition of the admin notification template follows:
mail-statistics {
statistics (errors,warnings,bad_signatures,
access_violations);
message <<EOT
Subject: Wydawca stats
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}
Regards,
Wydawca
EOT;
}
4.15.3.4 'module-config' for 'mod_mailutils'
............................................
When 'mod_mailutils' is used in the 'notify-event' block, the following
statements can be used in 'module-config' to configure it:
notify-event {
module mailutils;
# module configuration
module-config {
# Notify this recipient
recipient WHO;
# Sign message with this key
gpg-sign KEY;
# Text of the notification or identifier of a defined message
# template
message TEXT-OR-ID;
}
}
-- mod_mailutils config: recipient who
Determines who should receive the notification. The following
values for WHO are allowed:
'read'
'message'
Read recipients from the 'To', 'Cc' and 'Bcc' headers of the
message. This is the default.
'admin'
The system administrator, as defined in 'admin-address'
statement (*note admin-address: notification.).
'owner'
Administrators of the project for which the files where
uploaded. Their addresses are retrieved from the
'project-owner' dictionary (*note dictionaries::).
'user'
User name of the user who uploaded files.
-- mod_mailutils config: gpg-sign key
If this statement is present, the message will be signed using the
supplied GPG KEY. The key is looked up in the GPG home directory
(*note gpg-homedir::).
-- mod_mailutils config: 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
'define-message' (*note templates::).
The following macro-variables are expanded in the message texts:
Variable Replaced with
--------------------------------------------------------------------------
project Project system name.
url URL of the distribution site.
spool Name of the spool (*note spool::).
dir Directory (relative to the project distribution
root) where the files where uploaded.
dest-dir Value of the 'destination' keyword.
source-dir Value of the 'source' keyword.
triplet:dist File name of the main distribution file.
triplet:sig File name of the detached signature file.
triplet:dir File name of the directive file.
triplet:ls:full A full listing of the uploaded triplet(1).
triplet:ls:upload Listing of the uploaded files (see below).
triplet:ls:dist Listing of the main distribution file (see
below).
triplet:ls:sig Listing of the detached signature file (see
below).
triplet:ls:dir Listing of the directive file (see below).
user System name of the user who uploaded the
triplet.
user:name System name of the user who uploaded the
triplet.
user:real-name Real name of the user who uploaded the triplet.
user:email Email of the user who uploaded the triplet.
email:admin Full(2). email address of the systems
administrator, as set by the 'admin-address'
(*note admin-address: notification.).
email:owner Full email address of the project administrator
("owner").
email:user Full email address of the user who did the
upload. Equivalent to '"${user:real-name}"
<${user:email}>'.
check:result Code returned by external checker, in decimal.
*Note check-result: verification, for a detailed
description.
check:diagn Diagnostics text returned by external checker.
*Note verification::, for a detailed
description.
"Listings" referred to in the table above, are similar to those
produced by the 'ls' command, and include information on file
permissions, ownership, size and modification date. For example, here
is a possible '${triplet:ls:full}' listing:
-rw-r--r-- gray users 2707278 2007-09-06 22:14:35 tar-1.18.tar.gz
-rw-r--r-- gray users 189 2007-09-06 22:14:35 tar-1.18.tar.gz.sig
-rw-r--r-- gray user 62 2007-09-06 22:14:35 tar-1.18.tar.gz.directive.asc
The example in the following subsection shows how to configure
success notification for the user.
---------- Footnotes ----------
(1) It is equivalent to:
${triplet:ls:dist}
${triplet:ls:sig}
${triplet:ls:dir}
(2) "Full" here means an email address with eventual personal part
4.15.3.5 Example of mod_mailutils configuration
...............................................
This subsection provides a complete example for 'mod_mailutils'
configuration.
module mailutils mod_mailutils.la;
module-init mailutils {
admin-address "root@example.net";
from-address "wydawca@example.net";
mailer "sendmail:";
mail-statistics {
statistics all;
message <<- EOT
Subject: upload statistics
This is to notify you that the run of wydawca on ${date}
caused the following results:
errors ............................. ${stat:errors}
warning ............................ ${stat:warnings}
bad signatures ..................... ${stat:bad_signatures}
access violation attempts .......... ${stat:access_violations}
complete triplets .................. ${stat:complete_triplets}
incomplete triplets ................ ${stat:incomplete_triplets}
bad triplets ....................... ${stat:bad_triplets}
expired triplets ................... ${stat:expired_triplets}
triplet successes .................. ${stat:triplet_success}
files uploaded ..................... ${stat:uploads}
files archived ..................... ${stat:archives}
symlinks created ................... ${stat:symlinks}
symlinks removed ................... ${stat:rmsymlinks}
verification failures .............. ${stat:check_failures}
Regards,
Wydawca
EOT;
}
}
notify-event {
event statistics;
module mailutils;
}
notify-event {
event success;
module mailutils;
module-config {
recipient user;
message <<- EOT
Subject: Upload of ${project} successful
Upload of ${project} to ${url}/${dir} finished successfully.
Files uploaded:
${triplet:ls:upload}
Regards,
Wydawca
The Project Submission Robot
EOT;
}
}
For the sake of brevity, this example defines only two 'notify-event'
statements. More statements for others events can be added as needed.
4.15.4 'mod_logstat' - statistics logging
-----------------------------------------
The module 'mod_logstat' logs the supplied message at the
'statististics' event.
The simplest configuration for this module is:
module logstat mod_logstat.so;
notify-event {
event statistics;
module logstat;
}
This will produce on the default logging channel the detailed
statistics, as discussed in *note statistics::.
There is no specific 'module-init' statements. The module should be
called from 'notify-event' block on the 'statistics' event. The
module's 'module-config' statement can contain the following statements:
-- mod_logstat config: statistics list
Configures what statistics items should be included in the output.
*Note statistics::, for a detailed discussion of LIST.
This statement is ignored if the 'message' statement is present.
-- mod_logstat config: message text
Specifies the message to be logged. The TEXT argument can contain
references to statistic variables (*note statistic variables::).
If no 'message' statement is present, the following default is
assumed:
message <<EOT
errors: ${stat:errors}
warnings: ${stat:warnings}
bad signatures: ${stat:bad_signatures}
access violation attempts: ${stat:access_violations}
complete triplets: ${stat:complete_triplets}
incomplete triplets: ${stat:incomplete_triplets}
bad triplets: ${stat:bad_triplets}
expired triplets: ${stat:expired_triplets}
triplet successes: ${stat:triplet_success}
files uploaded: ${stat:uploads}
files archived: ${stat:archives}
symlinks created: ${stat:symlinks}
symlinks removed: ${stat:rmsymlinks}
check failures: ${stat:check_failures}
EOT;
5 'Wydawca' configuration file.
*******************************
This chapter summarizes the configuration statements. For each
statement, a reference to its detailed description is provided.
# Enable daemon mode.
# *Note daemon::.
daemon ARG:BOOLEAN;
# Start in foreground even in daemon mode.
# *Note foreground: general.
foreground ARG:BOOLEAN;
# Set pid file name.
# *Note pidfile: general.
pidfile FILE:STRING;
# Run with UID and GID of this user.
# *Note user privileges::.
user NAME:STRING;
# Retain these supplementary groups:
# *Note user privileges::.
group ARG:LIST OF STRING;
# Listen on this address.
# *Note listen: daemon.
listen SOCKET:SOCK-ADDR;
# Maximum number of simultaneous upload notification connections.
# *Note max-connections: daemon.
max-connections N;
# Idle timeout for an upload notification connection.
# *Note idle-timeout: daemon.
idle-timeout TIME:INTERVAL;
# Configure TCP wrappers.
# *Note tcp-wrapper::.
tcp-wrapper {
# Enable TCP wrapper access control. Default is 'yes'.
enable ARG:BOOLEAN;
# Set daemon name for TCP wrapper lookups. Default is program name.
daemon NAME:STRING;
# Use FILE for positive client address access control.
# (default: '/etc/hosts.allow').
allow-table FILE:STRING;
# Use FILE for negative client address access control.
# (default: '/etc/hosts.deny').
deny-table FILE:STRING;
# Log host allows at this syslog priority.
allow-syslog-priority PRIO:STRING;
# Log host denies at this syslog priority.
deny-syslog-priority PRIO:STRING;
}
# Load module
# *Note modules::.
module NAME:STRING FILE:STRING;
# Initialize the loaded module
# *Note module-init: modules.
module-init NAME {
# One or more module-specific statements
...
}
# Load mailutils module
# *Note mod_mailutils::.
module mailutils mod_mailutils.so;
# mod_mailutils initialization
module-init mailutils {
# Set mailer URL.
# *Note mailer::.
mailer URL:STRING;
# Set admin email address.
# *Note admin-address: mod_mailutils.
admin-address EMAIL:STRING;
# Set sender email address.
# *Note from-address: mod_mailutils.
from-address EMAIL:STRING;
# Send statistics report.
# *Note statreports::.
mail-statistics {
# Message text.
message TEXT:STRING;
# Send mail if one or more of these items are set.
statistics ITEMS:STRING;
# Sign message with this key.
gpg-sign KEY:STRING;
}
}
# Configure notification.
# *Note notification::.
notify-event {
# Event on which to notify.
event EV-ID:STRING;
# Name of the module to invoke on event
module MODNAME:STRING;
# Module-specific configuration data
module-config {
...
}
# Configuration for mod_mailutils
# *Note mail-config::.
module-config {
# Notify this recipient
# *Note recipient: mail-config.
recipient WHO:STRING;
# Sign message with this key
# *Note gpg-sign: mail-config.
gpg-sign KEY:STRING;
# Text of the notification or identifier of a defined message
# template
# *Note message: mail-config.
message TEXT-OR-ID:STRING;
}
}
# Define file sweep time.
# *Note file-sweep-time: general.
file-sweep-time TIME:INTERVAL;
# Set tar invocation command line.
# *Note tar-program: archivation.
tar-program PROG:STRING;
# Set umask.
# *Note umask: general.
umask MASK:OCTAL;
# Control implicit signature archivation.
# *Note archive-signatures: archivation.
archive-signatures ARG:BOOLEAN;
# Schedule generation of statistic reports.
# *Note statistics::.
stat-report-schedule TIME:CRONTAB-TIME;
# Generate statistic reports if one or more of these items
# changed.
# *Note statistics::.
statistics ITEMS:STRING;
# Service names that request scanning all spools.
# *Note all-spools: daemon.
all-spools ARG:LIST OF STRING;
# GPG home directory.
# *Note gpg-homedir::.
gpg-homedir ARG:STRING;
# Define SQL database.
# *Note sql::.
sql ID:STRING {
# Set the name of the configuration file to read.
config-file NAME:STRING;
# Set the name of the configuration file group to use.
config-group NAME:STRING;
# Set SQL server hostname or IP address.
host HOST:STRING;
# Set database name.
database DBNAME:STRING;
# Set SQL user name.
user NAME:STRING;
# Set SQL user password.
password ARG:STRING;
# File name of the Certificate Authority (CA) certificate.
ssl-ca FILE:STRING;
}
# Configure syslog logging.
# *Note syslog::.
syslog {
# Set syslog facility.
facility NAME:STRING;
# Tag syslog messages with this string.
tag STRING:STRING;
# Prefix each message with its priority.
print-priority ARG:BOOLEAN;
}
# Define message text.
# *Note templates::.
define-message IDENT:STRING TEXT:STRING;
# Create missing directories.
# *Note directory setup::.
create-directories ARG:BOOLEAN;
# Mode for created directories.
# *Note directory setup::.
directory-mode MODE:octal;
# Owner user and group for created directory.
# *Note directory setup::.
directory-owner UID:STRING GID:STRING;
# Set up archivation.
# *Note archivation::.
archive TYPE:STRING {
# Name of archive file or directory.
name FILE-OR-DIR:STRING;
# Define backup type.
# *Note backup-methods::.
backup TYPE:STRING;
# Mode for the archive directory.
# *Note directory-mode: archivation.
directory-mode MODE:OCTAL;
# Owner user and group for the archive directory.
directory-owner UID:STRING GID:STRING;
}
# Define data dictionary.
# *Note dictionaries::.
dictionary IDENT:STRING {
# Dictionary type.
type TYPE:STRING;
# Query template.
query STRING:STRING;
# Set dictionary parameters.
params ARG:LIST OF STRING;
}
# Define distribution spool.
# *Note spool::.
spool TAG:STRING {
# URL corresponding to this spool.
url ARG:STRING;
# Aliases.
alias ARG:LIST OF STRING;
# Source directory.
source DIR:STRING;
# Mode for the source directory.
# *Note source-mode: spool.
# *Note directory setup::.
source-mode MODE:OCTAL;
# Owner user and group for the source directory.
# *Note source-owner: spool.
# *Note directory setup::.
source-owner UID:STRING GID:STRING;
# Destination directory.
destination DIR:STRING;
# Mode for the destination directory.
# *Note destination-mode: spool.
# *Note directory setup::.
destination-mode MODE:OCTAL;
# Owner user and group for the destination directory.
# *Note destination-owner: spool.
# *Note directory setup::.
destination-owner UID:STRING GID:STRING;
# Define file sweep time.
file-sweep-time TIME:INTERVAL;
# Define data dictionary.
# See above.
dictionary IDENT:STRING { ... }
# Set up archivation.
archive TYPE:STRING { ... }
# Configure notification.
notify-event { ... }
}
6 'Wydawca' invocation summary.
*******************************
This chapter presents a short reference of all 'wydawca' command line
options. The entries are sorted alphabetically by their long option
name. Where no long option exists, short option is used instead.
'--config-file=FILE'
'-c FILE'
Use FILE instead of the default configuration file.
*Note The '--config-file' option: config-file.
'--config-help'
Display a concise summary of the available configuration
directives. This does not include statements specific for
particular loadable modules. To display these, use the
'--module-help' option (*note -module-help: modules.).
'--cron'
Run in cron mode. Implies '--syslog'. *Note cron: starting.
*Note The '--syslog' option: stderr.
'--daemon'
Run in daemon mode. *Note daemon: starting.
'--debug=N'
'-dN'
Set the debugging level to N. The argument is optional. If
specified, it must follow the short option immediately, with no
whitespace between them. When used with the long option, the
equals sign must be used.
Without argument, increases the current debugging level by 1. For
compatibility with previous version, '-d' options can be clustered.
E.g. '-ddd' is equivalent to '-d3'.
*Note The '--debug' option: debug.
'--define=NAME[=VALUE]'
'-D NAME[=VALUE]'
Define the preprocessor symbol NAME as having VALUE, or empty.
*Note Preprocessor::.
'--dump-grammar-trace'
Dump configuration grammar traces. This is useful for debugging
'wydawca' configuration file parser.
'--dump-lex-trace'
Dump lexical analyzer traces. This is useful for debugging
'wydawca' configuration file parser.
'--dry-run'
'-n'
"Dry-run mode": do nothing, print almost everything. This option
implies '--debug=1 --stderr'.
*Note The dry-run mode: dry-run.
'-E'
Dump the preprocessed configuration to stdout and exit. *note
Preprocessor::.
'--force'
Force start-up, even if running as root or if the PID file already
exists.
'--foreground'
Remain in the foreground. This is mostly for debugging 'wydawca'.
'--help'
'-h'
Print a concise usage summary and exit.
'--include-directory=DIR'
'-I DIR'
Add DIR to include search path.
*Note #include: Pragmatic Comments. *Note Preprocessor::.
'--lint'
'-t'
Parse configuration file, report any errors on the standard error
and exit with code 0, if the syntax is OK, and with code 1
otherwise.
*Note The '--lint' option: lint.
'--module-help=FILE'
Loads module FILE (*note modules::) and displays help about its
configuration. If FILE is an absolute or relative pathname, it
will be loaded as is. Otherwise, 'wydawca' will search for module
FILE in its default library load path (*note library search
path::).
'--no-preprocessor'
Disable preprocessor. *note Preprocessor::.
'--preprocessor=COMMAND'
Use COMMAND instead of the default preprocessor. *note
Preprocessor::.
'--source=NAME'
'-s NAME'
Process only the spool with the given source name. This option may
be given multiple times, to select several spools by their source
names.
'--spool=TAG'
'-S TAG'
Process only spool with the given tag. This option may be given
multiple times, to select several spools by their tag names.
'--stderr'
'-e'
Log to the standard error.
*Note The '--stderr' option: stderr.
'--syslog'
Log all diagnostics to syslog.
*Note The '--syslog' option: stderr.
'--version'
'-V'
Print the program version and exit.
7 How to Report a Bug
*********************
Email bug reports to <bug-wydawca@gnu.org.ua>.
As the purpose of bug reporting is to improve software, please be
sure to include a detailed information when reporting a bug. The
minimum information needed is:
* Program version you use (see the output of 'wydawca --version'.
* A description of the bug.
* Conditions under which the bug appears.
* It is often helpful to send the contents of 'config.log' file along
with your bug report. This file is created after running
'./configure' in 'wydawca' source root directory.
Appendix A Architecture of the Wydawca
**************************************
This appendix outlines the structure of the program. It serves as a
short reminder for debugging the program.
A running 'wydawca' process consists of at least four threads. Each
upload is processed by its dedicated thread. Additional threads can be
strarted to perform some specific tasks.
If the operating system permits, each thread is assigned a name.
Apart from the main thread, names of each thread begin with uppercase
letters WY plus underscore.
On a GNU/Linux system the name of a thread can be read from
'/proc/PID/task/TID/comm', where PID is the PID of the 'wydawca' process
and TID is the thread identifier.
The following table describes each thread:
'wydawca'
The main thread. It starts all other threads and waits for
signals. When it exits, all other threads are terminated as well.
'WY_listener'
The workhorse of the project. Listens on inotify descriptor and
TCP socket for incoming notification events. This thread keeps a
table of uploaded files, which is updated each time an inotify
event is reported. Uploaded files are verified and ordered into
triplets. Once a triplet is completed, a separate 'WY_triplet'
thread is started in order to process it.
If an incoming connection appears on upload notification socket
(*note upload notification::), a 'WY_tcpmux' thread is started to
handle it.
'WY_tricleaner'
Keeps track of registered triplets and removes expired ones.
'WY_stat'
This thread is responsible for statistic logging and notification.
'WY_connwatch'
This thread is started by if the legacy upload notification is
enabled (*note listen: daemon.). It enforces idle timeout for all
started upload notification threads ('WY_tcpmux' instances).
'WY_tcpmux'
Serves a particular notification upload connection. The number of
threads of this type is limited by the 'max-connections'
configuration file statement (*note max-connections: daemon.).
'WY_triplet'
Processes a triplet. A separate thread of this type is started by
'WY_listener' for each valid triplet it detects.
Event timestamps in WY_stat
===========================
On GNU/Linux systems the events generated by the 'WY_stat' thread may
appear to happen one second prior to their scheduled time. This happens
if the software reporting the events uses 'time'(2) instead of
'gettimeofday'(2) for time reporting. The internal timekeeping
mechanism of the linux kernel is designed so that the number of seconds
returned by 'time' may be one less than the 'tv_sec' value after return
from 'gettimeofday', if the two functions would be called the same
instant(1).
The two known cases are the legacy 'syslogd' used by default on
Slackware systems, and the 'Sendmail' MTA.
Since the results returned by 'gettimeofday' are more accurate, it
was decided to leave this feature as it is, instead of installing
workarounds of dubious nature just to satisfy older software.
---------- Footnotes ----------
(1) See
<https://stackoverflow.com/questions/22917318/time-and-gettimeofday-return-different-seconds>,
for details
Appendix B GNU Free Documentation License
*****************************************
Version 1.2, November 2002
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.
It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless
of subject matter or whether it is published as a printed book. We
recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it can
be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The
"Document", below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as "you". You accept
the license if you copy, modify or distribute the work in a way
requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document
is in part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or
of legal, commercial, philosophical, ethical or political position
regarding them.
The "Invariant Sections" are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in the
notice that says that the Document is released under this License.
If a section does not fit the above definition of Secondary then it
is not allowed to be designated as Invariant. The Document may
contain zero Invariant Sections. If the Document does not identify
any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed
of pixels) generic paint programs or (for drawings) some widely
available drawing editor, and that is suitable for input to text
formatters or for automatic translation to a variety of formats
suitable for input to text formatters. A copy made in an otherwise
Transparent file format whose markup, or absence of markup, has
been arranged to thwart or discourage subsequent modification by
readers is not Transparent. An image format is not Transparent if
used for any substantial amount of text. A copy that is not
"Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available DTD, and standard-conforming
simple HTML, PostScript or PDF designed for human modification.
Examples of transparent image formats include PNG, XCF and JPG.
Opaque formats include proprietary formats that can be read and
edited only by proprietary word processors, SGML or XML for which
the DTD and/or processing tools are not generally available, and
the machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, "Title
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
A section "Entitled XYZ" means a named subunit of the Document
whose title either is precisely XYZ or contains XYZ in parentheses
following text that translates XYZ in another language. (Here XYZ
stands for a specific section name mentioned below, such as
"Acknowledgements", "Dedications", "Endorsements", or "History".)
To "Preserve the Title" of such a section when you modify the
Document means that it remains a section "Entitled XYZ" according
to this definition.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These
Warranty Disclaimers are considered to be included by reference in
this License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and
has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. You
may not use technical measures to obstruct or control the reading
or further copying of the copies you make or distribute. However,
you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow the
conditions in section 3.
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than 100, and
the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also clearly
and legibly identify you as the publisher of these copies. The
front cover must present the full title with all words of the title
equally prominent and visible. You may add other material on the
covers in addition. Copying with changes limited to the covers, as
long as they preserve the title of the Document and satisfy these
conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a machine-readable
Transparent copy along with each Opaque copy, or state in or with
each Opaque copy a computer-network location from which the general
network-using public has access to download using public-standard
network protocols a complete Transparent copy of the Document, free
of added material. If you use the latter option, you must take
reasonably prudent steps, when you begin distribution of Opaque
copies in quantity, to ensure that this Transparent copy will
remain thus accessible at the stated location until at least one
year after the last time you distribute an Opaque copy (directly or
through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of copies,
to give them a chance to provide you with an updated version of the
Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you
release the Modified Version under precisely this License, with the
Modified Version filling the role of the Document, thus licensing
distribution and modification of the Modified Version to whoever
possesses a copy of it. In addition, you must do these things in
the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of previous
versions (which should, if there were any, be listed in the
History section of the Document). You may use the same title
as a previous version if the original publisher of that
version gives permission.
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in
the Modified Version, together with at least five of the
principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you
from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below.
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document's
license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on the
Title Page. If there is no section Entitled "History" in the
Document, create one stating the title, year, authors, and
publisher of the Document as given on its Title Page, then add
an item describing the Modified Version as stated in the
previous sentence.
J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for
previous versions it was based on. These may be placed in the
"History" section. You may omit a network location for a work
that was published at least four years before the Document
itself, or if the original publisher of the version it refers
to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section
all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered
in their text and in their titles. Section numbers or the
equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled
"Endorsements" or to conflict in title with any Invariant
Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option designate
some or all of these sections as invariant. To do this, add their
titles to the list of Invariant Sections in the Modified Version's
license notice. These titles must be distinct from any other
section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text,
and a passage of up to 25 words as a Back-Cover Text, to the end of
the list of Cover Texts in the Modified Version. Only one passage
of Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document
already includes a cover text for the same cover, previously added
by you or by arrangement made by the same entity you are acting on
behalf of, you may not add another; but you may replace the old
one, on explicit permission from the previous publisher that added
the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination all
of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique
by adding at the end of it, in parentheses, the name of the
original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the
combined work.
In the combination, you must combine any sections Entitled
"History" in the various original documents, forming one section
Entitled "History"; likewise combine any sections Entitled
"Acknowledgements", and any sections Entitled "Dedications". You
must delete all sections Entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the documents
in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of a
storage or distribution medium, is called an "aggregate" if the
copyright resulting from the compilation is not used to limit the
legal rights of the compilation's users beyond what the individual
works permit. When the Document is included an aggregate, this
License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half
of the entire aggregate, the Document's Cover Texts may be placed
on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket
the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also
include the original English version of this License and the
original versions of those notices and disclaimers. In case of a
disagreement between the translation and the original version of
this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to
Preserve its Title (section 1) will typically require changing the
actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided for under this License. Any other
attempt to copy, modify, sublicense or distribute the Document is
void, and will automatically terminate your rights under this
License. However, parties who have received copies, or rights,
from you under this License will not have their licenses terminated
so long as such parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
<http://www.gnu.org/copyleft/>.
Each version of the License is given a distinguishing version
number. If the Document specifies that a particular numbered
version of this License "or any later version" applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If the
Document does not specify a version number of this License, you may
choose any version ever published (not as a draft) by the Free
Software Foundation.
B.1 ADDENDUM: How to use this License for your documents
========================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with
the Front-Cover Texts being LIST, and with the Back-Cover Texts
being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.
Concept Index
*************
This is a general index of all issues discussed in this manual
* Menu:
* #include: Pragmatic Comments. (line 369)
* #include_once: Pragmatic Comments. (line 388)
* #line: Pragmatic Comments. (line 393)
* /etc/hosts.allow: tcp-wrapper. (line 815)
* /etc/services: daemon. (line 752)
* access-violations, statistics: statistics. (line 1711)
* admin: mail-config. (line 2217)
* admin-address: mod_mailutils. (line 1960)
* alias: spool. (line 1431)
* all, statistics: statistics. (line 1769)
* all-spools: daemon. (line 764)
* allow-syslog-priority: tcp-wrapper. (line 823)
* allow-table: tcp-wrapper. (line 815)
* archivation methods: archivation. (line 1265)
* archivation, defined: archivation. (line 1258)
* archive: archivation. (line 1265)
* archive <1>: archivation. (line 1271)
* archive <2>: spool. (line 1510)
* archive-signatures: archivation. (line 1394)
* archives, statistics: statistics. (line 1738)
* authpriv, syslog facility: syslog. (line 848)
* backup: archivation. (line 1345)
* bad-detached-signature: event notification. (line 1907)
* bad-directive-signature: event notification. (line 1903)
* bad-ownership: event notification. (line 1899)
* bad-signatures, statistics: statistics. (line 1707)
* bad-triplets, statistics: statistics. (line 1724)
* block statement: Statements. (line 599)
* boolean value: Statements. (line 430)
* builtin: dictionaries. (line 1006)
* builtin dictionary: builtin type. (line 1117)
* c, -c short option, described: starting. (line 231)
* c, -c short option, summary: invocation. (line 2734)
* check-failure: event notification. (line 1911)
* check-script: verification. (line 1565)
* check-script <1>: verification. (line 1566)
* check:diagn: mail-config. (line 2275)
* check:result: mail-config. (line 2272)
* command line options: invocation. (line 2730)
* comment: dictionaries. (line 1054)
* Comments in a configuration file: Comments. (line 345)
* comments, pragmatic: Pragmatic Comments. (line 363)
* complete-triplets, statistics: statistics. (line 1715)
* config-file: sql. (line 890)
* config-file, --config-file option, described: starting. (line 231)
* config-file, --config-file option, summary: invocation. (line 2734)
* config-group: sql. (line 893)
* config-help, --config-help option, introduced: configuring.
(line 327)
* config-help, --config-help option, summary: invocation. (line 2740)
* configuration file statements: Statements. (line 411)
* configuration statements, reference: wydawca.conf. (line 2426)
* create-directories: directory setup. (line 1219)
* cron mode: operation modes. (line 181)
* cron, --cron option, described: starting. (line 252)
* cron, --cron option, summary: invocation. (line 2746)
* cron, syslog facility: syslog. (line 848)
* d, -d short option, described: starting. (line 274)
* D, -D short option, introduced: Preprocessor. (line 644)
* d, -d short option, summary: invocation. (line 2754)
* D, -D short option, summary: invocation. (line 2765)
* daemon: daemon. (line 738)
* daemon <1>: tcp-wrapper. (line 810)
* daemon mode: operation modes. (line 187)
* daemon, --daemon option, described: starting. (line 257)
* daemon, --daemon option, summary: invocation. (line 2751)
* daemon, syslog facility: syslog. (line 848)
* database: sql. (line 934)
* database, MySQL: sql. (line 868)
* database, SQL: sql. (line 868)
* date: statreports. (line 2145)
* debug, --debug option, described: starting. (line 274)
* debug, --debug option, summary: invocation. (line 2754)
* define, --define option, introduced: Preprocessor. (line 644)
* define, --define option, summary: invocation. (line 2765)
* define-message: templates. (line 2069)
* defining source and distribution directories: spool. (line 1403)
* deny-syslog-priority: tcp-wrapper. (line 826)
* deny-table: tcp-wrapper. (line 819)
* destination: spool. (line 1467)
* destination directory: overview. (line 128)
* destination-mode: spool. (line 1488)
* destination-owner: spool. (line 1496)
* dest_dir: dictionaries. (line 1043)
* dest_dir <1>: mail-config. (line 2246)
* detached signature: Intro. (line 84)
* detached signature <1>: overview. (line 163)
* detached signature <2>: overview. (line 163)
* dictionaries: dictionaries. (line 970)
* dictionary: overview. (line 153)
* dictionary <1>: dictionaries. (line 977)
* dictionary <2>: spool. (line 1514)
* dir: dictionaries. (line 1039)
* dir <1>: mail-config. (line 2244)
* directory, archivation: archivation. (line 1294)
* directory, destination: overview. (line 128)
* directory, distribution: overview. (line 128)
* directory, source: Intro. (line 73)
* directory, source <1>: overview. (line 128)
* directory, upload: overview. (line 128)
* directory-mode: directory setup. (line 1223)
* directory-mode <1>: archivation. (line 1368)
* directory-owner: directory setup. (line 1233)
* directory-owner <1>: archivation. (line 1376)
* distribution directory: overview. (line 128)
* distribution directory, defining: spool. (line 1403)
* distribution spool: spool. (line 1403)
* distribution verification: verification. (line 1559)
* dry-run, --dry-run option, described: starting. (line 282)
* dry-run, --dry-run option, summary: invocation. (line 2779)
* dump-grammar-trace, --dump-grammar-trace option, summary: invocation.
(line 2771)
* dump-lex-trace, --dump-lex-trace option, summary: invocation.
(line 2775)
* e, -e short option, described: starting. (line 242)
* E, -E short option, described: Preprocessor. (line 637)
* E, -E short option, introduced: configuring. (line 322)
* E, -E short option, summary: invocation. (line 2786)
* e, -e short option, summary: invocation. (line 2840)
* email:admin: mail-config. (line 2264)
* email:owner: mail-config. (line 2267)
* email:user: mail-config. (line 2269)
* enable: tcp-wrapper. (line 807)
* errors, statistics: statistics. (line 1701)
* escape sequence: Statements. (line 438)
* event: event notification. (line 1892)
* existing, backup method: archivation. (line 1359)
* expansion of undefined variables: Statements. (line 524)
* expired triplet: overview. (line 146)
* expired-triplets, statistics: statistics. (line 1727)
* external: dictionaries. (line 1013)
* external dictionary: external type. (line 1204)
* facility: syslog. (line 847)
* FDL, GNU Free Documentation License: Copying This Manual.
(line 2955)
* file-sweep-time: general. (line 668)
* file-sweep-time <1>: spool. (line 1518)
* finish: event notification. (line 1915)
* force, --force option, summary: invocation. (line 2790)
* foreground: general. (line 662)
* foreground, --foreground option, summary: invocation. (line 2794)
* from-address: mod_mailutils. (line 1950)
* ftp, syslog facility: syslog. (line 848)
* gpg-homedir: general. (line 676)
* gpg-sign: statreports. (line 2135)
* gpg-sign <1>: mail-config. (line 2229)
* group: user privileges. (line 727)
* h, -h short option, described: starting. (line 295)
* h, -h short option, summary: invocation. (line 2797)
* help, --help option, described: starting. (line 295)
* help, --help option, summary: invocation. (line 2797)
* here-document: Statements. (line 529)
* host: sql. (line 927)
* I, -I short option, introduced: Preprocessor. (line 648)
* I, -I short option, summary: invocation. (line 2801)
* idle-timeout: daemon. (line 773)
* implicit signature archivation: archivation. (line 1387)
* include-directory, --include-directory option, introduced: Preprocessor.
(line 648)
* include-directory, --include-directory option, summary: invocation.
(line 2801)
* incomplete triplet: overview. (line 146)
* incomplete-triplets, statistics: statistics. (line 1718)
* inotify: daemon. (line 741)
* inotify <1>: operation modes. (line 191)
* inotify <2>: spool. (line 1435)
* introduction: Intro. (line 67)
* invocation: starting. (line 231)
* invocation <1>: invocation. (line 2730)
* lint, --lint option, described: starting. (line 237)
* lint, --lint option, introduced: configuring. (line 311)
* lint, --lint option, summary: invocation. (line 2807)
* list: Statements. (line 569)
* listen: daemon. (line 748)
* listing, triplet: mail-config. (line 2280)
* local0 through local7, syslog facilities: syslog. (line 848)
* m4: Preprocessor. (line 614)
* mail notification: mod_mailutils. (line 1943)
* mail, syslog facility: syslog. (line 848)
* mail-statistics: statreports. (line 2097)
* mailer: mailer. (line 1984)
* mailer <1>: mailer. (line 1980)
* mailer URL: mailer. (line 1987)
* max-connections: daemon. (line 769)
* max-version: versions. (line 708)
* message: mail-config. (line 2212)
* message <1>: statreports. (line 2116)
* message <2>: mail-config. (line 2234)
* message <3>: mod_logstat. (line 2399)
* message template: templates. (line 2063)
* min-version: versions. (line 704)
* module: modules. (line 1801)
* module <1>: event notification. (line 1927)
* module-config: event notification. (line 1932)
* module-help, --module-help option, introduced: modules. (line 1861)
* module-help, --module-help option, summary: invocation. (line 2815)
* module-init: modules. (line 1854)
* module-load-path: modules. (line 1840)
* module-prepend-load-path: modules. (line 1846)
* multi-line comments: Comments. (line 353)
* MySQL databases: sql. (line 868)
* n, -n short option, described: starting. (line 282)
* n, -n short option, summary: invocation. (line 2779)
* name: archivation. (line 1297)
* never, backup method: archivation. (line 1364)
* nil, backup method: archivation. (line 1359)
* no-preprocessor, --no-preprocessor option, defined: Preprocessor.
(line 653)
* no-preprocessor, --no-preprocessor option, introduced: configuring.
(line 322)
* no-preprocessor, --no-preprocessor option, summary: invocation.
(line 2822)
* none, archivation: archivation. (line 1288)
* none, statistics: statistics. (line 1764)
* notification: notification. (line 1783)
* notification message template: templates. (line 2063)
* notify-event: spool. (line 1524)
* notify-event <1>: event notification. (line 1878)
* numbered, backup method: archivation. (line 1355)
* operation: overview. (line 120)
* operation mode: operation modes. (line 179)
* overview: overview. (line 120)
* owner: mail-config. (line 2221)
* params: dictionaries. (line 1057)
* password: sql. (line 940)
* PGP: Intro. (line 84)
* PGP <1>: overview. (line 153)
* PGP key: dictionaries. (line 970)
* PGP signature: statistics. (line 1708)
* pidfile: daemon. (line 780)
* pp-setup: Preprocessor. (line 625)
* pragmatic comments: Pragmatic Comments. (line 363)
* preprocessor: Preprocessor. (line 614)
* preprocessor, --preprocessor option, defined: Preprocessor.
(line 656)
* preprocessor, --preprocessor option, summary: invocation. (line 2825)
* print-priority: syslog. (line 858)
* project: dictionaries. (line 1024)
* project <1>: mail-config. (line 2240)
* project-owner: dictionaries. (line 991)
* project-owner <1>: project-owner-sql. (line 1080)
* project-uploader: dictionaries. (line 997)
* project-uploader-sql: project-uploader-sql.
(line 1099)
* query: dictionaries. (line 1019)
* quoted string: Statements. (line 438)
* read: mail-config. (line 2212)
* recipient: mail-config. (line 2208)
* release submission daemon: Intro. (line 93)
* rmsymlinks, statistics: statistics. (line 1744)
* s, -s short option, summary: invocation. (line 2829)
* S, -S short option, summary: invocation. (line 2835)
* Savane: sql type. (line 1073)
* signature files, archivation: archivation. (line 1387)
* signature, detached: Intro. (line 84)
* signature, detached <1>: overview. (line 163)
* simple statements: Statements. (line 411)
* simple, backup method: archivation. (line 1364)
* single-line comments: Comments. (line 345)
* source: spool. (line 1445)
* source directory: Intro. (line 73)
* source directory <1>: overview. (line 128)
* source directory, defining: spool. (line 1403)
* source, --source option, summary: invocation. (line 2829)
* source-mode: spool. (line 1448)
* source-owner: spool. (line 1456)
* source_dir: dictionaries. (line 1046)
* source_dir <1>: mail-config. (line 2247)
* spool: overview. (line 128)
* spool <1>: dictionaries. (line 1031)
* spool <2>: spool. (line 1410)
* spool <3>: mail-config. (line 2243)
* spool, --spool option, described: starting. (line 263)
* spool, --spool option, summary: invocation. (line 2835)
* sql: dictionaries. (line 1009)
* sql <1>: sql. (line 875)
* SQL databases: sql. (line 868)
* sql dictionary: sql type. (line 1063)
* ssl-ca: sql. (line 943)
* stat-report-schedule: statistics. (line 1661)
* stat:access_violations: statreports. (line 2150)
* stat:archives: statreports. (line 2158)
* stat:bad_signatures: statreports. (line 2149)
* stat:bad_triplets: statreports. (line 2154)
* stat:check-failures: statreports. (line 2161)
* stat:complete_triplets: statreports. (line 2151)
* stat:errors: statreports. (line 2147)
* stat:expired_triplets: statreports. (line 2155)
* stat:incomplete_triplets: statreports. (line 2152)
* stat:rmsymlinks: statreports. (line 2160)
* stat:symlinks: statreports. (line 2159)
* stat:triplet_success: statreports. (line 2156)
* stat:uploads: statreports. (line 2157)
* stat:warnings: statreports. (line 2148)
* statement, block: Statements. (line 599)
* statement, simple: Statements. (line 411)
* statements, configuration file: Statements. (line 411)
* statistics: event notification. (line 1915)
* statistics <1>: statistics. (line 1750)
* statistics <2>: statreports. (line 2125)
* statistics <3>: statistics. (line 1656)
* statistics <4>: mod_logstat. (line 2393)
* stderr, --stderr option, described: starting. (line 242)
* stderr, --stderr option, summary: invocation. (line 2840)
* string, quoted: Statements. (line 438)
* string, unquoted: Statements. (line 434)
* success: event notification. (line 1896)
* symlinks, statistics: statistics. (line 1741)
* syslog: syslog. (line 840)
* syslog priority, printing in diagnostics: syslog. (line 859)
* syslog tag, configuring: syslog. (line 854)
* syslog, --syslog option, described: starting. (line 242)
* syslog, --syslog option, summary: invocation. (line 2846)
* syslog, configuration: syslog. (line 836)
* t, -t short option, described: starting. (line 237)
* t, -t short option, summary: invocation. (line 2807)
* t, backup method: archivation. (line 1355)
* tag: syslog. (line 853)
* tar, archivation: archivation. (line 1291)
* tar-program: archivation. (line 1314)
* tcp-wrapper: tcp-wrapper. (line 794)
* TCPMUX notification: operation modes. (line 197)
* templates, notification messages: templates. (line 2063)
* Time Interval Specification: Statements. (line 586)
* triplet listing: mail-config. (line 2280)
* triplet, expired: overview. (line 146)
* triplet, incomplete: overview. (line 146)
* triplet-success, statistics: statistics. (line 1730)
* triplet:dir: mail-config. (line 2250)
* triplet:dist: mail-config. (line 2248)
* triplet:dist <1>: mail-config. (line 2253)
* triplet:ls:dir: mail-config. (line 2257)
* triplet:ls:full: mail-config. (line 2251)
* triplet:ls:sig: mail-config. (line 2255)
* triplet:ls:upload: mail-config. (line 2252)
* triplet:sig: mail-config. (line 2249)
* type: dictionaries. (line 1003)
* umask: general. (line 665)
* undefined variable, expansion: Statements. (line 524)
* upload directory: overview. (line 128)
* upload site: Intro. (line 73)
* uploads, statistics: statistics. (line 1733)
* url: dictionaries. (line 1035)
* url <1>: spool. (line 1441)
* url <2>: mail-config. (line 2242)
* URL, mailer: mailer. (line 1987)
* user: user privileges. (line 724)
* user <1>: dictionaries. (line 1049)
* user <2>: sql. (line 937)
* user <3>: mail-config. (line 2226)
* user <4>: mail-config. (line 2258)
* user:email: mail-config. (line 2263)
* user:name: mail-config. (line 2260)
* user:real_name: mail-config. (line 2262)
* v, -v short option, described: starting. (line 295)
* V, -V short option, summary: invocation. (line 2851)
* variable expansion: Statements. (line 477)
* variables: Statements. (line 477)
* variables in admin notifications: statreports. (line 2143)
* verification: verification. (line 1559)
* version, --version option, described: starting. (line 295)
* version, --version option, summary: invocation. (line 2851)
* version-control Emacs variable: archivation. (line 1346)
* warnings, statistics: statistics. (line 1704)
* WYDAWCA_DEST: verification. (line 1579)
* WYDAWCA_DIST_FILE: verification. (line 1588)
* WYDAWCA_SOURCE: verification. (line 1575)
* WYDAWCA_SPOOL: verification. (line 1572)
* WYDAWCA_TRIPLET_BASE: verification. (line 1585)
* WYDAWCA_URL: verification. (line 1582)