rt/UPGRADING

   1 UPGRADING
   2
   3 Detailed information about upgrading can be found in the README file.
   4 This document is intended to supplement the instructions in that file.
   5
   6 Additional information about upgrading from specific versions of RT is
   7 contained below.
   8
   9 *******
  10 WARNING
  11 *******
  12
  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.
  16
  17 *******
  18
  19
  20 UPGRADING FROM 3.0.x - Changes:
  21
  22 = Installation =
  23
  24 We recommend you move your existing /opt/rt3 tree completely out
  25 of the way before installating the newversion of RT, to make sure
  26 that you don't inadvertently leave old files hanging around.
  27
  28 = Rights changes =
  29
  30 Now, if you want RT to automatically create new users upon ticket
  31 submission, you MUST grant 'Everyone' the right to create tickets.
  32 Granting this right only to "Unprivileged Users" is now insufficient.
  33
  34
  35 = FastCGI configuration =
  36
  37 This section is a snapshot of the documentation available at:
  38
  39 http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration
  40
  41 It's worth checking out that resource if these instructions don't
  42 work right for you
  43
  44
  45 RT 3.2 includes a signficant change to the FastCGI handler. It is
  46 no longer "setgid" to the RT group.  Perl's setid support has been
  47 deprecated for the last several releases and a number of platforms
  48 don't bundle the "sperl" or "suidperl" executable by default.
  49 Additionally, when perl is run SetUID or SetGID, the interpreter
  50 is automatically switched into /taint mode/, in which all incoming
  51 data, no matter the source is considered suspect. At first, this
  52 seems like a great idea. But perl's taint mode is a big sledgehammer
  53 used to hit small nails.  Many perl libraries aren't tested in taint
  54 mode and will fail when least expected.  Moving away from a SetGID
  55 FastCGI handler will enable more users to have a smoother RT
  56 experience.  It does require some changes in how you set up and
  57 configure RT.
  58
  59 Beginning with RT 3.2, you have several choices about how to configure
  60 RT to run as a FastCGI:
  61
  62
  63 == Install RT as the user your webserver runs as ==
  64
  65 Pros: Very easy to configure
  66
  67 Cons: Your webserver has access to RT's private database password
  68
  69
  70 === How To
  71
  72 When installing RT, run:
  73
  74  ./configure --with-web-user="webuser"  --with-web-group="webgroup"  \
  75     --with-rt-user="webuser" --with-rt-group="webgroup"
  76
  77 (Don't forget to include other configuration options that matter to you)
  78
  79 If you're using apache, you'll want to add something like the following
  80 to your httpd.conf:
  81
  82  <VirtualHost rt.example.com>
  83
  84     # Pass through requests to display images
  85     Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
  86
  87     # Tell FastCGI to put its temporary files somewhere sane.
  88     FastCgiIpcDir /tmp
  89
  90     FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120
  91
  92     AddHandler fastcgi-script fcgi
  93     ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
  94
  95  </VirtualHost>
  96
  97
  98 == Make your webserver user a member of the "rt" group ==
  99
 100 Pros: Easy to configure
 101
 102 Cons: Your webserver has access to RT's private database password
 103
 104
 105 === How To
 106
 107 Install RT normally. Add whichever user your webserver runs as
 108 (whatever you set --with-web-user to) to the "rt" group (whatever
 109 you set --with-rt-group to) in /etc/groups.
 110
 111 To find out what user your webserver runs as, look for the line
 112
 113   User some-user-name
 114
 115 in your apache httpd.conf. Common values are www, www-data, web and nobody.
 116
 117
 118
 119 == Run RT using _suexec_ or a similar mechanism
 120
 121
 122 Pros: More secure
 123
 124 Cons: Sometimes very difficult to configure
 125
 126 Apache's _suexec_ utility allows you run CGI programs as specific
 127 users. Because that's a relatively heavy responsibility, it's very,
 128 very conservative about what it's willing to do for you. On top of
 129 that, Apache's mod_fastcgi plugin doesn't respect all of suexec's
 130 features.  While suexec is designed to execute CGI scripts in a
 131 given virtual host's !DocumentRoot, It can only execute FastCGI
 132 scripts in the system's *main* !DocumentRoot.
 133
 134 This means you have to copy the RT FastCGI handler into your main
 135 !DocumentRoot
 136
 137 The following example !VirtualHost will run RT as a FastCGI on
 138 Apache 1.3 on a Debian Linux server.
 139
 140
 141  <VirtualHost rt.example.com>
 142
 143    DocumentRoot /opt/rt3/share/html
 144
 145     # Set the rt user and group as the executing user for this virtual host
 146     User rt
 147     Group rt
 148
 149
 150     # Pass through requests to display images
 151     Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
 152
 153     # Tell FastCGI to put its temporary files somewhere sane.
 154     FastCgiIpcDir /tmp
 155
 156     # Tell FastCGI that it should use apache's "suexec" binary to call any
 157     # FastCGI script.
 158     # This is a GLOBAL setting
 159     FastCgiWrapper /usr/lib/apache/suexec
 160
 161     # You need to copy the rt mason_handler.fcgi into a directory inside
 162     # the main server DocumentRoot
 163     # That directory must be owned by the user and group that will execute
 164     # the FastCGI script
 165     # In this case, that directory is /var/www/rt
 166
 167     # To find the local DocumentRoot, run "suexec -V" as root and look for the
 168     #  -D DOC_ROOT parameter.
 169
 170     # Apache 1.3 discards the user and group parameters on the FastCgiServer
 171     # line. Apache 2.0 requires them.
 172
 173     FastCgiServer /var/www/rt/mason_handler.fcgi -idle-timeout 120 -user rt -group rt
 174
 175     AddHandler fastcgi-script fcgi
 176     ScriptAlias / /var/www/rt/mason_handler.fcgi/
 177
 178  </VirtualHost>
 179