RT 4.2.5 Documentation
RT::Shredder
- NAME
- SYNOPSIS
- DESCRIPTION
- DATA STORAGE AND BACKUPS
- CONFIGURATION
- Database Indexes
- INFORMATION FOR DEVELOPERS
- NOTES
- BUGS AND HOW TO CONTRIBUTE
- 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 Admin->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)
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.