Request Tracker Installation Guide for Solaris 10

RT Installation

Use blastwave to install rt3 and it's dependencies

Using blastwave to install RT greatly simplifies installation due to the enormous amount of dependencies that RT requires. The main problem I have with this installation method is that blastwave's rt package depends on apache 1.3 and mysql 4.1. Which is annoying if you are already using apache 2 and mysql 5. Apache 1.3 is not actually required for RT. I have successfully setup my installation with Apache 2.2.

# pkg-get -i rt

Note: During the installation process, if you allow it to install apache 1.3, it will automatically start the service on port 80, which may conflict with any existing apache installation. If it does, promptly modify your /opt/csw/apache/conf/httpd.conf file to run your apache 1.3 server on a different port and restart the apache 1.3 server (/etc/init.d/cswapache restart)

Configure Apache http.conf

Apache 1.3

Edit apache's /opt/csw/apache/etc/http.conf. NOTE: The following settings will setup RT in the web root directory. Slight modifications will be necessary if you want to install under some subdomain or subdirectory (i.e. http://rt.yourserver.com or http://www.yourserver.com/rt). In my Apache 2.X instructions, I show how to install in a sub directory.

LoadModule perl_module        libexec/libperl.so

DocumentRoot "/opt/csw/rt3/share/html"

<VirtualHost 12.34.56.78>
    ServerName yourserver.yourdomain
    DocumentRoot /opt/csw/rt3/share/html
    AddDefaultCharset UTF-8

    PerlModule Apache::DBI
    PerlRequire /opt/csw/rt3/bin/webmux.pl

    <Location />
     SetHandler perl-script
     PerlHandler RT::Mason
    </Location>
</VirtualHost>

Note: Somehow blastwave's apache 1.3 postinstall script was not able to edit my httpd.conf file, so it was necessary for me to add the following lines manually to enable mod_perl:

# Added by CSWmodperl
<IfModule mod_perl.c>
  PerlModule Apache::Registry
  Alias /perl/ /opt/csw/apache/perl/
  <Location />
    SetHandler perl-script
    PerlHandler Apache::Registry
    PerlSendHeader On
    Options +ExecCGI
  </Location>
</IfModule>

Apache 2.0

If you installed the ap2_modperl blastwave package, it should have added the following line to the end of your /opt/csw/apache2/etc/httpd.conf file. Make sure it is there:

Include etc/extra/httpd-perl.conf

Modify the /opt/csw/apache2/etc/extra/httpd-perl.conf and remove mod_perl's taint option by commenting out the following line. RT cannot be run in taint mode.

    #PerlSwitches -wT

Edit your /opt/csw/apache2/etc/extra/httpd-vhosts.conf file and add the following entry. These settings will put RT in the sub directory: "rt/" on your webserver:

<VirtualHost *:80>
    ServerName gtee.sfbay.sun.com
    Alias /rt "/opt/csw/rt3/share/html"
    AddDefaultCharset UTF-8

    PerlModule Apache::DBI
    PerlRequire /opt/csw/rt3/bin/webmux.pl

    <Location /rt>
        SetHandler perl-script
        PerlHandler RT::Mason
    </Location>
</VirtualHost>

Install Perl CPAN DBI module

NOTE: I am not completely sure that this step is necessary, since blastwave's rt should have already installed the Perl Apache::DBI mdule.

# perl -MCPAN -e'install Apache::DBI'

Initialize and start MySQL database

# /opt/csw/mysql4/share/mysql/quick_start-csw
# svcadm enable cswmysql4

Setup RT database

# /opt/csw/rt3/sbin/rt-setup-database --action init

Set permissions of the rt3/var directory to the same owner as apache

# touch /opt/csw/rt3/var/log/rt.log
# chown -R nobody:nobody /opt/csw/rt3/var/*

Configure your RT_SiteConfig.pm

Now you need to customize your /opt/csw/rt3/etc/RT_SiteConfig.pm. Any option you specify in RT_SiteConfig.pm will override the default values in RT_Config.pm. You should never modify RT_Config.pm. Always use RT_SiteConfig.pm to customize your RT installation. You will probably need to change the following options:

# This will appear in the e-mail subject in brackets with the ticket number. For example: [example.com-support #1234]
Set($rtname , "example.com-support");
Set($Organization , "example.com");
# Define this if you want to run RT in a subdirectory
Set($WebPath , "/rt");
Set($WebBaseURL , "http://www.example.com");
Set($Timezone , 'US/Pacific');

On Solaris, it is necessary to add the following line to your /opt/csw/rt3/etc/RT_SiteConfig.pm:

@LogToSyslogConf = ( socket => 'inet' ) unless (@LogToSyslogConf);

Restart Apache and test the web interface.

If everything goes well, you should be able to login as "root" with the password "password".

Edit /var/mail/aliases with aliases for Request Tracker

Next you need to configure RT to accept e-mail and rout it to RT's mail handler. Add the following lines to /var/mail/aliases

# Aliases for Request Tracker (RT)
rt:         "|/opt/csw/rt3/bin/rt-mailgate --queue general --action correspond --url http://www.example.com"
rt-comment: "|/opt/csw/rt3/bin/rt-mailgate --queue general --action comment --url http://www.example.com"

Then run newaliases for the new aliases to go into effect:

# /usr/sbin/newaliases

Allow Everyone group to create tickets

In order to allow anyone to e-mail your RT support and create a new ticket, you need to give permissions to the "Everyone" group. Login to RT via the web interface as root/password and modify: Menu->Configuration->Global->Group Rights such that the "Everyone" group can create tickets. This will allow anyone who e-mails RT to create a new user/ticket.

Configure RT with LDAP support

Install Perl Net::LDAP CPAN module:

# pkg-get -i pm_ldap

NOTE: Actually I have never checked if the above step works, since in my installation I performed it manually in CPAN:

# /opt/csw/bin/cpan
cpan> install Net::LDAP

Copy the User_Local.pm file from http://wiki.bestpractical.com/index.cgi?LdapUserLocalOverlay. Place it to your /opt/csw/rt3/local/lib/RT/ directory. Finally set the permissions with executable permission and owned by root.

# chmod +x /opt/csw/rt3/local/lib/RT/User_Local.pm
# chown root:bin /opt/csw/rt3/local/lib/RT/User_Local.pm

Now you need to edit your /opt/csw/rt3/etc/RT_SiteConfig.pm to enable LDAP support and customize it to your own company's settings. First copy the The LDAP configuration options from http://wiki.bestpractical.com/index.cgi?LdapSiteConfigSettings to your RT_SiteConfig.pm. Then customize it for your site. You will need to configure $LdapAttrMap, $LdapRTAttrMatchList, $LdapEmailAttrMatchList, $LdapServer, $LdapBase settings to work with your LDAP server.

Now you will probably want to autocreate RT users with LDAP information on the fly, whenever a new user logs in. This will allow RT to create a new user as people login, rather than having to manually create user accounts. To do this, you need add the Auth file from http://wiki.bestpractical.com/index.cgi?LdapAutocreateAuthCallback. Place this file in:

/opt/csw/rt3/local/html/Callbacks/LDAP/autohandler/Auth

That should be it. To test it, clear the Mason cache and restart the webserver:

# rm -rf /opt/csw/rt3/var/mason_data/obj/*
# /etc/init.d/cswapache restart

Install RT-Extension-CommandByMail

This extension allows you to change various attributes of the ticket by fields in the e-mail. The extension is available here: http://search.cpan.org/~jesse/RT-Extension-CommandByMail-0.05/lib/RT/Extension/CommandByMail.pm

Download and extract RT-Extension-CommandByMail-0.05.tar.gz to a temporary directory.

# cd /tmp
# gunzip RT-Extension-CommandByMail-0.05.tar.gz
# tar -xf RT-Extension-CommandByMail-0.05.tar
# cd RT-Extension-CommandByMail-0.05
# /opt/csw/bin/perl Makefile.PL
# make
# make install
# cd /opt/csw/rt3
# patch -p 0 -i /opt/csw/rt3/RT-Extension-CommandByMail-0.05/patch/command_by_email-0.1-RT-3.4.5.patch lib/RT/Interface/Email.pm

You may notice that the patch command differs than in the CommandByMail^? INSTALL instructions. This is because those instructions only work for the Linux patch command. The above command works for Solaris.

Finally, to enable the extension, add the following line to your RT_SiteConfig.pm:

# Enable the RT-Extension-CommandByMail-0.05 extension
@MailPlugins = qw(Auth::MailFrom Filter::TakeAction);

Troubleshooting

Check apache's error logs:

# tail -f /opt/csw/apache/logs/error_log

Username ($self->Name) will be empty when attempting to login with a numeric username.

I encountered this error when trying to setup LDAP authentication with a numeric employee id. It seems that RT does not allow for numeric usernames without some kind of modification to it's code (http://lists.fsck.com/pipermail/rt-users/2005-February/028706.html). Another option is to use a different LDAP unique key to authenticate against, such as a UNIX username.

Enable logging to rt.log

Add these lines to your RT_SiteConfig.pm:

# Enable logging to /opt/csw/rt/var/log/rt.log
# the minimum level error that will be logged to the specific device.
# levels from lowest to highest:
#  debug info notice warning error critical alert emergency
Set($LogToFile      , 'debug');

In the web interface, after attempting to login i get this error: No connection to syslog

no connection to syslog available at /opt/machine/perl/lib/site_perl/5.8.2/Log/Dispatch/Syslog.pm line 77

Make sure you added the @LogToSyslogConf option to your RT_SiteConfig.pm

Sending mail to rt@example.com does not create a ticket (Ticket creation failed)

Check your dmesg. If you see messages like the following:

Nov  9 01:49:24 localhost RT: RT could not load a valid user, and RT's configuration does not allow for the creation of a new user for this email (email@example.com).\n\nYou might need to grant 'Everyone' the right 'CreateTicket' for the queue general. (/opt/csw/rt3/lib/RT/Interface/Email.pm:639)
Nov  9 01:49:25 localhost RT: RT could not load a valid user, and RT's configuration does not allow for the creation of a new user for your email. (/opt/csw/rt3/lib/RT/Interface/Email.pm:652)

Then you need to configure the queue so so that everyone can create a new ticket. Menu->Configuration->Global->Group Rights

LDAP seems to be working but it can't autocreate the user

In the rt.log you may see:

[Fri Nov 10 19:27:46 2006] [info]: RT::User::LookupExternalUserInfo : ou=people,dc=example,dc=com mail=John.Smith@example.com =>  EmailAddress: John.Smith@example, Name: jsmith, RealName: John Smith (/opt/csw/rt3/local/lib/RT/User_Local.pm:573)
[Fri Nov 10 19:27:46 2006] [debug]: FOUND OK (/opt/csw/rt3/local/lib/RT/User_Local.pm:345)
[Fri Nov 10 19:27:46 2006] [info]: RT::User::CanonicalizeEmailAddress John.Smith@example.com =>  John.Smith@example.com (/opt/csw/rt3/local/lib/RT/User_Local.pm:355)
[Fri Nov 10 19:27:46 2006] [warning]: Use of uninitialized value in numeric ne (!=) at /opt/csw/rt3/lib/RT/User_Overlay.pm line 653. (/opt/csw/rt3/lib/RT.pm:287)
[Fri Nov 10 19:27:46 2006] [info]: Autocreated authenticated user jsmith () (/opt/csw/rt3/local/html/Callbacks/LDAP/autohandler/Auth:27)
[Fri Nov 10 19:27:46 2006] [error]: FAILED LOGIN for jsmith from 129.145.133.76 (/opt/csw/rt3/share/html/autohandler:191)

Notice in the line: Autocreated authenticated user jsmith () that the parenthesis is empty. This means that RT was unable to insert the user into the database and get an user_id. This could be for several reasons, but in my case, it was unable to create the user because there was already an existing user with the same e-mail address (from when I originally e-mailed rt@example.com). To fix this, you can modify the existing user's e-mail address, delete the existing user, or simply re-initialize the database.

Apache won't start: Insecure dependency in unlink

If you see the following messages in your /opt/csw/apache2/var/log/error_log

[Thu Nov 16 17:08:04 2006] [error] Insecure dependency in unlink while running with -T switch at /opt/csw/share/perl/5.8.8/File/Path.pm line 267.\nCompilation failed in require at (eval 5) line 1.\n
[Thu Nov 16 17:08:04 2006] [error] Can't load Perl file: /opt/csw/rt3/bin/webmux.pl for server example.com:0, exiting...

The solution to this is to turn of "taint" in Perl by commenting out the "PerlSwitches -wT" option in your httpd-perl.conf.

• http://lists.fsck.com/pipermail/rt-users/2006-January/036525.html

client denied by server configuration

In your /opt/csw/apache2/var/log/error_log you see:

[Thu Nov 16 17:36:04 2006] [error] [client 129.145.133.76] client denied by server configuration: /opt/csw/rt3/share/html

Add the following to your VirtualHost^? entry for RT.

  <Directory /opt/csw/rt3/share/html>
    Options FollowSymLinks
    Order allow,deny
    allow from all
  </Directory>

RT stops receiving tickets after switching to SSL

If you see "Deferred: prog mailer (/bin/sh) exited with EX_TEMPFAIL" in your /var/log/syslog:

Nov 17 14:38:31 vmsge sendmail[14703]: [ID 801593 mail.info] kAHMcUF2014703: from=<john.smith@example.com>, size=1379, class=0, nrcpts=1, msgid=<455E399E.7060807@Sun.COM>, proto=ESMTP, daemon=MTA-v4, relay=sfbaymail2sca [129.145.155.42]
Nov 17 14:38:31 vmsge sendmail[14704]: [ID 801593 mail.info] kAHMcUF2014703: to="|/opt/csw/rt3/bin/rt-mailgate --queue gtee-support --action correspond --url https://www.example.com", ctladdr=<support@example.com> (1/0), delay=00:00:01, xdelay=00:00:00, mailer=prog, pri=31609, dsn=4.0.0, stat=Deferred: prog mailer (/bin/sh) exited with EX_TEMPFAIL

A required Perl module Crypt::SSLeay may not be installed. Try the following:

$ export RTUSER=root
$ export RTSERVER=https://www.example.com
$ alias rt=/opt/csw/rt3/bin/rt
$ /opt/csw/rt3/bin/rt show ticket/1
Password:
rt: Server error: Protocol scheme 'https' is not supported (Crypt::SSLeay not installed) (501)

If you see that Crypt::SSLeay is not installed, install it via blastwave:

# pkg-get -i pm_cryptssleay

NOTE: I had trouble installing it via CPAN, until I realized Crypt::SSLeay was in blastwave packages:

# /opt/csw/bin/cpan
cpan> install Crypt::SSLeay
...
...
...
/usr/ucb/cc:  language optional software package not installed
*** Error code 1
make: Fatal error: Command failed for target `SSLeay.o'
 /usr/ccs/bin/make  -- NOT OK
Running make test
 Can't test without successful make
Running make install
 make had returned bad status, install seems impossible 

On Solaris, the "language optional software package not installed" message means that make could not find a suitable c compiler.

• http://everythingsolaris.org/articles/iaug/frameset.html

References

• http://wiki.bestpractical.com/index.cgi/RPMInstall/Search/%5C%22$RT::WebPath/Ticket/index.cgi?TroubleShooting

-- JesseSuen - 07 Nov 2006