![[Note]](/media/com_docimport/admonition/note.png) | Note |
|---|---|
|
This feature is only available in Akeeba Backup Professional. As discussed below, you DO NOT need the Site Transfer Wizard to transfer your site between folders, subdomains, domains and servers using Akeeba Backup. Just take a backup, upload it together with Kickstart on the new location and run Kickstart. This is the method demonstrated in our video tutorial which is freely available on our site. |
What is the Site Transfer Wizard?
One of the most common uses of Akeeba Backup is transferring a site between different locations (folders, subdomains, domains and servers). Typically this involves taking a backup, downloading it to your computer, uploading it to the new location alongside Kickstart and launching Kickstart to extract the backup archive and proceed with the restoration. The download and upload part of this process takes a lot of time, especially when you have a slower connection. The Site Transfer Wizard will save you some precious time by eliminating the need to transfer the backup archive through your computer, instead performing a server to server transfer.
We recommend that you try using the Site Transfer Wizard without reading this documentation section. You only need to refer to this documentation in case a server issue or a mistake in the information you entered prevents you from using it. That's why this documentation section is brutally long; it's troubleshooting, not regular usage documentation. The Site Transfer Wizard is intuitive enough to use without reading its documentation.
![[Important]](/media/com_docimport/admonition/important.png) | Important |
|---|---|
|
The Site Transfer Wizard IS NOT the only way to transfer your site with Akeeba Backup and IS NOT guaranteed to work on all servers. If your site is very big, your server too slow or simply doesn't support the requirements of the Site Transfer Wizard then the wizard will fail to transfer the backup archive for you. We cannot do anything against your host's technical limitations. However, you can still transfer your site with the Manual method available in the Site Transfer Wizard. In a nutshell: you can take a backup; download the backup archive files to your site; upload the backup archive files and Kickstart where you want to restore the site to; run Kickstart. The Wizard will display a video tutorial about this when you select the Manual method. |
Prerequisites
Before you begin you must have create a new database for the destination site. This is something that Akeeba Backup and its restoration script is not allowed to do due to the configuration of most servers. This has to do with your server's database security settings and cannot be "worked around" in any way. If you are not sure how to do it please contact your host - this is a server-specific task and they are the only people who can help you with it.
You also need to know how to connect to the target location. This requires knowing the FTP, FTPS or SFTP connection information to the target location. This is required even if you are transferring to a subdirectory, subdomain or domain on the same server your site is currently on. If you are not sure how to obtain this information please contact your host; they are the only people who can help you accurately figure out this information.
If you will be using FTP or FTPS to transfer your site your current server must either have the PHP cURL extension installed with FTP support or the PHP FTP functions enabled.It must not block outbound connection to the remote server's FTP port (typically port 21). The remote FTP server must allow connections from your site's current server and allow at least 7 connection attempts to be made within 1 second.
If you will be using SFTP to transfer your site your current server must either have the PHP cURL extension installed with SFTP support of the PHP SSH2 extension installed. It must not block outbound connection to the remote server's FTP port (typically port 22). The remote FTP server must allow connections from your site's current server and allow at least 7 connection attempts to be made within 1 second.
In every case the remote location MUST be accessible through HTTP/HTTPS over the Internet from your site's server and your computer. Akeeba Backup will be checking that and won't let you proceed with the transfer if it can't connect.
Backup age check
The Site Transfer Wizard requires a recent backup, taken within the last 24 hours using the currently active backup profile. If one is not detected you will be notified. If you want to use a backup taken with a different profile please remember to activate that profile from Akeeba Backup's main page before clicking on Site Transfer Wizard.
Backup age check
Click the button to take a new backup with the current backup profile.After the backup is complete you will need to go back to the main page and then click on Site Transfer Wizard again.
Setting up the transfer target URL
When a recent backup is detected the Site Transfer Wizard will let you know how much free space you will need (approximately!) on the target server. Please make sure that you have enough disk space before proceeding.
Setting up the transfer target URL
Afterwards please enter the URL of the target site and click the
button. You must enter the full URL to
the target site including the http:// or
https:// prefix and any path to the site but without the
index.php part. For example you need to enter something like
https://www.example.com,
http://subdomain.example.net or
http://localhost/mysite.
The Site Transfer Wizard will check that the URL is accessible from your server.Please note that if the URL returns an error, including but not limited to 403 Forbidden and 500 Internal Server Error, you will receive a message telling you that the URL is inaccessible. In some very rare circumstances you may be receiving this message in error. In those cases you can click on the button and proceed anyway. Please note that you are doing so at your own risk. We will not be able to help you if something doesn't work or breaks!
![[Tip]](/media/com_docimport/admonition/tip.png) | Tip |
|---|---|
|
If at any point you realise you have entered the wrong URL you can click on the button in the toolbar to clear all Site Transfer Wizard settings and start over. |
Setting up the connection
The next step lets you tell the Site Transfer Wizard how to connect to your target site to transfer files.
Setting up the connection
Select one of the available transfer methods (not all of them may be available on your server):
- FTP, using cURL
-
You will connect to your site using plain (insecure) FTP. This is the simplest file transfer protocol, supported by most hosts - however it's also the least secure. This method uses the PHP cURL extension which is compatible with most hosts.
- FTPS, using cURL
-
You will connect to your site using plain FTP over a secure SSL/TLS connection. This is a simple file transfer protocol, supported by many hosts and it is quite secure. This method uses the PHP cURL extension which is compatible with most hosts.
- SFTP, using cURL
-
You will connect to your site using file transfer over SSH (a.k.a. Secure File Transfer Protocol, or SFTP for short). This is an advanced file transfer protocol, supported by some hosts and it is the most secure. This method uses the PHP cURL extension which is compatible with most hosts.
- FTP, native PHP functions
-
You will connect to your site using plain (insecure) FTP. This is the simplest file transfer protocol, supported by most hosts - however it's also the least secure. This method uses the PHP native FTP functions. You may experience some compatibility issues with badly configured FTP servers.
- FTPS, native PHP functions
-
You will connect to your site using plain FTP over a secure SSL/TLS connection. This is a simple file transfer protocol, supported by many hosts and it is quite secure. This method uses the PHP native FTP functions. You may experience some compatibility issues with badly configured FTP servers.
- SFTP, native PHP SSH2 extension
-
You will connect to your site using file transfer over SSH (a.k.a. Secure File Transfer Protocol, or SFTP for short). This is an advanced file transfer protocol, supported by some hosts and it is the most secure. This method uses the PHP SSH2 extension. Since this extension is currently marked as experimental it may not be available on your server or not work properly.
- Manually
-
If all else fails (your servers just can't talk to each other) choose this option, do not file a "bug" report (as noted above, we can't override your hosts' technical limitations since we are not your host, therefore cannot reconfigure your servers with more sane limits). The manual method will give you instructions for performing a manual backup archive transfer, including a tutorial for restoring it after it's transferred. This is your failsafe method, one which has been used by hundreds of thousands of site integrators and site owners since 2006 to transfer their sites between different locations.
If your target site supports more than one transfer methods please try using the most secure ones first. The order of preference, from MOST to least secure is: SFTP, FTPS, FTP. Moreover, if you are given the choice between a method that uses cURL and one which doesn't please try using the cURL one first. If none of them works for you please check your connection information and retry. If nothing works despite the connection information being correct you have a case where the two servers cannot talk to each other due to networking, firewall or setup issues. The easiest thing you can do is use the Manually option to transfer your site by manually uploading your backup archive.
The available settings for SFTP transfer methods are as follows.
- Host name
-
The hostname or IP address of the remote SFTP server. This is something like
sftp.example.com(fully qualified domain name),198.51.100.42(IPv4), or2001:db8:e6a4:ffff:ffff:ffff:ffff:ffff(IPv6, if supported by both servers and both your browser and your local network). - Port
-
The TCP/IP port the SSH server listens on for SFTP connections. Typically this is
22. If unsure, ask your host. - Username
-
The username you use to connect to your SFTP server. Required.
- Password
-
If you are connecting to your SFTP server with a username and password pair (most common use case) enter your password here and leave the SFTP Public Key file and SFTP Private Key file fields blank.
If you are connection to your SFTP server using certificates (Private and Public Key file pair) enter your private key file's password here and fill in the SFTP Public Key file and SFTP Private Key file fields. If your private key file does not have a password, leave this field blank but do fill in the SFTP Public Key file and SFTP Private Key file fields.
- SFTP Public Key file
-
Optional; only used if you connect to your SFTP server using certificates (Private and Public Key file pair).
Enter the full path of your SSH Public Key file, e.g.
/home/myuser/.ssh/id_rsa.pub.Important To use this feature you will need to upload your SSH public and private keys to your server, in a directory which can be read by your site. A good place for that would be inside your site's
administrator/logsfolder.Remember to delete these files after you are done using the Site Transfer Wizard.
- SFTP Private Key file
-
Optional; only used if you connect to your SFTP server using certificates (Private and Public Key file pair).
Enter the full path of your SSH Private Key file, e.g.
/home/myuser/.ssh/id_rsa.If your private key file is password protected please remember to enter its password in the Password field above.
- FTP/SFTP Directory
-
The absolute SFTP path to your remote site's (target site — where you are transferring the site to) web root.
Typically, it's something like
/home/myuser/public_html,/home/myuser/htdocs,/var/www/mysite,/var/www/htmlor/home/myuser/example.com. If unsure, ask the host of the new site. - Archive transfer mode
-
The Site Transfer Wizard (STW) has two possible modes for transferring your backup archive file(s) to the remote server. In both cases, the first step is to upload a special version of Akeeba Kickstart which can respond to remote commands sent by the STW to it. What happens next depends on how you set up this option:
-
Over FTP / SFTP. The STW will upload a small chunk of each backup archive file over SFTP. It will then send a command to Akeeba Kickstart on the remote site, instructing it to append the just uploaded chunk to the bigger archive file. This process continues until all backup archive files are fully uploaded to the remote server.This method is typically more robust but slower. It can fail if the remote server decides to reject SFTP connections coming from your server because there are many of them in a short period of time.
-
Over HTTP / HTTPS. The STW sends an HTTP(S) POST request to Akeeba Kickstart on the remote site with a small chunk of each backup archive as the POST payload. Akeeba Kickstart writes that to a temporary file and appends the just uploaded chunk to the bigger archive file, deleting the temporary file. This process continues until all backup archive files are fully uploaded to the remote server.This is less robust but faster. It can fail if the remote server has a very small allowed POST size, or if the server rejects the HTTP requests to Kickstart due to an overzealous server protection. You can try to work around these problems by adjusting the Chunk Size.
-
- Chunk size
-
The Chunk Size controls how much of each backup archive file will be transmitted to the remote server in each request.
The higher this value is the longer each upload request takes which increases the chance that the site transfer will experience a time out coming either from the server you are transferring from, or the server you are transferring to. Moreover, if you are using the HTTP / HTTPS archive transfer mode (as set up in the option above) a larger chunk size may be beyond the configured maximum POST size for PHP on the target server, causing the upload to fail — in those servers you may have to select 512Kb or 1Mb to make the STW work at all.
Lower values tend to work best but make the transfer slower as it needs many more steps to complete the transfer of the backup archive. At the same time, the increased number and cadence of requests may trigger a server protection on the target server, causing it to block your origin server's IP address temporarily, therefore causing the site transfer to fail.
The available settings for FTPS and FTP transfer methods are as follows.
- Host name
-
The hostname or IP address of the remote FTP server. This is something like
sftp.example.com(fully qualified domain name),198.51.100.42(IPv4), or2001:db8:e6a4:ffff:ffff:ffff:ffff:ffff(IPv6, if supported by both servers and both your browser and your local network). - Port
-
The TCP/IP port the FTP server listens on for connections. Typically this is
21. If unsure, ask your host. - Username
-
The username you use to connect to your FTP server. Required.
- Password
-
The password you use to connect to your FTP server. Required.
- FTP/SFTP Directory
-
The FTP directory of your target (transfer to) site's root. If unsure, ask your host.
- Archive transfer mode
-
The Site Transfer Wizard (STW) has two possible modes for transferring your backup archive file(s) to the remote server. In both cases, the first step is to upload a special version of Akeeba Kickstart which can respond to remote commands sent by the STW to it. What happens next depends on how you set up this option:
-
Over FTP / SFTP. The STW will upload a small chunk of each backup archive file over FTP. It will then send a command to Akeeba Kickstart on the remote site, instructing it to append the just uploaded chunk to the bigger archive file. This process continues until all backup archive files are fully uploaded to the remote server.This method is typically more robust but slower. It can fail if the remote server decides to reject FTP connections coming from your server because there are many of them in a short period of time.
-
Over HTTP / HTTPS. The STW sends an HTTP(S) POST request to Akeeba Kickstart on the remote site with a small chunk of each backup archive as the POST payload. Akeeba Kickstart writes that to a temporary file and appends the just uploaded chunk to the bigger archive file, deleting the temporary file. This process continues until all backup archive files are fully uploaded to the remote server.This is less robust but faster. It can fail if the remote server has a very small allowed POST size, or if the server rejects the HTTP requests to Kickstart due to an overzealous server protection. You can try to work around these problems by adjusting the Chunk Size.
-
- Chunk size
-
The Chunk Size controls how much of each backup archive file will be transmitted to the remote server in each request.
The higher this value is the longer each upload request takes which increases the chance that the site transfer will experience a time out coming either from the server you are transferring from, or the server you are transferring to. Moreover, if you are using the HTTP / HTTPS archive transfer mode (as set up in the option above) a larger chunk size may be beyond the configured maximum POST size for PHP on the target server, causing the upload to fail — in those servers you may have to select 512Kb or 1Mb to make the STW work at all.
Lower values tend to work best but make the transfer slower as it needs many more steps to complete the transfer of the backup archive. At the same time, the increased number and cadence of requests may trigger a server protection on the target server, causing it to block your origin server's IP address temporarily, therefore causing the site transfer to fail.
- Passive mode
-
Enabled the Passive Mode for communicating to the remote FTP server. Recommended for most commercial hosts.
- Passive mode workaround
-
Only available with the FTP/FTP file transfer methods marked as “using cURL”.
Some badly configured or misbehaving FTP servers return the wrong IP address when FTP Passive mode is enabled. Enable this option to force the FTP library to ignore the wrong IP returned by the FTP server, instead using the FTP server's public IP.
Enter the connection information below and click on to get to the next step. Please note that if you chose Manually above the next step simply gives you instructions for performing the transfer and the rest of this documentation section does not apply.
Files transfer and restoration
At this point the Site Transfer Wizard is going to make some sanity checks and upload some files on your server.
If the connection fails for any reason you will be told so. Please double check the connection information and the FTP/SFTP directory. The latter must exist and be both readable and writeable. If you still get an error despite all the connection information being correct please try a different connection method. If all available methods fail please do contact both hosts (the one your site is currently on and the one you're trying to transfer to). One or both of the servers have a server protection which prevents the two servers from talking to each other. If you cannot get your hosts to resolve that issue your only choice will be using the Manually option above. Unfortunately there is nothing we can do about it since it's the server which doesn't allow the server-to-server transfer in any way.
If the target server and location is the same as the one where your current site exists the process will be aborted. You MUST NOT use the Site Transfer Wizard to restore a backup archive on your own site. Either use the Restore feature in the Manage Backups Page (Professional version only) or use Akeeba Kickstart to extract the backup archive and start the restoration.
If a .htaccess file is detected on the target location the process will be aborted. The .htaccess files can interfere in the way PHP script execute, corrupting the upload of the backup archive or simply blocking the upload, extraction or restoration process. As a precaution the Site Transfer Wizard will not proceed in this case unless you delete the .htaccess file.
After these basic checks the Site Transfer Wizard will try to
upload the two Kickstart files (kickstart.php and
kickstart.transfer.php) to your target location
and create a new world-writable (0777 permissions) directory called
kicktemp. Yes, we are aware that the world
writable permissions are REALLY BAD for security - but only if you let
them persist. We only create this directory temporarily and only use
it for temporary data. After the process is done this directory is
removed, therefore eliminating any possible security concern. If any
of these operations fails you will receive an error message. If this
happens please make sure that the target directory is writeable. If
you are not sure please ask your host for assistance.
If the FTP/SFTP Directory you've entered does not correspond to the URL to the new site you have entered you will be told so. You CANNOT receive this message in error. If you get this message you MUST check that the directory corresponds to the URL you've entered. If you are not sure, or if you think that Akeeba Backup is wrong (it's not), do check with your host. This is the most common mistake people make. Trust us. This is exactly why we added this check.
Afterwards the Site Transfer Wizard will attempt to upload the backup archive file(s). This is done in small, 1Mb chunks. The file is NOT uploaded using FTP, FTPS or SFTP. Why? Because, as we explained previously in this documentation, transferring a big file can take too long which will cause PHP or your web server to halt with a timeout error. The Site Transfer Wizard is instead sending 1Mb of data at a time to Kickstart (which it uploaded in the previous step). Kickstart on the target location "assembles" the archive file(s) from these 1Mb chunks behind the scenes. This lets us transfer really big backup archives without timing out. The progress of the upload is displayed on the page.
However, this may lead to problems on some servers. Since the Site Transfer Wizard is making a lot of repeated requests to the kickstart.php URL on the target location some servers may mistakenly assume that this is an attack on the server. Other servers may not like that a lot of the CPU is being used by that site hosting account all of a sudden. If this kind of server protection is triggered you will receive an error message. Depending on the server and host they might also temporarily block the IP address of your site's current server, making it impossible to run the Site Transfer Wizard again for a period of a few minutes to a full day. If you get in this kind of situation you will have to use the Manually option and transfer the backup archives yourselves. Unfortunately there is nothing we can do about it since it's the server which doesn't allow the server-to-server transfer of large files.
When the backup archive files are fully transferred you will see a button called . Click on it to launch Kickstart on the target URL. Kickstart allows you to extract the backup archive on the target server. This is required since the actual restoration script is stored inside the backup archive. If you are unsure how to proceed after this point please consult our video tutorials on transferring your site to a new server. Ignore the part where you upload Kickstart and the backup archive; this is already done for you by the Site Transfer Wizard.