X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=rt%2FUPGRADING;h=7256f976b51acd9c57a054c8c0aa806b532182d3;hp=4306eb6cbbbabfad39c67956ccbddea92844f0d7;hb=d39d52aac8f38ea9115628039f0df5aa3ac826de;hpb=c582e92888b4a5553e1b4e5214cf35217e4a0cf0

diff --git a/rt/UPGRADING b/rt/UPGRADING
index 4306eb6cb..7256f976b 100644
--- a/rt/UPGRADING
+++ b/rt/UPGRADING
@@ -1,64 +1,179 @@
 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.
 
+*******
+
+
+UPGRADING FROM 3.0.x - Changes:
+
+= Installation =
+
+We recommend you move your existing /opt/rt3 tree completely out
+of the way before installating the newversion 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 signficant 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.
 
-Look for the 
+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.
 
-3.0.7
-=====
 
-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:
+== Run RT using _suexec_ or a similar mechanism
 
-CREATE INDEX Links4 ON Links(Type,LocalBase);
 
+Pros: More secure
 
+Cons: Sometimes very difficult to configure
 
-3.0.6
-=====
+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
 
-All Databases
--------------
+The following example !VirtualHost will run RT as a FastCGI on
+Apache 1.3 on a Debian Linux server.
 
-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); 
+ <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
 
-   CREATE INDEX CustomFieldValues1 ON CustomFieldValues (CustomField);
 
+    # 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
 
-Postgres
---------
+    # 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
 
-If you have a Postgres database, the following changes to your
-database can improve performance:
+    # To find the local DocumentRoot, run "suexec -V" as root and look for the 
+    #  -D DOC_ROOT parameter.
 
-  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;
+    # 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>