UPGRADING

Detailed information about upgrading can be found in the README file.
This document is intended to supplement the instructions in that file.

Additional information about upgrading from specific versions of RT is
contained below.

*******
WARNING
*******

Before making any changes to your database, always ensure that you have a 
complete current backup. If you don't have a current backup, you could 
accidentally damage your database and lose data or worse.

If you are using MySQL, please read the instructions in UPGRADING.mysql as
well.

*******
UPGRADING FROM 3.8.8 and earlier - Changes:

Previous versions of RT used a password hashing scheme which was too
easy to reverse, which could allow attackers with read access to the
RT database to possibly compromise users' passwords.  Even if RT does
no password authentication itself, it may still store these weak
password hashes -- using ExternalAuth does not guarantee that you are
not vulnerable!  To upgrade stored passwords to a stronger hash, run:

    perl etc/upgrade/vulnerable-passwords


We've proved that it's possible to delete set of records
from Transactions table without losing functionality. To delete
records run the following script:

    perl -I /opt/rt3/local/lib -I /opt/rt3/lib etc/upgrade/shrink_transactions_table.pl

If you chose not to run the shrink_cgm_table.pl script when you upgraded to 3.8,
you should read more about it below and run it at this point.

UPGRADING FROM 3.8.7 and earlier - Changes:

RT's ChartFont option has been changed from a string to a hash which
lets you specify per-language fonts. RT now comes with a better default
font for charts, too.

You should either update your 'ChartFont' option to match the new format
or consider trying the new default

RT now gives you more precise control over the order in which custom fields
are displayed.  This change requires some small changes to your currently saved
custom field orders.

RT will automatically clean up your existing custom fields when you run:


  /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade

After that cleanup, you should make sure that custom fields are ordered in
a way that you and your users find pleasing.

UPGRADING FROM 3.8.6 and earlier - Changes:

For MySQL and Oracle users:
If you upgraded from a version of RT earlier than 3.7.81 you should
already have a CachedGroupMembers3 index on your CachedGroupMembers table.
If you did a clean install of RT somewhere in the 3.8 release series, you 
most likely don't have this index.  You can add it manually with

  CREATE INDEX CachedGroupMembers3 on CachedGroupMembers (MemberId, ImmediateParentId);

UPGRADING FROM 3.8.5 and earlier - Changes:

You can now forward an entire Ticket history (in addition to specific transactions)
but this requires a new Template called forward ticket.  This template will be added
when you run.

/opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade

Custom fields with categories can optionally be split out into
hierarchical custom fields.  If you wish to convert your old
category-based custom fields, run:

    perl etc/upgrade/split-out-cf-categories

It will prompt you for each custom field with categories that it
finds, and the name of the custom field to create to store the
categories.

If you were using the LocalizedDateTime RT::Date formatter from code
and passing a DateFormat or TimeFormat argument, you need to switch from 
the strftime methods to the cldr methods (ie full_date_format becomes date_format_full)
You may have done this from your RT_SiteConfig.pm by using
Set($DateTimeFormat, { Format => 'LocalizedDateTime', DateFormat => 'medium_date_format' );

UPGRADING FROM 3.8.3 and earlier - Changes:

Arguments to the NotifyGroup Scrip Action need
to be corrected in the database using 

/opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade


UPGRADING FROM 3.8.2 and earlier - Changes:

New scrip condition 'On Reject'.

UPGRADING FROM 3.8.1 and earlier - Changes:

= Oracle configuration =

$DatabaseName is used as SID, so RT can connect without environment variables
or tnsnames.ora file. Because of this change your RT instance may loose ability
to connect to your DB, you have to update options and restart your web server.
Example configuration:

    Set($DatabaseType, 'Oracle');
    Set($DatabaseHost, '192.168.0.1');
    # undefined port => will try both 1526 and 1521
    Set($DatabasePort, undef);
    # ORACLE SID
    Set($DatabaseName, 'XE');
    # user for RT in Oracle, RT's tables in his schema
    Set($DatabaseUser, 'test');
    # above user's password
    Set($DatabasePassword, 'test');

= Rights changes =

Now, if you want any user to be able to access the Approvals tools (a.k.a.  the
Approvals tab), you must grant that user the "ShowApprovalsTab" right.

UPGRADING FROM 3.8.0 and earlier - Changes:

Searches for bookmarked tickets have been reimplemented and syntax has
been changed a little. Database upgrade script handles global 'Bookmarked Tickets'
search only. New Ticket SQL "id = '__Bookmarked__'" is more flexible than
old "__Bookmarks__". Old version is not valid Ticket SQL query, so people
can not use it in the query builder and as well admins couldn't not edit
format and other properties of the global saved search. Old version's been
left for backwards compatibility.


UPGRADING FROM 3.7.85 and earlier - Changes:

We've proved that it's possible to delete pretty big set of records
from CachedGroupMembers table without losing functionality. To delete
record run the following script.  If you don't run this, you may
occasionally see problems where RT miscounts users, particularly in the
chart functionality.

    perl -I /opt/rt3/local/lib -I /opt/rt3/lib etc/upgrade/shrink_cgm_table.pl

After you run this, you'll have significantly reduced the number of
records in your CachedGroupMembers table and may need to tell your
database to refresh indexes/statistics.  Please consult your DBA for
specific instructions for your database.

UPGRADING FROM 3.7.81 and earlier - Changes:

RT::Extension::BrandedQueues has been integrated into core, so you MUST read
upgrading instructions docs/queue_subject_tag.pod EVEN IF you have not used
that extension.

RT::Action::LinearEscalate extension has been integrated into core,
so you MUST uninstall it before upgrading.

RT::Extension::iCal has been integrated into core, so you MUST uninstall
it before upgrading. In addition, you must run etc/upgrade/3.8-ical-extension
script to convert old data.

UPGRADING FROM 3.7.80 and earlier - Changes:

Added indexes to CachedGroupMembers for MySQL and Oracle.
If you have previously installed RTx-Shredder, you may already
have these indexes.  You can see the indexes by looking at
etc/upgrade/3.7.81/schema.*

These indexes may take a very long time to create.

UPGRADING FROM 3.6.X and earlier - Changes:

There are a lot of changes all over the code, so it's highly recommended to
use fresh directory and then reinstalling your customizations.

New schema for mysql 4.1 and greater, read more in UPGRADING.mysql.

Config format has been made stricter. All options MUST be set using Set
function, no more "@XXX = (...) unless @XXX;". Use "Set(@XXX, ...);" instead.

RTx::Shredder extension has been integrated into core and features have been
added, so you MUST uninstall it before upgrading or use a fresh directory for
installation.

New interface for making links in text clickable and doing other replacements
has been integrated into RT.
Read more in `perldoc docs/extending_clickable_links.pod`.

New feature that allow users to forward messages. There is a new option in
the config ($ForwardFromUser), new rights and a template.

New global templates with "Error: " prefix in the name to make it possible
to configure error messages sent to users.

Read about GnuPG integration in `perldoc docs/gnupg_integration.pod`.

New scrip conditions 'On Close' and 'On Reopen'.

UPGRADING FROM 3.5.7 and earlier - Changes:

Scrips are now prepared and committed in order alphanumerically by description.
This means that you can prepend a number (00, 07, 15, 24) to the beginning of
each scrip's description, and they will run in that order.  Depending on your
database, the old ordering may have been by scrip id number -- if that is the
case, simply prepend the scrip id number to the beginning of its description.


UPGRADING FROM 3.5.1 and earlier - Changes:

The default for $RedistributeAutoGeneratedMessages has changed to
'privileged', to make out-of-the-box installations more resistant
to mail loops. If you rely on the old default of redistributing to
all watchers, you'll need to set it explicitly now.


UPGRADING FROM 3.3.14 and earlier - Changes:

The "ModifyObjectCustomFieldValues" right name was too long. It's been changed to
"ModifyCustomField"


UPGRADING FROM 3.3.11 and earlier - Changes:

= Rights Changes =

Custom Fields now have an additional right "ModifyCustomField". 
This right governs whether a user can modify an object's custom field values
for a particular custom field. This includes adding, deleting and changing values.


UPGRADING FROM 3.2 and earlier - Changes:

= Rights changes =

Now, if you want any user to be able to access the Admin tools (a.k.a. 
the Configuration tab), you must grant that user the "ShowConfigTab" 
right.  Making the user a privileged user is no longer sufficient.

"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.



UPGRADING FROM 3.0.x - Changes:

= Installation =

We recommend you move your existing /opt/rt3 tree completely out
of the way before installing the new version of RT, to make sure
that you don't inadvertently leave old files hanging around.

= Rights changes =

Now, if you want RT to automatically create new users upon ticket
submission, you MUST grant 'Everyone' the right to create tickets.
Granting this right only to "Unprivileged Users" is now insufficient.


= FastCGI configuration =

This section is a snapshot of the documentation available at:

http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration

It's worth checking out that resource if these instructions don't 
work right for you


RT 3.2 includes a significant change to the FastCGI handler. It is
no longer "setgid" to the RT group.  Perl's setid support has been
deprecated for the last several releases and a number of platforms
don't bundle the "sperl" or "suidperl" executable by default.
Additionally, when perl is run SetUID or SetGID, the interpreter
is automatically switched into /taint mode/, in which all incoming
data, no matter the source is considered suspect. At first, this
seems like a great idea. But perl's taint mode is a big sledgehammer
used to hit small nails.  Many perl libraries aren't tested in taint
mode and will fail when least expected.  Moving away from a SetGID
FastCGI handler will enable more users to have a smoother RT
experience.  It does require some changes in how you set up and
configure RT.

Beginning with RT 3.2, you have several choices about how to configure
RT to run as a FastCGI:


== Install RT as the user your webserver runs as ==

Pros: Very easy to configure

Cons: Your webserver has access to RT's private database password
 

=== How To

When installing RT, run:

 ./configure --with-web-user="webuser"  --with-web-group="webgroup"  \ 
    --with-rt-user="webuser" --with-rt-group="webgroup"

(Don't forget to include other configuration options that matter to you)

If you're using apache, you'll want to add something like the following 
to your httpd.conf:

 <VirtualHost rt.example.com>

    # Pass through requests to display images
    Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
    
    # Tell FastCGI to put its temporary files somewhere sane.
    FastCgiIpcDir /tmp

    FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120

    AddHandler fastcgi-script fcgi
    ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
    
 </VirtualHost>


== Make your webserver user a member of the "rt" group ==

Pros: Easy to configure

Cons: Your webserver has access to RT's private database password


=== How To

Install RT normally. Add whichever user your webserver runs as
(whatever you set --with-web-user to) to the "rt" group (whatever
you set --with-rt-group to) in /etc/groups.

To find out what user your webserver runs as, look for the line

  User some-user-name

in your apache httpd.conf. Common values are www, www-data, web and nobody.



== Run RT using _suexec_ or a similar mechanism


Pros: More secure

Cons: Sometimes very difficult to configure

Apache's _suexec_ utility allows you run CGI programs as specific
users. Because that's a relatively heavy responsibility, it's very,
very conservative about what it's willing to do for you. On top of
that, Apache's mod_fastcgi plugin doesn't respect all of suexec's
features.  While suexec is designed to execute CGI scripts in a
given virtual host's !DocumentRoot, It can only execute FastCGI
scripts in the system's *main* !DocumentRoot.

This means you have to copy the RT FastCGI handler into your main
!DocumentRoot

The following example !VirtualHost will run RT as a FastCGI on
Apache 1.3 on a Debian Linux server.


 <VirtualHost rt.example.com>
 
   DocumentRoot /opt/rt3/share/html
 
    # Set the rt user and group as the executing user for this virtual host
    User rt
    Group rt


    # Pass through requests to display images
    Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
    
    # Tell FastCGI to put its temporary files somewhere sane.
    FastCgiIpcDir /tmp

    # Tell FastCGI that it should use apache's "suexec" binary to call any 
    # FastCGI script.
    # This is a GLOBAL setting
    FastCgiWrapper /usr/lib/apache/suexec

    # You need to copy the rt mason_handler.fcgi into a directory inside 
    # the main server DocumentRoot
    # That directory must be owned by the user and group that will execute 
    # the FastCGI script
    # In this case, that directory is /var/www/rt

    # To find the local DocumentRoot, run "suexec -V" as root and look for the 
    #  -D DOC_ROOT parameter.

    # Apache 1.3 discards the user and group parameters on the FastCgiServer 
    # line. Apache 2.0 requires them.

    FastCgiServer /var/www/rt/mason_handler.fcgi -idle-timeout 120 -user rt -group rt

    AddHandler fastcgi-script fcgi
    ScriptAlias / /var/www/rt/mason_handler.fcgi/
    
 </VirtualHost>

UPGRADING FROM 2.x:

See http://search.cpan.org/dist/RT-Extension-RT2toRT3/