diff options
Diffstat (limited to 'src/mailman/docs/MTA.rst')
| -rw-r--r-- | src/mailman/docs/MTA.rst | 412 |
1 files changed, 0 insertions, 412 deletions
diff --git a/src/mailman/docs/MTA.rst b/src/mailman/docs/MTA.rst deleted file mode 100644 index ac38c3026..000000000 --- a/src/mailman/docs/MTA.rst +++ /dev/null @@ -1,412 +0,0 @@ -=========================== -Hooking up your mail server -=========================== - -Mailman needs to communicate with your *MTA* (*mail transport agent* -or *mail server*, the software which handles sending mail across the -Internet), both to accept incoming mail and to deliver outgoing mail. -Mailman itself never delivers messages to the end user. It sends them -to its immediate upstream MTA, which delivers them. In the same way, -Mailman never receives mail directly. Mail from outside always comes -via the MTA. - -Mailman accepts incoming messages from the MTA using the `Local Mail -Transfer Protocol`_ (LMTP_) interface. Mailman can use other incoming -transports, but LMTP is much more efficient than spawning a process -just to do the delivery. Most open source MTAs support LMTP for local -delivery. If yours doesn't, and you need to use a different -interface, please ask on the `mailing list or on IRC`_. - -Mailman passes all outgoing messages to the MTA using the `Simple Mail -Transfer Protocol`_ (SMTP_). - -Cooperation between Mailman and the MTA requires some configuration of -both. MTA configuration differs for each of the available MTAs, and -there is a section for each one. Instructions for Postfix and Exim (v4) -are given below. We would really appreciate a contribution of a -configuration for Sendmail, and welcome information about other popular -open source mail servers. - -Configuring Mailman to communicate with the MTA is straightforward, and -basically the same for all MTAs. Here are the default settings; if you need -to change them, edit your ``mailman.cfg`` file:: - - [mta] - incoming: mailman.mta.postfix.LMTP - outgoing: mailman.mta.deliver.deliver - lmtp_host: 127.0.0.1 - lmtp_port: 8024 - smtp_host: localhost - smtp_port: 25 - configuration: python:mailman.config.postfix - -This configuration is for a system where Mailman and the MTA are on -the same host. - -Note that the modules that configure the communication protocol (especially -``incoming``) are full-fledged Python modules, and may use these configuration -parameters to automatically configure the MTA to recognize the list addresses -and other attributes of the communication channel. This is why some -constraints on the format of attributes arise (e.g., ``lmtp_host``), even -though Mailman itself has no problem with them. - -The ``incoming`` and ``outgoing`` parameters identify the Python objects used -to communicate with the MTA. The ``python:`` scheme indicates that the paths -should be a dotted Python module specification. The ``deliver`` module used -in ``outgoing`` should be satisfactory for most MTAs. The ``postfix`` module -in ``incoming`` is specific to the Postfix MTA. See the section for your MTA -below for details on these parameters. - -``lmtp_host`` and ``lmtp_port`` are parameters which are used by -Mailman, but also will be passed to the MTA to identify the Mailman -host. The "same host" case is special; some MTAs (including Postfix) -do not recognize "localhost", and need the numerical IP address. If -they are on different hosts, ``lmtp_host`` should be set to the domain -name or IP address of the Mailman host. ``lmtp_port`` is fairly -arbitrary (there is no standard port for LMTP). Use any port -convenient for your site. "8024" is as good as any, unless another -service is using it. - -``smtp_host`` and ``smtp_port`` are parameters used to identify the -MTA to Mailman. If the MTA and Mailman are on separate hosts, -``smtp_host`` should be set to the domain name or IP address of the -MTA host. ``smtp_port`` will almost always be 25, which is the -standard port for SMTP. (Some special site configurations set it to a -different port. If you need this, you probably already know that, -know why, and what to do, too!) - -Mailman also provides many other configuration variables that you can -use to tweak performance for your operating environment. See the -``src/mailman/config/schema.cfg`` file for details. - - -Postfix -======= - -Postfix_ is an open source mail server by Wietse Venema. - - -Mailman settings ----------------- - -You need to tell Mailman that you are using the Postfix mail server. In your -``mailman.cfg`` file, add the following section:: - - [mta] - incoming: mailman.mta.postfix.LMTP - outgoing: mailman.mta.deliver.deliver - lmtp_host: mail.example.com - lmtp_port: 8024 - smtp_host: mail.example.com - smtp_port: 25 - -Some of these settings are already the default, so take a look at Mailman's -``src/mailman/config/schema.cfg`` file for details. You'll need to change the -``lmtp_host`` and ``smtp_host`` to the appropriate host names of course. -Generally, Postfix will listen for incoming SMTP connections on port 25. -Postfix will deliver via LMTP over port 24 by default, however if you are not -running Mailman as root, you'll need to change this to a higher port number, -as shown above. - - -Basic Postfix connections -------------------------- - -There are several ways to hook Postfix up to Mailman, so here are the simplest -instructions. The following settings should be added to Postfix's ``main.cf`` -file. - -Mailman supports a technique called `Variable Envelope Return Path`_ (VERP) to -disambiguate and accurately record bounces. By default Mailman's VERP -delimiter is the `+` sign, so adding this setting allows Postfix to properly -handle Mailman's VERP'd messages:: - - # Support the default VERP delimiter. - recipient_delimiter = + - -In older versions of Postfix, unknown local recipients generated a temporary -failure. It's much better (and the default in newer Postfix releases) to -treat them as permanent failures. You can add this to your ``main.cf`` file -if needed (use the `postconf`_ command to check the defaults):: - - unknown_local_recipient_reject_code = 550 - -While generally not necessary if you set ``recipient_delimiter`` as described -above, it's better for Postfix to not treat ``owner-`` and ``-request`` -addresses specially:: - - owner_request_special = no - - -Transport maps --------------- - -By default, Mailman works well with Postfix transport maps as a way to deliver -incoming messages to Mailman's LMTP server. Mailman will automatically write -the correct transport map when its ``mailman aliases`` command is run, or -whenever a mailing list is created or removed via other commands. To connect -Postfix to Mailman's LMTP server, add the following to Postfix's ``main.cf`` -file:: - - transport_maps = - hash:/path-to-mailman/var/data/postfix_lmtp - local_recipient_maps = - hash:/path-to-mailman/var/data/postfix_lmtp - relay_domains = - hash:/path-to-mailman/var/data/postfix_domains - -where ``path-to-mailman`` is replaced with the actual path that you're running -Mailman from. Setting ``local_recipient_maps`` as well as ``transport_maps`` -allows Postfix to properly reject all messages destined for non-existent local -users. Setting `relay_domains`_ means Postfix will start to accept mail for -newly added domains even if they are not part of `mydestination`_. - -Note that if you are not using virtual domains, then `relay_domains`_ isn't -strictly needed (but it is harmless). All you need to do in this scenario is -to make sure that Postfix accepts mail for your one domain, normally by -including it in ``mydestination``. - - -Postfix documentation ---------------------- - -For more information regarding how to configure Postfix, please see -the Postfix documentation at: - -.. _`The official Postfix documentation`: - http://www.postfix.org/documentation.html -.. _`The reference page for all Postfix configuration parameters`: - http://www.postfix.org/postconf.5.html -.. _`relay_domains`: http://www.postfix.org/postconf.5.html#relay_domains -.. _`mydestination`: http://www.postfix.org/postconf.5.html#mydestination - - -Exim -==== - -`Exim 4`_ is an MTA maintained by the `University of Cambridge`_ and -distributed by most open source OS distributions. - -Mailman settings ----------------- - -Add or edit a stanza like this in mailman.cfg:: - - [mta] - # For all Exim4 installations. - incoming: mailman.mta.exim4.LMTP - outgoing: mailman.mta.deliver.deliver - # Typical single host with MTA and Mailman configuration. - # Adjust to your system's configuration. - # Exim happily works with the "localhost" alias rather than IP address. - lmtp_host: localhost - smtp_host: localhost - # Mailman should not be run as root. - # Use any convenient port > 1024. 8024 is a convention, but can be - # changed if there is a conflict with other software using that port. - lmtp_port: 8024 - # smtp_port rarely needs to be set. - smtp_port: 25 - # Exim4-specific configuration parameter defaults. Currently empty. - configuration: python:mailman.config.exim4 - -For further information about these settings, see -``mailman/config/schema.cfg``. - -Exim4 configuration -------------------- - -The configuration presented below is mostly boilerplate that allows Exim to -automatically discover your list addresses, and route both posts and -administrative messages to the right Mailman services. For this reason, the -`mailman.mta.exim4` module ends up with all methods being no-ops. - -This configuration is field-tested in a Debian "conf.d"-style Exim -installation, with multiple configuration files that are assembled by a -Debian-specific script. If your Exim v4 installation is structured -differently, ignore the comments indicating location in the Debian -installation. -:: - - # /etc/exim4/conf.d/main/25_mm3_macros - # The colon-separated list of domains served by Mailman. - domainlist mm_domains=list.example.net - - MM3_LMTP_PORT=8024 - - # Assuming a typical source installation in /usr/local, with - # links to the Mailman bin directory and so on from MM3_HOME. - MM3_HOME=/usr/local/var/mailman - MM3_UID=list - MM3_GID=list - - ################################################################ - # The configuration below is boilerplate: - # you should not need to change it. - - # The path to the list receipt (used as the required file when - # matching list addresses) - MM3_LISTCHK=MM3_HOME/lists/${local_part}@${domain} - - # /etc/exim4/conf.d/router/455_mm3_router - mailman3_router: - driver = accept - domains = +mm_domains - require_files = MM3_LISTCHK - local_part_suffix_optional - local_part_suffix = -admin : \ - -bounces : -bounces+* : \ - -confirm : -confirm+* : \ - -join : -leave : \ - -owner : -request : \ - -subscribe : -unsubscribe - transport = mailman3_transport - - # /etc/exim4/conf.d/transport/55_mm3_transport - mailman3_transport: - driver = smtp - protocol = lmtp - allow_localhost - hosts = localhost - port = MM3_LMTP_PORT - -Troubleshooting ---------------- - -The most likely causes of failure to deliver to Mailman are typos in the -configuration, and errors in the ``MM3_HOME`` macro or the ``mm_domains`` -list. Mismatches in the LMTP port could be a cause. Finally, Exim's router -configuration is order-sensitive. Especially if you are being tricky and -supporting Mailman 2 and Mailman 3 at the same time, you could have one shadow -the other. - -Exim 4 documentation --------------------- - -There is `copious documentation for Exim`_. The parts most relevant to -configuring communication with Mailman 3 are the chapters on the `accept -router`_ and the `LMTP transport`_. Unless you are already familiar -with Exim configuration, you probably want to start with the chapter on -`how Exim receives and delivers mail`. - -.. _`Exim 4`: http://www.exim.org/ -.. _`University of Cambridge`: http://www.cam.ac.uk/ -.. _`copious documentation for Exim`: http://www.exim.org/docs.html -.. _`accept router`: http://www.exim.org/exim-html-current/doc/html/spec_html/ch-the_accept_router.html -.. _`LMTP transport`: http://www.exim.org/exim-html-current/doc/html/spec_html/ch-the_lmtp_transport.html -.. _`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 - - -qmail -===== - -qmail_ is a MTA written by djb_ and, though old and not updated, still -bulletproof and occassionally in use. - -Mailman settings ----------------- - -Mostly defaults in mailman.cfg:: - - [mta] - # NullMTA is just implementing the interface and thus satisfying Mailman - # without doing anything fancy - incoming: mailman.mta.null.NullMTA - # Mailman should not be run as root. - # Use any convenient port > 1024. 8024 is a convention, but can be - # changed if there is a conflict with other software using that port. - lmtp_port: 8024 - -This will listen on localhost:8024 with LMTP and deliver outgoing -messages to localhost:25. See ``mailman/config/schema.cfg`` for more -information on these settings. - -qmail configuration -------------------- - -It is assumed that qmail is configured to use the ``.qmail*`` files in a user’s -home directory, however the instructions should easily be adaptable to other -qmail configurations. However, it is required that Mailman has a (sub)domain -respectively a namespace on its own. A helper script called ``qmail-lmtp`` is -needed and can be found in the ``contrib/`` directory of the Mailman source -tree and assumed to be on ``$PATH`` here. - -As qmail puts every namespace in the address, we have to filter it out again. -If your main domain is ``example.com`` and you assign ``lists.example.com`` to -the user ``mailman``, qmail will give you the destination address -``mailman-spam@lists.example.com`` while it should actually be -``spam@lists.example.com``. The second argument to ``qmail-lmtp`` defines -how many parts (separated by dashes) to filter out. The first argument -specifies the LMTP port of mailman. Long story short, as user mailman: -:: - - % chmod +t "$HOME" - % echo '|qmail-lmtp 1 8042' > .qmail # put appropriate values here - % ln -sf .qmail .qmail-default - % chmod -t "$HOME" - -.. _qmail: https://cr.yp.to/qmail.html -.. _djb: https://cr.yp.to - - -Sendmail -======== - -The core Mailman developers generally do not use Sendmail, so experience is -limited. Any and all contributions are welcome! The follow information from -a post by Gary Algier <gaa@ulticom.com> may be useful as a starting point, -although it describes Mailman 2: - - I have it working fine. I recently replaced a very old implementation - of sendmail and Mailman 2 on Solaris with a new one on CentOS 6. When I - did so, I used the POSTFIX_ALIAS_CMD mechanism to automatically process - the aliases. See:: - - https://mail.python.org/pipermail/mailman-users/2004-June/037518.html - - In mm_cfg.py:: - - MTA='Postfix' - POSTFIX_ALIAS_CMD = '/usr/bin/sudo /etc/mail/import-mailman-aliases' - - /etc/mail/import-mailman-aliases contains:: - - #! /bin/sh - /bin/cp /etc/mailman/aliases /etc/mail/mailman.aliases - /usr/bin/newaliases - - In /etc/sudoers.d/mailman:: - - Cmnd_Alias IMPORT_MAILMAN_ALIASES = /etc/mail/import-mailman-aliases - apache ALL= NOPASSWD: IMPORT_MAILMAN_ALIASES - mailman ALL= NOPASSWD: IMPORT_MAILMAN_ALIASES - Defaults!IMPORT_MAILMAN_ALIASES !requiretty - - In the sendmail.mc file I changed:: - - define(`ALIAS_FILE', `/etc/aliases')dnl - - to:: - - define(`ALIAS_FILE', `/etc/aliases,/etc/mail/mailman.aliases')dnl - - so that the Mailman aliases would be in a separate file. - -The main issue here is that Mailman 2 expects to receive messages from -the MTA via pipes, whereas Mailman 3 uses LMTP exclusively. Recent -Sendmail does support LMTP, so it's a matter of configuring a stock -Sendmail. But rather than using aliases, it needs to be configured to -relay to the LMTP port of Mailman. - - -.. _`mailing list or on IRC`: START.html#contact-us -.. _`Local Mail Transfer Protocol`: - http://en.wikipedia.org/wiki/Local_Mail_Transfer_Protocol -.. _LMTP: http://www.faqs.org/rfcs/rfc2033.html -.. _`Simple Mail Transfer Protocol`: - http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol -.. _SMTP: http://www.faqs.org/rfcs/rfc5321.html -.. _Postfix: http://www.postfix.org -.. _`Variable Envelope Return Path`: - http://en.wikipedia.org/wiki/Variable_envelope_return_path -.. _postconf: http://www.postfix.org/postconf.1.html |