Chapter 7. Backing Up and Restoring IdM
Red Hat Enterprise Linux Identity Management provides a solution to manually back up and restore the IdM system. This may be necessary after a data loss event.
During backup, the system creates a directory containing information on your IdM setup and stores it. During restore, you can use this backup directory to bring your original IdM setup back.
The IdM backup and restore features are designed to help prevent data loss. To mitigate the impact of losing a server, and ensure continued operation by providing alternative servers to clients, ensure you have a replica topology according to Mitigating server loss with replication.
7.1. IdM Backup types
IdM provides two types of backups: a full-server backup, and a data-only backup.
|Backup type||Backup contents||Performed Online or Offline||Suitable for|
| || |
Offline only. IdM services must be temporarily stopped.
Rebuilding an IdM deployment from scratch
| || |
Online or Offline.
Restoring IdM data to a state in the past
7.2. Backup File Conventions
By default, IdM stores backups in the
/var/lib/ipa/backup/ directory, and the naming conventions for these subdirectories are:
ipa-full-YEAR-MM-DD-HH-MM-SSin GMT time
ipa-data-YEAR-MM-DD-HH-MM-SSin GMT time
Uninstalling an IdM server does not automatically remove any backup files.
7.3. Creating a Backup
This section describes how to create a full-server and data-only backup in offline and online modes using the
ipa-backupruns in offline mode, which will stop all IdM services. The services will start automatically after the backup is finished.
- A full-server backup must always run with IdM services offline, but a data-only backup may be performed with services online.
By default, backups are created on the file system containing the
/var/lib/ipa/backup/directory. We recommend creating backups regularly on a file system separate from the production filesystem used by IdM, and archiving the backups to a fixed medium (tape or optical storage, for example).
- Consider performing backups on hidden replicas. IdM services can be shut down on hidden replicas without affecting IdM clients.
An IdM backup of a server only captures the server roles installed on that server.
For example, if your IdM deployment uses the integrated Certificate Authority (CA), a backup of a non-CA replica will not capture CA data. Similarly, a backup of a replica that does not have the KRA installed will not capture KRA data.
- If the IdM deployment uses the built-in CA, a backup from a CA-less replica will not be enough to rebuild the IdM deployment. Please make sure to create backups on a replica with all of the in-use IdM server roles installed: CA, KRA, DNS.
Examples of using the
To create a full-server backup in offline mode, use the
ipa-backuputility without additional options.
[root@server ~]# ipa-backup Preparing backup on server.example.com Stopping IPA services Backing up ipaca in EXAMPLE-COM to LDIF Backing up userRoot in EXAMPLE-COM to LDIF Backing up EXAMPLE-COM Backing up files Starting IPA service Backed up to /var/lib/ipa/backup/ipa-full-2020-01-14-11-26-06 The ipa-backup command was successful
To create an offline data-only backup, specify the
[root@server ~]# ipa-backup --data
To create a full-server backup that includes IdM log files, use the
[root@server ~]# ipa-backup --logs
To create a data-only backup while IdM services are running, specify both
[root@server ~]# ipa-backup --data --online
If the backup fails due to insufficient space in the
/tmp directory, use the
TMPDIR environment variable to change the destination for temporary files created by the backup process:
[root@server ~]# TMPDIR=/new/location ipa-backup
For more details, see ipa-backup Command Fails to Finish.
The backup directory contains an archive with the backup.
[root@server ~]# ls /var/lib/ipa/backup/ipa-full-2020-01-14-11-26-06 header ipa-full.tar
7.4. Creating encrypted IdM backups
You can create encrypted backups using GNU Privacy Guard (GPG) encryption. To create encrypted IdM backups, you will first need to create a GPG2 key.
7.4.1. Creating a GPG2 key for encrypting IdM backups
The following procedure describes how to generate a GPG2 key for the
Install and configure the
[root@server ~]# dnf install pinentry [root@server ~]# mkdir ~/.gnupg -m 700 [root@server ~]# echo "pinentry-program /usr/bin/pinentry-curses" >> ~/.gnupg/gpg-agent.conf
key-inputfile used for generating a GPG keypair with your preferred details. For example:
[root@server ~]# cat >key-input <<EOF %echo Generating a standard key Key-Type: RSA Key-Length: 2048 Name-Real: IPA Backup Name-Comment: IPA Backup Name-Email: email@example.com Expire-Date: 0 %commit %echo Finished creating standard key EOF
By default, GPG2 stores its keyring in the
~/.gnupgfile. To use a custom keyring location, set the
GNUPGHOMEenvironment variable to a directory that is only accessible by root.
[root@server ~]# export GNUPGHOME=/root/backup [root@server ~]# mkdir -p $GNUPGHOME -m 700
Begin generating a new GPG2 key based on the contents of
[root@server ~]# gpg2 --batch --gen-key key-input
Enter a passphrase to protect the GPG2 key.
┌──────────────────────────────────────────────────────┐ │ Please enter the passphrase to │ │ protect your new key │ │ │ │ Passphrase: SecretPassphrase42 │ │ │ │ <OK> <Cancel> │ └──────────────────────────────────────────────────────┘
Confirm the correct passphrase by entering it again.
┌──────────────────────────────────────────────────────┐ │ Please re-enter this passphrase │ │ │ │ Passphrase: SecretPassphrase42 │ │ │ │ <OK> <Cancel> │ └──────────────────────────────────────────────────────┘
The new GPG2 key is now created.
gpg: keybox '/root/backup/pubring.kbx' created gpg: Generating a standard key gpg: /root/backup/trustdb.gpg: trustdb created gpg: key BF28FFA302EF4557 marked as ultimately trusted gpg: directory '/root/backup/openpgp-revocs.d' created gpg: revocation certificate stored as '/root/backup/openpgp-revocs.d/8F6FCF10C80359D5A05AED67BF28FFA302EF4557.rev' gpg: Finished creating standard key
List the GPG keys on the server.
[root@server ~]# gpg2 --list-secret-keys gpg: checking the trustdb gpg: marginals needed: 3 completes needed: 1 trust model: pgp gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u /root/backup/pubring.kbx ------------------------ sec rsa2048 2020-01-13 [SCEA] 8F6FCF10C80359D5A05AED67BF28FFA302EF4557 uid [ultimate] IPA Backup (IPA Backup) <firstname.lastname@example.org>
- For more information on GPG encryption and its uses, see the GNU Privacy Guard website.
7.4.2. Creating a GPG2-encrypted IdM backup
The following procedure creates an IdM backup and encrypts it using a GPG2 key.
- You have created a GPG2 key. See Creating a GPG2 key for encrypting IdM backups.
Create a GPG-encrypted backup by specifying the
[root@server ~]# ipa-backup --gpg Preparing backup on server.example.com Stopping IPA services Backing up ipaca in EXAMPLE-COM to LDIF Backing up userRoot in EXAMPLE-COM to LDIF Backing up EXAMPLE-COM Backing up files Starting IPA service Encrypting /var/lib/ipa/backup/ipa-full-2020-01-13-14-38-00/ipa-full.tar Backed up to /var/lib/ipa/backup/ipa-full-2020-01-13-14-38-00 The ipa-backup command was successful
Ensure that the backup directory contains an encrypted archive with a
[root@server ~]# ls /var/lib/ipa/backup/ipa-full-2020-01-13-14-38-00 header ipa-full.tar.gpg
- For general information on creating a backup, see Creating a backup.
7.5. When to restore from an IdM backup
You can respond to several disaster scenarios by restoring from an IdM backup:
- Undesirable changes were made to the LDAP content: Entries were modified or deleted, replication carried out those changes throughout the deployment, and you want to revert those changes. Restoring a data-only backup returns the LDAP entries to the previous state without affecting the IdM configuration itself.
- Total Infrastructure Loss, or loss of all CA instances: If a disaster damages all Certificate Authority replicas, the deployment has lost the ability to rebuild itself by deploying additional servers. In this situation, restore a backup of a CA Replica and build new replicas from it.
An upgrade on an isolated server failed: The operating system remains functional, but the IdM data is corrupted, which is why you want to restore the IdM system to a known good state. Red Hat recommends working with Technical Support in order to diagnose and troubleshoot the issue. If those efforts fail, restore from a full-server backup.Important
The preferred solution for hardware or upgrade failure is to rebuild the lost server from a replica. For more information, see Recovering from server loss with replication.
7.6. Considerations when restoring from an IdM backup
If you have a backup created with the
ipa-backup utility, you can restore your IdM server or the LDAP content to the state they were in when the backup was performed.
The following are the key considerations while restoring from an IdM backup:
You can only restore a backup on a server that matches the configuration of server where the backup was originally created. The server must have:
- The same hostname
- The same IP address
- The same version of IdM software
- If one IdM server in a multi-master environment is restored, the restored server becomes the only source of information for IdM. All other master servers must be re-initialized from the restored server.
- Since any data created after the last backup will be lost, do not use the backup and restore solution for normal system maintenance.
- If a server is lost, Red Hat recommends rebuilding the server by reinstalling it as a replica instead of restoring from a backup. Creating a new replica preserves data from the current working environment. For more information, see Preparing for server loss with replication.
- The backup and restore features can only be managed from the command line and are not available in the IdM web UI.
Restoring from a backup requires the same software (RPM) versions on the target host as were installed when the backup was performed. Due to this, Red Hat recommends restoring from a Virtual Machine snapshot rather than a backup. For more information, see Recovering from data loss with VM snapshots.
7.7. Restoring an IdM server from a backup
The following procedure describes restoring an IdM server, or its LDAP data, from an IdM backup.
Figure 7.1. Replication Topology used in this example
Table 7.1. Server naming conventions used in this example
| || |
The server that needs to be restored from backup
| || |
A Certificate Authority (CA) replica connected to master1.example.com.
| || |
A replica connected to caReplica2.example.com.
ipa-restoreutility to restore a full-server or data-only backup.
If the backup directory is in the default
/var/lib/ipa/backup/location, enter only the name of the directory:
[root@master1 ~]# ipa-restore ipa-full-2020-01-14-12-02-32
If the backup directory is not in the default location, enter its full path:
[root@master1 ~]# ipa-restore /mybackups/ipa-data-2020-02-01-05-30-00Note
ipa-restoreutility automatically detects the type of backup that the directory contains, and performs the same type of restore by default. To perform a data-only restore from a full-server backup, add the
[root@master1 ~]# ipa-restore --data ipa-full-2020-01-14-12-02-32
Enter the Directory Manager password.
Directory Manager (existing master) password:
yesto confirm overwriting current data with the backup.
Preparing restore from /var/lib/ipa/backup/ipa-full-2020-01-14-12-02-32 on master1.example.com Performing FULL restore from FULL backup Temporary setting umask to 022 Restoring data will overwrite existing live data. Continue to restore? [no]: yes
ipa-restoreutility disables replication on all servers that are available:
Each master will individually need to be re-initialized or re-created from this one. The replication agreements on masters running IPA 3.1 or earlier will need to be manually re-enabled. See the man page for details. Disabling all replication. Disabling replication agreement on master1.example.com to caReplica2.example.com Disabling CA replication agreement on master1.example.com to caReplica2.example.com Disabling replication agreement on caReplica2.example.com to master1.example.com Disabling replication agreement on caReplica2.example.com to replica3.example.com Disabling CA replication agreement on caReplica2.example.com to master1.example.com Disabling replication agreement on replica3.example.com to caReplica2.example.com
The utility then stops IdM services, restores the backup, and restarts the services:
Stopping IPA services Systemwide CA database updated. Restoring files Systemwide CA database updated. Restoring from userRoot in EXAMPLE-COM Restoring from ipaca in EXAMPLE-COM Restarting GSS-proxy Starting IPA services Restarting SSSD Restarting oddjobd Restoring umask to 18 The ipa-restore command was successful
Re-initialize all replicas connected to the restored server:
List all replication topology segments for the
domainsuffix, taking note of topology segments involving the restored server.
[root@master1 ~]# ipa topologysegment-find domain ------------------ 2 segments matched ------------------ Segment name: master1.example.com-to-caReplica2.example.com Left node: master1.example.com Right node: caReplica2.example.com Connectivity: both Segment name: caReplica2.example.com-to-replica3.example.com Left node: caReplica2.example.com Right node: replica3.example.com Connectivity: both ---------------------------- Number of entries returned 2 ----------------------------
domainsuffix for all topology segments with the restored server.
In this example, perform a re-initialization of
caReplica2with data from
[root@caReplica2 ~]# ipa-replica-manage re-initialize --from=master1.example.com Update in progress, 2 seconds elapsed Update succeeded
Moving on to Certificate Authority data, list all replication topology segments for the
[root@master1 ~]# ipa topologysegment-find ca ----------------- 1 segment matched ----------------- Segment name: master1.example.com-to-caReplica2.example.com Left node: master1.example.com Right node: caReplica2.example.com Connectivity: both ---------------------------- Number of entries returned 1 ----------------------------
Re-initialize all CA replicas connected to the restored server.
In this example, perform a
caReplica2with data from
[root@caReplica2 ~]# ipa-csreplica-manage re-initialize --from=master1.example.com Directory Manager password: Update in progress, 3 seconds elapsed Update succeeded
Continue moving outward through the replication topology, re-initializing successive replicas, until all servers have been updated with the data from restored server
In this example, we only have to re-initialize the
replica3with the data from
[root@replica3 ~]# ipa-replica-manage re-initialize --from=caReplica2.example.com Directory Manager password: Update in progress, 3 seconds elapsed Update succeeded
Clear SSSD’s cache on every server in order to avoid authentication problems due to invalid data:
Stop the SSSD service:
[root@server ~]# systemctl stop sssd
Remove all cached content from SSSD:
[root@server ~]# sss_cache -E
Start the SSSD service:
[root@server ~]# systemctl start sssd
- Reboot the server.
- The ipa-restore(1) man page also covers in detail how to handle complex replication scenarios during restoration.
7.8. Restoring from an encrypted backup
ipa-restore utility automatically detects if an IdM backup is encrypted, and restores it using the GPG2 root keyring and
gpg-agent by default.
- A GPG-encrypted IdM backup. See Creating encrypted IdM backups.
- The LDAP Directory Manager password
Passphraseused when creating the GPG key
If you used a custom keyring location when creating the GPG2 keys, make sure that the
$GNUPGHOMEenvironment variable is set to that directory. See Creating a GPG2 key for encrypting IdM backups.
[root@server ~]# echo $GNUPGHOME /root/backup
ipa-restoreutility with the backup directory location.
[root@server ~]# ipa-restore ipa-full-2020-01-13-18-30-54
Enter the Directory Manager password.
Directory Manager (existing master) password:
Passphraseyou used when creating the GPG key.
┌────────────────────────────────────────────────────────────────┐ │ Please enter the passphrase to unlock the OpenPGP secret key: │ │ "IPA Backup (IPA Backup) <email@example.com>" │ │ 2048-bit RSA key, ID BF28FFA302EF4557, │ │ created 2020-01-13. │ │ │ │ │ │ Passphrase: SecretPassPhrase42 │ │ │ │ <OK> <Cancel> │ └────────────────────────────────────────────────────────────────┘
- Re-initialize all replicas connected to the restored server. See Restoring an IdM server from backup.