With wp cloneworx-backup restore you check before a restore whether it can succeed, restore a backup and keep the restore or undo it. With wp cloneworx-backup import you add a backup from a file to the list.
WP-CLI still missing? The guide is in Install WP-CLI. All commands of the plugin are listed in The commands at a glance.
This applies to all actions
- You specify a backup by its job name.
wp cloneworx-backup backup listshows it. In the examples it is written as<Job>. A backup with the statussuccessorwarningscan be restored. - Only one job runs per website at a time. If one is already running, every command that starts a job ends with an error and shows the running job.
- The outputs are in English. The deadline of the rollback is shown there in UTC.
- All actions except
restore statusfirst check the user: the command must run as the user who owns the folders of the plugin. Forrestore precheckandimport,--forceskips the check. Forrestore run,keepandundothere is no--force: the website could not change files of another user afterwards.
Checking before the restore: precheck
restore precheck runs the pre-check: nine points before a restore writes anything. The pre-check changes nothing on the website. To test the permissions, it creates folders and tables and removes them again.
| Parameter | Meaning | Allowed values |
|---|---|---|
--target |
The target at which the plugin reads the backup. Without the parameter: the first local target at which the backup is complete, otherwise the first other one. | Identifier of a target |
--roots |
What is restored. Without the parameter: every root of the backup. | Roots, separated by commas, for example db,wp-uploads
|
--include-core |
Also restores the WordPress core on a different website. | without a value |
--include-dropins |
Also restores object-cache.php, advanced-cache.php and db.php on a different website. |
without a value |
--include-htaccess |
Also restores .htaccess, web.config and .user.ini on a different website. |
without a value |
--uploads-in-place |
Chooses the procedure without rollback for the uploads when the space next to the live folder is not enough. | without a value |
--remove-extras |
Checks for a restore that removes everything that is not in the backup: the line tables not in the backup then shows that the listed tables are moved to the previous state. The pre-check itself removes nothing. The former name --remove-extra-uploads is still accepted. |
without a value |
--force |
Also runs as another user. | without a value |
The three parameters with --include only take effect if the backup comes from a different website or its origin is unknown. On the same website the plugin restores core, drop-ins and .htaccess by default.
# Run the pre-check for a backup wp cloneworx-backup restore precheck <Job> # Read the backup at a specific target, only two roots wp cloneworx-backup restore precheck <Job> --target=local-1 --roots=db,wp-uploads
If this website does not know the backup because it was found again at a target, imported or written with an earlier version of the plugin, restore precheck and restore run end with an error. With --accept-unknown you confirm the backup as correct: the website then remembers the info file as it is at the target. Only confirm the backup as correct if you trust the storage target.
The first line of the output shows the backup, the target at which it was read, the roots and the origin: the same website, a different one or unknown. After that follows one line per point with state and finding.
| State | Meaning |
|---|---|
OK |
The point is fine. |
WARN |
Something you should know. You decide. A warning never blocks the restore. |
FAIL |
The restore cannot start. |
UNKNOWN |
The point could not be determined. |
| Point in the output | In the interface |
|---|---|
readable |
Backup readable and complete |
versions |
PHP and MySQL version |
space |
Free space |
permissions |
Write permissions at the target folders |
packet |
max_allowed_packet vs. largest row |
collations |
Collations |
fingerprint |
Same website |
db_rights |
Database rights (probe) |
loopback |
Self-request possible |
Below the points you see what is not restored and why. If the database belongs to the roots and this website has tables that are not in the backup, the line tables not in the backup lists these tables: at most 50 by name, further ones only as a number. In brackets it says whether they stay (they stay) or are moved to the previous state with --remove-extras (they move to the previous state). Tables of another WordPress installation that are in the same database under a longer prefix are not in the line. Finally the output lists the differences between the backup and this website: per line the value in the backup and the value here. You check the risk of these differences yourself. If a point has the state FAIL, the command ends with an error. Every point is explained in The restore precheck: every point explained.
Restoring a backup: run
A restore replaces the state of the website
The backup replaces the current state of the chosen roots. The previous state is kept for 7 days; for that long you can undo the restore. An exception are uploads that were replaced in place with --uploads-in-place: for them there is no rollback.
restore run restores the chosen roots. This is how it happens:
- The pre-check runs as the first phase. A
FAILends the job before anything is written. - The plugin builds the files next to the live folders and imports the database into tables next to the live ones. The website keeps running meanwhile.
- The plugin switches uploads and files in the root folder file by file, without maintenance mode.
- The plugin switches over database, core, must-use plugins, plugins, themes and the rest of
wp-contentin the maintenance mode of WordPress. This step runs in the web server: the command hands it over via the self-request and waits. - The new website confirms itself. If the confirmation does not come within 60 seconds, the same step switches back, and the website runs on the previous state again.
If the self-request does not reach the web server within 60 seconds, the command aborts the restore before the switch-over. The plugin reverts what was switched until then, and the website keeps running on its previous state. Only uploads that were replaced in place with --uploads-in-place stay replaced.
The plugin itself with its folders and tables and the wp-config.php are never restored. Files in the uploads and in the root folder that are not in the backup stay by default. Tables of this website that are not in the backup stay by default; the result lists them. With --remove-extras these files and tables are moved to the previous state.
| Parameter | Meaning | Allowed values |
|---|---|---|
--target, --roots, --include-core, --include-dropins, --include-htaccess, --uploads-in-place
|
As with restore precheck. |
as above |
--remove-extras |
Removes, in the chosen roots, everything that is not in the backup: files in the uploads and in the root folder and, with the root db, tables of this website. Nothing is deleted right away: the files and tables are moved to the previous state. restore undo brings them back, restore keep deletes them permanently. By default they stay. If the restore replaces the uploads in place with --uploads-in-place, the parameter has no effect. The former name --remove-extra-uploads is still accepted; it now does the same and no longer applies only to the uploads. |
without a value |
--accept-damaged |
Also restores a backup with damaged entries and leaves out exactly these entries. Without the parameter the restore ends before anything is switched and shows the number of damaged entries. | without a value |
--accept-failed |
Also restores a backup of which entries could not be created in the build folder (no space, no permission, name conflict) and leaves out exactly these entries. Without the parameter the restore ends before anything is switched. | without a value |
--without-confirmation |
Switches over in this process, without the confirmation of the new website. For servers on which the self-request does not work. | without a value |
--background |
The command only starts the restore. The website continues it by itself. | without a value |
# Restore the whole backup wp cloneworx-backup restore run <Job> # Restore only the database wp cloneworx-backup restore run <Job> --roots=db # Restore only plugins and themes wp cloneworx-backup restore run <Job> --roots=wp-plugins,wp-themes
The command writes one line with the progress per step. While the web server switches over, the command reports every ten seconds that it is waiting. At the end the result is shown: the backup and the target, the roots, the number of entries written, the files outside the backup, the comparison of the wp-config.php with the backup, the database with tables and rows, the duration of the switch-over, the method of confirmation and the response of the start page. The last line shows the number of warnings and the time until which the previous state is kept.
These lines of the result show what was not in the backup and what the comparison of the wp-config.php shows:
| Line in the result | Meaning |
|---|---|
wp-uploads: … files not in the backup, wp-root: … files not in the backup
|
This many files of this root are not in the backup; in brackets it says how many of them are executable. The line ends with they stay or, with --remove-extras, with … moved to the previous state: this many files were moved to the previous state. If files could not be moved, … could not be moved and stay follows. |
wp-config.php: |
The comparison of the wp-config.php of this website with the backup. A backup never contains the file; the line therefore reads not in the backup, nothing to compare. |
tables not in the backup stay: |
The tables of this website that are not in the backup. These tables stay. |
tables not in the backup moved to the previous state (undo brings them back): |
With --remove-extras: these tables were moved to the previous state. |
could not be created:, name conflicts:, symlinks pointing outside:, damaged:
|
The names of the entries that could not be created, that had a name conflict, that point outside as a symbolic link or that are damaged, up to ten each. |
…: … excluded entries inside swapped folders stay in place |
This many entries that were excluded from the backup stayed in place inside switched folders. |
The restore never puts back the wp-config.php; it stays as it is.
After a restore of the database your login in the WP admin may be invalid. Log in again in that case.
As long as the rollback of a restore is open, no new restore starts. Keep the open restore first or undo it.
Showing the state of a restore: status
restore status shows the running restore. If none is running, the command shows the restore whose rollback is open. With the job name of a restore it shows exactly that one. The action has no parameters.
# Show the running restore or the pending rollback wp cloneworx-backup restore status
For a running restore the output shows the phase and the progress. For a finished one it shows the status, the rollback with its deadline and the result as after restore run.
Keeping or undoing the restore: keep, undo
| Action | Purpose |
|---|---|
restore keep |
Keeps the restore: the plugin removes the previous state, the old folders and the old tables. This includes what --remove-extras moved to the previous state: these files and tables are then permanently deleted. After that there is no rollback any more. |
restore undo |
Undoes the restore: the plugin brings the previous state back, including the files and tables that --remove-extras moved to the previous state. Uploads that were replaced in place stay as the restore wrote them. If keeping has already begun, restore undo refuses. |
Without a job name both actions use the restore whose rollback is open. With --background the command only starts, and the website continues the job by itself.
# Keep the restore wp cloneworx-backup restore keep # Undo the restore wp cloneworx-backup restore undo
The output shows how many entries were removed and how many tables were removed or put back. If you decide nothing, the plugin keeps the restore on its own after 7 days. More about this: Keep or undo a restore.
When the WP admin cannot be reached
For a restore on the command line you need no login in the WP admin and no browser. You need access to the server and WP-CLI. The commands exist as long as WP-CLI can load WordPress with the plugin.
- Find the backup:
wp cloneworx-backup backup list. - Run the pre-check and read the line
loopback. WithOKthe self-request arrives. WithWARNit does not arrive: the restore then only works with--without-confirmation. WithUNKNOWNthe plugin has not tried the self-request on this server yet. - Start the restore with
restore run. If the self-request arrives, the restore runs as described above. - If the restore aborts because the self-request does not arrive, the website keeps running on its previous state. Then start the restore once more, with
--without-confirmation. - Check the website. If something is wrong,
restore undobrings the previous state back.
# Step 1: find the backup wp cloneworx-backup backup list # Step 2: the pre-check wp cloneworx-backup restore precheck <Job> # Step 3: the restore wp cloneworx-backup restore run <Job> # Step 4: switch over in this process wp cloneworx-backup restore run <Job> --without-confirmation # Step 5: if needed, bring back the previous state wp cloneworx-backup restore undo
Without confirmation you check yourself
With --without-confirmation the new website does not confirm itself. If it does not start, the plugin does not switch back on its own. The OPcache of the web server is not cleared: the server may serve old code for a while. Check the website yourself after the restore.
Importing a backup from a file: import
import accepts a backup file that is on this server: the tar file from downloading a backup. The plugin reads the file in parts, checks every part of the backup against its checksum and stores the backup at the target you specify. Afterwards the backup is in the list, under the job name of the original backup. As the date backup list shows the time of the import.
| Entry | Meaning | Allowed values |
|---|---|---|
<Datei> |
The backup file. Required. The entry comes directly after import. |
Path of a tar file on this server |
--target |
The target at which the backup is stored. Required. | Identifier of a usable target |
--background |
The command reads the file and only starts the import. The website continues the job by itself. | without a value |
--max-per-step |
Ends every step of the check after this many parts. The parameter is meant for diagnosis. | whole number |
--force |
Also runs as another user. | without a value |
# Import a backup file to the target local-1 wp cloneworx-backup import /tmp/backup.tar --target=local-1
The command imports a backup that this website does not know only with --accept-unknown.
The command first shows the size read and the job name of the backup in the file, then the progress of the import. At the end you see when and on which website the backup was made, at which target it is stored now, how many parts were checked and which roots it contains.
The command ends with an error
- if the file is not a backup file of this plugin or is incomplete,
- if a part does not match its checksum: then nothing is stored,
- if the same backup is already stored at this target,
- if there is a different backup with the same name in the list,
- if there is not enough space in the work folder for the file,
- if the file is larger than 32 GiB.
If the same backup has so far been stored only at another target, its entry in the list gets the new target added.
A backup that the import adds to the list as a new entry stays until you delete it
A backup that the import adds to the list as a new entry has the plan import. The plugin never deletes it automatically. It does not count for the warning about overdue backups. If an existing entry only gets the new target added, it keeps its plan: if backup list shows the identifier of a backup plan or manual there, the backup also counts for Max. backups at the new target, and the plugin can delete it there automatically.