Home | Gifts

Backup & Restore Plugin

Administrator utility to backup, restore and upgrade a TWiki site

Overview

This is a solution to backup, restore, and upgrade TWiki sites. It can be used via the browser and on the command line. This plugin is pre-installed in TWiki-5.1 and later releases. It can be installed in older TWiki releases as oldas TWiki-2001-09-01 (Athens Release) to easily create a backup that can be restored on a new TWiki release. This offers an easy upgrade path for TWiki.

This plugin backs up page data, attachment data, the plugin workspace area, and the TWiki configuration. However, it does not backup the TWiki engine, additional plugins, and skins you might have installed. It is recommended to do a manual backup of the whole twiki directory after installing plugins and skins.

Web-based Operation

The backup and restore functionality is restricted to members of the TWikiAdminGroup.

Once configured, visit the BackupRestoreConsole to:

Screenshot of Backup & Restore Console, overview:

Backup Console, Overview

How to Upgrade TWiki

The TWikiUpgradeGuide describes how to manually upgrade TWiki. It is much easier to use the BackupRestorePlugin to do a TWiki upgrade. Follow these steps:

  1. Install the BackupRestorePlugin on your old TWiki installation.
  2. Create a backup using the TWiki Backup & Restore Console (linked from plugin topic).
  3. Install the latest TWiki and additional plugins you need.
  4. Transfer the backup zip file to the backup directory of the new TWiki installation (not needed if on same server).
  5. Use the TWiki Backup & Restore Console to restore the backup to the new TWiki.

Screenshot of Backup & Restore Console, detail view of very old TWiki-01-Sep-2001 backup:

Backup Console, Detail

Command Line Utility and Cron

The backuprestore utility can be used to create a backup (scheduled or manually), to copy a backup, and to check on the status of the backup process.

Command Description
./backuprestore status Show backup status. Returns backup_status: 1 if web-based backup is in progress.
./backuprestore create_backup Create a backup. This is done without a background daemon process, e.g. the script returns when the backup is done.
./backuprestore download_backup <name.zip> Dump a backup file to STDOUT. If called as CGI script, download a backup file.

ALERT! Important Notes:

Scheduled backups can be done with a cron job. Example crontab entry that creates a backup at 10 minutes past midnight every Sunday:

10 0 * * 0 (cd /path/to/twiki/bin; ./backuprestore create_backup >/dev/null 2>&1)

Make sure the plugin is configured properly before creating backups. The backup destination can be local or remote. If remote, the remote server needs to be mounted on the TWiki server via NFS or the like.

Specification

Syntax Rules

This section is only relevant to plugin developers. This plugin handles a %BACKUPRESTORE{"..."}% variable to perform all web-based operations. The variable is used in the BackupRestoreConsole page.

%BACKUPRESTORE{"..."}% parameters:

Parameter Explanation Default
action="..." Action to take:
"" (empty) - show backup overview console.
"backup_detail" - show backup detail console.
"create_backup" - start new backup.
"cancel_backup" - cancel backup in progress.
"delete_backup" - delete a backup.
"restore_backup" - restore from a backup.
"status" - show backup status (1: backup in progress).
"debug" - debug and diagnostics - {Plugins}{BackupRestorePlugin}{Debug} must be enabled.
"" (empty)
file="..." Name of backup file to take action. The file parameter is required for the following actions: "backup_detail", "delete_backup" and "restore_backup". ""

This plugin starts a daemon (background process) when a backup is started. Status is checked via Ajax calls. Once the new backup is finished it shows up in the backup table.

Limitations and To-Do

License and Bug Reporting

This plugin has been reasonably tested. If you find any issues please file a bug report at TWikibug:BackupRestorePlugin.

This plugin is distributed under GPL (GNU General Public License) in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

Plugin Installation & Configuration

This plugin is pre-installed from TWiki-5.1 on. TWiki administrators can upgrade the plugin as needed on the TWiki server.

Show details toggleopen.gif Hide details toggleclose.gif

Plugin Info

Plugin Author: TWiki:Main.PeterThoeny, TWiki.org
Copyright: © 2011-2018 TWiki:Main.PeterThoeny
© 2011-2018 TWiki:TWiki.TWikiContributor
© 2004, 2005 Simon Flack (for CPAN:IO::CaptureOutput)
© 2007, 2008 David Golden (for CPAN:IO::CaptureOutput)
© 1997-2011 by Earl Hood and Detlef Pilzecker (for CPAN:Proc::Daemon)
License: GPL (GNU General Public License)
Plugin Version: 2018-07-10

Show Change History toggleopen.gif Hide Change History toggleclose.gif
2018-07-10: TWikibug:Item7841: Copyright update to 2018
2017-12-31: TWikibug:Item7831: Allow action=debug only if Debug flag set; parameter sanity checks
2016-01-08: TWikibug:Item7708: Copyright update to 2016
2015-01-09: TWikibug:Item7604: Switch to GPL v3
2013-02-16: TWikibug:Item7091: Use TWISTY in installation instructions section and change history
2012-09-03: TWikibug:Item6837: Doc update with zip utility limitation of 4GB
2012-01-13: TWikibug:Item6796: Fixing copyright year to 2012
2011-12-19: TWikibug:Item6799: Improved docs on GNU zip dependency
2011-09-13: TWikibug:Item6796: Improved docs on command line use
2011-09-05: TWikibug:Item6795: Add restore from backup functionality; upgrade old system topics on restore of old TWiki; describe how to upgrade TWiki
2011-08-17: TWikibug:Item6793: Avoid or work around newer APIs to make plugin run on old TWiki-2001-09-01 (Athens Release) for backup
2011-08-16: TWikibug:Item6793: Add screenshot; add Config.spec configure file; proper detection of command line mode also for older TWiki versions; use TWiki::Func::registerTagHandler only if available so that plugin can run in older TWiki versions
2011-08-15: TWikibug:Item6793: Better error handling; add magic number to download URL to restrict download of backups to TWiki admins only
2011-08-12: TWikibug:Item6631: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.0
CPAN Dependencies: none
(Proc::Daemon included as TWiki::Plugins::BackupRestorePlugin::ProcDaemon)
(IO::CaptureOutput included as TWiki::Plugins::BackupRestorePlugin::CaptureOutput )
Other Dependencies: GNU zip and unzip command line utilities
Perl Version: 5.005
TWiki:Plugins.Benchmark: GoodStyle nn%, FormattedSearch nn%, BackupRestorePlugin nn%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/BackupRestorePlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/BackupRestorePluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/BackupRestorePluginAppraisal

Related Topics: BackupRestoreConsole, TWikiPreferences, TWikiPlugins, AdminToolsCategory

Revision r7 - 2018-07-10 - 22:15:29 - TWikiContributor Edit