3.4 Notification

Pies provides a notification mechanism, which can be used to send email messages when components terminate. The exact contents of such notifications and the list of their recipients may depend on the exit code which the component returned. Notification is configured by ‘notify’ and ‘message’ statements in a ‘return-code’ block.

Config: return-code: notify email-string

Send email notification to each address from email-string. The latter is a comma-separated list of email addresses, e.g.:

notify "root@localhost,postmaster@localhost";

Config: return-code: message string

Supply the email message text to be sent. String must be a valid RFC 822 message, i.e. it must begin with message headers, followed by an empty line and the actual message body.

The message may contain variable data in the form of variable references. A variable is an entity that holds some data describing the event that occurred. Meta-variables are referenced using the following construct:

${name}

where name is the name of the variable. Before actually sending the message, each occurrence of this construct is removed from the text and replaced by the actual value of the referenced variable. For example, the variables ‘component’ and ‘retcode’ expand to the name of the exited component and its exit code, correspondingly. Supposing that ‘component’ is ‘ftpd’ and ‘retcode’ is 76, the following fragment:

Subject: ${component} exited with code ${retcode}

will become:

Subject: ftpd exited with code 76

The table below lists all available variables and their expansions:

Variable	Expansion
canonical_program_name	‘pies’
program_name	Program name of the pies binary.
package	Package name (‘GNU Pies’).
instance	Instance name (see instances).
version	Package version (1.8).
component	Name of the terminated component.
termination	Termination cause (see below).
retcode	Component exit code (or signal number, if exited on signal), in decimal.

Table 3.4: Notification Variables

The ‘termination’ variable is set so as to facilitate its use with the ‘retcode’ variable. Namely, its value is ‘exited with’, if the component exited and ‘terminated on signal’, if it terminated on a signal. Thus, using

${termination} ${retcode}

results in a correct English sentence. This message, however, cannot be properly internationalized. This will be fixed in the future versions.

If message statement is not given, the following default message is used instead:

From: <>
X-Agent: ${canonical_program_name} (${package} ${version})
Subject: Component ${component} ${termination} ${retcode}.

Notification messages are sent using an external program, called mailer. By default it is /usr/sbin/sendmail. You can change it using the following configuration statement:

Config: mailer-program prog

Use prog as a mailer program. The mailer must meet the following requirements:

1. It must read the message from its standard input.
2. It must treat the non-optional arguments in its command line as recipient addresses.

For example, the following statement instructs pies to use exim as a mailer:

mailer-program /usr/sbin/exim;

By default, the mailer program is invoked as follows:

/usr/sbin/sendmail -oi -t rcpts

where rcpts is a whitespace-separated list of addresses supplied in the ‘notify’ statement.

The mailer command may be altered using ‘mailer-command-line’ statement:

Config: mailer-command-line string

Set mailer command line. Notice, that string must include the command name as well. The ‘mailer-program’ statement supplies the full name of the binary which will be executed, while the first word from the ‘mailer-command-line’ argument gives the string it receives as ‘argv[0]’.

The example below shows how to use this statement to alter the envelope sender address:

mailer-command-line "sendmail -f root@domain.com -oi -t";