> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/installation/rpm/rpm-single-node/back-up-and-restore.md).

# Back up and restore

What to back up beyond the database, how to back it up, and how to restore.

A complete OpenIAM backup is more than the database. This page lists everything that matters, and gives a procedure for each part.

Do this before the deployment carries anything you would mind losing, and test a restore before you need one.

## What this covers, and how long it takes

<table><thead><tr><th width="144.39999389648438"></th><th></th></tr></thead><tbody><tr><td><strong>You get</strong></td><td>A backup you can restore a working deployment from</td></tr><tr><td><strong>Time</strong></td><td>30 minutes to set up; the run time depends on your data volume</td></tr><tr><td><strong>Hosts</strong></td><td>The platform host, and your database server</td></tr><tr><td><strong>Downtime</strong></td><td><strong>A short stop of the platform</strong>, for the consistent file copy in step 2. The database dump and the secret store snapshot need none</td></tr><tr><td><strong>Reversible</strong></td><td>Restoring replaces live data — always restore to a test host first</td></tr></tbody></table>

## What to back up

<table><thead><tr><th width="201">What</th><th width="242.5999755859375">Where</th><th>Why</th></tr></thead><tbody><tr><td><strong>The eight database schemas</strong></td><td>Your database server</td><td>The identity model, workflow state, audit records, campaigns</td></tr><tr><td><strong>Configuration</strong></td><td><code>/usr/local/openiam/conf/</code></td><td>Generated settings, scripts and templates for this deployment</td></tr><tr><td><strong>Deployment settings</strong></td><td><code>/usr/local/openiam/env.conf</code></td><td>The values the deployment was built with</td></tr><tr><td><strong>Secret store data</strong></td><td>Taken as a snapshot, not copied from disk — see step 3</td><td>Where the secret store keeps every credential the platform uses</td></tr><tr><td><strong>Secret store certificates and unseal material</strong></td><td><code>/usr/local/openiam/vault/</code></td><td>The certificates services authenticate with, and the keys that open the store</td></tr><tr><td><strong>Service and connector binaries</strong></td><td><code>/usr/local/openiam/services/bin/</code>, <code>/usr/local/openiam/connectors/bin/</code></td><td>The exact build in use, including any connectors you added</td></tr><tr><td><strong>Search indexes</strong></td><td>Not backed up</td><td>Rebuilt from the database after a restore. Rebuilding is a console operation covered in the <a href="/administration-guide/admin.md">Administration Guide</a>, and takes longer on a large population than the rest of the restore</td></tr></tbody></table>

**The secret store is the part people miss.** A database restore without it leaves a deployment that starts and cannot authenticate to anything.

## Before you start

* A working deployment — [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md) passing.
* **Somewhere to put the backup that is not this host.** A backup on the host it protects is not a backup.
* Access to the database with an account able to read every schema.
* A change window for the short platform stop in step 2, if your deployment is in use.

## Set these first

{% code overflow="wrap" %}

```bash
export DB_HOST=<your database server>
export DB_ADMIN=<an administrative database account>
export BACKUP_DIR=/var/backups/openiam
export STAMP=$(date +%F)
export SCHEMAS="openiam activiti groovy auditlog batchtasks pbac certification privacy"
mkdir -p "$BACKUP_DIR"
```

{% endcode %}

**Set `STAMP` once per backup run** so the database dump, the file archive and the secret store snapshot carry the same date and are restored as a set.

***

## Back up

### 1. The database

All eight schemas, in one consistent set:

{% code overflow="wrap" %}

```bash
# MySQL or MariaDB
for db in $SCHEMAS; do
  mysqldump -h $DB_HOST -u $DB_ADMIN -p \
            --single-transaction --routines --triggers "$db" \
            > "$BACKUP_DIR/openiam-${db}-$STAMP.sql"
done
```

{% endcode %}

{% code overflow="wrap" %}

```bash
# PostgreSQL
for db in $SCHEMAS; do
  pg_dump -h "$DB_HOST" -U "$DB_ADMIN" -Fc "$db" \
          > "$BACKUP_DIR/openiam-${db}-$STAMP.dump"
done
```

{% endcode %}

**On Microsoft SQL Server and Oracle, use your organisation's existing backup for that platform** — a native backup of all eight databases, taken as one consistent set. OpenIAM adds no requirement beyond that. The examples above are given for the two engines where a command-line dump is the usual route.

**What you should see:** eight files or eight databases in one backup set, none of them empty.

`--single-transaction` on MySQL and the custom format on PostgreSQL give a consistent snapshot without locking the database. On any engine, **the eight schemas must be captured as one set** — they are one logical dataset and a partial restore leaves the platform inconsistent.

### 2. The platform directory

Stop the platform first so nothing is written mid-copy:

{% code overflow="wrap" %}

```bash
openiam-cli stop
tar -czf "$BACKUP_DIR/openiam-files-$STAMP.tar.gz" \
    -C /usr/local/openiam \
    conf env.conf vault services/bin connectors/bin
openiam-cli start
```

{% endcode %}

**This is the only step that needs the platform stopped**, and it is usually under a minute. The database dump in step 1 and the secret store snapshot in step 3 both run against a live deployment.

**If you cannot take even that stop**, copy `conf/`, `env.conf` and `vault/` while running — they change rarely — and treat the database backup as the consistent point.

### 3. The secret store's data

The secret store keeps its data in its backend, not under `/usr/local/openiam`. Take a snapshot of it:

{% code overflow="wrap" %}

```bash
consul snapshot save "$BACKUP_DIR/openiam-secrets-$STAMP.snap"
```

{% endcode %}

**What you should see:** a file of a few hundred kilobytes. **Store it with the same care as the database** — it holds every credential the deployment uses.

### 4. Store it somewhere else

Copy all three artefacts off the host, to wherever your organisation keeps backups. A backup on the host it protects is not a backup.

***

## Restore

**Restore to a test host first.** Confirm the result, then decide about production.

### 1. Build a host to the same version

**Build it completely**, using [*Install*](/installation/rpm/rpm-single-node/install.md) through to a working deployment. The restore replaces this deployment's data, and it needs the infrastructure tiers, the service accounts and the platform's own initialisation already in place to replace data into.

Confirm it is healthy with [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md) before restoring anything. A restore onto a host that was never healthy tells you nothing about the backup.

### 2. Restore the database

{% code overflow="wrap" %}

```bash
# MySQL or MariaDB
for db in $SCHEMAS; do
  mysql -h "$DB_HOST" -u "$DB_ADMIN" -p "$db" < "$BACKUP_DIR/openiam-${db}-$STAMP.sql"
done
```

{% endcode %}

{% code overflow="wrap" %}

```bash
# PostgreSQL
for db in $SCHEMAS; do
  pg_restore -h "$DB_HOST" -U "$DB_ADMIN" -d "$db" --clean "$BACKUP_DIR/openiam-${db}-$STAMP.dump"
done
```

{% endcode %}

**Restore all eight together.** They are one logical dataset, and a partial restore leaves the platform inconsistent.

### 3. Restore the platform directory and the secret store

{% code overflow="wrap" %}

```bash
openiam-cli stop
tar -xzf "$BACKUP_DIR/openiam-files-$STAMP.tar.gz" -C /usr/local/openiam
chown -R openiam:openiam /usr/local/openiam
consul snapshot restore "$BACKUP_DIR/openiam-secrets-$STAMP.snap"
```

{% endcode %}

**Restore the secret store snapshot and the platform directory together.** The certificates under `vault/` and the data in the snapshot are one set — restoring one without the other leaves services unable to authenticate.

### 4. Start and verify

{% code overflow="wrap" %}

```bash
openiam-cli start
```

{% endcode %}

Then work through [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md) in full. Confirm you can sign in and that a managed system's **test connection** succeeds — that last check proves the secret store was restored correctly.

## Verify it

**A backup you have never restored is a hope, not a plan.** At least once:

1. Restore to a spare host by the procedure above.
2. Sign in to the console.
3. Confirm users, roles and managed systems are present.
4. Run a **test connection** on one managed system.

Then record how long it took. That number is your recovery time, and it is the one your business continuity plan needs.

## Three-node deployments

The same set applies, with three additions and one difference in where things live.

| What                                   | Where                                                   | Note                                                                                                                   |
| -------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **The shared directories**             | `/opt/nfs_share/openiam/` on the host that exports them | `conf`, `upload` and `vault/certs` are one copy shared by all three nodes — back them up once, from the exporting host |
| **The secret store's data**            | `consul snapshot save` from any node                    | The backend is clustered, so one snapshot covers the cluster                                                           |
| **The unseal material and root token** | Wherever you recorded them at the build                 | Not on the hosts, and not recoverable if lost. Keep them with your other break-glass credentials                       |
| **The database**                       | Your database server, or the Galera cluster             | On Galera, take the dump from one node — every node holds the same data                                                |

**Node-specific files are rebuildable.** The service binaries, the interface builds and each host's `env.conf` come back with a fresh install of the same version; the shared directories and the database are what carry the deployment.

**Restore order on a cluster:** build all three hosts to the same version, restore the shared directories on the exporting host, restore the secret store snapshot on one node, restore the database, then start the cluster with `cluster openiam-cli start`.

**Expected downtime for a restore** is the time to build the hosts plus the time to restore the database — the rest is minutes. Measure it once, as the single-node procedure describes, and record the number.

## Kubernetes deployments

The same five things have to be captured, with different mechanics — the deployment secret and the secret store's backend in place of the platform directory, and the provider's backup or a dump in place of a local one. [*Back up and restore*](/installation/kubernetes/back-up-and-restore.md) is the procedure, with the commands.

**A provider database backup does not protect the deployment.** It protects the database. Without the deployment secret and the secret store's data, a restored database is a set of tables the platform cannot read.

## If it goes wrong

| What you see                                       | What it means                                                                  | What to do                                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| A dump file is empty or very small                 | The account cannot read that schema                                            | Grant it read access to all eight and run again                                    |
| `consul snapshot save` fails                       | The secret store's backend is not reachable from this host                     | Confirm it is running before taking the backup — a backup without it is incomplete |
| The archive is missing `vault/`                    | The platform was running and the directory was in use                          | Take the stop in step 2, or copy that directory separately                         |
| A restore starts but sign-in fails                 | The secret store snapshot and the file archive are from different runs         | Restore a matched set — that is what `STAMP` is for                                |
| A restore succeeds but a managed system test fails | The secret store was not restored, or was restored from a different deployment | Confirm the snapshot came from this deployment                                     |
| The restore host has no `initialized` marker       | It was never built to completion                                               | Build it fully first — the restore replaces data, it does not create a deployment  |

## What this procedure does not cover

* **Your database server's own backup regime.** If it is managed by a database team or a cloud service, their schedule and retention apply — make sure all eight OpenIAM schemas are in scope.
* **The connected systems.** OpenIAM manages accounts in other systems; restoring OpenIAM to an earlier point does not roll those back.

## Related

* [*Use a remote database*](/installation/rpm/rpm-single-node/use-a-remote-database.md)
* [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md)
* [*Configure*](/installation/rpm/rpm-single-node/configure.md)

*Applies to OpenIAM 2026.8.1.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/installation/rpm/rpm-single-node/back-up-and-restore.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.