• NAME
• SYNOPSIS
  • CLI
• DESCRIPTION
  • "Delete" vs "Wipeout"
  • Why do you want this?
  • Command line tools (CLI)
  • Web based interface (WebUI)
• DATA STORAGE AND BACKUPS
  • • Restoring from backup
• CONFIGURATION
  • $DependenciesLimit
  • $ShredderStoragePath
• Database Indexes
• INFORMATION FOR DEVELOPERS
  • General API
  • RT::Shredder class' API
    • GENERIC
      • Init
      • new
      • CastObjectsToRecords( Objects => undef )
    • OBJECTS CACHE
      • PutObjects( Objects => undef )
      • PutObject( Object => undef )
      • GetObject, GetState, GetRecord( String => ''| Object => '' )
    • Dependencies resolvers
      • PutResolver, GetResolvers and ApplyResolvers
    • Data storage and backups
      • GetFileName( FileName => '<ISO DATETIME>-XXXX.sql', FromStorage => 1 )
      • StoragePath
• NOTES
  • Database transactions support
  • Foreign keys
• BUGS AND HOW TO CONTRIBUTE
  • Testing
  • Reporting
  • Documentation
  • Todo
  • Repository
• AUTHOR
• COPYRIGHT
• SEE ALSO

NAME

RT::Shredder - Permanently wipeout data from RT

SYNOPSIS

CLI

  rt-shredder --force --plugin 'Tickets=query,Queue="General" and Status="deleted"'

DESCRIPTION

RT::Shredder is extension to RT which allows you to permanently wipeout data from the RT database. Shredder supports the wiping of almost all RT objects (Tickets, Transactions, Attachments, Users...).

"Delete" vs "Wipeout"

RT uses the term "delete" to mean "deactivate". To avoid confusion, RT::Shredder uses the term "Wipeout" to mean "permanently erase" (or what most people would think of as "delete").

Why do you want this?

Normally in RT, "deleting" an item simply deactivates it and makes it invisible from view. This is done to retain full history and auditability of your tickets. For most RT users this is fine and they have no need of RT::Shredder.

But in some large and heavily used RT instances the database can get clogged up with junk, particularly spam. This can slow down searches and bloat the size of the database. For these users, RT::Shredder allows them to completely clear the database of this unwanted junk.

An additional use of Shredder is to obliterate sensitive information (passwords, credit card numbers, ...) which might have made their way into RT.

Command line tools (CLI)

rt-shredder is a program which allows you to wipe objects from command line or with system tasks scheduler (cron, for example). See also 'rt-shredder --help'.

Web based interface (WebUI)

Shredder's WebUI integrates into RT's WebUI. You can find it in the Configuration->Tools->Shredder tab. The interface is similar to the CLI and gives you the same functionality. You can find 'Shredder' link at the bottom of tickets search results, so you could wipeout tickets in the way similar to the bulk update.

DATA STORAGE AND BACKUPS

Shredder allows you to store data you wiped in files as scripts with SQL commands.

Restoring from backup

Should you wipeout something you did not intend to the objects can be restored by using the storage files. These files are a simple set of SQL commands to re-insert your objects into the RT database.

1) Locate the appropriate shredder SQL dump file. In the WebUI, when you use shredder, the path to the dump file is displayed. It also gives the option to download the dump file after each wipeout. Or it can be found in your $ShredderStoragePath.

2) Load the shredder SQL dump into your RT database. The details will be different for each database and RT configuration, consult your database manual and RT config. For example, in MySQL...

    mysql -u your_rt_user -p your_rt_database < /path/to/rt/var/data/shredder/dump.sql

That's it.i This will restore everything you'd deleted during a shredding session when the file had been created.

CONFIGURATION

$DependenciesLimit

Shredder stops with an error if the object has more than $DependenciesLimit dependencies. For example: a ticket has 1000 transactions or a transaction has 1000 attachments. This is protection from bugs in shredder from wiping out your whole database, but sometimes when you have big mail loops you may hit it.

Defaults to 1000. To change this (for example, to 10000) add the following to your RT_SiteConfig.pm:

    Set( $DependenciesLimit, 10_000 );>

$ShredderStoragePath

Directory containing Shredder backup dumps; defaults to /opt/rt4/var/data/RT-Shredder (assuming an /opt/rt4 installation).

To change this (for example, to /some/backup/path) add the following to your RT_SiteConfig.pm:

    Set( $ShredderStoragePath, "/some/backup/path" );>

Be sure to specify an absolute path.

Database Indexes

We have found that the following indexes significantly speed up shredding on most databases.

    CREATE INDEX SHREDDER_CGM1 ON CachedGroupMembers(MemberId, GroupId, Disabled);
    CREATE INDEX SHREDDER_CGM2 ON CachedGroupMembers(ImmediateParentId,MemberId);
    CREATE INDEX SHREDDER_CGM3 on CachedGroupMembers (Via, Id);

    CREATE UNIQUE INDEX SHREDDER_GM1 ON GroupMembers(MemberId, GroupId);

    CREATE INDEX SHREDDER_TXN1 ON Transactions(ReferenceType, OldReference);
    CREATE INDEX SHREDDER_TXN2 ON Transactions(ReferenceType, NewReference);
    CREATE INDEX SHREDDER_TXN3 ON Transactions(Type, OldValue);
    CREATE INDEX SHREDDER_TXN4 ON Transactions(Type, NewValue);

    CREATE INDEX SHREDDER_ATTACHMENTS1 ON Attachments(Creator);

INFORMATION FOR DEVELOPERS

General API

RT::Shredder is an extension to RT which adds shredder methods to RT objects and classes. The API is not well documented yet, but you can find usage examples in rt-shredder and the lib/t/regression/shredder/*.t test files.

However, here is a small example that do the same action as in CLI example from "SYNOPSIS":

  use RT::Shredder;
  RT::Shredder::Init( force => 1 );
  my $deleted = RT::Tickets->new( RT->SystemUser );
  $deleted->{'allow_deleted_search'} = 1;
  $deleted->LimitQueue( VALUE => 'general' );
  $deleted->LimitStatus( VALUE => 'deleted' );
  while( my $t = $deleted->Next ) {
      $t->Wipeout;
  }

RT::Shredder class' API

RT::Shredder implements interfaces to objects cache, actions on the objects in the cache and backups storage.

GENERIC

Init

    RT::Shredder::Init( %default_options );

RT::Shredder::Init() should be called before creating an RT::Shredder object. It iniitalizes RT and loads the RT configuration.

%default_options are passed to every <RT::Shredder-new>> call.

new

  my $shredder = RT::Shredder->new(%options);

Construct a new RT::Shredder object.

There currently are no %options.

CastObjectsToRecords( Objects => undef )

Cast objects to the RT::Record objects or its ancesstors. Objects can be passed as SCALAR (format <class>-<id>), ARRAY, RT::Record ancesstors or RT::SearchBuilder ancesstor.

Most methods that takes Objects argument use this method to cast argument value to list of records.

Returns an array of records.

For example:

    my @objs = $shredder->CastObjectsToRecords(
        Objects => [             # ARRAY reference
            'RT::Attachment-10', # SCALAR or SCALAR reference
            $tickets,            # RT::Tickets object (isa RT::SearchBuilder)
            $user,               # RT::User object (isa RT::Record)
        ],
    );

OBJECTS CACHE

PutObjects( Objects => undef )

Puts objects into cache.

Returns array of the cache entries.

See CastObjectsToRecords method for supported types of the Objects argument.

PutObject( Object => undef )

Puts record object into cache and returns its cache entry.

NOTE that this method support only RT::Record object or its ancesstor objects, if you want put mutliple objects or objects represented by different classes then use PutObjects method instead.

GetObject, GetState, GetRecord( String => ''| Object => '' )

Returns record object from cache, cache entry state or cache entry accordingly.

All three methods takes String (format <class>-<id>) or Object argument. String argument has more priority than Object so if it's not empty then methods leave Object argument unchecked.

You can read about possible states and their meanings in RT::Shredder::Constants docs.

Dependencies resolvers

PutResolver, GetResolvers and ApplyResolvers

TODO: These methods have no documentation.

Data storage and backups

GetFileName( FileName => '<ISO DATETIME>-XXXX.sql', FromStorage => 1 )

Takes desired FileName and flag FromStorage then translate file name to absolute path by next rules:

* Default value of the FileName option is <ISO DATETIME>-XXXX.sql;

* if FileName has XXXX (exactly four uppercase X letters) then it would be changed with digits from 0000 to 9999 range, with first one free value;

* if FileName has %T then it would be replaced with the current date and time in the YYYY-MM-DDTHH:MM:SS format. Note that using %t may still generate not unique names, using XXXX recomended.

* if FromStorage argument is true (default behaviour) then result path would always be relative to StoragePath;

* if FromStorage argument is false then result would be relative to the current dir unless it's already absolute path.

Returns an absolute path of the file.

Examples: # file from storage with default name format my $fname = $shredder->GetFileName;

    # file from storage with custom name format
    my $fname = $shredder->GetFileName( FileName => 'shredder-XXXX.backup' );

    # file with path relative to the current dir
    my $fname = $shredder->GetFileName(
        FromStorage => 0,
        FileName => 'backups/shredder.sql',
    );

    # file with absolute path
    my $fname = $shredder->GetFileName(
        FromStorage => 0,
        FileName => '/var/backups/shredder-XXXX.sql'
    );

StoragePath

Returns an absolute path to the storage dir. See "$ShredderStoragePath".

See also description of the "GetFileName" method.

NOTES

Database transactions support

Since 0.03_01 RT::Shredder uses database transactions and should be much safer to run on production servers.

Foreign keys

Mainstream RT doesn't use FKs, but at least I posted DDL script that creates them in mysql DB, note that if you use FKs then this two valid keys don't allow delete Tickets because of bug in MySQL:

  ALTER TABLE Tickets ADD FOREIGN KEY (EffectiveId) REFERENCES Tickets(id);
  ALTER TABLE CachedGroupMembers ADD FOREIGN KEY (Via) REFERENCES CachedGroupMembers(id);

http://bugs.mysql.com/bug.php?id=4042

BUGS AND HOW TO CONTRIBUTE

We need your feedback in all cases: if you use it or not, is it works for you or not.

Testing

Don't skip make test step while install and send me reports if it's fails. Add your own tests, it's easy enough if you've writen at list one perl script that works with RT. Read more about testing in t/utils.pl.

Reporting

Send reports to "AUTHOR" or to the RT mailing lists.

Documentation

Many bugs in the docs: insanity, spelling, gramar and so on. Patches are wellcome.

Todo

Please, see Todo file, it has some technical notes about what I plan to do, when I'll do it, also it describes some problems code has.

Repository

Since RT-3.7 shredder is a part of the RT distribution. Versions of the RTx::Shredder extension could be downloaded from the CPAN. Those work with older RT versions or you can find repository at https://opensvn.csie.org/rtx_shredder

AUTHOR

    Ruslan U. Zakirov <Ruslan.Zakirov@gmail.com>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the Perl distribution.

SEE ALSO

rt-shredder, rt-validator

← Back to index