extsmail Manual

Operation

extsmail has two executable programs.

The extsmail program masquerades as sendmail when messages are sent; effectively, it notes the command line switches passed to it, and puts those, and the message contents read from stdin, into a file in a spool directory.

extsmaild is the delivery program. If called without -m specified, or if -m batch is specified, extsmaild operates in batch mode, running as a foreground process and terminating after trying to send all messages; it returns 0 if all messages were sent successfully and 1 if any messages remain unsent. If called with the -m daemon switch, extsmaild operates as a long running daemon; it monitors the spool directory and when it notices changes to the directory (or a fixed period has elapsed) it tries to send any unsent messages. This means that even on unreliable networks, extsmaild can easily be left alone and relied upon to ultimately send all messages - without manual intervention.

Integration

To use extsmail, you need to alter any programs which send e-mail via sendmail to instead call extsmail. You then need to run extsmaild when convenient (or, if you prefer, permanently as a daemon) to send messages.

A separate page shows how other apps can be configured to use extsmail.

Configuration

extsmail can operate as either a system-wide application or as a per-user application. In the former case extsmail expects to find configuration files in /etc/extsmail; in the latter case in ~/.extsmail. Inside the configuration directory must be at least two files: conf and externals. Both configuration files are whitespace insensitive, and quotes begin with // and run until the end of the line.

conf is the extsmail-wide configuration file. Currently it only defines the location of the spool directory. A per-user conf file may look as follows:

$ cat ~/.extsmail/conf
spool_dir = "~/.extsmail/spool_dir"

externals is the file which tells extsmaild which external commands should be run when sending e-mail. There are two components within such a file. An external records the command required to send an e-mail; it is typically an ssh command invoking sendmail on a remote machine. A group specifies when it matches against an individual message (if no match / reject criteria are specified, a group matches every message), and a sequence of externals which will be tried, in order, to send that message.

The simplest externals file which sends e-mails via ssh looks as follows:

$ cat ~/.extsmail/externals
group {
    external mymachine {
        sendmail = "/usr/bin/ssh -q -C -l user mymachine.net /usr/sbin/sendmail"
    }
}

where mymachine is a human-friendly name given to an external (it does not effect processing), and user is your username on the remote machine mymachine.net.

If you have access to a backup machine bk.mymachine.net, which should only be used if mymachine.net is not processing e-mail, your externals file may look as follows:

$ cat ~/.extsmail/externals
group {
    external mymachine {
        sendmail = "/usr/bin/ssh -q -C -l user mymachine.net /usr/sbin/sendmail -t"
    }

    external bk {
        sendmail = "/usr/bin/ssh -q -C -l user bk.mymachine.net /usr/sbin/sendmail -t"
    }
}

Groups can begin with match and reject clauses which force e-mail to be routed to particular servers. For example if you wish all e-mail sent to anyone at foo.com to be sent via your shell.foo.com account while all other e-mail should be sent via mymachine.net your externals file might look as follows:

$ cat ~/.extsmail/externals
group {
    match header "^To:.*@foo.com"

    external foo {
        sendmail = "/usr/bin/ssh -q -C -l user shell.foo.com /usr/sbin/sendmail -t"
    }
}

group {
    external mymachine {
        sendmail = "/usr/bin/ssh -q -C -l user mymachine.net /usr/sbin/sendmail -t"
    }
}

Matches are normal extended POSIX regular expressions, and currently match anywhere within the entire header (hence why the ^ character is used to ensure that only the to header is matched). Matches can be negated by using the reject keyword instead of match. As this example also suggests, groups are tried in order; only if the first group has failed to match will the second group be tried.

This section has aimed to enumerate the most common uses of extsmail; a list of more exotic scenarios is also maintained.