Juliet Kemp shows you how to look after your bugs with Request Tracker, an enterprise-grade (and GPL'ed) ticketing system that can be used for project management, help desks, software development, and much more.
Managing bugs and help requests isn’t easy, but it’s crucial for effective project management. Using the wrong tool can set your project back to the dark ages, but the right tool can help your team excel. With that in mind, let’s look at Request Tracker, an enterprise-grade (and free software) ticketing system written in Perl.
A ticketing system is a piece of software in which every bug, request, or problem is entered as a’ ticket,’ which can then be tracked. It can be allocated to someone to fix, given a priority, placed in a queue (to separate out different types of bug or request), commented on, replied to, and finally closed when resolved. The system can also send progress updates and reminders to the initial requester and to other people involved with the ticket. RT handles all of these functions and more.
A ticketing system is of course particularly useful when more than one person is involved in a project (whether at work or out of it). It provides a centralized record of what has been done and what is still to do. However, even if you work alone, or are only working on your own needs and problems, a ticketing system can be helpful.
Whether you’re working on issues brought up by yourself or others, we all know how easy it is to lose track of problems or requests. Not to mention to forget how a particular issue was fixed, only to face the same problem again six months later, and have to restart from scratch or waste time hunting through email archives. RT can deal with both of these issues. In addition, it can automatically update others on your progress– useful in keeping them happy– and act as a record of your achievements.
Installation Tips for RT and Related Packages
Installation from source, if you prefer that, is covered on the wiki. Alternatively, RT is available as a package for most Linux systems. In Debian, the package is request-tracker3.4 or request-tracker3.6, and comes with a stack of Perl module packages. I’ll refer here to version 3.6 as from the Debian stable install.
One slight installation annoyance in the Debian package is that apache is a dependency — a nuisance if you already have apache2 installed. You can use your existing apache2 if you want. You will need to install libapache2-mod-perl2, and remove /etc/init.d/apache to avoid having
apache2 starting at boot.
/usr/share/doc/request-tracker3.6/NOTES.Debian.gz provides final installation instructions. This covers basic initial configuration edits, and setting up your database backend.
The install does not include a database requirement– it’s up to you to install and set up whichever database you prefer (or to use one that already exists). If you have a database running on another machine, you only need to install the database client package on your RT server. You’ll also need to specify the name of the host in RT_SiteConfig.pm as the setup scripts assume that the database is on localhost. Check RT_Config.pm for syntax (see below).
Similarly, in order for RT to send emails, you will need a working mail setup (a smarthost setup works fine). This is not covered by the install. Using email to create tickets on RT is covered later in this article.
Also not mentioned in the install docs: when you include the provided modperl2 file, if you are using Apache2, you will probably need to comment out this line:
The individual site configuration file is in /etc/request-tracker3.6/RT_SiteConfig.pm. The RT_Config.pm file in the same directory shows all the configuration options and their defaults. RT_SiteConfig.pm is where you put your own configuration changes and settings, as it overrides RT_Config.pm. This division makes your site configuration much easier to read, and to reproduce if need be.
The file as installed contains the values that you absolutely must edit, and then you can add other values as required. An example is shown below:
# THE BASICS:
Set($OwnerEmail , 'firstname.lastname@example.org');
Set($CorrespondAddress , 'email@example.com');
Set($CommentAddress , 'firstname.lastname@example.org');
Set($Timezone , 'Europe/London'); # obviously choose what suits you
Set($LogToSyslog , 'error');
Set($LogToFile , 'debug');
# THE DATABASE:
Set($DatabaseType, 'mysql'); # e.g. Pg or mysql
# These are the settings used when creating the RT database,
# You MUST set these to what you chose then.
Set($DatabaseUser , 'rtuser');
Set($DatabasePassword , 'rtpwd');
Set($DatabaseName , 'rtdb');
# THE WEBSERVER:
Set($WebPath , "/rt");
Set($WebBaseURL , "http://www.example.com");
Set($UseFriendlyFromLine , 1);
Set($FriendlyFromLineFormat , "\"IT Manager via RT\" <rt-owner\@example.com>");
Set($UseTransactionBatch , 1);
Most of these are self-explanatory.
CommentAddress set the default email addresses used in the From: and Reply-To: headers of (respectively) correspondence and comment emails sent by RT. You can override these at a queue level.
The FriendlyFromLine settings make RT use a nicer From header when sending out emails than the default,” SenderName via RT”.
Reload Apache, then go to the RT Web page that you have set in the example above. You should see the RT login screen.
Starting and setting up RT
As per the installation instructions, the first thing you do on logging in for the first time should be to change the root user password (the default is password). The menus on RT are along the top. Go to Configuration -> Users -> root, enter the new password, and click Save Changes. You may wish to make other changes (e.g. to the email address and name) at the same time.
Next, you can create a user account for yourself, or a test user account. Go to Configuration -> Users -> New User, and set the fields as appropriate. Be careful also to click the Give this user rights button, or your user will not be able to interact with tickets or queues at all. We’ll cover rights more in a bit. Click Save Changes, and that’s it.
To start, you have a single queue, called General. Now you can add a test ticket to it. The quick way to do this is via the Quick ticket creation box at the bottom of the Home page. A ticket created like this, however, won’t have any information other than the title.
For a more comprehensive ticket, there is a button at the top right of the screen called New ticket in (with a drop-down queue box next to it). Hit this and you will get up a full ticket creation screen. Create a new ticket using either of these methods, then return to the Home page to see your new ticket.
Adding and editing queues
It can be useful to have more than one queue: For example, Software and Hardware queues, or Bugs and Requests. To add a queue, go to Configuration -> Queues -> New Queue. Fill in as many of the boxes as you like, and click Save Changes and that’s it.
You might want to think for a moment before creating queues. Once you have created a queue, you can’t delete it. You can however disable it (by unchecking the “Enable queue” box) which means that it won’t be visible on the site.
Go to Configuration- Queues and then select either the General queue or your new queue. The lowest menu level now allows you to edit aspects of queue configuration. For example, if you want to override the default reply address and comment address at a per-queue level, you can do so here. The reply address sets the Reply-To header of ticket correspondence emails, and the comment address sets the Reply-To header of ticket comment emails.
The next part of queue configuration is to set up the watchers for this queue, the AdminCc group. This enables RT to send emails to the appropriate people when tickets are added to the queue, or when activity (comments, correspondence, or resolution) happens on a ticket.
You can add either a user, or a group. If you have a setup where there are several people watching a particular queue, or one person watching several queues, then the best option is to set up a group (e.g. Admin) and add that group as AdminCc.
This means that if your personnel change, or if you get a new member of staff or person working on the project, you only need make alterations in one place. As with coding, reuse your effort whenever possible!
So the first step here is the straightforward one of creating a Group. It follows a very similar process to adding a queue, using the Configuration -> Groups -> Add Group menu item. Once you’ve added the group, choose Select Group and click on your new group’s name. Add members under the Members menu item. Note that any members you add must already be known to RT.
Next, go to Configuration -> Queues -> Select queue General -> Watchers. Enter the name of the group that you’ve just created into the group search box; choose AdminCc from the drop-down box that appears, and click Save Changes. You’re done! Test this by creating another ticket. Emails should be sent to the members of your group.
RT enables you to create custom fields for tickets- for example, a” machine being used” field may be useful, or there may be other common aspects of problems that you can encourage people to specify by using a custom field.
These are created separately from either queues or global settings, via the Configuration -> Custom Fields menu. Choose New Custom Field, fill in the values you want, and click Submit. As you will see, you can make custom fields mandatory, or validate them in other ways. They can apply to tickets, users, or groups.
Next add this field to your new queue either via the Applies To option on the Custom Field itself; or by going back to the Queues menu item, selecting your queue, and then selecting Ticket Custom Fields. Click the box beside the field, and then hit Submit.
Similarly, you can go to the Global menu, and choose custom fields to apply across all queues or tickets. In general, anything you can do to one queue can be done to all queues at once, via the Global menus; and similarly with users and groups.
The RT rights system is a fundamental aspect of the way it works but can be a little confusing initially.
You can do various things to tickets, for example:
- CreateTicket: Create a ticket in a queue.
- ModifyTicket: Change a ticket.
- SeeQueue: Be able to see the queue at all.
- OwnTicket: Have a ticket allocated to you to fix.
- ShowTicketComments: See the comments on a ticket.
- TakeTicket: Allocate a ticket to yourself.
- ShowScrips: Look at the scrips (see below) that apply to a ticket.
And that’s just the beginning. The full list is available by looking at Queues -> Select Queue -> Group / User Rights.
Particularly important is that if a user doesn’t have ShowTicket rights, then even if they have created a particular ticket, they won’t be able to see it. Similarly, without ShowQueue rights, they cannot see the queues (and so see other tickets).
In a simple setup, the most straightforward option is to give all rights to the AdminCc group. This will mean that anyone watching the queue via this group (as per the setup above) will have full queue admin rights. Highlight all the rights next to the AdminCc group (under the Group Rights menu item), and click Save Changes.
After this you can decide which rights to give to All users. CreateTicket, ModifyTicket, ReplyToTicket, SeeQueue, ShowOutgoingEmail, and ShowTicket is a good basic set, but you can experiment and see what suits your setup best.
It is probably a good idea to distinguish between ShowTicket and ShowTicketComments — this enables your admin team to make comments that cannot be seen by users. Even though users won’t be able to see the comments, it’s not a good idea to be rude in the comments. It does mean that you can keep technical information in the comments to avoid confusing non-technical users or just to keep from bothering them with comments that aren’t relevant. You can also add references to other tickets which are related to the backend of your system, which are generally uninteresting to users.
Obviously, there is plenty of scope to increase the complexity and granularity of your rights setup. You can have as many groups as you like, and set up as many divisions of rights as you like.
User rights work in a similar way, and are administered via Configuration -> Groups -> Select Group -> Group Rights (to change the rights for all group members) or User Rights (to set rights for group members individually). You can also set various global rights under Configuration -> Global -> User Rights. Rights that can be given to users include SuperUser rights.
The rights system, although very powerful, is quite complicated. It will pay you to read through the lists of rights and experiment with them.
The final important part of RT is scrips. These are scripts (specifically, chunks of Perl) which run under certain conditions. It is the part of the system that enables one of the major features of RT: it can update all relevant parties by email.
RT has a collection of default scrips that apply to all queues — these can be found under Configuration -> Global -> Scrips (and also accessible from the Scrips menu item of individual queues). Looking at the default setup, you will see that these distinguish between Correspond and Comment. On Correspond, there are three scrips, to inform AdminCcs, Requester, Ccs, and Other Recipients (these are added when the reply to the ticket is written. On Comment, RT has only two scrips, emailing AdminCcs and Other Recipients.
These scrips can be modified, or deleted, by clicking on them. For example, you can alter the template used for the email, or alter the action. RT has a collection of pre-defined actions.
You can also create your own custom conditions and actions. You can do this by creating a new scrip, or by editing the existing default scrips. For example, you may want to forward new tickets to your mobile phone, but only on weekends (when you’re not checking your email). Or you may want to forward them only on weekdays when you’re being paid to do work! Basically, anything you can express in Perl, you can add as a scrip.
In this section, we’ll look at some additional configuration options for RT.
In addition to RT sending out emails to users, you can also set it up to accept tickets by email.
This uses the
rt-mailgate program. As per the documentation, edit /etc/aliases to include this line:
rt-email: "|/usr/bin/rt-mailgate --queue General --action correspond --url https://localhost/rt"
Next, make any necessary edits to your mailserver configuration to enable the use of pipe commands. For Exim, edit /etc/exim4/exim4.conf.template to include the following line (outside the
pipe_transport = address_pipe
exim4 for the change to take effect.
If you have any authorization set up for RT access (see below), you run into a problem here, which is that the mail server doesn’t have that authorization. For this reason, there are sections of RT which are identified as NoAuth — you should turn authorization off for those bits. The relevant section of your Apache2 config should look a bit like this:
Allow from all
Allow from all
# whatever auth you have in place - Kerberos for me.
To test all of this, create a file testfile and execute:
cat testfile |/usr/bin/rt-mailgate --queue General --action correspond --url https://localhost/rt
A ticket corresponding to the contents of testfile should show up on the RT Web site. Next, try sending an email to your rt-email address from the local command line. Run
mail-s"testing RT!" email@example.com then hit Ctrl-D. Again, the ticket should show up on the Web page, and your AdminCc group should receive the appropriate emails.
If you run your own mailserver, this is all you need, as the mailserver will handle external mail already. If not, the next step is to grab the mail from the server and deal with it correctly. You can use
fetchmail for this, with the following config in a file rt-fetchmail.conf:
poll imap.example.com protocol IMAP username rt-email password passwd smtpaddress example.com
mda '/usr/bin/rt-mailgate --queue General --action correspond --url https://localhost/rt'
In this example,
imap.example.com is whatever email server you use, and
example.com is whatever domain your email appears to come from.
To fetch the email using
fetchmail-f /path/to/rt-fetchmail.conf, which you should then put in an appropriate crontab, to run every minute or two.
To test, email rt-email from somewhere non-local, wait for the cronjob to run, and a new ticket should appear in RT.
Adding users automatically
If you have email submission of tickets set up, or if you have external Web authorization (see below), you can configure RT to add users automatically on receipt of email or on login. This obviously saves you time!
Add the following line to your RT_SiteConfig.pm file:
Set($WebExternalAuto , 1);
This causes RT to automatically create a user corresponding to that external authentication ID.
Apache Secure Setup
You will need to add configuration to your Apache2 config file if you wish to run RT as a secure or authorized setup, i.e. under HTTPS.
AddType text/html .shtml
AddOutputFilter INCLUDES .shtml
Options FollowSymLinks Includes
Options Indexes +Includes FollowSymLinks
AllowOverride FileInfo AuthConfig Options
Allow from all
If you’re running Kerberos single-sign-on, you can use Kerberos authentication to control access to the RT Web pages. Note that this doesn’t strictly form part of the single-sign-on process; your users will have to enter their passwords. But it does avoid the need to remember a separate password.
Add this section in the <VirtualHost*: 443> section of your Apache config:
AuthName "Request Tracker"
# Need to avoid kerberos auth for "noauth" areas of RT - these are the
# areas that run outgoing mail and other similar things.
Allow from all
Allow from all
You will also need to edit RT_SiteConfig.pm as described previously in the” Adding users automatically” section, and also add the line:
Set($WebExternalAuth , 1);
After that’s done, reload Apache. It is also possible to integrate with LDAP, in a similar way.
RT is a very powerful and extensible system, which is well worth the reasonably small effort of installing and setting up. You can have a basic functional system up and running very fast; but if you want something grander and more complicated, you can spend about as much time and effort as you choose customizing to your site’s requirements.