path: root/README

				   ---------
				   ESMTP MTA
				   ---------
                                  José Fonseca
                                      ---
				  October 2008


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.

  See the {{{http://esmtp.sourceforge.net/}ESMTP MTA home page}} for updated
  information.


Configuration
~~~~~~~~~~~~~


* Sample configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  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.

  Gmail's server certificated is signed by Thawte. You can either follow the
  instructions to use Mozilla's CA cert bundle, found elsewhere in this
  document, or download directly the
  {{{http://www.thawte.com/roots/index.html}Thawte Premium Server CA
  certificate}}, as shown below:

---------------------------------------
mkdir ~/.authenticate
chmod 0700 ~/.authenticate
wget https://www.verisign.com/support/thawte-roots.zip
unzip -p thawte-roots.zip 'Thawte Server Roots/ThawtePremiumServerCA_b64.txt' > ~/.authenticate/ca.pem
chmod 0600 ~/.authenticate/ca.pem
---------------------------------------


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:

    [[1]] 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.

    [[2]] put the certificate of the trusted Cert-Authority that signed the
    server certificate into <<<~/.authenticate/ca.pem>>>.

    [[3]] 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.

    [[4]] 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.