Before you can make use of most of the wonderful advice and tricks in this book, you need a live RT instance running. If you already have an installed and running RT instance, skip to Chapter 3. In many ways, the initial installation of RT is the hardest part. RT is a complex Perl application with many dependencies—once all of those dependencies are in place, RT installs easily. Most of the time installing RT is spent installing those modules.
RT was designed to run on UNIX and UNIX-like systems. This means Linux, Solaris, FreeBSD, IRIX, HP/UX, Mac OS X, and similar systems. If your operating system of choice has pre-built packages for RT, that is the easiest way to install it. These third party packages are contributed and don’t come from the RT developers. As of this writing, packages are available for Debian, FreeBSD, RedHat, and Mandrake Linux. There are some downsides to these packages: they may put files in unexpected locations to conform to packaging requirements, and they also may be out of date.
RT also runs on Windows. It is experimental and unsupported, so this chapter won’t cover it, but it generally works. All of the component pieces (Perl, Apache, and MySQL) are available natively. The easiest way to get it running is to use Autrijus Tang’s pre-packaged version of RT for Windows, which includes all the component pieces in one convenient installer. Download it from http://wiki.bestpractical.com/?WindowsOSInstallGuide.
Before you begin setting up RT, you need to satisfy a few requirements. RT is complex, and the requirements are fairly strict, as Perl applications go.
You must have a recent version of Perl installed. RT will run on older versions of Perl, but bugs in the Unicode implementation in older versions may cause data corruption. (And you really don’t want to have to explain that to your boss.)
You do not need to install the same Perl that you use for RT as your system-wide version of Perl (i.e., as /usr/bin/perl). You can install it off to the side, in /usr/local or wherever you’d like. If you choose to use mod_perl, it must be linked against this installation of Perl.
If the server running RT also runs other services (especially other mod_perl applications), you might want to create an installation of Perl specifically for RT to ensure that there are no dependency or version problems.
Ultimately, RT is all about its database . You have several options here:
MySQL 4.0.14 or later, with InnoDB support enabled (http://www.mysql.com/)
PostgreSQL 7.2 or later (http://www.postgresql.com/)
Oracle 9iR2 or later (http://www.oracle.com/)
SQLite (http://www.sqlite.org/)
RT runs equally well on MySQL and PostgreSQL. Oracle support is relatively new, but it should be as stable as the MySQL and PostgreSQL. An option for development is SQLite, a lightweight single-file database engine. We don’t recommend you run it in a production environment, because it doesn’t support high levels of concurrency well. Check the README file that comes with RT to see if the latest version supports any other databases.[4] You should choose which database to use based on what’s familiar to you and what resources you have available.
If you don’t have a preferred database, we suggest you choose MySQL. It is the easiest supported database to set up and maintain.
It may be possible to make RT install on earlier versions of MySQL or PostgreSQL, but as with earlier versions of Perl, you may run into trouble. In general, we recommend using the latest stable release version of whichever database you choose. At the time of writing, that version is MySQL 4.1.10 and PostgreSQL 8.0.1.
For production uses, you want a scalable web server (instead of the standalone_httpd that comes with RT). Any of the following will do:
Apache 1.3 with mod_perl 1.x (http://www.apache.org/ and http://perl.apache.org/)
Apache 2.x with mod_perl 2.x
Apache 1.x or 2.x with the FastCGI module (http://www.fastcgi.com/)
Any FastCGI compliant web server
As with choice of database, choice of web server often depends on what you already have installed. If you’re building a stand-alone RT system, the most stable configuration is the latest Apache 1.3 series release with the latest compatible mod_perl 1.x release.
At the time of this writing, mod_perl 2.0 has just been released. Some of the libraries that RT depends on haven’t been put through their paces with it. During the mod_perl 2 beta cycle, most of the kinks have been worked out, but there could still be some gremlins hiding in the corners. (Make sure you build your Apache 2.0 with the prefork MPM to avoid odd threading issues.)
For more information on choosing between different Apache versions, you might want to look at Apache: The Definitive Guide, 3rd Edition (O’Reilly).
Most everyone runs RT on an Apache or Apache-derived web server, but RT’s FastCGI server is known to play well with other servers. If you use something else, like SunOne/Netscape/iPlanet or WebStar and have a FastCGI plugin for it, it should work.
RT makes heavy use of freely available Perl libraries available on the CPAN. To make your installation process somewhat smoother, Best Practical has created a (mostly) automated procedure using the CPAN.pm module to download and install libraries from CPAN. See Step 6: Check for RT’s Perl Dependencies later in this chapter. Depending on your system configuration, there are still a couple of difficult modules that must be installed manually—mostly ones that require external libraries to be present, like your database’s client libraries or the Apache libraries.
A list of required modules and versions can be found in Appendix D.
Get yourself a comfortable chair, a nice drink, some free hard disk space, and sit down for an hour or so of module building and configuration to install RT.
Like most database driven applications, RT is relatively resource intensive, especially on RAM. The more memory you can afford to dedicate to RT and its database server, the snappier it will feel and the happier your users will be. Fast CPUs and disks will help as well.
Also in this step, you should install the appropriate webserver and database, if those aren’t installed yet.
There are good O’Reilly books on each of the supported databases, including Managing and Using MySQL, Practical PostgreSQL, and Oracle Essentials. Many of these books are also available on Safari, O’Reilly’s online library, which makes searching convenient. You can access Safari by going to http://safari.oreilly.com.
You can find information about the latest RT releases from the official RT download page at http://www.bestpractical.com/rt/download.html. In addition to the locations for packaged releases, this page also contains instructions on how to download the latest development copy of RT.
The latest stable release of RT is always available as http://download.bestpractical.com/pub/rt/release/rt.tar.gz, so you can grab that now, and place it in /tmp.
With the tarball now in /tmp, unpack it with gunzip or an equivalent utility on your system:
# gunzip -c rt.tar.gz | tar xvf -
This creates a directory named rt-3.x.x, where 3.x.x is the version of RT you downloaded. Make that directory your current working directory:
# cd rt-3.x.x
Take a moment to read through the README file in your new RT directory. This file covers the basics of the installation, with brief instructions on how to do the install. More importantly, this file is the canonical location for updates to the installation procedure. If you are using Oracle, you’ll also want to read the Oracle-specific instructions in the file README.Oracle. Finally, any special notes about upgrading an RT installation are in the file UPGRADING.
At this point, you’ll need to know certain information in order to continue: The server architecture (mod_perl 1.x, mod_perl 2.x, FastCGI); database type (MySQL, PostgreSQL, or Oracle); where the database lives and the usernames and passwords to access it; and which Perl you want to use. If you don’t have that information yet, pause and collect it now.
Now you need to tell RT how to install itself by running the configure program. It takes a number of different options. We’ll explain most of them here and in the following sections, but you can get a complete and current list with the —help option:
# ./configure --help
You can install RT in any directory by using the —prefix option, and it will put all of its files under that location. The default is /opt/rt3. Some users prefer to specify /usr/local/rt3. You can also put a private install in a location such as /home/you/projects/rt.
--prefix=PREFIX where to install RT's files to
Unless you change the configuration, RT will write any logs, session files, and HTML::Mason object cache files under the location you select, so you will want to choose a partition with a few hundred megabytes of free space.
Select alternate file layouts with —enable-layout=inplace, —enable-layout=FHS, and —enable-layout=FreeBSD. See config.layout in the source directory for more information on each.
These settings (see Table 2-1) control the file ownership that will be used on all of the installed files. You must make sure that all the users and groups exist before you try and configure RT. They are optional unless you wish to change the detected defaults.
Table 2-1. File ownership
|
Option |
Meaning |
|---|---|
|
|
The group that owns all files (default: rt, rt3) |
|
|
The user that owns the RT binaries (default: root) |
|
|
The user that owns the RT libraries (default: root) |
|
|
The group that owns the RT libraries (default: bin) |
|
|
The user the web server runs as (defaults: www, www-data, apache, httpd, nobody) |
|
|
The group the web server runs as (defaults: www, www-data, apache, httpd, nogroup, nobody) |
|
|
Set all users and groups mentioned above to the current user and group (i.e. “you”) |
By default, RT assumes the existence of several users and groups on your system and will autodetect the defaults mentioned in this table. The standard configuration is to have all RT files owned by a ‘rt’ group. The installation process will chown or chgrp any files and directories that need to be accessible by the webserver.
These defaults are probably fine for most people installing into a system-wide directory like /opt/rt3 or /usr/local/rt3. The reason for this complex set of permissions is because only certain users/groups should be able to write to (and read) certain files for security purposes.
On some systems, the web-user and web-group should be set to “nobody”, “apache” or “httpd.” Look at the User and Group lines in your httpd.conf for details.
If you are performing a non-root install, (i.e., into your home directory or entirely as a special rt user) then you can use --with-my-user-group to use only your current user and group. This will use the current value of the $USER or $LOGUSER environment variables and the first entry in the output of “groups”.
RT needs to be able to talk to the database you’ve specified and also needs to create users and tables. To do this, it needs to know where you want your RT database to be. It also needs to know the username of an account that has permission to create and modify databases. For MySQL this is usually root but is configurable (see Table 2-2). RT will prompt you for the administrator’s password, so it can create the appropriate tables.
Table 2-2. Database options
|
Option |
Meaning |
|---|---|
|
|
The type of database RT will use: |
|
|
The fully qualified domain name of the database server (default: localhost) |
|
|
The port on which the database listens |
|
|
The fully qualified domain name of RT server that talks to the database server (default: localhost) |
|
|
The name of the database administrator (default: root) |
|
|
The name of the database to use (default: rt3) |
|
|
The name of the database user (default: rt_user) |
|
|
The password for the database user (default: rt_pass) |
You will want to change the default password for the user RT will create. It’s insecure to leave the default password of “rt_pass.”
Some systems have multiple instances or versions of Perl installed, and you don’t always want to use the default one for RT. (This is especially true because RT requires a recent version of Perl to function properly.) Use the PERL environment variable to specify the location of the Perl binary you want RT to use. For example:
$ env PERL=/usr/local/bin/perl ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking for perl... /usr/local/bin/perl
checking for chosen layout... RT3
checking if user www exists... not found
checking if user www-data exists... not found
checking if user apache exists... found
checking if group www exists... not found
checking if group www-data exists... not found
checking if group apache exists... found
checking if group rt3 exists... not found
checking if group rt exists... found
checking if group apache exists... found
which: no apachectl in (/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin)
configure: creating ./config.status
config.status: creating sbin/rt-dump-database
config.status: creating sbin/rt-setup-database
config.status: creating sbin/rt-test-dependencies
config.status: creating bin/mason_handler.fcgi
config.status: creating bin/mason_handler.scgi
config.status: creating bin/standalone_httpd
config.status: creating bin/rt-crontool
config.status: creating bin/rt-mailgate
config.status: creating bin/rt
config.status: creating Makefile
config.status: creating etc/RT_Config.pm
config.status: creating lib/RT.pm
config.status: creating bin/mason_handler.svc
config.status: creating bin/webmux.plThis shows a default configuration of RT, using the Perl binary located at /usr/local/bin/perl and installing into the default location (/opt/rt3). Web scripts will be owned by the Apache user and in the Apache group. All other files will be in the rt group.
RT comes with a handy script called rt-test-dependencies that automatically queries your chosen version of Perl for all the modules that RT requires, and generates a report of what it finds. You can have RT run this script with the right options by issuing the following command:
# make testdeps
The script will output a report similar to the following:
/usr/local/bin/perl ./sbin/rt-test-dependencies --verbose --with-mysql
perl:
5.8.3...found
users:
rt group (apache)...found
bin owner (root)...found
libs owner (root)...found
libs group (bin)...found
web owner (apache)...found
web group (apache)...found
MASON dependencies:
Params::Validate 0.02...found
Cache::Cache ...found
Exception::Class 1.14...found
HTML::Mason 1.23...found
MLDBM ...found
Errno ...found
FreezeThaw ...found
Digest::MD5 2.27...found
CGI::Cookie 1.20...found
Storable 2.08...found
Apache::Session 1.53...found
XML::RSS ...found
HTTP::Server::Simple 0.07...MISSING
HTTP::Server::Simple version 0.07 required—this is only version 0.04
at (eval 41) line 2, <DATA> line 11.
HTTP::Server::Simple::Mason 0.03...found
MAILGATE dependencies:
HTML::TreeBuilder ...found
HTML::FormatText ...found
Getopt::Long ...found
LWP::UserAgent ...found
CLI dependencies:
Getopt::Long 2.24...found
CORE dependencies:
Digest::base ...found
Digest::MD5 2.27...found
DBI 1.37...found
Test::Inline ...found
Class::ReturnValue 0.40...found
DBIx::SearchBuilder 1.21...found
Text::Template ...found
File::Spec 0.8...found
HTML::Entities ...found
HTML::Scrubber 0.08...found
Net::Domain ...found
Log::Dispatch 2.0...found
Locale::Maketext 1.06...found
Locale::Maketext::Lexicon 0.32...found
Locale::Maketext::Fuzzy ...found
MIME::Entity 5.108...found
Mail::Mailer 1.57...found
Net::SMTP ...found
Text::Wrapper ...found
Time::ParseDate ...found
Time::HiRes ...found
File::Temp ...found
Term::ReadKey ...found
Text::Autoformat ...found
Text::Quoted 1.3...found
Tree::Simple 1.04...found
Scalar::Util ...found
Module::Versions::Report ...found
Cache::Simple::TimedExpiry ...found
XML::Simple ...found
DEV dependencies:
Regexp::Common ...found
Test::Inline ...found
Apache::Test ...found
HTML::Form ...found
HTML::TokeParser ...found
WWW::Mechanize ...found
Test::WWW::Mechanize ...found
Module::Refresh 0.03...found
MYSQL dependencies:
DBD::mysql 2.1018...foundIf anything is missing, RT can use the CPAN.pm module to install it. If you haven’t previously configured CPAN.pm, you need to do that before running this script. Run perl -MCPAN -eshell and follow the instructions. Then, RT can attempt to automatically install the necessary modules; run make fixdeps:
# make fixdeps
This step requires either a network connection—to contact a CPAN mirror—or a local CPAN mirror, so that the installer can download any missing modules.
Earlier, you had the chance to specify three potentially different users and three groups: the user and group to own the scripts that RT installs, the user and group to own the libraries that RT installs, and the user and group that will run the web server process. At this point, you should make sure that these users and groups exist, because if they don’t, the installation process will fail. How to do this depends on your system, but many systems provide the useradd and groupadd tools to automate the process. However you do it, create the users and groups now, if necessary.
RT will copy all the files to the appropriate location under PREFIX. If you are not doing a —with-my-user-group install, you will need to run this as root, since the process changes the ownership and permission of many of the files.
# make install
RT will create the appropriate database, users, and initialize some tables when you run make initialize-database. (Do not run this more than once, unless you want to lose your data.)
# make initialize-database
Creating mysql database rt.
Now populating database schema.
Creating database schema.
schema sucessfully inserted
Now inserting database ACLs
Now inserting RT core system objects
Checking for existing system user...not found. This appears to be a new installation.
Creating system user...done.
Now inserting RT data
Creating Superuser ACL...Creating groups...3.4.5.6.7.8.9.done.
Creating users...10.12.done.
Creating queues...1.2.done.
Creating ACL...2.3.done.
Creating ScripActions...1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.done.
Creating ScripConditions...1.2.3.4.5.6.7.8.9.done.
Creating templates...1.2.3.4.5.6.7.8.9.10.11.12.done.
Creating scrips...1.2.3.4.5.6.7.8.9.10.11.12.13.done.At this point, RT is installed. The next step is to configure it and then configure your web servers and mail servers to talk to it properly. If you already have a webserver with mod_perl or FastCGI set up, the hard work is over.
The primary configuration file for RT is etc/RT_SiteConfig.pm, which is based on etc/RT_Config.pm. You should never edit etc/RT_Config.pm. It contains default values and will get overwritten during upgrades. However, any changes you make in etc/RT_SiteConfig.pm will take precedence.
RT has many configuration options, but most sites only need a few to get up and running. For more advanced configuration options, see Chapter 7 and Appendix E.
The data in RT_SiteConfig.pm can be in any order. You should place things in logical groupings, so that you can easily find them. The definitive reference on the possible configuration options for any particular version of RT is RT_Config.pm.
Once you’ve finalized the configuration for your new RT instance, be sure to back up RT_SiteConfig.pm somewhere safe. Other than the database, this is the single most important file in your RT installation, and complex configurations can be difficult and time-consuming to recreate manually.
There are some options you must configure. They are site-specific information.
The $rtname option is a short, unique name for this particular RT instance. It appears in the subject line of emails, so the RT instance can determine that the ticket was intended for it. Do not choose a generic name like “support” or “tech” for your $rtname, because this has the potential to conflict with other RT instances. A short version of your company name or its acronym are good examples.
Set($rtname, "examplecorp");
$Organization should be a unique identifier for this particular RT instance, similar to a domain-name. $Organization is used for generating message identifiers and linking between RT instances. It does not necessarily have to be a valid hostname.
Set($Organization, "rt.example.com");
Once you chose a $rtname and $Organization, you will need to be very careful about changing them, because RT uses them internally to maintain data structures.
Setting the $Timezone isn’t required, but your users will be happier if you do. The value is system-specific. Look in your zoneinfo database directories (usually located in /usr/share/zoneinfo or /usr/share/lib/zoneinfo) for valid values.
Set($Timezone, 'US/Pacific');
You will also need to set $WebPath and $WebBaseURL to match how you will configure your webserver. $WebBaseURL should not have a trailing slash. $WebBaseURL includes the schema, hostname, and port (if necessary) for your RT instance. $WebPath is the rest of the path. An RT instance at http://support.example.com/rt3 would use the following settings:
Set($WebBaseURL, "http://support.example.com");
Set($WebPath, "/rt3");Or, an RT instance on its own virtualhost at http://rt.example.com/ might use the following:
Set($WebBaseURL, "http://rt.example.com");
Set($WebPath, "/");RT needs to know the default addresses to use for queues that don’t have an email address explicitly set. These must be configured in your mail system, as detailed later in this chapter.
Set($CorrespondAddress, 'correspond@rt.example.com');
Set($CommentAddress, 'comment@rt.example.com');You may also need to tell RT how to send outbound email. Generally the default setting will work. If you don’t have a sendmail-like program at /usr/sbin/sendmail, you will need to set that path as appropriate. For example:
Set($SendmailPath, "/usr/lib/sendmail");
By default, RT logs all messages (level debug and up) to syslog with facility user. If you want to log to a file instead, use the following settings:
Set($LogToSyslog, ''); # disable syslog
Set($LogToFile, 'debug'); # set file logging
to include everything
Set($LogDir, '/opt/rt3/var/log'); # path to log
Set($LogToFileNamed , "rt.log"); # logfile nameBe sure to set the $LogDir appropriately.
Many more possibilities for logging configuration are discussed in Appendix E.
A sample site configuration might look like this:
Set($rtname, "examplecorp");
Set($Organization, "rt.example.com");
Set($Timezone, 'US/Pacific');
Set($WebBaseURL, "http://support.example.com");
Set($WebPath, "/rt3");
Set($CorrespondAddress, 'correspond@rt.example.com');
Set($CommentAddress, 'comment@rt.example.com');
Set($SendmailPath, "/usr/lib/sendmail");
Set($LogToSyslog, '');
Set($LogToFile, 'debug');
Set($LogDir, '/opt/rt3/var/log');
Set($LogToFileNamed , "rt.log");
Set($OwnerEmail, "admin@example.com");
Set($MyTicketsLength, 20);
1;Now that you have RT configured, it is time to configure your webserver. In the previous stage you set $WebBaseURL and $WebPath to where in “URLspace” you plan to have RT installed. Now we’ll tell Apache
about those values. (If you are not using Apache, you will need to extrapolate from the FastCGI section below.)
A common configuration for RT is to place it on its own VirtualHost, such as on rt.example.com for the example.com organization.
Use the following configuration in your httpd.conf:
<VirtualHost *>
ServerName rt.example.com
DocumentRoot /opt/rt3/share/html
AddDefaultCharset UTF-8
PerlModule Apache::DBI
PerlRequire /opt/rt3/bin/webmux.pl
<Location />
SetHandler perl-script
PerlHandler RT::Mason
</Location>
</VirtualHost>You will need NameVirtualHost * earlier in your httpd.conf unless you are using IP-based virtual hosting. (In that case, specify an IP address in place of the *.)
That configuration corresponds to the following lines in RT_SiteConfig.pm.
Set($WebBaseURL, "http://rt.example.com");
Set($WebPath, "/");Using a separate virtual host isn’t required. You can place RT at any location on your webserver. The following example places it at /rt3/:
Alias /rt3 /opt/rt3/share/html
<Location /rt3>
AddDefaultCharset UTF-8
SetHandler perl-script
PerlHandler RT::Mason
PerlModule Apache::DBI
PerlRequire /opt/rt3/bin/webmux.pl
</Location>If your webserver is www.example.com, these would be the RT_SiteConfig.pm entries:
Set($WebBaseURL, "http://www.example.com");
Set($WebPath, "/rt3");An alternative to mod_perl is FastCGI. FastCGI is a protocol designed to allow a web server to run CGI scripts via a separate, persistent program. FastCGI defines how a web server interacts with this separate program in much the same way that the CGI spec defines how a web server and regular spawned programs interact. There are FastCGI implementations for many web servers—including Apache 1.3.x and Apache 2.x—that should work just fine with RT.
There are several cases where you might want to use FastCGI instead of mod_perl:
FastCGI is much simpler to install; mod_perl may be difficult to build on some systems.
Your core Apache process will stay small in size.
Because the perl process running RT is a separate process, it can be stopped or restarted without having to take down the web server.
FastCGI programs are often easier to manage, both for sysadmins maintaining a running instance and for developers who are making frequent changes to their code.
The official FastCGI homepage is at http://www.fastcgi.com/, and it provides a lot of good information about running and developing FastCGI applications, as well as download information.
Configuring FastCGI under Apache, you’ll need this chunk of configuration in your httpd.conf:
Under Apache, as a separate virtual host, the configuration looks like this:
<VirtualHost *>
ServerName rt.example.com
FastCgiServer /opt/rt3/bin/mason_handler.fcgi
AddHandler fastcgi-script fcgi
Alias /NoAuth/images/ /opt/rt3/html/NoAuth/images/
ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
</VirtualHost>If your RT will live at /rt3/, the configuration would look like this:
FastCgiServer /opt/rt3/bin/mason_handler.fcgi
AddHandler fastcgi-script fcgi
Alias /rt3/NoAuth/images/ /opt/rt3/html/NoAuth/images/
ScriptAlias /rt3 /opt/rt3/bin/mason_handler.fcgi/By default, FastCGI will start only one process at a time. If your RT instance experiences high concurrent use, you will want to tell FastCGI to start more processes by using the -processes option to FastCgiServer.
FastCgiServer /opt/rt3/bin/mason_handler.fcgi -processes 10
Depending on your configuration, you might not be able to, or want to, run RT on your main webserver. One solution to this problem is to use a proxy in front of it. Figure 2-1 shows a proxied RT server. Apache 2.x, beyond being a webserver, also can function as a high-performance proxy.
There are several reasons you might want to do this:
First, only one instance of a mod_perl 1.x application can run inside Apache at a time, because there is a shared Perl interpreter. Multiple instances of an application can conflict with unexpected and undesirable results. A proxy can be used to map multiple instances into one URLspace.
Apache 2.x and mod_perl 2.x doesn’t have this limitation. Perl interpreters can be bound to VirtualHosts or Locations with PerlOptions +Parent .
Second, Perl applications use a lot of RAM, and all Apache processes will end up allocating this RAM. If you also are serving static content, the memory usage will be high, thus limiting the number of Apache processes a machine can support and throughput..
Third, a proxy can allow your server to serve more requests. The back-end server won’t need to buffer for a slow network connection and can quickly return to serving requests. This means you will need fewer heavy mod_perl processes running.
Finally, RT is designed to be a secure application, but as with any piece of software there is always potential for a hole to be found. By using a proxy to a dedicated Apache server, RT can be isolated from other services on the system. A compromise of RT would not imply instant access to the rest of the web system.
Apache 2.x is a good candidate for this, as it’s a bit faster and a little more flexible than Apache 1.x.
In your front-end proxy webserver, use the following configuration, after making sure that mod_rewrite and mod-proxy loaded:
<VirtualHost *>
ServerName rt.example.com
RewriteEngine On
RewriteRule ^/(.*)$ http://localhost:8284/$1 [P,L]
</VirtualHost>Under Apache 2.x, mod_proxy offers a cleaner configuration:
<VirtualHost *>
ServerName rt.example.com
ProxyPass / http://localhost:8284/
ProxyPassReverse / http://localhost:8284/
</VirtualHost>Then, as shown in Figure 2-1, configure another Apache running RT on a high-numbered port, such as 8284 in this example. You can configure your firewall so it can only receive traffic from the proxy server.
This approach is explained in great detail in the mod_perl documentation, at http://perl.apache.org/docs/1.0/guide/strategy.html, and in the mod_perl Developer’s Cookbook, by Geoffrey Young, Paul Lindner, and Randy Kobes (Sams) and in Practical mod_perl by Stas Bekman and Eric Cholet (O’Reilly).
RT also includes a standalone webserver. It doesn’t need Apache or anything besides Perl and RT.
You can start it by running bin/standalone_httpd. You may also specify a port number, i.e. bin/standalone_httpd 8888.
The standalone server is meant primarily for development. It can do only one thing at a time, which makes it suboptimal for multiple concurrent users.
Configuring RT to send mail consists of a few steps. First of all, make sure that the server has a working MTA (Mail Transfer Agent).
Common MTAs include sendmail (http://www.sendmail.org/), postfix (http://www.postfix.org/), and qmail (http://cr.yp.to/qmail.html). Most Unix-based operating systems ship with at least one of these available by default (Linux distributions have almost all of them available, in fact). Installing and configuring the MTA is beyond the scope of this book, but the vendors’ web sites all provide detailed installation and configuration instructions.
Once you have the MTA installed and set up to send mail, you need to tell RT to use it. Look in the RT_Config.pm file, and copy the following lines to RT_SiteConfig.pm:
Set($SendmailPath , "/usr/sbin/sendmail");
Set($SendmailArguments , "-oi -t");Since it’s the traditional location for sendmail, /usr/sbin/sendmail will usually work. Most other MTAs respect this tradition through compatibility wrappers. If /usr/sbin/sendmail does not exist, try /usr/lib/sendmail.
Incoming mail destined for RT is processed through RT’s mailgate, conveniently called rt-mailgate. When it is invoked, this script parses the incoming message, and transfers it to your main RT server for processing. The mailgate does not have to run on the same machine as your main RT server, as long as it can communicate with it via http or https.
MTAs have the ability to pass mail destined for particular addresses to a program instead of to a mailbox, and RT utilizes this. Unfortunately, this feature is configured differently for different MTAs. Most of them support Sendmail’s traditional aliases format, so that’s the format we’ll be using for the examples in the following sections. A notable exception is qmail, which will be covered separately.
Several different command line options are supported by rt-mailgate (as shown in Table 2-3).
Table 2-3. Mailgate options
|
Option |
Meaning |
|---|---|
|
|
Select whether this email should be processed as a comment or correspondence. |
|
|
Select which queue to process the email into. |
|
|
The URL of your RT instance. |
|
|
Print debugging messages. |
|
|
Select the Queue, Action, or Ticket to operate on based on the $EXTENSION environment variable. For systems like Sendmail and Postfix which support rt+extension@host notation. |
|
|
How many seconds to give up after. Defaults to 180. |
Sendmail’s /etc/aliases file uses a simple name: value format, with the address receiving the mail on the left of the colon and the address to which it expands on the right hand side. The expansion address can be one of a few different types, including a different email address, a filename, or a program. There can be several expansion addresses as well, separated by commas.[5] You must run the newaliases command after editing /etc/aliases.
To specify a program to run when mail comes to an address you can use this syntax:
correspond: "|/opt/rt3/bin/rt-mailgate --queue General --action correspond --url http://rt.example.com/"
This passes the message to the script /opt/rt3/bin/rt-mailgate , which is configured with the command line arguments following the script name.
Modern versions of Sendmail require all programs called from the /etc/aliases file to be symlinked into the /etc/smrsh/ directory. You will receive DSN: Service unavailable errors if you haven’t done this. Use the following command:
# ln -s /opt/rt3/bin/rt-mailgate /etc/smrsh/
Postfix sometimes stores its aliases file at /etc/postfix/aliases. This file is in the same format as Sendmail’s. After editing it you must run Postfix’s newaliases script.
Unlike Sendmail and Postfix, qmail uses specially-named files in a user’s home directory to determine the handler for a message. Since you have already created a user account for RT, you can set that user up to process all RT-related mail. When qmail’s delivery agent tries to figure out what to do with an incoming message for a user, it first looks to see if there is an extension to the username. By default, this extension is separated from the username by a dash (-), so you could have
rt-foo@rt.example.com
, where rt is the username and foo is the extension. If there is an extension, then qmail will look in the rt user’s ~/.qmail-foo file for delivery instructions. Otherwise, it looks in the rt user’s ~/.qmail file.
To set up mail delivery into RT, you can create a series of .qmail files, two for each queue (for responses and comments). For example, the General queue would be handled by these files:
# cat ~rt/.qmail-general
|/opt/rt3/bin/rt-mailgate --queue General --action correspond --url
http://rt.example.com/
# cat ~rt/.qmail-general-comment
|/opt/rt3/bin/rt-mailgate --queue General --action comment --url http://rt.example.com/With these files in place, mail sent to rt-general@rt.example.com will become correspondence in the General queue, and mail sent to rt-general-comment@rt.example.com will become comments in the General queue.
You also can create a catch-all .qmail-default file:
# cat ~rt/.qmail-default |/opt/rt3/bin/rt-mailgate --queue $DEFAULT --action correspond --url http://rt.example.com/
Anything sent to rt-queuename will be delivered as correspondence to the queuename queue.
Note the rt- at the beginning of each address; that is because the mail is actually being sent to the rt user and handled using qmail’s convenient features. Setting up qmail so that these messages are handled globally, and not by a particular user, is a little different. Rather than a global /etc/aliases file, like the other MTAs use, qmail has a general alias user that handles all system-wide aliases. To make this user handle mail for RT, simply create the files ~alias/.qmail-general and ~alias/.qmail-general-comment with the same content as before. This allows the RT addresses to be
general@rt.example.com
and
general-comments@rt.example.com
. Under RT2, the mail handling script had to be setgid to the rt group, so the user restriction was important, but under RT3, this is no longer the case.
You also can call the mailgate from procmail. This allows you to perform virus or spam filtering before mail gets to RT. This can be very important because RT addresses are often published in places where spam-crawlers can find them.
Here’s an example procmail file that performs spam and virus filtering with SpamAssassin and ClamAV:
CLAMSCAN=`/usr/bin/clamscan --mbox --disable-summary --stdout -`
:0 iD
* CLAMSCAN ?? FOUND
viruses
:0fw
| spamassassin
:0 H
* ^X-Spam-Status: Yes
spam
:0
* ^TO_rt-general@
| /opt/rt3/bin/rt-mailgate --queue general --action correspond --url
http://rt.example.com/
:0
* ^TO_rt-general-comment@
| /opt/rt3/bin/rt-mailgate --queue general --action comment --url http://rt.example.com/This file will send all messages to rt-general@rt.example.com to the general queue as correspondence, and all messages to rt-general-comment@rt.example.com to the general queue as a comment. With a little bit of procmail magic, you can do much more powerful filtering and mail direction, but that’s beyond the scope of this book.
For more information on procmail, try The Procmail Companion (Addison Wesley), or visit http://procmail.org/ for more procmail resources.
Not everyone’s installation goes perfectly the first time. There are some common problems that may occur.
All necessary Perl dependencies must be installed. Make sure you’ve run
configurewith the proper arguments followed by amake testdeps. If there are any failures, you will need to resolve them.If you have odd email issues, double check that you have configured Sendmail’s smrsh by symlinking /opt/rt3/bin/rt-mailgate into /etc/smrsh.
Some places to go for help are the rt-users mailing list on http://lists.bestpractical.com, Chapter 8, or the RT Wiki at http://wiki.bestpractical.com.
At this point you should have a working RT instance. Restart your Apache, and test it out by pointing your web browser at whatever URL you’ve specified.
The default administrator user for RT is called root and the password is password. After you log in for the first time, you will want to change this by clicking on “Preferences” in the upper right hand corner.