Disable quilt.
[mspang/vmailman.git] / 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: