howto/mailman21.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <title>HOWTO - Using exim and Mailman together</title>
   5   </head>
   6
   7   <body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
   8     <h1>HOWTO - Using exim and Mailman 2.1 together</h1>
   9
  10     <p>Mailman is a list manager with web front end and built in
  11       archiving functions.  Details can be found at <a href="http://www.list.org/">
  12         http://www.list.org/</a>.  This documentation describes the
  13       configuration of Exim (version 3 or 4) to work with Mailman
  14       version 2.1</p>
  15
  16
  17
  18     <h2>Mailman configuration</h2>
  19
  20     <p>There is no Mailman configuration needed other than the
  21     standard options detailed in the Mailman install documentation.
  22     The Exim configuration is transparent to Mailman.  The user/group
  23     settings for Mailman must match those in the config fragments
  24     given below.</p>
  25
  26
  27     <h2>Exim configuration</h2>
  28
  29     <p>The Exim configuration is built so that a list created within
  30     Mailman automatically appears to Exim without the need for
  31     defining any additional aliases.</p>
  32
  33     <p>The drawback of this configuration is that it will work poorly
  34     on systems supporting lists in several different mail domains.
  35     While Mailman handles virtual domains, it does not yet support
  36     having two distinct lists with the same name in different virtual
  37     domains, using the same Mailman installation.  This will
  38     eventually change.  (But see below for a variation on this scheme
  39     that should accomodate virtual domains better.)</p>
  40
  41     <p>The configuration file excerpts below are for use in an already
  42     functional Exim configuration, which accepts mail for the domain
  43     in which the list resides.  If this domain is separate from the
  44     others handled by your Exim configuration, then you'll need to:</p>
  45
  46     <ul>
  47
  48       <li>add the list domain, <tt>"my.list.domain"</tt> to local_domains</li>
  49
  50       <li>add a <tt>"domains=my.list.domain"</tt> option to the
  51       director (router) for the list</li>
  52
  53       <li>(optional) exclude that domain from the other directors
  54       (routers)</li>
  55     </ul>
  56
  57     <p><i>[Note: the instructions in this document should work with
  58     either Exim 3 or Exim 4.  In Exim 3, you must have a
  59     <tt>'local_domains'</tt> configuration setting; in Exim 4, you
  60     most likely have a <tt>'local_domains'</tt> domainlist.  If you
  61     don't, you probably know what you're doing and can adjust
  62     accordingly.  Similarly, in Exim 4 the concept of "directors" has
  63     disappeared -- there are only routers now.  So if you're using
  64     Exim 4, whenever this document says "director", read
  65     "router".]</i></p>
  66
  67     <p>Whether you are using Exim 3 or Exim 4, you will need to add
  68     some macros to the main section of your Exim config file.  You
  69     will also need to define one new transport.  With Exim 3, you'll
  70     need to add a new director; with Exim 4, a new router plays
  71     the same role.</p>
  72
  73     <p>Finally, the configuration supplied here should allow
  74     co-habiting Mailman 2.0 and 2.1 installations, with the proviso
  75     that you'll probably want to use <tt>"mm21"</tt> in place of
  76     <tt>"mailman"</tt> -- e.g., <tt>MM21_HOME</tt>,
  77     <tt>mm21_transport</tt>, etc.</p>
  78
  79
  80     <h2>Main configuration settings</h2>
  81
  82     <p>First, you need to add some macros to the top of your Exim
  83     config file.  These just make the directors (routers) and
  84     transport below a bit cleaner.  Obviously, you'll need to edit
  85     these based on how you configured and installed Mailman.</p>
  86
  87 <pre>
  88   # Home dir for your Mailman installation -- aka Mailman's prefix
  89   # directory.
  90   MAILMAN_HOME=/usr/local/mailman
  91   MAILMAN_WRAP=MAILMAN_HOME/mail/mailman
  92
  93   # User and group for Mailman, should match your --with-mail-gid
  94   # switch to Mailman's configure script.
  95   MAILMAN_UID=mailman
  96   MAILMAN_GID=mailman
  97 </pre>
  98
  99     <h2>Transport for Exim 3</h2>
 100
 101     <p>Add this to the transports section of your Exim config file,
 102       i.e. somewhere between the first and second "end" line:</p>
 103
 104 <pre>
 105   mailman_transport:
 106     driver = pipe
 107     command = MAILMAN_WRAP \
 108               '${if def:local_part_suffix \
 109                     {${sg{$local_part_suffix}{-(\\w+)(\\+.*)?}{\$1}}} \
 110                     {post}}' \
 111               $local_part
 112     current_directory = MAILMAN_HOME
 113     home_directory = MAILMAN_HOME
 114     user = MAILMAN_UID
 115     group = MAILMAN_GID
 116 </pre>
 117
 118     <p><i>(XXX this is untested by me under Exim 3!  Can someone using
 119     Exim 3 please let me know if it works?)</i></p>
 120
 121
 122     <h2>Director for Exim 3</h2>
 123
 124
 125     <p>If you're using Exim 3, you'll need to add the following
 126     director to your config file (directors go between the second and
 127     third "end" lines).  Also, don't forget that order matters --
 128     eg. you can make Mailman lists take precedence over system aliases
 129     by putting this directors in front of your aliasfile director, or
 130     vice-versa.</p>
 131
 132 <pre>
 133   # Handle all addresses related to a list 'foo': the posting address.
 134   # Automatically detects list existence by looking
 135   # for lists/$local_part/config.pck under MAILMAN_HOME.
 136   mailman_director:
 137     driver = smartuser
 138     require_files = MAILMAN_HOME/lists/$local_part/config.pck
 139     suffix_optional
 140     suffix = -bounces : -bounces+* : \
 141              -confirm+* : -join : -leave : \
 142              -owner : -request : -admin
 143     transport = mailman_transport
 144 </pre>
 145
 146     <h2>Router for Exim 4</h2>
 147
 148     <p>In Exim 4, there are no such things as directors -- you instead
 149     need to add a router.  Also, the canonical order of the
 150     configuration file was changed so routers come before transports,
 151     so the routers for Exim 4 come first here.  Put these two routers
 152     somewhere after the <tt>"begin routers"</tt> line of your config
 153     file, and remember that order matters.</p>
 154
 155 <pre>
 156   mailman_router:
 157     driver = accept
 158     require_files = MAILMAN_HOME/lists/$local_part/config.pck
 159     local_part_suffix_optional
 160     local_part_suffix = -bounces : -bounces+* : \
 161                         -confirm+* : -join : -leave : \
 162                         -owner : -request : -admin
 163     transport = mailman_transport
 164 </pre>
 165
 166     <h2>Transports for Exim 4</h2>
 167
 168     <p>The transport for Exim 4 is the same as for Exim 3; just copy
 169     the transport given above to somewhere under the "begin
 170     transports" line of your Exim config file.</p>
 171
 172
 173     <h2>Notes</h2>
 174
 175     <p>Exim should be configured to allow reasonable volume --
 176     e.g. don't set max_recipients down to a silly value -- and with
 177     normal degrees of security -- specifically, be sure to allow
 178     relaying from 127.0.0.1, but pretty much nothing else.  Parallel
 179     deliveries and other tweaks can also be used if you like;
 180     experiment with your setup to see what works.  Delay warning
 181     messages should be switched off or configured to only happen for
 182     non-list mail, unless you like receiving tons of mail when some
 183     random host is down.</p>
 184
 185
 186     <h2>Problems</h2>
 187
 188     <ul>
 189
 190       <li> Mailman will send as many <tt>MAIL FROM/RCPT TO</tt> as it
 191       needs. It may result in more than 10 or 100 messages sent in one
 192       connection, which will exceed the default value of Exim's
 193       smtp_accept_queue_per_connection This is bad because it will
 194       cause Exim to switch into queue mode and severely delay delivery
 195       of your list messages.  The way to fix this is to set mailman's
 196       <tt>SMTP_MAX_SESSIONS_PER_CONNECTION</tt> (in
 197       <tt>~mailman/Mailman/mm_cfg.py</tt>) to a smaller value than
 198       Exim's <tt>smtp_accept_queue_per_connection</tt></li>
 199
 200       <li>Mailman should ignore Exim delay warning messages, even
 201       though Exim should never send this to list messages.  Mailman
 202       2.1's general bounce detection and VERP support should greatly
 203       improve the bounce detector's hit rates.</li>
 204
 205       <li>List existence is determined by the existence of a
 206       config.pck file for a list.  If you delete lists by foul means,
 207       be aware of this.</li>
 208
 209       <li>If you are getting Exim or Mailman complaining about user
 210       ids when you send mail to a list, check that the
 211       <tt>MAILMAN_UID</tt> and <tt>MAILMAN_GID</tt> match those of
 212       Mailman itself (i.e. what were used in the configure script).
 213       Also make sure you do not have aliases in the main alias file
 214       for the list.</li>
 215
 216     </ul>
 217
 218
 219     <h2>Receiver Verification</h2>
 220
 221     <P>Exim's receiver verification feature is very useful -- it lets
 222     Exim reject unrouteable addresses at SMTP time.  However, this is
 223     most useful for externally-originating mail that is addresses to
 224     mail in one of your local domains.  For Mailman list traffic, mail
 225     originates on your server, and is addressed to random external
 226     domains that are not under your control.  Furthermore, each
 227     message is addressed to many recipients -- up to 500 if you use
 228     Mailman's default configuration, and don't tweak
 229     <tt>SMTP_MAX_RCPTS</tt>.</p>
 230
 231     <p>Doing receiver verification on Mailman list traffic is a recipe
 232     for trouble.  In particular, Exim will attempt to route every
 233     recipient addresses in outgoing Mailman list posts.  Even though
 234     this requires nothing more than a few DNS lookups for each
 235     address, it can still introduce significant delays.  Therefore,
 236     you should disable recipient verification for Mailman traffic.</p>
 237
 238     <p>Under Exim 3, put this in your main configuration section:</p>
 239 <pre>
 240   receiver_verify_hosts = !127.0.0.1
 241 </pre>
 242
 243     <p>Under Exim 4, this is probably already taken care of for you by
 244     the default recipient verification ACL statement (in the "RCPT TO"
 245     ACL):</p>
 246
 247 <pre>
 248   accept  domains       = +local_domains
 249           endpass
 250           message       = unknown user
 251           verify        = recipient
 252 </pre>
 253
 254     <p>which only does recipient verification on addresses in your
 255     domain.  (That's not exactly the same as doing recipient
 256     verification only on messages coming from non-127.0.0.1 hosts, but
 257     it should do the trick for Mailman.)</p>
 258
 259
 260     <h2>SMTP Callback</h2>
 261
 262     <p>Exim's SMTP callback feature is an even more powerful way to
 263     detect bogus sender addresses than normal sender verification.
 264     Unfortunately, lots of servers send bounce messages with a bogus
 265     address in the header, and there are plenty that sound bounces
 266     with bogus envelope senders (even though they're supposed to just
 267     use an epmty envelope sender for bounces).</p>
 268
 269     <p>In order to ensure that Mailman can disable/remove bouncing
 270     addresses, you generally want to receive bounces for Mailman
 271     lists, even if those bounces are themselves not bouncable.  Thus,
 272     you might want to disable SMTP callback on bounce messages.</p>
 273
 274     <p>If you do header and envelope callbacks, you can disable them
 275     for bounces to mailman lists (it is quite common for internal
 276     hosts to bounce with a non reachable internal address). The idea
 277     is that you typically don't want non bounceable Email, but you'd
 278     better accept bounces to mailman lists so that you can unsubscribe
 279     the people who are bouncing.</p>
 280
 281     <p>With Exim 4, you can accomplish this using something like the
 282     following in your <tt>"RCPT TO"</tt> ACL:</p>
 283
 284 <pre>
 285   # Accept bounces to lists even if callbacks or other checks would fail
 286   warn     message      = X-WhitelistedRCPT-nohdrfromcallback: Yes
 287            condition    = \
 288            ${if and {{match{$local_part}{(.*)-bounces\+.*}}
 289                      {exists {MAILMAN_HOME/lists/$1/config.pck}}} \
 290                 {yes}{no}}
 291                 {yes}{no}}
 292
 293   accept   condition    = \
 294            ${if and {{match{$local_part}{(.*)-bounces\+.*}}
 295                      {exists {MAILMAN_HOME/lists/$1/config.pck}}} \
 296                 {yes}{no}}
 297                 {yes}{no}}
 298
 299   # Now, check sender address with SMTP callback.
 300   deny   !verify = sender/callout=90s/check_postmaster
 301 </pre>
 302
 303     <p>If you also do SMTP callbacks on header addresses, you'll want
 304     something like this in your "DATA" ACL:</p>
 305
 306 <pre>
 307   deny   !condition = $header_X-WhitelistedRCPT-nohdrfromcallback:
 308          !verify = header_sender/callout=90s/check_postmaster
 309 </pre>
 310
 311     <p><i>[XXX all this stuff is completely untested by me!
 312     -Greg]</i></p>
 313
 314
 315     <h2>Doing VERP with Exim and Mailman</h2>
 316
 317     <p>VERP will send one email, with a separate envelope sender
 318     (return path), for each of your subscribers -- read the
 319     information in <tt>~mailman/Mailman/Default.py</tt> for the
 320     options that start with <tt>VERP</tt>.  In a nutshell, all you
 321     need to do to enable VERP with Exim is to add these lines to
 322     <tt>~mailman/Mailman/mm_cfg.py</tt>:</p>
 323
 324 <pre>
 325   VERP_PASSWORD_REMINDERS = 1
 326   VERP_PERSONALIZED_DELIVERIES = 1
 327   VERP_DELIVERY_INTERVAL = 1
 328   VERP_CONFIRMATIONS = 1
 329 </pre>
 330
 331     <p>(The directors/routers above are smart enough to deal with VERP
 332     bounces.)</p>
 333
 334
 335 <h2>Virtual Domains</h2>
 336
 337     <p>One approach to handling virtual domains is to use a separate
 338     Mailman installation for each virtual domain.  (Currently, this is
 339     the only way to have lists with the same name in different virtual
 340     domains handled by the same machine.)</p>
 341
 342     <p>In this case, the <tt>MAILMAN_HOME</tt> and
 343     <tt>MAILMAN_WRAP</tt> macros are useless -- you can remove them.
 344     Change your director (router) to something like this:</p>
 345
 346 <pre>
 347   require_files = /virtual/${domain}/mailman/lists/${lc:$local_part}/config.pck
 348 </pre>
 349
 350     <p>and change your transport like this:</p>
 351
 352 <pre>
 353   command = /virtual/${domain}/mailman/mail/mailman \
 354             ${if def:local_part_suffix \
 355                  {${sg{$local_part_suffix}{-(\\w+)(\\+.*)?}{\$1}}}
 356                  {post}} \
 357               $local_part
 358   current_directory = /virtual/${domain}/mailman
 359   home_directory = /virtual/${domain}/mailman
 360 </pre>
 361
 362 <h2>List Verification</h2>
 363
 364     <p>This is how a set of address tests for the Exim lists look on a
 365     working system.  The list in question is
 366     <tt>quixote-users@mems-exchange.org</tt>, and these commands were
 367     run on the <tt>mems-exchange.org</tt> mail server (<tt>"% "</tt>
 368     indicates the Unix shell prompt):</p>
 369
 370 <pre>
 371   % exim -bt quixote-users
 372   quixote-users@mems-exchange.org
 373     router = mailman_main_router, transport = mailman_transport
 374
 375   % exim -bt quixote-users-request
 376   quixote-users-request@mems-exchange.org
 377     router = mailman_router, transport = mailman_transport
 378
 379   % exim -bt quixote-users-bounces
 380   quixote-users-bounces@mems-exchange.org
 381     router = mailman_router, transport = mailman_transport
 382
 383   % exim -bt quixote-users-bounces+luser=example.com
 384   quixote-users-bounces+luser=example.com@mems-exchange.org
 385     router = mailman_router, transport = mailman_transport
 386 </pre>
 387
 388     <p>If your <tt>"exim -bt"</tt> output looks something like this,
 389     that's a start: at least it means Exim will pass the right
 390     messages to the right Mailman commands.  It by no means guarantees
 391     that your Exim/Mailman installation is functioning perfectly,
 392     though!</p>
 393
 394
 395     <h2>Document History</h2>
 396
 397     <p>Originally written by Nigel Metheringham.  Updated by Marc
 398     Merlin for Mailman 2.1, Exim 4.
 399     Overhauled/reformatted/clarified/simplified by Greg Ward.</p>
 400
 401     <hr>
 402     <h4>$Id: mailman.html,v 1.3 2002/06/14 10:42:18 nigel Exp $</h4>
 403   </body>
 404 </html>