Forgot your username?             Forgot your password?

Native CRON script

[Tip]Tip

This option is only available in the Akeeba Backup Professional releases. You need to subscribe to the Professional edition to use it.

[Tip]Tip

Our users report that they get no joy using this script on GoDaddy hosting, but our alternative script (detailed on the next chapter) works.

[Note]Note

This file was found in administrator/components/com_akeeba/backup.php in Akeeba Backup 3.0.x up to and including 3.4.x. Since Akeeba Backup 3.5 this file is now present under cli/akeeba-backup.php.

If you have access to the command-line version of PHP, Akeeba Backup Professional includes an even better - and faster - way of scheduling your backups. All Akeeba Backup Professional releases include the file cli/akeeba-backup.php, which can be run from the command-line PHP interface (PHP CLI). In contrast with previous releases, it doesn't require the front-end backup in order to work; it is self-contained, native backup for your Joomla!™ site, even if your web server is down!

In order to schedule a backup, you will have to use the following command line to your host's CRON interface:

/usr/local/bin/php /home/USER/webroot/cli/akeeba-backup.php

where /usr/local/bin/php is the path to your PHP CLI executable and /home/USER/webroot is the absolute path to your web site's root. You can get this information from your host.

The backup script accepts three optional parameters:

  • --profile profile_id allows you to select which backup profile you would like to use for the scheduled backup. The profile_id is the numeric profile ID you can see in your Control Panel page.

  • --description "Your description" allows you set a backup description different than the default. Do not forget to enclose your description in double quotes, or this parameter will not work! Since Akeeba Backup 3.1 the description supports Akeeba Backup's file naming "variables", e.g. [SITE], [DATE] and [TIME]. These variables are documented in the Output Directory configuration option's description. This allows you to use them in conjunction with this parameter to provide flexible backup descriptions.

  • --override "keyname=value" allows you to override profile configuration variables. This parameter can appear an unlimited number of times in the command line. It can be used, for example, to provide the username and password to your cloud storage service in the command line, without having to store it in the backup profile's configuration, therefore never storing it in database and hiding it from other administrators. Please take a look at the "Overriding configuration variables" subsection for more information.

  • --quiet will suppress all output except warnings and error messages. If the backup runs successfully you get no output at all. Note: this option was added in Akeeba Backup Professional 3.3.4.

The akeeba-backup.php script will return a different exit code, depending on the backup status. When the backup is successful and without warnings, the exit code will be 0. When the backup completed but with warnings, the exit code will be 1. Finally, if the backup fails, the exit code will be 2. This allows you to check the backup status, for example inside a shell script, for automation purposes.

In order to give some examples, I will assume that your PHP CLI binary is located in /usr/local/bin/php - a common setting among hosts - and that your web site's root is located at /home/johndoe/httpdocs.

  1. Backup with the default profile (ID = 1) and default description:

    usr/local/bin/php /home/johndoe/httpdocs/cli/akeeba-backup.php
  2. Backup with profile number 2 and default description:

    usr/local/bin/php /home/johndoe/httpdocs/cli/akeeba-backup.php --profile=2
  3. Backup with the default profile (ID = 1) and a description reading "My automated backup":

    usr/local/bin/php /home/johndoe/httpdocs/cli/akeeba-backup.php --description="My automated backup"
  4. Backup with profile number 2 and a description reading "My automated backup":

    usr/local/bin/php /home/johndoe/httpdocs/cli/akeeba-backup.php --profile=2
      --description="My automated backup"

It goes without saying that the line breaks are for readability only. You should not include line breaks in your command line.

Special considerations:

  • All parameters must start with a double dash. If you use a single dash, they will be ignored. This is a limitation of Joomla!'s JApplicationCli iterface –used by our script– which follows the UNIX conventions of command line parameters.

  • Most hosts do not impose a time limit on scripts running from the command-line. If your host does and the limit is less than the required time to backup your site, the backup will fail. We are working on a workaround to allow operation even within such time constraints.

  • This script is not meant to run from a web interface. If your host only provides access to the CGI or FastCGI PHP binaries, backup.php will not work with them. The solution to this issue is tied to the time constraint above. The workaround we're planning will solve both issues.

  • Some servers do not fully support this backup method. The usual symptoms will be a backup which starts but is intermittently or consistently aborted in mid-process without any further error messages and no indication of something going wrong. In such a case, trying running the backup from the back-end of your site will work properly. If you witness similar symptoms please use the Alternative CRON Script, outlined in the next section.

Setting up a CRON job on cPanel

Go to your cPanel main page and choose the CRON Jobs icon from the Advanced pane. In the Add New CRON Job box on the page which loads, enter the following information:

Common Settings

Choose the frequency of your backup, for example once per day.

Command

Enter your backup command. Usually, you have to use something like:

/usr/bin/php5-cli /home/myusername/public_html/cli/akeeba-backup.php --profile=YourProfileID

where myusername is your account's user name (most probably the same you use to login to cPanel) and YourProfileID is the numeric profile number you want to use for your backup job. Do note the path for the PHP command line executable: /usr/bin/php5-cli. This is the default location of the correct executable file for cPanel 11 and later. Your host may use a different path to the executable. If the command never runs, ask them. We can't help you with that; only those who have set up the server know the changes they have made to the default setup.

Finally, click the Add New Cron Job button to activate the CRON job.

Special considerations for HostGator

The location of the PHP CLI binary is /usr/bin/php-cli. This means that your CRON command line should look like:

/opt/php53/bin/php /home/myusername/public_html/cli/akeeba-backup.php --profile=YourProfileID

Overriding configuration variables

Since Akeeba Backup 3.1 the Native CRON Script allows you to override or supply missing configuration variables in the command line. This is especially useful for security reasons. One security issue with the cloud storage service integration is that other administrators can peek at Akeeba Backup's configuration and read the username, password or API keys used to access the cloud storage service. You can, however, leave these fields blank in the configuration and supply their values in the command line.

Overriding a configuration variable requires knowing its key name. The key names are represented in dot-format, i.e. engine.postproc.s3.accesskey for Amazon S3's access key. Determining the key name is quite easy, as they are stored in INI files throughout the component's back-end. The first location you should look at is administrator/components/com_akeeba/akeeba/core, where you will find four INI files with general settings. Inside the administrator/components/com_akeeba/akeeba/engines and administrator/components/com_akeeba/akeeba/plugins/engines directories and their subdirectories you will find one INI file per engine.

In order to save you from trouble, here are the most useful key names for providing cloud storage engine credentials. The names are designed to be self-explanatory.

Amazon S3
  • engine.postproc.s3.accesskey

  • engine.postproc.s3.secretkey

RackSpace CloudFiles
  • engine.postproc.cloudfiles.username

  • engine.postproc.cloudfiles.apikey

Dropbox
  • engine.postproc.dropbox.token

  • engine.postproc.dropbox.token_secret

Microsoft Windows Azure BLOB Storage
  • engine.postproc.azure.account

  • engine.postproc.azure.key

Remote FTP server
  • engine.postproc.ftp.host

  • engine.postproc.ftp.port

  • engine.postproc.ftp.user

  • engine.postproc.ftp.pass

Applying them on the command line is easy. Take this command line as an example:

usr/local/bin/php /home/johndoe/httpdocs/cli/akeeba-backup.php
--profile=2 --description="My automated backup"
--override="engine.postproc.s3.accesskey=ABCDEF"
--override="engine.postproc.s3.secretkey=1234567890abcdefgh"

In this case, we are telling the backup script to use the backup Profile with ID=2, give the backup description of "My automated backup" and then supply the S3 access and secret keys.

[Important]Important

The values of the override parameters must be enclosed in double or single quotes (depends on your Operating System), otherwise the operating system will not pass them back to the backup.php script.

[Important]Important

Your script MUST NOT include the line breaks in the previous example. The line breaks are there only for typesetting purposes.

Finally, it should be noted that you can use the command-line override feature to do more tricky configuration overrides, for example turning off the archive splitting or using a different backup output directory to enhance your security. If it's something you can do in the Configuration page of the component, you can also do it using command line overrides.