{docbook}
<abstract>
<para>
The backup of eXo Platform instance involves backing up the databases and the file systems for the JCR index and value storage. The following topics are covered in this chapter:
</para>
<itemizedlist>
<listitem>
<para>
	<emphasis role="bold"><link linkend="ADM.Backup.Plan_backup">Pre-backup</link></emphasis>
</para>
<para>
Preparations for backing up JCR data, Organization service database, and Transaction service files; basic principles of eXo Platform backup and how to create your backup implementation.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><link linkend="ADM.Backup.Perform_backup">Back up eXo Platform</link></emphasis>
</para>
<para>
Instructions on how to back up eXo Platform.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><link linkend="ADM.Backup.Perform_restore">Restore</link> </emphasis>
</para>
<para>
Instructions on how to restore from the backup that can be used in the failure or site duplication cases.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><link linkend="ADM.Backup.Third_party_tools">Third-party tools</link> </emphasis>
</para>
<para>
Additional information of third-party tools which can be used in the backup period, such as <emphasis>rsync</emphasis> tool for Unix platforms, or the Backup utility for Microsoft Windows.
</para>
</listitem>
</itemizedlist>
</abstract>
{docbook}
{note}
The _gatein.data.dir_ variable is defined in the _configuration.properties_ file and by default points to the _$APPSEVERHOME/gatein/data_ folder.
{note}

You can use the .tar command for the file backup from your application server home dir: 

{code}tar cvjf gatein-backup.tar.bz gatein/data{code}


h1. Pre-backup {anchor:id=ADM.Backup.Plan_backup}

You can start your backup strategy with the concept of a data repository. It is required to store and arrange backup data properly.
The backup of one eXo Platform instance produces a set of files which can be located on various storage media (hard disk, tape, optical or solid storages, or even special remote backup services).  

The files are organized in catalogs (folders) or used in different media to the concrete Platform implementation. However, it is highly recommended that you apply the [Backup rotation scheme|http://en.wikipedia.org/wiki/Backup_rotation_scheme] to make the backup implementation effective and reliable.

Also, be sure that your available backup solution of Operating System and Database software are always used, allowing you to simplify the backup organization and avoid mistakes and data loss.

In the pre-backup, you need to stop the whole eXo Platform server. 

{warning}
In case of the eXo Platform clustering, every node should be stopped before the backup is performed.
{warning}

The backup of eXo Platform consists of the following parts:

* Backup of the JCR data:
** JCR index files, pointed by the configuration property: _gatein.jcr.index.data.dir_.
** JCR value storage files, pointed by the configuration property: _gatein.jcr.storage.data.dir_.
** JCR database backup, database specified in the JDNI configuration of Application server with the _exo-jcr\_portal_ name.
* Backup of Organization service database specified in the JDNI configuration of Application server with the _exo-idm\_portal_ name.
* Backup of Transaction service files pointed by the configuration property: _com.arjuna.ats.arjuna.objectstore.objectStoreDir_.

In the pre-backup, it is recommended that you prepare for tools, such as scripts, to restore data quickly and safely. 

{note}
eXo Platform indicates to one Portal application in this context, which is set by default. However, if your eXo Platform instance runs several portals, each of which has its own JCR, Organization and Transaction services, you should back up data of each portal separately. 

Information provided in this chapter only describes the backup of the single-portal Platform. The backup can be repeated for each portal in your system. 
Only two types of JCR files are important in the backup: index and value storages. 

The _gatein.jcr.data.dir_ folder (_$gatein.data.dir/jcr_ by default) also contains the _swap_ sub-folder. The _swap_ folder is used for temporary files in case BLOBs are stored in the database and has no meaning for backup. For more details, see the [eXo JCR configuration|../../reference/html/JCRref.Configuration.BasicConfiguration.html] section.
{note}

To learn more about the basic principles of eXo Platform backup and how to create your backup implementation, see the following *Backup Planning* example:

{docbook}
<citetitle>
<para>
<emphasis role="bold">
Environment
</emphasis>
</para>
</citetitle>
{docbook}

* The eXo Platform server runs on the RedHat Linux server. eXo Platform provides the remote database server MySQL 5.1:
** JCR database - _jcrdb_.
** Organization service database - _idmdb_.

* The eXo Platform files are on the network mounted storage _/mnt/netfs/platform_:
** JCR value storage files in _/mnt/netfs/platform/jcr/values_.
** JCR index files in _/mnt/netfs/platform/jcr/index_.
** Transaction service stored in _/mnt/netfs/platform/jta_.

* The backup storage is located on the dedicated network mounted storage: _/mnt/backupfs/my\_plf\_backup_.

{docbook}
<citetitle>
<para>
<emphasis role="bold">
Naming and Rotation
</emphasis>
</para>
</citetitle>
{docbook}
It is a general case when the backup is organized in the two-cycle rotation: backup files are stored everyday and older data are stored weekly, and the data storage history will be planned for three years.

To implement this approach, the daily backup is run (at night when the site is not in use) and stores result files (database and JCR files) on the network storage in the following structure:

* {{{/my_plf_backup/2010/...}}} - The archive folder of the previous year.
* {{{/my_plf_backup/current/}}} - The archive folder of the current year.
* {{{/my_plf_backup/current/weeks}}} - The weekly archive folder of the current year.
* {{{/my_plf_backup/current/weeks/01}}} - The archive folder of the first week of the current year.
* {{{/my_plf_backup/current/weeks/02}}} - The archive folder of the second week of the current year.
* {{{/my_plf_backup/current/weeks/N}}} - The archive folder of the week named N of the current year.

The backup files are named to the [ISO 8601|http://en.wikipedia.org/wiki/ISO_8601] date format:

* {{{yyyy-MM-dd_mysql_jcrdb.tar.gz}}} - For the JCR database.
* {{{yyyy-MM-dd_mysql_idmdb.tar.gz}}} - For the Organization service database.
* {{{yyyy-MM-dd_jcr_values.tar.gz}}} - For the JCR value storage files.
* {{{yyyy-MM-dd_jcr_index.tar.gz}}} - For the JCR index files.
* {{{yyyy-MM-dd_jta.tar.gz}}} - For the Transaction service files.

For the files backup, eXo Platform provides a shell script running on the eXo Platform server. This script does the following actions:

* Stop the eXo Platform server to ensure the full stop by the log sniffering.
* Run the database backup tool against _jcrdb_ and store the result file in the archive {{{/mnt/backupfs/my_plf_backup/current/yyyy-MM-dd_mysql_jcrdb.tar.gz}}}.
* Run the database backup tool against _idmdb_ and store the result file in the archive {{{/mnt/backupfs/my_plf_backup/current/yyyy-MM-dd_mysql_idmdb.tar.gz}}}.
* Copy the JCR value files to the archive {{{/mnt/backupfs/my_plf_backup/current/yyyy-MM-dd_jcr_values.tar.gz}}}.
* Copy the JCR index files to the archive {{{/mnt/backupfs/my_plf_backup/current/yyyy-MM-dd_jcr_index.tar.gz}}}.
* Copy the Transaction service files to the archive {{{/mnt/backupfs/my_plf_backup/current/yyyy-MM-dd_jta.tar.gz}}}.
* Copy all old archive files of 7 days to a week folder, for example {{{/my_plf_backup/current/weeks/02}}}.
* Delete older files of 7 days as from {{{/my_plf_backup/current/}}}.
* Create a folder for the previous year in {{{/my_plf_backup/}}} if it is the [first week|http://en.wikipedia.org/wiki/ISO_8601#Week_dates] of a new year, such as {{{/my_plf_backup/2010}}}, and then move content of {{{/my_plf_backup/current/weeks}}} there.
* Start the eXo Platform server.
* Send email to the administrator in case of any errors on any step.


{note}
Examples of the script implementation are out of the scope of this guide.
{note}

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Back up eXo Platform|#ADM.Backup.Perform_backup]
* [Restore|#ADM.Backup.Perform_restore]
* [Third-party tools|#ADM.Backup.Third_party_tools]

h1. Back up eXo Platform {anchor:id=ADM.Backup.Perform_backup}

*1.* Stop the whole eXo Platform instance by using the shell command: _stop\_eXo_. To see more details, see the [Installation and Startup|#ADM.Installation_and_Startup] chapter.

*2.* Run the backup procedure, including:

* The JCR database.
* The Organization service database.
* The JCR value storage files.
* The JCR index files.
* The Transaction service files.

*3.* Archive the backup files to your backup storage.

*4.* Start the eXo Platform server.

{note}
In case of the eXo Platform clustering, start the backup to the steps described in the [Clustering|#ADM.Clustering] chapter.
{note}

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Pre-backup|#ADM.Backup.Plan_backup]
* [Restore|#ADM.Backup.Perform_restore]
* [Third-party tools|#ADM.Backup.Third_party_tools]

h1. Restore {anchor:id=ADM.Backup.Perform_restore} 

Restoring from the backup can be used in several cases, such as failure, or site duplication. Similar to the backup, it is important to stop the whole eXo Platform before restoring. Next, do the main steps to start restoring from the backup of eXo Platform:

*1.* Unarchive the backup files from the backup storage to the temporary location.

*2.* Stop the whole eXo Platform instance by using the shell command {{{stop_eXo}}}. To see more details, see the [Installation and Startup|#ADM.Installation_and_Startup] chapter.

*3.* Run the restoring procedure to restore from the backup local files for:

* The JCR database.
* The Organization service database.
* The JCR value storage files.
* The JCR index files.
* The Transaction service files.

*4.* Start the eXo Platform server.

{note}
In case of the eXo Platform clustering, start restoring to the steps described in the [Clustering|#ADM.Clustering] chapter.
{note}

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Pre-backup|#ADM.Backup.Plan_backup]
* [Back up eXo Platform|#ADM.Backup.Perform_backup]
* [Third-party tools|#ADM.Backup.Third_party_tools]

h1. Third-party tools {anchor:id=ADM.Backup.Third_party_tools}

Steps described above are based on the whole backup of data. However, the [incremental backup approach|http://en.wikipedia.org/wiki/Incremental_backup] allows you to
preserve data by creating multiple copies that are based on the differences in those data. The successive copy of data only contains the portion which has been changed since the preceding copy has been created.

In steps described above, it is also possible to implement an incremental backup against the eXo Platform data.

Users of the Unix platforms can use the _rsync_ tool for files synchronization and implement the incremental backup for JCR value and index files. Meanwhile, Microsoft Windows users can use the Backup utility (_Ntbackup.exe_).  

These tools can be used in conjunction with a database incremental backup feature of your RDBMS to implement the eXo Platform incremental backup solution. However, all backup targets described above should be counted. 

In case of the example, it is possible to organize the full backup weekly (on Sunday) and incrementals daily. The incremental backup will be faster, and reduce your site maintenance daily.

{note}
It is also possible to use the ready solutions as [backula.org.|http://www.bacula.org/]
{note}

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Pre-backup|#ADM.Backup.Plan_backup]
* [Back up eXo Platform|#ADM.Backup.Perform_backup]
* [Restore|#ADM.Backup.Perform_restore]