grant all needed rights to fs_selfservice, #13199
[freeside.git] / rt / UPGRADING
1 UPGRADING
2
3 Detailed information about upgrading can be found in the README file.
4 This document is intended to supplement the instructions in that file.
5
6 Additional information about upgrading from specific versions of RT is
7 contained below.
8
9 *******
10 WARNING
11 *******
12
13 Before making any changes to your database, always ensure that you have a 
14 complete current backup. If you don't have a current backup, you could 
15 accidentally damage your database and lose data or worse.
16
17 If you are using MySQL, please read the instructions in UPGRADING.mysql as
18 well.
19
20 *******
21 UPGRADING FROM 3.8.8 and earlier - Changes:
22
23 Previous versions of RT used a password hashing scheme which was too
24 easy to reverse, which could allow attackers with read access to the
25 RT database to possibly compromise users' passwords.  Even if RT does
26 no password authentication itself, it may still store these weak
27 password hashes -- using ExternalAuth does not guarantee that you are
28 not vulnerable!  To upgrade stored passwords to a stronger hash, run:
29
30     perl etc/upgrade/vulnerable-passwords
31
32
33 We've proved that it's possible to delete set of records
34 from Transactions table without losing functionality. To delete
35 records run the following script:
36
37     perl -I /opt/rt3/local/lib -I /opt/rt3/lib etc/upgrade/shrink_transactions_table.pl
38
39 If you chose not to run the shrink_cgm_table.pl script when you upgraded to 3.8,
40 you should read more about it below and run it at this point.
41
42 UPGRADING FROM 3.8.7 and earlier - Changes:
43
44 RT's ChartFont option has been changed from a string to a hash which
45 lets you specify per-language fonts. RT now comes with a better default
46 font for charts, too.
47
48 You should either update your 'ChartFont' option to match the new format
49 or consider trying the new default
50
51 RT now gives you more precise control over the order in which custom fields
52 are displayed.  This change requires some small changes to your currently saved
53 custom field orders.
54
55 RT will automatically clean up your existing custom fields when you run:
56
57
58   /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade
59
60 After that cleanup, you should make sure that custom fields are ordered in
61 a way that you and your users find pleasing.
62
63 UPGRADING FROM 3.8.6 and earlier - Changes:
64
65 For MySQL and Oracle users:
66 If you upgraded from a version of RT earlier than 3.7.81 you should
67 already have a CachedGroupMembers3 index on your CachedGroupMembers table.
68 If you did a clean install of RT somewhere in the 3.8 release series, you 
69 most likely don't have this index.  You can add it manually with
70
71   CREATE INDEX CachedGroupMembers3 on CachedGroupMembers (MemberId, ImmediateParentId);
72
73 UPGRADING FROM 3.8.5 and earlier - Changes:
74
75 You can now forward an entire Ticket history (in addition to specific transactions)
76 but this requires a new Template called forward ticket.  This template will be added
77 when you run.
78
79 /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade
80
81 Custom fields with categories can optionally be split out into
82 hierarchical custom fields.  If you wish to convert your old
83 category-based custom fields, run:
84
85     perl etc/upgrade/split-out-cf-categories
86
87 It will prompt you for each custom field with categories that it
88 finds, and the name of the custom field to create to store the
89 categories.
90
91 If you were using the LocalizedDateTime RT::Date formatter from code
92 and passing a DateFormat or TimeFormat argument, you need to switch from 
93 the strftime methods to the cldr methods (ie full_date_format becomes date_format_full)
94 You may have done this from your RT_SiteConfig.pm by using
95 Set($DateTimeFormat, { Format => 'LocalizedDateTime', DateFormat => 'medium_date_format' );
96
97 UPGRADING FROM 3.8.3 and earlier - Changes:
98
99 Arguments to the NotifyGroup Scrip Action need
100 to be corrected in the database using 
101
102 /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade
103
104
105 UPGRADING FROM 3.8.2 and earlier - Changes:
106
107 New scrip condition 'On Reject'.
108
109 UPGRADING FROM 3.8.1 and earlier - Changes:
110
111 = Oracle configuration =
112
113 $DatabaseName is used as SID, so RT can connect without environment variables
114 or tnsnames.ora file. Because of this change your RT instance may loose ability
115 to connect to your DB, you have to update options and restart your web server.
116 Example configuration:
117
118     Set($DatabaseType, 'Oracle');
119     Set($DatabaseHost, '192.168.0.1');
120     # undefined port => will try both 1526 and 1521
121     Set($DatabasePort, undef);
122     # ORACLE SID
123     Set($DatabaseName, 'XE');
124     # user for RT in Oracle, RT's tables in his schema
125     Set($DatabaseUser, 'test');
126     # above user's password
127     Set($DatabasePassword, 'test');
128
129 = Rights changes =
130
131 Now, if you want any user to be able to access the Approvals tools (a.k.a.  the
132 Approvals tab), you must grant that user the "ShowApprovalsTab" right.
133
134 UPGRADING FROM 3.8.0 and earlier - Changes:
135
136 Searches for bookmarked tickets have been reimplemented and syntax has
137 been changed a little. Database upgrade script handles global 'Bookmarked Tickets'
138 search only. New Ticket SQL "id = '__Bookmarked__'" is more flexible than
139 old "__Bookmarks__". Old version is not valid Ticket SQL query, so people
140 can not use it in the query builder and as well admins couldn't not edit
141 format and other properties of the global saved search. Old version's been
142 left for backwards compatibility.
143
144
145 UPGRADING FROM 3.7.85 and earlier - Changes:
146
147 We've proved that it's possible to delete pretty big set of records
148 from CachedGroupMembers table without losing functionality. To delete
149 record run the following script.  If you don't run this, you may
150 occasionally see problems where RT miscounts users, particularly in the
151 chart functionality.
152
153     perl -I /opt/rt3/local/lib -I /opt/rt3/lib etc/upgrade/shrink_cgm_table.pl
154
155 After you run this, you'll have significantly reduced the number of
156 records in your CachedGroupMembers table and may need to tell your
157 database to refresh indexes/statistics.  Please consult your DBA for
158 specific instructions for your database.
159
160 UPGRADING FROM 3.7.81 and earlier - Changes:
161
162 RT::Extension::BrandedQueues has been integrated into core, so you MUST read
163 upgrading instructions docs/queue_subject_tag.pod EVEN IF you have not used
164 that extension.
165
166 RT::Action::LinearEscalate extension has been integrated into core,
167 so you MUST uninstall it before upgrading.
168
169 RT::Extension::iCal has been integrated into core, so you MUST uninstall
170 it before upgrading. In addition, you must run etc/upgrade/3.8-ical-extension
171 script to convert old data.
172
173 UPGRADING FROM 3.7.80 and earlier - Changes:
174
175 Added indexes to CachedGroupMembers for MySQL and Oracle.
176 If you have previously installed RTx-Shredder, you may already
177 have these indexes.  You can see the indexes by looking at
178 etc/upgrade/3.7.81/schema.*
179
180 These indexes may take a very long time to create.
181
182 UPGRADING FROM 3.6.X and earlier - Changes:
183
184 There are a lot of changes all over the code, so it's highly recommended to
185 use fresh directory and then reinstalling your customizations.
186
187 New schema for mysql 4.1 and greater, read more in UPGRADING.mysql.
188
189 Config format has been made stricter. All options MUST be set using Set
190 function, no more "@XXX = (...) unless @XXX;". Use "Set(@XXX, ...);" instead.
191
192 RTx::Shredder extension has been integrated into core and features have been
193 added, so you MUST uninstall it before upgrading or use a fresh directory for
194 installation.
195
196 New interface for making links in text clickable and doing other replacements
197 has been integrated into RT.
198 Read more in `perldoc docs/extending_clickable_links.pod`.
199
200 New feature that allow users to forward messages. There is a new option in
201 the config ($ForwardFromUser), new rights and a template.
202
203 New global templates with "Error: " prefix in the name to make it possible
204 to configure error messages sent to users.
205
206 Read about GnuPG integration in `perldoc docs/gnupg_integration.pod`.
207
208 New scrip conditions 'On Close' and 'On Reopen'.
209
210 UPGRADING FROM 3.5.7 and earlier - Changes:
211
212 Scrips are now prepared and committed in order alphanumerically by description.
213 This means that you can prepend a number (00, 07, 15, 24) to the beginning of
214 each scrip's description, and they will run in that order.  Depending on your
215 database, the old ordering may have been by scrip id number -- if that is the
216 case, simply prepend the scrip id number to the beginning of its description.
217
218
219 UPGRADING FROM 3.5.1 and earlier - Changes:
220
221 The default for $RedistributeAutoGeneratedMessages has changed to
222 'privileged', to make out-of-the-box installations more resistant
223 to mail loops. If you rely on the old default of redistributing to
224 all watchers, you'll need to set it explicitly now.
225
226
227 UPGRADING FROM 3.3.14 and earlier - Changes:
228
229 The "ModifyObjectCustomFieldValues" right name was too long. It's been changed to
230 "ModifyCustomField"
231
232
233 UPGRADING FROM 3.3.11 and earlier - Changes:
234
235 = Rights Changes =
236
237 Custom Fields now have an additional right "ModifyCustomField". 
238 This right governs whether a user can modify an object's custom field values
239 for a particular custom field. This includes adding, deleting and changing values.
240
241
242 UPGRADING FROM 3.2 and earlier - Changes:
243
244 = Rights changes =
245
246 Now, if you want any user to be able to access the Admin tools (a.k.a. 
247 the Configuration tab), you must grant that user the "ShowConfigTab" 
248 right.  Making the user a privileged user is no longer sufficient.
249
250 "SuperUser" users are no longer automatically added to the list of users who can own tickets in a queue. You now need to explicitly give them the "own tickets" right.
251
252
253
254 UPGRADING FROM 3.0.x - Changes:
255
256 = Installation =
257
258 We recommend you move your existing /opt/rt3 tree completely out
259 of the way before installing the new version of RT, to make sure
260 that you don't inadvertently leave old files hanging around.
261
262 = Rights changes =
263
264 Now, if you want RT to automatically create new users upon ticket
265 submission, you MUST grant 'Everyone' the right to create tickets.
266 Granting this right only to "Unprivileged Users" is now insufficient.
267
268
269 = FastCGI configuration =
270
271 This section is a snapshot of the documentation available at:
272
273 http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration
274
275 It's worth checking out that resource if these instructions don't 
276 work right for you
277
278
279 RT 3.2 includes a significant change to the FastCGI handler. It is
280 no longer "setgid" to the RT group.  Perl's setid support has been
281 deprecated for the last several releases and a number of platforms
282 don't bundle the "sperl" or "suidperl" executable by default.
283 Additionally, when perl is run SetUID or SetGID, the interpreter
284 is automatically switched into /taint mode/, in which all incoming
285 data, no matter the source is considered suspect. At first, this
286 seems like a great idea. But perl's taint mode is a big sledgehammer
287 used to hit small nails.  Many perl libraries aren't tested in taint
288 mode and will fail when least expected.  Moving away from a SetGID
289 FastCGI handler will enable more users to have a smoother RT
290 experience.  It does require some changes in how you set up and
291 configure RT.
292
293 Beginning with RT 3.2, you have several choices about how to configure
294 RT to run as a FastCGI:
295
296
297 == Install RT as the user your webserver runs as ==
298
299 Pros: Very easy to configure
300
301 Cons: Your webserver has access to RT's private database password
302  
303
304 === How To
305
306 When installing RT, run:
307
308  ./configure --with-web-user="webuser"  --with-web-group="webgroup"  \ 
309     --with-rt-user="webuser" --with-rt-group="webgroup"
310
311 (Don't forget to include other configuration options that matter to you)
312
313 If you're using apache, you'll want to add something like the following 
314 to your httpd.conf:
315
316  <VirtualHost rt.example.com>
317
318     # Pass through requests to display images
319     Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
320     
321     # Tell FastCGI to put its temporary files somewhere sane.
322     FastCgiIpcDir /tmp
323
324     FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120
325
326     AddHandler fastcgi-script fcgi
327     ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
328     
329  </VirtualHost>
330
331
332 == Make your webserver user a member of the "rt" group ==
333
334 Pros: Easy to configure
335
336 Cons: Your webserver has access to RT's private database password
337
338
339 === How To
340
341 Install RT normally. Add whichever user your webserver runs as
342 (whatever you set --with-web-user to) to the "rt" group (whatever
343 you set --with-rt-group to) in /etc/groups.
344
345 To find out what user your webserver runs as, look for the line
346
347   User some-user-name
348
349 in your apache httpd.conf. Common values are www, www-data, web and nobody.
350
351
352
353 == Run RT using _suexec_ or a similar mechanism
354
355
356 Pros: More secure
357
358 Cons: Sometimes very difficult to configure
359
360 Apache's _suexec_ utility allows you run CGI programs as specific
361 users. Because that's a relatively heavy responsibility, it's very,
362 very conservative about what it's willing to do for you. On top of
363 that, Apache's mod_fastcgi plugin doesn't respect all of suexec's
364 features.  While suexec is designed to execute CGI scripts in a
365 given virtual host's !DocumentRoot, It can only execute FastCGI
366 scripts in the system's *main* !DocumentRoot.
367
368 This means you have to copy the RT FastCGI handler into your main
369 !DocumentRoot
370
371 The following example !VirtualHost will run RT as a FastCGI on
372 Apache 1.3 on a Debian Linux server.
373
374
375  <VirtualHost rt.example.com>
376  
377    DocumentRoot /opt/rt3/share/html
378  
379     # Set the rt user and group as the executing user for this virtual host
380     User rt
381     Group rt
382
383
384     # Pass through requests to display images
385     Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
386     
387     # Tell FastCGI to put its temporary files somewhere sane.
388     FastCgiIpcDir /tmp
389
390     # Tell FastCGI that it should use apache's "suexec" binary to call any 
391     # FastCGI script.
392     # This is a GLOBAL setting
393     FastCgiWrapper /usr/lib/apache/suexec
394
395     # You need to copy the rt mason_handler.fcgi into a directory inside 
396     # the main server DocumentRoot
397     # That directory must be owned by the user and group that will execute 
398     # the FastCGI script
399     # In this case, that directory is /var/www/rt
400
401     # To find the local DocumentRoot, run "suexec -V" as root and look for the 
402     #  -D DOC_ROOT parameter.
403
404     # Apache 1.3 discards the user and group parameters on the FastCgiServer 
405     # line. Apache 2.0 requires them.
406
407     FastCgiServer /var/www/rt/mason_handler.fcgi -idle-timeout 120 -user rt -group rt
408
409     AddHandler fastcgi-script fcgi
410     ScriptAlias / /var/www/rt/mason_handler.fcgi/
411     
412  </VirtualHost>
413
414 UPGRADING FROM 2.x:
415
416 See http://search.cpan.org/dist/RT-Extension-RT2toRT3/
417