Support

Documentation

The setup page
Prev Kickstart's interface Next

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 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.

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 writable. 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 unwritable. 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 unwritable 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.

Prev Up Next
Kickstart's interface Home Chapter 4. Advanced features