Wydawca
	Release Submission Daemon	Sergey Poznyakoff

• Main
• Downloads
• Documentation

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 (see 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. See 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’.

See statreports, for a detailed discussion. See also 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 (see 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 (see 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 (see variable expansion) within it. The message text may be specified either in place within the configuration directive it belongs to (see 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 (see 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 (see 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 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 (see gpg-homedir).

The statistics message is sent to addresses configured by admin-address statement (see admin-address).

The variables available for use in statistic reports are:

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 (see admin-address).

owner

Administrators of the project for which the files where uploaded. Their addresses are retrieved from the ‘project-owner’ dictionary (see 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 (see 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 (see templates).

The following macro-variables are expanded in the message texts:

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.

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 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. See 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 (see 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;

${triplet:ls:dist}
${triplet:ls:sig}
${triplet:ls:dir}