Backup module

Content management Bundled: Extension

Edition

DX Core

License

MLA

Issues

MGNLBACKUP

Maven site

Backup

Latest

2.5.1

The Backup module allows you to create manual and automatic content and configuration data backups. The module backs up the configuration of the respective Magnolia instance on which it runs and all versions of content stored in all its workspaces.

You can manage both manual and automatic backups in the Backup app. Scripts can back up and restore content and configuration data flexibly by specifying various backup and restore options.

Using the Backup module should mainly be reserved for specific cases such as cross-platform dumps and small databases. A cross-platform dump might be backing up on a Jackrabbit configuration and restoring on possibly another Jackrabbit configuration.

For production environments, we recommend you use both database tools and file system copies (the contents of any file stored and optionally Lucene indexes) to have consistent and transaction-safe backups.

Most of your content is stored in a database, and you can use database tools to back up and restore your JCR content. However, some high-level steps to remember when backing up your content are outlined here.

Backup app

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.5.1</version> (1)
</dependency>

1	Should you need to specify the module version, do it using `<version>`.

Backup app

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

Creating manual backups

To create a manual backup:

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

Manual backup

Below is the structure of a backup folder once a backup is created.

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

The following table explains the backup folder contents.

<backup folder>

respository

Subfolders containing data store and configuration files necessary to restore the repositories.

version

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

workspaces

One folder per workspace. Holds all content of a 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:

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

Automatic backup

Automatic backup tasks are registered in /modules/backup/config.

Backup module configuration

Property Description

Property	Description
`config`	optional Module configuration node.
`tasks`	optional Tasks folder.
`backupTasks`	required Task configuration node.
`automatedExecution`	required Automatic execution node.
`cron`	required CRON expression that sets the scheduled execution time.
`enabled`	optional, default is `false` Enables and disables the task.
`class`	required info.magnolia.module.backup.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

Task configuration node.

automatedExecution

required

Automatic execution node.

cron

required

CRON expression that sets the scheduled execution time.

enabled

optional, default is false

Enables and disables the task.

class

required

info.magnolia.module.backup.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.

Managing existing tasks

Under Existing tasks, you can view and delete scheduled automatic backups.

Existing tasks

`Backup` script

For backing up Magnolia, the backup script provides more flexibility and options, such as launching a backup from a running Magnolia instance.

The script is in the bin folder in the Backup module bundle and needs to be run in a CLI.

If you choose to use the script, make sure that the library versions in the target webapp after a restoration update are the same as those in the Magnolia instance you are currently running.

Usage:

./bin/backup [options]

Short Long Description

-c <arg>

--configuration <arg>

required

Location of the repository configuration.

By default, Derby is the database configured out of the box. Several configuration files are included in your installation’s apache-tomcat/webapps/magnoliaAuthor/WEB-INF/config/repo-conf folder. Make sure you specify the file that best fits your database, for example, jackrabbit-bundle-derby-search.xml for Derby.

-r <arg>

--repository <arg>

required

Location of the repository to back up.

-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 the backup 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 rest-backup role. See Backup REST service.

-z

--zip

optional

Creates a compressed ZIP archive.

-zp <arg>

--zipPath <arg>

required when -z is used

Location for a zip backup archive. The argument must be a file with a path.

The path must be absolute in the context of the Backup module (for example, -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-derby-search.xml -u http://localhost:8080 superuser:superuser

Although it’s possible to back up from a running Magnolia instance, it’s not recommended as a 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.

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 re-create an instance, not to patch an existing one.

For it to work correctly, you need to:

Clean your database schema before running the script.
Run the script before starting Magnolia so that the script can recreate the repository.

To make sure the webapp directory is set up before running the restore script, we recommend you take the WAR file or webapp from the bundle, add all your custom modules, start up the server once and perform the installation. Create a backup of this new instance before shutting down the server, deleting the repositories directory and running 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 Restores 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

Restores 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

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 to run it.
It’s not necessary to reindex your repository when you run the restore script.

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 time, do this 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 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 execution of both manual and automatic backups.

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

Backup command

Property Description

Property	Description
`commands`	optional Commands folder.
`backup`	required Backup catalog.
`backup`	required Command name.
`class`	required info.magnolia.module.backup.commands.BackupCommand starts the execution of both manual and automatic backups.
`repositoryPath`	required, default is `magnolia.repositories.home` Location of the repository to back up.
`configurationPath`	required, default is `magnolia.repositories.jackrabbit.config` Location of the repository configuration.
`backupLocation`	required Target location for the backup.
`compression`	optional, default is `false` When `true`, the backup is compressed in a ZIP archive.
`retryTimeout`	optional, default is `30` Interval in seconds for retrying the backup 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

info.magnolia.module.backup.commands.BackupCommand starts the execution of both manual and automatic backups.

repositoryPath

required, default is magnolia.repositories.home

Location of the repository to back up.

configurationPath

required, default is magnolia.repositories.jackrabbit.config

Location of the repository configuration.

backupLocation

required

Target location for the backup.

compression

optional, default is false

When true, the backup is compressed in a ZIP archive.

retryTimeout

optional, default is 30

Interval in seconds for retrying the backup 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 will stop and retry 3 times (the default value for maxRetries). If the inconsistency persists, the backup will fail and this will be 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.

Backup REST

Property Description

Property	Description
`enabledCommands`	required Enabled commands node.
`backup`	required Command node. The 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. The 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.

enabledCommands

required

Enabled commands node.

backup

required

Command node. The 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. The 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 Backup module adds the rest-backup role to the Security app. The role allows the execution of the backup command from a running Magnolia instance and has the following web access permission:

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 as described above.

Issues

Ant: Malformed \uxxxx encoding in a propertyfile task

You may encounter the following error:

1) [Guice/ErrorInjectingConstructor]: IllegalArgumentException: Malformed \\uxxxx encoding.
  at DefaultMessageBundlesLoaderProvider.<init>(DefaultMessageBundlesLoaderProvider.java:50)
  while locating DefaultMessageBundlesLoaderProvider
  at GuiceComponentConfigurationModule.bindProvider(GuiceComponentConfigurationModule.java:187)
      \\_ installed by: Modules$OverrideModule -> Modules$OverrideModule -> GuiceComponentProviderBuilder$1 -> GuiceComponentConfigurationModule
  while locating DefaultMessageBundlesLoader

Debug to find the properties file which caused this error, enable it through the log4j2.xml.

<Logger name="info.magnolia.i18nsystem" level="DEBUG"/>

Solution

Use the correct classpath for SmartTomcat.
Follow java.lang.IllegalArgumentException: Malformed \uxxxx encoding while mvn install.

Feedback

DX Core

Backup module

Installing with Maven

Backup app

Creating manual backups

Scheduling automatic backups

Managing existing tasks

Backup script

Restoring a backup

Database size

Changing persistence managers

Backup command

Backup REST service

Issues

Ant: Malformed \uxxxx encoding in a propertyfile task

Location

Main doc sections

`Backup` script

`Backup` command