1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>5. Upgrading Sympa</TITLE>
<META NAME="description" CONTENT="5. Upgrading Sympa">
<META NAME="keywords" CONTENT="sympa">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="sympa.css">
<LINK REL="next" HREF="node7.html">
<LINK REL="previous" HREF="node5.html">
<LINK REL="up" HREF="sympa.html">
<LINK REL="next" HREF="node7.html">
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#ffffff">
<!--Navigation Panel-->
<A NAME="tex2html855"
HREF="node7.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html849"
HREF="sympa.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html843"
HREF="node5.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html851"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html853"
HREF="node30.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html856"
HREF="node7.html">6. Mail aliases</A>
<B> Up:</B> <A NAME="tex2html850"
HREF="sympa.html">Sympa Mailing Lists Management Software version</A>
<B> Previous:</B> <A NAME="tex2html844"
HREF="node5.html">4. Running Sympa</A>
<B> <A NAME="tex2html852"
HREF="node1.html">Contents</A></B>
<B> <A NAME="tex2html854"
HREF="node30.html">Index</A></B>
<BR>
<BR>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL>
<LI><A NAME="tex2html857"
HREF="node6.html#SECTION00610000000000000000">5.1 Incompatible changes</A>
<LI><A NAME="tex2html858"
HREF="node6.html#SECTION00620000000000000000">5.2 CPAN modules update</A>
<LI><A NAME="tex2html859"
HREF="node6.html#SECTION00630000000000000000">5.3 Database structure update</A>
<LI><A NAME="tex2html860"
HREF="node6.html#SECTION00640000000000000000">5.4 Preserving your customizations</A>
<LI><A NAME="tex2html861"
HREF="node6.html#SECTION00650000000000000000">5.5 Running 2 Sympa versions on a single server</A>
<LI><A NAME="tex2html862"
HREF="node6.html#SECTION00660000000000000000">5.6 Moving to another server</A>
</UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION00600000000000000000"></A>
<A NAME="upgrading-sympa"></A>
<BR>
5. Upgrading Sympa
</H1>
<P>
Sympa upgrade is a relatively riskless operations, mainly because the install process preserves your
customizations (templates, configuration, authorization scenarios,...) and also because Sympa automates
a few things (DB update, CPAN modules installation).
<P>
<H1><A NAME="SECTION00610000000000000000"></A>
<A NAME="665"></A>
<BR>
5.1 Incompatible changes
</H1>
<P>
New features, changes and bug fixes are summarized in the <A NAME="7644"></A><TT>NEWS</TT> file, part of the tar.gz (the
<A NAME="7647"></A><TT>Changelog</TT> file is a complete log file of CVS changes).
<P>
Sympa is a long-term project, so some major changes may need some extra work. The following list is well kown changes that require some attention :
<UL>
<LI>version 5.1 (August 2005) use XHTML and CSS in web templates
</LI>
<LI>version 4.2b3 (August 2004) introduce TT2 template format
</LI>
<LI>version 4.0a5 (September 2003) change auth.conf (no default anymore so you may have the create this file)
</LI>
<LI>version 3.3.6b2 (May 2002) the list parameter user_data_source as a new value include2 which is the recommended value for any list.
</LI>
</UL>
<P>
The file <A NAME="7650"></A><TT>NEWS</TT> list all changes and of course, all changes that may require some attention from the installer. As mentionned at the beginning of this
file, incompatible changes are preceded by '*****'. While running the <A NAME="7653"></A><TT>make install</TT> Sympa will
detect the previously installed version and will prompt you with incompatible changes between both versions
of the software. You can interrupt the install process at that stage if you are too frightened.
Output of the <A NAME="7656"></A><TT>make install</TT> :<PRE>
You are upgrading from Sympa 4.2
You should read CAREFULLY the changes listed below ; they might be incompatible changes :
<RETURN>
***** require new perlmodule XML-LibXML
***** You should update your DB structure (automatically performed by Sympa with MySQL), adding the following table (mySQL example) :
***** CREATE TABLE admin_table (
***** list_admin varchar(50) NOT NULL,
***** user_admin varchar(100) NOT NULL,
***** role_admin enum('listmaster','owner','editor') NOT NULL,
***** date_admin datetime NOT NULL,
***** update_admin datetime,
***** reception_admin varchar(20),
***** comment_admin varchar(150),
***** subscribed_admin enum('0','1'),
***** included_admin enum('0','1'),
***** include_sources_admin varchar(50),
***** info_admin varchar(150),
***** profile_admin enum('privileged','normal'),
***** PRIMARY KEY (list_admin, user_admin,role_admin),
***** INDEX (list_admin, user_admin,role_admin)
***** );
***** Extend the generic_sso feature ; Sympa is now able to retrieve the user email address in a LDAP directory
<RETURN>
</PRE>
<P>
<H1><A NAME="SECTION00620000000000000000"></A>
<A NAME="678"></A>
<BR>
5.2 CPAN modules update
</H1>
<P>
Required and optional perl modules (CPAN) installation is automatically handled at the <A NAME="7659"></A><TT>make</TT> time. You are asked before each module is installed. For optional modules, associated features are listed.
<P>
Output of the <A NAME="7662"></A><TT>make</TT> command :<PRE>
Checking for REQUIRED modules:
------------------------------------------
perl module from CPAN STATUS
----------- --------- ------
Archive::Zip Archive-Zip OK (1.09 >= 1.05)
CGI CGI OK (2.89 >= 2.52)
DB_File DB_FILE OK (1.806 >= 1.75)
Digest::MD5 Digest-MD5 OK (2.20 >= 2.00)
FCGI FCGI OK (0.67 >= 0.67)
File::Spec File-Spec OK (0.83 >= 0.8)
IO::Scalar IO-stringy OK (2.104 >= 1.0)
LWP libwww-perl OK (5.65 >= 1.0)
Locale::TextDomain libintl-perl OK (1.10 >= 1.0)
MHonArc::UTF8 MHonArc version is too old ( < 2.4.6).
>>>>>>> You must update "MHonArc" to version "" <<<<<<.
Setting FTP Passive mode
Description:
Install module MHonArc::UTF8 ? n
MIME::Base64 MIME-Base64 OK (3.05 >= 3.03)
MIME::Tools MIME-tools OK (5.411 >= 5.209)
Mail::Internet MailTools OK (1.60 >= 1.51)
Regexp::Common Regexp-Common OK (2.113 >= 1.0)
Template Template-ToolkitOK (2.13 >= 1.0)
XML::LibXML XML-LibXML OK (1.58 >= 1.0)
Checking for OPTIONAL modules:
------------------------------------------
perl module from CPAN STATUS
----------- --------- ------
Bundle::LWP LWP OK (1.09 >= 1.09)
Constant subroutine CGI::XHTML_DTD redefined at /usr/lib/perl5/5.8.0/constant.pm line 108, <STDIN> line 1.
CGI::Fast CGI CGI::Fast doesn't return 1 (check it).
Crypt::CipherSaber CipherSaber OK (0.61 >= 0.50)
DBD::Oracle DBD-Oracle was not found on this system.
Description: Oracle database driver, required if you connect to a Oracle database.
Install module DBD::Oracle ?
</PRE>
<P>
<H1><A NAME="SECTION00630000000000000000"></A>
<A NAME="686"></A>
<BR>
5.3 Database structure update
</H1>
<P>
Whatever RDBMS you are using (mysql, SQLite, Pg, Sybase or Oracle) Sympa will check every database tables and fields. If one is missing <A NAME="7665"></A><TT>sympa.pl</TT>
will not start. If you are using <A NAME="7668"></A>mysql Sympa will also check field types and will try to change them (or create them) automatically ;
assuming that the DB user configured has sufficient privileges. If You are not using Mysql or if the DB user configured in <A NAME="7669"></A><TT>sympa.conf</TT>
does have sufficient privileges, then you should change the database structure yourself, as mentionned in the <A NAME="7672"></A><TT>NEWS</TT> file.
<P>
Output of Sympa logs :<PRE>
Table admin_table created in database sympa
Field 'comment_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field comment_admin added to table admin_table
Field 'date_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field date_admin added to table admin_table
Field 'include_sources_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field include_sources_admin added to table admin_table
Field 'included_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field included_admin added to table admin_table
Field 'info_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field info_admin added to table admin_table
Field 'list_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field list_admin added to table admin_table
Field 'profile_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field profile_admin added to table admin_table
Field 'reception_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field reception_admin added to table admin_table
Field 'role_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field role_admin added to table admin_table
Field 'subscribed_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field subscribed_admin added to table admin_table
Field 'update_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Field update_admin added to table admin_table
Field 'user_admin' (table 'admin_table' ; database 'sympa') was NOT found. Attempting to add it...
Setting list_admin,user_admin,role_admin fields as PRIMARY
Field user_admin added to table admin_table
</PRE>
<P>
You might need, for some reason, to make Sympa run the migration procedure from version <I>X</I> to version <I>Y</I>.
This procedure is run automatically by <A NAME="7675"></A><TT>sympa.pl</TT> when it detects that <A NAME="7678"></A><TT>/data_structure.version</TT> is older
than the current version, but you can also run trigger this procedure yourself :<PRE>
sympa.pl --upgrade --from=4.1 --to=5.2
</PRE>
<P>
<H1><A NAME="SECTION00640000000000000000"></A>
<A NAME="704"></A>
<BR>
5.4 Preserving your customizations
</H1>
<P>
Sympa comes with default configuration files (templates, scenarios,...) that will be installed in the <A NAME="7681"></A><TT>/home/sympa/bin</TT> directory.
If you need to customize some of them, you should copy the file first in a safe place, ie in the <A NAME="7684"></A><TT>/home/sympa/etc</TT> directory.
If you do so, the Sympa upgrade process will preserve your site customizations.
<P>
<H1><A NAME="SECTION00650000000000000000"></A>
<A NAME="708"></A>
<BR>
5.5 Running 2 Sympa versions on a single server
</H1>
<P>
This can be very convenient to have a stable version of Sympa and a fresh version for test purpose, both running on the same server.
<P>
Both sympa instances must be completely partitioned, unless you want the make production mailing lists visible through the
test service.
<P>
The biggest part of the partitioning is achieved while running the <A NAME="7687"></A><TT>./configure</TT>. Here is a sample call to <A NAME="7690"></A><TT>./configure</TT>
on the test server side :
<P><PRE>
./configure --prefix=/home/sympa-dev \
--with-confdir=/home/sympa-dev/etc \
--with-mandir=/home/sympa-dev/man \
--with-initdir=/home/sympa-dev/init \
--with-piddir=/home/sympa-dev/pid
--with-lockdir=/home/sympa-dev/lock \
--with-sendmail_aliases=/home/sympa-dev/etc/sympa_aliases
</PRE>
<P>
You can also customize more parameters via the <A NAME="7693"></A><TT>/home/sympa-dev/etc/sympa.conf</TT> file.
<P>
If you wish to share the same lists in both Sympa instances, then some parameters should have the same value :
<A NAME="7696"></A><TT>home</TT>, <A NAME="7699"></A><TT>db_name</TT>, <A NAME="7702"></A><TT>arc_path</TT>
<P>
<H1><A NAME="SECTION00660000000000000000"></A>
<A NAME="720"></A>
<BR>
5.6 Moving to another server
</H1>
<P>
If you're upgrading and moving to another server at the same time, we recommend you first to stop the operational service, move your data and
then upgrade Sympa on the new server. This will guarantee that Sympa upgrade procedures have been applied
on the data.
<P>
The migration process requires that you move the following data from the old server to the new one :
<UL>
<LI>the user database. If using mysql you can probably just stop <A NAME="7705"></A><TT>mysqld</TT> and copy the <A NAME="7708"></A><TT>/var/lib/mysql/sympa/</TT>
directory to the new server.
<P>
</LI>
<LI>the <A NAME="7711"></A><TT>/home/sympa/expl</TT> directory that contains list config
<P>
</LI>
<LI>the <A NAME="7714"></A> directory that contains the spools
<P>
</LI>
<LI>the <A NAME="7717"></A> directory and <A NAME="7720"></A><TT>/etc/sympa.conf</TT> and <A NAME="7723"></A><TT>wwsympa.conf</TT>. Sympa new installation create a file <A NAME="7726"></A><TT>/etc/sympa.conf</TT> (see <A HREF="node8.html#exp-admin">7</A>) and initialize randomly the cookie parameter. Changing this parameter will break all passwords. When upgrading Sympa on a new server take care that you start with the same value of this parameter, otherwise you will have troubles !
<P>
</LI>
<LI>the web archives
<P>
</LI>
</UL>
<P>
In some case, you may want to install the new version and run it for a few days before switching
the existing service to the new Sympa server. In this case perform a new installation with an empty
database and play with it. When you decide to move the existing service to the new server :
<OL>
<LI>stop all sympa processus on both servers,
</LI>
<LI>transfert the database
</LI>
<LI>edit the <A NAME="7729"></A><TT>/data_structure.version</TT> on the new server ; change the version value to reflect the old number
</LI>
<LI>start <A NAME="7732"></A><TT>sympa.pl</TT>, it will upgrade the database structure according the hop you do.
</LI>
</OL>
<P>
<HR>
<!--Navigation Panel-->
<A NAME="tex2html855"
HREF="node7.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html849"
HREF="sympa.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html843"
HREF="node5.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html851"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html853"
HREF="node30.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html856"
HREF="node7.html">6. Mail aliases</A>
<B> Up:</B> <A NAME="tex2html850"
HREF="sympa.html">Sympa Mailing Lists Management Software version</A>
<B> Previous:</B> <A NAME="tex2html844"
HREF="node5.html">4. Running Sympa</A>
<B> <A NAME="tex2html852"
HREF="node1.html">Contents</A></B>
<B> <A NAME="tex2html854"
HREF="node30.html">Index</A></B>
<!--End of Navigation Panel-->
<ADDRESS>
root
2006-10-20
</ADDRESS>
</BODY>
</HTML>
|
