Chapter 5. Preparing for data loss with IdM backups

IdM provides the ipa-backup utility to backup IdM data, and the ipa-restore utility to restore servers and data from those backups.


Red Hat recommends running backups as often as necessary on a hidden replica with all server roles installed, especially the Certificate Authority (CA) role if the environment uses the integrated IdM CA.

5.1. IdM Backup types

IdM provides two types of backups: a full-server backup, and a data-only backup.

Backup typeBackup contentsPerformed Online or OfflineSuitable for

Full-server backup

  • All server configuration files related to IdM
  • LDAP data in LDAP Data Interchange Format (LDIF)

Offline only. IdM services must be temporarily stopped.

Rebuilding an IdM deployment from scratch

Data-only backup

  • LDAP data in LDAP Data Interchange Format (LDIF)
  • Replication Changelog

Online or Offline.

Restoring IdM data to a state in the past

5.2. Backup File Conventions

By default, IdM stores backups in the /var/lib/ipa/backup/ directory, and the naming conventions for these subdirectories are:

  • Full-server backup: ipa-full-YEAR-MM-DD-HH-MM-SS in GMT time
  • Data-only backup: ipa-data-YEAR-MM-DD-HH-MM-SS in GMT time

Uninstalling an IdM server does not automatically remove any backup files.

5.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-backup command.

  • By default, ipa-backup runs 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 ipa-backup command

  • To create a full-server backup in offline mode, use the ipa-backup utility without additional options.

    [root@server ~]# ipa-backup
    Preparing backup on
    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 --data option.

    [root@server ~]# ipa-backup --data
  • To create a full-server backup that includes IdM log files, use the --logs option.

    [root@server ~]# ipa-backup --logs
  • To create a data-only backup while IdM services are running, specify both --data and --online options.

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

Verification Steps

  • 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

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

5.4.1. Creating a GPG2 key for encrypting IdM backups

The following procedure describes how to generate a GPG2 key for the ipa-backup utility.


  1. Install and configure the pinentry utility.

    [root@server ~]# dnf install pinentry
    [root@server ~]# mkdir ~/.gnupg -m 700
    [root@server ~]# echo "pinentry-program /usr/bin/pinentry-curses" >> ~/.gnupg/gpg-agent.conf
  2. Create a key-input file 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
    Expire-Date: 0
    %echo Finished creating standard key
  3. By default, GPG2 stores its keyring in the ~/.gnupg file. To use a custom keyring location, set the GNUPGHOME environment variable to a directory that is only accessible by root.

    [root@server ~]# export GNUPGHOME=/root/backup
    [root@server ~]# mkdir -p $GNUPGHOME -m 700
  4. Begin generating a new GPG2 key based on the contents of key-input.

    [root@server ~]# gpg2 --batch --gen-key key-input
    1. Enter a passphrase to protect the GPG2 key.

      │ Please enter the passphrase to                       │
      │ protect your new key                                 │
      │                                                      │
      │ Passphrase: SecretPassphrase42                       │
      │                                                      │
      │	 <OK>                             <Cancel>     │
    2. Confirm the correct passphrase by entering it again.

      │ Please re-enter this passphrase                      │
      │                                                      │
      │ Passphrase: SecretPassphrase42                       │
      │                                                      │
      │	 <OK>                             <Cancel>     │
    3. 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

Verification Steps

  • 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
    sec   rsa2048 2020-01-13 [SCEA]
    uid           [ultimate] IPA Backup (IPA Backup) <>

Additional resources

  • For more information on GPG encryption and its uses, see the GNU Privacy Guard website.

5.4.2. Creating a GPG2-encrypted IdM backup

The following procedure creates an IdM backup and encrypts it using a GPG2 key.



  • Create a GPG-encrypted backup by specifying the --gpg option.

    [root@server ~]# ipa-backup --gpg
    Preparing backup on
    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

Verification Steps

  • Ensure that the backup directory contains an encrypted archive with a .gpg file extension.

    [root@server ~]# ls /var/lib/ipa/backup/ipa-full-2020-01-13-14-38-00
    header  ipa-full.tar.gpg

Additional resources

5.5. Additional resources