(r1) BackupRestorePlugin < TWiki

Tags: view all tags
---+!! Backup &amp; 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.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ 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 %USERSWEB%.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:__ <br />
<sticky><div style="margin:10px 0; padding: 10px; border: 1px solid #cccccc; width: 673px">
<img src="%ATTACHURLPATH%/backup-console-overview.png" alt="Backup Console, Overview" width="673" height="222" />
</div></sticky>

---++ 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.

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

__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 [[http://en.wikipedia.org/wiki/Cron][cron job]]. Example crontab entry that creates a backup at 10 minutes past midnight every Sunday:
<verbatim>
10 0 * * 0 (cd /path/to/twiki/bin; ./backuprestore create_backup >/dev/null 2>&1)
</verbatim>

Make sure the plugin is [[#PluginInstallation][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-%SERVERTIME{$year-$mo-$day-$hour-$min}%.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: %BR% =version: TWiki-5.1.0= %BR% =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-&lt;major&gt;.&lt;minor&gt;.txt=

---++ Syntax Rules

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

=%<nop>BACKUPRESTORE{"..."}%= parameters:

| *Parameter* | *Explanation* | *Default* |
| =action="..."= | Action to take: %BB% =""= (empty) - show backup overview console. %BB% ="backup_detail"= - show backup detail console. %BB% ="create_backup"= - start new backup. %BB% ="cancel_backup"= - cancel backup in progress. %BB% ="delete_backup"= - delete a backup. %BB% ="restore_backup"= - restore from a backup. %BB% ="status"= - show backup status (1: backup in progress). %BB% ="debug"= - debug and diagnostics. | =""= (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

   * 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.

#PluginInstallation
---++ Plugin Installation &amp; 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 [[%SCRIPTURL{configure}%][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 ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==bin/backuprestore== | CGI/command line utility |
        | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
        | ==data/TWiki/BackupRestoreConsole.txt== | Backup and restore console topic |
        | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
        | ==lib/TWiki/Plugins/%TOPIC%/CaptureOutput.pm== | Perl module |
        | ==lib/TWiki/Plugins/%TOPIC%/Core.pm== | Core backup module |
        | ==lib/TWiki/Plugins/%TOPIC%/ProcDaemon.pm== | Perl module |
      * Set the ownership of the extracted directories and files to the webserver user.

   * Plugin __configuration and testing__:
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Configure additional <nop>%TOPIC% settings in the __Extensions__ section. Alternatively, add the following to =twiki/lib/LocalSite.cfg= and customize as needed:<verbatim>
  # 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;</verbatim>
      * 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:<verbatim>
  my $twikiLibPath = "/path/to/your/twiki/lib";
  unshift @INC, $twikiLibPath;
  1;</verbatim>
      * 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 %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Administrator utility to backup, restore and upgrade a TWiki site

|  Plugin Author: | TWiki:Main.PeterThoeny, [[http://www.twiki.net/][Twiki, Inc.]] |
|  Copyright: | &copy; 2011 TWiki:Main.PeterThoeny <br /> &copy; 2011 TWiki:TWiki.TWikiContributor <br /> &copy; 2004, 2005 Simon Flack (for CPAN:IO::CaptureOutput) <br /> &copy; 2007, 2008 David Golden (for CPAN:IO::CaptureOutput) <br /> &copy; 1997-2011 by Earl Hood and Detlef Pilzecker (for CPAN:Proc::Daemon) |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2011-08-17 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  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 <br /> (=Proc::Daemon= included as =TWiki::Plugins::BackupRestorePlugin::ProcDaemon=) <br /> (=IO::CaptureOutput= included as =TWiki::Plugins::BackupRestorePlugin::CaptureOutput= ) |
|  Other Dependencies: | GNU =zip= and =unzip= command line utilities |
|  Perl Version: | 5.005 |
|  TWiki:Plugins.Benchmark: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% 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, %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.AdminToolsCategory
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who
png	backup-console-detail.png	manage	98.3 K	16 Jul 2018 - 03:09	UnknownUser
gif	newtopic.gif	manage	0.3 K	16 Jul 2018 - 03:09	UnknownUser
gif	zip.gif	manage	0.4 K	16 Jul 2018 - 03:09	UnknownUser
Topic revision: r1 - 17 Aug 2011 - TWikiContributor
Account
- Log In
~~Edit~~
~~Attach~~
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.BackupRestorePlugin.