Support

Documentation

This documentation page is for Joomla! 3.x

This documentation page does not apply to our software versions for Joomla! 4.0 and later versions. If you are not using Joomla 3 please consult the documentation index to find and read the correct version of the documentation.

Off-site Directories Inclusion

[Note]Note

This feature is available only in Akeeba Backup Professional

It's very likely that advanced site owners will place files outside the site's root to prevent web visitors from having direct access to those files. These directories typically contain files that need complex access control and are, therefore, only made available for download through PHP code, e.g. a download manager extension for Joomla!. Akeeba Backup Core will only backup files under the site's root, which would make these files impossible to backup.

The solution to that problem is the Off-site Directories Inclusion feature of Akeeba Backup Professional. Using this feature you can tell Akeeba Backup to look for files in arbitrary locations outside the site's root and include them in the backup archive. All the directories included with this filter will be placed in the archive as subdirectories of another folder, in order to avoid directory name clashes. We call this parent folder the "virtual folder".

For example, let's say you want to backup an off-site directory named images. If we weren't using the virtual folder its contents would end up being backed up inside the Joomla! images directory. This is not desirable. If your virtual folder is called my_offsite_includes , this directory would end up being backed up as something like my_offsite_includes\123ABC-images . Notice the stuff and the dash before the actual directory name? This is a smart feature which allows you to backup many directories that have the same name. You could, for instance, backup two directories named images , confident that there would be no name clash inside the archive.

Since keeping track of these folders is a pain, Akeeba Backup includes a readme.txt text file inside the virtual folder which tells you which backed up folder corresponds to which physical folder, making it easy for you to restore these directories to their rightful place.

Moreover, ANGIE -the restoration script included in the Akeeba Backup archives- can semi-automatically restore the off-site directories to their original location. You will need to confirm the destination directory or, if you don't want to do this, just tell it to skip over that directory.

Finally note that you MUST NOT add your site's root as an off-site directory inclusion. Akeeba Backup already adds the contents of your site's root to the backup. If you manually add your site's main directory as an off-site directory inclusion you will be backing up the same files twice, doubling your backup size. For the same reason you must not add an folder already under the site's root as an off-site directory inclusion: you'd be backing up files already backed up, bloating the backup size.

Off-site Directories Inclusion

At first you are presented with a grid view, listing all the off-site inclusions you may have already added. Next to each row and on the left hand side of it you will find two icons:

  • The trashcan. Clicking on this icon will remove the current directory definition from the backup set.

  • Pencil or Add. Both will toggle the row to edit mode: the former to edit the directory definition, the latter to create a new one.

Off-site Directories Inclusion - Edit mode

When a row enters the edit mode, the pencil icon changes to two different icons:

  • The disk. Clicking on this icon will save any changes you have made.

  • Cancel. Clicking it will abort any changes you have made.

You will also observe that the path to the external directory has also turned to an edit box with a folder icon on its left. You can type in the absolute path to the external directory using the edit box, or click on the folder icon to launch a visual folder browser, much like the one you use to select an output directory in the component's Configuration page. If you choose to use the edit box, you can use the following variables:

  • [SITEROOT] is the absolute path to your site's root. You should never use this for the reasons explained earlier in this section.

  • [ROOTPARENT] is the absolute path to your site root's parent directory, i.e. one level above your site's root.

To the right of the directory you will see another field called Virtual Directory. This is the name of the subdirectory where Akeeba Backup stores the files and folders of these off-site directory's files. Normally, the subdirectory is placed inside the virtual directory for external files, as defined in your backup profile's configuration. If you do not enter a directory name Akeeba Backup will use a predetermined name. This name is a random value followed by a dash and the name of the off-site directory you are defining.

Sometimes you want to include off-site files directly inside the archive's root. Two very useful cases are overriding your regular configuration.php file with another one –presumably one tuned for use on your dev site– as well as overriding files in the installation directory, for example in order to customise the appearance of the installer. In those cases you don't want the off-site files to be included inside the virtual directory for off-site files. With Akeeba Backup 3.7.5 and later this is very easy to accomplish. Just set the Virtual Directory to a single forward slash (it's this character: /) and Akeeba Backup will copy the off-site files inside the archive's root.