Support

In order for ANGIE to work it needs to be able some temporary data between page loads. This data is stored in files inside the installation/tmp directory of your site during the restoration. Depending on your server and the way you extracted the backup archive this directory may end up being unwritable for PHP and, of course, ANGIE itself. The easiest way to work around it is giving this directory 0777 permissions using your favourite FTP programme. We have, however, found out that many of our users feel lost when they are told they have to change permissions. As a result we have made ANGIE very smart and capable of fixing this problem by itself, as log as you give it your FTP connection information first. Therefore, in case that this problem is detected, you will see the following page:

You have to provide the following settings:

Then click on the Apply changes button. If all of the FTP connection information is correct, PHP can connect to your site by FTP and your FTP server allows changing permissions you will see the main page of ANGIE. Otherwise you will see the session fix page again. In this relatively rare (less than 5% of servers out there, according to our experience) case you will have to change the permissions of the installation/tmp directory manually, using your FTP software or your hosting control panel.

Your backup contains all of the database connection information and, sometimes, the FTP connection information as well. This means that anyone who has access to the backup restoration script over the web can learn this information. This is a security risk. While Kickstart allows you to use Stealth Mode (which locks the site for everyone except your own IP address) this only works on servers using the Apache web server. With alternative web server software such as IIS, NginX, Litespeed and Lighttpd becoming more popular this doesn't cut it any more.

This is why we added support for password protection to ANGIE. You can enabled it in the application, in the Configuration page of the component. You also get the chance to override that password when taking a backup from the back-end of your site, by providing it your desired password to the "ANGIE password" field in the Backup Now page. The password is stored in the backup archive encrypted, making it more difficult to be accidentally exposed to a hacker.

If you have specified a password for ANGIE you will see the ANGIE password page when you launch it. Just provide your password and ANGIE will show its main page. If the password is incorrect you will be shown the password page again.

In some cases you may have forgotten your ANGIE password or not remember setting one. The latter could happen if your browser auto-fills a password in the backup page. You can still continue the restoration by deleting the file installation/password.php from your site which is currently being restored. Then reload ANGIE and the password page will go away without having to enter a password.

First you see ANGIE's initialisation page:

At this point ANGIE is performing system checks. If your browser gets stuck at this page please try disabling any browser plugins, firewalls and antivirus applications which might be interfering with the Javascript on the page. The most likely culprits we've seen are NoScript (a Firefox plugin which disables Javascript) and AVG Antivirus' "Link Checker" feature which ultimately breaks Javascript on most pages. If that doesn't help please try using a different computer, with a different browser and connected via a different ISP to the Internet. Sometimes computer policies, proxies and other network settings can interfere with web applications such as ANGIE or the site script you are restoring.

The next page you will see is the main system checks page. In this page ANGIE checks your server configuration and makes sure it matches the requirements of both ANGIE and the site script you are currently restoring. The exact layout of the page depends on which ANGIE installer you are using. Here you can find links to these specialised installers, in alphabetical order:

At the top of the page you see which database you are about to restore. The first database you will be restoring is the "site's main database" which means that it's the database your web script uses to store its data (the one you set up in the configuration wizard or the application's Configuration page). If you had defined multiple databases you will be restoring one database after the other, but the "site's main database" is always the first one to restore. If you do not wish to restore a particular database you can click the orange Skip Restoration button in the top right hand corner of the page.

The first thing you see is the Connection information column in the left hand side of the page. It is pre-populated with the connection settings of the site you backed up. If you are restoring to a different site than the one you backed up from it will be blank, indicating that you must specify the correct connection information for the new server.

Start with the database type. It's usually MySQLi (with the "i" at the end), unless you have a server with an outdated PHP version or suboptimal server settings. The other option, MySQL (without the "i" at the end) is the old MySQL driver which is slower and was ultimately removed in PHP 5.5.0 released on June 2013. The final option is the PDO MySQL which is another modern driver for MySQL. It's just as fast as the MySQLi driver. If you see no option then your new server lacks the PHP modules which are necessary to connect to MySQL databases. Do note that it's not necessary to have a MySQL-compatible database server (MySQL, MariaDB, Percona, Amazon RDS etc). Your version of PHP also needs to include the mysqli or pdo_mysql module which allows it to talk to MySQL servers. If the list is empty you need to contact your host.

The other available options you need to set are:

The Database table name prefix is up to your liking. For security purposes it's best to not use the default prefixes used by most common site scripts (e.g. jos_ or wp_). Ideally, you should use three to four letters followed by an underscore, e.g. tst_ or test_.

After entering this information, take a look at the the Advanced options column on the right hand side of the page.

The With existing tables option lets you decide what to do with tables which have the same name as those currently being restored. The default Drop option will delete same-named tables during restoration without asking. The Backup option will keep a copy of those tables, changing their name prefix to bak_, i.e. an existing abc_users table will be renamed to bak_users. Existing bak_ tables will be deleted before the rename. Both Drop and Backup options apply to tables that are being restored by ANGIE.

There are two more options which apply to tables in your database even if they are NOT included in the backup archive you are restoring or if you chose not to restore them via the Select which tables to restore option. Drop same prefix will delete all tables with the same prefix as the Database table name prefix you defined in the Connection Information. Drop All is the most dangerous option. It will remove all tables from the database, regardless of their name. If you are sharing a database with another site its database tables will be erased. Both of these options are dangerous and can cause permanent data loss. Be very careful when you use them!

Select which tables to restore allows you to perform a partial restoration. Select which of the tables backed up should be restored. Make a multiple selection with CTRL-click (Windows, Linux) or CMD-click (macOS). Any table you have not selected here will not be restored; it will be skipped over. This an advanced feature. Use it if you are absolutely sure about what you're doing. Skipping the restoration of the wrong table may cause your site to malfunction or not work at all.

Suppress Foreign Key checks allows you to restore cross-linked tables without MySQL errors. Leave it on. Use REPLACE instead of INSERT may be required if you keep getting MySQL errors about rows already existing in your tables. Force UTF-8 collation on database and Force UTF-8 collation on tables should be enabled on all sites which use non-ASCII characters in their contents, e.g. accented Latin characters, German umlauts, Cyrillic, Greek, Chinese or any other characters which are not normally used in the English language. If unsure, make sure it's checked.

No auto value on zero works around a problem with some software which uses an auto incrementing counter column in a database table but also inserts the numerical value 0 in it. This can cause problems during restoration which why this option exists. If unsure, keep it enabled.

Use REPLACE instead of INSERT tells ANGIE to use REPLACE database commands to apply the restored table contents instead of INSERT. This is rarely necessary, if you have edited your SQL files by hand and removed the CREATE TABLE lines. If you don't know what it is you most likely don't need it.

Some PHP software, such as Joomla 3.7 and later, is using the utf8mb4_general_ci collation instead. This collation supports multi-byte Unicode characters such as Emoji, certain Traditional Chinese characters and so on. If you need to restore such a site please remember to turn on the Allow UTF8MB4 auto-detection option.

In case you have taken a backup on a server supporting UTF8MB4 but trying to restore on a server that doesn't you will observe that this results in an error. This is by design: UTF8MB4 supports more characters (notably: emoji) than UTF8. If the database server allowed you to restore UTF8MB4 data to a UTF8 table / table field you'd lose data. If, however, you are absolutely sure you want to downgrade your UTF8MB4 data to UTF8 and complete the restoration you can do that in newer versions of our restoration script by selecting (checking) the Force UTF-8 collation on tables option but NOT selecting (leave unchecked) the Allow UTF8MB4 auto-detection option. Please note that if you have extended, 4-byte characters such as Emoji, certain traditional Chinese characters etc they will be replaced with the Unicode Replacement Character (�) as they cannot be mapped to plain UTF-8.

As a final note on the subject of UTF8MB4, if you back up a site on a server supporting only UTF8 and restore it to a server supporting UTF8MB4 you will NOT have a problem. Therefore you do not need to do anything special.

Handling database errors

On rarely cases during the restoration you could get a database error. This is not caused by Akeeba software, but by the data you're trying to restore (in other words: you would get the error even manually importing the SQL file using PhpMyAdmin). However, if that data is not crucial, your site would work perfectly fine without it. Think about logging data, statistical information or some article metadata that is too large for your new database: if one page is missing an image or some formatting that's something you can manually fix later.

This is when the options Stop on CREATE error and Stop on other error come into play. By default ANGIE will stop when something wrong happened, if you uncheck those fields, ANGIE will ignore any database error, showing you a report of the failed queries. In this way you can review them and know which part of the old database wasn't restored in the new one.

You will find the Fine Tuning area towards the bottom. The setting Maximum execution time should be left at its default values unless you get AJAX or timeout errors while ABI is restoring your database. In this case, try setting it to 3, 2 or even 1. This will slow down the restoration a bit, but it will make it more resilient to timeout issues. The Throttle time (msec) should be left at 250 unless you are told by our support staff to change it.

When you're ready with all those settings, click on the Next button on the top right corner of the installer page to start restoring your database. The restoration dialog appears:

While your database is restoring, you will see the progress bar filling up and the information line below informing you of the processed and total size of the database dump file. The estimated time left is a very rough approximate. Should an error occur, you can close the dialog, modify the settings and retry by clicking the Next button again. Once the restoration is over, the Next step button appears:

Just click on it. If you have more databases to restore (only backups made with the Professional version, using the Multiple Database Definitions feature of Akeeba Backup Professional) you will see the database setup page again, but the header will read the name of the extra database instead of Site's main database. If you have extra databases to restore you will see the same database restoration page for the next database.

If there are no more databases left to restore but you had defined off-site directories to be backed up, upon clicking Next step you will be taken to the Off-site directories restoration page.

If, however, you do not have any off-site directories upon clicking Next step you will be taken to the Site Setup page. The exact page depends on the installer you are using:

If you don't see that page, maybe you want to take a look at this troubleshooting page.

When Akeeba Backup backs up an off-site directory its contents are placed inside the backup archive in a directory called "virtual folder". By default this is external_files. Naturally, this is extracted inside the site's root which is not where these files need to be. Therefore, they have to be moved. This is what this page does: it moves the off-site folder from where they were extracted to where they should be.

The Virtual folder area shows you the directory inside the extracted site's root where the files and folders to be copied reside. In the Target folder you can enter the absolute filesystem path of where the files and folders contained in the displayed Virtual folder should be moved to. Click on the Next button to perform the move.

You can always click on Skip Restoration to skip moving the files and folders from the displayed virtual folder, e.g. when you would rather do that manually.

While the move is in progress you will see a progress bar filling up:

When the process is finished, ANGIE will let you know:

Clicking on the Next step button will let you move the next off-site folder.

When you have move all off-site folders, upon clicking Next step you will be taken to the Site Setup page. The exact page depends on the installer you are using:

If you don't see that page, maybe you want to take a look at this troubleshooting page.

Normally, you should see a success message like this:

If ANGIE could not write to your site's configuration file, it will present you with a dialog box informing you of this fact. You can close the message by clicking on the "X" button on its top right corner. You can then copy the contents of the text area and paste it into your configuration file - replacing any and all existing content - manually, following the instructions printed on this page. This is only required if your configuration file was not writable in the first place. Under most circumstances this won't happen. Do note that if you get this message and you do not follow the steps printed on the page your restored site will not work.

You now have three options to proceed, depending on how you extracted the backup archive.

If you used Kickstart to extract the backup archive, close the window/tab of the restoration script and return to Kickstart's window. You will see a big “Clean Up” button. Just click on it and it will automatically remove the installation directory, the backup archive, kickstart.php and its translation files, as well as rename htaccess.bak to .htaccess and php.ini.bak to php.ini respectively. No further action is necessary. Your restored site is ready for use.

If you were not using Kickstart, you can try clicking on the Remove the installation directory button to have ANGIE try to remove the installation directory automatically. If it succeeds, it will present you with a success dialog. Just click on the Visit your site's front-end button to visit your site's front page. However, if you used Kickstart to extract your files and clicked on this link accidentally instead of using Kickstart's Clean Up button you need to manually rename htaccess.bak to .htaccess and php.ini.bak to php.ini, as well as remove the archive file, kickstart.php file and all its INI files and the kicktemp directory (if one is present) manually.

If you uploaded the extracted files manually, you must remove the installation directory from your site using your FTP client application before visiting your restored site. If you don't, the restoration page may appear again. In this case do not run the restoration again. Just remove the installation directory through FTP and retry visiting your site.