extsmail

[RSS feed]

Overview

extsmail enables the robust sending of e-mail to external commands. extsmail masquerades as the standard UNIX sendmail program, reading messages, and later piping them to user-defined commands. In a sense, extsmail can be thought of as a very simple tiny sendmail. A typical use is to allow e-mail to be piped via ssh to external servers running a full sendmail-compatible MTA. extsmail is designed to have sensible defaults, and configuring it is a one-off, quick job.

Should I use extsmail?

Fundamentally, extsmail is only of interest to those who use (or wish to use) traditional UNIX mechanisms to send e-mail. If one or more of the following then apply to you, extsmail might be the tool you're looking for:

In addition to its main purpose, extsmail allows priority lists to be defined, and also for e-mails to be routed to different servers depending on the e-mail content. The former feature allows one to designate a preferred server to send e-mail, but to use a backup server if the preferred server is down. The latter feature allows e-mails sent to different e-mail addresses, for example, to be routed to different servers; this is often useful for mailing lists which require mail to be sent from machines on a specific IP range.

Download

extsmail is released under a BSD / MIT style licence.

Formal releases:

Development of extsmail uses git. If you wish to contribute to extsmail, it is recommended that you work with a check-out of the repository. You can get a copy with the following command: 

$ git clone git://github.com/ltratt/extsmail.git
You can also view extsmail's online git repository. Patches are always gratefully received.

60 second install instructions

If you don't like reading manuals, most per-user configurations of extsmail can be accomodated with the following commands: 
$ ./configure
$ make
$ make install
$ mkdir -p ~/.extsmail
$ echo spool_dir = \"~/.extsmail/spool_dir\" > ~/.extsmail/conf
Assuming you want to send e-mail to another machine via ssh, you then need to create the file ~/.extsmail/externals and put in the following configuration: 
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.

Finally you need to run extsmail as a daemon so that it sends your mail: 

$ extsmail -m daemon
You might want to put this command in a start-up script.

And with that you're done. If you want to do something more complex you'll need to read the detailed instructions (extsmail comes with complete man page documentation), but the above works perfectly well for the majority of cases.

Install

extsmail is a C application. It should be trivially portable to any POSiX compliant operating system. It can be installed as follows: 
$ ./configure
$ make
$ make install
Please note that if, and only if, you are building from the git repository you will first need to execute make -f Makefile.bootstrap to build the configure script.

Documentation

FAQ:FAQ
Man pages:extsmail(1), extsmail.conf(1), extsmail.externals(1), extsmaild(1)
Other:Configuring other apps to use extsmail, Exotic scenarios using extsmail

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"
    }

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

Group's 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"
    }
}

group {
    external mymachine {
        sendmail = "/usr/bin/ssh -q -C -l user mymachine.net /usr/sbin/sendmail"
    }
}
$
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.

Related programs

This section lists any other pieces of software which have similar functionality to extsmail. You may find that one of them is better suited to your purposes. Contributions are welcome.