path: root/doc/wydawca.texi
authorSergey Poznyakoff <>2007-09-06 09:30:05 (GMT)
committer Sergey Poznyakoff <>2007-09-06 09:30:05 (GMT)
commitafd4995c30c273a02f81e80a972688936907853a (patch) (side-by-side diff)
tree5b18b5c7bde6efe3e1c51d892753761ae2645432 /doc/wydawca.texi
parent36ec2dca7633f984351d683b8b17b6cc85ed313c (diff)
git-svn-id: file:///svnroot/wydawca/trunk@315 6bb4bd81-ecc2-4fd4-a2d4-9571d19c0d33
Diffstat (limited to 'doc/wydawca.texi') (more/less context) (ignore whitespace changes)
1 files changed, 252 insertions, 9 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 14cdbe9..cc7b04c 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -96,8 +96,15 @@ How to Configure @command{wydawca}.
* access methods::
* archivation::
* directory pairs::
+* statistics::
* notification::
+Mail Notification
+* mailer::
+* admin notification::
+* user notification::
@end detailmenu
@end menu
@@ -937,16 +944,237 @@ statistics all errors warnings
@node notification
@section Mail Notification
+@cindex mail notification
While running, @command{wydawca} keeps track of certain events
occurring, such as, for example, broken @acronym{PGP} signatures or
file uploads attempted by unauthorized users. The utility can notify,
via email, project administrators about any of those events that
concern their projects. Additionally, the system administrator can
choose to obtain via email the execution statistics, described in the
-previous section. This section describes how to configure
-@command{wydawca} to send such notifications.
+previous section.
+@kwindex from-address
+ The sender email for these notifications can be set using the
+@code{from-address} statement, e.g.:
+@end smallexample
+It is not strictly necessary to specify it, however. In the absense of
+@code{from-address} statement, the sender email will be constructed
+from the name of the user @command{wydawca} runs as (usually
+@samp{root}) and the full domain name of the machine it runs at.
+* mailer::
+* admin notification::
+* user notification::
+@end menu
+@node mailer
+@subsection Mailer
+@cindex mailer
+@kwindex mailer
+ To send messages @command{wydawca} uses a special logical entity
+called @dfn{mailer}. It is set in the configuration file using
+@code{mailer} keyword:
+mailer @var{url}
+@end smallexample
+@cindex @acronym{URL}, mailer
+@cindex mailer @acronym{URL}
+ A mailer @acronym{URL} begins with a protocol specification.
+Two protocol specifications are currently supported: @samp{sendmail}
+and @samp{smtp}. The former means to use a
+@command{sendmail}-compatible program to send mails. Such a program
+must be able to read mail from its standard input and must support the
+following options:
+@table @option
+@item -oi
+Do not treat '.' as message terminator.
+@item -f @var{addr}
+Use @var{addr} as the address of the sender.
+@item -t
+Get recipient addresses from the message.
+@end table
+These conditions are met by most existing @acronym{MTA} programs, such
+as @command{exim} or @command{postfix} (to say nothing of
+@command{sendmail} itself).
+Following the protocol specification is the @dfn{mailer location}, which
+is separated from it with a colon. For the @samp{sendmail} protocol,
+the mailer location sets the full file name of the sendmail-compatible
+@acronym{MTA} binary, for example:
+mailer sendmail:/usr/sbin/sendmail
+@end smallexample
+A special form of a sendmail @acronym{URL}, consisting of protocol
+specification only (@samp{sendmail:}) is also allowed. It means
+``use the sendmail binary from the @code{_PATH_SENDMAIL}
+macro in your @file{/usr/include/paths.h} file''. This is the default
+The @samp{smtp} protocol means to use an @acronym{SMTP} server directly.
+In this case, the mailer location consists of two slashes,
+followed by the @acronym{IP} address or host name of the @acronym{SMTP}
+server, and, optionally, the port number. If the port number is
+present, it is separated from the rest of @acronym{URL} by a colon.
+For example:
+mailer smtp://
+mailer smtp://
+@end group
+@end smallexample
+@node admin notification
+@subsection Admin Notification
+@kwindex mail-admin-stat
+ Sending notifications to the system administrator is enabled by
+@code{mail-admin-stat} statement. It takes as its argument a list of
+statistics keywords as described in @ref{statistics}. The notification
+will be sent only if statistics counters for at least one of the
+requested categories are not zero. For example, the following
+statement requires sending notifications only if there ocurred any
+errors or access violation attempts, or any bad signature was uploaded:
+mail-admin-stat errors access-violations bad-signatures
+@end smallexample
+ The recipient address for these notifications is set using
+@code{admin-address} statement. Its argument is either a single
+@acronym{RFC} 822 email address, or a comma-separated list of such
+addresses, e.g.:
+@end smallexample
+@kwindex admin-stat-message
+ Finally, the text of the notification is given using
+@code{admin-stat-message} statement. As any block statement,
+it ends with an @code{end} keyword on a line by itself. The lines
+between @code{admin-stat-message} and @code{end} statements compose
+the notification text. This text must consist of two parts, separated
+by a single empty line. The part before the empty line gives any
+@acronym{RFC} 822 headers, and the part after it supplies the email
+body. It is important that both parts be always present. If you do not
+wish to supply any headers, simply begin the message text with an
+empty line. Following is a simple example of the
+@code{admin-stat-message} statement:
+Subject: Wydawca stats
+On my recent run I have noticed some events that may
+need your attention.
+@end smallexample
+@cindex meta-variables in @code{admin-stat-message}
+ Any occurrence of @samp{%@{@var{name}@}} in the text is replaced
+with the value of the meta-variable @var{name}. If such meta-variable
+is not defined, this string is passed unchanged. The meta-variables
+available for use in @code{admin-stat-message} text are:
+@multitable @columnfractions 0.50 0.50
+@headitem Variable @tab Replaced with
+@kwindex date
+@item date @tab Current date and time in the current locale.
+@kwindex stat:errors
+@item stat:errors @tab Number of errors detected.
+@kwindex stat:warnings
+@item stat:warnings @tab Number of warnings reported.
+@kwindex stat:bad_signatures
+@item stat:bad_signatures @tab Number of bad signatures detected.
+@kwindex stat:access_violations
+@item stat:access_violations @tab Number of access violation attempts.
+@kwindex stat:complete_triplets
+@item stat:complete_triplets @tab Number of complete triplets
+@kwindex stat:incomplete_triplets
+@item stat:incomplete_triplets @tab Number of incomplete triplets left
+ in the source directory.
+@kwindex stat:bad_triplets
+@item stat:bad_triplets @tab Number of bad triplets seen.
+@kwindex stat:expired_triplets
+@item stat:expired_triplets @tab Number of expired triplets.
+@kwindex stat:triplet_success
+@item stat:triplet_success @tab Number of successfully processed
+@kwindex stat:uploads
+@item stat:uploads @tab Number of successful uploads.
+@kwindex stat:archives
+@item stat:archives @tab Number of archivations performed.
+@kwindex stat:symlinks
+@item stat:symlinks @tab Number of symbolic links created.
+@kwindex stat:rmsymlinks
+@item stat:rmsymlinks @tab Number of symbolic links removed.
+@end multitable
+ These macro-variables can make the notification text be more
+informative, as shown in the following example:
+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@}
+@end smallexample
+@node user notification
+@subsection User Notification
+@cindex mail notification, project admin
+ Project administrators can be notified via email about any of the
+following events:
+@table @code
+@kwindex success
+@item success
+ Successfull upload.
+@kwindex bad-ownership
+@item bad-ownership
+ An unauthorized user attempted to upload files for their project.
+@kwindex bad-directive-signature
+@item bad-directive-signature
+ The directive signature does not match the public key of the
+@kwindex bad-detached-signature
+@item bad-detached-signature
+ The detached signature does not match the public key of the
+@end table
@node wydawca.rc, invocation, configuring, Top
@chapter @command{Wydawca} configuration file.
@@ -957,7 +1185,7 @@ file statements.
@deffn {Wydawca Statement} archive @var{type} @var{archive-name} @
Defines archivation and backup methods for the destination
-directory. @xref{archivation}, for the detailed discussion. The
+directory. @xref{archivation}, for a detailed discussion. The
@var{type} specifies the archivation type:
@table @asis
@@ -1140,7 +1368,7 @@ This statement begins a MySQL database definition. It may contain
several substatements, defining how to access the database. The
statement ends with the @code{end} keyword on a line by itself.
-@xref{sql}, for the detailed description.
+@xref{sql}, for more information.
The @var{identifier} is the symbolic name that can be used in
subsequent configuration statements to refer to this @acronym{SQL}
@@ -1213,7 +1441,7 @@ defining source and distribution directories, and @var{statements} are
any optional archive and/or access method definitions, overriding the
global ones for this directory pair.
-@xref{directory pairs}, for the detailed discussion.
+@xref{directory pairs}, for more information.
The following statements must be present in a @code{directory} block:
@@ -1257,25 +1485,40 @@ a user.
@end deffn
@deffn {Wydawca Statement} admin-address @var{email}
+Sets email address or addresses to send administrator notification to.
+@xref{admin notification}.
@end deffn
@deffn {Wydawca Statement} from-address @var{email}
+Sets the sender address for mail notifications.
+@xref{notification}, for more information on this statement.
@end deffn
@deffn {Wydawca Statement} mail-admin-stat @var{condition-list}
+Defines statistics categories that trigger administrator
+@xref{admin notification}.
@end deffn
@deffn {Wydawca Statement} admin-stat-message
+Defines the text of administrator notification message.
+@xref{admin notification}.
@end deffn
@deffn {Wydawca Statement} user-message @var{condition}
@end deffn
+@deffn {Wydawca Statement} mailer @var{url}
+Sets the mailer @acronym{URL} to use.
+@xref{mailer}, for more information on mailers.
+@end deffn
@node invocation, Reporting Bugs, wydawca.rc, Top
@chapter @command{Wydawca} invocation summary.
@cindex invocation

Return to:

Send suggestions and report system problems to the System administrator.