Support

Documentation

The setup page

The setup page

The setup page contains of four steps.

The first step is selecting a backup archive. Kickstart automatically scans the directory it's in for JPA and ZIP archives, populating the drop-down list with these results. If there are multiple archives present, please click on the drop down list and select the one you would like to use. Extracting JPS (encrypted) backup archives requires either the mcrypt or OpenSSL PHP extension to be installed and activated on your server. Please keep in mind that even if your site is using HTTPS this doesn't mean that you have the OpenSSL PHP extension installed. You usually have to ask your host to enable it for you.

If you want to import a backup archive stored in external storage such as Amazon S3, Dropbox etc please consult Importing archives from Amazon S3, Dropbox etc.

The second step is the selection of the extraction method. There are two supported methods:

Directly

With this method, Kickstart will try to write directly to files. This is the ideal method if your server is using suPHP or if you have no Joomla! site installed yet. Since Kickstart runs in PHP, which in turn might run with your web server's privileges, you have to ensure that there are adequate permissions to write to the directory Kickstart is in and any existing files and directories with the same name as files and directories in the archive. If you are not sure, first try to remove everything except kickstart.php and the backup archive from your server. If you still get errors regarding the inability to write to files, you'll have to use the FTP mode.

Use FTP

In this mode, Kickstart tries to extract the files in a temporary directory, then use FTP to "upload" them to their final location. The ability to run Kickstart in this mode depends on your server setup. For example, some servers have a very strange firewall setup which doesn't allow Kickstart to connect to your site's FTP. Also note that Kickstart support FTP and FTPS (FTP over implicit SSL). It does not support the SFTP protocol, widely known as Secure FTP or FTP over SSH, as it is an entirely different protocol with very poor PHP support on commercial hosts.

The only implication in using the FTP mode is that you need a writable temporary directory. More on that later.

When you choose this option, a list of several options will expand underneath it. You have to fill them in for Kickstart to be able to work.

[Important]Important

Kickstart 3.1 or later, when extracting any ZIP archive or JPA archives created by Akeeba Backup 3.1 (or later), will also try to restore the last file modification time to match that of the source server. If you activate the FTP mode this will not be possible, as FTP does not support "touching" (changing the modification date and time) of files.

Hybrid

This mode combines the previous two in an intelligent manner. When selected, Kickstart 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 exracted, 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.

The same notes regarding a temporary directory etc as the "Use FTP" mode apply for the Hybrid mode as well.

Moreover, there is also the Ignore most errors checkbox. When it's checked, Kickstart will not throw an error when a file is not writeable. This is useful when you are restoring a backup taken on a Linux server to a Windows server. In that case, some filenames may contain characters which are valid in Linux (e.g. colons) but not on Windows. Checking that option will tell Kickstart to ignore file creation errors.

[Warning]Warning

When that option is enabled, Kickstart will not warn you even if a file could not be overwritten because, for example, its permissions made it unwriteable. Use with extreme caution and always check that all of your files have been extracted properly.

The FTP Options

The FTP options which get to be displayed, should you choose the FTP mode, are:

FTP Host Name

If you are using the FTP mode, this defines the address of the FTP server used for uploading the files. Do note that you must enter only the domain or IP address, without the protocol. This means that ftp.example.com is correct usage, while ftp://ftp.example.com is incorrect.

FTP Port

The TCP/IP port of the FTP server to use. Normally you want to use port 21 (default plain FTP port). Only use something different if your host tells you so, or if you are using FTPS (FTP over SSL).

[Warning]Warning

If your host tells you to use port 22, their connection mode is not compatible with Kickstart. Port 22 is used by the SFTP protocol, which is entirely different that the supported FTP and FTPS protocols. In this case you have to ask your host for plain FTP access to your site.

Use FTP over SSL (FTPS)

Check the box if you want to use the FTPS (FTP over SSL) protocol. The default is unchecked which means that Kickstart will use an unencrypted connection. Do note that Kickstart does not support SFTP, as it is an entirely different protocol than FTPS. The names look alike, but the protocols have nothing to do with each other.

Use FTP Passive Mode

Check the box to use the FTP Passive mode (default), or uncheck it to use the FTP Active mode. Most probably you want to use the default value (checked), as it is the only way to work around the firewall of your host. A very small minority of hosts require the Active mode, but they will tell you so in their FTP connection instructions.

FTP User Name

The FTP username.

FTP Password

The FTP password.

FTP Directory

The absolute FTP path to your restored site's root. THIS IS NOT THE SAME AS THE FILE SYSTEM PATH TO YOUR SITE'S ROOT!!! The easiest way to figure this out is to use FileZilla. Connect to your target FTP server with FileZilla. Navigate to the web server's root (usually it's a subdirectory named httpdocs, htdocs, public_html, http_docs or www). Above the right-hand folder pane you will see a text box with a path. Copy this path and paste it to this setting.

Temporary Directory

As PHP can't directly upload files while they are being extracted, Kickstart is extracting them to a temporary directory using direct file writes first, then uploads them to their final destination using FTP. Normally, Kickstart will try using the directory it's stored in to extract the temporary files. Many web hosts configure their servers in such a way that this is not possible. Using this option you can customise the location of the temporary directory to somewhere with adequate permissions. You can use either an absolute or a relative (to Kickstart's directory) path for this setting.

If unsure, you can follow an easy workaround. Create a directory named kicktemp in your site's root using FTP and give it 0777 permissions (or world-write privileges, e.g. full control to the Everybody pseudo-user, if you are using a Windows server). Then type in kicktemp as this option.

[Tip]Tip

If you leave this field empty Kickstart will try creating the kicktemp directory automatically. On most servers this works just fine.

The third step is the Fine-Tuning of the extraction engine. In older versions these advanced options were hidden. Please click the Show advanced options (for experts) button to display the options. In newer versions (after 5.5.0) these options are displayed by default.

The first two options require you to understand how Kickstart works. Kickstart will start extracting files until the Maximum execution time threshold is reached. In fact, Kickstart allows for a 20% uncertainty of the accuracy of the elapsed time measurements, so the real duration may be somewhat less than that. If there are more files to extract, it will continue extraction in the next step. This approach allows it to work around the PHP time limit imposed by all hosts. However, if a step takes too little time, it is possible that your host mistakenly identifies this behaviour as a Denial of Service attack. As a result, Kickstart will force each step to last at least as much as the Minimum execution time value is. These two settings are expressed in seconds and can be perceived as a combined "from-to" step duration setting.

Next, you will find the options for the Stealth Mode in the Fine Tuning pane. The Stealth Mode allows you to display a static HTML page (optionally with images and SWF animation) to all visitors to the web site except yourself while you perform the restoration and only works with Apache or any other server supports mod_redirect functionality using .htaccess files (even some versions of IIS with third party add-ons do). This will prevent accidental disclosure of sensitive information while the restoration is in progress. This is performed by directing all traffic not coming from your IP address to the page you define in here. The first, obvious, setting is the Stealth mode check box. When you tick it, the stealth mode will be activated. The HTML file to show to web visitors option allows you to define the name of the static HTML page to show to your visitors. The file and its resources (images, CSS, Javascript files) must reside inside your to-be-restored site's root. You must only define the name of the file to use, not its URL. This means that offline.html is a valid setting, whereas http://www.example.com/offline.html is INVALID and will result in a 404 error thrown to your visitors.

[Tip]Tip

If you are worried about SEO, fear not. The redirection happens with a "temporary redirection" HTTP status code, which will instruct search engines to revisit your site in a later time. As a result, you are not penalized for duplicate content or otherwise negatively affect your SEO while restoring your site.

The next option, Delete everything before extraction is dangerous, meant for expert users and only available in the Professional version of Kickstart. When you select this option all files and folders under the directory where you are extracting your backup archive (i.e. the directory where Kickstart lives) will be deleted. This may include files and directories which are not present in your backup archive and which may NOT belong to your site. For example, if you have the web root folder of a different domain or subdomain, or a third party script, it would be deleted all the same. This is what makes this feature dangerous. If you don't think everything through you might inadvertently and irreversibly delete something you shouldn't. As such YOU ASSUME ALL RESPONSIBILITY AND LIABILITY if you enable this feature. For security reasons (preventing someone from visiting a leftover kickstart.php file on your site and deleting everything before you knew it) this feature is only available in the Professional version of Kickstart which only works if its file is renamed to something which does not contain the word "kickstart" in it, making it unlikely that it will be abused.

Then, we have the Rename server configuration files checkbox. By default, Kickstart will rename .htaccess to htaccess.bak, web.config to web.config.bak, php.ini to php.ini.bak and .user.ini to user.ini.bak before extracting the archive. Moreover, any files by that name in the archive will be renamed. When you click on the Clean Up button the files are renamed back to their original names. These are all files that take an immediate effect on the server and can possibly cause the restoration to fail. For example, a .htaccess file which prohibits execution of kickstart.php would cause the extraction to fail immediately. Unchecking this box will NOT rename these files back after extraction. To make it clear, let's take the .htaccess file as an example:

  • If this box is checked (default) the .htaccess file which was contained in the archive IS renamed to htaccess.bak as soon as it's extracted. After the restoration is complete, the htaccess.bak files IS renamed back to .htaccess

  • If this box is NOT checked the .htaccess file which was contained in the archive IS renamed to htaccess.bak as soon as it's extracted. After the restoration is complete, the htaccess.bak files IS NOT renamed back to .htaccess. Its name remains htaccess.bak and you have to manually rename the file, e.g. through FTP or your hosting control panel's file manager.

[Warning]Warning

Unchecking Rename server configuration files will most likely result in the restored site NOT working properly, or at all, until you manually rename and possibly edit the htaccess.bak, web.config.bak, php.ini.bak and user.ini.bak files.

Then you will find the Restore file permissions checkbox. When this is checked Kickstart will restore the permissions of the files (not folders!) to the ones they were at backup time. Please note that there are a few caveats:

  • This option only makes sense for backup archives taken on a Linux or macOS server and being restored to a Linux or macOS server. Windows servers do NOT have the concept of file permissions. Trying to use this option when restoring an archive on Windows OR with an archive that belongs to a backup taken on Windows this will have unpredictable effects. Just don't do it.

  • This option only works with JPA and JPS archives. ZIP archives do NOT store file permissions. Using this option with ZIP files has no effect.

  • Please remember that only permissions are restored, not the file ownership. The ownership of the files depends on your server setup and the file writing method you have used. Generally, it's a REALLY BAD IDEA to restore permissions if your original site had mixed ownership of its files.

  • This option does not restore folder permissions. Folders are listed before files in the archive and there's no guarantee that you're "done" extracting files to a folder. Therefore changing the folder permissions could easily make the folder unwriteable before we are done writing files to it, therefore causing the extraction to fail. As a result the folders always get 0755 permissions.

It is a generally BAD IDEA using this option. Restoring a backup archive will result, in most cases, in all files and folders having the same ownership and the same, safe permissions (0644 for files and 0755 for folders). Unless you truly understand what you are doing and have a very specific use case you are recommended to not use this option. If you are not positively sure about what you are doing you may end up breaking your restored site and we won't be able to help you.

Finally we have the Files to extract area. If you leave it empty (default) all of the contents of the backup archive will be extracted. Sometimes you only want to extract specific files which were unfortunately deleted or overwritten. In the olden days you'd have to extract the entire backup archive, find the files you need and upload them to your site. This option eliminates this need. Just enter one or more file paths or shell patterns, one on each line, and Kickstart will only extract these files. A few things you should know:

  • All files and folders are expressed relative to the archive. For example, if you are extracting an archive to /home/myaccount/public_html/site and the file inside the archive is images/cat.png then you must use images/cat.png in Files to Extract, NOT /home/myaccount/public_html/site/images/cat.png.

  • Always use forward slashes to separate folder names and file names, even on Windows. For example, images/cat.png is valid whereas images\cat.png is INVALID.

  • You can use wildcards in the names. * matches any number of characters, ? matches exactly zero or one characters.

    For example images/cat.jp? matches images/cat.jpg and images/cat.jpe but NOT images/cat.jpeg. On the other hand, images/cat.jp* matches all three files.

    Wildcards apply to folder names as well. For example, images/*/cat.png matches both images/foo/cat.png and images/bar/cat.png. It does not, however, match images/cat.png since it's missing a second forward slash.

  • If you want to extract all files and folders under a directory suffix it with /*. For example images/* will match all contents of the images folder. Be careful! Do not use *.* as it will only match folder and file names with a dot in their name!

  • For geeks and power users only: this field is parsed by PHP's fnmatch() function. This means that you can use any shell pattern for more complex filename pattern matching. Using shell patterns is the only way, for example, to extract the files under a directory but not its subdirectories.

The extraction page

For the fourth step just click on the big, green Start button and wait while Kickstart extracts your archive.

The restoration and clean up page, right after the extraction

When the extraction is complete, you will be presented with an option to launch the installer. Clicking on the large green button will launch the installation/index.php relative URL to a new window. If you were extracting a backup archive taken with Akeeba Backup, this will execute the restoration script which was included in your backup archive and just got extracted. You will not be running Kickstart at that point, so you have to refer to the Akeeba Backup documentation for more information on how the restoration script works. Please do not close Kickstart's window. You will need it later.

After you have completed your site's restoration and you close the installation script's window, you will get back to Kickstart. The interface has changed slightly in the meantime:

The restoration and clean up page, right after the restoration

Just click on the Clean Up button. The following actions will be performed:

  • The installation directory is removed as it is no longer required.

  • Renamed files are renamed back. See Rename server configuration files in the configuration documentation above.

  • The backup archive (and all its parts, if it is a multi-part archive) is removed.

  • Kickstart itself and all of its translation INI files, if present, are removed.

The final page

At this point you can simply close Kickstart's window. Alternatively, you click on either button (or both!) to open the respective area of your site to a new browser window/tab.

Troubleshooting

Kickstart tells me that this is not a valid archive?

First, ensure that you have downloaded and uploaded the backup archive using FTP in Binary transfer mode. If not, do it now. This is the most common cause of issues. Then, make sure that you have tried both the Direct and Hybrid file writing modes. The next step would be lowering the Maximum execution time setting to 2 or 3 seconds and setting the Minimum execution time to 1 second.

If you are still getting this error message and you are a subscriber you can file a support ticket. Please take a screenshot of the entire message (do not downscale it, we'll need to be able to read it) and attach it to your ticket. Please include as much information as you can regarding the error condition, how you took your backup, which EXACT version of Akeeba Backup you were using ("latest" doesn't help since we may have released an update in the meantime, or you may be using a dev release and so one), which EXACT version of Kickstart you were using (displayed in very large type at the top of the Kickstart page) and the PHP version of your host. Remember that the less information you give us, the more time it will take us to figure out what's going wrong and the less happy you'll feel about our support. We need you to help us help you.

I am getting "Can't open xyz for writing" or "Can't create directory xyz" error messages

The first thing you have to check, even though it sounds silly, is that you have enough free disk space. Most probably you have an account quota limit. Since you are extracting an archive, you must have at least as much as 2-3 times free space as your backup archive. This means that if you have a backup archive weighing 100Mb, you need another 150-200Mb to extract it. In total, you'd need 250-300Mb of free disk space before you begin uploading files and extracting the archive with Kickstart.

[Important]Important

Some hosts claim "unlimited" disk space. Sadly, this is never the case. Most hosts have "hidden" limits, such as the amount of files you can host under one account. If you go over that limit, you'll get extraction errors. Another thing is that you "unlimited" host is physically bound to the size of their hard drives. If their hard drive was close to completely filling up, trying to extract your site will also lead to a restoration failure. Moreover, we have seen hosts with "unlimited" space which actually give you a finite and small amount of space (e.g. 1GB) and you have to explain why you need more to get another chunk of free space (if you successfully convince them). If nothing else helps with this kind of errors, do contact your host and ask them if you are hitting a file count limitation or their hard drive is full.

Moreover, some hosts have a limitation on the maximum file size PHP can create. For example, Strato allows PHP to create files of only up to 10Mb. Trying to extract bigger files from the archive will lead to such an error. Do note that you might be able to upload large files, such as your site's backup archive, through FTP. However, if you try to extract a large file from the archive (e.g. a large non-split database dump, a large video or music file, etc) it will fail. Your ONLY way to perform the restoration is to extract the archive on your local PC, e.g. using Akeeba eXtract, and uploading all the extracted files by FTP. All you'll have to do next is visiting the restoration URL which is in the form of http://www.yoursite.com/installation/index.php. Please refer to Akeeba Backup's documentation (the chapter on restoring your site) for more information.

Finally, it may be a classic case of wrong or mixed file and directory permissions (a "permissions hell" situation). This is very easy to happen if you are restoring to a host with an existing installation of Joomla! or WordPress which doesn't use per-account web server process ownership through FastCGI or suPHP, i.e. the majority of cheap shared hosting. You might want to try using the FTP or Hybrid file writing mode. If this still doesn't work for you, try removing all existing files and directories from your server before restoring the backup archive. It's very easy to mix up ownerships and permissions on a shared host, effectively entering into a "permissions hell" which is virtually impossible to work around unless you have root privileges on an SSH console or, more easily, removing all files from the account. Do note that removing files might require using both an FTP program and your host's control panel, or raising a ticket with your host.

I am getting AJAX errors with some weird 403, 500, 502 or 503 code

This is actually a server issue. Kickstart works by having your browser visit the same URL repeatedly through AJAX to perform each extraction step. This is necessary since the extraction would otherwise take too long to complete which would cause your server to abort it, or simply run out of memory, reporting an error. By separating the work in smaller chunks we can perform the time, disk and memory intensive process of extracting a backup archive over a web interface. However, this may cause different issues on some servers.

First of all, some servers impose limits on the amount of resources (CPU, disk, memory) your hosting account can use in a specific period of time. These limits are there to protect the server against abuse by malicious tenants or scripts with coding mistakes which result in very high resource usage. By its very nature, Kickstart needs to do “heavy work”. It has to read a rather big backup archive, decompress the data in memory and write it into the thousands of files which make up your site. This requires a lot of disk and CPU activity to take place and do take up a substantial amount of memory. This may indeed trip the server protection. Tech talk (for IT pros): this is usually implemented either with Linux ulimit settings or through configuration of the virtualization environment (e.g. CloudLinux) under which your hosting account runs.

Second, some servers may have a built in Denial of Service protection. They keep track of which IP address is visiting which URL. If the same IP address tries to repeatedly access the same URL they treat is as a potential Denial of Service and may either simply reject the request or ban the IP address for a while. If this happens you will probably be unable to connect to your site for anywhere between a few seconds to a few hours. Unfortunately there is no way to know that in advance because, for security reasons, do not publicize this information. Tech talk (for IT pros): this is usually implemented on Apache using mod_evasive.

Finally, some servers may be filtering requests based on what kind of information is being sent. If they think that the data being sent to the server looks dissimilar to typical web traffic they might either just reject the request or ban the IP address for a while. PHP, the language Kickstart and your site's software is written in, is stateless. This means that it doesn't remember what happened between two successive requests. Extracting a backup archive requires a way to remember state, for example to track of how much of the archive we have already extracted, where to extract it and other options you made in Kickstart. To this end, Kickstart sends its state in an encoded form to your browser after an extraction step is complete. Your browser will then send it back to Kickstart when it asks it to run the next extraction step. The state is a rather long bit of encoded data which does indeed look dissimilar to regular web traffic. This may trip up the server protection discussed above. Tech talk (for IT pros): this is usually implemented on Apache using mod_security2.

The first two issues can be worked around using the first two options (time settings) in the Fine Tuning section of Kickstart's interface. You can set the minimum execution time to 5 and the maximum to 1. This is not a typo! It creates a 20% duty cycle: Kickstart extracts files for 1 second and then waits, doing nothing, for another 4 seconds so that the time between requests is the configured maximum, 5 seconds. Some servers might not like the predictability of the requests' timing. If this is the case try setting a minimum of 5 and a maximum of 10. This means that Kickstart will work for 5 to 10 seconds before telling your browser to run the next extraction step. This uses more resources, makes the extraction faster and introduces some variance in the time it takes each extraction step to run. If none of these settings work for you the server may be configured with very tight settings. In this case you can extract the backup archive on your computer, using either Akeeba Kickstart or Akeeba eXtract Wizard, and upload all extracted files to your site. Then you can complete the restoration by visiting the /installation/index.php on your site.

The last issue cannot be worked around by you. You can try asking your host for a temporary way to disable that server protection. It's possible that your host may be unable to help you if you are not on a VPS or dedicated server. In this case you can extract the backup archive on your computer, exactly as described in the previous paragraph.

I am getting an error restoring my database / after my site was restored

This is NOT a Kickstart issue. Kickstart only extracts the archive. It does not handle the restoration of your database or your site configuration. Please read the chapter about what Kickstart does and does not do you saw earlier in this documentation if you're in doubt.

Cookies Notification - Action required

This website uses cookies to provide user authentication and improve your user experience. Please indicate whether you consent to our site placing these cookies on your device. You can change your preference later, from the controls which will be made available to you at the bottom of every page of our site.