Support

Documentation

Extracting your backup archives

There are different ways to extract your backup archive, depending on its format and where you intend to restore it to. If you are restoring on the same hosting account as your Akeeba Solo / Akeeba Backup installation the most convenient method is using the integrated restoration feature. If you are restoring to a different site or server using Akeeba Kickstart is the best option. Finally, if you are using a ZIP archive it is possible that some third party software will be able to extract it as well.

Using the integrated restoration feature (most common)

The integrated restoration feature allows you to easily restore a previous backup directly on your server, where you took the backup from, as long as your backup archive still exists on your server of course.

The communication between your browser and the archive extraction script is encrypted with the AES128 (Rijndael) encryption method, using a random key produced as soon as you initiate the restoration of a backup archive. This ensures that a malicious user can't exploit the restoration script to mischievously extract your backup archive in your site's root with the intent to steal your database password. The encryption/decryption algorithm is implemented with standard PHP and Javascript code, eliminating the need for third party cryptography libraries and ensuring that under no circumstances unencrypted data will be exchanged between the browser and the server.

In order to start an integrated restoration begin by going to the Manage Backups page of the component. In that page check the checkbox next to the backup you want to restore and click the Restore button in the toolbar to will run the integrated restoration feature for the selected archive file.

The integrated restoration setup page

When you first start the integrated restoration feature, you are presented with a few settings. The first setting, appearing above the Start Restoration button, determines how the file extraction will be performed. The available options are:

Write directly to files

All files will be extracted directly to their final location using direct PHP file writes. If your permissions settings do not allow some files or directories to be created/overwritten the process will fail and your site will be left in a half-restored state.

Use FTP uploads

Using this method, each file is first extracted to the temporary directory specified by the current profile and then moved to its final location using FTP. This is a "best effort" approach and can work with most servers. Do note that only unencrypted FTP (plain FTP) is supported. If you choose this option, you'll also have to specify the FTP connection settings.

[Tip]Tip

You can use this option to restore a backup on a different site. Just select this option and provide the FTP connection details to the other site before clicking on Start Restoration.

Hybrid

This mode combines the previous two in an intelligent manner. When selected, the application will first attempt to write to the files directly. If this is not possible, i.e. due to permissions or ownership of the file or folder being extracted, it will automatically make use of the FTP mode to overcome the permissions / ownership problem. It effectively works around a situation commonly called "permissions hell", where different files and folders are owned by different users, making it extremely difficult to overwrite them. This is a situation which happens very commonly on shared hosting. Therefore we strongly advise clients on shared hosting environments to use the Hybrid option.

[Note]Note

You MUST supply your FTP information for this mode to have any effect. If you do not do that the Hybrid mode will function exactly as the "Write directly to files" mode.

The default mode is writing directly to files, unless you have already enabled the FTP mode in the application's System Configuration page. In this case the Hybrid Mode is selected by default.

In the event that a partial restoration happens, your site will be left in a semi-restored state. Trying to access it will probably cause the restoration script (ANGIE) to appear. If you want to stop the restoration please remove the installation directory from your site's root manually, for example using FTP, before trying to access your site again. Please note that it is possible that your site is left in an unusable state by doing that. If this happens, please retry the restoration.

If you chose to use the FTP mode, there are some connection settings you have to take care of. They areL

Host name

The host name of your site's FTP server, without the ftp:// protocol prefix. For example, ftp.example.com is valid, ftp://ftp.example.com is invalid.

Port

The TCP/IP port of your site's FTP server. The default and standard value is 21. Please only use a different setting if your host explicitly specifies a non-standard port.

User name

The username used to connect to the FTP server.

Password

The password used to connect to the FTP server.

Initial directory

The FTP directory to your web site's root. This is not the same as the filesystem directory and can't be determined automatically. The easiest way to determine it is to connect to your site using your favourite FTP client, such as FileZilla. Navigate inside your web site's root directory. Copy (in FileZilla it appears on the right hand column, above the directory tree) and paste that path in the application's setting.

Test FTP connection

Clicking on this button will tell you if the FTP connection could be established or not. If the connection is not successful you should not proceed with a restoration in FTP mode as it will fail immediately.

The rest of the extraction process is automated, so there is not much to tell you about it. However, you must not that in order for the restoration procedure to work properly you must take care of the following:

  1. This feature is directly calling the restore.php script inside the application's root directory. If you have a server-side protection, i.e. .htaccess rules, or permissions settings which prevent this file from being called directly the process will fail.

    Security note: The restore.php file is of no use to potential hackers. In order for it to work at all, it requires the restoration.php file (more on that on the next point of this list) to load. Even then, it expects encrypted data with a key which is not predefined and is only known to the restore.php script and the integrated restoration page of the application. As a result, it can't be used as a potential attack vector.

  2. Before the restoration begins, the application needs to create the restoration.php file with all the archive extraction setup parameters. It is intelligent enough to use any FTP / SFTP file writing mode which you have configured in the System Configuration page to overcome any permission problems, but you are ultimately responsible for ensuring that the permission settings are adequate for the application to create this file.

    If you are using the direct file writes in the System Configuration page the permissions of the application's directory should be 0777 for the integrated restoration to work. USING SUCH BROAD PERMISSIONS IS NOT RECOMMENDED AND MUST BE AVOIDED IF AT ALL POSSIBLE. On hosts which use suPHP, FastCGI or other methods which ensure proper file ownership 0755 permissions are recommended.

    If you are using the FTP / SFTP layer, you'll need to give this directory at least 0744 permissions, but you may have to manually remove restoration.php (but NOT restore.php!!!) after the site restoration is over.

  3. When the extraction of the backup archive finishes, you will be asked to open the restoration script in a new tab or window. DO NOT CLOSE THE INTEGRATED RESTORATION PAGE'S TAB/WINDOW! Just point your browser to http://www.yoursite.com/installation/index.php (where www.yoursite.com is the domain name of the site you are restoring to) to access the restoration script.

  4. After you have competed the restoration script's process you are supposed to return to the Integrated Restoration page and click on the Finalize button to:

    • remove the installation directory from your restored site's root, and

    • remove the restoration.php setup file from the application's directory.

    If you have restored the backup to a site different than the one you backed up from, the Finalize button may fail to work. In this case use your favorite FTP client to remove the installation directory from the site you were restoring to and rename any htaccess.bak file back to .htaccess.