1============================= 2 Hooking up your mail server 3============================= 4 5Mailman needs to communicate with your *MTA* (*mail transport agent* 6or *mail server*, the software which handles sending mail across the 7Internet), both to accept incoming mail and to deliver outgoing mail. 8Mailman itself never delivers messages to the end user. It sends them 9to its immediate upstream MTA, which delivers them. In the same way, 10Mailman never receives mail directly. Mail from outside always comes 11via the MTA. 12 13Mailman accepts incoming messages from the MTA using the `Local Mail Transfer 14Protocol`_ (LMTP_) interface. LMTP is much more efficient than spawning a 15process just to do the delivery. Most open source MTAs support LMTP for local 16delivery. If yours doesn't, and you need to use a different interface, please 17ask on the `mailing list or on IRC`_. 18 19Mailman passes all outgoing messages to the MTA using the `Simple Mail 20Transfer Protocol`_ (SMTP_). 21 22Cooperation between Mailman and the MTA requires some configuration of 23both. MTA configuration differs for each of the available MTAs, and 24there is a section for each one. Instructions for Postfix and Exim (v4) 25are given below. We would really appreciate a contribution of a 26configuration for Sendmail, and welcome information about other popular 27open source mail servers. 28 29Configuring Mailman to communicate with the MTA is straightforward, and 30basically the same for all MTAs. Here are the default settings; if you need 31to change them, edit your ``mailman.cfg`` file:: 32 33 [mta] 34 incoming: mailman.mta.postfix.LMTP 35 outgoing: mailman.mta.deliver.deliver 36 lmtp_host: 127.0.0.1 37 lmtp_port: 8024 38 smtp_host: localhost 39 smtp_port: 25 40 configuration: python:mailman.config.postfix 41 42This configuration is for a system where Mailman and the MTA are on 43the same host. 44 45Note that the modules that configure the communication protocol (especially 46``incoming``) are full-fledged Python modules, and may use these configuration 47parameters to automatically configure the MTA to recognize the list addresses 48and other attributes of the communication channel. This is why some 49constraints on the format of attributes arise (e.g., ``lmtp_host``), even 50though Mailman itself has no problem with them. 51 52It is possible (although not documented here) to completely replace or 53override the default mechanisms to handle both incoming and outgoing mail. 54Mailman is highly customizable here! 55 56The ``incoming`` and ``outgoing`` parameters identify the Python objects used 57to communicate with the MTA. The ``python:`` scheme indicates that the paths 58should be a dotted Python module specification. The ``deliver`` module used 59in ``outgoing`` should be satisfactory for most MTAs. The ``postfix`` module 60in ``incoming`` is specific to the Postfix MTA. See the section for your MTA 61below for details on these parameters. 62 63``lmtp_host`` and ``lmtp_port`` are parameters which are used by Mailman, but 64also will be passed to the MTA to identify the Mailman host. The "same host" 65case is special; some MTAs (including Postfix) do not recognize "localhost", 66and need the numerical IP address. If they are on different hosts, 67``lmtp_host`` should be set to the domain name or IP address of the Mailman 68host. ``lmtp_port`` is fairly arbitrary (there is no standard port for LMTP). 69Use any port convenient for your site. "8024" is as good as any, unless 70another service is using it. 71 72``smtp_host`` and ``smtp_port`` are parameters used to identify the MTA to 73Mailman. If the MTA and Mailman are on separate hosts, ``smtp_host`` should 74be set to the domain name or IP address of the MTA host. ``smtp_port`` will 75almost always be 25, which is the standard port for SMTP. (Some special site 76configurations set it to a different port. If you need this, you probably 77already know that, know why, and what to do, too!) 78 79Mailman also provides many other configuration variables that you can 80use to tweak performance for your operating environment. See the 81``src/mailman/config/schema.cfg`` file for details. 82 83 84Postfix 85======= 86 87Postfix_ is an open source mail server by Wietse Venema. 88 89 90Mailman settings 91---------------- 92 93You need to tell Mailman that you are using the Postfix mail server. In your 94``mailman.cfg`` file, add the following section:: 95 96 [mta] 97 incoming: mailman.mta.postfix.LMTP 98 outgoing: mailman.mta.deliver.deliver 99 lmtp_host: mail.example.com 100 lmtp_port: 8024 101 smtp_host: mail.example.com 102 smtp_port: 25 103 104Some of these settings are already the default, so take a look at Mailman's 105``src/mailman/config/schema.cfg`` file for details. You'll need to change the 106``lmtp_host`` and ``smtp_host`` to the appropriate host names of course. 107Generally, Postfix will listen for incoming SMTP connections on port 25. 108Postfix will deliver via LMTP over port 24 by default, however if you are not 109running Mailman as root, you'll need to change this to a higher port number, 110as shown above. 111 112 113Basic Postfix connections 114------------------------- 115 116There are several ways to hook Postfix up to Mailman, so here are the simplest 117instructions. The following settings should be added to Postfix's ``main.cf`` 118file. 119 120Mailman supports a technique called `Variable Envelope Return Path`_ (VERP) to 121disambiguate and accurately record bounces. By default Mailman's VERP 122delimiter is the `+` sign, so adding this setting allows Postfix to properly 123handle Mailman's VERP'd messages:: 124 125 # Support the default VERP delimiter. 126 recipient_delimiter = + 127 128In older versions of Postfix, unknown local recipients generated a temporary 129failure. It's much better (and the default in newer Postfix releases) to 130treat them as permanent failures. You can add this to your ``main.cf`` file 131if needed (use the `postconf`_ command to check the defaults):: 132 133 unknown_local_recipient_reject_code = 550 134 135While generally not necessary if you set ``recipient_delimiter`` as described 136above, it's better for Postfix to not treat ``owner-`` and ``-request`` 137addresses specially:: 138 139 owner_request_special = no 140 141 142Transport maps 143-------------- 144 145By default, Mailman works well with Postfix transport maps as a way to deliver 146incoming messages to Mailman's LMTP server. Mailman will automatically write 147the correct transport map when its ``mailman aliases`` command is run, or 148whenever a mailing list is created or removed via other commands. Mailman 149supports two type of transport map tables for Postfix, namely ``hash`` and 150``regexp``. Tables using hash are processed by ``postmap`` command. To use this 151format, you should have ``postmap`` command available on the host running 152Mailman. It is also the default one of the two. To connect Postfix to 153Mailman's LMTP server, add the following to Postfix's ``main.cf`` file:: 154 155 transport_maps = 156 hash:/path-to-mailman/var/data/postfix_lmtp 157 local_recipient_maps = 158 hash:/path-to-mailman/var/data/postfix_lmtp 159 relay_domains = 160 hash:/path-to-mailman/var/data/postfix_domains 161 162where ``path-to-mailman`` is replaced with the actual path that you're running 163Mailman from. Setting ``local_recipient_maps`` as well as ``transport_maps`` 164allows Postfix to properly reject all messages destined for non-existent local 165users. Setting `relay_domains`_ means Postfix will start to accept mail for 166newly added domains even if they are not part of `mydestination`_. 167 168Note that if you are not using virtual domains, then `relay_domains`_ isn't 169strictly needed (but it is harmless). All you need to do in this scenario is 170to make sure that Postfix accepts mail for your one domain, normally by 171including it in ``mydestination``. 172 173Regular Expression tables remove the additional dependency of having ``postmap`` 174command available to Mailman. If you want to use ``regexp`` or Regular 175Expression tables, then add the following to Postfix's ``main.cf`` file:: 176 177 transport_maps = 178 regexp:/path-to-mailman/var/data/postfix_lmtp 179 local_recipient_maps = 180 regexp:/path-to-mailman/var/data/postfix_lmtp 181 relay_domains = 182 regexp:/path-to-mailman/var/data/postfix_domains 183 184You will also have to instruct Mailman to generate regexp tables instead of hash 185tables by adding the following configuration to ``mailman.cfg``:: 186 187 [mta] 188 incoming: mailman.mta.postfix.LMTP 189 outgoing: mailman.mta.deliver.deliver 190 lmtp_host: mail.example.com 191 lmtp_port: 8024 192 smtp_host: mail.example.com 193 smtp_port: 25 194 configuration: /path/to/postfix-mailman.cfg 195 196Also you will have to create another configuration file called as 197``postfix-mailman.cfg`` and add its path to the ``configuration`` parameter 198above. The ``postfix-mailman.cfg`` would look like this:: 199 200 [postfix] 201 transport_file_type: regex 202 203 204Unusual Postfix configuration 205----------------------------- 206 207In some cases there will be an existing Postfix configuration in which the 208domain that will be used for Mailman 3 lists is a `virtual alias domain`_ and 209for various reasons, perhaps because it supports Mailman 2 lists and Mailman 3 210lists need to use the same domain, it must remain a virtual alias domain. 211This is a challenge because ``virtual alias domains`` do not use 212``transport_maps``. 213 214In order to enable this configuration, Mailman `domains`_ have an 215``alias_domain`` attribute. This is normally ``None`` but can be set to any 216otherwise unused domain name. The ``alias_domain`` is a fictitious domain that 217is not exposed in ``DNS`` and is only known to Postfix via the Mailman 218generated mappings. For example if the actual domain is ``example.com`` the 219``alias_domain`` could be ``x.example.com`` or even literally ``bogus.domain``. 220If this is done and the configured MTA is Postfix, Mailman will create an 221additional ``/path-to-mailman/var/data/postfix_vmap`` file with mappings from 222the ``example.com`` addresses to the corresponding addresses in the 223``alias_domain`` and will use the ``alias_domain`` in the other files. 224To use this feature, add the following in ``main.cf``:: 225 226 transport_maps = 227 hash:/path-to-mailman/var/data/postfix_lmtp 228 relay_domains = 229 hash:/path-to-mailman/var/data/postfix_domains 230 virtual_alias_maps = 231 hash:/path-to-mailman/var/data/postfix_vmap 232 233where ``path-to-mailman`` is as above. If any of these are already set, just 234add the ``hash`` references to the existing settings. We don't add 235``local_recipient_maps`` because the lists are in a virtual domain and are 236therefore not local, although if you have lists in multiple domains, some of 237which are local, you may need ``local_recipient_maps`` as above. Note that 238these can be ``regexp`` tables rather than ``hash`` tables. See the 239``Transport maps`` section above. 240 241 242Postfix documentation 243--------------------- 244 245For more information regarding how to configure Postfix, please see 246`The official Postfix documentation`_, 247`The reference page for all Postfix configuration parameters`_, 248and the documentation for the `relay_domains`_, `mydestination`_ and 249`virtual alias domain`_ settings. 250 251.. _`The official Postfix documentation`: 252 http://www.postfix.org/documentation.html 253.. _`The reference page for all Postfix configuration parameters`: 254 http://www.postfix.org/postconf.5.html 255.. _`relay_domains`: http://www.postfix.org/postconf.5.html#relay_domains 256.. _`mydestination`: http://www.postfix.org/postconf.5.html#mydestination 257.. _`virtual alias domain`: http://www.postfix.org/ADDRESS_CLASS_README.html#virtual_alias_class 258 259 260Exim 261==== 262 263`Exim 4`_ is an MTA maintained by the `University of Cambridge`_ and 264distributed by most open source OS distributions. 265 266Mailman settings 267---------------- 268 269Add or edit a stanza like this in mailman.cfg:: 270 271 [mta] 272 # For all Exim4 installations. 273 incoming: mailman.mta.exim4.LMTP 274 outgoing: mailman.mta.deliver.deliver 275 # Typical single host with MTA and Mailman configuration. 276 # Adjust to your system's configuration. 277 # Exim happily works with the "localhost" alias rather than IP address. 278 lmtp_host: localhost 279 smtp_host: localhost 280 # Mailman should not be run as root. 281 # Use any convenient port > 1024. 8024 is a convention, but can be 282 # changed if there is a conflict with other software using that port. 283 lmtp_port: 8024 284 # smtp_port rarely needs to be set. 285 smtp_port: 25 286 # Exim4-specific configuration parameter defaults. Currently empty. 287 configuration: python:mailman.config.exim4 288 289For further information about these settings, see 290``mailman/config/schema.cfg``. 291 292Exim4 configuration 293------------------- 294 295The configuration presented below is mostly boilerplate that allows Exim to 296automatically discover your list addresses, and route both posts and 297administrative messages to the right Mailman services. For this reason, the 298`mailman.mta.exim4` module ends up with all methods being no-ops. 299 300This configuration is field-tested in a Debian "conf.d"-style Exim 301installation, with multiple configuration files that are assembled by a 302Debian-specific script. If your Exim v4 installation is structured 303differently, ignore the comments indicating location in the Debian 304installation. 305:: 306 307 # /etc/exim4/conf.d/main/25_mm3_macros 308 # The colon-separated list of domains served by Mailman. 309 domainlist mm_domains=list.example.net 310 311 MM3_LMTP_PORT=8024 312 313 # MM3_HOME must be set to mailman's var directory, wherever it is 314 # according to your installation. 315 MM3_HOME=/opt/mailman/var 316 MM3_UID=list 317 MM3_GID=list 318 319 ################################################################ 320 # The configuration below is boilerplate: 321 # you should not need to change it. 322 323 # The path to the list receipt (used as the required file when 324 # matching list addresses) 325 MM3_LISTCHK=MM3_HOME/lists/${local_part}.${domain} 326 327 # /etc/exim4/conf.d/router/455_mm3_router 328 mailman3_router: 329 driver = accept 330 domains = +mm_domains 331 require_files = MM3_LISTCHK 332 local_part_suffix_optional 333 local_part_suffix = \ 334 -bounces : -bounces+* : \ 335 -confirm : -confirm+* : \ 336 -join : -leave : \ 337 -owner : -request : \ 338 -subscribe : -unsubscribe 339 transport = mailman3_transport 340 341 # /etc/exim4/conf.d/transport/55_mm3_transport 342 mailman3_transport: 343 driver = smtp 344 protocol = lmtp 345 allow_localhost 346 hosts = localhost 347 port = MM3_LMTP_PORT 348 rcpt_include_affixes = true 349 350Troubleshooting 351--------------- 352 353The most likely causes of failure to deliver to Mailman are typos in the 354configuration, and errors in the ``MM3_HOME`` macro or the ``mm_domains`` 355list. Mismatches in the LMTP port could be a cause. Finally, Exim's router 356configuration is order-sensitive. Especially if you are being tricky and 357supporting Mailman 2 and Mailman 3 at the same time, you could have one shadow 358the other. 359 360Another issue, not specific to Exim, is Mailman's requirement that every 361message have a ``Message-ID:`` header. Exim can ensure this if you add these 362two lines to the ``mailman3_transport:`` section. 363:: 364 365 headers_remove = message-id 366 headers_add = "Message-ID: ${if def:header_message-id:{$h_message-id:}{<E${message_exim_id}@${qualify_domain}>}}" 367 368Exim 4 documentation 369-------------------- 370 371There is `copious documentation for Exim`_. The parts most relevant to 372configuring communication with Mailman 3 are the chapters on the `accept 373router`_ and the `LMTP transport`_. Unless you are already familiar 374with Exim configuration, you probably want to start with the chapter on 375`how Exim receives and delivers mail`_. 376 377.. _`Exim 4`: http://www.exim.org/ 378.. _`University of Cambridge`: https://www.cam.ac.uk/ 379.. _`copious documentation for Exim`: http://www.exim.org/docs.html 380.. _`accept router`: http://www.exim.org/exim-html-current/doc/html/spec_html/ch-the_accept_router.html 381.. _`LMTP transport`: http://www.exim.org/exim-html-current/doc/html/spec_html/ch-the_lmtp_transport.html 382.. _`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 383 384 385qmail 386===== 387 388qmail_ is a MTA written by djb_ and, though old and not updated, still 389bulletproof and occassionally in use. 390 391Mailman settings 392---------------- 393 394Mostly defaults in mailman.cfg:: 395 396 [mta] 397 # NullMTA is just implementing the interface and thus satisfying Mailman 398 # without doing anything fancy 399 incoming: mailman.mta.null.NullMTA 400 # Mailman should not be run as root. 401 # Use any convenient port > 1024. 8024 is a convention, but can be 402 # changed if there is a conflict with other software using that port. 403 lmtp_port: 8024 404 405This will listen on ``localhost:8024`` with LMTP and deliver outgoing messages 406to ``localhost:25``. See ``mailman/config/schema.cfg`` for more information 407on these settings. 408 409qmail configuration 410------------------- 411 412It is assumed that qmail is configured to use the ``.qmail*`` files in a user’s 413home directory, however the instructions should easily be adaptable to other 414qmail configurations. However, it is required that Mailman has a (sub)domain 415respectively a namespace on its own. A helper script called ``qmail-lmtp`` is 416needed and can be found in the ``contrib/`` directory of the Mailman source 417tree and assumed to be on ``$PATH`` here. 418 419As qmail puts every namespace in the address, we have to filter it out again. 420If your main domain is ``example.com`` and you assign ``lists.example.com`` to 421the user ``mailman``, qmail will give you the destination address 422``mailman-spam@lists.example.com`` while it should actually be 423``spam@lists.example.com``. The second argument to ``qmail-lmtp`` defines 424how many parts (separated by dashes) to filter out. The first argument 425specifies the LMTP port of Mailman. An optional third argument specifies the 426LMTP hostname to connect to (by default localhost). 427Long story short, as user mailman: 428:: 429 430 % chmod +t "$HOME" 431 % echo '|qmail-lmtp 8042 1' > .qmail # put appropriate values here 432 % ln -sf .qmail .qmail-default 433 % chmod -t "$HOME" 434 435.. _qmail: https://cr.yp.to/qmail.html 436.. _djb: https://cr.yp.to 437 438 439Sendmail 440======== 441 442The core Mailman developers generally do not use Sendmail, so experience is 443limited. Any and all contributions are welcome! The follow information from 444a post by Gary Algier <gaa@ulticom.com> may be useful as a starting point, 445although it describes Mailman 2: 446 447 I have it working fine. I recently replaced a very old implementation 448 of sendmail and Mailman 2 on Solaris with a new one on CentOS 6. When I 449 did so, I used the POSTFIX_ALIAS_CMD mechanism to automatically process 450 the aliases. See:: 451 452 https://mail.python.org/pipermail/mailman-users/2004-June/037518.html 453 454 In mm_cfg.py:: 455 456 MTA='Postfix' 457 POSTFIX_ALIAS_CMD = '/usr/bin/sudo /etc/mail/import-mailman-aliases' 458 459 /etc/mail/import-mailman-aliases contains:: 460 461 #! /bin/sh 462 /bin/cp /etc/mailman/aliases /etc/mail/mailman.aliases 463 /usr/bin/newaliases 464 465 In /etc/sudoers.d/mailman:: 466 467 Cmnd_Alias IMPORT_MAILMAN_ALIASES = /etc/mail/import-mailman-aliases 468 apache ALL= NOPASSWD: IMPORT_MAILMAN_ALIASES 469 mailman ALL= NOPASSWD: IMPORT_MAILMAN_ALIASES 470 Defaults!IMPORT_MAILMAN_ALIASES !requiretty 471 472 In the sendmail.mc file I changed:: 473 474 define(`ALIAS_FILE', `/etc/aliases')dnl 475 476 to:: 477 478 define(`ALIAS_FILE', `/etc/aliases,/etc/mail/mailman.aliases')dnl 479 480 so that the Mailman aliases would be in a separate file. 481 482The main issue here is that Mailman 2 expects to receive messages from 483the MTA via pipes, whereas Mailman 3 uses LMTP exclusively. Recent 484Sendmail does support LMTP, so it's a matter of configuring a stock 485Sendmail. But rather than using aliases, it needs to be configured to 486relay to the LMTP port of Mailman. 487 488 489.. _`mailing list or on IRC`: START.html#contact-us 490.. _`Local Mail Transfer Protocol`: 491 https://en.wikipedia.org/wiki/Local_Mail_Transfer_Protocol 492.. _LMTP: http://www.faqs.org/rfcs/rfc2033.html 493.. _`Simple Mail Transfer Protocol`: 494 https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol 495.. _SMTP: http://www.faqs.org/rfcs/rfc5321.html 496.. _Postfix: http://www.postfix.org 497.. _`Variable Envelope Return Path`: 498 https://en.wikipedia.org/wiki/Variable_envelope_return_path 499.. _postconf: http://www.postfix.org/postconf.1.html 500.. _domains: ../model/docs/domains.html 501