3 Detailed information about upgrading can be found in the README file.
4 This document is intended to supplement the instructions in that file.
6 Additional information about upgrading from specific versions of RT is
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.
17 If you are using MySQL, please read the instructions in UPGRADING.mysql as
21 UPGRADING FROM 3.8.6 and earlier - Changes:
23 For MySQL and Oracle users:
24 If you upgraded from a version of RT earlier than 3.7.81 you should
25 already have a CachedGroupMembers3 index on your CachedGroupMembers table.
26 If you did a clean install of RT somewhere in the 3.8 release series, you
27 most likely don't have this index. You can add it manually with
29 CREATE INDEX CachedGroupMembers3 on CachedGroupMembers (MemberId, ImmediateParentId);
31 UPGRADING FROM 3.8.5 and earlier - Changes:
33 You can now forward an entire Ticket history (in addition to specific transactions)
34 but this requires a new Template called forward ticket. This template will be added
37 /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade
39 Custom fields with categories can optionally be split out into
40 hierarchical custom fields. If you wish to convert your old
41 category-based custom fields, run:
43 perl etc/upgrade/split-out-cf-categories
45 It will prompt you for each custom field with categories that it
46 finds, and the name of the custom field to create to store the
49 If you were using the LocalizedDateTime RT::Date formatter from code
50 and passing a DateFormat or TimeFormat argument, you need to switch from
51 the strftime methods to the cldr methods (ie full_date_format becomes date_format_full)
52 You may have done this from your RT_SiteConfig.pm by using
53 Set($DateTimeFormat, { Format => 'LocalizedDateTime', DateFormat => 'medium_date_format' );
55 UPGRADING FROM 3.8.3 and earlier - Changes:
57 Arguments to the NotifyGroup Scrip Action need
58 to be corrected in the database using
60 /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade
63 UPGRADING FROM 3.8.2 and earlier - Changes:
65 New scrip condition 'On Reject'.
67 UPGRADING FROM 3.8.1 and earlier - Changes:
69 = Oracle configuration =
71 $DatabaseName is used as SID, so RT can connect without environment variables
72 or tnsnames.ora file. Because of this change your RT instance may loose ability
73 to connect to your DB, you have to update options and restart your web server.
74 Example configuration:
76 Set($DatabaseType, 'Oracle');
77 Set($DatabaseHost, '192.168.0.1');
78 # undefined port => will try both 1526 and 1521
79 Set($DatabasePort, undef);
81 Set($DatabaseName, 'XE');
82 # user for RT in Oracle, RT's tables in his schema
83 Set($DatabaseUser, 'test');
84 # above user's password
85 Set($DatabasePassword, 'test');
89 Now, if you want any user to be able to access the Approvals tools (a.k.a. the
90 Approvals tab), you must grant that user the "ShowApprovalsTab" right.
92 UPGRADING FROM 3.8.0 and earlier - Changes:
94 Searches for bookmarked tickets have been reimplemented and syntax has
95 been changed a little. Database upgrade script handles global 'Bookmarked Tickets'
96 search only. New Ticket SQL "id = '__Bookmarked__'" is more flexible than
97 old "__Bookmarks__". Old version is not valid Ticket SQL query, so people
98 can not use it in the query builder and as well admins couldn't not edit
99 format and other properties of the global saved search. Old version's been
100 left for backwards compatibility.
103 UPGRADING FROM 3.7.85 and earlier - Changes:
105 We've proved that it's possible to delete pretty big set of records
106 from CachedGroupMembers table without losing functionality. To delete
107 record run the following script:
109 perl -I /opt/rt3/local/lib -I /opt/rt3/lib etc/upgrade/shrink_cgm_table.pl
111 UPGRADING FROM 3.7.81 and earlier - Changes:
113 RT::Extension::BrandedQueues has been integrated into core, so you MUST read
114 upgrading instructions docs/queue_subject_tag.pod EVEN IF you have not used
117 RT::Action::LinearEscalate extension has been integrated into core,
118 so you MUST uninstall it before upgrading.
120 RT::Extension::iCal has been integrated into core, so you MUST uninstall
121 it before upgrading. In addition, you must run etc/upgrade/3.8-ical-extension
122 script to convert old data.
124 UPGRADING FROM 3.7.80 and earlier - Changes:
126 Added indexes to CachedGroupMembers for MySQL and Oracle.
127 If you have previously installed RTx-Shredder, you may already
128 have these indexes. You can see the indexes by looking at
129 etc/upgrade/3.7.81/schema.*
131 These indexes may take a very long time to create.
133 UPGRADING FROM 3.6.X and earlier - Changes:
135 There are a lot of changes all over the code, so it's highly recommended to
136 use fresh directory and then reinstalling your customizations.
138 New schema for mysql 4.1 and greater, read more in UPGRADING.mysql.
140 Config format has been made stricter. All options MUST be set using Set
141 function, no more "@XXX = (...) unless @XXX;". Use "Set(@XXX, ...);" instead.
143 RTx::Shredder extension has been integrated into core and features have been
144 added, so you MUST uninstall it before upgrading or use a fresh directory for
147 New interface for making links in text clickable and doing other replacements
148 has been integrated into RT.
149 Read more in `perldoc docs/extending_clickable_links.pod`.
151 New feature that allow users to forward messages. There is a new option in
152 the config ($ForwardFromUser), new rights and a template.
154 New global templates with "Error: " prefix in the name to make it possible
155 to configure error messages sent to users.
157 Read about GnuPG integration in `perldoc docs/gnupg_integration.pod`.
159 New scrip conditions 'On Close' and 'On Reopen'.
161 UPGRADING FROM 3.5.7 and earlier - Changes:
163 Scrips are now prepared and committed in order alphanumerically by description.
164 This means that you can prepend a number (00, 07, 15, 24) to the beginning of
165 each scrip's description, and they will run in that order. Depending on your
166 database, the old ordering may have been by scrip id number -- if that is the
167 case, simply prepend the scrip id number to the beginning of its description.
170 UPGRADING FROM 3.5.1 and earlier - Changes:
172 The default for $RedistributeAutoGeneratedMessages has changed to
173 'privileged', to make out-of-the-box installations more resistant
174 to mail loops. If you rely on the old default of redistributing to
175 all watchers, you'll need to set it explicitly now.
178 UPGRADING FROM 3.3.14 and earlier - Changes:
180 The "ModifyObjectCustomFieldValues" right name was too long. It's been changed to
184 UPGRADING FROM 3.3.11 and earlier - Changes:
188 Custom Fields now have an additional right "ModifyCustomField".
189 This right governs whether a user can modify an object's custom field values
190 for a particular custom field. This includes adding, deleting and changing values.
193 UPGRADING FROM 3.2 and earlier - Changes:
197 Now, if you want any user to be able to access the Admin tools (a.k.a.
198 the Configuration tab), you must grant that user the "ShowConfigTab"
199 right. Making the user a privileged user is no longer sufficient.
201 "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.
205 UPGRADING FROM 3.0.x - Changes:
209 We recommend you move your existing /opt/rt3 tree completely out
210 of the way before installing the new version of RT, to make sure
211 that you don't inadvertently leave old files hanging around.
215 Now, if you want RT to automatically create new users upon ticket
216 submission, you MUST grant 'Everyone' the right to create tickets.
217 Granting this right only to "Unprivileged Users" is now insufficient.
220 = FastCGI configuration =
222 This section is a snapshot of the documentation available at:
224 http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration
226 It's worth checking out that resource if these instructions don't
230 RT 3.2 includes a significant change to the FastCGI handler. It is
231 no longer "setgid" to the RT group. Perl's setid support has been
232 deprecated for the last several releases and a number of platforms
233 don't bundle the "sperl" or "suidperl" executable by default.
234 Additionally, when perl is run SetUID or SetGID, the interpreter
235 is automatically switched into /taint mode/, in which all incoming
236 data, no matter the source is considered suspect. At first, this
237 seems like a great idea. But perl's taint mode is a big sledgehammer
238 used to hit small nails. Many perl libraries aren't tested in taint
239 mode and will fail when least expected. Moving away from a SetGID
240 FastCGI handler will enable more users to have a smoother RT
241 experience. It does require some changes in how you set up and
244 Beginning with RT 3.2, you have several choices about how to configure
245 RT to run as a FastCGI:
248 == Install RT as the user your webserver runs as ==
250 Pros: Very easy to configure
252 Cons: Your webserver has access to RT's private database password
257 When installing RT, run:
259 ./configure --with-web-user="webuser" --with-web-group="webgroup" \
260 --with-rt-user="webuser" --with-rt-group="webgroup"
262 (Don't forget to include other configuration options that matter to you)
264 If you're using apache, you'll want to add something like the following
267 <VirtualHost rt.example.com>
269 # Pass through requests to display images
270 Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
272 # Tell FastCGI to put its temporary files somewhere sane.
275 FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120
277 AddHandler fastcgi-script fcgi
278 ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
283 == Make your webserver user a member of the "rt" group ==
285 Pros: Easy to configure
287 Cons: Your webserver has access to RT's private database password
292 Install RT normally. Add whichever user your webserver runs as
293 (whatever you set --with-web-user to) to the "rt" group (whatever
294 you set --with-rt-group to) in /etc/groups.
296 To find out what user your webserver runs as, look for the line
300 in your apache httpd.conf. Common values are www, www-data, web and nobody.
304 == Run RT using _suexec_ or a similar mechanism
309 Cons: Sometimes very difficult to configure
311 Apache's _suexec_ utility allows you run CGI programs as specific
312 users. Because that's a relatively heavy responsibility, it's very,
313 very conservative about what it's willing to do for you. On top of
314 that, Apache's mod_fastcgi plugin doesn't respect all of suexec's
315 features. While suexec is designed to execute CGI scripts in a
316 given virtual host's !DocumentRoot, It can only execute FastCGI
317 scripts in the system's *main* !DocumentRoot.
319 This means you have to copy the RT FastCGI handler into your main
322 The following example !VirtualHost will run RT as a FastCGI on
323 Apache 1.3 on a Debian Linux server.
326 <VirtualHost rt.example.com>
328 DocumentRoot /opt/rt3/share/html
330 # Set the rt user and group as the executing user for this virtual host
335 # Pass through requests to display images
336 Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
338 # Tell FastCGI to put its temporary files somewhere sane.
341 # Tell FastCGI that it should use apache's "suexec" binary to call any
343 # This is a GLOBAL setting
344 FastCgiWrapper /usr/lib/apache/suexec
346 # You need to copy the rt mason_handler.fcgi into a directory inside
347 # the main server DocumentRoot
348 # That directory must be owned by the user and group that will execute
350 # In this case, that directory is /var/www/rt
352 # To find the local DocumentRoot, run "suexec -V" as root and look for the
353 # -D DOC_ROOT parameter.
355 # Apache 1.3 discards the user and group parameters on the FastCgiServer
356 # line. Apache 2.0 requires them.
358 FastCgiServer /var/www/rt/mason_handler.fcgi -idle-timeout 120 -user rt -group rt
360 AddHandler fastcgi-script fcgi
361 ScriptAlias / /var/www/rt/mason_handler.fcgi/
367 See http://search.cpan.org/dist/RT-Extension-RT2toRT3/