SupportConsoleDevelopersStart a trialContact

Chapter 12. Backups and Migration

12.1. Backing Up and Restoring the Red Hat Virtualization Manager

12.1.1. Backing up Red Hat Virtualization Manager - Overview

Use the engine-backup tool to take regular backups of the Red Hat Virtualization Manager. The tool backs up the engine database and configuration files into a single file and can be run without interrupting the ovirt-engine service.

12.1.2. Syntax for the engine-backup Command

The engine-backup command works in one of two basic modes: 

# engine-backup --mode=backup
# engine-backup --mode=restore

These two modes are further extended by a set of parameters that allow you to specify the scope of the backup and different credentials for the engine database. Run engine-backup --help for a full list of parameters and their function.

Basic Options

--mode
Specifies whether the command will perform a backup operation or a restore operation. Two options are available - backup, and restore. This is a required parameter.
--file
Specifies the path and name of a file into which backups are to be taken in backup mode, and the path and name of a file from which to read backup data in restore mode. This is a required parameter in both backup mode and restore mode.
--log
Specifies the path and name of a file into which logs of the backup or restore operation are to be written. This parameter is required in both backup mode and restore mode.
--scope

Specifies the scope of the backup or restore operation. There are four options: all, which backs up or restores all databases and configuration data; files, which backs up or restores only files on the system; db, which backs up or restores only the Manager database; and dwhdb, which backs up or restores only the Data Warehouse database. The default scope is all.

The --scope parameter can be specified multiple times in the same engine-backup command.

Manager Database Options

The following options are only available when using the engine-backup command in restore mode. The option syntax below applies to restoring the Manager database. The same options exist for restoring the Data Warehouse database. See engine-backup --help for the Data Warehouse option syntax.

--provision-db
Creates a PostgreSQL database for the Manager database backup to be restored to. This is a required parameter when restoring a backup on a remote host or fresh installation that does not have a PostgreSQL database already configured.
--change-db-credentials
Allows you to specify alternate credentials for restoring the Manager database using credentials other than those stored in the backup itself. See engine-backup --help for the additional parameters required by this parameter.
--restore-permissions or --no-restore-permissions

Restores (or does not restore) the permissions of database users. One of these parameters is required when restoring a backup.

Note

If a backup contains grants for extra database users, restoring the backup with the --restore-permissions and --provision-db (or --provision-dwh-db) options will create the extra users with random passwords. You must change these passwords manually if the extra users require access to the restored system. See https://access.redhat.com/articles/2686731.

12.1.3. Creating a Backup with the engine-backup Command

The Red Hat Virtualization Manager can be backed up using the engine-backup command while the Manager is active. Append one of the following options to --scope to specify which backup to perform:

  • all: A full backup of all databases and configuration files on the Manager
  • files: A backup of only the files on the system
  • db: A backup of only the Manager database
  • dwhdb: A backup of only the Data Warehouse database
Important

To restore a database to a fresh installation of Red Hat Virtualization Manager, a database backup alone is not sufficient; the Manager also requires access to the configuration files. Any backup that specifies a scope other than the default, all, must be accompanied by the files scope, or a filesystem backup.

Example Usage of the engine-backup Command

  1. Log on to the machine running the Red Hat Virtualization Manager.

  2. Create a backup:

    Example 12.1. Creating a Full Backup

    # engine-backup --scope=all --mode=backup --file=file_name --log=log_file_name

    Example 12.2. Creating a Manager Database Backup

    # engine-backup --scope=files --scope=db --mode=backup --file=file_name --log=log_file_name

    Replace the db option with dwhdb to back up the Data Warehouse database.

    A tar file containing a backup is created using the path and file name provided.

The tar files containing the backups can now be used to restore the environment.

12.1.4. Restoring a Backup with the engine-backup Command

Restoring a backup using the engine-backup command involves more steps than creating a backup does, depending on the restoration destination. For example, the engine-backup command can be used to restore backups to fresh installations of Red Hat Virtualization, on top of existing installations of Red Hat Virtualization, and using local or remote databases.

Important

Backups can only be restored to environments of the same major release as that of the backup. For example, a backup of a Red Hat Virtualization version 4.2 environment can only be restored to another Red Hat Virtualization version 4.2 environment. To view the version of Red Hat Virtualization contained in a backup file, unpack the backup file and read the value in the version file located in the root directory of the unpacked files.

12.1.5. Restoring a Backup to a Fresh Installation

The engine-backup command can be used to restore a backup to a fresh installation of the Red Hat Virtualization Manager. The following procedure must be performed on a machine on which the base operating system has been installed and the required packages for the Red Hat Virtualization Manager have been installed, but the engine-setup command has not yet been run. This procedure assumes that the backup file or files can be accessed from the machine on which the backup is to be restored.

Restoring a Backup to a Fresh Installation

  1. Log on to the Manager machine. If you are restoring the engine database to a remote host, you will need to log on to and perform the relevant actions on that host. Likewise, if also restoring the Data Warehouse to a remote host, you will need to log on to and perform the relevant actions on that host.

  2. Restore a complete backup or a database-only backup.

    • Restore a complete backup: 

      # engine-backup --mode=restore --file=file_name --log=log_file_name --provision-db --restore-permissions

      If Data Warehouse is also being restored as part of the complete backup, provision the additional database: 

      engine-backup --mode=restore --file=file_name --log=log_file_name --provision-db --provision-dwh-db --restore-permissions

    • Restore a database-only backup by restoring the configuration files and database backup: 

      # engine-backup --mode=restore --scope=files --scope=db --file=file_name --log=log_file_name --provision-db --restore-permissions

      The example above restores a backup of the Manager database. 

      # engine-backup --mode=restore --scope=files --scope=dwhdb --file=file_name --log=log_file_name --provision-dwh-db --restore-permissions

      The example above restores a backup of the Data Warehouse database.

      If successful, the following output displays: 

      You should now run engine-setup.
Done.

  3. Run the following command and follow the prompts to configure the restored Manager: 

    # engine-setup

The Red Hat Virtualization Manager has been restored to the version preserved in the backup. To change the fully qualified domain name of the new Red Hat Virtualization system, see Section 18.1.1, “The oVirt Engine Rename Tool”.

12.1.6. Restoring a Backup to Overwrite an Existing Installation

The engine-backup command can restore a backup to a machine on which the Red Hat Virtualization Manager has already been installed and set up. This is useful when you have taken a backup up of an installation, performed changes on that installation, and then want to restore the installation from the backup.

Important

When restoring a backup to overwrite an existing installation, you must run the engine-cleanup command to clean up the existing installation before using the engine-backup command. Because the engine-cleanup command only cleans the engine database, and does not drop the database or delete the user that owns that database, you do not need to create a new database or specify the database credentials because the user and database already exist.

Restoring a Backup to Overwrite an Existing Installation

  1. Log on to the Red Hat Virtualization Manager machine.

  2. Remove the configuration files and clean the database associated with the Manager: 

    # engine-cleanup
  3. Restore a full backup or a database-only backup:

  4. Restore a full backup: 

    # engine-backup --mode=restore --file=file_name --log=log_file_name --restore-permissions

  5. Restore a database-only backup by restoring the configuration files and the database backup: 

    # engine-backup --mode=restore --scope=files --scope=db --file=file_name --log=log_file_name --restore-permissions

    The example above restores a backup of the Manager database. If necessary, also restore the Data Warehouse database: 

    # engine-backup --mode=restore --scope=dwhdb --file=file_name --log=log_file_name --restore-permissions

    If successful, the following output displays: 

    You should now run engine-setup.
Done.

  6. Run the following command and follow the prompts to reconfigure the firewall and ensure the ovirt-engine service is correctly configured: 

    # engine-setup

12.1.7. Restoring a Backup with Different Credentials

The engine-backup command can restore a backup to a machine on which the Red Hat Virtualization Manager has already been installed and set up, but the credentials of the database in the backup are different to those of the database on the machine on which the backup is to be restored. This is useful when you have taken a backup of an installation and want to restore the installation from the backup to a different system.

Important

When restoring a backup to overwrite an existing installation, you must run the engine-cleanup command to clean up the existing installation before using the engine-backup command. Because the engine-cleanup command only cleans the engine database, and does not drop the database or delete the user that owns that database, you do not need to create a new database or specify the database credentials because the user and database already exist. However, if the credentials for the owner of the engine database are not known, you must change them before you can restore the backup.

Restoring a Backup with Different Credentials

  1. Log on to the Red Hat Virtualization Manager machine.

  2. Run the following command and follow the prompts to remove the configuration files for and clean the database associated with the Manager: 

    # engine-cleanup

  3. Change the password for the owner of the engine database if the credentials of that user are not known:

    1. Enter the postgresql command line: 

      # su - postgres -c 'scl enable rh-postgresql95 -- psql'

    2. Change the password of the user that owns the engine database: 

      postgres=# alter role user_name encrypted password 'new_password';

      Repeat this for the user that owns the ovirt_engine_dwh database if necessary.

  4. Restore a complete backup or a database-only backup with the --change-db-credentials parameter to pass the credentials of the new database. The database_location for a database local to the Manager is localhost.

    Note

    The following examples use a --*password option for each database without specifying a password, which will prompt for a password for each database. Passwords can be supplied for these options in the command itself, however this is not recommended as the password will then be stored in the shell history. Alternatively, --*passfile=password_file options can be used for each database to securely pass the passwords to the engine-backup tool without the need for interactive prompts.

    • Restore a complete backup: 

      # engine-backup --mode=restore --file=file_name --log=log_file_name --change-db-credentials --db-host=database_location --db-name=database_name --db-user=engine --db-password --no-restore-permissions

      If Data Warehouse is also being restored as part of the complete backup, include the revised credentials for the additional database: 

      engine-backup --mode=restore --file=file_name --log=log_file_name --change-db-credentials --db-host=database_location --db-name=database_name --db-user=engine --db-password --change-dwh-db-credentials --dwh-db-host=database_location --dwh-db-name=database_name --dwh-db-user=ovirt_engine_history --dwh-db-password --no-restore-permissions

    • Restore a database-only backup by restoring the configuration files and the database backup: 

      # engine-backup --mode=restore --scope=files --scope=db --file=file_name --log=log_file_name --change-db-credentials --db-host=database_location --db-name=database_name --db-user=engine --db-password --no-restore-permissions

      The example above restores a backup of the Manager database. 

      # engine-backup --mode=restore --scope=files --scope=dwhdb --file=file_name --log=log_file_name --change-dwh-db-credentials --dwh-db-host=database_location --dwh-db-name=database_name --dwh-db-user=ovirt_engine_history --dwh-db-password --no-restore-permissions

      The example above restores a backup of the Data Warehouse database.

      If successful, the following output displays: 

      You should now run engine-setup.
Done.

  5. Run the following command and follow the prompts to reconfigure the firewall and ensure the ovirt-engine service is correctly configured: 

    # engine-setup

12.1.8. Migrating the Engine Database to a Remote Server Database

You can migrate the engine database to a remote database server after the Red Hat Virtualization Manager has been initially configured. Use engine-backup to create a database backup and restore it on the new database server. This procedure assumes that the new database server has Red Hat Enterprise Linux 7 installed and the appropriate subscriptions configured. See Enabling the Red Hat Virtualization Manager Repositories in the Installation Guide.

Migrating the Database

  1. Log in to the Red Hat Virtualization Manager machine and stop the ovirt-engine service so that it does not interfere with the engine backup: 

    # systemctl stop ovirt-engine.service

  2. Create the engine database backup: 

    # engine-backup --scope=files --scope=db --mode=backup --file=file_name --log=log_file_name

  3. Copy the backup file to the new database server: 

    # scp /tmp/engine.dump root@new.database.server.com:/tmp

  4. Log in to the new database server and install engine-backup: 

    # yum install ovirt-engine-tools-backup

  5. Restore the database on the new database server. file_name is the backup file copied from the Manager. 

    # engine-backup --mode=restore --scope=files --scope=db --file=file_name --log=log_file_name --provision-db --no-restore-permissions

  6. Now that the database has been migrated, start the ovirt-engine service: 

    # systemctl start ovirt-engine.service
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.