UPGRADING

   1 Mailman - The GNU Mailing List Management System
   2 Copyright (C) 1998-2004 by the Free Software Foundation, Inc.
   3 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
   4
   5
   6 UPGRADING FROM PREVIOUS VERSIONS
   7
   8     For the most part, upgrading Mailman entails installing the latest version
   9     over the existing version.  Usually, you can unpack the new release, run
  10     'configure' with the same options you used in your previous install, and
  11     then do a 'make install'.  However, there are some changes that may need
  12     to be taken care of manually.
  13
  14     What you need to do depends on the version you are using and the version
  15     you are upgrading to.  In all cases, you should first turn off your mail
  16     and web access to your Mailman installation.  You're essentially upgrading
  17     a database, and it's usually a good idea to make sure the database cannot
  18     be modified in the middle of the upgrade.
  19
  20     My recommendations are:
  21
  22     - Turn off your incoming mail daemon.  Most remote smtp servers will
  23       simply queue up messages destined for your domain if port 25 is shut
  24       off.
  25
  26     - Temporarily disable web access to Mailman.  You can do this by either
  27       turning off your web server temporarily, or by setting up a temporary
  28       redirect to a "service unavailable" page for the Mailman URLs.  Refer to
  29       your web server documentation for details.
  30
  31
  32 UPGRADING FROM 2.1.4 to 2.1.5
  33
  34     In Mailman 2.1.5, some significant changes have been made to the file
  35     formats for qfiles and the pendings database.  All care has been taken to
  36     make sure the upgrades happen automatically and smoothly, but you should
  37     double check and, for the ultra-paranoid, make backups of your Mailman
  38     site before you upgrade.  BE SURE TO TURN OFF MAILMAN AS DESCRIBED ABOVE
  39     BEFORE YOU UPGRADE.
  40
  41     Specifically, in MM2.1.4 every message in the queues were represented by
  42     two files, a .msg or .pck file containing the email message, and a .db
  43     file containing metadata about the message.  In MM2.1.5 this has been made
  44     more efficient by using only one file (with a .pck extension) for both the
  45     message and metadata.  This should make MM2.1.5 half as hostile to the
  46     file system.
  47
  48     The bin/upgrade script, which is run automatically when you upgrade,
  49     should convert all the old style qfiles to the new style qfiles.  Note
  50     that this could take a long time if you have a lot of files in your qfiles
  51     subdirectories.  Pay particular attention to files you might have in
  52     qfiles/shunt; these will get upgraded too, although files in qfiles/bad
  53     will not.
  54
  55     In MM2.1.4, the database file containing pending actions (i.e
  56     subscriptions, unsubscriptions, message holds, etc.) was shared globally
  57     among all mailing lists.  In MM2.1.5, each list now has its own pending
  58     database file.  All care has been taken to properly split pending actions
  59     from the global to the list-specific files, but it's possible there are
  60     bugs here.  Best practice is to clear all pending actions before you
  61     upgrade, although this is not always possible.
  62
  63
  64 UPGRADING FROM 2.0.x to 2.1
  65
  66     When you upgrade from Mailman 2.0.x to Mailman 2.1, you should double
  67     check that your moderation and privacy options are still set the way you
  68     want them.  The Mailman options dealing with moderation and privacy have
  69     changed significantly, to make them easier to understand and control.
  70     Ever effort was taken to translate the old configuration variables to the
  71     new configuration variables, but because the old semantics were so
  72     complex, it is possible your settings may not have been correctly
  73     translated.
  74
  75     Check especially the values for (in Privacy -> Sender Filters)
  76     default_member_moderation, generic_nonmember_action, and
  77     accept_these_nonmembers.  Check also the moderation flag on member
  78     accounts in the Membership Management screen.
  79
  80     In Mailman 2.1, the qrunner subsystem has been completely
  81     rewritten.  You no longer start qrunner from cron!  Instead, there
  82     is a bin/mailmanctl script which is used to start, stop, and
  83     restart mail delivery.  This script is appropriate to use as a
  84     Unix init script.  Be sure to update your crontab with the new
  85     cron/crontab.in file.
  86
  87     NOTE: It is very important that if you are upgrading from a
  88     pre-MM2.1alpha2 system to a post-MM2.1alpha2 system that you let
  89     the old qrunner process clear any and all messages sitting in the
  90     qfiles/ directory *BEFORE* you upgrade.  Otherwise after the
  91     upgrade, those messages will not get delivered, and I'm not
  92     exactly sure yet how to upgrade those pending messages.
  93
  94     NOTE: When upgrading to Mailman 2.1, you will need to regenerate
  95     your aliases files.  There have been many changes to the alias
  96     names, the programs they map to, and the name of the wrapper
  97     script.  See README.<yourMTA> for details of making Mailman work
  98     with your mail server.
  99
 100     To regenerate your aliases, use the bin/genaliases script.
 101
 102     Mailman 2.1 introduces multilingual (a.k.a. internationalization
 103     or i18n) support.  Previously only one language per list was
 104     supported, and it was assumed that this language would be English.
 105     The upgrade script for Mailman 2.1 creates a subdirectory `en'
 106     inside each lists/<listname> directory.  It then copies all the
 107     .txt and .html files from lists/<listname> into
 108     lists/<listname>/en.
 109
 110     If you have modified those templates to contain non-English text,
 111     you will have to manually rename the en subdirectories to the
 112     language code for the language of your templates.  Mailman's
 113     upgrade script should handle cleaning up any templates which are
 114     duplicates of the defaults, but you'll want to double check this
 115     manually.
 116
 117     If you are running a MM2.0.x system with non-standard patches
 118     applied, you might have some other problems with your upgrade.
 119     Here are some instances we know about:
 120
 121     - If you've applied patch #413752 (coerce to plaintext), then your
 122       upgraded will not go smoothly.  Take a look at patch #651406 for
 123       an unofficial solution.
 124
 125       http://sf.net/tracker/?group_id=103&atid=300103&func=detail&aid=413752
 126       http://sf.net/tracker/?group_id=103&atid=300103&func=detail&aid=651406
 127
 128
 129 UPGRADING INDIVIDUAL LISTS
 130
 131     If you're nervous about upgrading all of your lists to 2.1 in one
 132     go, you can move them and upgrade them one at a time.  Start by
 133     doing a clean Mailman 2.1 installation in an empty directory --
 134     call it $MM21.  (I'll assume your Mailman 2.0 installation is in
 135     $MM20.)
 136
 137     Doing this means you'll have co-habiting Mailman 2.0 and 2.1
 138     installations for a while, until you have moved all of your lists
 139     to Mailman 2.1.  Depending on your MTA and web server, this could
 140     be transparent and painless, or it could be an ongoing headache.
 141
 142     If you use Apache with mod_rewrite, then it's fairly
 143     straightforward to set things up so that both Mailman 2.0 and 2.1
 144     inhabit the /mailman and /pipermail URL-space of your server; this
 145     makes the transition almost transparent to list admins and
 146     subscribers.  See below for details.
 147
 148     Now, for each list that you want to move, you'll have to
 149
 150       * Shut down your MTA.
 151
 152         If you have a lot of outgoing list traffic, you might need to
 153         leave your MTA up but only let it accept connections from
 154         127.0.0.1 (localhost), so Mailman 2.0 can flush its queue.
 155         How to do this is MTA-dependent; for Exim, you can set
 156         "local_interfaces = 127.0.0.1" and "kill -HUP" the Exim
 157         daemon.
 158
 159       * Shut down your web server.  For a more professional look, or
 160         if you want to allow people to keep accessing the rest of your
 161         web site, you could make your web server respond to all
 162         /mailman/ URLs with a "temporarily unavailable" message.
 163
 164         How to do this is web server-dependent; with Apache and
 165         mod_rewrite, this does the trick:
 166
 167           RewriteRule ^/mailman/.* /var/www/unavailable.html [L]
 168
 169         (Of course, you'll have to supply your own
 170         /var/www/unavailable.html.)
 171
 172       * Force Mailman 2.0 to process its queue:
 173
 174           python -S $MM20/cron/qrunner
 175
 176         (This is only necessary if there are any files in $MM20/qfiles;
 177         if you need to do this, make sure you left your MTA listening to
 178         127.0.0.1.)
 179
 180       * Move the list:
 181
 182           cd $MM20
 183           mv -i lists/foo-list $MM21/lists
 184           mv -i archives/private/foo-list $MM21/archives/private
 185           mv -i archives/private/foo-list.mbox $MM21/archives/private
 186           rm archives/public/foo-list
 187           rm archives/public/foo-list.mbox
 188           cd $MM21
 189           bin/withlist -l -r fix_url mylist
 190
 191         (The fix_url step will not be necessary if your Mailman 2.0
 192         and 2.1 installations will be sharing the same URL-space.)
 193
 194       * Edit your web server config so the list's URLs continue to
 195         work.  There are two possible approaches here; the simpler way
 196         is to setup a new slice of URL-space that will be used by your
 197         Mailman 2.1 installation, eg. /mailman-21:
 198         With Apache and mod_rewrite:
 199
 200           RewriteRule /mailman/(.*)/(foo-list.*) /mailman-21/$1/$2 [R=temp]
 201
 202         (The [R=temp] assumes that "/mailman-21/" is a temporary URL,
 203         and you'll move all your lists to "/mailman/" when the
 204         transition to Mailman 2.1 is complete.)
 205
 206         If you don't want to expose ugly temporary URLs like
 207         "/mailman-21" to the world, it's only slightly more work to make
 208         Mailman 2.0 and 2.1 share the same slices of URL-space.  Here's
 209         how to do it with Apache and mod_rewrite:
 210
 211           RewriteRule ^/mailman/(.*)/(foo-list.*) \
 212                       $MM21/cgi-bin/$1/$2 \
 213                       [T=application/x-httpd-cgi]
 214
 215         Not only is this more aesthetically pleasing, it's faster -- no
 216         redirects.
 217
 218         In either case, you'll want to rewrite the list's archive URLs
 219         to Mailman 2.1's archive:
 220
 221           RewriteRule ^/pipermail/(foo-list.*) $MM21/archives/public/$1
 222
 223       * Restart your web server (or disable the "temporarily
 224         unavailable" stuff).
 225
 226       * Restart your MTA (or make it listen to more than just
 227         127.0.0.1).
 228
 229
 230 UPGRADING FROM 2.0 to 2.0.x (where x >= 1)
 231
 232     Nothing much more than running "make install" (after upgrading)
 233     should be necessary.
 234
 235
 236 UPGRADING FROM 2.0 beta to 2.0 final
 237
 238     You MUST re-run configure; running config.status is not sufficient
 239     due to some recent changes in the autoconf scripts.  You can do a
 240     head of config.status if you don't remember the options you
 241     originally ran configure with.
 242
 243     The cron jobs for Mailman 2.0 final have changed considerably,
 244     including the frequency with which they run.  You should reload
 245     misc/crontab.in for the `mailman' user to get the right settings.
 246     See the INSTALL file for details.
 247
 248     FAILURE TO DO THIS WILL RESULT IN A LESS THAN OPTIMALLY FUNCTIONAL
 249     MAILMAN INSTALLATION.
 250
 251
 252 UPGRADING FROM 1.x to 2.x
 253
 254     In addition to the instructions above, I highly recommend that you
 255     make sure your Mailman queue is cleared /before/ upgrading.
 256
 257     Mailman version 1.x had a cron script called run_queue which was
 258     part of its bulk mailer.  With Mailman 2.x there is no default
 259     bulk mailer (it lets the MTA handle this), and it is currently
 260     unknown what the effects of upgrading are on the run_queue script,
 261     but I'll bet it's not good. :)
 262
 263     The way to make sure that your Mailman queue is empty is to look
 264     in your $prefix/data directory.  If you see any files that start
 265     with "mm_q." you've still got messages waiting on the queue.  You
 266     can run $prefix/cron/run_queue by hand until the queue is cleared.
 267     Multiple invocations of this script won't help though; they lock
 268     each other out.  Also, be warned that clearing the queue can take
 269     a while and may cause a large load on your system (two reasons why
 270     all this stuff has been redesigned in 2.x :).
 271
 272     You do not need to run "make update" if you are upgrading from
 273     version 1.0 or 1.1 to version 2.0, since this is now run
 274     automatically when you do a "make install".  However you should
 275     modify your crontab entries to execute cron/qrunner instead of
 276     cron/run_queue.  You can also safely remove the file
 277     $prefix/cron/run_queue.
 278
 279     If you are upgrading from a pre-1.0 beta, you need to follow the
 280     instructions below.
 281
 282
 283 UPGRADING FROM PRE-1.0 to 2.x
 284
 285     You need to do a few extra things to make sure that the file
 286     system layout for the early 1.0 betas is upgraded to the 1.x
 287     configuration.  There are two ways to do this.
 288
 289     First, from the source directory, after you've done a "make
 290     install" you can run "make update".  "make update" creates a file
 291     named "update.log" in the top level of the source distribution.
 292     If the script that updates the Mailman filesystem encounters
 293     something that is not resolvable, it will log info about this to
 294     "update.log".  This is worth checking after the upgrade completes.
 295
 296     You can also just change to the installation directory (i.e. $prefix)
 297     and run bin/update.  This is the same as above except that the
 298     update.log file is not generated.
 299
 300     Check your crontab entry.  Remove any runs of obsolete scripts, in
 301     particular cron/upvolumes_yearly, cron/upvolumes_monthly, or
 302     cron/archive.
 303
 304
 305 WHAT "MAKE UPDATE" DOES
 306
 307     Below is an annotated listing of the things that "make update"
 308     does.  Hopefully, this will help resolve any problems you are
 309     having.
 310
 311     Note that it can't hurt to run "make update" each time you
 312     upgrade, but if you're running version 1.0 or newer, it won't help
 313     much either!
 314
 315     - To upgrade to 1.0b10, you will need to copy
 316       templates/options.html to lists/<listname>/options.html for each
 317       mailing list you have.  However, if you have edited the
 318       options.html file, say from the Web interface, you will have to
 319       merge these changes in manually.
 320
 321     - The upgrade to 1.0b7 included the removal of
 322       Mailman/smtplib.py{,c} since Mailman now uses the default Python
 323       1.5.2 version of smtplib.
 324
 325     - Archiving files are moved around as part of integrating
 326       Pipermail into Mailman, as of 1.0b6.  In particular,
 327
 328       1) if a list has only a private mbox archive
 329       $prefix/archives/private/<listname> is moved to
 330       $prefix/archives/private/<listname>.mbox/<listname>
 331
 332       2) if a list has only a public mbox archive
 333       $prefix/archives/public/<listname> is moved to
 334       $prefix/archives/private/<listname>.mbox/<listname>
 335
 336       and a symlink is made that points
 337       $prefix/archives/public/<listname>.mbox to
 338       $prefix/archives/private/<listname>.mbox/<listname>
 339
 340       3) if a list has both private and public mbox archives,
 341       make update picks one of the above 2 configurations based on
 342       whether or not the list currently is archived publicly.  It then
 343       renames the other mbox to mbox.preb6.
 344
 345       4) if a list used recent CVS sources, where archives were placed in
 346       $prefix/public_html/archives, then these are moved to
 347       $prefix/archives/private/<listname> and a symlink is made from
 348       $prefix/archives/public/<listname> to that spot if the list's
 349       archives are public.  Also, a permissions-related security
 350       problem is removed.
 351
 352       To integrate mbox archives of old lists, log in as user `mailman'
 353       and run $prefix/bin/arch <listname> <path-to-mbox-archive>.
 354
 355       Also, by default, beta6 does both mbox and html based archiving,
 356       but you can configure Mailman to do one, both, or neither.
 357       Please see $prefix/Mailman/Defaults.py for details.
 358
 359       There was a short period of time when the CVS sources archiving
 360       code was not organized into its own package.  The pickled
 361       articles in the archives that were placed into archives during
 362       this period stored the path to the module HyperArch, but that
 363       module has moved.  You can quick fix this by running
 364
 365       ln -s $prefix/Mailman/Archiver/HyperArch.py \
 366               $prefix/Mailman/HyperArch.py
 367
 368     - If upgrading from version 1.0b4 or earlier, "make update" moves
 369       list-specific templates.  For each list,
 370       $prefix/templates/<listname>/* is moved to $prefix/lists/<listname>.
 371       Please reference the generic templates in $prefix/templates to see
 372       if any variables have changed (There shouldn't be many, only
 373       options.html was updated from b5 to b6).
 374
 375       For really old versions of Mailman, you may not even have
 376       <listname> subdirectories in $prefix/templates!  In this case
 377       you will need to manually copy some files into your new list
 378       directories.  Here's an example shell command that will do the
 379       trick:
 380
 381       cp templates/{archives,handle_opts,listinfo,roster,subscribe}.html lists/<listname>
 382
 383     - Some modules that existed in previous versions, but that have
 384       been replaced with newer (differently named) modules, are
 385       removed.
 386
 387
 388 \f
 389 Local Variables:
 390 mode: indented-text
 391 indent-tabs-mode: nil
 392 End: