Documentation for "expecto"

Download the whole documentation as one plain text file


3. Usage and Options

3.1. Usage with Cron Jobs

The expecto utility works as a filter. That is, it reads input data from standard input (stdin) and writes output data to standard output (stdout), if any. The name of the template file must be given on the command line.

By default, most cron jobs write their output to the standard output channel (and possibly also to the standard error channel) and rely on the cron daemon to capture it and send an email message to the owner of the crontab. This makes it easy to add expecto to the game: Just append a pipe symbol to your crontab entry, followed by the expecto command. See below for details.

However, FreeBSD's periodic framework is a little different: By default it does not produce any output for the cron daemon, but sends the email messages itself. This behaviour can be configured. For example, in order to let it send the "daily run output" to the standard output channel, you have to add the following line to /etc/periodic.conf (create this file if it doesn't exist yet):

daily_output=""

Please refer to the "periodic.conf" manual page for details.

As mentioned above, the easiest way to use expecto is to add it to your cron job with a pipe symbol. For example, FreeBSD has the following command in its master crontab (/etc/crontab) to start the daily run:

periodic daily

When using expecto with an appropriate template, the command should be modified like this (assuming the template file is called "daily-template"):

periodic daily | expecto daily-template

Additionally, you might want to log the original output in a file, so you can look at it if necessary:

periodic daily | tee -a /var/log/daily.log | expecto daily-template

Important notes:

If this cronjob generates some output, the cron daemon will automatically send it to the owner of the crontab, and the subject will be the command line of the entry (or the beginning of it, if the line is very long).

However, you might want to prefer a different mail subject, such as the usual "daily run output", or something that attracts more attention like "WARNING: Unexpected output from cron job!". You also might want to send the output to a different user, such as an alias like "admins" that expands to several people. You can do all of that by appending another command to the pipe:

periodic daily | tee -a /var/log/daily.log | expecto daily-template | mail -E -s "daily run" admins

This uses the "mail" command to send the message explicitly. The above invocation works for FreeBSD. On other operating systems, you might have to use different command line options; please consult the manual page of your "mail" or "mailx" command. As you probably guessed, the -s option specifies the subject, and the last argument specifies the recipient of the message. The -E option instructs the mail utility to not send a message if it would be empty.

Don't worry: If anything goes wrong, the owner of the crontab (i.e. you) will always get an email message with the standard error output (stderr) of the job. For example, if expecto crashes (I certainly hope it doesn't), python prints a backtrace to stderr. Similarly, if the mail tool cannot send the message for some reason, it prints an error message to stderr. All of that will be picked up by the cron daemon and mailed to you.

Alternative: Aliases

Alternatively, you can create a mail alias that performs the filtering. Actually this is not recommended because it has drawbacks. If possible, use the method above, i.e. change the crontab entry. Only if that's not possible for some reason, the following might work for you.

This section assumes that you are using a standard installation of sendmail. Things might be different when you're using a different MTA such as postfix.

Let's start with an example. Add the following line to your alias file (usually /etc/mail/aliases):

daily-output: "|/usr/local/bin/expecto daily-template | mail -E -s daily_foo_bar root"

This example assumes that you use sendmail with standard /bin/sh as your proc mailer (this is the default), not smrsh. After modifying the aliases file, don't forget to rebuild the alias database with the command newaliases.

In order to actually use that alias, you have to tell the periodic cron job to send its output to the alias name. Add the following line to /etc/periodic.conf (create it if it doesn't exist yet):

daily_output="daily-output"

However, this method (i.e. using an alias) has some drawbacks. In particular, the commands inside aliases are executed by an unprivileged user (commonly called "mailnull" when using sendmail). This can have some undesirable side-effects. Also, there are some restrictions that apply to commands in alias expansions (sendmail calls this the prog mailer).

Important: If you use expecto within an alias expansion, it will also receive a "From" line and the email headers. That means that your template must be prepared to accept those additional lines, otherwise the match will fail right from the start.



[Valid XHTML 1.0]