RTFM RT Manual - DOC by dal93033


                                        Table of Contents


Administration Guide
       - Concepts
       - Terminology
                - Ticket
                - Links
                - Requestor
                - Status
                - Users
                - Attributes
                - Privileged Users
                - Nonprivileged Users
                - Queue
                - Groups
                         - Normal Groups
                         - Pseudogroups
                - Watchers
                         - Types of Watchers
                                  - Requestors
                                  - Ccs
                                  - AdminCc
                         - Watcher Scopes
                                  - Queue
                                  - Ticket
                - Keywords
       - Access Control (ACLs)
                - Description of Rights
                - Scrips
                - Conditions
                - Actions
                - Templates
                - Relationships
       - Backup and Restoration
       - Email
       - Administrative Procedures
                - Creating a user
                         - with the CLI
                         - with the web interface
                - Creating a queue
                - Granting users rights to access a queue
                - Using scrips to notify users of changes to tickets in a queue
       - Keywords
                - Creating a Set of Keywords
                - Adding a keyword selection to a queue
                - Sample Keyword Tree for IT Support
       - Performance Tuning
                - Database Optimisation
                - Operating System and Environment
                - Hardware aspects
       - Extending and Customizing RT
              - Scrip Actions
              - Scrip Conditions
              - Plugging in your own user metadata
              - Plugging in your own authentication system
      - Tool Reference
              - Email Gateway

      - Administration
              - Are there any default templates with RT?
              - What is the purpose of keywords?
              - Why can't users change their password?
              - Is there a default password for auto-created users to view their ticket?
              - How do I delete users and groups
              - Why aren't emails being sent to watchers?
              - Can I send emailed reminders to ticket owners?
              - Email
                       - What's that Sender: header, and how do I make it go away?
                               - sendmail and sender
              - Sendmail won't let me run rt-mailgate
              - Why is RT so slow?
              - Why are there two Mason Component directories?
              - Why is the owner of a new ticket nobody and not the requestor?
              - How do I delete and re-create my RT database?
  Request Tracker is a trouble ticketing system. It lets a group of people intelligently and efficiently manage
requests from a community of users. RT is used by systems administrators, customer support teams,
network operation centres, developers and even marketing departments.

 The basic model works something like this:

  - A user makes a request via email or a web interface
  - RT emails the user an automatic reply containing an electronic ticket stub for reference in further
  - RT creates a new ticket in a queue containing the user's request. The ticket is now visible via the web
interface to queue members, who are generally experts of some kind who can answer the request
  - If configured to do so, RT also emails the contents of the request to a list of queue members who have
opted for such notification, or other people for whom the queue administrators have added an email address
  - A queue member takes ownership of a request (normally via the web interface) and drafts a reply to the
user, which RT records and forwards to the user
  - The queue member resolves the ticket and moves onto the next new ticket

  RT can be configured to suit specific site requirements, but the basic concepts and usage remains the
Administration Guide

RT is a complex application. You need to understand the concepts behind RT and the terminology
describing these concepts if you are going to deploy it to the best effect in your organisation.


  A Ticket contains all the information regarding a request, including who requested it, what action has been
taken, its current status, and the details of the request.
  Each ticket is identified by a unique ticket number. The terms ticket and request are used interchangably.
Users with a background with the commercial Clarify helpdesk system will be used to the term Case, which
also means the same thing.

  Tickets can be linked to each other with these relationships:
        - MemberOf
        - RelatedTo
        - DependsOn
        - MergedInto
  These links are informative for RT users viewing tickets, and are also used in a variety of ways by RT such
as in searches.

 The user who created the request. He may or may not be a user on the local Unix system. Depending on
how RT is configured, he might instead be someone sending an email whose identity cannot be verified.

 A ticket will always have a status which may be one of:
        - New: The ticket has never been viewed or acted upon.
        - Open: The ticket has been viewed, and is being dealt with.
        - Stalled: The ticket has been put on hold as it cannot presently be resolved. If there is any further
        correspondance, the ticket will automatically be reopened.
        - Resolved: The ticket has been dealt with, and is no longer an issue.
        - Dead: This indicates that the ticket was deleted. Usually tickets are only deleted in the case of
        duplicate requests or spam email. For technical reasons a ticket is never erased from the database,
        it just has the Dead status.
 Sites will sometimes have their own interpretation of each status.
  Every person or program that interacts with RT has a username and is therefore a user. A user has
attributes stored against their username. There is only one type of user, but the attributes means that users
have very different capabilities within the RT system.
  Examples of attributes used to differentiate users are:
         - Ticket privileges, where a user has the ability to perform a certain action to tickets such as create
         or delete
         - Group memberships, where a user shares attributes with other users
         - Unix username, which gives the user the right to use RT from the Unix commandline interface
  Sometimes it looks like someone can interact with RT without having a username. As you'll find out
elsewhere in this documentation, this is not correct.

 Some attribute information is stored for every user.
      - Name. This is the username that all activity is logged by. It need not correspond to a username in
      any other system at all, although it can do either via the external authentication scheme or via the
      Gecos Unix Username attribute.
      - Password. This can be null, although of course it is normally bad policy to do so.
      - Gecos (Unix Username). If this is not set then the user cannot log in via RT's commandline tool,
      which uses the unix username for authentication.

Privileged Users
  Privileged users are users who can be granted rights and responsibilities. Typically they are the staff of the
organisation using RT but that entirely depends how your organisation is structured. For example, you can
easily create privileged users with minimal privileges to allow your customers to contribute to tickets about a
certain topic.

Nonprivileged Users
  These users can not be granted rights or responsibilites (except as members of pseudogroups. These
users can not access the normal RT web interface. When they access the web interface, they are
immediately shunted to RT's "SelfService" interface for requestors.
  When email is submitted to RT's email gateway from an unknown email address, RT will automatically
create a Nonprivileged user with a name derived from the email address. RT will assign the ticket to the
special nonprivileged user nobody. The newly-created Nonprivileged user is required in order for RT to
function (e.g. to track correspondance) and has nothing to do with ticket ownership, queue privileges or
anything else. It is a very good idea to put RT behind a spam filter such as Spamassasian.
  It is not currently possible to force tickets that are automatically created like this to be owned by a
particular user.

  A queue contains tickets generally of a similar nature, for example, a technical support queue. Queues are
an administrative unit with their own privileges, scrip actions, templates and keywords. Each ticket can only
be associated with one queue.
  Multiple queues may be set up, and each will have its own email address. So you might have a queue
called noc@example.com which is monitored by technical staff, and billing@example.com which is used by
accounts staff. Tickets may be moved between queues, so a tech could pass a ticket onto the accounts
department once work has completed.
  Queues can be configured differently, so the noc queue may issue an autoresponse when a ticket is
created, whereas the accounts queue might be configured to prevent internal correspondance being sent to
the requestor.

  Groups are logical collections of usernames. In general, if an RT operation can be performed on a single
user it can be performed on a group as well.
  This is particularly useful when dealing with permissions and ACLs. So for example it often makes sense
to give a particular group read-only access to a certain queue rather than the many members of that group.
Removing a username from the group causes all privileges granted via that group membership to be

  Normal Groups
 These consists of collections of usernames.

  These are special collections of usernames, and contain some special usernames. These come
configured by default. Pseudogroups cannot be created by an Administrator, they are built in to RT. Some
memberships in pseudogroups can be changed, however.
  A list of the pseudogroups is:
          - AdminCc
          - Cc
          - Everyone
          - Owner
          - Requestor

  Watchers are (essentially) people that get email about tickets. Watchers can be added globally (all
queues), per-queue, or per-ticket. Right now, watchers can only be individual users, not groups. I expect
this to change.

Types of Watchers

 There are three types of watchers.

  Requestors are people making the request which ended up in a particular queue by some means. The
requestor does not own a ticket because they made the request (and in most installations the requestor
cannot own a ticket), but the requestor usually does get at least some correspondance via email, for
example an automated reply via the AutoReply scrip.
  Requestors traditionally see only correspondence, however since RT knows about some kinds of users
(either because they are RT users, or because RT does a matching between email address and RT
username) a requestor may also be someone with privileges to do things to the ticket.

  Ccs are people other than the Requestor who need to see email traffic relating to the ticket (exactly what
traffic depends on the scripactions that have been set up.) The thing distinguishing a Cc is that while they
receive this email they do not necessarily have privileges to do anything in the RT system. Any email
address anywhere on the Internet can be in the Cc list.

   An AdminCc is just like a Cc, except that the recipient is someone with privileges to do things in RT. Often
this may be used so that AdminCcs get to see more details about ticket activity, however this is not
necessarily so (for example, some queue administrators might not wish to be burdened with a lot of email.)
   The only people that can be added as a AdminCcs for a queue are those with permissions to administer
tickets in that queue.

Watcher Scopes
  A watcher can be set for a queue. This person will e.g. be notified of all activities in said, in accordance
with the scrips set up for that queue. This will typically be a person who will reassign tickets arriving in the
queue or someone who needs to keep an eye on the activities in a section of a company.
  As above, but only for one ticket.

  Keywords are tags specific to your organisation that are presented to queue administrators for their use in
classifying tickets. The definition and use of keywords is entirely site-specific. Keywords are definied in a
hierachical tree.
  Keywords can be used for searching and reporting, and as trigger values in Scrips. This Administration
Guide has an extensive section on keywords which includes a tutorial.

Access Control (ACLs)
  RT includes a rich ACL scheme which supports granting rights to users and groups for a given queue or
for the entire RT instance.

 Rights can be granted to:
       - a specific user who has the privileged flag set and doesn't have the disabled flag set
       - a specific locally defined group
       - one of several 'pseudogroups': everyone, requestor, cc, admincc, owner

 Rights granted to an individual user are granted to that user and only that user

  Rights granted to a locally defined group will be made available to all members of that group, so long as
they remain members of the group.

 Rights granted to the pseudo-group 'everyone' will be granted to all users.

  Rights granted to any of the following pseudo-groups will be dynamically
granted to users based on the current ticket being dealt with: requestor, cc, admincc, owner.

Description of Rights

  Rights can be granted to users and groups to define what the user is allowed to do and change in RT.
Rights can apply to the whole of RT and all the queues (global) or can apply to a single specific queue.
Rights can be granted to individual users and to defined groups of users.

   Rights can also be assigned to pseudogroups that define users in a context. The pseudogroups are
"Everyone" (all the users on the system), "Requestor" (users that are requestor in the context of the current
ticket), "Cc" (users that are Cc , either direct by the ticket or defined in the queue, of the selected ticket) and
"AdminCc" (users that are Administrative Cc to the ticket or the ticket's queue).
  The effective rights of a user are the combination of the global personal right, the combined global rights of
the groups the user is in, the rights of the user and all the groups that the user is in to the currently selected
queue and the rights the user gets through the pseudogroups.

 A description of all the rights that users and groups can be assigned in RT follows:

  AdminGroups (global only)
 Users with this right are allowed to create new groups, modify the name and description of the group and
add and remove registered users to and from the group.

  AdminKeywordSelects (global and queue)
  Users with the AdminKeywordSelects should be able to add, delete and modify keyword selections for a
specific queue (or all queues if this right is set

 AdminKeywords (global only)
 Users with the AdminKeywords rights can add, modify and delete keywords. Keywords are global to RT.

   AdminQueue (global and queue)
   Users with the AdminQueue right can change can change anything on the queue 'basics' screen. They
can create queues (if granted the right globally). They can "disable" a queue. Which means that no new
tickets can be created in the queue.

   AdminUsers (global only)
  Users with this right are allowed to add and modify users. All privileged users are allowed to browse all
the registered users.

 CommentOnTicket (global and queue)
  Users with the CommentOnTicket right are allowed to add comments to tickets. When this right is global a
user can add comments to all the tickets in RT otherwise the user is only allowed to comment on tickets in
the specified queue.

 CreateTicket (global and queue)
  Users with the CreateTicket right can create requests in the specified queue or in all the queues if global is

 ModifyACL (global and queue)
  If a user has the ModifyACL right he/she can change the rights different users and groups can be assigned
regarding queues. If the ModifyACL right was granted globally the user can change all the ACLs in RT,
including the global ones (including granting him/herself SuperUser privileges). ModifyACL does strange
things without ShowACL.

 ModifyQueueWatchers (global and queue)
   This rights enables a user to register and remove other users as watchers (Cc and AdminCc) to a queue.
If this right is assigned globally the user can modify watcher settings of all the queues.

 ModifyScrips (global and queue)
  This right allows a user to add and delete scrips from a queue of, if the right is granted globally, change
the global default scrips.

 ModifySelf (global only)
  This allows the user to change his/her personal settings. The following fields are now only modifiable by
folks with "AdminUsers" permission:
 Organization, Disabled, Privileged, Name, ExternalContactInfoId, ContactInfoSystem, ExternalAuthId,
AuthSystem, Gecos

 The basic philosophy behind the decision about what to limit editing to is that the user should be free to
modify their own contact info, but should not be able to modify RT username or fields that could effect ACLs.

  ModifyTemplate (global and queue)
  The user is allowed to modify the templates. If this right is granted globally the user may modify the global
templates and the templates for all the queues.

 ModifyTicket (global and queue)
   The user is allowed to modify the ticket. Modifying the ticket includes changing the subject, status, time
worked, time left, priorities. ticket dates, keyword values, owner (to users that are allowed to own the ticket?),
requestor and watchers and relationships with other tickets. The user can also comment and correspond on

  OwnTicket (global and queue)
 Only users that have the OwnTicket right can be owners of a ticket. This right can be granted globally or
per queue.

 ReplyToTicket (global and queue)
 User with a ReplyToTicket right can add replies to a ticket.

 SeeQueue (global and queue)
 This right right allows the user to see that a given queue (or all queues) exists

 ShowACL (global and queue)
   This allows the user to view the currently active ACLs (rights granted to users and groups). When this
rights is applies globally the user is allowed to view all system ACLS

 ShowScrips (global and queue)
 Users with this right are allowed to view scrips.

 ShowTemplate (global and queue)
 Users with this right are allowed to view the mail templates.

 ShowTicket (global and queue)
 Users with this right are allowed to display the ticket.

 ShowTicketComments (global and queue)
 Users are allowed to view the comments entered with tickets.

 SuperUser (global only)
 A SuperUser is allowed to do anything.

 Watch (global and queue)
  The user is allowed to sign up to "watch" this queue or tickets in this queue as a cc or a requestor. The
user is also allowed to stop watching tickets in this queue. Think of this as AdminWatchers, but only for
oneself as requestor or CC.

 WatchAsAdminCc (global and queue)
 Like Watch, but only as an Admin

  RT includes a powerful system for implementing local business logic, called 'Scrips'. (The 'Scrips' system
is a combination of a 'script' system and a 'subscription' system).

 RT allows each site to control this and many other behaviors at the queue level. Through the scrips
mechanism, RT allows local administrators to define what actions should be taken on each transaction.

  Scrips can be defined per-queue and system-wide. Each scrip is composed of a Condition, an Action and
a Template.


    Conditions are things like:

-        OnCorrespond
-        OnComment
-        OnCreate
-        OnStall
-        OnResolve
-        OnTransaction


    Actions include things like:

-        NotifyRequestorsAsCorrespondence
-        NotifyCcsAsCorrespondence
-        NotifyAdminCcsAsCorrespondence
-        NotifyAllWatchersAsCorrespondence
-        NotifyRequestorsAsComment
-        NotifyCcsAsComment
-        NotifyAdminCcsAsComment
-        NotifyAllWatchersAsComment

    Note: Notify scrips do not send mail to the user performing the action.


    There are a bunch of predefined system-wide templates like:

     -    Autoreply
     -    Transaction
     -    Correspondence
     -    Comment

 Additionally, RT allows local RT administrators to define new system-wide tempaltes and allows queue
administrators to define per-queue templates.
  Templates can optionally have RFC822 headers which will be appended to an outgoing mail message. If
a template has such headers, it MUST contain 2 newlines seperating the message body from the headers.


 RT has the concept of arbitary relationships that link two (or more) tickets together. A ticket can have
multiple relationships with multiple tickets.

  Depends on / Depended on By
  A ticket can depend on another ticket. The normal usage is when a given project (ticket) cannot be
completed until another project (ticket) has been completed.
  Parent / Child, Children
  A given project (ticket) can be a sub-project of another, larger project (ticket). This also has some of the
implications of Depends on/Depended on by, but the focus is on a vertical, rather than horizontal
  Refers to / Referred to by
  This is primarily for documentation purposes. A given ticket can contain the interesting/useful information
that doesn't need to be repeated in another ticket.

Backup and Restoration
  The RT system is primarily database driven. To backup your working RT installation, it is suggested that
you first understand the pitfalls behind backup and restoration of a relational database. The MySQL chaps
have written an excellent guide, with specifics:

This states in parts:

The key to safe database management is taking regular backups. To take a 'binary' backup
of your database you have to do the following:

     *   Shut   down your MySQL database and make sure it shuts down without errors.
     *   Copy   all your data files into a safe place.
     *   Copy   all your log files to a safe place.
     *   Copy   your `my.cnf' configuration file(s) to a safe place.
     *   Copy   all the `.frm' files for your InnoDB tables into a safe place.


Administrative Procedures

Creating a user

with the CLI
with the web interface

Creating a queue

Granting users rights to access a queue

  - To allow any user to create a ticket in any queue, grant the right 'CreateTicket' to the Pseudogroup
'Everyone' globally.
  - To allow any user to create a ticket in the queue 'general', grant the right 'CreateTicket' to the
pseudogroup 'Everyone' for the queue 'general'
  - To allow anyone to send in an email update to a ticket in the queue 'general', grant the rights
'ReplyToTicket' and 'CommentOnTicket' to the pseudogroup 'Everyone for the queue 'general'

Using scrips to notify users of changes to tickets in a queue

  RT has a very useful new feature, called keywords, for tracking characteristics of tickets. Keywords allow
you to assign any sort of tracking metrics you want to tickets in your queues. For instance, you could track
job applications by geographic region in order to determine where you should locate new offices; or you
could add a "severity" level to tickets in order to help you prioritize your work.

  Once keywords are added, they become part of the ticket display, and you can use them as restrictions in
a ticket search.

  Another important use for keywords is reporting. A common requirement is a regular report that includes a
brief summary of the tickets that have been closed recently. Keywords can save a lot of time in doing this
without requiring the workers to write detailed explanations. Just assign a keyword category such as
"Reason for Closure" and the report can be mostly constructed from a normal RT search screen.

  Keywords are very easy to add to your RT installation -- they can be added completely through the Web
interface. There are two basic steps to adding keywords to RT:
         - Create a set of keywords that you want to track; and
         - Add your keywords to all queues, or to one or more individual queues.

  This manual covers how to add a "Progress" keyword selection to a job application tracking queue. This
keyword will allow you to track how far along each candidate is in the review process. Using this example
you can add any keywords appropriate for your uses to your site's RT configuration.

Creating a Set of Keywords

  The first step in using keyword selections is to set up a set of keywords that will be useful to you. A
"keyword" is either any individual ticket characteristic (such as an urgency level like "Critical"), or a category
of individual keywords (such as "Urgency"). In planning your keywords, take a look at the example job-
applicant keyword selection to the right, and use it as a model. This example shows one keyword selection,
with a category named "Progress," and six individual keywords in that category (of which five are shown in
the graphic) named "1. Requested interview," "2. Interviewed once," and so on.

  Internally, RT does not make a distinction between categories and individual keywords -- all keywords are
stored in one "tree" structure (just like a filesystem with a root directory and subdirectories). Any keyword
can contain other keywords. This fact can be helpful in organizing keywords for easy administration.

  In our example, we want to create a keyword selection to track candidate review progress for a queue
named 'jobs'. Since this keyword selection applies only to the jobs queue, and no other queue on our
system, we'll create a top-level keyword called Jobs.
  This is not required -- you could put the Progress keyword at the top level -- but doing this will allow us to
keep ourselves organized by grouping any keywords specific to the 'jobs' queue together. Inside Jobs, we'll
create a subcategory called Progress, which is our category keyword. Then, inside Progress, we will create
one keyword for each of the selections we want to appear in the form. Our plan, then, is to create the
following keyword structure:

 - Jobs
     - Progress
         - 1: Requested interview
         - 2: Interviewed once
         - 3: Interviewed more than once
         - 4: Offer made
         - 5: Hired
         - 6: Offer rejected

  One thing to note is that when RT displays keyword selections on a ticket, it sorts them alphabetically. If
you would like to have your selections appear in a specified, non-alphabetic order, it is helpful to add a
sequential number or letter to the front of each individual keyword. In our example, our interviewing process
has several steps that need to follow each other, so we've added "1:", "2:", etc. to the beginning of each step.

  Now that we've planned out our keywords, we can add them to RT. While logged into our RT system as a
SuperUser (for instance, using the "Administrator" account), first select [Configuration], and then within
configuration, select [Keywords]. The keywords administration page shows a list of existing top-level
keywords (probably empty at this point), and then a field for adding a new keyword. Following our plan
above, type "Jobs" into the entry field and hit the "Add" button. The result should look like this:

  Once this is done, we then want to create keywords within the Jobs keyword. To do this, first click on the
word "Jobs" (not the "edit" next to "Jobs" -- edit only changes the name of the "Jobs" keyword -- but instead
the word "Jobs" itself), and then use the text field to add the "Progress" keyword. Then click on "Progress"
and add each of the individual keywords planned out above. When all of the keywords have been added,
the result appears as follows:

  (In the image above, the numbers "16", "17" and so on may be different on your system -- don't worry
about that. These numbers are RT's internal id's for each keyword, and they do not affect your

 We have now added all the keywords we need to the system. As of right now, these keywords do not
appear in any of our tickets, because they have not been added to the queue configuration. What we have
done so far is make RT aware of the keywords -- now we need to associate our keywords with our "jobs"
Adding a keyword selection to a queue

  Once we have entered keywords into RT, we then need to specify Keyword Selections, which are sets of
keywords available for selection on a ticket. To do this, we need to choose a selection model (single or
multiple), a selection depth, and which queue or queues will use the keyword selection. Each choice is
described below.

  A keyword selection is represented in the RT interface as one form selection field -- a list of items that a
user may select. Our example keyword selection is pictured at right. There are two varities of keyword
selection: Single selection and Multiple selection. In single selection, a user may select any one keyword in
the list, but not more than one. In our example, we use a single selection since each step in the interview
process is distinct. In a multiple selection, a user may choose one or more keywords in the selection list
(usually by holding down the "Control" key while selecting each keyword). For instance, if you had a
keyword category called "Ways to contact" containing the individual keywords "Email," "Phone," "Fax," and
"Pager," you might want to allow multiple selection to include several contact methods.

  A keyword selection's depth represents how many levels down in the keyword tree the selection should
include. A keyword selection starts at what we've been calling the category keyword -- in our example,
"Progress." This keyword can contain other keywords, which themselves might contain keywords. As an
example, let's say you wanted to change our keyword tree to look like this:

 - Jobs
     - Progress
         - 1: Requested interview
         - 2: Interviewed once
         - 3: Interviewed more than once
              - 3a: Manager interviewed
              - 3b: Peer interviewed
              - 3c: CEO interviewed
         - 4: Offer made
         - 5: Hired
         - 6: Offer rejected

  In this case, if we used "Progress" as our category keyword, and set a depth of "1," the 3a, 3b, and 3c
steps would not be included in the selection field -- they are two levels deep, so they would not meet the
depth requirement. If instead we used a depth of "2" or more, steps 3a, 3b, and 3c would be included in the
selection field. Another way to include these steps would be to use a depth "0," which includes all keywords
under "Progress," no matter how deep they are.

  Next, we can use the keyword selection in two ways: either we can add a keyword selection to a single
queue, or we can add a keyword selection to all queues at once. For our example, our keyword selection is
specific to the 'jobs' queue, so we will add it to that queue's configuration only. To do this, we first choose
[Configuration], then [Queues], and then select the 'jobs' queue. If we had a general keyword selection we
wanted to apply to all of our queues (for instance, "Requestor satisfaction: Happy, Okay, Unhappy,
Unknown") we would instead choose [Configuration] and then [Global].

  Once we have selected the queue to modify (or chosen "Global"), the next step is to click [Keyword
Selections]. Doing this will bring up a form with which we can add a keyword selection to a queue. The
form uses four fields to configure the keyword selection. The first field is the label that will be put above the
selection form field. In our example above, we used the label "Progress." (Note that the label does not
need to be a keyword itself -- the label can be any text you want to use.) Next, choose between Single and
Multiple selection models, as described above. We are using "Single" selection in our example. Next,
choose your category keyword from the pop-up list of keywords. This is the keyword that contains the
selections you want to appear in the form. For our example, we choose "Jobs/Progress". Finally, choose
the selection depth for the keyword selection. We enter '0', which is interpreted as "unlimited depth beneath
the category keyword." Once these selections are made, hit the submit button, and the following form
should appear:

  Your keywords are now enabled. Go to the 'jobs' queue and open a ticket, then click on "Keyword
Selections." You should see the "Progress" keyword selection, and it should contain the six progress steps
entered above, plus the keyword "(empty)," which indicates that no keyword selection has been made for
this ticket.

  Once you have entered some keyword selections, go to the search form and search for the queue 'jobs'.
At the bottom of your results page, you will see that the 'Progress' keyword is now included as a search
restriction, so you can use the progress step as a term in searches. (If you associate a keyword with a
queue, the keyword search form will only appear on searches within that queue. Global keyword selections
will appear on all search forms.)

 Keywords can be an enormous help in adding order and searchability to a large set of tickets.

Sample Keyword Tree for IT Support

  Since many people use RT for IT support desks the following example is included to illustrate how
keywords can be applied

  Support staff are trained to always set the keywords on a ticket, even if they don't have time to write a lot
in the notes. This way basic sorting and reporting can always be done, giving an idea how time has been
spent and what kinds of requests are arising.

 There are two main queues, sysadmin and support, with different keywords available to a ticket in each.
Here are some highlights of this tree design:

        - The keyword 'Closure reason' saves large amounts of time when compiling reports on RT activity.
        For summary purposes there is no longer any need to plough through the ticket notes. For example,
        doing a search on the Closure Reason keyword for 'Done - tranferred responsibility' gives an
        indication of how often problems are being fielded that actually belong to some other area.
        - The idea of reactive tickets(those that arose through the user getting a surprise, e.g. a hardware
        failure) and planned tickets (where the user is making contact because he wants somwething to
        change, e.g. buying a new computer.)
        - Knowledgebase. Articles that have this set to "required" will show up in a regular search, and
        something can then be written for the Knowledgebase from the ticket notes. This keyword can then
        be set to "article written", so it doesn't turn up again.

      closure reason
        Transferred responsibility elsewhere
        Won't do - not reasonably fixable
        Won't do - not our fault
        Won't do - can't reproduce
      ticket classification
           System fault
           User problem
           New feature request
       Purchase - software
       Purchase - hardware
       Inhouse app1 - user issue
       Inhouse app1 - hardware
       Inhouse app1 - software
  ticket classification
    handholding / user understanding
    documentation problem
    new feature request
    billing inquiry
    flat-rate account
  closure reason
    No support
    Bug raised
    5.5, 6000R2
    5.1.1, 6000R1
    4.1 or prior
      Internet connection
      Installation - initial configuration
      Local networking
      Users - Groups - Directories
      Fileserver - I-Bays
      Web server
      Remote Access
      Partner Zone
      Guaranteed Email
      DNS Hosting
      Virus Protection
      Mp3 Jukebox
  knowledge base
    Article Written
    Needs Article
Performance Tuning
  RT can be quite sensitive to bottlenecks and poor optimisation choices, particularly if the number queues
is high (for example, greater than 50) or the total number of tickets is large (for example, greater than 100k).
Exactly what is 'large' for you depends on many factors. (Someone reported to the rt-users mailing list that
they had an installation of WebRT on a Pentium 100 running FreeBSD, so this site would have a very small
value for 'large' :-)

  A very simple thing to check is the version of RT you are running. If you are well out of date in the current
stable series then you should consider upgrading. Upgrading is usually not too painful a job and there are
regular improvements in RT's performance gained through better coding.

Database Optimisation

  Database tuning is very important. If all your RT tables are indexed correctly, and if transactions are
working properly, and whatever regular maintenance your database requires is being carried out then there
is a much better chance that RT will run smoothly.

Operating System and Environment

  The faster your Unix, the faster RT may run (see the other parts of the Performance Tuning section for
other factors that contribute to RT speed.) So make sure that your Unix is running well. Use vmstat and
iostat (or the equivalents for your OS) to keep an eye on system performance. You'll find a tool such as
Netsaint at http://netsaint.org/ invaluable for keeping ongoing records of key system performance indicators
at regular intervals. It even has pretty graphs.

  RT needs a responsive Apache/Perl web server installation. This requires matching to your hardware
requirements. If you have a small server, look at tuning Apache with the start servers and spare servers
command. If you have large amounts of memory and you're getting lots of simultaneous incoming requests,
increase the number of waiting servers.

  Watch your logging. Apache and mod_perl can both do a lot of logging if you turn it on, enough to
significantly affect performance. If many of your connections are from the Internet you may wish to turn off
reverse DNS mapping in Apache.

  If you think you are running tight on resources, have a look at what other services are running. Maybe you
don't need them. If this is a critical server and it is heavily loaded, perhaps you need to split the web/perl
server out from the database server, because they have different optimisation requirements.

Hardware aspects

Extending and Customizing RT

Scrip Actions
Scrip Conditions

  Take a look at http://lists.fsck.com/pipermail/rt-users/2002-February/006509.html this post from the rt-
users mailing list.

Plugging in your own user metadata

Plugging in your own authentication system

 If you define $WebExternalAuth in your config.pm, then rt will trust whatever apache hands it in the
REMOTE_USER variable.

  Unsurprisingly, Apache is nice and powerful and can do just about any kind of auth your looking for. How
to get apache to auth against foo is out of scope for this, but there's reasonable docs on google. Though you
will need “require valid-user” somewhere in your httpd.conf

Tool Reference

Email Gateway

Are there any default templates with RT?

 The default templates are in Configuration / Global / Templates.

What is the purpose of keywords?

  Imagine if you could define multiple area pulldowns per queue, optionally be able to select multiple values
for some areas and could define areas that apply to all queues. That's Keywords. Elsewhere in these online
documents is a better explanation of what they are and how best to work with them.

Why can't users change their password?

  Grant the user the right 'ModifySelf'. Then they should be able to change their password from
"preferences" via the web ui.

Is there a default password for auto-created users to view their ticket?

  As of now, RT doesn't automatically assign passwords to users on account creation. Down the line, the
plan is to assign random passwords and optionally email them to the user. For now, you need to manually
set them.

How do I delete users and groups

   With groups, the lack of a 'delete' button is an oversight which will be corrected. With users, it's a bit more
complex. For referential integrity reasons, you can't delete users, but you can 'disable'. Uncheck the "Let this
user access RT" option in the WebUI. Email is still sent to disabled users by scrips (e.g. if the user created a
ticket, he might get a copy of comments), so you may wish to catch this with an email alias to redirect traffic
from departed users.

Why aren't emails being sent to watchers?

  If the logs say "No recipients found", check that the relevant scrips are setup for the queue. Also make
sure that the watchers are setup properly for the particular queue. The fact that they have the right to watch
things doesn't mean that they _are_ watching them.

Can I send emailed reminders to ticket owners?

  RT doesn't have this functionality by default, but it can be scripted up easily enough. With a combination
of cron entries, scripting skill and the following command syntax:

   '/opt/rt2/bin/rt --summary --limit-status=open --limit-owner=Username'

where Username is replaced by an individual ticket owner's username of course. Check the contributed
software directory at [http://www.fsck.com/pub/rt/contrib/] for scripts to do this.

What's that Sender: header, and how do I make it go away?

  The Sender header is probably being added by one of 2 things. The perl Mail::Internet module insists on
adding it; and it's generally added by the MTA if the sender is setting a From. So if your apache and rt run
as user www-data, you'll likely end up with headers something like this:

From: Queue <rt-queue@domain>
Sender: <www-data@domain>

  You can avoid Mail::Internet by using sendmailpipe as the delivery message (an option in config.pm). The
next section have MTA-specific information.

sendmail and sender

  Sendmail has a concept of trusted users. I don't have a sendmail machine to test on, but take a look at
[http://www.sendmail.org/m4/tweakingoptions.html] for sendmail tweaking options The section about
confTRUSTED_USERS should do the trick. Your sendmail may just use /etc/mail/trusted-users,
redhat's does.

Sendmail won't let me run rt-mailgate

 If you get an error like the following:

----- The following addresses had permanent fatal errors -----
|”/usr/local/rt/bin/rt-mailgate general action”

----- Transcript of session follows -----
sh: rt-mailgate not available for sendmail programs
554 |”/usr/local/rt/bin/rt-mailgate general action”... Service unavailable

then, the following information from Jesse should help:

 Sendmail has a program called smrsh. smrsh restricts what binaries can
be run from sendmail aliases.

  I think it keeps the programs in /etc/smrsh on redhat6. add a symlink from /usr/local/rt/bin/rt-
mailgate to /etc/smrsh/rt-mailgate and things should work better.

Why is RT so slow?

 Some possible reasons:

 - you may have an old version of SearchBuilder. It got a lot faster at one point
 - your database may lack indexes or be using an old schema. If you're comfordable, you can try to update
the schema or add diffs. otherwise you'll need to export and reimport data.
 - your installation of Apache::DBI may not be operating correctly.

Why are there two Mason Component directories?

 RT defines two variables in config.pm for storing the Web files that HTML::Mason interprets, in
MasonComponentDir and $MasonLocalComponentDir.
  If a file exists in both of these locations, then the copy in the Local Component directory is the one
presented to the user. However, the Local Component directory is only checked if the file and directory
exists in the Main Component directory.

  If you are creating new files (ie, files not in the RT base distribution) to go into the Local Component
directory, remember to create matching dummy files and directories in the Main Component directory.

Why is the owner of a new ticket nobody and not the requestor?

  The default is to assume that a given RT queue is open to anyone, thus the creator of the ticket (the
requestor) is, quite likely, not the person who will be dealing with the ticket (a possible owner). This is true
regardless of the means used to create the ticket. Tickets created via email from a previously-unknown
email address cause a new unprivileged to be created based on the email address, but the owner is still

  Assuming that you have an internal queue where the only people who can create tickets are also the
people who can own tickets, then you could define a Scrip to change the ownership of a ticket to the

How do I delete and re-create my RT database?

  Oh no! You've done something terrible and need to wipe the RT database and start again. Or you are
changing what you use RT for, and don't like the fact that disabled queues and dead tickets from the
previous use are still in the database even though not visible through the web front-end. However, you don't
want to install RT again just to clear the database.

  Go to the installation directory, perhaps something like /usr/src/rt2. Stop Apache (using a command such
as /etc/init.d/apache-perl stop.) As root, enter these commands:

make dropdb              # This destroys the database.
make initialize.Pg       # For Postgresql. MySQL users need “initialize.mysql”
make insert              # This populates DB with default users, templates etc

  Now restart apache-perl and RT should be running with an empty database. The RT root user's password
will be whatever you set in the Makefile or
later in /path/to/rt/etc/config.pm.

How do I list the due date in the home page or queue listing?

 Take a look at etc/config.pm it has a hash which describes what the generic queue looks like. Add
$Ticket->DueAsString to that.

End users
Why don't I receive an email when other watchers do?

 Are you taking into account that RT should never mail the person performing the action? RT tries to be
smart about this. E-mails are not sent to the people taking the actions. When you reply to the ticket, RT will
not send you the reply since you are the one performing the action, and therefore know about it. It will only
notify other users affected by that scrip.
Why doesn't the requestor receive my comments?

  For the simple reason that comments are not intended for the requestor, and RT does it's best to avoid
sending them. Comments are there to let you scream at everybody over how dumb the requestor is, without
him getting a copy.
  If you want the requestor to receive the email, choose 'Reply' or 'Correspond'.

Can an unpriviledged user comment on/reply to the tickets he's requestor for?

  Grant either 'Everyone' or (preferably) 'Requestor' the right to 'CommentOnTicket' and 'ReplyToTicket'

Can I change ticket status/attributes via email?

  This functionality isn't in RT at present. You might want to take a look at enhanced mailgate in

What format do I use for date and time values?

 RT uses a fairly sophisticated date-parser. Most absolute date formats should work.

  A few possibilities include:
- '6/21/2001' may or may not work depending on your regional settings
- 'Tuesday' should work.
- 'In 5 days' might work.
- '13 July 2001 17:00'
- '30 Nov 2001'

How do I send Attachments back to requestors (or to queue watchers) ?

  The default Notify ScripActions that come supplied with RT do not have the ability to actually Attach
anything in outgoing mails. text/plain works (to be Technical, text/plain is the type of RT::Attachment
returned by RT::Transaction->Content() ).

  To overcome this, you can do three things. One is to use the
http://www.fsck.com/pub/rt/contrib/2.0/NotifyWithAttachment.tgz NotifyWithAttachment contrib ScripAction.
This is the reliable method.

  Another is to allow end-users to download attachments from RT itself, and provide links to the attachments
from the RT Web Interface in the outgoing emails. ( this is an easy way out if you don't want to email
attachments to users outside your site )

   Finally, you could always generate the requisite MIME Attachment magic in the outgoing template, a non-
trivial task.

To top