Back up and restore a shared space

This topic describes how to back up a shared space, and how to restore it from backup.

Backup overview

You can back up a shared space and then restore it from backup within the original ALM Octane instance. For example, suppose you want to delete a large number of entities and verify that there are no unexpected results. You can back up your space, perform the deletion, and then restore the original data if you need to undo the action.

ALM Octane stores its information in the following components:

  • A relational database (either Oracle or SQL Server). This is where the most important system data are located. The relational database is the most important component of the backup.

  • Elasticsearch. Elasticsearch stores trend data, audit information, run history, and search information. Elasticsearch is a NoSQL database geared towards fast textual indexing and searching.

  • The repository folder on your file system. ALM Octane includes its own file system repository where attachments, manual scripts and other artifacts are kept. The default location for this folder is: 

    • Linux: /opt/octane/repo

    • Windows: C:\Program Files\octane\repo

To fully back up ALM Octane, you need to back up all of its components. We recommend that you store each backup in a separate location.

Note: Audit data is only saved in the Elasticsearch database . To preserve audit data, make sure to back up your Elasticsearch database. To improve performance, you can truncate the audit table.

Back to top

Backup frequency

Database systems such as Oracle and SQL Server usually support hot backup procedures and provide the ability to restore operations to the last second before the system crash. However, in ALM Octane, it is only possible to take a periodic snapshot of the Elasticsearch and ALM Octane repository, but not the relational database.

Therefore, how often you should back up is determined by the amount of down time your site can tolerate. If the amount of tolerated time is one day (meaning, the company is fine with the ability to restore the operation to the state of 24 hours ago), the suggested backup frequency could be defined as one day. If the amount of tolerated time is 12 hours, backups should run every 12 hours.

Example: ALM Octane operations on SaaS are backed up every 4 hours. In most cases, hot backups and dumps/snapshots should then be either moved to a separate location or put on removable media for storage.

In addition, follow these guidelines:

  • Back up each component as closely as possible, one after the other.

  • Back up ALM Octane during quiet times to minimize missing files, broken file associations, and time inconsistencies between the three components.

  • Back up all of the components before performing an upgrade. For details, see Periodic maintenance and recovery.

Tip: To back up the relational database, use the database's backup mechanism and save the resulting files and folders. Open files do not pose a problem during the backup, since most files are not locked by ALM Octane.

Backup order

When preparing to do a backup, consider the following:

  • Time may elapse as you back up each of these components. In terms of time difference tolerance, the time as specified in the relational database is used as the determining factor. When you restore ALM Octane, it is the data and timestamps stored in the relational database that users see. Keep this in mind when restoring.

  • If you backed up your relational database, added files, and only then backed up the repository, the files exist after restore, but ALM Octane will not see any associations to those files. As a result, they will eventually be deleted. 

    Conversely, if you backed up the repository, added files, and only then backed up the relational database, ALM Octane might report that you have some broken associations, as the files do not exist in the repository while ALM Octane tries to find them.

Recommended sequence

For best results, follow this the sequence for your backup:

  1. Always back up the database first. Use the database vendor's, or commercially-available, tools to perform a hot backup (such as Oracle RMAN). We recommend that you take a snapshot (dump) before performing any major operations on the database, such as an upgrade, data migration (such as from Agile Manager to ALM Octane), or massive import.

  2. Back up Elasticsearch after backing up the database. You can take a snapshot of the Elasticsearch indexes periodically using REST API commands from any programming language (for example, JavaScript). Kibana is an example of a tool recommended by Elasticsearch for issuing REST API commands.

    See https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-snapshots.html on the Elasticsearch site.

    To back up properly in a clustered Elasticsearch environment, attach shared storage to which snapshots from each node can be saved.

  3. Lastly, back up the ALM Octane repository. Make a complete backup using operating system capabilities (tar, zip) or commercially-available tools.

Back to top

Back up a shared space

This section describes how to back up a shared space with all of its data. This includes:

  • Backing up the database schema
  • Backing up the Elasticsearch index

  • Backing up the ALM Octane repository

Prepare to back up a shared space

Before you begin, collect the required space information.

  1. Get space information by issuing this SQL query against the site admin schema:

    SELECT sp_id, sp_logical_name, sp_mode, sp_schema_name, sp_version

    FROM shared_space

    WHERE sp_id = {SP_ID}

  2. Locate your repository (storage) path: CD /<repo path>/storage/sharedspaces/sp{SP_ID}

    • Linux: /opt/octane/repo

    • Windows: C:\Program Files\octane\repo

    Note:

  • The following example steps refer to the deployment of ALM Octane on Linux, but they can be adjusted to Windows folders as required.

Step 1: Back up the database schema

Use database tools to back up the schema. For example, with the Oracle expdb utility:

  • For Oracle: expdp <admin conn> schemas=< SP_SCHEMA_NAME > dumpfile=<dumpfile> directory=<directory>

    SP_SCHEMA_NAME is the value obtained in the preparation step above.

  • For SQL Server, see Full back up to disk to default location.

Step 2: Back up the Elasticsearch index

  1. Use a REST API client to get the relevant Elasticsearch index name:

    curl 'http://<elastic host>:9200/_cat/indices/mqm_<sp_logical_name>*'

    For Windows, download curl for Windows.

  2. Take a snapshot (backup) of the index. For details, see: Snapshot module.

    The general flow will be:

    1. Create a repository (if none exists).

    2. Back up the specific indexes.

    For example (after creating a repository):

    curl -XPUT "http://<elastic host>:9200/_snapshot/<repository_name>/<snapshot_name>?wait_for_completion=true&pretty" -H 'Content-Type: application/json' -d'

    {

    "indices": "mqm_<sp_logical_name>*",

    "ignore_unavailable": true,

    "include_global_state": false

    }

    }

    '

Step 3: Back up the ALM Octane repository

  1. Go to the repository directory in your ALM Octane installation directory.

  2. Locate the relevant subdirectory using this command:

    cd /<repo path>/storage/sharedspaces/sp{SP_ID}

  3. Create a zip file using this command: 

    tar cvzf {BACKUP_DIR}/sp{SP_ID}.trz

    For Windows use 7-Zip or another compression tool to compress the repository.

Back to top

Restore a shared space

To restore data backed up from a shared space you need to restore the shared space schema, restore the Elasticsearch snapshot, restore the ALM Octane repository, and activate the space.

The following table lists the steps you need tot take to prepare for the restore.

Action Steps
Disable the space

Since you will continue to use the shared space, do not delete it from the site admin console. Instead, disable the shared space.

  1. In ALM Octane site settings, access Site Admin > Spaces.

  2. Select your space (for example, default_shared_space).

  3. Click Deactivate Space.
Prepare the database

Connect to the database as an admin user:

  • For an Oracle Schema (user):

    Delete the user: Drop user <SP_SCHEMA_NAME> cascade;

  • For SQL Server:

    During restore there is an option to overwrite. If you do not overwrite, the database needs to be deleted. To delete the database, use Drop database <SP_SCHEMA_NAME>
Prepare Elasticsearch

Use the following command to close the Elasticsearch indexes:

curl -XPOST 'http://<elastic host>:9200/mqm_<sp_logical_name>*/close'

For Windows, download curl for Windows.

Step 1: Restore the shared space schema

  • For Oracle:

    1. Copy the dump file with space schema data to the new database server.

    2. Import the space schema data from backup using an Oracle utility.

    Example: impdp <admin conn> schemas=< SP_SCHEMA_NAME > dumpfile=<dumpfile> directory=<directory>

  • For SQL Server, see Restore a Database Backup.

    Example: RESTORE DATABASE < SP_SCHEMA_NAME > FROM DISK = N'<Path to .bak file>' WITH FILE = 1, NOUNLOAD, REPLACE, STATS = 5

Step 2: Restore the Elasticsearch snapshot

Use the guidelines from the Elasticsearch documentation to Restore a snapshot.

For example:

curl -XPOST "http://<elastic host>:9200/_snapshot/<repository_name>/<snapshot_name>/_restore?pretty" -H 'Content-Type: application/json' -d'

{

"indices": " mqm_<sp_logical_name>*",

"ignore_unavailable": true,

"include_global_state": false

}

'

Step 3: Restore the ALM Octane repository

  1. Go to the repo directory in your ALM Octane installation directory (default /opt/octane/repo/).

  2. Locate the relevant subdirectory using this command: cd storage/sharedspaces/sp{SP_ID}

  3. Delete all the contents of the directory before restoring: rm –fr *

  4. Restore the zip file using this command: tar xvzf {BACKUP_DIR}/sp{SP_ID}.trz

  5. For Windows use 7-Zip or another compression tool to restore the repository.

Step 4: Activate the space

  1. After all preparations are finished and data is restored, restart the ALM Octane service. If there is more than one node of ALM Octane, restart each node.

  2. After restart, activate the space:

    1. In site settings, access Site Admin > Spaces.

    2. Select your space (e.g., default_shared_space).

    3. Click Activate.

Back to top

Periodic maintenance and recovery

Having backup procedures in place allows for data integrity and completeness. Periodic maintenance includes upgrading to new versions of the product, including patches. This involves: 

  • Downloading the appropriate version build from OpenText Software Self-service Online.

  • Deploying the package.

  • Performing database upgrade steps.

Before upgrading to a new build or patch, make sure to:

  1. Back up the database.

  2. Back up (meaning, take a snapshot of) the Elasticsearch index.

  3. Back up the ALM Octane repository file system.

  4. Back up the ALM Octane configuration files located in <Repository folder>/conf/octane.conf.

Disaster recovery

ALM Octane can be deployed in a cluster to allow for uninterrupted operation. In fact, each component can be scaled out: 

  • Database and Elasticsearch, according to vendor instructions.

  • ALM Octane cluster guidelines can be found in the ALM Octane Installation Guide.

ALM Octane does not lose data at a time of crash, because data is kept in database. All asynchronous jobs are persistent.

Back to top

See also: