Article
Figure 1
Figure 2
Figure 3
Figure 4
Figure 5
Figure 6
Figure 7
Figure 8

aug2004.tar

Trouble Ticketing Using Request Tracker 3

Greg Williamson

Request Tracker (RT) is an open source, enterprise-grade, trouble-ticketing tool from Best Practical Solutions LLC. It is commonly used for helpdesks but is able to go beyond that. Customized versions are available for incident management and FAQ management in RTIR and RTFM, respectively. In this article, I will cover the installation and configuration of RT3 on a Debian Sarge (mixed stable/testing) system.

The installation described here utilizes RT3 to provide a mechanism for a team of administrators to schedule work and record output from Nagios (see "Advanced Configuration of Nagios", Sys Admin, October 2003: http://www.samag.com/documents/s=8920/sam0311i/). The members of this team are not generally in the same office at the same time, making some type of trouble-ticketing tool essential. As this is a small team, the server is a low-end Pentium II-350MHz with 160MB of RAM. This server is also running Nagios to monitor a number of other hosts, and the MySQL database which provides the backend to both RT and Nagios. For a larger team, splitting the services or a faster machine may be required, but the requirements of RT are not high.

Installation

Installation HOWTOs are found at:

http://wiki.bestpractical.com/index.cgi?InstallationGuides

These cover Solaris and Fedora from source, and Debian, FreeBSD, Microsoft Windows, and Red Hat from packages.

If installing from source, the first step is to obtain the software. The latest source tarball can be downloaded from:

http://download.bestpractical.com/pub/rt/release/rt.tar.gz

The documentation included in that tarball includes the full list of prerequisites. Briefly, these include a database backend (MySQL recommended), a number of Perl modules, and a Web server. If using Apache, version 1.3 is recommended due to stability concerns about mod_perl 2.0. FastCGI is the suggested alternative for sites that would prefer to run Apache 2.0. Instructions for a source install are covered in the RT manual, which is available at:

http://www.bestpractical.com/rt/docs.html

On Debian, installation is as simple as:

# apt-get install request-tracker3 rt3-clients

if a suitable database is installed. If not, first install either MySQL server or PostgreSQL server. Accept the list of prerequisites and wait for the installation to complete.

Before RT can be used, a number of steps must be completed. First, edit /etc/request-tracker3/RT_SiteConfig.pm. Set sensible values for the variables contained in the file. The config file is in fact a Perl module, and as such needs the 1; at the end.

Second, create the database user. For MySQL, su to the mysql user, run mysqladmin and issue:

GRANT ALL PRIVILEGES ON rtdb.* TO rtuser@localhost \
  IDENTIFIED BY '<password>';

where <password> matches that set in /etc/request-tracker3/RT_SiteConfig.pm.

Next, run the rt-setup-database script as follows:

klinzai:~#  /usr/sbin/rt-setup-database --action init \
  --dba rtuser --prompt-for-dba-password

To create a new database and grant RT access to that database, this script must connect to your MySQL instance on localhost as rtuser. Please specify that user's database password below. If the user has no database password, just press return.

Password: <password>
Now creating a database for RT.
Creating mysql database rtdb.
Now populating database schema.
Creating database schema.
schema successfully inserted
Now inserting database ACLs
Now inserting RT core system objects
Checking for existing system user \
  (RT::CurrentUser=HASH(0x8f13b74))...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.

If there is a configuration error with the database, the script will fail. With luck, the output will be detailed enough to pinpoint the problem. Once that problem is resolved, drop the database and re-create using the steps above.

Apache Integration

The Debian package includes a module file that can be simply added into the virtual host section from which RT should be served. This is in /etc/request-tracker3/apache-modperl.conf. The file contains the following directives:

Alias /rt /usr/share/request-tracker3/html/

PerlModule Apache::DBI
PerlFreshRestart Off

<Directory /usr/share/request-tracker3/html/>
   AddDefaultCharset UTF-8
   PerlRequire /usr/share/request-tracker3/libexec/webmux.pl
   SetHandler perl-script
   PerlHandler RT::Mason
</Directory>

This aliases /rt to serve RT and includes the required hooks into Perl::Mason. The main Apache configuration also needs to be modified to ensure that either mod_perl or FastCGI is loaded. Once this is done, reload Apache and visit the URL. The screen should display the contents of Figure 1.

At this point, log in as root with the password "password". Click on the "Preferences" link, and set a better password.

Client Configuration


#  vi /etc/request-tracker3/rt.conf

Update this file with the correct server URL. The default is "http://localhost/rt". This is the address that the rt command-line utility will use.

Mail Integration

In a distributed environment, the email interface is likely to see a lot more use than the command line. The RT client package can be installed on any host, but email is likely to prove more popular and is certainly simple for end users. To enable the email interface, add the following to the system alias file:

rt:         "|/usr/bin/rt-mailgate --queue General --action \
             correspond --url <url>"
rt-comment: "|/usr/bin/rt-mailgate --queue General --action \
             comment --url <url>"

and run newaliases (or postalias or whatever makes the mail system recognize that this file has been changed). The <url> must be replaced with the URL of the system. This will route mail sent to rt into the RT system. RT allows information to be recorded on a private ticket. This information is called a "comment" and will not be displayed to a normal user. Unlike general status updates, comments will not be emailed to the requestor.

Configuration

RT has its own user and group configuration. This allows users to access your trouble ticketing system without requiring any Unix knowledge or even an account. The downside is a secondary set of credentials to maintain.

As with normal security practices, each user should have her own account. Configuration of users and groups is accomplished through the Web interface. Group membership should be used to simplify administration of your users and is not limited to users alone. Groups can be members of other groups, allowing a hierarchical structure.

To create a new user, click on the "Configuration" link, then "Users". RT defines two general kinds of users -- those with rights (staff), and those without (non-staff). Staff accounts generally have the ability to log into the system, assign tickets, resolve tickets, and update tickets. Creation of a staff account requires that the "Let this user be granted rights" checkbox be selected. A sample screenshot is in Figure 2.

RT will create non-staff accounts whenever a request is received from a new email address. Non-staff accounts are generally not granted any rights into the system except as a by-product of other roles. In simple terms, this means non-staff users can monitor tickets they have requested. The users must be given a password before they can access the Web interface, but once that's done they will be able to log in and see a screen similar to Figure 3.

Once appropriate groups and users are created, it is worthwhile to create queues. By default, there is only the "General" queue. Although this may be enough for a very small site, we use this to differentiate between user-initiated requests and system-generated problems. This has been further broken down to reflect monitored services located in our main site and those at remote sites. Our environment will be monitored using Nagios and, whenever a Nagios event is detected, an email notification will be sent to RT to the Nagios queue.

In a more general environment, an individual queue could be created for different teams. A ticket can be transferred between queues, so a complicated issue could be handed between teams using RT. To enable the mail interface for this new queue, an alias must be added to the system aliases file. The name of the new queue should replace "General" as the --queue parameter. This can also be used in a public relations exercise, where each remote customer can be given a dedicated queue to which to submit requests. Internally, these could all be the same queue, or a number of different queues. The queue creation screen is shown in Figure 4.

After a queue has been created (and indeed for the General queue), users must be granted rights. Rights can be granted on a global basis but will more commonly be granted per queue. Before users can productively work on a ticket, they must have been granted rights such as "Show Ticket", "Show Ticket Comments", "Watch", "Watch As Admin Cc", "Own Ticket" and "Modify Ticket." Most of these rights are self-explanatory. The "Watch As Admin Cc" right allows users to add themselves to the list of people to be notified when work is performed on a ticket.

To allow an arbitrary remote user to create a ticket in a queue via email, the system group "Everyone" needs to be granted the rights "See Queue", "Create Ticket", "Reply To Ticket", and "Comment On Ticket" for that queue. To allow non-staff requestors the right to see their tickets, the system role "Requestor" should be granted the right "Show Ticket". Right assignment is performed using the Web interface. Multiple selections can be performed using the CTRL key. Remember that a user will have all of the rights available to them in any group of which they are a member. Thus, rights granted to "Everyone" do not need to be re-granted to a user or group individually.

RT comes with a number of default actions to take in response to user interaction. This takes the form of email to the requestor, the queue administrators, and any other interested parties. This is controlled using "scrips" (which are a way of telling RT to trigger certain actions based on when something happens). The scrips in turn make use of templates and fill in those templates with data from the record. The data used includes the ticket number and a string used by RT to process any email responses. It can also include information such as the name of the staff member who has been assigned to work on the ticket, any public information on the ticket, and the status of the request.

Comments attached to the ticket are not sent out, but replies are. This keeps the user informed of the status of the request without extra administrative effort, thereby reducing the load on the helpdesk staff and keeping the customer "in the loop". The comment function allows helpdesk staff to record information about an issue that the customer may not need to receive. The default scrips are probably suitable for most sites, although you may wish to modify them to use site-specific details, such as escalation paths, SLA indications, or just the company or department name.

In a more complicated environment, you may wish to create new scrips to advise requestors that a ticket has been passed between queues. Templates and scrips can be created on a per queue or global basis. This could be used to present different corporate images to different customers, allowing a consulting company to present tailored messages to different customers. Generally, global templates and scrips will be more useful. Figure 5 contains a screenshot of the default template used when a ticket is created.

Usage

Once the system is configured, you can actually start to use it. Staff will generally interact using the Web interface. The default screen displayed when a user logs into RT is shown in Figure 6. From the top menu, a new ticket can be created; from the side menu, you can search for an existing ticket or alter a system setting. A new ticket could be created in response to a non-email-based request, such from a user whose computer is completely down or who is having problems with email.

Each queue can be easily searched by clicking on the queue name on the right-hand side. This page can be set to automatically refresh at a variety of increments between 2 minutes and 2 hours, or only by the browser. For a more complicated search, potentially across queues or for requests with similar subjects or requestors, the search function allows more specific searches to be performed. A search can also be built incrementally, and each search bookmarked. Search criteria can also be deleted if required.

Non-staff will tend to use the email interface to enter a request. This is as simple as advertising the new address for helpdesk requests and waiting for requests to roll in. Each new requestor will have an account created, but most will not need to have a password created. The queue configuration screens have the option to define queue-wide "Watchers." This is a list of people to be advised when updates are made to tickets in that queue or when new tickets are created. If the request volume is low, this may be the best way to advise administrative staff that a new ticket has been created. If the volume of requests is high enough to warrant dedicated queue monitor staff, this may not be necessary -- instead, the automatically refreshing screen can be used.

Once a ticket has been created, it can be in one of six states. An ideal ticket will move from "new" to "open" and then "resolved". Of the other states, "stalled" means that it is waiting on something outside the helpdesk's control; "rejected" means that the ticket will not be worked on by the helpdesk team but is worth archiving for some other reason; and "deleted" is used for tickets that should never have been created in the first place, such as misdirected mail, spam, etc. A screenshot of an open ticket is in Figure 7.

As staff work on tickets, the ticket history is updated. Any transfer of ownership or queue change can be advised to the requestor and any other interested party. Tickets can be updated en masse or individually. Tickets can also be linked to each other, allowing the establishment of hierarchies, either in a true dependency relationship or just as a cross-reference. Tickets can also be linked in a parent/child relationship, allowing a single large request to be broken down into sub-parts. This can help maintain the flow of progress reports and aid in planning and resource management.

The command-line interface is the final method for interaction with RT. The current Debian package (version 3.0.10-2) has a bug, whereby the rt utility crashes. This can be bypassed with the creation of a file called .rtrc in the user's home directory. The command-line utility is designed for integration with automated tools or batch processes and is unlikely to be used by end users.

Extensions

RT has a number of extension modules, both from the original author and the wider community. RT FAQ Manager integrates with RT, allowing helpdesk staff to simply click and send common replies to users. Users can also search the knowledge base themselves, reducing the workload on helpdesks even further. Tickets in RT can be cross-referenced with answers in RTFM. It also allows helpdesk staff to access a central repository for shared knowledge, without introducing another environment.

RT Statistics is a reporting suite to extract graphs and trends from an RT database. Installation is as simple; download the latest source tarball from:

ftp://anonftp.mqsoftware.com/kfh/RT/

and extract it into the RT3 directory. On Debian, this is /usr/local/share/request-tracker3. Basic statistics are available in a numeric form in a table. Graphs require the installation of GD, GD::Graph, and GD::Textutil.

Once these packages are installed, a simple refresh of the page will produce the graphs. A sample screenshot can be seen in Figure 8. As with the base RT, the statistics can be grouped by a number of criteria, including status and queue, and can be over a variable time interval. The statistics package itself is undergoing continued development and has a wishlist if a required metric is not already provided.

As with many active open source projects, the main Web site has a section for community contributions. This is found at:

http://wiki.bestpractical.com/index.cgi?Contributions

Conclusion

RT can be used to streamline helpdesk requests. It is simple to use, relatively low in terms of server resources, and requires end users in particular to change very little about the way they interact with their support teams. At the same time, it is a powerful tool that allows management to track problem resolution and to keep a history of user requests. With its extensions, it can also be used to provide an organizational knowledge base. With low server requirements, it can be easily installed and evaluated even without customization.

Greg Williamson has a Bachelor's degree in Applied Science (Computer Science) from RMIT in Melbourne, Australia, GSEC and RHCE. When not working his day job as a systems administrator for a financial services company, he provides consultancy to another small computer consulting firm. When not doing either of these things, he can be found with his wife and four children hoping one day to complain about "too much life" in his work/life balance. He can be reached at: greg@saintly.com.au.