#How I Got Request Tracker to Work
September 6, 2016
#How I Got Request Tracker to Work
#Intro Are you new to Linux but need to get Request Tracker running? Not great with the command line, but you can get around? Completely lost by all the different articles online about Request Tracker and not sure where to start? I was too, so I thought I’d put together this post that details what I did and which webpages I found useful.
I’m running the most current version of Debian 8 as of September 2016 and using the pre-built RT package (4.2.8 as of right now). I use MySQL as the backend, and Gmail as my email provider. I run Nginx, not Apache, as my preferred web server.
Finally, a disclaimer. I make no guarantees at all about how well this will work for you. Further, I make no promises about this setup’s security. It’s very likely that I’m running things under Debian users I shouldn’t be, or haven’t secured this or that properly. All I’m trying to do is show you how to get RT up and running with a database backend, a server that serves it correctly, and integration with email. The security, longevity, and other aspects are up to you.
#Installing Packages First, since I like MySQL, we’ll need to grab that:
apt-get install mysql-client mysql-server
Run through the MySQL configuration as directed, setting a good root password. RT will make its own user account and database, but it will ask you for the root password, so be sure you know it.
Next, you’ll need Nginx if you don’t already have it:
apt-get install nginx
There’s really no configuration to speak of here, at least not yet. Start it, just to be sure it’s running, and make sure you can see a webpage when you navigate to your server in a browser.
Now the fun part: Request Tracker.
apt-get install request-tracker4 rt4-db-mysql rt4-fcgi
It is very important that you install rt4-db-mysql at the same time. If you don’t, you’ll only get the default rt4-db-sqlite, and you won’t be able to switch over to MySQL later on.
The RT configuration will ask you for the settings RT needs–name, database type, and so on. Go through that configuration. Don’t worry if you miss something; you can adjust settings later. Once you’re done with that, you should have everything you need to get started.
#RT Configuration All settings, at least on Debian, are stored in /etc/request-tracker4/RT_SiteConfig.d/. There are a few files, each starting with two numbers. One for general configuration, one for database settings, and so on. You always modify these, never the main RT_SiteConfig.pm file in the folder above this settings folder. Instead, you change these files, then run
to apply them. This command replaces the pm file. Note, however, that it will not actually apply the changes to the user-facing UI. For that, you must stop and start the RT server, be that Apache, the stand-alone server, or FCGI (if you’re using Nginx or another fast CGI server).
##Serving RT with Nginx I use Nginx as my web server. RT will work with it, but you need to use FCGI to have the two talk. Install rt4-fcgi on your system to make this easier, if you didn’t earlier; it will install spawn-fcgi on its own.
If you’re pounding your keyboard, yelling at me to explain what FCGI (Fast CGI) is, sorry, I’m not going to. I don’t fully know the answer myself, but I do know that for our purposes, the answer doesn’t matter. Just think of FCGI as the language, and RT’s FCGI server as the translator between RT and Nginx. Both programs can speak FCGI, so the FCGI server sits between them, letting them talk to each other. Why do they both need a translator if they speak the same language? Because I’m bad at analogies, that’s why. Just go with it.
###Creating the Nginx File for RT I won’t go into great detail about Nginx here, as it’s pretty simple to use (which is one reason I like it over Apache). In brief, though, you’ll create a file in /etc/nginx/sites-available. Call it something meaningful, like rt.mysite.com or simply rt, if you only ever serve one domain on this server. Below I’ll explain what to put in this file. Once the file is ready, enable it by linking it over to sites-enabled. The trick here is to use full paths in the linking command, even if you’re already in the right location. Failing to specify full paths will cause problems.
ln -s /etc/nginx/sites-available/my_rt_file /etc/nginx/sites-enabled
Again, please use full paths in the ln command as in the example above, or you won’t have a good day. Don’t forget to restart Nginx so it sees the new file:
###RT-Specific Nginx Settings In the Nginx RT file, add all the fastcgi_params and other settings detailed in the “Nginx” section of this section of the RT docs.
The important thing here is the fastcgi_pass line; use a port you’ll remember, because you’ll need it in a minute. You could try to use Unix sockets here instead of 127.0.0.1:xxxx, but I’ve never had good luck with them and have never tried them with RT. Also note that, at least for me, the path to RT’s html files is different from what the docs say. I use /usr/share/request-tracker4/html and that seems to work.
###Connecting RT and Nginx Before you continue, you must add the port you chose to RT. Edit /etc/request-tracker4/RT_SiteConfig.d/50-debconfig, and add:
Set($WebPort , 9000);
This will make sure RT knows how to link to itself. If you don’t do this, you’ll get an error about the request never completing in Firefox, no response at all in Internet Explorer, and–no doubt–similar reactions in other browsers. Note that 9000 is just a random example; pick a port you’ll know, and remember it, as you’ll need it a couple more times. It needs to be the same one in your RT file for Nginx, the one after 127.0.0.1.
Now that you have the site set up–and presumably enabled–you can start the FCGI server that will let Nginx and RT talk. To do this:
spawn-fcgi -u www-data -g www-data -a 127.0.0.1 -p 9000 /usr/share/request-tracker4/libexec/rt-server.fcgi
Note the path, as it differes on the two Debian servers I’ve done this on from what the docs say it will be. Also notice the port; it should match the number you put in the Nginx config file for your RT site, and the port you used for the $WebPort variable. Finally, remember that PID, too, because you’ll need to stop it if you need to apply configuration changes to RT. rt4-fcgi should help here, but I have no idea how to use it. If you forget the PID, just run
netstat -antp | grep LIST | grep 9000
where 9000 is the port you chose. That should show you the PID.
After all this, RT should be running. If it’s not displaying at all, did you restart Nginx to apply the changes to your RT site? Was the spawn-fcgi command successful? Is it still running (use that netstat command to check that the server is still up)? Check your Nginx logs, wherever you told RT to log to in its Nginx file, to see if there are problems. Double check your RT configuration files, to make sure you have the URL, port, and other details set up right.
#Mail Configuration Now that RT is running, it’s time to incorporate email. After all, a web-only ticket system won’t get used nearly as much as one users can interact with via email, not to mention the ticket reminder emails that form the core of the user-facing part of any good ticket system. I’ll be using Gmail, since that’s what we use at work. I don’t know about other mail systems, but the process should be similar for most of them. You’re essentially adding two components: a way for RT to send out emails (postfix relaying to Gmail, in my case) and a way for RT to grab incoming emails (fetchmail). Don’t forget to set your Gmail account to allow IMAP access before you start!
##Sending First, install postfix (selecting “internet” during the initial setup), then follow this tutorial. Ignore the SSL certificates section. At least, I did, and things work fine here. To get Gmail working with postfix, follow this tutorial. Again, ignore the certificate stuff.
RT should now be sending emails as it needs to. Test this by making a user in RT with an email address you can access, then making a new ticket on behalf of the new user. If all goes well, the user will get an email about the ticket. Remember to watch your mail log as you do this.
##Receiving Next, we have to get RT to receive mail. For this, we use fetchmail; install it, create the file /etc/fetchmailrc (yep, one word, the ‘rc’ isn’t an extension) and follow this tutorial. For the user after the email address in fetchmailrc, use www-data, to match the user under which Nginx and the FCGI process run. Of course, if you’ve run them under another user, use that one instead.
Run the test command in the tutorial and be sure it works. However, that’s just to check you’ve set things up correctly–it won’t yet talk to RT for you. To do that, you must make another fetchmailrc file, preferably stored in the RT folder /etc/request-tracker4/fetchmailrc. In it will be all the email addresses, passwords, queue names, and so on. Here’s a tutorial that explains things in detail. See ‘option two’ under the ‘receiving mail’ section. As mentioned before, I don’t find the SSL certificates part to be necessary.
#RT Administration There are two great wikis on this topic, one for using RT’s web interface, and the other for manual RT administration. Below, I’ll highlight the concepts that helped me most as I started configuring the RT instance for my work.
##Queues A queue is simply a collection of related tickets. I made one queue for each department at work–IT, graphics, sales, etc. The important thing to remember about queues is, as detailed in the next section, that you never add users to queues. Instead, you add groups to queues, and the rights those groups are granted apply to the users in the group for that queue.
For example, if you make an IT queue, you’ll likely want to make two groups: IT_staff (for queue members who can act on tickets, but not change much about the queue itself) and IT_admins. You’d then go to your IT queue, click ‘Group Rights’, and type in the name of either of your two IT-related groups. Choose the group, grant it all the rights you want, and save it. Now, to give someone admin rights on the queue, you’d just add them to IT_admins and you’re done.
##Groups The first thing to remember is that groups are how you do everything. For instance, to make a user into an administrator, your first instinct is likely to grant that user admin rights–mine was–but that’s now how RT wants you to do it. Instead, you create a new group, calling it something like ‘admins’, and grant the group admin rights. You then add the users whom you want to be admins to the group, even if it’s only one user.
Similarly, as described above, you should never grant users rights on queues. Instead, create a group, grant the group the rights, and then add users to the group.
##Watchers It took me a while to figure out how to make members of groups able to get ticket activity notifications. The key is what RT calls ‘watchers’, which are groups or users who are copied on all ticket emails. To add a group (remember to always use groups, not individual users), simply open the queue, click ‘Watchers’, and add the group(s) you want. I usually make queue_staff CC watchers, and queue_admins admin CC watchers.
##Scripts Scripts are how notifications get sent out. You can choose from a wide range of options for triggers that make the script run, and actions, which are executed when the script triggers. The default scripts will notify the right people of ticket activity, and a lot more besides, but you can modify and/or add scripts if you want to. Note that scripts can act on queues or globally, across the entire RT system.
##Templates Templates, of course, are the bits of text used in emails and other parts of RT. They have placeholders that get replaced with real values when the template is used, such as the ticket number or name of the requestor. Some good descriptions of the basics, and the available syntax/keywords, are in this template intro and this template syntax wiki.
#Still Here? I know that was a lot, especially if, like me, you’re not a seasoned sysadmin or anything. If you got it to work, awesome! If you’re still having trouble, please don’t ask me why. I might be able to answer a few questions, but I will mostly be a waste of your time. Instead, please refer to the RT email list, where a lot of great help can be found. I got most of the information/answers in this post from that list.
#The Pre-Babble Before I get to the questions I’d love some Christians to answer, I wanted to briefly explain why
#Intro This page contains notes I’ve made on the ocarinas from Mountain Ocarinas (and yes, that pun was