Support

Documentation

Chapter 5. Restoring backups and transferring sites

Backups taken with the application can be restored on the same site they were taken from, a different location (subdirectory, subdomain or domain) on the same server or even on an entirely new server. From our software's point of view, a backup restoration and a site migration is exactly the same thing. This is what sets the application apart from its competition.

Throughout this chapter we are referring to this process as "restoration". Rest assured, everything we describe as being part of the "restoration" applies equally to site transfers.

General guidelines for backing up and restoring sites

General guidelines for backing up and restoring your site

Restoring sites with Akeeba Solo and Akeeba Backup is easy. Sometimes it may even be too easy which makes you prone to making obvious mistakes due to the implied complacency of using third party software to restore your site. In the following paragraphs we explain how to avoid the most common mistakes. This is a long read but we recommend that you read and understand it. We will not accept any "bug" reports about these issues which are, ultimately, user errors. If you need clarifications about any of these issues, however, do feel free to ask us (and be specific about what you didn't understand). We will be happy to help you better understand the issue.

Make sure you have backups before you need to restore your site. Over the years we've come across many people who were furious that having installed, but not having used, our backup software didn't help them when their site got destroyed. Don't be that person. Take frequent backups of your site, at the very least before updating your site (or any third party software running inside it, such as WordPress plugins and Joomla! extensions) and after making any substantial change to your site. It's dull, it's boring, it's a chore, it will save your life one day. Always keep at least one copy (ideally: three copies) of your backups outside of your site and ideally outside of your computer too. What is the point of having your backups stored on your site's server when the server's disk crashes or the hosting company goes bankrupt?

Test your backups periodically. Maybe you excluded a database table you didn't mean to. Maybe a folder was unreadable but you ignored the warning. Maybe the FTP program you are using to download your backups is broken. Maybe you accidentally set the temp-directory or logs file directory of your site to your site's root or another important system folder, ending up excluding it automatically in the process. Maybe there was a bug in the version of Akeeba Solo or Akeeba Backup you were using, it created a corrupt archive and you didn't update to the next version that fixed it (it happens once every 3-4 years, we usually fix the issue within 24 hours). No matter what happened, a corrupt backup can ruin your day. Test your backups periodically to make sure that they actually work.

Multipart backup archives. Some backup archives may consist of more than one files. These are called multipart backup archives. You MUST download all part files to have a backup archive set which can be used to extract all files and restore a site. All files have the same base name, for example site-www.example.com-20220925-105300-abcdef012345, but different extensions. JPA archives have the extensions .jpa, .j01, .j02, …; JPS archives have the extensions .jps, .j01, .j02, …; ZIP archives have the extensions .zip, .z01, .z02, … The part files of a multipart backup archive are NOT separate archives; you cannot extract its one of them individually. The are all parts of the same archive and they all need to be present for the archive to be able to be extracted. The order of the parts is .j01, .j02, …, .jpa for JPA archives; .j01, .j02, …, .jps for JPS archives; and .z01, .z02, …, .zip for ZIP archives. That is to say, the numbered part files come first in the numeric order defined by their extension, the file with the .jpa, .jps or .zip extension comes last. You can extract multipart archives using the integrated restoration but also Akeeba Kickstart Core, our free of charge archive extraction tool. It can run on a web server — even a local web server created with MAMP, WAMPserver, XAMPP etc — or, for expert users, on the command line.

Akeeba Backup archives are self-contained. The backup archive contains a copy of your site's files, an export of its database data and the restoration script to put everything together. This is very different to most other backup software in that the restoration script is inside the backup itself, not a separate thing you need to install. The only thing you need to do before restoring a backup is extract the backup archive. This can be done with Akeeba eXtract Wizard (desktop software), Akeeba Kickstart (single file web application), Akeeba UNiTE (automatic site restoration running under the CLI) etc.

Restoring a backup overwrites the entire site (e.g. WordPress or Joomla installation). It cannot be used to transfer content between different site installations. An Akeeba Backup archive contains your entire site, files and database contents. Restoring a backup will overwrite the files and database tables that have the same name as those included in the backup. As a result it cannot be used to transfer content (e.g. blog posts or pages) between two different CMS installations, e.g. between two WordPress sites or between a Joomla! and a WordPress site. It will transfer the entire site installation instead.

You DO NOT need to install a site (e.g. WordPress or Joomla!) before restoring a backup. As explained above, an Akeeba Backup archive contains your entire site and the restoration script required to restore it. You do not need to have a functional site to restore a backup. The whole point of Akeeba Backup is restoring a backup when the site is no longer functional. Moreover, we recommend NOT installing a CMS before restoring a backup.

Restoring a backup does NOT delete files on your site which don't exist in your backup. If a file exists on the site you are restoring to but not inside the backup archive itself it will not be overwritten. This is important in two cases. First, when you are restoring a backup after your site is hacked (unhacking a site). The hacker may have left behind files which can be used to re-hack your site. These files will not be deleted automatically. You want third party software or services to detect and remove these files. Furthermore, if you are trying to replace a site with a new one. If the old site is based on an older version of the CMS you are using or a different CMS, or if it is a static site or had different extensions / templates installed these files will be left behind. In both of these uses cases you should take a copy of your site's files, then delete all files and folders, create a new database and finally restore the backup.

Make sure you are backing up only the files that belong to the site you want to back up. This is very important when you are backing up a site in the root of your domain but you have additional sites in subdirectories (or subdomains whose root directory is a subdirectory of your main site). Akeeba Backup does NOT assign meaning to your directory names! It does not know that the directory old_site has a copy of your site from two years ago or that the folder gju4rl has the files for a subdomain you use to share files with your cousin who lives in another country. Akeeba Backup will backup all files and folders under the root of your site unless you tell it otherwise with the Files and Directories Exclusion feature. In any other case restoring your main site would overwrite the files of all the sites in subdirectories under your main site's root!

Make sure you are backing up only the database tables that belong to the site you want to back up. This is very important when you are backing up a site that shares a database with another site. Akeeba Backup does NOT assign meaning to the prefix used by your database tables. All tables in the database used by your site will be backed up regardless of their database prefix. If you use the same database for the tables of other sites, e.g. sites installed in subdirectories or subdomains on the same hosting account, you MUST exclude them manually with the Database Tables Exclusion feature. Otherwise restoring your site would overwrite the database of all of the other sites sharing the same database.

Keep copies of your backup archives outside of your site. The reason is simple: human error. If you mess up the restoration and, at the same time, somehow delete your only backup archive you are in deep trouble. Always keep several copies of your backup archives before doing a restoration. We recommend having at least THREE copies: on your computer, on a cloud storage provider (e.g. Dropbox, OneDrive, Google Drive, ...) and on a USB stick you keep in a sealed envelope in your desk's drawer. You can never have too many copies of your backups - but you can have too few!

Always practice the restoration on a test server / subdomain before doing it on your live site. Do you know why the military has so many drills? By repeating the same task over and over they get to perform it near perfectly, every single time, without thinking - even when bullets are flying around them. You don't want to start learning how to restore backups when your site is down. At that point you want your site restored, pronto. That's why you should practice restoring backups before you need to restore them. Practice on a test server, e.g. a MAMP, WAMPServer or XAMPP installation on your computer, or a subdomain on a server under your control. Once you have done this a few times you can restore any site, anywhere, without much thinking and without mistakes.

Make sure you have a database. Even though Akeeba Backup's restoration script can try to create a database for you this WILL NOT work on most database servers for security reasons. Creating a database requires database server administrator (root) privileges which you typically do not have and, even if you do, should not use when restoring a site to a live server. Instead, create a database for your site in advance. You will also need to create a database user and give it the correct privileges as described in our troubleshooter.

Do not restore in a subdirectory of your main site. For example, if your site's root is in public_html do not restore to public_html/dev. The reason is that the .htaccess files, which tell Apache (your web server) how to server your site, cascade. That is, Apache will read all .htaccess files in all folders leading to the one hosting your site's index.php file. This will cause problems with the restored site which you will experience as 404, 403 and 500 error messages or blank pages. These have nothing to do with our software and / or the restoration. It's how your web server works. Use a subdomain instead.

If you are restoring on a subdomain, make sure that the subdomain's root directory is NOT a subdirectory of your main site. This is the same as the previous paragraph, really. Most hosting control panel software default to using a subdirectory of your site's root when creating a subdomain. For example, if your site is www.example.com and its root is public_html if you create the subdomain dev.example.com your hosting control panel will put its root in public_html/dev. Therefore you will have the problem we described above. In this case ask your host what is the best way to create a root folder for the subdomain next to public_html, not inside it.

Try restoring to as close a PHP version as possible. Not all third party software installed on your sute support all PHP versions. If your site was running on PHP 5.6 and you try to restore it on a server running PHP 5.3 or PHP 7.1 your site may break. This has, again, nothing to do with Akeeba Backup. Upholding the minimum / maximum PHP version requirements of the software running on your site is your responsibility. We have no way of knowing that information. All we can do is print out the PHP version of the site you backed up and the site you are restoring to during restoration. Everything else is up to you.

Don't try to restore to a different database technology. If your site runs on MySQL don't try to restore it on a server that only supports PostgreSQL or Microsoft SQL Server. Even though some CMS support all of these database technologies they are incompatible with each other and you cannot transfer data between them. You can only restore a site on the same database technology it was backed up on. Clarification: MySQL, Percona and MariaDB are all using the same database technology, collectively called "MySQL". While you can a site between these different MySQL-type database servers we recommend against it. Subtle differences between them may cause restoration errors in some cases. In the few cases we can prevent that, we have added the necessary workarounds. There are some cases we can do nothing about. If you get a database restoration issue please check if you're trying to restore to a different MySQL-like database server than the one you backed up from.

Do not try to overwrite one CMS version family with a different one. If you have a site using one version of your CMS and try to restore a backup based on a different (newer or older) version of it may result in a broken site. This has to do with the way different CMS load their files from disk automatically based on several conventions. The best way to deal with such a case is deleting the existing files and folders (except, perhaps, user generated content) before restoring the backup.

Pay attention when restoring to a different domain, subdomain or folder: you will need to enter the domain name, directory and database connection information where you are restoring to. If you don't pay attention you may overwrite a site you didn't intend to touch!

The restored site is a fully functional clone of your original site. There is no functional difference between a restored site and one you built from scratch. This means that you can always backup the restored site and then restore that new backup on top of the original site. This makes Akeeba Backup ideal for live-to-development and development-to-live site transfers. If you are an advanced user such as a busy web agency do note that the process can be fully automated using Akeeba UNiTE: it can take a backup remotely, download it and restore it.

Guidelines for storing your backups remotely / "cloud backup"

[Note]Note

This only applies to Akeeba Backup Professional and Akeeba Solo Professional.

Uploading backups to a remote location requires setting up a Post-Processing Engine in the Configuration. By default, your backups are only stored locally, on the server where the site being backed up lives. If you want the backup to be uploaded to remote storage you have to go to the Configuration page and set up a Post-Processing Engine. As with all Configuration settings, this is set up per backup profile. Each profile can have a different post-processing setup - or no post-processing setup. Remember this if you're trying to figure out why your backups don't upload.

Uploading your backup archives can happen during or after taking the actual backup. All post-processing engines have an option to "Upload parts immediately". When this is enabled (checked), Akeeba Backup will upload each backup archive part file as it's finished being created. The first part of the backup is exempt from this rule: it is always uploaded after Akeeba Backup is done backing up your site. The first part contain special information about the number of part files and / or the number and size of files in the backup, information which is only known after the backup is complete. When the "Upload parts immediately" option is disabled (unchecked, the default state) Akeeba Backup will finish taking a backup of your site and only then will it upload the backup to remote storage. Therefore, when you are perceiving an issue with Akeeba Backup "not uploading your backups" first check if you have an issue preventing the backup to be taken at all!

A failed upload to remote storage does not cause the backup record to be reported as failed. As far as Akeeba Backup is concerned, backing up and uploading are two distinct operations. If the backup completes but the upload fails the backup record will appear as "OK" (green), NOT as Failed (red). If both the backup and upload are successful the backup record will appear as either OK (if the backup archive is kept on your site's server) or Remote (if the backup archive is deleted from your site's server, the default option). This distinction makes sense: if the backup is complete you can still restore your site from the generated backup archive.

Most failed uploads are caused by timeouts. PHP and your web server have time limits, i.e. the maximum time a PHP script may process data before the web server aborts it. Uploading the backup archives to cloud storage takes time, the exact amount of which depends on the size of the file and the network speed. If that time is over either time limit your backup will fail. The time limit and the bandwidth are beyond our control. The only thing you can control is the size. Many post-processing engines support chunked uploading (breaking up the uploads in smaller bits and having the remote server piece together the file) and you can change their chunk size. A chunk size of 5 or 10 MB works best in most cases. For those post-processing engines which don't have an option for chunked uploads you will have to change the Part size for split archives in the Archiver Engine options. Again, a value of 5 or 10 MB works best in most cases. This setting will split our backup archive into multiple files (same base filename, the extensions are .j01, .j02, ..., .jpa; or .j01, .j02, ..., .jps; or .z01, .z02, ..., .zip;), the maximum size of each one being the value of this setting. To restore these backups just place ALL of these files in the same directory and choose the main .jpa, .jps or .zip file: the other parts are discovered and extracted automatically.

If you get no uploads / zero sized uploads but not error message, contact your host. We have seen many hosts putting a (broken) caching proxy in front of their web servers. Instead of letting Akeeba Backup communicate with the remote storage server they immediately return an HTTP 200 OK response without contacting the remote storage server. Unfortunately, for many remote storage services such as Dropbox, OneDrive and Google Drive this would be the expected response when the upload succeeds. How you can tell this happened? Check the Akeeba Backup log file. If the upload takes less than 2 seconds we GUARANTEE that your host is doing what we just described. Their first level support may deny it; ask to escalate to a server technician. They will add a proxy server exception and your remote backups will work perfectly.

You can't upload to multiple locations. You can only set up a single post-processing engine. Multiple upload locations would increase the load on your server and the likelihood that something fails during backup. Moreover, this does not offer the kind of redundancy you might hope to achieve. Instead, use Dropbox, OneDrive or Google Drive to automatically download the backup archive to your computer. Use a regular desktop backup software to back up the local copies of your site's backups to a NAS.

If some part files of your backups failed to upload use the Manage remote backups in the Manage Backups page to retry uploading them. Sometimes a temporary network issue may prevent the upload from going through. Using the Manage remote backups to retry the upload usually works just fine!

If your uploads fail with long, cryptic errors about the signatures being wrong please check the time and the timezone of your server. Most remote storage engines require your server's time to be set within a reasonable accuracy to the true time. This can be automated on your server by setting and running the ntpd service. If your host hasn't done so the time will drift until it's so far off the true time that uploads will fail. If you get these cryptic error messages about signatures first triple check that your credentials are set up correctly in the post-processing engine options in the Configure page for the backup profile that fails. If you have triple checked them and found them to be working, contact your host and ask them to check the time and timezone on the server. It's silly, but this is the second most common cause of upload failures (after the part size discussed above) that we keep seeing.