Support

Documentation

4.Uploading Kickstart

4.Uploading Kickstart

Tip

TL;DR: Upload Kickstart over FTP in Binary Transfer Mode. Alternatively, upload it with SFTP or your hosting control panel's file manager.

Kickstart is a not a regular PHP file; it's a PHAR archive.

Regular PHP files are just text. Each line ends with either a Line Feed (LF) character, or a Carriage Return and a Line Feed (CRLF) character sequence, or a mix of them; PHP supports both. A single LF is called Unix-style line termination, a CRLF sequence is called Windows-style line termination.

[1].

For historical reasons, FTP clients have offered three file transfer modes: Binary, ASCII, and Auto. In Binary mode the file is transferred as-is, byte for byte. In ASCII mode the line termination characters can be replaced when transferring between systems which use different line endings. For example, if you are on a Windows computer (CRLF line endings) transferring a file to a Linux server (LF line endings) the FTP client will automatically convert CRLF to LF when uploading the file, and LF to CRLF when downloading a file. The idea here is that text files will have the "correct" line endings to be displayed correctly by each system. This is largely irrelevant today as even Windows' Notepad can understand different line endings these days. The Auto mode is usually the default, and it's a bit weird. If the file being transferred is a known "text file" type then the ASCII mode will be used, otherwise the Binary transfer mode is used.

Files with a .php extension are considered "text files" by FTP clients. Therefore, if you are using the ASCII or Auto (default) file transfer mode the FTP client will try to convert CRLF to LF and vice versa if you are on a Windows device transferring files to/from a non-Windows server, or if you are on a non-Windows device transferring files to/from a Windows server. This is bad for two reasons:

  1. File sizes and checksums get changed when you convert between LF and CRLF. This means that the transferred files may fail security checks, e.g. when checking if your Joomla or WordPress core files have been tampered with.

  2. If the files contain non-text data –like Kickstart's compressed PHAR data, or a backup archive's contents– this data will become corrupt.

This is exactly the reason why you need to transfer Kickstart after setting the Transfer Mode explicitly to Binary. Even though Kickstart has a .php extension, it is a PHAR archive which contains compressed, binary data. The Auto or ASCII mode will corrupt that data, making the file unusable.

Important

If you get an immediate 500 Internal Server Error trying to run Kickstart, that's the problem. Same goes if you get a PHP error message complaining about the checksum of the PHAR archive not matching.

There are other alternatives, too.

  1. Use SFTP (preferred). Despite the similar names, SFTP and FTP have nothing to do with each other. SFTP is essentially a file transfer protocol implemented over SSH. It only does binary file transfers. This is the recommended method as it is also the most secure file transfer method you can use.

  2. Use your hosting control panel's file manager. Since this is an HTML upload form, the file transfer takes places byte-for-byte, just like FTP's Binary Transfer Mode.



[1] There was a third style with a single Carriage Return (CR) character, without a Line Feed. That was called Mac-style line termination. You will never see that anymore. This was only used by macOS Classic. Since Mac OS X, and in macOS versions from 11 onwards, Apple is using Unix-style line termination.