Support

Documentation

Chapter 2. Using UNiTE
Prev   Next

Chapter 2. Using UNiTE

Table of Contents

The XML command file format
The unite root element
The remote section
The s3 section
The siteInfo section
Common options
Joomla!
WordPress
Drupal 7/8, single site
Drupal 7/8, multi-site installation
Magento 1.x
Magento 2.x
Moodle
phpBB 3
Prestashop
The databaseInfo section
The extrafiles section
The extrasql section
The postrun section

Using UNiTE is fairly simple.

You just need to upload the XML file for the site to be restored and the backup archive in any readable folder on your server and then point UNiTE to that XML file. The latter step can either be a CRON job or executed manually from an SSH console.

[Tip]Tip

You can find examples for restoring your sites in the examples directory of the ZIP file you downloaded from our site. You can consult the examples to get the structure of the file right and this document to understand what each key in the XML file does.

The XML command file format

The most crucial part for getting UNiTE to work is to create the XML command file for each site you want to be installed. Below, we provide a sample skeleton file and explain each of its areas.

<?xml version="1.0" encoding="UTF-8"?>
<unite scripting="02_angie">
	<remote>
		<host>http://www.example.com</host>
		<secret>test</secret>
		<component>com_akeeba</component>
		<profile>1</profile>
		<downloadmode>http</downloadmode>
		<dlurl>ftp://user:pass@ftp.example.com/administrator/components/com_akeeba/backups</dlurl>
		<delete>1</delete>
	</remote>

	<s3>
		<accesskey>ABCDEF</accesskey>
		<secretkey>123456</secretkey>
		<signature>v4</signature>
		<bucket>mybucket</bucket>
		<region>us-east-1</region>
		<ssl>1</ssl>
		<endpoint>api.myservice.com</endpoint>
		<filename>path/to/site-backup.jpa</filename>
	</s3>
	
	<siteInfo>
		<package from="remote"></package>
		<deletePackage>0</deletePackage>
		<localLog>test.log</localLog>
		<emailSysop>0</emailSysop>
		<name>My Shiny Restored Site</name>
		<email>nicholas@dionysopoulos.me</email>
		<absolutepath>/Users/nicholas/Sites/restored</absolutepath>
		<homeurl>http://www.example.net</homeurl>
		<livesite>http://www.example.net</livesite>
		
		<jpspassword><![CDATA[yourpassword]]></jpspassword>
		
		<ftphost>ftp.example.net</ftphost>
		<ftpport>21</ftpport>
		<ftpuser>myuser</ftpuser>
		<ftppass>secret</ftppass>
		<ftpdir>/public_html</ftpdir>

		<adminID>123</adminID>
		<adminUser>admin</adminUser>
		<adminPassword><![CDATA[yourPassword]]></adminPassword>
	</siteInfo>

	<databaseInfo>
		<database name="site">
			<changecollation>0</changecollation>
			<dbdriver>mysqli</dbdriver>
			<dbhost>127.0.0.1</dbhost>
			<dbuser>mydbuser</dbuser>
			<dbpass>password</dbpass>
			<dbname>example</dbname>
			<dbprefix>exmp_</dbprefix>
		</database>
	</databaseInfo>
	
	<extrafiles>
		<extract to="">extras.zip</extract>
	</extrafiles>
	
	<extrasql>
		<execute db="joomla">test.sql</execute>
	</extrasql>

	<postrun>
		<emailto>user@example.com</emailto>
		<emailsubject>Restoration complete</emailsubject>
		<emailbody><![CDATA[
			Email body
		]]></emailbody>
	</postrun>

</unite>

Please note that if you are NOT using one of the optional sections (such as <remote> or <s3>) you should NOT include it in your XML file.

The unite root element

Required: Yes. The root element of your XML file MUST be <unite>.

Scope: The root element can have the attribute scripting which tells UNiTE what kind of site it is restoring and which steps it needs to take to restore it. Scripting INI files can be found in the engine/scripting folder of your UNiTE installation.

In short, you should know this:

  • All backups to be restored MUST be taken with Akeeba Backup for Joomla! 4.6.0 or later, Akeeba Backup for WordPress 1.7.0 or later or Akeeba Solo 1.7.0 or later.

  • You must specify the scripting attribute.

  • Since UNiTE 3.0.0 the value of the scripting attribute MUST be 02_angie at all times.

  • If you have older backups taken with old releases of Akeeba Backup you must set the scripting attribute to joomla or wordress to successfully restore them. Backups taken with Akeeba Solo 1.0 to 1.6 of sites not powered by Joomla or WordPress cannot be restored by UNiTE. Please note that the deprecated scripting methods (joomla and wordress) do not support all of the features listed below in the siteInfo section. We very strongly recommend only using backups taken with moderately recent versions of Akeeba Backup and Akeeba Solo with Akeeba UNiTE.

The remote section

Required: No; this section is optional

Scope: This section tells UNiTE to run a remote site backup and download the backup archive. It is only required when you want to clone a site based on a freshly taken backup, e.g. when transferring a staging site to a live site. This works exactly the same as our Akeeba Remote CLI software. Please consult Remote CLI's documentation on the necessary setup required on your site to enable remote backups.

This section consists of the following parameters:

host

When you are using Akeeba Backup 3.x / 4.x for Joomla!: The URL to your site's root, without a trailing slash, e.g. http://www.example.com Please note that if your site is located in a subdirectory, you have to give the full path to the subdirectory, e.g. http://www.example.com/joomla

When you are using Akeeba Solo: Set it to your Akeeba Solo installation URL without a trailing slash, e.g. http://www.example.com Please note that if your Solo installation is located in a subdirectory, you have to give the full path to the subdirectory, e.g. http://www.example.com/solo

When you are using Akeeba Backup for WordPress: he URL to your site's root, plus the path to Akeeba Backup for WordPress (default: wp-content/plugins/akeebabackupwp), e.g. http://www.example.com/wp-content/plugins/akeebabackupwp Please note that if your site is located in a subdirectory, you have to give the full path to the subdirectory, e.g. http://www.example.com/wp/wp-content/plugins/akeebabackupwp

secret

The secret key, as defined in Akeeba Backup's component parameters. In order to access it in the component, please log in to your site's back-end, go to Components, Akeeba Backup and click on the Component Parameters button. Make sure the Enable front-end and remote backup option is enabled. Right below it, you will find the Secret Key field.

[Important]Important

We strongly advise you to use only lower and upper case latin letters and numbers (a-z, A-Z, 0-9) in your secret word, as many servers will refuse to work with secret words containing special characters.

[Important]Important

If you are using sh404SEF make sure you have upgraded to the latest release. Older versions conflicted with Akeeba Backup's remote API feature and will cause UNiTE to report a JSON decoding error. No support will be provided for this error. The only workaround is to upgrade your copy of sh404SEF (which is a good idea anyway, as the older versions also contained potential security vulnerabilities).

[Important]Important

Some SEF and security components will corrupt or block the request to Akeeba Backup's Remote API. In this case you will most likely get a "JSON decoding error". If this happens you may have to instruct your component to ignore com_akeeba or allow full access to the http://www.example.com/index.php?option=com_akeeba&view=json URL. If unsure, please consult with the developer of your SEF or security component.

component

When you are using Akeeba Backup 3.x / 4.x for Joomla! set it to com_akeeba, i.e. <component>com_akeeba</component>

When you are using Akeeba Solo or Akeeba Backup for WordPress set it to solo, i.e. <component>solo</component>

profile

Optional. The numeric profile ID used to backup the site. If omitted, profile 1 (Default backup profile) will be used.

downloadmode

Can be one of http, chunk or curl

http

instructs UNiTE to download the backup archive through HTTP, similar to what you get by clicking the download links in the "Administer Backup Files" page of Akeeba Backup. Even though it is the simplest method, it may cause corrupted downloads of backup archives over 10-20Mb on most shared hosts.

chunk

works similarly to http, but is designed to work with larger backup archives. It tries to download 1Mb at a time, in order to work around server restrictions on HTTP download. However, on a few shared hosts this will cause the download to fail with a timeout error, memory outage error or an Internal Server Error (HTTP 500 error).

curl

is the recommended method and can be used to download the backup archive over FTP, FTPS or SFTP. The only downside is that it needs some configuration (see the dlurl option below).

dlurl

This option is only required if you are using the curl download method. In this case, it tells UNiTE how to connect to your remote site in order to download the backup archives.

If you are using FTP, you have to specify something like ftp://username:password@hostname:port/path/to/output/directory

Username and Password are your FTP username and password. Hostname is the FTP server's host name. Port is the numeric TCP/IP port (normally it's 21, ask your host). The /path/to/output/directory is the FTP path to yoru output directory. In order to figure out the latter, please use FileZilla to connect to your site and navigate to the backup output directory (by default that is administrator/components/com_akeeba/backup). Copy the path shown above the right-hand folders pane. That's the one you want.

Example:

ftp://myuser: mypassword@ftp.example.com:21/public_html/administrator/components/com_akeeba/backup

delete

When set to 1 (as in the example XML) the backup archive will be removed from the remote site once it's downloaded. It's recommended to set this option to 1 in order not to waste disk space on the remote site's disk.

The s3 section

Required: No; this section is optional

Scope: This section tells UNiTE to connect to S3 -or a third party service with an S3-compatible API- and download a backup archive stored there. It is only required when you want to clone a site based on a backup already stored on Amazon S3 or a third party service with an S3-compatible API.

This section consists of the following parameters:

secretkey

Required. The Amazon S3 Secret Key used for connecting to Amazon S3.

accesskey

Required. The Amazon S3 Access Key used for connecting to Amazon S3.

signature

Optional. The Amazon S3 API signature method to use, i.e. how UNiTE will prove to Amazon S3 that it's authorized to download files. It can either be v2 or v4. The default since UNiTE 3.1.0 is v4.

You should always use the v4 method. It is the most secure and modern method. All Amazon S3 regions added after 2014 (e.g. Frankfurt, Sao Paolo, Ohio etc) support only the v4 method. The old, v2, method should only be used with third party (non-Amazon) implementations of the S3 API, e.g. DreamHost's DreamObjects, Google Storage etc.

[Note]Note

In previous versions of UNiTE the S3 signature method was always v2.

bucket

Required. The Amazon S3 bucket to download files from.

region

Required if you are using the v4 signature. Ignored otherwise. The Amazon S3 region your bucket is located in.

This must be given in the machine readable format under the Region column of the Amazon S3 Region page, NOT the human readable Region Name. For example, you must type us-east-1 , NOT "US East (N. Virginia)", "US", or "Virginia".

filename

Required. The path to the file to download, e.g. /mybackups/somesite/site.jpa.

[Important]Important

In the case of multi-part backup archives you only need to specify the .jpa, .jps or .zip file. UNiTE will automatically find and download all parts (.j01, .j02, ... or .z01, .z02, ...)

ssl

Optional. Should I use SSL (HTTPS) when connecting to Amazon S3. Enter 0 for no or 1 for yes. Default is 1 (yes, use HTTPS). We strongly recommend using the default (1) unless you have a particularly misbehaving server or a proxy in front of it.

endpoint

Optional. When you are not using Amazon S3 but a third party service providing an S3-compatible RESTful API you can give its service endpoint hostname here. Please note that you MUST NOT prefix it with http:// or https://. UNiTE will do that automatically for you when necessary.

If you provide a custom endpoint using this parameter the signature will be forced to v2 and the region parameter will be ignored. v4 signatures and Amazon S3 regions only apply when you are using Amazon S3 proper, not a third party S3-compatible API.

The siteInfo section

Required: Yes; this section must be present!

Scope: This is the section where the basic information regarding the site is defined. It tells UNiTE how the installation is going to happen and what to do with the backup archives. All keys in this section are mandatory unless otherwise specified. All keys' tags are case-sensitive. This means that <package> is different than <PACKAGE> and <Package>. You must follow the letter casing of this skeleton file!

Please note that since UNiTE 3.0 some of the options are different depending on the CMS / script you are restoring.

Common options

The following options apply to all kinds of CMS supported by Akeeba Backup and Akeeba Solo.

package

This option tells UNiTE where to find the backup archive it will restore. There are two cases, getting the archive from a remote backup or getting it from a local file.

If you wish to run a remote backup, you will have to use exactly the following syntax:

<package from="remote"></package>

This will instruct UNiTE to use the information in the <remote> section of the XML command file to take a remote backup, download the backup archive into the configured inbox directory and use it to restore a site.

If you want to use a local file, you have to use the following syntax:

<package>/path/to/package.jpa</package>

The /path/to/package.jpa is the path to the backup archive of the site to be restored. The package can be in the ZIP or JPA format. The path can be either absolute, or relative to the inbox directory. For example, if you have stored a package named mypackage.jpa inside the configured inbox directory, the relative path is mypackage.jpa and the syntax for this parameter would be:

<package>mypackage.jpa</package>

If you have a multipart backup archive (.jpa, .j01, .j02 etc or .zip, .z01, .z02 etc) you MUST only specify the .jpa or .zip file. UNiTE will automatically figure out it's a multipart archive and use the rest of the backup part files without you having to specify them.

[Important]Important

It is recommended that you store your packages inside UNiTE's inbox directory. Please remember that asking UNiTE to use packages outside th inbox directory may NOT work as it is subject to PHP's open_basedir restrictions and file and directory permissions / ACLs.

deletePackage

Should the package files be deleted after a successful installation? This works irrespectively of the global configuration setting for the XML files. Set to 1 to erase the package files, or 0 to skip erasing.

[Note]Note

When set to 1, the extrafiles and extrasql files – if any – will also be erased upon successful installation of the site. If you want the same restoration action to execute whenever UNITE runs (e.g. restoring a demo site), set this to 0.

localLog

The absolute or relative path of the log file kept for this XML file only. The log will contain each action performed by UNiTE when installing the site defined in this XML file. The path can be either absolute, or relative to UNITE's installation path.

emailSysop

When set to 1, UNiTE will email the administrator (the email address defined in UNiTE's configuration) with a copy of the information email sent to the address defined in the XML file and a copy of the log file. Set to 0 to skip emailing the administrator.

absolutepath

The absolute path to the site's root. This is a necessary setting to allow UNiTE to update the site's configuration with the correct values for directories that require an absolute path, e.g. the temporary and cache directories in Joomla!.

jpspassword

Optional. This is used to provide the encryption password necessary only when you are restoring encrypted (JPS) archives. Please remember to surround your password with CDATA, otherwise you will not be able to use any special characters in it (the XML processing will fail, that's how XML works).

ftphost

Optional. The host name of the FTP server containing the site's root directory. If you leave it blank, UNiTE will attempt to restore your site's files using direct PHP file writes and will also ignore all the other ftp* settings. If unsure, always use FTP when restoring sites. If this is defined, you MUST define all other ftp* parameters.

ftpport

Optional. The port of the FTP server containing the site's root directory. Usually it's 21.

ftpuser

Optional. The username for the FTP server containing the site's root directory.

ftppass

Optional. The password for the FTP server containing the site's root directory.

ftpdir

Optional. The FTP path to the site's root directory. THIS IS NOT THE SAME AS THE FILESYSTEM PATH. If unsure, connect to your site with an FTP client, navigate to the site's root and use the FTP directory displayed in your FTP software in this parameter.

Joomla!

The available options for Joomla sites are:

name

The name of the Joomla! site. Whatever you write here will be stored in the site's configuration.php file and will be the title of your site, appearing in the front- and back-end.

email

The email of the site's Super Administrator and the e-mail address from which all email sent by Joomla! will appear to come from. Whatever you write here will be stored in the site's configuration.php file and database, but is not validated to make sure it's a real, live e-mail address.

[Warning]Warning

Make sure this is a valid email address. Joomla! 3.5 will crash when trying to send email if this is not a valid email address!

livesite

Optional. If set, the contents of the $live_site parameter in your configuration.php file. If you omit it, the $live_site parameter will be left intact. If you want to reset $live_site on the restored site with an empty string, please write this tag as <livesite></livesite> (no spaces between the open and closing tags).

tmppath

Optional. The site's temporary directory. If you do not provide this the tmp directory inside your site's root will be used instead.

logspath

Optional. The site's logs directory. If you do not provide this the administrator/logs directory inside your site will be used instead. If this doesn't exist, UNiTE will try using the logs directory in your site's root. If this is not writeable, as is the case with Plesk servers which use this for system logs, the log directory will be used instead.

cookiedomain

Optional. The domain name for the cookies set by Joomla!. This should be your domain name without protocol and path, e.g. www.example.com or localhost but NOT http://www.example.com or http://localhost/joomla. This setting MUST be the domain name where your site is installed. In most cases you can set this to empty i.e. <cookiedomain></cookiedomain> instructing Joomla! to automatically detect this setting. Omit this to preserve the setting currently in your configuration.php file.

cookiepath

Optional. The path for the cookies set by Joomla!. This should be the path in your domain where the site is installed, with a leading slash, but without a trailing slash , e.g. / or /joomla but NOT http://www.example.com or http://localhost/joomla. This setting MUST be the directory where your site is installed. In most cases you can set this to empty i.e. <cookiepath></cookiepath> instructing Joomla! to automatically detect this setting. Omit this to preserve the setting currently in your configuration.php file.

force_ssl

Optional. Should Joomla! forcibly turn on SSL (HTTPS)? 0 means that HTTPS will NOT be enforced by Joomla!. 1 means that only the backend of the site will be forced to use HTTPS. 2 means that the entire site, backend and frontend, will be forced to use HTTPS. If your site uses HTTPS you are strongly advised to set it to 2. Omit to leave this setting as it's currently set in your site's Global Configuration.

removephpini

Optional. Should I remove any php.ini and .user.ini files from the site's root and administrator directories? Set to 0 (default) to keep them, set to 1 to remove them. Recommended to set to 1 when restoring on a new server whose settings might be incompatible with the server you backed the site up from.

removehtpasswd

Optional. Should I remove any .htaccess and .htpasswd files from the site's root and administrator directories? Set to 0 (default) to keep them, set to 1 to remove them. Recommended to set to 1 when restoring on a new server whose settings might be incompatible with the server you backed the site up from, preventing you from logging it to the site's backend if you have administrator password protection using .htaccess files enabled.

replacehtaccess

Optional. Should I replace your site's .htaccess file with the Joomla!'s default file? Set to 0 (default) to keep any existing file as-is, set to 1 to replace it. Recommended to set to 1 when restoring on a new Apache or Lighttpd server whose settings might be incompatible with the server you backed the site up from.

replacewebconfig

Optional. Should I replace your site's web.config file with the Joomla!'s default file? Set to 0 (default) to keep any existing file as-is, set to 1 to replace it. Recommended to set to 1 when restoring on a new Microsoft Internet Information Services (IIS) server whose settings might be incompatible with the server you backed the site up from.

adminID

Optional. The numeric ID of the Super Administrator / Super User user, so that we can change his username and password, if the next two keys are specified. The default Super Administrator user created on Joomla! installation is 62 for Joomla! 1.5 and 42 for Joomla! 2.5. If you have deleted this user, you'll have to look it up in the database of the site you have backed up and use as an installation package. For Joomla! 3.x you MUST provide this ID as the Super User ID is assigned randomly during installation.

adminUser

Optional. Change the username of the Super User account to this value. Requires the adminID and adminEmail options to be set. Omit to leave the username intact.

adminPassword

Optional. The new password for the Super User account. Requires the adminID and adminEmail options to be set. Omit to leave the password intact.

adminEmail

Optional (but required if changing password) . The email of the Super User account. Required to change the Super User password. Omit to leave the password intact.

WordPress

The available options for WordPress sites are:

name

The name of the WordPress site. Whatever you write here will be stored in the site's wp_options table and will be the title of your blog, appearing in the front- and back-end.

email

The email of the site's Administrator.

homeurl

The WordPress Address (URL) for your site. This is the address you want people to type in their browser to reach your WordPress blog (also known as the Home setting)

livesite

Optional. Site Address (URL). Enter the address here if you want your site homepage to be different from the directory you installed WordPress.

adminID

Optional. The numeric ID of the Administrator user, so that we can change his username and password. Check your database.

adminUser

Optional. The username you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the username intact.

adminPassword

Optional. The password you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the password intact.

replacedata

A set of additional values to replace in WordPress' tables after the database restoration. It has the format:

<replacedata>
	<data oldvalue="foo" newvalue="bar" />
	<data oldvalue="some" newvalue="thing" />
</replacedata>

Each <data> element MUST have exactly two attributes named oldvalue (the value in the site you backed up from) and newvalue (the value you want to have in the restored site).

Replacement of data takes place in both text and serialised data content.

Drupal 7/8, single site

The available options for Drupal 7 and 8 single sites (NOT multi-site installations!) are as follows:

name

The name of the site. Whatever you write here will be stored in the site's configuration will be the title of your site.

email

The email of the site's Administrator.

adminID

Optional. The numeric ID of the Administrator user, so that we can change his username and password. Check your database.

adminUser

Optional. The username you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the username intact.

adminPassword

Optional. The password you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the password intact.

Drupal 7/8, multi-site installation

The available options for Drupal 7 and 8 multi-site installations are as follows. All of the following options apply for the main site only. Each slave (multi-)site needs a <site> definition inside the <sites> element as documented below.

name

The name of the site. Whatever you write here will be stored in the site's configuration will be the title of your site.

email

The email of the site's Administrator.

adminID

Optional. The numeric ID of the Administrator user, so that we can change his username and password. Check your database.

adminUser

Optional. The username you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the username intact.

adminPassword

Optional. The password you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the password intact.

sites

A list of definitions for your multisites. The format is similar to this:

    <sites>
      <domain>newsite.com</domain>
      <site>
        <key>newsite.com.slave</key>
        <name>My Shiny Slave Site</name>
        <email>slave@example.com</email>
        <adminID>1</adminID>
        <adminUser>admin</adminUser>
        <adminEmail>admin@example.com</adminEmail>
        <adminPassword>unite</adminPassword>
      </site>
    </sites>

The <domain> key defines the domain name used by your multisites. Please note that each slave site of the multisite installation needs a new <site> element with the keys outlined below. Also remember that restoring a multisite installation which uses a different database per site also requires you to set up the database restoration in the <databaseInfo> section. Please consult the inbox/examples/drupal_7_ms_different_db.xml example file for a more understandable example.

The keys for each <site> element are as follows:

key

The key of this slave site, as defined in Drupal.

name

The name of the slave site. Whatever you write here will be stored in the slave site's configuration will be the title of your slave site.

email

The email of the slave site's Administrator.

adminID

Optional. The numeric ID of the Administrator user of the slave site, so that we can change his username and password. Check your database.

adminUser

Optional. The username you wish for the Administrator user of the slave site. Requires the adminID option to be set. Omit to leave the username intact.

adminPassword

Optional. The password you wish for the Administrator user of the slave site. Requires the adminID option to be set. Omit to leave the password intact.

Magento 1.x

The available options for Magento 1.x are:

livesite

Optional. The URL to your site, in case your server doesn't report it correctly.

adminID

Optional. The numeric ID of the Administrator user of the site, so that we can change his email and password. Check your database.

adminEmail

Optional. Change the email of the site's Administrator to this value. This also acts as a username for logging in. Omit to leave the email intact.

adminPassword

Optional. The password you wish for the Administrator user of the site. Requires the adminID option to be set. Omit to leave the password intact.

Magento 2.x

The available options for Magento 2.x are:

adminID

Optional. The numeric ID of the Administrator user of the site, so that we can change his username and password. Check your database.

adminUser

Optional. The username you wish for the Administrator user of the site. Requires the adminID option to be set. Omit to leave the username intact.

adminEmail

Optional. Change the email of the site's Administrator to this value. Omit to leave the email intact.

adminPassword

Optional. The password you wish for the Administrator user of the site. Requires the adminID option to be set. Omit to leave the password intact.

Moodle

The available options for Moodle are:

livesite

Optional. The URL to your site, in case your server doesn't report it correctly.

adminID

Optional. The numeric ID of the Administrator user of the site, so that we can change his email and password. Check your database.

adminEmail

Optional. Change the email of the site's Administrator to this value. Omit to leave the email intact.

adminPassword

Optional. The password you wish for the Administrator user of the site. Requires the adminID option to be set. Omit to leave the password intact.

offsitedirs

Optional. Tells UNiTE where to copy the files of Off-Site Directory Inclusions. Remember that Moodle comes with a Moodle Data Directory that is supposed to be stored off-site? This data is extracted in external_files/moodledata inside the site's root. This option lets you move that data to the correct location:

    <offsitedirs>
      <dir virtual="/moodledata" real="/new/absolute/path/to/moodledata"/>
    </offsitedirs>

Each <dir> element has the following attributes:

  • dir. The name of the directory in the external_files directory of the backup archive.

  • real. The absolute filesystem path where the files should be copied to (the permanent and final location).

phpBB 3

The available options for phpBB 3 sites are:

name

The name of the phpBB 3 forum. Whatever you write here will be stored in the site's configuration file and will be the title of your site.

descr

The description of the phpBB 3 forum.

email

The the e-mail address from which all email sent by the forum will appear to come from.

siteurl

The URL to your forum.

Prestashop

The available options for Prestashop sites are:

name

The name of the shop. Whatever you write here will be stored in the site's configuration file and will be the title of your shop.

email

The e-mail address from which all email sent by Joomla! will appear to come from.

siteurl

The URL to your shop.

adminID

Optional. The numeric ID of the Administrator so that we can change his email and password, if the next two keys are specified.

adminEmail

Optional. Change the email of the Administrator account to this value. Requires the adminID option to be set. Omit to leave the email intact.

adminPassword

Optional. The new password for the Administrator account. Requires the adminID option to be set. Omit to leave the password intact.

The databaseInfo section

Required: Yes; this section is mandatory

Scope: UNITE needs to know how to connect to your MySQL database so that it can restore the database(s) dumped during backup time. The databaseInfo section does exactly that. It takes one <database> section per database to restore.

Each database section tag has a name attribute which corresponds to the base name of the dump file. For backups made with Akeeba Backup 3.2.7 up to and including 3.10.0 the main Joomla! database is always dumped to files named joomla.sql, joomla.s01, etc so the name attribute needs to be joomla. Since Akeeba Backup 3.10.1 the main Joomla! database is always dumped to files named site.sql, site.s01, etc so the name attribute needs to be site. If you are restoring a backup created by Akeeba Backup for WordPress or Akeeba Solo you MUST use site. If you mistakenly use joomla instead of site UNiTE will automatically try to switch to site in most cases.

The extra databases are dumped using short UUID's as their base name which typically look like ABCD123-databasename.sql. In this case, the name attribute needs to be the base name of the dump file, i.e. ABCD123-databasename in the specified example.

The best way to figure out which database is dumped under which name is to take a look at the databases.ini file in the installation/sql directory inside the archive. In order to do that, simply take one backup of the site and extract it using Akeeba eXtract Wizard. Then, navigate to the extracted installation/sql directory and open the databases.ini in your text editor. The INI sections correspond to the base name of the dump files, whereas the keys contain the connection information of the original site's databases. You can use that as your “cheat sheet” when creating the <database> sections of the <databaseInfo> tag for UNiTE.

Each <database> tag can contain the following tags:

changecollation

When set to 1 UNiTE will try to forcibly change the collation of all tables and fields to UTF8 (utf8_general_ci). Normally this is not required, unless you have a broken database setup.

[Note]Note

This feature is deprecated. We suggest creating your database with UTF-8 collation.

dbdriver

The database driver to use. You can use one of:

  • mysql. Legacy MySQL driver. Mostly for older hosts. We recommend using the mysqli driver whenever possible.

  • mysqli. The mysqli driver is the newest version of PHP's MySQL driver and we suggest trying this first. If it doesn't work we advise you to update your copy PHP to the latest published stable version; in the meantime, please use the mysql driver.

  • postgresql. Driver for PostgreSQL databases.

  • sqlazure. Driver for Microsoft Azure SQL Database. This is essentially an instance of Microsoft SQL Server running on Microsoft's cloud.

  • sqlsrv. Driver for Microsoft SQL Server databases.

Please remember that the driver server technology MUST match the database server technology of BOTH the origin AND the target server. This means that, for example, if you backed up a site running on a MySQL database server you can only use the mysql and mysqli servers and your target database server (where the restoration takes place) must be MySQL. You cannot, for example, backup a site on MySQL and restore it on PostgreSQL or SQL Server.

dbhost

Database host name (MySQL server's host name).

dbport

Optional. The port your MySQL server listens to. If you skip this it will use the default port (3306).

dbuser

Database username.

dbpass

Database password.

[Warning]Warning

YOU SHOULD NEVER USE AN EMPTY DATABASE PASSWORD. Use of empty passwords is deprecated and may cease to work at any time.

dbname

Database name.

[Warning]Warning

THE DATABASE NAME SPECIFIED HERE MUST BE A VALID NAME FOR A DATABASE WHICH ALREADY EXISTS. Depending on the database driver being used, UNiTE MAY try to create the database if it doesn't exist but it's not guaranteed that it will succeed (usually creating a database requires providing the database root user credentials in dbuser and dbpass which is risky). If the database does not exist and cannot be created you MAY receive a misleading error indicating that a table doesn't exist. UNiTE cannot really test for the existence of a database. It has to take your word for it.

dbprefix

Prefix of the database table names.

If AND ONLY if you are restoring an extra database, NOT the main database of your site, which already didn't have a prefix attached to it during backup, you can leave the value blank, that is the tag should read <dbprefix />

[Warning]Warning

YOU MUST NEVER LEAVE THIS BLANK FOR THE MAIN DATABASE OF A JOOMLA! OR WORDPRESS SITE! Using a blank prefix WILL lead to a restoration FAILURE as neither Joomla! nor WordPress are designed to work with an empty database prefix.

existing

Since 3.0.0. What to do with existing tables. Can be drop (delete existing tables) or backup (rename existing tables, changing their prefix to bak_).

foreignkey

if set to 1 we will ignore foreign key checks. This is useful when restoring sites with complex data structures. We recommend always setting this to 1 when restoring full site backups with UNiTE. If omitted or set to 1 the database will enforce any foreign key constraints.

noautovalue

When it's set to 1 no auto value will be applied on zero values. Only valid for MySQL databases. Allows you to restore tables with auto-incrementing fields whose value is zero. Magento and Drupal require this setting to be set to 1 for proper restoration. Other CMS should not require this. Defaults to 0 when not set. NOTE: Per MySQL's documentation: "Storing 0 is not a recommended practice."

replace

When set to 1 UNiTE will use REPLACE instead of INSERT. UNiTE will normally use INSERT commands to restore the database data. This doesn't work well with certain extensions' data, causing restoration issues. If you get database restoration errors please set this to 1. If omitted the default value 0 (use INSERT commands) will be used.

utf8db

When set to 1, force UTF-8 collation on database. When enabled UNiTE will try to convert the default collation of your table to Unicode (UTF-8), as suggested by most CMS. This doesn't work on all servers. Check it if you get question marks or broken text instead of international characters. Default is 0 (do not convert).

If you want to restore a Joomla! or WordPress site taken on a server with UTF8MB4 collation to a server that does not support UTF8MB4 collation set this option to 1 and the utf8mb4 option to 0.

utf8tables

When set to 1, force UTF-8 collation on tables. When enabled UNiTE will try to convert all text fields of restored tables to Unicode (UTF-8). This is a workaround when you cannot use the option above. Please note that if your database collation is anything other than UTF-8 you will have problems in the future, e.g. after an extension/module/plugin upgrade adds a new text field.

utf8mb4

Allow UTF8MB4 auto-detection. If set to 1 and your database server supports UTF8MB4 (UTF-8 Multibyte) it will be used instead of plain old UTF-8. WARNING: Only use if your site was using UTF8MB4 when you backed it up. Set to 0 if you get broken text after restoring your site! See the information about utf8db above.

ignoreCreateErrors

Ignore errors coming from table CREATE. If set to 1 any errors coming from running CREATE TABLE and CREATE VIEW commands will not cause the restoration to fail.

ignoreInsertErrors

Ignore errors coming from INSERT commands, writing data to the database. If set to 1 any errors coming from running INSERT commands will not cause the restoration to fail.

The extrafiles section

Required: No; this section is optional

Scope: This section allows you to extract an arbitrary number of ZIP and/or JPA archives into arbitrary locations under the newly installed web site's root directory. This might be useful for branding purposes (e.g. supplying a different custom theme for each new site).

If you do not wish to make use of this feature, you must not include this section at all in your XML file.

This section can consist of any number of <extract> tags. Each extract tag specifies the extraction details of exactly one ZIP or JPA archive's files into the newly restored site. Each archive is extracted keeping its directory structure. This means that if you have directories and subdirectories inside the archive, this directory structure will be kept intact, just like most archiver utilities would do when extracting an archive.

Each tag can have an optional attribute, titled to, which instructs UNITE where to extract the files. This is a path relative to the site's root, so an entry of images/stories will extract the contents of the archive inside the stories subdirectory of the images directory inside the site's root. If omitted, or left blank, the site's root is assumed.

The value between the starting and ending tag is the absolute or relative (to the inbox directory) path to the ZIP or JPA archive.

There is no limit on the number of <extract> tags inside the extrafiles section. You can have only one or several hundred thousands. You are only limited by available memory to hold the list of the archive files to be extracted.

The extrasql section

Required: No; this section is optional

Scope: Just like extrafiles, you can use the extrasql section to execute SQL scripts against your newly installed site's database. There is no limit on the number of SQL files you can execute against your site's database or in the number of SQL commands a single SQL file can hold.

If you do not wish to make use of this feature, you must not include this section at all in your XML file.

This section can consist of any number of <execute> tags. Each execute tag specifies the execution details of exactly one SQL script against the newly restored site's database.

There is a mandatory attribute for each <execute> tag, called db. This includes the database tag – as specified in the <databaseInfo> section – of the database against which the SQL file will run. For example, in order to run a file against the Joomla! / WordPress database, you have to use a tag like this: <execute db="joomla"> or <execute db="site">, see the notes on the siteInfo section.

The value between the starting and ending tag is the relative, to your inbox directory, path to the SQL file.

The SQL file can hold any number of SQL commands, as long as they are terminated by a semicolon (standard SQL script rules). You can use the “metaprefix”, a single hash followed by two underscores (#__) instead of the real prefix to the site's database in table names. So, if you use the table name #__content and your site's prefix is jos_, before executing the SQL command UNiTE will translate it to jos_content. If you use the same script against another site whose prefix is dem_ then UNiTE will translate it to dem_content. This allows for reusable SQL scripts, without having to update the table prefixes all the time.

There is no limit on the number of <execute> tags inside the extrasql section. You can have only one or several hundred thousands. You are only limited by available memory to hold the list of the SQL files to be executed.

The postrun section

Required: No; this section is optional

Scope: This final section defines the e-mail communication to the restored site's administrator, after the site's installation is over.

The configuration keys are:

emailto

The email address to send the e-mail to. This is your restored site's administrator e-mail address. It may be different than the e-mail address specified for the Super Admin user of the restored site.

emailsubject

The subject line of the email message.

emailbody

The contents (body) of the email to be sent to the client. Do not use HTML. UNiTE only supports sending plain text messages. You are advised to wrap the lines at 78 characters, as per the RFC specifications. Some (older) email clients get anal retentive when met with longer lines, causing the email to not appear correctly or at all! Also, please do note the <![CDATA[ and ]]> at the beginning and the end of the text. They are mandatory! Without them, the preformatted nature of the email text will be ignored and line brakes will occur at random places, or the message might be cut off, or the installation fail completely.

Prev   Next
Configuring UNiTE Home Appendix A. GNU Free Documentation License

Cookies Notification - Action required

This website uses cookies to provide user authentication and improve your user experience. Please indicate whether you consent to our site placing these cookies on your device. You can change your preference later, from the controls which will be made available to you at the bottom of every page of our site.