Day-to-day administration of an RT instance is pretty minimal. Other than the initial installation, setup, and occasional configuration tweaks, administration generally falls under a few basic areas: creating new users, modifying existing users, and backups.
Now that you have an RT server running, it’s time to configure and customize it for your organization. Chapter 7 shows some example configurations, but for now, we’ll help you get up to speed with a basic RT configuration.
First, you’ll need to create a few users. Once that’s taken care of, you’ll create a queue for your project and grant your users rights to work with that queue.
Every person that interacts with RT has a corresponding user object. This object is loaded when the person accesses RT, whether through the web, email, or rt.
To create a new user, load up RT’s web interface and click on Configuration, Users, and then New user. Figure 5-1 shows the new user page. To update an existing user (for example, one that RT created automatically from an incoming email), click Configuration, Users, and then search for the user’s email address, names, or user id.
The only required attribute is Name, which RT uses as the username. If you want RT to be able to send email to your users, it’s worth filling in the Email Address and Real Name fields. If your users will be logging into RT, you also should fill in the Password field.
Privileged users have access to RT’s full web interface and can be granted rights directly. Unprivileged users only get access to RT’s self-service interface. As of RT 3.4.2, only privileged users can be added as group member in RT, but that will change in the future.
When RT creates a user, it creates an unprivileged user by default. To make your user privileged, check the box Let this user be granted rights.
If you ever need to cut off someone’s access to RT, uncheck the box Let this user access RT. This will make sure the user can’t log in to RT, but it does not fully delete the user. RT won’t let you delete users because that would erase everything that user had done, and a large part of the point of a system like RT is that you don’t lose history like that.
RT has a built-in group management system to make it easy to manage your users’ rights and responsibilities. You can grant rights to groups and make them queue and ticket watchers. Using RT’s Saved search system, it’s also possible to let group members share saved searches among themselves. You’re not required to use groups when managing RT. But it’s a lot easier to pop somebody into a group when they join your team and yank them out if they leave than go through 10 different queues looking to see if you’ve properly yanked any rights they once had.
To create, update, and disable groups, you need to be logged in to RT as a user with the AdminGroups right (or SuperUser). The first step is to go to the group management interface. From RT’s web interface, click Configuration, then Groups , then New group. You should now be on RT’s new group page, shown in Figure 5-2.
Enter a name and description for your group. The name will be seen primarly by people, not by computers, so make sure it’s easy to understand when you (or somebody else) come back to it in six months. “Staff,” “IT Department,” and “Nuclear Weapons Development Team” are all fine names. Description is strictly optional and is just another place for you to record a bit more data about what this group is for.
As with many other things in RT, you can’t ever delete a group, since you’d lose historical information about what happened to that group. You can, however, disable groups, by unchecking the enabled checkbox. Once the nuclear weapons project is over and the development team has retired to a small tropical island, it’s safe to uncheck the enabled box on the group overview page for the “Nuclear Weapons Development Team.”
Once you’ve created a group, you can add and remove group members by navigating to the group overview page—Configuration > Groups > <your group>—and clicking on Members. Since RT 3.0, group membership has been recursive—groups can contain both users and other groups. There isn’t any limit to how many levels deep groups can contain other groups. The only thing a group can’t contain is itself, but don’t worry, RT will stop you before you do that.
You’ll want to set up a queue for each new department or long-lived project that you track in RT. Like users and groups, queues never go away, so you don’t want to create too many. Create a queue each time you have a set of tasks or requests that will be handled by a separate group of people who track their own special metadata or have different privacy requirements than your existing queues.
If you’ve been following along, the instructions for creating a queue are going to look rather familiar. Click Configuration, then Queues, and then New queue. Figure 5-3 shows the new queue page.
The Queue Name is the primary way that you’ll see the queue in the web interface and also from the mail gateway and some scrips. While you can use any name you want, it’s easiest to stick with names that don’t contain apostrophes, slashes, and other characters that might need special escaping. The Reply Address and Comment Address fields determine what RT will stick in the return address of outgoing response and comment emails. If you leave them blank, they default to the systemwide settings in your configuration file. RT also lets you set a default initial priority for tickets in the queue, as well as a final priority that only kicks in if you use the RT escalation tool.[10] If you fill in the Requests should be due in _ _ days field, RT will automatically assign a due date that many days in the future for your tickets.
Don’t forget to set up RT’s incoming mail gateway for your new queues. See Chapter 2 for instructions on how to do that.
Once you’ve created a new queue, you should set up the default Cc and AdminCc lists for it. From the queue overview page (Configuration > Queue ><your queue>), click Watchers. Figure 5-4 shows the queue watchers page.
You can search for users and groups to add to the queue’s Cc and AdminCc lists. These people will be added implicitly to those roles for every ticket in the queue and may also be granted rights based on your queue access control configuration.
You can grant per-queue rights to users or to groups. We generally recommend that you grant all rights to roles and groups, as it makes administration much easier. From the queue overview page (Configuration > Queue > <your queue>), click Group Rights. On this page, shown in Figure 5-5, you can grant rights to role groups such as Requestor, AdminCc, and Cc, as well as system-internal groups like Everyone and Privileged.
To allow arbitrary remote users to submit tickets into a given queue by email, grant the system-internal group Everyone the rights SeeQueue, CreateTicket, ReplyToTicket, and CommentOnTicket.
To make sure your staff can work with tickets, you should grant your staff group all the following additional rights: ShowTicket, ShowTicketComments, Watch, WatchAsAdminCc, OwnTicket, and ModifyTicket. If you’ve given your staff group an AdminCc role for the queue, you can grant only these rights to the AdminCc role group.
If you’ll be opening up the self-service interface to your requestors, you’ll also need to grant the Requestor role group the ShowTicket right.
Out of the box, RT comes with a relatively straight-forward set of scrips. These scrips take care of making sure that Requestors get an autoresponse when they create a ticket and that everyone gets copies of relevant email and other ticket updates. You can add custom scrips either globally or per queue, but they aren’t required for making RT work correctly. We’ll go into more detail about scrips in Chapter 6.
RT lets you define custom fields that apply to tickets, ticket updates, users, or groups. People mainly use custom fields to track additional site-specific metadata. We’ve seen them used for simple things, such as the version number of a software package where a bug was found, and more complex things, such as whether someone enquiring about renting a vacation home needed a place that accepted pets.
As of this writing, RT supports five different sorts of custom fields: Select to pick from list, Freeform to type a line of text, Text to type a large block of text, Wikitext to hold multi-line blocks of wikitext, Binary to upload a file, and Image to upload an image. For each of these types except Text, you can pick whether you want your users to be able to enter one or many values. In the near future, we expect to add additional field types, as well as validated and mandatory fields.
To create a custom field, click Configuration → Custom Fields → New Custom field. You’ll need to fill in a Name for your field and pick which sort of field you want, as well as saying whether it applies to tickets, ticket updates (transactions), users, or groups. If you created a Select field, you can build up a list of possible values for the field after you create the field. Figure 5-6 shows the form for creating or editing a custom field with the values options for Select fields.
RT lets you switch a custom field’s type, even when it’s already in active use. Toggling a Image field into a Binary field is perfectly safe. It’s even generally safe to turn a Select custom field into a Freeform field, since RT stores custom field values by value instead of by reference.
Each custom field has its own access control . This means that it’s easy to create fields that only certain users see, even if your tickets are otherwise public. To modify your field’s access control, click Configuration → Custom Fields → <your custom field> → Group Rights. Figure 5-7 shows the custom field rights page.
The AdminCustomField right governs who can change a field’s name, values, and access control. SeeCustomField determines who can see that a custom field even exists, and ModifyCustomField determines who can set a custom field’s value for a particular ticket, transaction, user, or group.
Regular ticket custom fields apply either globally or to any set of one or more queues. To tie your new custom field to your queues, click Configuration → Custom Fields → < your custom field> → Applies to. From this page, you can pick one or more queues for your custom field. If you want your custom field to apply to all queues, even queues you haven’t created yet, click Configuration → Global → Custom Fields → Tickets, and pick the fields you want to make global.
Most days, you won’t need to think about RT management. Sometimes, you’ll need to reset a user’s password, add a queue, or update someone’s permissions, but RT generally takes care of itself. In this section, we’ll show you how to take care of a few of the most common day-to-day tasks you’ll encounter.
Some organizations invest a fair amount of time to set up a single sign-on system of one sort or another. While there are many different ways to get RT to support single sign-on, the easiest is to configure RT to let your webserver deal with authentication; most single sign-on frameworks already have a good solution for Apache authentication. If you set $WebExternalAuth to 1 in RT’s configuration file, RT will trust whatever your webserver says about who is currently logged in. If the webserver tells RT that a user RT’s never heard of has logged in, it’s possible to have RT automatically create the user. To do this, just set $WebExternalAuto to 1.
Sometimes, someone puts something into RT that really should never have been there in the first place, like the entire company’s salary list or the CEO’s baby pictures. When you absolutely need to make sure that content is purged from RT, it’s possible, though not encouraged. First, find the transaction’s ID. You can do this by looking at the URL for the # anchor next to the transaction. Let’s say that it reads http://rt.example.com/Ticket/Display.html?id=3700#txn-33070. That means you want to get rid of transaction 33070.
The following code will take care of it for you:
perl -I/opt/rt3/lib -MRT -e '
RT::LoadConfig(); RT::Init();
my $t = RT::Transaction->new($RT::SystemUser);
$t->Load(33070);
print $t->Delete;
'
RT logs information about each message it sends out, as well as each message it considers sending out. All outgoing mail about a given ticket update is sent by a scrip. Each scrip evaluates some sort of condition, such as Is this a new ticket being created? or Is this a private comment? If the answer to the question is Yes, then RT moves on to whichever action you’ve associated with that scrip. It might be an action such as notify the requestor or notify the owner. RT then sets up an email message using the template you’ve defined for the scrip and checks to make sure that it’s actually being sent to someone. RT logs this process using its standard logging framework. Log messages about scrip-generated email are keyed by the outgoing message’s Message-Id header. You can use that identifier to trace a message RT sends as it makes its way across the Internet from your RT server to the recipient’s local email server. The example below shows an autoreply being sent out to jesse@example.com.
Jul 4 22:15:53 pallas RT: <rt-3.2.HEAD-5813-28448-22.1.5718764250061@example.com> #5813/28448 - Scrip 22 Jul 4 22:15:53 pallas RT: <rt-3.2.HEAD-5813-28448-22.1.5718764250061@example.com> sent To: jesse@example.com Cc: Bcc:
Let’s take a look at these log messages in a bit more detail. The first message gives us a heads-up that RT is considering sending some sort of email. In this case, scrip 22 sends an autoreply to the ticket’s creator when a ticket is created. This scrip is acting on transaction 28448 on ticket 5813. The second message tells us that RT has sent out this email to just one person, jesse@example.com. If RT had decided to scrap the email, we’d see a different second message:
Jul 4 22:15:53 pallas RT: <rt-3.2.HEAD-5813-28448-22.1.5718764250061@example.com> No recipients found. Not sending
This usually means that you have a scrip set up to notify a ticket’s Owner or AdminCc or manually entered Cc or Bcc recipients, but there weren’t any.
RT reports all failed logins at the error log level. Generally, failed logins can be found in /var/log/syslog. Depending on how you’ve configured the syslog service, errors might turn up in different places, but they’ll all look something like this:
Jul 4 21:08:01 pallas RT: FAILED LOGIN for root from 209.6.22.246
You can use standard log summarizing tools to automatically extract all RT login failures from your syslog. A quick and dirty shell script to send you mail about all failed RT logins today would look something like this:
#!/bin/sh
grep `date +%b%e` /var/log/syslog \
| grep RT:\ FAILED\ LOGIN \
| mail -s "Today's failed RT logins" rt-admin-userRT doesn’t store anything important about your users, groups, tickets, or queues directly on your filesystem. All the data you need to worry about on a day-to-day basis lives inside the database you’ve set up for RT.
If you’re already backing up your MySQL, PostgreSQL, or Oracle server, you can skip down to Backing up the RT Application below.
If you’re still with us, that probably means you’re one of the silent majority of users who doesn’t yet backup your data, because you haven’t yet suffered catastropic data-loss. Backing up RT is quick and easy. All you need to do is take a snapshot of your database and spool it out to disk as a series of SQL statements that you can run later if you need to recreate your database.
- MySQL
MySQL’s mysqldump command is a very convenient way to backup any MySQL database. It exports the contents of the database as a series of CREATE TABLE and INSERT statements, which then can be replayed to recreate a database. This method is slower than a disk-based byte-by-byte copy, but you are guaranteed to have a usable dump that can be used to recreate your database with minimal effort.
mysqldump --opt --add-drop-table --single-transaction \ -urt_user-prt_pass-hdatabasehostrt3 > rt3-mysql-backuprt_user,rt_pass, andrt_hostnameshould match the user, password, and hostname in your RT_Config.pm or RT_SiteConfig.pm.- PostgreSQL
pg_dump lets you dump out a live postgres database, including all schema and content. All of the previous comments about MySQL apply here, too.
pg_dump --clean --blobs --format=C -U
rt_userrt3 > rt3-postgres-backup- Oracle
If you’re running Oracle, it probably means you have a DBA. Take your DBA out to lunch, and discuss backing up your RT database. It’s a business expense and a great way to ensure his cooperation if you ever need your RT database restored at 2 a.m.
- SQLite
SQLite uses a single file as its entire database. To be sure your database is consistent, stop your RT daemon, copy the database file to your backup media, and start RT again. This should be automated with cron, and done regularly. SQLite’s one file makes backups convenient. For example, you can use a source control system such as Subversion or CVS (in binary mode) to manage the file.
The RT application itself is stored on disk. Certain cache files get written out at runtime, but they’re not important to keep in the event of a catastrophe. If you’ve just installed RT from the source distribution and haven’t customized any of the source files or web templates, you can get by without backing up the RT application. Just make sure you hang onto a copy of the original source files and reinstall RT when you need to. If you’ve made any changes to RT’s configuration files, libraries, or web templates, you should keep backups of your RT installation. There isn’t any danger to backing up RT while it’s accepting tickets.
The most important file to back up is RT_SiteConfig.pm, since this the only file you are guaranteed to have changed. You can restore an RT instance using only RT_SiteConfig.pm and a database dump if needed.
When you back up the RT application and libraries, be sure that you have a backup of your webserver, database server, Perl installation, and other similar things on which RT depends. If you plan on making extensive changes to your RT instance, you should consider storing RT’s libraries and document root in a local source control repository. CVS’s vendor import facility was designed specifically to handle this situation (indeed, CVS originated as a way to track local modifications to vendor distributed source code), and other source control systems have analogous functionality.
The worst has happened. Your RT database server went up in a big ball of flames about 20 minutes ago. And your users are already clamoring for you to replace the server and let them get on with their work.
To get RT up and running after a crash, restore your RT application from your regular system backups. If that’s not an option, start with a brand new, fresh installation of the RT version you were running. Make sure RT’s configuration file has the same values it had before your crash. It’s particularly important that you get the $rtname and $Organization variables right, or RT won’t work properly.
Once you have RT installed, it’s time to restore your existing RT database. This is essentially the reverse of the dump process you go through when making backups.
To restore a mysql-based RT instance, you just need to use the mysql command to feed your rt3 database back in from your backups using this command:
mysql -urt_user-prt_pass-hrt_hostnamert3 < rt3-mysql-backup
You can restore a Postgres RT instance from a backup you made with the procedure we outlined earlier using this command:
pg_restore --create < rt3-postgres-backup
All the data postgres needs about the database name, tables, and columns is embedded in the backup file.
Since SQLite stores its database in a single file, restoration means copying the backup file to where RT expects to find it. What could be simpler?
RT’s default administrative user is called root, after the Unix super-user of the same name. When you installed RT, this user started off with the default password password. If you followed our instructions, you changed this password immediately. For one reason or another, you might no longer know root’s password. Either you changed it to something you couldn’t possibly forget or, more likely, someone else set up your RT instance and is hiking in the Himalayas or otherwise uncontactable. No problem. Just log in as another user who has either the SuperUser right or the AdminUsers right and change root’s password. If you don’t happen to have one of those around, you can write a simple Perl one-liner to change a user’s password. In the example below, we’re going to change root’s password to secret. You’ll need to run this script as root or as another user who can read RT’s private configuration file.
perl -I/opt/rt3/lib -MRT -e'
RT::LoadConfig(); RT::Init();
my $u = RT::User->new($RT::SystemUser);
$u->Load("root");
print $u->SetPassword("secret");
'When you run the script, you should see the response “The new value has been set.” Then you should be all set to log in as root.
If you ever find yourself in the unfortunate situation of having removed your only administrator’s SuperUser rights, don’t panic.
The following one-liner uses the RT API and the internal module RT::SystemUser to grant the root user the SuperUser right safely. As with the last tip, you’ll need to run this as a local user who can access the RT config file.
perl -I/opt/rt3/lib -MRT -e'
RT::LoadConfig(); RT::Init();
my $u = RT::User->new($RT::SystemUser);
$u->Load("root");
print $u->PrincipalObj->GrantRight(
Object => $RT::System,
Right => "SuperUser"
);
'If you’ve really clobbered your administrative user or don’t even know who your RT administrative user is, don’t despair. This tip will turn any RT user into a superuser in seconds. Just replace root in this example with any other valid username.