RTIR 5.0.6 Documentation

AdministrationTutorial

RTIR Administrative Tutorial

RTIR Administrative Tutorial

General Configuration

RT and RTIR store many configuration items in configuration files on the file system in the etc directory in your RT directory. RT_Config.pm and RTIR_Config.pm provide documentation on all available configuration options and also set system defaults. You can view these files to see what configuration options are available, but don't edit these files to change configuration values. The RT_SiteConfig.pm file is specifically provided to store your core site-specific configurations and you may create RTIR_SiteConfig.pm for customizations to configuration declared in RTIR_Config.pm. RTIR_SiteConfig.pm is normally created in /opt/rt5/etc/.

To change a configuration value, copy the Set code from RT_Config.pm or RTIR_Config.pm and add it to the relevant Site Config. Then set your custom configuration values there.

Countermeasures Feature

You may disable the Countermeasures feature by putting the following into your RTIR_SiteConfig.pm config:

    Set($RTIR_DisableCountermeasures, 1);

You will probably also want to disable any Countermeasures queues using the RT Administrative interface. Tools -> Configuration -> Queues -> (select one), uncheck Enabled and click Save Changes.

Status

The various states an incident, incident report, investigation, or countermeasure can be in, such as 'open', 'stalled', 'abandoned', etc.

This field contains custom statuses for tickets, and values are different in different queues. The status values are set via the %Lifecycles option in the RTIR configuration file. You can read more about Lifecycles in the RT_Config.pm file.

Status is a critical field for functionality.

For more information, read the description in RTIR_Config.pm and description of "Scrips" below.

Custom Queues

While RTIR ships with four queues by default (Incident Reports, Incidents, Investigations, and Countermeasures) you can create your own versions of these queues. This functionality (new in RTIR 4.0) is what powers the Constituencies feature, but its use is not limited to Constituencies. For example you can have multiple queues for Incident Reports, one for each of your monitoring tools, each with its own set of custom fields, watchers, automation with scrips, templates, watchers, etc.

To create a new RTIR queue, visit RT's Admin -> Queue -> Create menu. Create the queue as normal, but be sure to select an RTIR lifecycle (incident_reports, incidents, investigations, or countermeasures). By doing so you include the queue into the RTIR system. After creating the queue, it will be available throughout RTIR alongside the four builtin incident response queues. Assign custom fields, watchers, etc. as desired.

Custom Fields

When RTIR is installed, several custom fields are created and applied to queues in RTIR. Some of these custom fields are important for RTIR functionality and must not be renamed, disabled or un-applied, but other fields can be.

RTIR Constituency

The constituency of a queue.

Heavy automation is tied to this field. This is described in the Constituencies doc. Don't rename this field if you want to use this functionality.

Description

Short description of an Incident.

Resolution

How an Incident was or wasn't resolved.

Function

Who is handling the Incident.

Classification

The type of Incident, such as system compromise or denial of service.

How Reported

How the IR got into RTIR.

ReporterType

Context for the incident reporter, such as the police, other ISP, or external individual.

IP

IP addresses related to the incident, IR, investigation, or countermeasure.

Don't rename this custom field or it will lose all associated features. It's possible to change this CF from multiple values to single value.

See "IP" in Tutorial for more information.

Documenting Process for Incidents

Starting in version 5.0.4, RT supports a feature called Process Articles that allows you to document the process for working on a ticket, and display it right on the page. The process is managed in an article, and which article to show is determined by a field on the ticket.

Starting in RTIR 5.0.4 this feature is available for Incidents. The default Classification field contains values to indicate the type of the incident. You can set up an article for each of the Classification values to document how that type of incident should be handled. Once configured, this documentation will be shown right on the incident page.

The configuration options ProcessArticleFields and ProcessArticleMapping set the article class to use and also determine the mapping between the Classification values and corresponding articles. If you have added or removed Classification values, you can update this configuration with your new settings.

Articles are created in a class called Incidents Processes by default, and members of the DutyTeam group can see and modify these articles. You can change the rights on the class if you want to restrict who can update the documentation.

Edit the articles to add your actual process docuemtnation. Note that if you change the article Name field, you need to update the %ProcessArticleMapping setting mentioned above because it uses the article name.

This feature is optional and can be disabled by clearing the configuration options linked above.

Managing "RT at a glance" and "RTIR at a glance" pages

In the config you can set the @RTIR_HomepageComponents option to control allowed portlets people can add to thier workspace. RT has its own option $HomepageComponents so you can list different sets for RT and RTIR. See Tutorial for more information.

Notifications

Almost all email notifications in RT/RTIR are controlled via scrips.

There are three default base actions you can use to notify users:

Notify: Sends a notification to users. The reply-to field is set based on the correspond address. The NotifyActor option also influences the set of recipients.
Notify As Comment: Similar to 'Notify', but the reply-to field is set based on the comment address.
Autoreply: A variation of the 'Notify' action which sends email even if the NotifyActor option is disabled.

The above actions have multiple variants with different list of recipients, for example 'Notify Owner' or 'Notify Requestors'. The list of recipients may contain the following values: 'Requestors', 'Owner', 'Ccs', 'AdminCcs' and 'Other Recipients'. 'Other Recipients' is the only special case, these are users who are listed as one-time recipients on the ticket's reply/comment pages. All other entries are watchers of a ticket. The list can be a combination of values like 'Owner, Ccs, AdminCcs'.

Here are several examples:

    On Correspond Notify Requestors and Ccs with template Correspondence
    On Create Autoreply To Requestors with template Autoreply
    On Owner Change Notify Owner with template Transaction

Text of notifications is controlled using templates where a queue's template can override the global one. For example you can create a template 'Correspondence' in a queue and all notifications (global or queue specific) will use that template instead of the global template.

Scrips

Scrips run for every transaction on a ticket in RT and RTIR, sometimes changing values based on the transaction being performed. Transactions are any change to a ticket, whether updating a status or replying to a requestor.

SetHowReported

Applies to Incident Reports. On ticket creation, sets the HowReported custom field to a default value of Email if it isn't otherwise specified.

On Correspond Change Status of the Countermeasure

On replies, changes the status of countermeasures according to a few rules that are described in "DESCRIPTION" in RT::Action::RTIR_SetCountermeasureStatus.

RT's default RT::Action::AutoOpen is disabled for countermeasures to avoid unwanted changes of status from 'pending activation' to 'active'.

See also the $RTIR_CountermeasureApproveActionRegexp option in the config.

On Linking To Incident Activate Report

On Correspond (not every) Activate Report

IRs are activated (status changed to first possible active status, by default 'open') only when they are linked to an incident. These two scrips take care of that.

RT's default RT::Action::AutoOpen is disabled for IRs to avoid unwanted changes of status when an IR is not linked. When an IR is linked to an Incident, RT::Condition::RTIR_RequireReportActivation checks everything that RT's AutoOpen checks and the scrip behaves in the same way.

Set Due Date On Incident

Keeps the Due date of incidents in sync with the most due child.

See "Service Level Agreements (SLAs)" below for details on automating Due dates, and RT::Action::RTIR_SetDueIncident for details about action of the scrip.

It is now possible to edit the Due date of Incidents manually, however editing a child's Due Date will disable this (and Incident Due dates are not copied down to Children).

ResolveAllChildren

Applies to Incidents.

If an incident is changed to an inactive status, looks for linked tickets in Incident Reports, Investigations or Countermeasures queues and resolves them. If any of these linked tickets are linked to other ongoing incidents, a comment is added and they remain unresolved.

FixOwnership

For Incidents: When the Owner of an incident is changed, the Owner of linked children tickets are changed to the same owner.

For Incident Reports, Countermeasures and Investigations: When the Owner of a ticket in such queues is changed, that change is also applied to the linked Incident.

ReopenIncident

Applies to Incident Reports, Countermeasures and Investigations.

If the status of a ticket in such queues is changed from rejected or resolved, the linked parent Incident ticket status is set to open.

SetDefaultIncidentResolution

Applies to Incidents.

When an incident's status is changed, if it is changed from an inactive status to an active status, the Resolution custom field is cleared. If it is changed from an active status to an inactive status and the Resolution custom field isn't set manually, it is set to the value set in %RTIR_CustomFieldsDefaults in your RTIR_Config.pm.

NotifyOnClose

Applies to Countermeasures.

When a countermeasure ticket is moved from an active status to an inactive status (closed), the requestors on the countermeasure are notified using the "CountermeasureRemoved in Countermeasure queue" in Templates template.

SetIPFromContent

Applies to Incident Reports, Countermeasures, Incidents and Investigations.

Updates the ticket custom field IP to have a list of all IPs and IP ranges found in the body of the ticket during Create and Correspond.

If configuration of the CF allows only one value then only first IP from the content is used.

It's OK to disable this scrip.

Templates

Autoreply in Countermeasures queue: This template is sent when a countermeasure is created.
CountermeasureRemoved in Countermeasure queue: This template is sent when a countermeasure is removed.
Autoreply in Investigations queue: This template is sent when a new investigation is launched.

Locking

See the documentation for RT::Extension::TicketLocking

Aging

See the documentation for RT::Extension::TicketAging

Maintaining DB size, deleting entries, restoring deleted data

During normal operation RT/RTIR never deletes data from the database. Since RT 3.7 the RTx::Shredder extension has been integrated into RT. This extension can remove data such as users or tickets from the RT/RTIR system. You can find documentation for this extension in RT::Shredder by running `perldoc lib/RT/Shredder.pm` or on the Best Practical website at http://bestpractical.com/rt/docs/latest/RT/Shredder.html. RT::Shredder's documentation includes information on restoring deleted data from backups. RT::Shredder provides SQL commands to reverse any delete operations, so any data that it deletes may be restored.

GnuPG and S/MIME support

GnuPG and S/MIME integration is a core feature of RT. Configuration can be done in your RT_SiteConfig.pm. See also the documentation in RT::Crypt.

Reverification

RTIR supports reverification of incoming email. If a user sends signed mail but RTIR doesn't have his public key (or if some other error occurs), then his message will be be processed, but there will be "This message is unverified" warnings in the UI. Afterwards, RTIR will automatically attempt to reverify that message whenever someone views it.

Key selection

Sometimes a user will have multiple public keys in RTIR's GPG database. When that happens, RTIR has the user writing the message decide which key to use when sending that user encrypted mail. They are listed as fingerprints along with their trust levels. If only one key is valid, then RTIR will automatically choose it instead of asking the user.

If a user has no trusted keys, then the web interface will warn and refuse to send him an encrypted message. This is ultimately due to limitations in GnuPG: we cannot encrypt a message with an untrusted key. Managing the trust levels of keys must be done outside of RT as there is not currently key management support available.

Missing passphrase

If RTIR is asked to sign an outgoing message and the passphrase is unavailable, it will detect this and avoid sending any email. The user will be asked to notify a system administrator.

A missing passphrase occurs when GPG Agent is unresponsive or the passphrase is wrong in RT_SiteConfig.pm. Note that you can use either GPG Agent or set the passphrase in the site config, you need not do both.

Service Level Agreements (SLAs)

RTIR used to have a simple Service Level Agreements (SLA) implementation. RT::Extension::SLA was prototyped on it, but vastly improved. In RTIR 3.0 we removed the SLA implementation in the core of RTIR that was in conflict with the extension.

RT 4.4 has cored RT::Extension::SLA, please disable SLA on Incidents. You will encounter a race condition between the core SLA and the RTIR scrips that synchronize due dates between an incident and its most due active child. If you need to manage incident due dates using the core SLA, you can disable the RTIR scrips that manage due dates on Incidents.

← Back to index