Table of Contents
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 |
---|---|
You can find examples for restoring your sites in the
|
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.
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.
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:
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
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 |
---|---|
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 |
---|---|
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 |
---|---|
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
|
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>
Optional. The numeric profile ID used to backup the site. If omitted, profile 1 (Default backup profile) will be used.
Can be one of http, chunk or curl
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.
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).
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).
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
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.
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:
Required. The Amazon S3 Secret Key used for connecting to Amazon S3.
Required. The Amazon S3 Access Key used for connecting to Amazon S3.
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 |
---|---|
In previous versions of UNiTE the S3 signature method was always v2. |
Required. The Amazon S3 bucket to download files from.
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".
Required. The path to the file to download, e.g.
/mybackups/somesite/site.jpa
.
![]() | 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, ...) |
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.
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.
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.
The following options apply to all kinds of CMS supported by Akeeba Backup and Akeeba Solo.
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 |
---|---|
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. |
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 |
---|---|
When set to |
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.
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.
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!.
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).
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.
Optional. The port of the FTP server containing the site's root directory. Usually it's 21.
Optional. The username for the FTP server containing the site's root directory.
Optional. The password for the FTP server containing the site's root directory.
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.
The available options for Joomla sites are:
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.
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 |
---|---|
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! |
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).
Optional. The site's
temporary directory. If you do not provide this the
tmp
directory inside your site's root
will be used instead.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Optional. The new password for the Super User account. Requires the adminID and adminEmail options to be set. Omit to leave the password intact.
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.
The available options for WordPress sites are:
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.
The email of the site's Administrator.
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)
Optional. Site Address (URL). Enter the address here if you want your site homepage to be different from the directory you installed WordPress.
Optional. The numeric ID of the Administrator user, so that we can change his username and password. Check your database.
Optional. The username you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the username intact.
Optional. The password you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the password intact.
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.
The available options for Drupal 7 and 8 single sites (NOT multi-site installations!) are as follows:
The name of the site. Whatever you write here will be stored in the site's configuration will be the title of your site.
The email of the site's Administrator.
Optional. The numeric ID of the Administrator user, so that we can change his username and password. Check your database.
Optional. The username you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the username intact.
Optional. The password you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the password intact.
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.
The name of the site. Whatever you write here will be stored in the site's configuration will be the title of your site.
The email of the site's Administrator.
Optional. The numeric ID of the Administrator user, so that we can change his username and password. Check your database.
Optional. The username you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the username intact.
Optional. The password you wish for the Administrator user. Requires the adminID option to be set. Omit to leave the password intact.
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:
The key of this slave site, as defined in Drupal.
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.
The email of the slave site's Administrator.
Optional. The numeric ID of the Administrator user of the slave site, so that we can change his username and password. Check your database.
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.
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.
The available options for Magento 1.x are:
Optional. The URL to your site, in case your server doesn't report it correctly.
Optional. The numeric ID of the Administrator user of the site, so that we can change his email and password. Check your database.
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.
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.
The available options for Magento 2.x are:
Optional. The numeric ID of the Administrator user of the site, so that we can change his username and password. Check your database.
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.
Optional. Change the email of the site's Administrator to this value. Omit to leave the email intact.
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.
The available options for Moodle are:
Optional. The URL to your site, in case your server doesn't report it correctly.
Optional. The numeric ID of the Administrator user of the site, so that we can change his email and password. Check your database.
Optional. Change the email of the site's Administrator to this value. Omit to leave the email intact.
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.
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).
The available options for phpBB 3 sites are:
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.
The description of the phpBB 3 forum.
The the e-mail address from which all email sent by the forum will appear to come from.
The URL to your forum.
The available options for Prestashop sites are:
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.
The e-mail address from which all email sent by Joomla! will appear to come from.
The URL to your shop.
Optional. The numeric ID of the Administrator so that we can change his email and password, if the next two keys are specified.
Optional. Change the email of the Administrator account to this value. Requires the adminID option to be set. Omit to leave the email intact.
Optional. The new password for the Administrator account. Requires the adminID option to be set. Omit to leave the password intact.
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:
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 |
---|---|
This feature is deprecated. We suggest creating your database with UTF-8 collation. |
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.
Database host name (MySQL server's host name).
Optional. The port your MySQL server listens to. If you skip this it will use the default port (3306).
Database username.
Database password.
![]() | Warning |
---|---|
YOU SHOULD NEVER USE AN EMPTY DATABASE PASSWORD. Use of empty passwords is deprecated and may cease to work at any time. |
Database name.
![]() | 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. |
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 |
---|---|
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. |
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_).
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.
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."
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
The subject line of the email message.
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.