1 ===========================
2 Hooking up your mail server
3 ===========================
5 Mailman needs to communicate with your *MTA* (*mail transport agent*
6 or *mail server*, the software which handles sending mail across the
7 Internet), both to accept incoming mail and to deliver outgoing mail.
8 Mailman itself never delivers messages to the end user. It sends them
9 to its immediate upstream MTA, which delivers them. In the same way,
10 Mailman never receives mail directly. Mail from outside always comes
13 Mailman accepts incoming messages from the MTA using the `Local Mail
14 Transfer Protocol`_ (LMTP_) interface. Mailman can use other incoming
15 transports, but LMTP is much more efficient than spawning a process
16 just to do the delivery. Most open source MTAs support LMTP for local
17 delivery. If yours doesn't, and you need to use a different
18 interface, please ask on the `mailing list or on IRC`_.
20 Mailman passes all outgoing messages to the MTA using the `Simple Mail
21 Transfer Protocol`_ (SMTP_).
23 Cooperation between Mailman and the MTA requires some configuration of
24 both. MTA configuration differs for each of the available MTAs, and
25 there is a section for each one. Instructions for Postfix and Exim (v4)
26 are given below. We would really appreciate a contribution of a
27 configuration for Sendmail, and welcome information about other popular
28 open source mail servers.
30 Configuring Mailman to communicate with the MTA is straightforward,
31 and basically the same for all MTAs. In your ``mailman.cfg`` file,
32 add (or edit) a section like the following::
35 incoming: mailman.mta.postfix.LMTP
36 outgoing: mailman.mta.deliver.deliver
41 configuration: python:mailman.config.postfix
43 This configuration is for a system where Mailman and the MTA are on
46 Note that the modules that configure the communication protocol (especially
47 ``incoming``) are full-fledged Python modules, and may use these configuration
48 parameters to automatically configure the MTA to recognize the list addresses
49 and other attributes of the communication channel. This is why some
50 constraints on the format of attributes arise (e.g., ``lmtp_host``), even
51 though Mailman itself has no problem with them.
53 The ``incoming`` and ``outgoing`` parameters identify the Python objects used
54 to communicate with the MTA. The ``python:`` scheme indicates that the paths
55 should be a dotted Python module specification. The ``deliver`` module used
56 in ``outgoing`` should be satisfactory for most MTAs. The ``postfix`` module
57 in ``incoming`` is specific to the Postfix MTA. See the section for your MTA
58 below for details on these parameters.
60 ``lmtp_host`` and ``lmtp_port`` are parameters which are used by
61 Mailman, but also will be passed to the MTA to identify the Mailman
62 host. The "same host" case is special; some MTAs (including Postfix)
63 do not recognize "localhost", and need the numerical IP address. If
64 they are on different hosts, ``lmtp_host`` should be set to the domain
65 name or IP address of the Mailman host. ``lmtp_port`` is fairly
66 arbitrary (there is no standard port for LMTP). Use any port
67 convenient for your site. "8024" is as good as any, unless another
70 ``smtp_host`` and ``smtp_port`` are parameters used to identify the
71 MTA to Mailman. If the MTA and Mailman are on separate hosts,
72 ``smtp_host`` should be set to the domain name or IP address of the
73 MTA host. ``smtp_port`` will almost always be 25, which is the
74 standard port for SMTP. (Some special site configurations set it to a
75 different port. If you need this, you probably already know that,
76 know why, and what to do, too!)
78 Mailman also provides many other configuration variables that you can
79 use to tweak performance for your operating environment. See the
80 ``src/mailman/config/schema.cfg`` file for details.
86 Postfix_ is an open source mail server by Wietse Venema.
92 You need to tell Mailman that you are using the Postfix mail server. In your
93 ``mailman.cfg`` file, add the following section::
96 incoming: mailman.mta.postfix.LMTP
97 outgoing: mailman.mta.deliver.deliver
98 lmtp_host: mail.example.com
100 smtp_host: mail.example.com
103 Some of these settings are already the default, so take a look at Mailman's
104 ``src/mailman/config/schema.cfg`` file for details. You'll need to change the
105 ``lmtp_host`` and ``smtp_host`` to the appropriate host names of course.
106 Generally, Postfix will listen for incoming SMTP connections on port 25.
107 Postfix will deliver via LMTP over port 24 by default, however if you are not
108 running Mailman as root, you'll need to change this to a higher port number,
112 Basic Postfix connections
113 -------------------------
115 There are several ways to hook Postfix up to Mailman, so here are the simplest
116 instructions. The following settings should be added to Postfix's ``main.cf``
119 Mailman supports a technique called `Variable Envelope Return Path`_ (VERP) to
120 disambiguate and accurately record bounces. By default Mailman's VERP
121 delimiter is the `+` sign, so adding this setting allows Postfix to properly
122 handle Mailman's VERP'd messages::
124 # Support the default VERP delimiter.
125 recipient_delimiter = +
127 In older versions of Postfix, unknown local recipients generated a temporary
128 failure. It's much better (and the default in newer Postfix releases) to
129 treat them as permanent failures. You can add this to your ``main.cf`` file
130 if needed (use the `postconf`_ command to check the defaults)::
132 unknown_local_recipient_reject_code = 550
134 While generally not necessary if you set ``recipient_delimiter`` as described
135 above, it's better for Postfix to not treat ``owner-`` and ``-request``
136 addresses specially::
138 owner_request_special = no
144 By default, Mailman works well with Postfix transport maps as a way to deliver
145 incoming messages to Mailman's LMTP server. Mailman will automatically write
146 the correct transport map when its ``mailman aliases`` command is run, or
147 whenever a mailing list is created or removed via other commands. To connect
148 Postfix to Mailman's LMTP server, add the following to Postfix's ``main.cf``
152 hash:/path-to-mailman/var/data/postfix_lmtp
153 local_recipient_maps =
154 hash:/path-to-mailman/var/data/postfix_lmtp
156 hash:/path-to-mailman/var/data/postfix_domains
158 where ``path-to-mailman`` is replaced with the actual path that you're running
159 Mailman from. Setting ``local_recipient_maps`` as well as ``transport_maps``
160 allows Postfix to properly reject all messages destined for non-existent local
161 users. Setting `relay_domains`_ means Postfix will start to accept mail for
162 newly added domains even if they are not part of `mydestination`_.
164 Note that if you are not using virtual domains, then `relay_domains`_ isn't
165 strictly needed (but it is harmless). All you need to do in this scenario is
166 to make sure that Postfix accepts mail for your one domain, normally by
167 including it in ``mydestination``.
170 Postfix documentation
171 ---------------------
173 For more information regarding how to configure Postfix, please see
174 the Postfix documentation at:
176 .. _`The official Postfix documentation`:
177 http://www.postfix.org/documentation.html
178 .. _`The reference page for all Postfix configuration parameters`:
179 http://www.postfix.org/postconf.5.html
180 .. _`relay_domains`: http://www.postfix.org/postconf.5.html#relay_domains
181 .. _`mydestination`: http://www.postfix.org/postconf.5.html#mydestination
187 `Exim 4`_ is an MTA maintained by the `University of Cambridge`_ and
188 distributed by most open source OS distributions.
193 Add or edit a stanza like this in mailman.cfg::
196 # For all Exim4 installations.
197 incoming: mailman.mta.exim4.LMTP
198 outgoing: mailman.mta.deliver.deliver
199 # Typical single host with MTA and Mailman configuration.
200 # Adjust to your system's configuration.
201 # Exim happily works with the "localhost" alias rather than IP address.
204 # Mailman should not be run as root.
205 # Use any convenient port > 1024. 8024 is a convention, but can be
206 # changed if there is a conflict with other software using that port.
208 # smtp_port rarely needs to be set.
210 # Exim4-specific configuration parameter defaults. Currently empty.
211 configuration: python:mailman.config.exim4
213 For further information about these settings, see
214 ``mailman/config/schema.cfg``.
219 The configuration presented below is mostly boilerplate that allows Exim to
220 automatically discover your list addresses, and route both posts and
221 administrative messages to the right Mailman services. For this reason, the
222 `mailman.mta.exim4` module ends up with all methods being no-ops.
224 This configuration is field-tested in a Debian "conf.d"-style Exim
225 installation, with multiple configuration files that are assembled by a
226 Debian-specific script. If your Exim v4 installation is structured
227 differently, ignore the comments indicating location in the Debian
231 # /etc/exim4/conf.d/main/25_mm3_macros
232 # The colon-separated list of domains served by Mailman.
233 domainlist mm_domains=list.example.net
237 # Assuming a typical source installation in /usr/local, with
238 # links to the Mailman bin directory and so on from MM3_HOME.
239 MM3_HOME=/usr/local/var/mailman
243 ################################################################
244 # The configuration below is boilerplate:
245 # you should not need to change it.
247 # The path to the list receipt (used as the required file when
248 # matching list addresses)
249 MM3_LISTCHK=MM3_HOME/lists/${local_part}@${domain}
251 # /etc/exim4/conf.d/router/455_mm3_router
254 domains = +mm_domains
255 require_files = MM3_LISTCHK
256 local_part_suffix_optional
257 local_part_suffix = -admin : \
258 -bounces : -bounces+* : \
259 -confirm : -confirm+* : \
261 -owner : -request : \
262 -subscribe : -unsubscribe
263 transport = mailman3_transport
265 # /etc/exim4/conf.d/transport/55_mm3_transport
276 The most likely causes of failure to deliver to Mailman are typos in the
277 configuration, and errors in the ``MM3_HOME`` macro or the ``mm_domains``
278 list. Mismatches in the LMTP port could be a cause. Finally, Exim's router
279 configuration is order-sensitive. Especially if you are being tricky and
280 supporting Mailman 2 and Mailman 3 at the same time, you could have one shadow
286 There is `copious documentation for Exim`_. The parts most relevant to
287 configuring communication with Mailman 3 are the chapters on the `accept
288 router`_ and the `LMTP transport`_. Unless you are already familiar
289 with Exim configuration, you probably want to start with the chapter on
290 `how Exim receives and delivers mail`.
292 .. _`Exim 4`: http://www.exim.org/
293 .. _`University of Cambridge`: http://www.cam.ac.uk/
294 .. _`copious documentation for Exim`: http://www.exim.org/docs.html
295 .. _`accept router`: http://www.exim.org/exim-html-current/doc/html/spec_html/ch-the_accept_router.html
296 .. _`LMTP transport`: http://www.exim.org/exim-html-current/doc/html/spec_html/ch-the_lmtp_transport.html
297 .. _`how Exim receives and delivers mail`: http://www.exim.org/exim-html-current/doc/html/spec_html/ch-how_exim_receives_and_delivers_mail.html
303 The core Mailman developers generally do not use Sendmail, so experience is
304 limited. Any and all contributions are welcome! The follow information from
305 a post by Gary Algier <gaa@ulticom.com> may be useful as a starting point,
306 although it describes Mailman 2:
308 I have it working fine. I recently replaced a very old implementation
309 of sendmail and Mailman 2 on Solaris with a new one on CentOS 6. When I
310 did so, I used the POSTFIX_ALIAS_CMD mechanism to automatically process
313 https://mail.python.org/pipermail/mailman-users/2004-June/037518.html
318 POSTFIX_ALIAS_CMD = '/usr/bin/sudo /etc/mail/import-mailman-aliases'
320 /etc/mail/import-mailman-aliases contains::
323 /bin/cp /etc/mailman/aliases /etc/mail/mailman.aliases
326 In /etc/sudoers.d/mailman::
328 Cmnd_Alias IMPORT_MAILMAN_ALIASES = /etc/mail/import-mailman-aliases
329 apache ALL= NOPASSWD: IMPORT_MAILMAN_ALIASES
330 mailman ALL= NOPASSWD: IMPORT_MAILMAN_ALIASES
331 Defaults!IMPORT_MAILMAN_ALIASES !requiretty
333 In the sendmail.mc file I changed::
335 define(`ALIAS_FILE', `/etc/aliases')dnl
339 define(`ALIAS_FILE', `/etc/aliases,/etc/mail/mailman.aliases')dnl
341 so that the Mailman aliases would be in a separate file.
343 The main issue here is that Mailman 2 expects to receive messages from
344 the MTA via pipes, whereas Mailman 3 uses LMTP exclusively. Recent
345 Sendmail does support LMTP, so it's a matter of configuring a stock
346 Sendmail. But rather than using aliases, it needs to be configured to
347 relay to the LMTP port of Mailman.
350 .. _`mailing list or on IRC`: START.html#contact-us
351 .. _`Local Mail Transfer Protocol`:
352 http://en.wikipedia.org/wiki/Local_Mail_Transfer_Protocol
353 .. _LMTP: http://www.faqs.org/rfcs/rfc2033.html
354 .. _`Simple Mail Transfer Protocol`:
355 http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
356 .. _SMTP: http://www.faqs.org/rfcs/rfc5321.html
357 .. _Postfix: http://www.postfix.org
358 .. _`Variable Envelope Return Path`:
359 http://en.wikipedia.org/wiki/Variable_envelope_return_path
360 .. _postconf: http://www.postfix.org/postconf.1.html