/usr/share/doc/rt4-doc-html/RT/Shredder.html is in rt4-doc-html 4.4.2-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 | <ul id="index">
<li><a href="#NAME">NAME</a></li>
<li><a href="#SYNOPSIS">SYNOPSIS</a>
<ul>
<li><a href="#CLI">CLI</a></li>
</ul>
</li>
<li><a href="#DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#Delete-vs-Wipeout">"Delete" vs "Wipeout"</a></li>
<li><a href="#Why-do-you-want-this">Why do you want this?</a></li>
<li><a href="#Command-line-tools-CLI">Command line tools (CLI)</a></li>
<li><a href="#Web-based-interface-WebUI">Web based interface (WebUI)</a></li>
</ul>
</li>
<li><a href="#DATA-STORAGE-AND-BACKUPS">DATA STORAGE AND BACKUPS</a>
<ul>
<li>
<ul>
<li><a href="#Restoring-from-backup">Restoring from backup</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#CONFIGURATION">CONFIGURATION</a>
<ul>
<li><a href="#DependenciesLimit">$DependenciesLimit</a></li>
<li><a href="#ShredderStoragePath">$ShredderStoragePath</a></li>
</ul>
</li>
<li><a href="#Database-Indexes">Database Indexes</a></li>
<li><a href="#INFORMATION-FOR-DEVELOPERS">INFORMATION FOR DEVELOPERS</a>
<ul>
<li><a href="#General-API">General API</a></li>
<li><a href="#RT::Shredder-class-API">RT::Shredder class' API</a>
<ul>
<li><a href="#GENERIC">GENERIC</a>
<ul>
<li><a href="#Init">Init</a></li>
<li><a href="#new">new</a></li>
<li><a href="#CastObjectsToRecords-Objects-undef">CastObjectsToRecords( Objects => undef )</a></li>
</ul>
</li>
<li><a href="#OBJECTS-CACHE">OBJECTS CACHE</a>
<ul>
<li><a href="#PutObjects-Objects-undef">PutObjects( Objects => undef )</a></li>
<li><a href="#PutObject-Object-undef">PutObject( Object => undef )</a></li>
<li><a href="#GetObject-GetState-GetRecord-String-Object">GetObject, GetState, GetRecord( String => ''| Object => '' )</a></li>
</ul>
</li>
<li><a href="#Dependencies-resolvers">Dependencies resolvers</a>
<ul>
<li><a href="#PutResolver-GetResolvers-and-ApplyResolvers">PutResolver, GetResolvers and ApplyResolvers</a></li>
</ul>
</li>
<li><a href="#Data-storage-and-backups">Data storage and backups</a>
<ul>
<li><a href="#GetFileName-FileName-ISO-DATETIME-XXXX.sql-FromStorage-1">GetFileName( FileName => '<ISO DATETIME>-XXXX.sql', FromStorage => 1 )</a></li>
<li><a href="#StoragePath">StoragePath</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="#NOTES">NOTES</a>
<ul>
<li><a href="#Database-transactions-support">Database transactions support</a></li>
<li><a href="#Foreign-keys">Foreign keys</a></li>
</ul>
</li>
<li><a href="#BUGS-AND-HOW-TO-CONTRIBUTE">BUGS AND HOW TO CONTRIBUTE</a>
<ul>
<li><a href="#Testing">Testing</a></li>
<li><a href="#Reporting">Reporting</a></li>
<li><a href="#Documentation">Documentation</a></li>
<li><a href="#Todo">Todo</a></li>
<li><a href="#Repository">Repository</a></li>
</ul>
</li>
<li><a href="#AUTHOR">AUTHOR</a></li>
<li><a href="#COPYRIGHT">COPYRIGHT</a></li>
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
</ul>
<h1 id="NAME"><a href="#___top">NAME</a></h1>
<p>RT::Shredder - Permanently wipeout data from RT</p>
<h1 id="SYNOPSIS"><a href="#___top">SYNOPSIS</a></h1>
<h2 id="CLI"><a href="#___top">CLI</a></h2>
<pre><code> rt-shredder --force --plugin 'Tickets=query,Queue="General" and Status="deleted"'</code></pre>
<h1 id="DESCRIPTION"><a href="#___top">DESCRIPTION</a></h1>
<p>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...).</p>
<h2 id="Delete-vs-Wipeout"><a href="#___top">"Delete" vs "Wipeout"</a></h2>
<p>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").</p>
<h2 id="Why-do-you-want-this"><a href="#___top">Why do you want this?</a></h2>
<p>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.</p>
<p>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.</p>
<p>An additional use of Shredder is to obliterate sensitive information (passwords, credit card numbers, ...) which might have made their way into RT.</p>
<h2 id="Command-line-tools-CLI"><a href="#___top">Command line tools (CLI)</a></h2>
<p><a href="../rt-shredder.html">rt-shredder</a> 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'.</p>
<h2 id="Web-based-interface-WebUI"><a href="#___top">Web based interface (WebUI)</a></h2>
<p>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.</p>
<h1 id="DATA-STORAGE-AND-BACKUPS"><a href="#___top">DATA STORAGE AND BACKUPS</a></h1>
<p>Shredder allows you to store data you wiped in files as scripts with SQL commands.</p>
<h3 id="Restoring-from-backup"><a href="#___top">Restoring from backup</a></h3>
<p>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.</p>
<p>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 <code>$ShredderStoragePath</code>.</p>
<p>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...</p>
<pre><code> mysql -u your_rt_user -p your_rt_database < /path/to/rt/var/data/shredder/dump.sql</code></pre>
<p>That's it.i This will restore everything you'd deleted during a shredding session when the file had been created.</p>
<h1 id="CONFIGURATION"><a href="#___top">CONFIGURATION</a></h1>
<h2 id="DependenciesLimit"><a href="#___top">$DependenciesLimit</a></h2>
<p>Shredder stops with an error if the object has more than <code>$DependenciesLimit</code> 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.</p>
<p>Defaults to 1000. To change this (for example, to 10000) add the following to your <i>RT_SiteConfig.pm</i>:</p>
<pre><code> Set( $DependenciesLimit, 10_000 );></code></pre>
<h2 id="ShredderStoragePath"><a href="#___top">$ShredderStoragePath</a></h2>
<p>Directory containing Shredder backup dumps; defaults to <i>/opt/rt4/var/data/RT-Shredder</i> (assuming an /opt/rt4 installation).</p>
<p>To change this (for example, to /some/backup/path) add the following to your <i>RT_SiteConfig.pm</i>:</p>
<pre><code> Set( $ShredderStoragePath, "/some/backup/path" );></code></pre>
<p>Be sure to specify an absolute path.</p>
<h1 id="Database-Indexes"><a href="#___top">Database Indexes</a></h1>
<p>We have found that the following indexes significantly speed up shredding on most databases.</p>
<pre><code> 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);</code></pre>
<h1 id="INFORMATION-FOR-DEVELOPERS"><a href="#___top">INFORMATION FOR DEVELOPERS</a></h1>
<h2 id="General-API"><a href="#___top">General API</a></h2>
<p><a href="../../../rt/latest/RT/Shredder.html">RT::Shredder</a> 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 <a href="../rt-shredder.html">rt-shredder</a> and the <i>lib/t/regression/shredder/*.t</i> test files.</p>
<p>However, here is a small example that do the same action as in CLI example from <a href="#SYNOPSIS">"SYNOPSIS"</a>:</p>
<pre><code> 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;
}</code></pre>
<h2 id="RT::Shredder-class-API"><a href="#___top">RT::Shredder class' API</a></h2>
<p><a href="../../../rt/latest/RT/Shredder.html">RT::Shredder</a> implements interfaces to objects cache, actions on the objects in the cache and backups storage.</p>
<h3 id="GENERIC"><a href="#___top">GENERIC</a></h3>
<h4 id="Init"><a href="#___top">Init</a></h4>
<pre><code> RT::Shredder::Init( %default_options );</code></pre>
<p><code>RT::Shredder::Init()</code> should be called before creating an RT::Shredder object. It iniitalizes RT and loads the RT configuration.</p>
<p>%default_options are passed to every <code><RT::Shredder-</code>new>> call.</p>
<h4 id="new"><a href="#___top">new</a></h4>
<pre><code> my $shredder = RT::Shredder->new(%options);</code></pre>
<p>Construct a new RT::Shredder object.</p>
<p>There currently are no %options.</p>
<h4 id="CastObjectsToRecords-Objects-undef"><a href="#___top">CastObjectsToRecords( Objects => undef )</a></h4>
<p>Cast objects to the <code>RT::Record</code> objects or its ancesstors. Objects can be passed as SCALAR (format <code><class>-<id></code>), ARRAY, <code>RT::Record</code> ancesstors or <code>RT::SearchBuilder</code> ancesstor.</p>
<p>Most methods that takes <code>Objects</code> argument use this method to cast argument value to list of records.</p>
<p>Returns an array of records.</p>
<p>For example:</p>
<pre><code> 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)
],
);</code></pre>
<h3 id="OBJECTS-CACHE"><a href="#___top">OBJECTS CACHE</a></h3>
<h4 id="PutObjects-Objects-undef"><a href="#___top">PutObjects( Objects => undef )</a></h4>
<p>Puts objects into cache.</p>
<p>Returns array of the cache entries.</p>
<p>See <code>CastObjectsToRecords</code> method for supported types of the <code>Objects</code> argument.</p>
<h4 id="PutObject-Object-undef"><a href="#___top">PutObject( Object => undef )</a></h4>
<p>Puts record object into cache and returns its cache entry.</p>
<p><b>NOTE</b> that this method support <b>only <code>RT::Record</code> object or its ancesstor objects</b>, if you want put mutliple objects or objects represented by different classes then use <code>PutObjects</code> method instead.</p>
<h4 id="GetObject-GetState-GetRecord-String-Object"><a href="#___top">GetObject, GetState, GetRecord( String => ''| Object => '' )</a></h4>
<p>Returns record object from cache, cache entry state or cache entry accordingly.</p>
<p>All three methods takes <code>String</code> (format <code><class>-<id></code>) or <code>Object</code> argument. <code>String</code> argument has more priority than <code>Object</code> so if it's not empty then methods leave <code>Object</code> argument unchecked.</p>
<p>You can read about possible states and their meanings in <a href="../../../rt/latest/RT/Shredder/Constants.html">RT::Shredder::Constants</a> docs.</p>
<h3 id="Dependencies-resolvers"><a href="#___top">Dependencies resolvers</a></h3>
<h4 id="PutResolver-GetResolvers-and-ApplyResolvers"><a href="#___top">PutResolver, GetResolvers and ApplyResolvers</a></h4>
<p>TODO: These methods have no documentation.</p>
<h3 id="Data-storage-and-backups"><a href="#___top">Data storage and backups</a></h3>
<h4 id="GetFileName-FileName-ISO-DATETIME-XXXX.sql-FromStorage-1"><a href="#___top">GetFileName( FileName => '<ISO DATETIME>-XXXX.sql', FromStorage => 1 )</a></h4>
<p>Takes desired <code>FileName</code> and flag <code>FromStorage</code> then translate file name to absolute path by next rules:</p>
<p>* Default value of the <code>FileName</code> option is <code><ISO DATETIME>-XXXX.sql</code>;</p>
<p>* if <code>FileName</code> has <code>XXXX</code> (exactly four uppercase <code>X</code> letters) then it would be changed with digits from 0000 to 9999 range, with first one free value;</p>
<p>* if <code>FileName</code> has <code>%T</code> then it would be replaced with the current date and time in the <code>YYYY-MM-DDTHH:MM:SS</code> format. Note that using <code>%t</code> may still generate not unique names, using <code>XXXX</code> recomended.</p>
<p>* if <code>FromStorage</code> argument is true (default behaviour) then result path would always be relative to <code>StoragePath</code>;</p>
<p>* if <code>FromStorage</code> argument is false then result would be relative to the current dir unless it's already absolute path.</p>
<p>Returns an absolute path of the file.</p>
<p>Examples: # file from storage with default name format my $fname = $shredder->GetFileName;</p>
<pre><code> # 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'
);</code></pre>
<h4 id="StoragePath"><a href="#___top">StoragePath</a></h4>
<p>Returns an absolute path to the storage dir. See <a href="#ShredderStoragePath">"$ShredderStoragePath"</a>.</p>
<p>See also description of the <a href="#GetFileName">"GetFileName"</a> method.</p>
<h1 id="NOTES"><a href="#___top">NOTES</a></h1>
<h2 id="Database-transactions-support"><a href="#___top">Database transactions support</a></h2>
<p>Since 0.03_01 RT::Shredder uses database transactions and should be much safer to run on production servers.</p>
<h2 id="Foreign-keys"><a href="#___top">Foreign keys</a></h2>
<p>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:</p>
<pre><code> ALTER TABLE Tickets ADD FOREIGN KEY (EffectiveId) REFERENCES Tickets(id);
ALTER TABLE CachedGroupMembers ADD FOREIGN KEY (Via) REFERENCES CachedGroupMembers(id);</code></pre>
<p><a href="http://bugs.mysql.com/bug.php?id=4042">http://bugs.mysql.com/bug.php?id=4042</a></p>
<h1 id="BUGS-AND-HOW-TO-CONTRIBUTE"><a href="#___top">BUGS AND HOW TO CONTRIBUTE</a></h1>
<p>We need your feedback in all cases: if you use it or not, is it works for you or not.</p>
<h2 id="Testing"><a href="#___top">Testing</a></h2>
<p>Don't skip <code>make test</code> 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 <i>t/utils.pl</i>.</p>
<h2 id="Reporting"><a href="#___top">Reporting</a></h2>
<p>Send reports to <a href="#AUTHOR">"AUTHOR"</a> or to the RT mailing lists.</p>
<h2 id="Documentation"><a href="#___top">Documentation</a></h2>
<p>Many bugs in the docs: insanity, spelling, gramar and so on. Patches are wellcome.</p>
<h2 id="Todo"><a href="#___top">Todo</a></h2>
<p>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.</p>
<h2 id="Repository"><a href="#___top">Repository</a></h2>
<p>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 <a href="https://opensvn.csie.org/rtx_shredder">https://opensvn.csie.org/rtx_shredder</a></p>
<h1 id="AUTHOR"><a href="#___top">AUTHOR</a></h1>
<pre><code> Ruslan U. Zakirov <Ruslan.Zakirov@gmail.com></code></pre>
<h1 id="COPYRIGHT"><a href="#___top">COPYRIGHT</a></h1>
<p>This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</p>
<p>The full text of the license can be found in the Perl distribution.</p>
<h1 id="SEE-ALSO"><a href="#___top">SEE ALSO</a></h1>
<p><a href="../rt-shredder.html">rt-shredder</a>, <a href="../rt-validator.html">rt-validator</a></p>
<a href="./../">← Back to index</a>
|