Restore and import with WP-CLI

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 named in The commands at a glance.

This applies to all actions

• You name a backup with its job name. wp cloneworx-backup backup list shows it. In the examples it is written as <Job>. A backup with the status success or warnings can be restored.
• Only one job ever runs per website. If one is already running, every command that starts a job ends with an error and names the running job.
• The outputs are in English. The deadline of the rollback is shown there in UTC.
• All actions except restore status first check the user: the command must run as the user who owns the folders of the plugin. For restore precheck and import, --force skips the check. For restore run, keep and undo there 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. For the probe of the rights 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. wp-config is never restored.	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 way without rollback for the uploads when the space next to the live folder is not enough.	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

The first line of the output names 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. 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

restore run restores the chosen roots. This is how it happens:

1. The pre-check runs as the first phase. A FAIL ends the job before anything is written.
2. 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.
3. Uploads and files in the root folder are switched by the plugin file by file, without maintenance mode.
4. Database, core, must-use plugins, plugins, themes and the rest of wp-content are switched over by the plugin in the maintenance mode of WordPress. This step runs in the web server: the command hands it over via the self-request and waits.
5. 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.

Never restored are the plugin itself with its folders and tables and the wp-config.php. Files in the uploads and in the root folder that are not in the backup stay. Tables of this website that are not in the backup stay; the result names them.

Parameter	Meaning	Allowed values
--target, --roots, --include-core, --include-dropins, --include-htaccess, --uploads-in-place	As with restore precheck.	as above
--remove-extra-uploads	Moves uploads that are not in the backup to the previous state. With restore undo these uploads come back. By default they stay.	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 names the number of damaged entries.	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 drives it on 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 database with tables and rows, the duration of the switch-over, the way of the confirmation and the response of the start page. The last line names the number of warnings and the time until which the previous state is kept.

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 names the phase and the progress. For a finished one it names 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. After that there is no rollback any more.
restore undo	Undoes the restore: the plugin brings the previous state back. Uploads that were replaced in place stay as the restore wrote them.

Without a job name both actions take the restore whose rollback is open. With --background the command only starts, and the website drives the job on itself.

# Keep the restore
wp cloneworx-backup restore keep

# Undo the restore
wp cloneworx-backup restore undo

The output names 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.

1. Find the backup: wp cloneworx-backup backup list.
2. Run the pre-check and read the line loopback. With OK the self-request arrives. With WARN it does not arrive: the restore then only works with --without-confirmation. With UNKNOWN the plugin has not tried the self-request on this server yet.
3. Start the restore with restore run. If the self-request arrives, the restore runs as described above.
4. 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.
5. Check the website. If something is wrong, restore undo brings 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

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 name. Afterwards the backup is in the list, under the job name of the original backup. As the date backup list names 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 drives the job on itself.	without a value
--max-per-step	Ends every step of the check after this many parts. The parameter serves 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 first names 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.

See also

• Restore the website from a backup
• Restore a backup on another website
• Restore uploads when there is not enough space
• Import a backup from a file
• Create and manage backups with WP-CLI