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.7 and earlier - Changes:
23 RT's ChartFont option has been changed from a string to a hash which
24 lets you specify per-language fonts. RT now comes with a better default
27 You should either update your 'ChartFont' option to match the new format
28 or consider trying the new default
30 RT now gives you more precise control over the order in which custom fields
31 are displayed. This change requires some small changes to your currently saved
34 RT will automatically clean up your existing custom fields when you run:
37 /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade
39 After that cleanup, you should make sure that custom fields are ordered in
40 a way that you and your users find pleasing.
42 UPGRADING FROM 3.8.6 and earlier - Changes:
44 For MySQL and Oracle users:
45 If you upgraded from a version of RT earlier than 3.7.81 you should
46 already have a CachedGroupMembers3 index on your CachedGroupMembers table.
47 If you did a clean install of RT somewhere in the 3.8 release series, you
48 most likely don't have this index. You can add it manually with
50 CREATE INDEX CachedGroupMembers3 on CachedGroupMembers (MemberId, ImmediateParentId);
52 UPGRADING FROM 3.8.5 and earlier - Changes:
54 You can now forward an entire Ticket history (in addition to specific transactions)
55 but this requires a new Template called forward ticket. This template will be added
58 /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade
60 Custom fields with categories can optionally be split out into
61 hierarchical custom fields. If you wish to convert your old
62 category-based custom fields, run:
64 perl etc/upgrade/split-out-cf-categories
66 It will prompt you for each custom field with categories that it
67 finds, and the name of the custom field to create to store the
70 If you were using the LocalizedDateTime RT::Date formatter from code
71 and passing a DateFormat or TimeFormat argument, you need to switch from
72 the strftime methods to the cldr methods (ie full_date_format becomes date_format_full)
73 You may have done this from your RT_SiteConfig.pm by using
74 Set($DateTimeFormat, { Format => 'LocalizedDateTime', DateFormat => 'medium_date_format' );
76 UPGRADING FROM 3.8.3 and earlier - Changes:
78 Arguments to the NotifyGroup Scrip Action need
79 to be corrected in the database using
81 /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade
84 UPGRADING FROM 3.8.2 and earlier - Changes:
86 New scrip condition 'On Reject'.
88 UPGRADING FROM 3.8.1 and earlier - Changes:
90 = Oracle configuration =
92 $DatabaseName is used as SID, so RT can connect without environment variables
93 or tnsnames.ora file. Because of this change your RT instance may loose ability
94 to connect to your DB, you have to update options and restart your web server.
95 Example configuration:
97 Set($DatabaseType, 'Oracle');
98 Set($DatabaseHost, '192.168.0.1');
99 # undefined port => will try both 1526 and 1521
100 Set($DatabasePort, undef);
102 Set($DatabaseName, 'XE');
103 # user for RT in Oracle, RT's tables in his schema
104 Set($DatabaseUser, 'test');
105 # above user's password
106 Set($DatabasePassword, 'test');
110 Now, if you want any user to be able to access the Approvals tools (a.k.a. the
111 Approvals tab), you must grant that user the "ShowApprovalsTab" right.
113 UPGRADING FROM 3.8.0 and earlier - Changes:
115 Searches for bookmarked tickets have been reimplemented and syntax has
116 been changed a little. Database upgrade script handles global 'Bookmarked Tickets'
117 search only. New Ticket SQL "id = '__Bookmarked__'" is more flexible than
118 old "__Bookmarks__". Old version is not valid Ticket SQL query, so people
119 can not use it in the query builder and as well admins couldn't not edit
120 format and other properties of the global saved search. Old version's been
121 left for backwards compatibility.
124 UPGRADING FROM 3.7.85 and earlier - Changes:
126 We've proved that it's possible to delete pretty big set of records
127 from CachedGroupMembers table without losing functionality. To delete
128 record run the following script:
130 perl -I /opt/rt3/local/lib -I /opt/rt3/lib etc/upgrade/shrink_cgm_table.pl
132 UPGRADING FROM 3.7.81 and earlier - Changes:
134 RT::Extension::BrandedQueues has been integrated into core, so you MUST read
135 upgrading instructions docs/queue_subject_tag.pod EVEN IF you have not used
138 RT::Action::LinearEscalate extension has been integrated into core,
139 so you MUST uninstall it before upgrading.
141 RT::Extension::iCal has been integrated into core, so you MUST uninstall
142 it before upgrading. In addition, you must run etc/upgrade/3.8-ical-extension
143 script to convert old data.
145 UPGRADING FROM 3.7.80 and earlier - Changes:
147 Added indexes to CachedGroupMembers for MySQL and Oracle.
148 If you have previously installed RTx-Shredder, you may already
149 have these indexes. You can see the indexes by looking at
150 etc/upgrade/3.7.81/schema.*
152 These indexes may take a very long time to create.
154 UPGRADING FROM 3.6.X and earlier - Changes:
156 There are a lot of changes all over the code, so it's highly recommended to
157 use fresh directory and then reinstalling your customizations.
159 New schema for mysql 4.1 and greater, read more in UPGRADING.mysql.
161 Config format has been made stricter. All options MUST be set using Set
162 function, no more "@XXX = (...) unless @XXX;". Use "Set(@XXX, ...);" instead.
164 RTx::Shredder extension has been integrated into core and features have been
165 added, so you MUST uninstall it before upgrading or use a fresh directory for
168 New interface for making links in text clickable and doing other replacements
169 has been integrated into RT.
170 Read more in `perldoc docs/extending_clickable_links.pod`.
172 New feature that allow users to forward messages. There is a new option in
173 the config ($ForwardFromUser), new rights and a template.
175 New global templates with "Error: " prefix in the name to make it possible
176 to configure error messages sent to users.
178 Read about GnuPG integration in `perldoc docs/gnupg_integration.pod`.
180 New scrip conditions 'On Close' and 'On Reopen'.
182 UPGRADING FROM 3.5.7 and earlier - Changes:
184 Scrips are now prepared and committed in order alphanumerically by description.
185 This means that you can prepend a number (00, 07, 15, 24) to the beginning of
186 each scrip's description, and they will run in that order. Depending on your
187 database, the old ordering may have been by scrip id number -- if that is the
188 case, simply prepend the scrip id number to the beginning of its description.
191 UPGRADING FROM 3.5.1 and earlier - Changes:
193 The default for $RedistributeAutoGeneratedMessages has changed to
194 'privileged', to make out-of-the-box installations more resistant
195 to mail loops. If you rely on the old default of redistributing to
196 all watchers, you'll need to set it explicitly now.
199 UPGRADING FROM 3.3.14 and earlier - Changes:
201 The "ModifyObjectCustomFieldValues" right name was too long. It's been changed to
205 UPGRADING FROM 3.3.11 and earlier - Changes:
209 Custom Fields now have an additional right "ModifyCustomField".
210 This right governs whether a user can modify an object's custom field values
211 for a particular custom field. This includes adding, deleting and changing values.
214 UPGRADING FROM 3.2 and earlier - Changes:
218 Now, if you want any user to be able to access the Admin tools (a.k.a.
219 the Configuration tab), you must grant that user the "ShowConfigTab"
220 right. Making the user a privileged user is no longer sufficient.
222 "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.
226 UPGRADING FROM 3.0.x - Changes:
230 We recommend you move your existing /opt/rt3 tree completely out
231 of the way before installing the new version of RT, to make sure
232 that you don't inadvertently leave old files hanging around.
236 Now, if you want RT to automatically create new users upon ticket
237 submission, you MUST grant 'Everyone' the right to create tickets.
238 Granting this right only to "Unprivileged Users" is now insufficient.
241 = FastCGI configuration =
243 This section is a snapshot of the documentation available at:
245 http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration
247 It's worth checking out that resource if these instructions don't
251 RT 3.2 includes a significant change to the FastCGI handler. It is
252 no longer "setgid" to the RT group. Perl's setid support has been
253 deprecated for the last several releases and a number of platforms
254 don't bundle the "sperl" or "suidperl" executable by default.
255 Additionally, when perl is run SetUID or SetGID, the interpreter
256 is automatically switched into /taint mode/, in which all incoming
257 data, no matter the source is considered suspect. At first, this
258 seems like a great idea. But perl's taint mode is a big sledgehammer
259 used to hit small nails. Many perl libraries aren't tested in taint
260 mode and will fail when least expected. Moving away from a SetGID
261 FastCGI handler will enable more users to have a smoother RT
262 experience. It does require some changes in how you set up and
265 Beginning with RT 3.2, you have several choices about how to configure
266 RT to run as a FastCGI:
269 == Install RT as the user your webserver runs as ==
271 Pros: Very easy to configure
273 Cons: Your webserver has access to RT's private database password
278 When installing RT, run:
280 ./configure --with-web-user="webuser" --with-web-group="webgroup" \
281 --with-rt-user="webuser" --with-rt-group="webgroup"
283 (Don't forget to include other configuration options that matter to you)
285 If you're using apache, you'll want to add something like the following
288 <VirtualHost rt.example.com>
290 # Pass through requests to display images
291 Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
293 # Tell FastCGI to put its temporary files somewhere sane.
296 FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120
298 AddHandler fastcgi-script fcgi
299 ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
304 == Make your webserver user a member of the "rt" group ==
306 Pros: Easy to configure
308 Cons: Your webserver has access to RT's private database password
313 Install RT normally. Add whichever user your webserver runs as
314 (whatever you set --with-web-user to) to the "rt" group (whatever
315 you set --with-rt-group to) in /etc/groups.
317 To find out what user your webserver runs as, look for the line
321 in your apache httpd.conf. Common values are www, www-data, web and nobody.
325 == Run RT using _suexec_ or a similar mechanism
330 Cons: Sometimes very difficult to configure
332 Apache's _suexec_ utility allows you run CGI programs as specific
333 users. Because that's a relatively heavy responsibility, it's very,
334 very conservative about what it's willing to do for you. On top of
335 that, Apache's mod_fastcgi plugin doesn't respect all of suexec's
336 features. While suexec is designed to execute CGI scripts in a
337 given virtual host's !DocumentRoot, It can only execute FastCGI
338 scripts in the system's *main* !DocumentRoot.
340 This means you have to copy the RT FastCGI handler into your main
343 The following example !VirtualHost will run RT as a FastCGI on
344 Apache 1.3 on a Debian Linux server.
347 <VirtualHost rt.example.com>
349 DocumentRoot /opt/rt3/share/html
351 # Set the rt user and group as the executing user for this virtual host
356 # Pass through requests to display images
357 Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
359 # Tell FastCGI to put its temporary files somewhere sane.
362 # Tell FastCGI that it should use apache's "suexec" binary to call any
364 # This is a GLOBAL setting
365 FastCgiWrapper /usr/lib/apache/suexec
367 # You need to copy the rt mason_handler.fcgi into a directory inside
368 # the main server DocumentRoot
369 # That directory must be owned by the user and group that will execute
371 # In this case, that directory is /var/www/rt
373 # To find the local DocumentRoot, run "suexec -V" as root and look for the
374 # -D DOC_ROOT parameter.
376 # Apache 1.3 discards the user and group parameters on the FastCgiServer
377 # line. Apache 2.0 requires them.
379 FastCgiServer /var/www/rt/mason_handler.fcgi -idle-timeout 120 -user rt -group rt
381 AddHandler fastcgi-script fcgi
382 ScriptAlias / /var/www/rt/mason_handler.fcgi/
388 See http://search.cpan.org/dist/RT-Extension-RT2toRT3/