summaryrefslogtreecommitdiff
path: root/README
blob: ed92c6c56d33d0d9550b8641292882b26ee6c36a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
                                     -----
                                     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.


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>>>.