X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=rt%2FUPGRADING;h=6466a36a50de0f45ab2cdeb16bb9f109316ae691;hp=4306eb6cbbbabfad39c67956ccbddea92844f0d7;hb=573139dbd6c37808697bfa72a3a468bb0980d4dd;hpb=eb9668a6f3181ee02cb335272c5ee4616e61fd09 diff --git a/rt/UPGRADING b/rt/UPGRADING index 4306eb6cb..6466a36a5 100644 --- a/rt/UPGRADING +++ b/rt/UPGRADING @@ -1,64 +1,417 @@ 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: + + + + # 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/ + + + + +== 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 -Look for the +in your apache httpd.conf. Common values are www, www-data, web and nobody. ----------------------------------------------------------------------- -3.0.7 -===== +== Run RT using _suexec_ or a similar mechanism -All Databases -------------- -If you are upgrading from versions between 3.0.0 and 3.0.7, inclusive, -you might find improved performance by adding the following index to -your database: +Pros: More secure -CREATE INDEX Links4 ON Links(Type,LocalBase); +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 -3.0.6 -===== +The following example !VirtualHost will run RT as a FastCGI on +Apache 1.3 on a Debian Linux server. -All Databases -------------- + + + DocumentRoot /opt/rt3/share/html + + # Set the rt user and group as the executing user for this virtual host + User rt + Group rt -If you are upgrading from versions between 3.0.0 and 3.0.6, inclusive, -you might find improved performance by adding the following indices to -your database: - CREATE INDEX TicketCustomFieldValues1 ON TicketCustomFieldValues (CustomField,Ticket,Content); - CREATE INDEX TicketCustomFieldValues2 ON TicketCustomFieldValues (CustomField,Ticket); + # 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 - CREATE INDEX CustomFieldValues1 ON CustomFieldValues (CustomField); + # 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. -Postgres --------- + # Apache 1.3 discards the user and group parameters on the FastCgiServer + # line. Apache 2.0 requires them. -If you have a Postgres database, the following changes to your -database can improve performance: + FastCgiServer /var/www/rt/mason_handler.fcgi -idle-timeout 120 -user rt -group rt - ALTER TABLE groups rename instance to instance1; - ALTER TABLE groups add instance int; - UPDATE groups SET instance = instance1::text::int where btrim(instance1) <> ''; - ALTER TABLE groups drop column instance1; + AddHandler fastcgi-script fcgi + ScriptAlias / /var/www/rt/mason_handler.fcgi/ + + +UPGRADING FROM 2.x: +See http://search.cpan.org/dist/RT-Extension-RT2toRT3/