Back up and restore a space

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

Backup overview

You can back up a space and then restore it from backup within the original 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.

Information is stored in the following components.

Component Description
Relational database (either Oracle or SQL Server)

The 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.

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.

Repository folder

OpenText Software Delivery Management 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 OpenText Software Delivery Management, you need to back up all of its components. We recommend that you store each backup in a separate location.

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 OpenText Software Delivery Management, it is only possible to take a periodic snapshot of Elasticsearch and the 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: OpenText Software Delivery Management 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 OpenText Software Delivery Management 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 OpenText Software Delivery Management.

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 OpenText Software Delivery Management, 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 OpenText Software Delivery Management does 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, OpenText Software Delivery Management might report that you have some broken associations, as the files do not exist in the repository while OpenText Software Delivery Management tries to find them.

Recommended sequence

For best results, follow this sequence for your backup:

  1. Database. 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 OpenText Software Delivery Management), or massive import.

  2. Elasticsearch. 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.

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

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

Back to top

Back up a space

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

Prepare to back up a space

Before you begin, collect the required space information.

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

    Copy code
    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 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:

    Copy code
    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: Refer to the product documentation for details.

Step 2: Back up the Elasticsearch index

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

    Copy code
    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. Refer to the product documentation for details.

    The general flow is:

    1. Create a repository, if none exists.

    2. Back up the specific indexes.

    Copy code
    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 repository

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

  2. Locate the relevant sub-directory using this command:

    Copy code
    cd /<repo path>/storage/sharedspaces/sp{SP_ID}
  3. Create a zip file using this command:

    Copy code
    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 space

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

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

Action Steps
Deactivate the space

Because you continue to use the space, do not delete it from the site admin console. Instead, deactivate the space.

  1. In OpenText Software Delivery Management 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 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.

    Copy code
    Example: Restore space schema for Oracle
    impdp <admin conn> schemas=< SP_SCHEMA_NAME > dumpfile=<dumpfile> directory=<directory>
  • For SQL Server: Refer to the product documentation for details.

    Copy code
    Example: Restore space schema for SQL Server
    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

For details on restoring the Elasticsearch snapshot, refer to the product documentation.

Copy code

Example: Restore the Elasticsearch snapshot

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 repository

  1. Go to the repo directory in your installation directory. The default is /opt/octane/repo/.

  2. Locate the relevant sub-directory using this command:

    Copy code
    cd storage/sharedspaces/sp{SP_ID}
  3. Delete all the contents of the directory before restoring:

    Copy code
    rm –fr *
  4. Restore the zip file using this command:

    Copy code
    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 OpenText Software Delivery Management service. If there is more than one node, restart each node.

  2. After restart, activate the space:

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

    2. Select your space. For example, 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 the Elasticsearch index (this means, taking a snapshot of it).

  3. Back up the repository file system.

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

Disaster recovery

OpenText Software Delivery Management can be deployed in a cluster to allow for uninterrupted operation. Each component can be scaled out as follows: 

  • Database and Elasticsearch, according to vendor instructions.

  • Cluster guidelines can be found in the OpenText Software Delivery Management Installation Guide.

OpenText Software Delivery Management does not lose data at a time of crash, because data is kept in the database. All asynchronous jobs are persistent.

Back to top

See also: