<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

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.

• Start a new backup.
• Cancel a backup in progress.
• List all backups.
• Delete a backup.
• Restore from a backup.

Screenshot of Backup & Restore 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).
   • This creates a backup of name twiki-backup-2025-03-15-09-25.zip in the backup directory (default /tmp).
3. Install the latest TWiki and additional plugins you need.
   • Install the latest BackupRestorePlugin.
4. Transfer the backup zip file to the backup directory of the new TWiki installation (not needed if on same server).
   • The TWiki Backup & Restore Console overview should show the backup of the old TWiki.
5. Use the TWiki Backup & Restore Console to restore the backup to the new TWiki.
   • Check the "Overwrite existing pages" checkbox.
   • Check the "Upgrade restored webs with latest system pages" checkbox.
   • Check the "Restore plugin work area" checkbox.

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

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.

Important Notes:

• The utility must run as the same user as the CGI scripts executed by the webserver. This can be apache, nobody, www-data, wwwrun or the like, and depends on the webserver configuration.
• Change to the twiki/bin directory before executing the backuprestore utility.

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

• Configuration:
  • {Plugins}{BackupRestorePlugin}{BackupDir} - Backup destination directory. Default: /tmp.
  • {Plugins}{BackupRestorePlugin}{KeepNumberOfBackups} - keep number of backups (e.g. delete old backups), 0 to keep all. Default: 7
  • {Plugins}{BackupRestorePlugin}{TempDir} - temp directory. Default: /tmp
  • {Plugins}{BackupRestorePlugin}{createZipCmd} - create zip command. Default: /usr/bin/zip -r
  • {Plugins}{BackupRestorePlugin}{listZipCmd} - list zip content command. Default: /usr/bin/unzip -l
  • {Plugins}{BackupRestorePlugin}{unZipCmd} - unzip command. Default: /usr/bin/unzip -o
  • {Plugins}{BackupRestorePlugin}{Debug} - debug flag. Default: 0
• Backup files:
  • Location: Specified by the {Plugins}{BackupRestorePlugin}{BackupDir} configure setting.
  • Name: twiki-backup-2025-03-15-09-25.zip - date based names.
• Backup format of .zip file:
  • data/* - all data and logs.
  • pub/* - all attachments.
  • working/* - working data.
  • working/BackupRestorePlugin/LocalSite.cfg - TWiki configuration file (if found).
  • working/BackupRestorePlugin/LocalLib.cfg - TWiki lib file (if found).
  • working/BackupRestorePlugin/twiki.conf - Apache config file (if found).
  • working/BackupRestorePlugin/version.txt - contains the TWiki version number of the backup. Used to intelligently restore backup to newer TWiki version. Example:
    version: TWiki-5.1.0
short: 5.1
  • working/BackupRestorePlugin/version-long-TWiki-5.1.0.txt - file with TWiki version in filename
  • working/BackupRestorePlugin/version-short-5.1.txt - file with TWiki short-version in filename, name version-short-<major>.<minor>.txt

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:

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

• The zip utility on most platforms has a limitation of 4GB.
  • Fix: Install the latest zip 3.x and unzip 6.x utilities from infozip project on SourceForge.
  • Workaround: Follow the manual upgrade instructions at TWikiUpgradeGuide if you have more data.
• A web-based backup is currently not supported on a native Windows installation of TWiki.
  • Workaround: Use command line utility on Windows.
• Restore is currently not supported on a native Windows installation of TWiki.
  • Workaround: Follow the upgrade instructions at TWikiUpgradeGuide, section Copy your old webs to new TWiki.
• Cancelling a backup or restore might leave some temporary files in the {Plugins}{BackupRestorePlugin}{BackupDir} directory.

• To-do:
  • Option to backup engine (bin, lib, locale, templates, tools).
  • Option to restore log files.

• Ideas for enhancements:
  • In backup, record $TWiki::cfg{Site}{CharSet} setting; on restore do a char-set re-encoding if needed (for example from ISO-8859-15 to UTF-8)
  • Unlock RCS files if restoring from old TWiki.
  • Add incremental backup and restore feature.

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 Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Administrator utility to backup, restore and upgrade a TWiki site

Plugin Author:

TWiki:Main.PeterThoeny, TWiki.org

Show Change History Hide Change History

<--/twistyPlugin twikiMakeVisibleInline-->

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

<--/twistyPlugin-->

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

Backup & Restore Plugin - Beta Version

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

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:

• Start a new backup.
• Cancel a backup in progress.
• List all backups.
• Delete a backup.
• Restore from a backup.

Screenshot of Backup & Restore 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).
   • This creates a backup of name twiki-backup-2025-03-15-09-25.zip in the backup directory (default /tmp).
3. Install the latest TWiki and additional plugins you need.
   • Install the latest BackupRestorePlugin.
4. Transfer the backup zip file to the backup directory of the new TWiki installation (not needed if on same server).
   • The TWiki Backup & Restore Console overview should show the backup of the old TWiki.
5. Use the TWiki Backup & Restore Console to restore the backup to the new TWiki.
   • Check the "Overwrite existing pages" checkbox.
   • Check the "Upgrade restored webs with latest system pages" checkbox.
   • Check the "Restore plugin work area" checkbox.

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

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.

Important Notes:

• The utility must run as the same user as the CGI scripts executed by the webserver. This can be apache, nobody, www-data, wwwrun or the like, and depends on the webserver configuration.
• Change to the twiki/bin directory before executing the backuprestore utility.

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

• Configuration:
  • {Plugins}{BackupRestorePlugin}{BackupDir} - Backup destination directory. Default: /tmp.
  • {Plugins}{BackupRestorePlugin}{KeepNumberOfBackups} - keep number of backups (e.g. delete old backups), 0 to keep all. Default: 7
  • {Plugins}{BackupRestorePlugin}{TempDir} - temp directory. Default: /tmp
  • {Plugins}{BackupRestorePlugin}{createZipCmd} - create zip command. Default: /usr/bin/zip -r
  • {Plugins}{BackupRestorePlugin}{listZipCmd} - list zip content command. Default: /usr/bin/unzip -l
  • {Plugins}{BackupRestorePlugin}{unZipCmd} - unzip command. Default: /usr/bin/unzip -o
  • {Plugins}{BackupRestorePlugin}{Debug} - debug flag. Default: 0
• Backup files:
  • Location: Specified by the {Plugins}{BackupRestorePlugin}{BackupDir} configure setting.
  • Name: twiki-backup-2025-03-15-09-25.zip - date based names.
• Backup format of .zip file:
  • data/* - all data and logs.
  • pub/* - all attachments.
  • working/* - working data.
  • working/BackupRestorePlugin/LocalSite.cfg - TWiki configuration file (if found).
  • working/BackupRestorePlugin/LocalLib.cfg - TWiki lib file (if found).
  • working/BackupRestorePlugin/twiki.conf - Apache config file (if found).
  • working/BackupRestorePlugin/version.txt - contains the TWiki version number of the backup. Used to intelligently restore backup to newer TWiki version. Example:
    version: TWiki-5.1.0
short: 5.1
  • working/BackupRestorePlugin/version-long-TWiki-5.1.0.txt - file with TWiki version in filename
  • working/BackupRestorePlugin/version-short-5.1.txt - file with TWiki short-version in filename, name version-short-<major>.<minor>.txt

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:

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

• The zip utility on most platforms has a limitation of 4GB.
  • Fix: Install the latest zip 3.x and unzip 6.x utilities from infozip project on SourceForge.
  • Workaround: Follow the manual upgrade instructions at TWikiUpgradeGuide if you have more data.
• A web-based backup is currently not supported on a native Windows installation of TWiki.
  • Workaround: Use command line utility on Windows.
• Restore is currently not supported on a native Windows installation of TWiki.
  • Workaround: Follow the upgrade instructions at TWikiUpgradeGuide, section Copy your old webs to new TWiki.
• Cancelling a backup or restore might leave some temporary files in the {Plugins}{BackupRestorePlugin}{BackupDir} directory.

• To-do:
  • Option to backup engine (bin, lib, locale, templates, tools).
  • Option to restore log files.

• Ideas for enhancements:
  • In backup, record $TWiki::cfg{Site}{CharSet} setting; on restore do a char-set re-encoding if needed (for example from ISO-8859-15 to UTF-8)
  • Unlock RCS files if restoring from old TWiki.
  • Add incremental backup and restore feature.

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 Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Administrator utility to backup, restore and upgrade a TWiki site

Plugin Author:

TWiki:Main.PeterThoeny, TWiki.org

Show Change History Hide Change History

<--/twistyPlugin twikiMakeVisibleInline-->

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

<--/twistyPlugin-->

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

Backup & Restore Plugin - Beta Version

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Overview

Web-based Operation

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

Once configured, visit the BackupRestoreConsole to:

• Start a new backup.
• Cancel a backup in progress.
• List all backups.
• Delete a backup.
• Restore from a backup.

Screenshot of Backup & Restore 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).
   • This creates a backup of name twiki-backup-2025-03-15-09-25.zip in the backup directory (default /tmp).
3. Install the latest TWiki and additional plugins you need.
   • Install the latest BackupRestorePlugin.
4. Transfer the backup zip file to the backup directory of the new TWiki installation (not needed if on same server).
   • The TWiki Backup & Restore Console overview should show the backup of the old TWiki.
5. Use the TWiki Backup & Restore Console to restore the backup to the new TWiki.
   • Check the "Overwrite existing pages" checkbox.
   • Check the "Upgrade restored webs with latest system pages" checkbox.
   • Check the "Restore plugin work area" checkbox.

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

Command Line Utility and Cron

Important Notes:

• The utility must run as the same user as the CGI scripts executed by the webserver. This can be apache, nobody, www-data, wwwrun or the like, and depends on the webserver configuration.
• Change to the twiki/bin directory before executing the backuprestore utility.

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

• Configuration:
  • {Plugins}{BackupRestorePlugin}{BackupDir} - Backup destination directory. Default: /tmp.
  • {Plugins}{BackupRestorePlugin}{KeepNumberOfBackups} - keep number of backups (e.g. delete old backups), 0 to keep all. Default: 7
  • {Plugins}{BackupRestorePlugin}{TempDir} - temp directory. Default: /tmp
  • {Plugins}{BackupRestorePlugin}{createZipCmd} - create zip command. Default: /usr/bin/zip -r
  • {Plugins}{BackupRestorePlugin}{listZipCmd} - list zip content command. Default: /usr/bin/unzip -l
  • {Plugins}{BackupRestorePlugin}{unZipCmd} - unzip command. Default: /usr/bin/unzip -o
  • {Plugins}{BackupRestorePlugin}{Debug} - debug flag. Default: 0
• Backup files:
  • Location: Specified by the {Plugins}{BackupRestorePlugin}{BackupDir} configure setting.
  • Name: twiki-backup-2025-03-15-09-25.zip - date based names.
• Backup format of .zip file:
  • data/* - all data and logs.
  • pub/* - all attachments.
  • working/* - working data.
  • working/BackupRestorePlugin/LocalSite.cfg - TWiki configuration file (if found).
  • working/BackupRestorePlugin/LocalLib.cfg - TWiki lib file (if found).
  • working/BackupRestorePlugin/twiki.conf - Apache config file (if found).
  • working/BackupRestorePlugin/version.txt - contains the TWiki version number of the backup. Used to intelligently restore backup to newer TWiki version. Example:
    version: TWiki-5.1.0
short: 5.1
  • working/BackupRestorePlugin/version-long-TWiki-5.1.0.txt - file with TWiki version in filename
  • working/BackupRestorePlugin/version-short-5.1.txt - file with TWiki short-version in filename, name version-short-<major>.<minor>.txt

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:

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

• The zip utility on most platforms has a limitation of 4GB.
  • Fix: Install the latest zip 3.x and unzip 6.x utilities from infozip project on SourceForge.
  • Workaround: Follow the manual upgrade instructions at TWikiUpgradeGuide if you have more data.
• A web-based backup is currently not supported on a native Windows installation of TWiki.
  • Workaround: Use command line utility on Windows.
• Restore is currently not supported on a native Windows installation of TWiki.
  • Workaround: Follow the upgrade instructions at TWikiUpgradeGuide, section Copy your old webs to new TWiki.
• Cancelling a backup or restore might leave some temporary files in the {Plugins}{BackupRestorePlugin}{BackupDir} directory.

• To-do:
  • Option to backup engine (bin, lib, locale, templates, tools).
  • Option to restore log files.

• Ideas for enhancements:
  • In backup, record $TWiki::cfg{Site}{CharSet} setting; on restore do a char-set re-encoding if needed (for example from ISO-8859-15 to UTF-8)
  • Unlock RCS files if restoring from old TWiki.
  • Add incremental backup and restore feature.

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 Hide details

<--/twistyPlugin twikiMakeVisibleInline-->

<--/twistyPlugin-->

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Administrator utility to backup, restore and upgrade a TWiki site

Plugin Author:	TWiki:Main.PeterThoeny, TWiki.org
Copyright:	© 2011-2013 TWiki:Main.PeterThoeny © 2011-2013 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:	2013-02-16

Show Change History Hide Change History

<--/twistyPlugin twikiMakeVisibleInline-->

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

<--/twistyPlugin-->

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

Backup & Restore Plugin - Beta Version

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Overview

This is a solution to backup, restore and upgrade TWiki sites. It can be used via 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 low as 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:

• Start a new backup.
• Cancel a backup in progress.
• List all backups.
• Delete a backup.
• Restore from a backup.

Screenshot of Backup & Restore 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).
   • This creates a backup of name twiki-backup-2025-03-15-09-25.zip in the backup directory (default /tmp).
3. Install the latest TWiki and additional plugins you need.
   • Install the latest BackupRestorePlugin.
4. Transfer the backup zip file to the backup directory of the new TWiki installation (not needed if on same server).
   • The TWiki Backup & Restore Console overview should show the backup of the old TWiki.
5. Use the TWiki Backup & Restore Console to restore the backup to the new TWiki.
   • Check the "Overwrite existing pages" checkbox.
   • Check the "Upgrade restored webs with latest system pages" checkbox.
   • Check the "Restore plugin work area" checkbox.

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

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.

Important Notes:

• The utility must run as the same user as the CGI scripts executed by the webserver. This can be apache, nobody, www-data, wwwrun or the like, and depends on the webserver configuration.
• Change to the twiki/bin directory before executing the backuprestore utility.

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

• Configuration:
  • {Plugins}{BackupRestorePlugin}{BackupDir} - Backup destination directory. Default: /tmp.
  • {Plugins}{BackupRestorePlugin}{KeepNumberOfBackups} - keep number of backups (e.g. delete old backups), 0 to keep all. Default: 7
  • {Plugins}{BackupRestorePlugin}{TempDir} - temp directory. Default: /tmp
  • {Plugins}{BackupRestorePlugin}{createZipCmd} - create zip command. Default: /usr/bin/zip -r
  • {Plugins}{BackupRestorePlugin}{listZipCmd} - list zip content command. Default: /usr/bin/unzip -l
  • {Plugins}{BackupRestorePlugin}{unZipCmd} - unzip command. Default: /usr/bin/unzip -o
  • {Plugins}{BackupRestorePlugin}{Debug} - debug flag. Default: 0
• Backup files:
  • Location: Specified by the {Plugins}{BackupRestorePlugin}{BackupDir} configure setting.
  • Name: twiki-backup-2025-03-15-09-25.zip - date based names.
• Backup format of .zip file:
  • data/* - all data and logs.
  • pub/* - all attachments.
  • working/* - working data.
  • working/BackupRestorePlugin/LocalSite.cfg - TWiki configuration file (if found).
  • working/BackupRestorePlugin/LocalLib.cfg - TWiki lib file (if found).
  • working/BackupRestorePlugin/twiki.conf - Apache config file (if found).
  • working/BackupRestorePlugin/version.txt - contains the TWiki version number of the backup. Used to intelligently restore backup to newer TWiki version. Example:
    version: TWiki-5.1.0
short: 5.1
  • working/BackupRestorePlugin/version-long-TWiki-5.1.0.txt - file with TWiki version in filename
  • working/BackupRestorePlugin/version-short-5.1.txt - file with TWiki short-version in filename, name version-short-<major>.<minor>.txt

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:

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

• The zip utility on most platforms has a limitation of 4GB.
  • Fix: Install the latest zip 3.x and unzip 6.x utilities from infozip project on SourceForge.
  • Workaround: Follow the manual upgrade instructions at TWikiUpgradeGuide if you have more data.
• A web-based backup is currently not supported on a native Windows installation of TWiki.
  • Workaround: Use command line utility on Windows.
• Restore is currently not supported on a native Windows installation of TWiki.
  • Workaround: Follow the upgrade instructions at TWikiUpgradeGuide, section Copy your old webs to new TWiki.
• Cancelling a backup or restore might leave some temporary files in the {Plugins}{BackupRestorePlugin}{BackupDir} directory.

• To-do:
  • Option to backup engine (bin, lib, locale, templates, tools).
  • Option to restore log files.

• Ideas for enhancements:
  • In backup, record $TWiki::cfg{Site}{CharSet} setting; on restore do a char-set re-encoding if needed (for example from ISO-8859-15 to UTF-8)
  • Unlock RCS files if restoring from old TWiki.
  • Add incremental backup and restore feature.

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

• For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

• Or, follow these manual installation steps:
  • Download the ZIP file from the Plugins home (see below).
  • Unzip BackupRestorePlugin.zip in your twiki installation directory. Content:

    File:	Description:
    bin/backuprestore	CGI/command line utility
    data/TWiki/BackupRestorePlugin.txt	Plugin topic
    data/TWiki/BackupRestoreConsole.txt	Backup and restore console topic
    lib/TWiki/Plugins/BackupRestorePlugin.pm	Plugin Perl module
    lib/TWiki/Plugins/BackupRestorePlugin/CaptureOutput.pm	Perl module
    lib/TWiki/Plugins/BackupRestorePlugin/Core.pm	Core backup module
    lib/TWiki/Plugins/BackupRestorePlugin/ProcDaemon.pm	Perl module

  • Set the ownership of the extracted directories and files to the webserver user.

• If the server has an OS other than Linux make sure to install the GNU zip utility. On Windows, install GNU Zip for Windows, http://gnuwin32.sourceforge.net/packages/zip.htm

• Plugin configuration and testing:
  • Run the configure script and enable the plugin in the Plugins section.
  • Configure additional BackupRestorePlugin settings in the Extensions section.
    Alternatively, add the following to twiki/lib/LocalSite.cfg and customize as needed:

      # Path to backup destination directory. Can be a volume mounted to the file system.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{BackupDir} = '/tmp';
      # Keep number of backups (e.g. delete old backups), 0 to keep all.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{KeepNumberOfBackups} = '7';
      # Path to temp directory, used by BackupRestorePlugin daemon for temporary data.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{TempDir} = '/tmp';
      # Path to zip command with options to recursively archive files and directory.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{createZipCmd} = '/usr/bin/zip -r';
      # Path to unzip command with options to list all files.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{listZipCmd} = '/usr/bin/unzip -l';
      # Path to unzip command with options to unzip all files with option to overwrite existing files.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{unZipCmd} = '/usr/bin/unzip -o';
      # Debug plugin. See output in data/debug.txt
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{Debug} = 0;

  • If your TWiki is older than TWiki-4.0, create a twiki/lib/LocalSite.cfg file with above $TWiki::cfg settings and end the file with: 1;
  • If your TWiki is an old TWiki-2001-09-01 (Athens Release), create a twiki/bin/setlib.cfg file with this content:

      my $twikiLibPath = "/path/to/your/twiki/lib";
      unshift @INC, $twikiLibPath;
      1;

  • If your TWiki is older than TWiki-4.2, create a working directory in the twiki root (same level as twiki/lib), and set ownership to the webserver user.
  • Test if the installation was successful: See BackupRestoreConsole.

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Administrator utility to backup, restore and upgrade a TWiki site

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

Backup & Restore Plugin - Beta Version

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Overview

This is a solution to backup, restore and upgrade TWiki sites. It can be used via 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 low as 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:

• Start a new backup.
• Cancel a backup in progress.
• List all backups.
• Delete a backup.
• Restore from a backup.

Screenshot of Backup & Restore 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).
   • This creates a backup of name twiki-backup-2025-03-15-09-25.zip in the backup directory (default /tmp).
3. Install the latest TWiki and additional plugins you need.
   • Install the latest BackupRestorePlugin.
4. Transfer the backup zip file to the backup directory of the new TWiki installation (not needed if on same server).
   • The TWiki Backup & Restore Console overview should show the backup of the old TWiki.
5. Use the TWiki Backup & Restore Console to restore the backup to the new TWiki.
   • Check the "Overwrite existing pages" checkbox.
   • Check the "Upgrade restored webs with latest system pages" checkbox.
   • Check the "Restore plugin work area" checkbox.

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

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.

Important Notes:

• The utility must run as the same user as the CGI scripts executed by the webserver. This can be apache, nobody, www-data, wwwrun or the like, and depends on the webserver configuration.
• Change to the twiki/bin directory before executing the backuprestore utility.

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

• Configuration:
  • {Plugins}{BackupRestorePlugin}{BackupDir} - Backup destination directory. Default: /tmp.
  • {Plugins}{BackupRestorePlugin}{KeepNumberOfBackups} - keep number of backups (e.g. delete old backups), 0 to keep all. Default: 7
  • {Plugins}{BackupRestorePlugin}{TempDir} - temp directory. Default: /tmp
  • {Plugins}{BackupRestorePlugin}{createZipCmd} - create zip command. Default: /usr/bin/zip -r
  • {Plugins}{BackupRestorePlugin}{listZipCmd} - list zip content command. Default: /usr/bin/unzip -l
  • {Plugins}{BackupRestorePlugin}{unZipCmd} - unzip command. Default: /usr/bin/unzip -o
  • {Plugins}{BackupRestorePlugin}{Debug} - debug flag. Default: 0
• Backup files:
  • Location: Specified by the {Plugins}{BackupRestorePlugin}{BackupDir} configure setting.
  • Name: twiki-backup-2025-03-15-09-25.zip - date based names.
• Backup format of .zip file:
  • data/* - all data and logs.
  • pub/* - all attachments.
  • working/* - working data.
  • working/BackupRestorePlugin/LocalSite.cfg - TWiki configuration file (if found).
  • working/BackupRestorePlugin/LocalLib.cfg - TWiki lib file (if found).
  • working/BackupRestorePlugin/twiki.conf - Apache config file (if found).
  • working/BackupRestorePlugin/version.txt - contains the TWiki version number of the backup. Used to intelligently restore backup to newer TWiki version. Example:
    version: TWiki-5.1.0
short: 5.1
  • working/BackupRestorePlugin/version-long-TWiki-5.1.0.txt - file with TWiki version in filename
  • working/BackupRestorePlugin/version-short-5.1.txt - file with TWiki short-version in filename, name version-short-<major>.<minor>.txt

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:

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

• Cancelling a backup or restore might leave some temporary files in the {Plugins}{BackupRestorePlugin}{BackupDir} directory.

• To-do:
  • Option to backup engine (bin, lib, locale, templates, tools).
  • Option to restore log files.

• Ideas for enhancements:
  • In backup, record $TWiki::cfg{Site}{CharSet} setting; on restore do a char-set re-encoding if needed (for example from ISO-8859-15 to UTF-8)
  • Unlock RCS files if restoring from old TWiki.
  • Add incremental backup and restore feature.

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

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server. This plugin is pre-installed in TWiki-5.1.0 and newer.

• For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

• Or, follow these manual installation steps:
  • Download the ZIP file from the Plugins home (see below).
  • Unzip BackupRestorePlugin.zip in your twiki installation directory. Content:

    File:	Description:
    bin/backuprestore	CGI/command line utility
    data/TWiki/BackupRestorePlugin.txt	Plugin topic
    data/TWiki/BackupRestoreConsole.txt	Backup and restore console topic
    lib/TWiki/Plugins/BackupRestorePlugin.pm	Plugin Perl module
    lib/TWiki/Plugins/BackupRestorePlugin/CaptureOutput.pm	Perl module
    lib/TWiki/Plugins/BackupRestorePlugin/Core.pm	Core backup module
    lib/TWiki/Plugins/BackupRestorePlugin/ProcDaemon.pm	Perl module

  • Set the ownership of the extracted directories and files to the webserver user.

• If the server has an OS other than Linux make sure to install the GNU zip utility. On Windows, install GNU Zip for Windows, http://gnuwin32.sourceforge.net/packages/zip.htm

• Plugin configuration and testing:
  • Run the configure script and enable the plugin in the Plugins section.
  • Configure additional BackupRestorePlugin settings in the Extensions section.
    Alternatively, add the following to twiki/lib/LocalSite.cfg and customize as needed:

      # Path to backup destination directory. Can be a volume mounted to the file system.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{BackupDir} = '/tmp';
      # Keep number of backups (e.g. delete old backups), 0 to keep all.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{KeepNumberOfBackups} = '7';
      # Path to temp directory, used by BackupRestorePlugin daemon for temporary data.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{TempDir} = '/tmp';
      # Path to zip command with options to recursively archive files and directory.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{createZipCmd} = '/usr/bin/zip -r';
      # Path to unzip command with options to list all files.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{listZipCmd} = '/usr/bin/unzip -l';
      # Path to unzip command with options to unzip all files with option to overwrite existing files.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{unZipCmd} = '/usr/bin/unzip -o';
      # Debug plugin. See output in data/debug.txt
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{Debug} = 0;

  • If your TWiki is older than TWiki-4.0, create a twiki/lib/LocalSite.cfg file with above $TWiki::cfg settings and end the file with: 1;
  • If your TWiki is an old TWiki-2001-09-01 (Athens Release), create a twiki/bin/setlib.cfg file with this content:

      my $twikiLibPath = "/path/to/your/twiki/lib";
      unshift @INC, $twikiLibPath;
      1;

  • If your TWiki is older than TWiki-4.2, create a working directory in the twiki root (same level as twiki/lib), and set ownership to the webserver user.
  • Test if the installation was successful: See BackupRestoreConsole.

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Administrator utility to backup, restore and upgrade a TWiki site

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

Backup & Restore Plugin - Beta Version

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Web-based Operation

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

Once configured, visit the BackupRestoreConsole to:

• Start a new backup.
• Cancel a backup in progress.
• List all backups.
• Delete a backup.
• Restore from a backup.

Command Line Utility and Cron

cron job

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

• Configuration:
  • {Plugins}{BackupRestorePlugin}{BackupDir} - Backup destination directory. Default: /tmp.
  • {Plugins}{BackupRestorePlugin}{KeepNumberOfBackups} - keep number of backups (e.g. delete old backups), 0 to keep all. Default: 7
  • {Plugins}{BackupRestorePlugin}{TempDir} - temp directory. Default: /tmp
  • {Plugins}{BackupRestorePlugin}{createZipCmd} - create zip command. Default: /usr/bin/zip -r
  • {Plugins}{BackupRestorePlugin}{listZipCmd} - list zip content command. Default: /usr/bin/unzip -l
  • {Plugins}{BackupRestorePlugin}{unZipCmd} - unzip command. Default: /usr/bin/unzip -o
  • {Plugins}{BackupRestorePlugin}{Debug} - debug flag. Default: 0
• Backup files:
  • Location: Specified by the {Plugins}{BackupRestorePlugin}{BackupDir} configure setting.
  • Name: twiki-backup-2025-03-15-09-25.zip - date based names.
• Backup format of .zip file:
  • data/* - all data and logs.
  • pub/* - all attachments.
  • working/* - working data.
  • working/BackupRestorePlugin/LocalSite.cfg - TWiki configuration file (if found).
  • working/BackupRestorePlugin/LocalLib.cfg - TWiki lib file (if found).
  • working/BackupRestorePlugin/twiki.conf - Apache config file (if found).
  • working/BackupRestorePlugin/version.txt - contains the TWiki version number of the backup. Used to intelligently restore backup to newer TWiki version. Example:
    version: TWiki-5.1.0
short: 5.1
  • working/BackupRestorePlugin/version-long-TWiki-5.1.0.txt - file with TWiki version in filename
  • working/BackupRestorePlugin/version-short-5.1.txt - file with TWiki short-version in filename, name version-short-<major>.<minor>.txt

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:

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

• To-do:

• • Add incremental backup and restore feature.

Plugin Installation & Configuration

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server. This plugin is pre-installed in TWiki-5.1.0 and newer.

• For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

• Or, follow these manual installation steps:
  • Download the ZIP file from the Plugins home (see below).
  • Unzip BackupRestorePlugin.zip in your twiki installation directory. Content:

    File:	Description:
    bin/backuprestore	CGI/command line utility
    data/TWiki/BackupRestorePlugin.txt	Plugin topic
    data/TWiki/BackupRestoreConsole.txt	Backup and restore console topic
    lib/TWiki/Plugins/BackupRestorePlugin.pm	Plugin Perl module
    lib/TWiki/Plugins/BackupRestorePlugin/CaptureOutput.pm	Perl module
    lib/TWiki/Plugins/BackupRestorePlugin/Core.pm	Core backup module
    lib/TWiki/Plugins/BackupRestorePlugin/ProcDaemon.pm	Perl module

  • Set the ownership of the extracted directories and files to the webserver user.

• Plugin configuration and testing:
  • Run the configure script and enable the plugin in the Plugins section.

• • If your TWiki is older than TWiki-4.0, create a twiki/lib/LocalSite.cfg file with above $TWiki::cfg settings and end the file with: 1;
  • If your TWiki is an old TWiki-2001-09-01 (Athens Release), create a twiki/bin/setlib.cfg file with this content:

      my $twikiLibPath = "/path/to/your/twiki/lib";
      unshift @INC, $twikiLibPath;
      1;

  • If your TWiki is older than TWiki-4.2, create a working directory in the twiki root (same level as twiki/lib), and set ownership to the webserver user.
  • Test if the installation was successful: See BackupRestoreConsole.

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Administrator utility to backup, restore and upgrade a TWiki site

Plugin Author:

TWiki:Main.PeterThoeny, Twiki, Inc.

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

Backup & Restore Plugin - Beta Version

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/BackupRestorePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->

Introduction

This is a solution to backup, restore and upgrade TWiki sites. It can be used via 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 low as 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.

Note: The initial plugin release does not yet offer the restore functionality. Check TWiki:Plugins.BackupRestorePlugin for updates.

Web-based Operation

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

Once configured, visit the BackupRestoreConsole to:

• Start a new backup.
• Cancel a backup in progress.
• List all backups.
• Delete a backup.
• Restore from a backup.

Screenshot:

Command Line Utility and Cron

The bin/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.

Important: The utility must run as the same user as the CGI scripts executed by the webserver. This can be apache, nobody, www-data, wwwrun or the like, and depends on the webserver configuration.

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

• Configuration:
  • {Plugins}{BackupRestorePlugin}{BackupDir} - Backup destination directory. Default: /tmp.
  • {Plugins}{BackupRestorePlugin}{KeepNumberOfBackups} - keep number of backups (e.g. delete old backups), 0 to keep all. Default: 7
  • {Plugins}{BackupRestorePlugin}{TempDir} - temp directory. Default: /tmp
  • {Plugins}{BackupRestorePlugin}{createZipCmd} - create zip command. Default: /usr/bin/zip -r
  • {Plugins}{BackupRestorePlugin}{listZipCmd} - list zip content command. Default: /usr/bin/unzip -l
  • {Plugins}{BackupRestorePlugin}{unZipCmd} - unzip command. Default: /usr/bin/unzip -o
  • {Plugins}{BackupRestorePlugin}{Debug} - debug flag. Default: 0
• Backup files:
  • Location: Specified by the {Plugins}{BackupRestorePlugin}{BackupDir} configure setting.
  • Name: twiki-backup-2025-03-15-09-25.zip - date based names.
• Backup format of .zip file:
  • data/* - all data and logs.
  • pub/* - all attachments.
  • working/* - working data.
  • working/BackupRestorePlugin/LocalSite.cfg - TWiki configuration file (if found).
  • working/BackupRestorePlugin/LocalLib.cfg - TWiki lib file (if found).
  • working/BackupRestorePlugin/twiki.conf - Apache config file (if found).
  • working/BackupRestorePlugin/version.txt - contains the TWiki version number of the backup. Used to intelligently restore backup to newer TWiki version. Example:
    version: TWiki-5.1.0
short: 5.1
  • working/BackupRestorePlugin/version-long-TWiki-5.1.0.txt - file with TWiki version in filename
  • working/BackupRestorePlugin/version-short-5.1.txt - file with TWiki short-version in filename, name version-short-<major>.<minor>.txt

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:

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

• A web-based backup is currently not supported on a native Windows installation of TWiki, however, the command line utility can be used on Windows.

• To-do:
  • Add restore from backup functionality.
  • Add incremental backup and restore feature.

Plugin Installation & Configuration

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server. This plugin is pre-installed in TWiki-5.1.0 and newer.

• For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

• Or, follow these manual installation steps:
  • Download the ZIP file from the Plugins home (see below).
  • Unzip BackupRestorePlugin.zip in your twiki installation directory. Content:

    File:	Description:
    bin/backuprestore	CGI/command line utility
    data/TWiki/BackupRestorePlugin.txt	Plugin topic
    data/TWiki/BackupRestoreConsole.txt	Backup and restore console topic
    lib/TWiki/Plugins/BackupRestorePlugin.pm	Plugin Perl module
    lib/TWiki/Plugins/BackupRestorePlugin/CaptureOutput.pm	Perl module
    lib/TWiki/Plugins/BackupRestorePlugin/Core.pm	Core backup module
    lib/TWiki/Plugins/BackupRestorePlugin/ProcDaemon.pm	Perl module

  • Set the ownership of the extracted directories and files to the webserver user.

• Plugin configuration and testing:
  • Run the configure script and enable the plugin in the Plugins section.
  • Configure additional BackupRestorePlugin settings in the Extensions section. Alternatively, add the following to twiki/lib/LocalSite.cfg and customize as needed:

      # Path to backup destination directory. Can be a volume mounted to the file system.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{BackupDir} = '/tmp';
      # Keep number of backups (e.g. delete old backups), 0 to keep all.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{KeepNumberOfBackups} = '7';
      # Path to temp directory, used by BackupRestorePlugin daemon for temporary data.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{TempDir} = '/tmp';
      # Path to zip command with options to recursively archive files and directory.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{createZipCmd} = '/usr/bin/zip -r';
      # Path to unzip command with options to list all files.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{listZipCmd} = '/usr/bin/unzip -l';
      # Path to unzip command with options to unzip all files with option to overwrite existing files.
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{unZipCmd} = '/usr/bin/unzip -o';
      # Debug plugin. See output in data/debug.txt
      $TWiki::cfg{Plugins}{BackupRestorePlugin}{Debug} = 0;

  • If your TWiki is older than TWiki-4.0, create a twiki/lib/LocalSite.cfg file with above $TWiki::cfg settings and end the file with: 1;
  • If your TWiki is an old TWiki-2001-09-01 (Athens Release), create a twiki/bin/setlib.cfg file with this content:

      my $twikiLibPath = "/path/to/your/twiki/lib";
      unshift @INC, $twikiLibPath;
      1;

  • If your TWiki is older than TWiki-4.2, create a working directory in the twiki root (same level as twiki/lib), and set ownership to the webserver user.
  • Test if the installation was successful: See BackupRestoreConsole.

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Administrator utility to backup, restore and upgrade a TWiki site

Plugin Author:	TWiki:Main.PeterThoeny, Twiki, Inc.
Copyright:	© 2011 TWiki:Main.PeterThoeny © 2011 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:	2011-08-17
Change History:	<-- versions below in reverse order -->
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