kernel_Notes/Zim/Utils/mail_system/esmtp.txt

Content-Type: text/x-zim-wiki
Wiki-Format: zim 0.4
Creation-Date: 2011-05-22T20:29:36+08:00

====== esmtp ======
Created Sunday 22 May 2011

===== Introduction =====

esmtp is a user configurable **relay-only Mail Transfer Agent (MTA)** with a sendmail compatible syntax. It's based on libESMTP supporting the **AUTH** (including the CRAM-MD5 and NTLM SASL mechanisms) and the **StartTLS** SMTP extensions.

===== Configuration =====

This is a simple configuration file for a quick start:

__hostname = mail.myisp.com:25__
__username = "myself"__
__password = "secret"__
__starttls = enabled__

__mda "/usr/bin/procmail -d %T"__

If you have more than one SMTP account you have them automatically chosen for you:

identity myself@myisp.com
        hostname mail.myisp.com:25
        username "myself"
        password "secret"
        __starttls enabled__
        __default__

identity myself@anotherisp.com
        hostname smtp.anotherisp.com:25
        username "myself"
        password "secret"

mda "/usr/bin/procmail -d %T"

===== Configuration options =====

See the esmtprc man page for more detailed information on the configuration options.

===== Invocation =====

esmtp is command line compatible with sendmail.
See the esmtp man page for information on how to invoke it.

===== Interfacing to Mail User Agents =====

Most Mail User Agents (MUAs) will work without need to configuration provided that you install a** symbolic from /usr/sbin/sendmail to the esmtp executable**. This should already be taken care of by the install target of the makefile when building from source.

If by any reason it is not possible to have (such as no administrator privileges or the use of another MTA for local delivery) then you will have to **reconfigure your MUA **to use the esmtp executable instead.

===== Mutt =====

If not using a symbolic link to the esmtp executable you can make Mutt use esmtp by adding the following line to your __~/.muttrc__:

__set sendmail="/path/to/esmtp"__

Esmtp supports sendmail envelope sender__ -f __flag, and you are advised to always enable it by adding the following line to Mutt configuration file:

__set use_envelope_from=yes__

For debugging purposes you may prefer to put in your ~/.muttrc:

__set sendmail="/path/to/esmtp -v -X /tmp/esmtp.log"__

This will enable verbose output and logging of the traffic with the SMTP server.

===== Interfacing to Mail Delivery Agents =====

esmtp relies upon a **Mail Delivery Agent (MDA) for local mail delivery**, so you need one if you want to **avoid having another MTA for local delivery.**

Notice that at the moment esmtp does not honor mail aliases or .forward files.

To deliver to other users beside yourself, the MDA must be installed with **setuid** flag -- which is done by default in most Linux distributions.

==== Procmail ====

To use procmail with esmtp set the mda configuration value to:

__mda="/usr/bin/procmail -d %T"__

If the mail message doesn't have a Date: header, such as those generated by vixie-cron, neither esmtp or procmail will add one for you. A simple hack is to pipe the message through the __formail__ program (also part of the procmail distribution), such as:

__mda='/usr/bin/formail -a "Date: `date -R`" | /usr/bin/procmail -d %T'__

Or, alternatively, add the following rule to your .procmailrc:

__:0fw__
__* ! ^Date:__
__| formail -a "Date: `date -R`"__

===== Interfacing with other mail applications =====

==== Fetchmail ====

By default fetchmail delivers messages via SMTP to port 25 on the machine it is running. Because **esmtp has no SMTP server** if you are not using another MTA for local delivery then you will need to** configure fetchmail to use esmtp executable**. This is accomplished by adding the following lines to the top of your ~/.fetchmailrc:

__defaults__
__        mda "/path/to/esmtp -f %F %T"__

Since esmtp simply **forwards the mail to another MDA **you can avoid this redundant step by simply replacing the value inside the quotes above by whichever value you use on your [[~/.esmtprc.]]

===== Interfacing with particular mail servers =====

==== Gmail ====

First edit your** ~/.esmtprc** according to http://mail.google.com/support/bin/answer.py?answer=13287. It should look like this:

__identity username@gmail.com__
__        hostname smtp.gmail.com:587__
__        username "username@gmail.com"__
__        password "password"__
__        starttls required__

Since Gmail requires the use of the **StartTLS** extension, you'll need to add the **Cert-Authority (CA) root certificate **which signed Gmail server certificate.

You can follow the instructions to use Mozilla's CA cert bundle, found elsewhere in this document.

===== Using the StartTLS extension =====

TLS support in __libESMTP__ although usable is not yet as robust and featureful as the rest of the library. At the moment to use the StartTLS extension you will need to:

* create a __~/.authenticate__ directory for the certificates. All files and directories in ~/.authenticate (including itself) must be user-readable only, i.e., they must have 0600 and 0700 permissions respectively.
* put the certificate of the trusted Cert-Authority that signed the server certificate into __~/.authenticate/ca.pem__.
* if a client certificate is required by the server then put it (including the private key) into ~/.authenticate/private/smtp-starttls.pem or ~/.authenticate/host.name/private/smtp-starttls.pem. If your client certificate has a passphrase then it should be specificied with the certificate_passphrase configuration.
* enable (or require) the StartTLS extension with the starttls configuration option. Note that the value of the hostname configuration option of the server you connect MUST match the name in the server certificate, since it will be used to verify the server identity.

In case of failure no error message will appear. Instead, libESMTP will terminate the SMTP connection right after issuing the STARTLS command.

For more information about TLS support in libEMSTP see the comments in smtp-tls.c in the libESMTP source distribution.

===== Using CA root certificates from mozilla.org =====

Mozilla.org's browsers already ship with a bundle of CA root certificates. For most cases this bundle should suffice. You can download the bundle a format suitable to esmtp from http://curl.haxx.se/docs/caextract.html, as

mkdir ~/.authenticate
chmod 0700 ~/.authenticate
wget http://curl.haxx.se/ca/cacert.pem
mv cacert.pem ~/.authenticate/ca.pem
chmod 0600 ~/.authenticate/ca.pem

===== Using CA root certificates from debian =====

If you use Debian, you can also use the CA root certificates included in the ca-certificates package:

mkdir ~/.authenticate
chmod 0700 ~/.authenticate
sudo apt-get install ca-certificates
cp -a /etc/ssl/certs/ ~/.authenticate/ca
chmod -R go-rwx ~/.authenticate/ca

===== Determining the Cert-Authority certificate =====

It may happen that the mail server certificate is signed by an unknown or custom root certificate. If you think that may be your case you can try to figure out which one is using openssl:

__openssl s_client -connect hostname:port__

Depending on the SMTP mail server, you might need to play with the port number or add '-starttls smtp' option.

Look for lines in the output which can provide clues for the certification authority such as:

issuer=/C=ZA/ST=Western Cape/L=Cape Town/O=Thawte Consulting cc/OU=Certification Services Division/CN=Thawte Premium Server CA/emailAddress=premium-server@thawte.com

Once you are in possession of the root certificate, you can check if it validates the server certificate by passing it on the -CAfile option. It is does then you'll get a line like:

  Verify return code: 0 (ok)

See also http://curl.haxx.se/docs/sslcerts.html

===== Queueing support for dial-in users =====

To enable mail queueing support for esmtp, a wrapper script has been included with this distribution. It's goal is to be called instead of esmtp when a mail client requests sending of an email, and then periodically or on request to actually send pending emails. First choose a place to save the script. This path will be referenced by DIR in the following examples. Then you need to create symbolic links to it with special names at one of the directories in your $PATH environment variable, e.g. $HOME/bin:

cd $HOME/bin
ln -s <<DIR>>/esmtp-wrapper sendmail
ln -s <<DIR>>/esmtp-wrapper deliver
ln -s <<DIR>>/esmtp-wrapper mailq

When esmtp-wrapper is called either as sendmail or esmtp, it will first enqueue the mail by saving the mail itself and the given parameters (like, e.g. the envelope-from address) into a directory within the caller's $HOME/.esmtp_queue directory, and then try to directly deliver the queue in background. In difference to enqueueing, successful delivery is not treated as critical at this point and therefore won't disturb the mail client's workflow. To trigger delivery of all enqueued mails, execute esmtp-wrapper either as deliver, or as mailq using '-q' as first parameter. You can check whether there are enqueued mails either by simply issueing mailq or manually checking your $HOME/.esmtp_queue directory. Maybe the best way to trigger mail delivery is within some script which is called after the internet connection has been enabled. Alternatively I find the following crontab entry quite useful:

*/10 * * * * /bin/ping -c1 mail.example.com >/dev/null 2>&1 && $HOME/bin/deliver

it will check every 10 minutes whether the mailserver mail.example.com is reachable and on success deliver all mails in the queue. BEWARE: always make sure the script is called by the right user, as esmtp-wrapper depends on that.

Last modified on 2011-02-14.