• RTIR Administrative Tutorial
  • General Configuration
  • Blocks Queue
  • Status
  • Custom Fields
  • Managing "RT at a glance" and "RTIR at a glance" pages
  • Notifications
  • Scrips
  • Templates
  • Locking
  • Aging
  • Maintaining DB size, deleting entries, restoring deleted data
  • GnuPG support
    • Reverification
    • Key selection
    • Missing passphrase
  • Service Level Agreements (SLAs)

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 site-specific configurations.

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

Blocks Queue

You may disable the Blocks queue by putting the following into your RT_SiteConfig.pm config:

    Set($RTIR_DisableBlocksQueue, 1);

You will probably also want to disable the Queue using the RT Administrative interface. Tools -> Configuration -> Queues -> Blocks, uncheck Enabled and click Save Changes.

Status

The various states an incident, IR, investigation, or block 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 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 can not be renamed, disabled or un-applied, but other fields can be.

Constituency

The constituency of an incident, IR, investigation, or block.

Additional quite heavy automation is tied to this field. This is described in 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 block.

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.

See also "SetIPFromContent" below.

Netmask

Network mask for a Block.

Port

Port for a Block.

Where Blocked

Where the block is placed.

Customer

Customer for an IR or Investigation.

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 the Incident Reports queue. 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 Block

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

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

See also the $RTIR_BlockAproveActionRegexp 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.

ResolveAllChildren

Applies to the Incidents queue.

If an incident is changed to an inactive status, looks for linked tickets in the Incident Reports, Investigations or Blocks 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

Applies to the Incidents queue.

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

Applies to the Incident Reports, Blocks and Investigations queues.

When the Owner of a ticket in these queues is changed, that change is also applied to the linked incident.

ReopenIncident

Applies to the Incident Reports, Blocks and Investigations queues.

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

SetDefaultIncidentResolution

Applies to the Incidents queue.

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 the Blocks queue.

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

SetIPFromContent

Applies to the Incident Reports, Blocks, Incidents and Investigations queues.

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.

SetConstituency

Applies to the Incident Reports, Blocks, Incidents and Investigations queues.

Uses the Constituency algorithms discussed in docs/Constituencies.pod to set and propagate changes to the Constituency custom field. On ticket creation, Constituency is set based on the parent ticket, the X-RT-Mail-Extension header (see docs/Constituencies.pod) or the default set in your RTIR_Config.pm

When linking tickets or changing the Constituency custom field, this scrip ensures that the change is propagated based on your choice of _RTIR_Constituency_Propagation in your RTIR_Config.pm

SetConstituencyGroup

Applies to the Incident Reports, Blocks, Incidents and Investigations queues.

When tickets are created, or the Constituency custom field is updated, this scrip manages the assignment of DutyTeam groups as AdminCcs. It makes sure that for a Constituency EDUNET, a DutyTeam group named 'DutyTeam EDUNET' is assigned as AdminCc and removes other DutyTeam groups from the AdminCc. "ACLs" in Constituencies discusses how to use these groups.

Templates

Autoreply in Blocks queue

This template is sent when a block is created.

BlockRemoved in Blocks queue

This template is sent when a block 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 support

GnuPG integration is now a feature of RT. Configuration can be done in your RT_SiteConfig.pm. See also the documentation in RT::Crypt::GnuPG.

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 RTIR_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.

If you install and configure RT::Extension::SLA do not apply it to the Incidents queue. You will encounter a race condition between the extension 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 SLA extension, you can disable the RTIR scrips that manage due dates on the Incidents queue.

← Back to index