Backup module

Edition	DX Core
License	MLA
Issues	MGNLBACKUP
Maven site	Backup
Latest	2.4.1

Edition

DX Core

License

MLA

Issues

MGNLBACKUP

Maven site

Backup

Latest

2.4.1

The Backup module allows you to take manual and scheduled backups of content and configuration. The module backs up Magnolia configuration and all versions of content in all workspaces. Manual and automated scheduled backups can be managed in the Backup app. Backup and restore scripts are provided for more flexible backup options and for restoring Magnolia.

Installing with maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia</groupId>
  <artifactId>magnolia-module-backup</artifactId>
  <version>2.4.1</version>
</dependency>

Backup app

The Backup app allows you to make a manual backup, schedule automatic backups and view existing backup tasks. The tool creates a backup of the entire Magnolia installation.

Making a manual backup

To make a manual backup:

Create the target backup directory on the file system.
In Manual backup enter the path to your backup directory. The path must be absolute.
Click Backup.

Here is the structure of the backup folder.

└───<target directory>
    ├───repository
    │ ├───datastore
    │ ├───meta
    │ ├───namespaces
    │ ├───nodetypes
    │ └───privileges
    ├───version
    │ └───db
    └───workspaces
        ├───category
        │ └───db
        ├───config
        │ └───db
        ├───...
        └───workflow
            └───db
    ├───repository.xml

Content:

<backup folder>

`<backup folder>`
`respository`	Subfolders containing datastore and configuration files necessary to restore the repositories.
`version`	Versions database. Contains versions of all versionable content from all repositories.
`workspaces`	One folder per workspace. Holds all content of given workspace.
`repository.xml`	Repository configuration file.

respository

Subfolders containing datastore and configuration files necessary to restore the repositories.

version

Versions database. Contains versions of all versionable content from all repositories.

workspaces

One folder per workspace. Holds all content of given workspace.

repository.xml

Repository configuration file.

Backup files contain confidential information on how to connect to the database. Keep your backup files in a secure location.

Scheduling automatic backups

To schedule an automatic backup:

In Automatic backup set the time, frequency, date and target directory
Click Schedule backup.

The tool registers an automatic backup task in the module configuration in /modules/backup/config.

Property Description

Property	Description
`config`	optional Module configuration node.
`tasks`	optional Tasks folder.
`backupTasks`	required Name of task.
`automatedExecution`	required Automated execution node.
`cron`	required CRON expression that sets the scheduled execution time.
`enabled`	optional, default is `false` Enables and disables the task.
`class`	required AutomatedBackupConfiguration is the bean that holds the backup configuration.
`name`	required Task name.
`targetPath`	required Path to the backup directory. The path must be absolute. Automatic backups include a timestamp in the backup folder.

config

optional

Module configuration node.

tasks

optional

Tasks folder.

backupTasks

required

Name of task.

automatedExecution

required

Automated execution node.

cron

required

CRON expression that sets the scheduled execution time.

enabled

optional, default is false

Enables and disables the task.

class

required

AutomatedBackupConfiguration is the bean that holds the backup configuration.

name

required

Task name.

targetPath

required

Path to the backup directory. The path must be absolute.

Automatic backups include a timestamp in the backup folder.

Viewing existing tasks

You can view and delete scheduled automatic backups in Existing tasks.

Backup script

The backup script provides more flexibility for backing up Magnolia. Options include backing up a single workspace or file, and running a backup from a running Magnolia instance. The backup script is in the bin folder in the Backup module bundle and needs to be run in a CLI.

If choose to use the script, make sure that library versions referenced by the script after the update are the same as the versions in Magnolia you are currently running.

Usage:

./bin/backup [options]

Short Long Description

-c <arg>

--configuration <arg>

required

Location of the repository configuration.

-r <arg>

--repository <arg>

required

Location of the repository to backup.

-t <arg>

--target <arg>

required

Target location for the backup.

-mr <arg>

--maxRetries <arg>

optional

Maximum number of retries when encountering an exception.

-rt <arg>

--retryTimeout <arg>

optional

Interval in seconds for retrying backup execution when an exception occurs.

-u <context> <username:password>

--user <context> <username:password>

optional

Context, username and password. Used for launching a backup from a running Magnolia instance
with a given username, password and host URL.

This option only works if the user has been assigned the the rest-backup role.
See Backup REST service for more.

-z

--zip

optional

Create a compressed ZIP archive.

-zp <arg>

--zipPath <arg>

required when -z is used (WARNING: Magnolia 5.6.2+)

The location for a zip backup archive. The argument should be a file with a path to it.

The path provided needs to be absolute in the context of the backup module, e.g. -z -zp /tmp/magnolia-backup.zip.

Example: Launching a backup from a running Magnolia instance.

./bin/backup -t /tmp/backup/backup-some/01 -r /Users/Name/Workspace/dev-project/magnolia-dev-webapp/target/magnolia-dev-webapp-1.0/repositories/magnolia -c /Users/Name/Workspace/dev-project/magnolia-dev-webapp/target/magnolia-dev-webapp-1.0/WEB-INF/config/repo-conf/jackrabbit-bundle-mysql-search.xml -u http://localhost:8080 superuser:superuser

Although it is possible to backup from a running Magnolia instance, it is not a recommended best practice. To ensure stability and prevent potential inconsistencies caused by nodes being published (versioned) during the backup process, avoid this option if possible. See Backup REST service for more.

Restoring a backup

To restore the previously backed up data, use the restore script in the bin folder in the Backup module bundle. The restore script needs to be run in a CLI.

The restore script is meant to recreate an instance, not to patch an existing one. For it to work correctly you should clean your database schema before running it.

Run the script before starting Magnolia so that the script can re-create the repository.

To make sure the webapp directory is properly setup before running the restore script, we recommend you take the WAR file or webapp from the bundle, add all your custom modules, startup the server once and perform the installation. Perform a backup of this new instance. After that, shutdown the server, delete the repositories directory and run the restore as specified below.

Usage:

/restore [options]

Short Long Description

Short	Long	Description
`-c`	`--configuration <arg>`	required Location of the repository configuration. `magnolia.repositories.jackrabbit.config` property.
`-r`	`--repository <arg>`	required Location of the repository to restore. `magnolia.repositories.home` property followed by the repository name (default: magnolia).
`-s`	`--source <arg>`	required Source location of the backup.
`-z`	`--zip`	optional Restore from a compressed ZIP archive.

-c

--configuration <arg>

required

Location of the repository configuration.

magnolia.repositories.jackrabbit.config property.

-r

--repository <arg>

required

Location of the repository to restore.

magnolia.repositories.home property followed by the repository name (default: magnolia).

-s

--source <arg>

required

Source location of the backup.

-z

--zip

optional

Restore from a compressed ZIP archive.

Example:

./bin/restore -r /Users/Name/Workspace/dev-project/magnolia-dev-webapp/target/magnolia-dev-webapp-1.0/repositories/magnolia -s /magnoliaBackups/Sept2016/01 -c /Users/Name/Workspace/dev-project/magnolia-dev-webapp/target/magnolia-dev-webapp-1.0/WEB-INF/config/repo-config/jackrabbit-bundle-mysql-search.xml

Tips

Assign the restore script more memory by changing the EXTRA_JVM_ARGUMENTS variable in the script file. On a Linux server you need to grant the correct permissions to the script file in order to run it.
It is not necessary to reindex your repository when the restore script is done.

Best practice

For safety reasons, run the restore from time to time on a test system to verify the validity of the backup files. Depending on the amount of data changed over the time, perhaps do so every month or every quarter.

Database size

During restore all entries are reinserted into the database sequentially. This ensures that the restored database is not fragmented and is slightly smaller than the equivalent database before backup.

Changing persistence managers

You can use backup and restore to migrate data to another persistence manager and to another database. For example you can change from Derby to MySQL.

To change persistence managers use the -c <arg> (--configuration <arg>) option to point to the new database persistence manager configuration.

Example:

./bin/restore -c /Users/Name/Workspace/dev-project/magnolia-dev-webapp/target/magnolia-dev-webapp-1.0/WEB-INF/config/repo-config/jackrabbit-bundle-mysql-search.xml

Backup command

The backup command starts the backup execution process for both manual and automated requests.

The command is registered in /modules/backup/commands/backup/backup.

Property Description

Property	Description
`commands`	optional Commands folder.
`backup`	required Backup catalog.
`backup`	required Command name
`class`	required BackupCommand starts the backup execution process both manual and automated requests.
`repositoryPath`	required, default is `magnolia.repositories.home` property Location of the repository to back up.
`configurationPath`	required, default is `magnolia.repositories.jackrabbit.config` property Location of the repository configuration.
`backupLocation`	required Target location of the backup.
`compression`	optional, default is `false` When set to `true` backup is compressed in a ZIP archive.
`retryTimeout`	optional, default is `30` seconds Interval in seconds for retrying backup execution when an exception occurs.
`maxRetries`	optional, default is `3` Maximum number of retries when encountering an exception.

commands

optional

Commands folder.

backup

required

Backup catalog.

backup

required

Command name

class

required

BackupCommand starts the backup execution process both manual and automated requests.

repositoryPath

required, default is magnolia.repositories.home property

Location of the repository to back up.

configurationPath

required, default is magnolia.repositories.jackrabbit.config property

Location of the repository configuration.

backupLocation

required

Target location of the backup.

compression

optional, default is false

When set to true backup is compressed in a ZIP archive.

retryTimeout

optional, default is 30 seconds

Interval in seconds for retrying backup execution when an exception occurs.

maxRetries

optional, default is `3`

Maximum number of retries when encountering an exception.

Backup REST service

The backup command is executed with a REST call. This allows observation of the mgnlVersion workspace and prevents potential inconsistencies if a node is published (versioned) during the backup process. If an inconsistency is detected, the backup stops and retries 3 times (maxRetries default value). If the inconsistency persists the backup fails and this is logged to the user.

The backup command is enabled as a REST endpoint in the REST Services module in /modules/rest-services/rest-endpoints/commands/enabledCommands/backup.

Property Description

Property	Description
`enabledCommands`	required Enabled commands node.
`backup`	required Command node. Name is arbitrary.
`access`	required Access node.
`roles`	required Roles node.
`rest-backup`	required Role name. Grants the `rest-backup` role permission to execute the command. Property name is arbitrary but the value must be a valid role name.
`catalogName`	required Catalog where the command resides.
`commandName`	required Command definition name. The module adds the `rest-backup` role in the Security app. The role allows the execution of the `backup` command from a running Magnolia instance and has the following permissions:

enabledCommands

required

Enabled commands node.

backup

required

Command node. Name is arbitrary.

access

required

Access node.

roles

required

Roles node.

rest-backup

required

Role name. Grants the rest-backup role permission to execute the command. Property name is arbitrary but the value must be a valid role name.

catalogName

required

Catalog where the command resides.

commandName

required

Command definition name.

The module adds the rest-backup role in the Security app.

The role allows the execution of the backup command from a running Magnolia instance and has the following permissions:

Web access

Permission

Path

Get & Post

/.rest/commands/v2/backup/backup

you must use POST to send requests to the commands endpoint.

You have to define the backup command properties in the request body or predefine it in the backup command properties as described above.