summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorJosé Fonseca <jrfonseca@users.sourceforge.net>2003-07-05 10:49:22 +0000
committerJosé Fonseca <jrfonseca@users.sourceforge.net>2003-07-05 10:49:22 +0000
commit60b9cfd5abf4e2c68821b8435cc73ec3a7d1e058 (patch)
tree8c9f64a1f99ca5eead75993b53852d3fa132a366 /README
parent5f63162c8088321f5d0f88e8a367815b9cd2d694 (diff)
Better documentation.
Support for more sendmail options. Error verification for libESMTP calls.
Diffstat (limited to 'README')
-rw-r--r--README241
1 files changed, 236 insertions, 5 deletions
diff --git a/README b/README
index 9caa605..1a19027 100644
--- a/README
+++ b/README
@@ -1,6 +1,237 @@
-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.
+ -----
+ ESMTP
+ -----
+ José Fonseca
+ ---
+ July 2003
+
+
+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 home page}} for updated
+ information.
+
+
+Rationale
+~~~~~~~~~
+
+ Since the moment I switched to Linux I had some problems to have email
+ properly configurated to my personal needs. I use a POP3/SMTP mail account
+ for my personal mail, and I usually connect to the internet with my laptop
+ via several LANs (home, work, ...) with several different firewall
+ configurations. The standard MTAs didn't provided the flexibility I needed --
+ they either failed to deliver the mail directly or failed to authenticate
+ with the relay, or were configured system-wide and conflicted with the local
+ MTA.
+
+ <<fetchmail>> always worked fine to get email, but I needed a <<sendmail>>
+ alike program to send email from <<Mutt>>. Basically I wanted a program
+ which could be for SMTP what <<fetchmail>> was for POP3, i.e., an user
+ configurable MTA with authorization support.
+
+ Some small modifications to the <<<mail-file>>> example from <<libESMTP>> did
+ the trick. After receiving positive feedback from the <<libESMTP>> author,
+ Brian Stafford, I decided to make the program more confortable for others to
+ use -- adding a command-line option parser extracted from sendmail, a
+ configuration file parser from <<fetchmail>>, a man page based on <<ssmtp>>
+ and <<sendmail>> man pages and using autotools to wrap it all up. The result
+ of this cut and paste effort is <<esmtp>>. Well, the first version, that is.
+ Since then a few more bells and whistles were added, with the help of some
+ contributors.
+
+
+
+Configuration
+~~~~~~~~~~~~~
+
+
+* Sample configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ This is a simple configuration file for a quick start:
+
+--------------------------------------
+hostname = mail.myisp.com:25
+username = "myusername"
+password = "mysecret"
+starttls = enabled
+
+identity = myself@somewhere.com
+ hostname = smtp.somewhere.com:25
+ username = "myself"
+ password = "secret"
+ starttls = enabled
+
+mda "/usr/bin/procmail -d %T"
+--------------------------------------
+
+
+* Configuration options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+ Options are speficied by giving a <keyword=value> in the configuration
+ file. The equal sign is optional and can be replaced by whitespace. The
+ value may be enclose in simple or double quotes, in which case special
+ characters can be escaped as in normal <C> strings.
+
+ [hostname] - set SMTP host and service (port).
+
+ This is specified in the format <<<host.example.org[:service]>>> with no
+ whitespace surrounding the colon if service is specified. service may be a
+ name from <<</etc/services>>> or a decimal port number. If not specified
+ the port defaults to 587.
+
+ Note (from <<libESMTP>> documentation): the default port number is set to
+ 587 since this is the port that should be used for mail submission, see RFC
+ 2476. By choosing this default now, the API does not change behaviour
+ unexpectedly in the future as use of the new standard becomes commonplace.
+ The hostport notation simplifies things for the application, the user can
+ type <<<localhost:smtp>>> or <<<localhost:25>>> where the application
+ expects a host name.
+
+ [username] - set the user name.
+
+ [password] - set the password.
+
+ [starttls] - determine the usage of the StartTLS extension.
+
+ It can be one of <"enabled">, <"disabled"> or <"required">. It defaults to
+ disabled.
+
+ [certificate_passphrase] - set the certificate passphrase.
+
+ [identity] - define an identity.
+
+ An identities is a set of options associated with a given address. For
+ example:
+
+--------------------------------------
+identity = myself@somewhere.com
+ hostname = smtp.somewhere.com:25
+ username = "myself"
+ password = "secret"
+--------------------------------------
+
+ Identities are be selected by the address specified in the <-f> flag. You
+ can have as many you like.
+
+ The options up to the first <identity> option constitute the default
+ identity.
+
+
+ Note: the default identity settings are not shared by the other identities.
+ Everything (username, password, etc.) must be specified for every identity
+ even if they don't differ from the default identity.
+
+ [mda] - set the Mail Delivery Agent (MDA).
+
+ Local delivery addresses will be inserted into the MDA command wherever you
+ place a <%T>. The mail message's From address will be inserted where you
+ place an <%F>.
+
+ Some common MDAs are <"/usr/bin/procmail -d %T">,
+ <"/usr/bin/deliver"> and <"/usr/lib/mail.local %T">.
+
+ See below for more information about using <<esmtp>> with an MDA.
+
+
+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
+ priviledges 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 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"
+-----------------------------
+
+
+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 acomplished 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>>>.
-See ESMTP home page http://esmtp.sourceforge.net/ for more information.