Tags:
admin_tool1Add my vote for this tag automation1Add my vote for this tag usability1Add my vote for this tag create new tag
, view all tags

EcoTrashPlugin

Trash manager to restore or permanently delete topics and attachments (manually and automated)

Without this plugin, TWiki is, in some environments, an ecological disaster. With it, TWiki is ecologically correct.

Background

TWiki deletes files and attachments by moving them to the Trash web. TWiki does not provide a mechanism to expunge deleted files from the Trash web. This works well for environments where infinite history is desired.

However, this can be a problem in the following circumstances:

  • Where policy requires history to be limited
  • Where users are concerned that a mistakenly-attached file (perhaps with embarrassing content) may be retained forever
  • Where disk space isn't an infinite resource

Traditionally, TWiki specifies that management of the Trash web requires command line or FTP access. This is not always possible and is error-prone. The past advice was to delete and rebuild the entire Trash web, but various policy considerations led to manual methods that left the Trash in inconsistent states.

Features and User Interface

Screenshot of the Trash Manager: (click to enlarge)
trash-manager-500.png

EcoTrashPlugin provides a means to manage the Trash web. It allows you to expunge (permanently delete) topics and attachments from the Trash web.

Arrow right Use the Trash Manager topic to manage the content of the Trash web, it has a simple point and click user interface.

Warning, important Expunging items is irreversible (at least, without recourse to system backup tapes). Please be sure that this is what you want to do.

The tools/ecotrashsweeper script provides a periodic maintenance function for the Trash web, which can also be invoked from the graphical interface. This includes deleting any empty directories in pub/Trash, and enforcing your site retention policy defined in the configuration.

Developer Documentation

This documentation is for developers.

EcoTrashPlugin itself provides supporting functions for the graphical interface. It is not intended for use in other topics, and may be changed without regard to compatibility with unauthorized applications.

Configuration functions

%TRASH{"minage"}% - returns the minimum age parameter (required retention) from configure.

%TRASH{"maxage"} - returns the maximum age parameter (maximum retention) from configure.

%TRASH{"expiretime"} - returns the time (serial) when files expire (now - maxage).

%TRASH{"expiredate"} - returns the date (string) when files expire (now - maxage).

%TRASH{"group"} - returns the user group authorized to use the interface by configure.

%TRASH{"protected"} - returns the list of Trash web topics that are protected from deletion.

%TRASH{"attachtopic"} - returns the name of the topic that holds deleted attachments from configure.

=%TRASH{"icon"}% Returns an image tag for the application icon.

Topic utilities

%TRASH{"topicmove" options... }%

Options

Options are specified in the usual format -- each option is of the form name="value", where the quotes are required. multiple options are separated by spaces. These accept several parameters:

  • topic - Topic to format
  • format - may contain the following special tokens in addition to the standard FormatTokens:
    • $name - Topic name
    • $rev - Version
    • $date - Date last modified (serial)
    • $fdate - Date last modified formatted for display
    • $user - User who last modified
    • $from - Moved from Web.Topic
      • $ftopic - Web.Topic
      • $fname - Web.Topic
    • $to - Moved to Web.Topic
      • $ttopic - Web.Topic
      • $tname - Web.Topic
      • $tpath -path from Trash
    • $mdate - Date of move (serial)
    • $fmdate - Date of move formatted for display
    • $mname - Name of user who moved
    • $restore - Link to restore topic
    • $comment - Comment associated with attachment

Attachment lists

%TRASH{"listattachments" options... }%

%TRASH{"listunclaimed" options... }%

Options

Options are specified in the usual format -- each option is of the form name="value", where the quotes are required. multiple options are separated by spaces. These accept several parameters:

  • format - may contain the following special tokens in addition to the standard FormatTokens:
    • $name - Filename
    • $rev - Version
    • $path - Path supplied at attach
    • $size - File size
    • $date - Date last modified (serial)
    • $fdate - Date last modified formatted for display
    • $user - User who last modified
    • $attr - Attributes
    • $from - Moved from Web.Topic.filename
      • $ftopic - Web.Topic
      • $fname - filename
    • $to - Moved to Web.Topic.filename
      • $ttopic - Web.Topic
      • $tname - filename
      • $tpath -path from Trash
    • $mdate - Date of move (serial)
    • $fmdate - Date of move formatted for display
    • $mname - Name of user who moved
    • $restore - Link to restore attachment
    • $comment - Comment associated with attachment
  • none - specifies a string to be produced if no items are found. The standard format tokens may be used.
  • header - specifies a string to be produced if at least one item is found. The standard format tokens may be used.
  • footer - specifies a string to be produced if at least one item is found. The standard format tokens may be used.

Note that date/time values are provided as time serial (integer) values or as a date string formatted according to the system-wide {DefaultDateFormat} and {DisplayTimeValues} configuration parameters. To obtain the time, use %CALC%'s $FORMATTIME on the integer.

TrashManager GUI

The GUI topic does some handstands to minimize the chance of it being treated as an editable topic. If you're a maintainer, and you really know what you're doing, click the trashcan icon to access the usual topic editing tools.

EcoTrashSweeper

The tools/ecotrashsweeper script performs automatic maintenance of the Trash web. It should be run by cron under the webserver user.

The script:

  • Locates any pub/Trash directories that don't correspond to a Trash topic. (This can occur due to previous manual management or system failure.) Empty directories are expunged. Otherwise, the corresponding topic is created and the files found in =pub/Trash are attached to it.
  • Removes any metadata for attachments that were deleted without updating it.
  • Expunges any deleted attachments or topics that are older than {Plugins}{EcoTrashPlugin}{MaximumAge} days. This is measured from the deletion time of the item, or if none is recorded, from the last change time of the file. This function can be disabled by setting {Plugins}{EcoTrashPlugin}{MaximumAge} to zero (the default).

Switches (you must specify =1 for the switch to take effect):

  • -q=1 - When specified, the script is silent. By default, it reports every action.
  • -t=1 - When specified, the script runs normally, except that it does not delete anything. This should be used to verify that the script is configured correctly.

Note that the script deletes directory trees under the Trash web. If misconfigured, it can do a great deal of damage. A trial run with -t=1 is strongly recommended.

The same functions are available from the graphical interface, which is a good way to do a trial run.

Issues

  • Subwebs may not work properly due to the limitations of the FILEATTACHMENT metadata.
  • Only the RCS database format is supported, because the storage API doesn't provide the necessary functions.
  • The WatchlistPlugin is not informed of the final deletion of a topic. However, since links are not usually updated when a topic is deleted, this doesn't seem worth doing.
  • The management page will misbehave ungracefully if the plugins listed as dependencies (below) are not satisfied.

Plugin Settings

There are no user settings (TWiki preferences) for this plugin.

See the EcoTrashPlugin parameters in the Extensions section of the configure script for the system configuration settings.

Installation and Configuration

You do not need to install anything on the browser to use this plugin. These instructions are for the administrator who installs the plugin on the TWiki server.

1. Plugin installation

There are three methods available for installing this plugin.:

  • Use the configure script's extension manager.
    • Simplest, but your webserver must have write access to the TWiki code.
  • Run the installation script manually
    • Automated, works in most environments
  • Do a manual installation
    • If you don't trust automation, or have an unusual environment

Tip, idea No matter which method you choose, if you run selinux you will probably have to correct security context assignments for the new files and/or any intermediate directories.

Using Configure

  • Click on this link: configure
  • Click on Extensions, Find more extensions
  • Locate EcoTrashPlugin
  • Click on the link and follow the directions

Runing the installation script manually

  • From your TWiki root directory:
    • Download the EcoTrashPlugin_installer script and the EcoTrashPlugin.md5 file from the Plugin Home (see below)
    • Verify that the files were downloaded correctly: md5sum -c EcoTrashPlugin.md5
    • Run the installer: perl EcoTrashPlugin_installer *

Manual installation

  • Install the prerequisite plugins. Be sure that they are at or above the minimum requred revisions.
  • Download the EcoTrashPlugin.zip or EcoTrashPlugin.tar.gz and EcoTrashPlugin.md5 files from the Plugin Home (see below)
  • Verify that the files were downloaded correctly: md5sum -c EcoTrashPlugin.md5
  • Expand the file that you selected in your TWiki installation directory. Content:
  • Correct file ownership, permissions, (and selinux contexts) for your environment.
  • Tip, idea: by default, the tar and unzip commands will set the permissions of each directory to those in the archive. This can disrupt your wiki. This can be avoided by explicitly extracting each of the files.*
    data/Trash/WebTrashManager.txt User interface
    data/Trash/WebHomeEcoTrashPlugin.txt Updated home topic for Trash web (TWiki rev below 26952)
    data/TWiki/EcoTrashPlugin.txt Documentation
    pub/TWiki/EcoTrashPlugin/trash-manager-500.png Screenshot
    pub/TWiki/EcoTrashPlugin/trash-manager.png Screenshot
    lib/TWiki/Plugins/EcoTrashPlugin.pm Perl module
    lib/TWiki/Plugins/EcoTrashPlugin/Core.pm Perl module
    lib/TWiki/Plugins/EcoTrashPlugin/Config.spec Configuration data
    templates/restoreattachment.tmpl Restore attachment template
    tools/ecotrashsweeper Perl script

If your Trash.WebHome does not include the text "WebTrashManager section="WebHomeText" (is older than version 26956), replace it with WebHomeEcoTrashPlugin: Otherwise, you can expunge WebHomeEcoTrashPlugin.

2. Plugin configuration and testing

  • Run the configure script to configure the plugin.
    • Ensure that the bin/rest script is enabled and configured for authentication. (This is part of a normal TWiki installation.)
    • Check the additional settings in the Extensions section, and change if the defaults are not suitable for your installation.
      • {Plugins}{EcoTrashPlugin}{AdminGroup} - Administrator group
      • {Plugins}{EcoTrashPlugin}{MinimumAge} - Minimum retention period
      • {Plugins}{EcoTrashPlugin}{MaximumAge} - Maximum retention period
      • Check the {Plugins}{EcoTrashPlugin}{Enabled} box, in the Plugins section.
  • Optional: Configure your webserver to allow access to items in the Trash by your administrator(s). This is normally prohibited for all users to prevent abuse, but it may be useful to an administrator who is reviewing Trash contents..
  • Visit the TrashManager topic and verify that the plugin is active. Tip, ideaIf you have items in Trash but the presentation looks wrong, you probably have an old version of SpreadSheetPlugin. Please upgrade it.
3. Set up and test the maintenance function

We recommend that you install a crontab entry (or equivalent) for tools/ecotrashsweeper to run under the webserver user. This will enable automatic maintenance of the Trash web.

Because the script deletes files and directories, it is important to verify that it is configured correctly. We strongly recommend running it initially with the -t=1 option to verify that it is accessing the expected directories. This will do everything except the actual deletions. (It will produce messages indicating that deletions happen - but they don't.)

You can test the script from the TrashManager topic by clicking Test mode and Perform Maintenance Now. This will perform the exact actions that the maintenance script will with -t=1, displaying the results in your browser.

Tip, idea If you prefer not to set up a cron job, you can run the maintenance function from the TrashManager topic. If you elect that option, you can skip the rest of this section.

For a manual test run from the command line (on unix), use:

(cd /var/www/twiki; nice sudo -u *apache* perl -T -I bin tools/ecotrashsweeper -t=1)

Replace *apache* with the user under which the TWiki webserver runs on your system. It is important to use the webserver user so that updated files will have the correct permissions.

Once you are comfortable that the script is accessing the correct directories, you should set up a crontab entry for the webserver user.

A typical crontab entry looks like:

23 00 * * * (cd /var/www/twiki; nice perl  -T -I bin tools/ecotrashsweeper -q=1)

By default, the script will report every action. To suppress this, use the -q=1 switch.

For a log, use:

23 00 * * * (cd /var/www/twiki; nice perl  -T -I bin tools/ecotrashsweeper >>/var/www/twiki/data/ecotrashsweeper.log)

A somewhat simpler (equivalent) command structure on systems where perl scripts can be executed directly is:

(cd /var/www/twiki/bin; nice ../tools/ecotrashsweeper -q=1)

Plugin Info

  • One line description, shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Trash manager to restore or permanently delete topics and attachments (manually and automated)

Plugin Author: TWiki:Main.TimotheLitt
Copyright: © 2014 TWiki:Main.TimotheLitt
© 2014 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Plugin Version: 2014-02-03 (V1.002)
2014-02-03 TWikibug:Item7427: Fix for too small font with twikiSubmit class on button tag (workaround for unpatched PatterSkin) -- TWiki:Main.PeterThoeny
2014-01-31 TWikibug:Item7422: Doc fixes -- TWiki:Main.PeterThoeny
2014-01-29 TWikibug:Item7422: Use system date display formats, handle disabled plugin more gracefully.
2014-01-28 TWikibug:Item7422: Change minage handling to be more prominent
2014-01-27 TWikibug:Item7422: Work-around issue with newer JQueryPlugin, fix Webhome, TWiki version, and plugin disabled issues
2014-01-26 TWikibug:Item7422: More cleanup, incorporate feedback
2014-01-21 General cleanup, add deferred features
2014-01-19 Technology preview
Dependencies:
NameVersionDescription
TWiki::Plugins>=1.2TWiki 4.2 release.
TWiki::Plugins::SpreadSheetPlugin>=2013-10-10Required by GUI
TWiki::Plugins::TablePlugin>=0Required
TWiki::Plugins::JQueryPlugin>=0Required
File::Find>=1.10Required - Part of perl distribution
CGI>=3.55Required
Perl Version: 5.008
Benchmarks: GoodStyle nn%, FormattedSearch nn%, EcoTrashPlugin nn%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/EcoTrashPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/EcoTrashPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/EcoTrashPluginAppraisal

Related Topics: WebTrashManager, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatmd5 EcoTrashPlugin.md5 r5 r4 r3 r2 r1 manage 0.2 K 2014-02-04 - 07:18 PeterThoeny  
Compressed Zip archivetgz EcoTrashPlugin.tgz r5 r4 r3 r2 r1 manage 182.7 K 2014-02-04 - 07:18 PeterThoeny  
Compressed Zip archivezip EcoTrashPlugin.zip r5 r4 r3 r2 r1 manage 185.7 K 2014-02-04 - 07:18 PeterThoeny  
Unknown file formatEXT EcoTrashPlugin_installer r3 r2 r1 manage 4.2 K 2014-02-04 - 07:18 PeterThoeny  
Edit | Attach | Watch | Print version | History: r8 < r7 < r6 < r5 < r4 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r8 - 2014-02-04 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.