Support

Documentation

Walkthrough

Below we will see how to get Remote CLI interface your site, make sure Akeeba Backup is up to date, run a backup and automatically download the backup archive to your PC.

In this fictional example, the following assumptions are made: Your site can be found at http://www.example.com and the secret word is 0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA. The backup archives are stored in the default output directory (administrator/components/com_akeeba/backup). The site's FTP host is ftp.example.com and its username and password are example and test respectively. The site is under the public_html directory. We also assume that the PHP CLI executable is already in your path.

Connection test

We begin by making sure that Remote CLI can access our site:

php remote.phar --action=test --host=http://www.example.com --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA

You should see something like this:

Akeeba Remote Control CLI svn724 (2011-06-14)
Copyright ©2008-2014 Nicholas K. Dionysopoulos / AkeebaBackup.com
--------------------------------------------------------------------------------
 This program comes with ABSOLUTELY NO WARRANTY. This is Free Software and you
 are welcome to redistribute it under certain conditions. Use command line
 option --license for details.
--------------------------------------------------------------------------------
Successful connection to site

The last line tells you that the connection worked. However, if something goes wrong, you might get one of these error messages:

Error 401 - Invalid login credentials : Your secret word is wrong. Go to your site's back-end, Components, Akeeba Backup, click on Component Parameters and enter a secret key of your liking. We strongly recommend using only a-z, A-Z and 0-9 to work around limitations with some hosts.

Error 503 - Access denied: You forgot to enable the remote API or enter a secret word in Akeeba Backup. Go to your site's back-end, Components, Akeeba Backup, click on Component Parameters and set Enable remote and front-end backups to Yes. Then enter a secret key of your liking. We strongly recommend using only a-z, A-Z and 0-9 to work around limitations with some hosts.

Your server does not seem to be compatible with Remote Control : Check that you are using the correct host name, including the http/https prefix. Also make sure that Akeeba Backup 3.3.0 or later is installed and activated. Also note that some SEF and security extensions may be blocking the Remote API calls to your site. In this case, you won't be able to use Remote CLI.

[Important]Important

If your host name, secret key or any other option contains non-alphanumeric characters (anything except 0-9, a-z, A-Z, slash, backslash, dash, dot and underscore) you MUST enclose the option value in double quotes. For example, --secret=ab=gt%6 will not work, but --secret="ab=gt%6" will do. If you get connection errors despite having set the correct host name and secret key, try using double quotes around all of your option values.

Taking a backup

The following command will take a backup (without downloading it to your local PC), using backup profile #1:

php remote.phar --action=backup --host=http://www.example.com 
    --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA --profile=1
[Warning]Warning

The command line above should be entered ON A SINGLE LINE. We have added the line break for typesetting purposes only. When you copy & paste it and it doesn't work, come back here, read this paragraph, go back to your command line and REMOVE the line break after --profile=1 and before --dlurl.

You should see a long list of output coming through, detailing the backup progress. In the end it should read:

Backup finished successfully

And that's it! You now have a backup. Since it's useless without downloading, let's try...

Taking and downloading a backup

There are many ways to download a backup archive. We'll explore only two, using HTTP (not recommended on most sites) and FTP.

First, let's try HTTP. The command line to achieve that is the same as the backup command line, with the --download, --dlmethod and --dlpath added:

php remote.phar --action=backup --host=http://www.example.com 
    --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA --profile=1
    --download --dlmode=http --dlpath="c:\Downloads"
[Warning]Warning

The command line above should be entered ON A SINGLE LINE. We have added the line break for typesetting purposes only. When you copy & paste it and it doesn't work, come back here, read this paragraph, go back to your command line and REMOVE the line break after --profile=1.

This will take a backup and then download it to C:\Downloads (or anything else you specify with --dlpath) using the HTTP download method. After the "Backup finished successfully" messages you will also see many download lines and a "Archive downloaded successfully". If that fails, you'll have to use the FTP mode.

First, you need to know the following information about your site:

  • FTP hostname. We'll assume it's ftp.example.com for this example

  • FTP username and password. We'll assume it's foo and bar, respectively

  • The FTP path to your backup output directory. We'll assume it's /public_html/administrator/components/com_akeeba/backup.

    [Tip]Tip

    In order to find this directory, connect to your site using FileZilla. Navigate inside the folder Joomla! is installed in. Usually it's a directory named public_html, htdocs, www or something similar. If unsure don't ask us, ask your host. Then navigate to your backup output directory. The default is administrators/components/com_akeeba/backup. If unsure, check your Akeeba Backup Configuration page. Now, on the right-hand pane you will find the FTP path, right above the folders list. Copy this; it's the path we need.

Then, modify the command line to read:

php remote.phar --action=backup --host=http://www.example.com
--secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA --profile=1
--download --dlmode=curl --dlpath="c:\Downloads"
--dlurl="ftp://foo:bar@ftp.example.com/public_html/administrator/components/com_akeeba/backup"
[Warning]Warning

The command line above should be entered ON A SINGLE LINE. We have added the line break for typesetting purposes only. When you copy & paste it and it doesn't work, come back here, read this paragraph, go back to your command line and REMOVE the line break after --profile=1 and before --dlurl.

One final note. After you download the backup archive, it's a good idea to delete the copy on the server for security reasons. Just append --delete to the command line to achieve that. For example, the command line above will become:

php remote.phar --action=backup --host=http://www.example.com 
  --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA --profile=1
  --download --dlmode=curl --dlpath="c:\Downloads" --delete
  --dlurl="ftp://foo:bar@ftp.example.com/public_html/administrator/components/com_akeeba/backup"
[Warning]Warning

The command line above should be entered ON A SINGLE LINE. We have added the line break for typesetting purposes only. When you copy & paste it and it doesn't work, come back here, read this paragraph, go back to your command line and REMOVE the line break after --profile=1 and before --dlurl.

That's it!

Updating Akeeba Backup automatically

If your server supports our Live Update method, you can automatically update Akeeba Backup to its latest version, when one is made available. The command line to do that is:

php remote.phar --action=update --host=http://www.example.com
  --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA
[Warning]Warning

The command line above should be entered ON A SINGLE LINE. We have added the line break for typesetting purposes only. When you copy & paste it and it doesn't work, come back here, read this paragraph, go back to your command line and REMOVE the line break after --profile=1 and before --dlurl.

Automating the whole lot

If you want to automate updating Akeeba Backup, taking and downloading backups, you can simply create a batch/script file and use your Operating System's scheduling features to run it at predefined intervals. We suggest taking a look at the following tutorials:

As for the batch/script file, all you have to do is to include the commands above in a .BAT (Windows) or .sh (Linux, Mac OS X) file. For example, a Windows batch file (backup.php) looks like that:

REM IMPORTANT! Before running Remote CLI, you have to change the current
REM directory to wherever remote.phar is located in. In this example, we
REM will assume that you followed our advice and put it in c:\PHP
C:
CD c:\PHP

REM The following line updates Akeeba Backup - REMOVE THE LINE BREAKS
REM WHEN COPYING THIS SCRIPT TO YOUR SYSTEM, OTHERWISE IT WILL NOT WORK!!!

php-cli.exe remote.phar --action=update --host=http://www.example.com
 --secret=iloveakeeba

REM The following line takes and downloads a backup - REMOVE THE LINE
REM BREAKS WHEN COPYING THIS SCRIPT TO YOUR SYSTEM, OTHERWISE IT WILL
REN NOT WORK!!!

php-cli.exe remote.phar --action=backup --host=http://www.example.com
 --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA --profile=1 --download
 --dlmode=curl --dlpath="c:\Downloads"
 --dlurl="ftp://foo:bar@ftp.example.com/public_html/administrator/components/com_akeeba/backup"
 --delete

Note that we assume that the path to PHP is c:\PHP\php-cli.exe and you followed our advice and also copied Remote CLI (remote.phar) into C:\PHP. That's it! You can now use the Scheduled Tasks feature of Windows to make this file run whenever you want, essentially having an always up-to-date copy of Akeeba Backup installed on your site, take automated backups of your site, download them to your PC and remove them from the server. All you need to do once you set this up is to remember to leave your PC turned on for the scheduled task to run. Easy peasy!