Chapter 12. Backups and Migration

12.1. Backing Up and Restoring the Red Hat Enterprise Virtualization Manager

12.1.1. Backing up Red Hat Enterprise Virtualization Manager - Overview

Use the engine-backup tool to take regular backups of the Red Hat Enterprise 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. You can specify additional options to modify the backup settings according to your requirements. Take time to plan your backups as the backup options used affects the options available when you need to restore an environment.

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.

Table 12.1. Basic Options

Option Description
--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 five 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; dwhdb, which backs up or restores only the Data Warehouse database; and reportsdb, which backs up or restores only the Reports database. The default scope is all. The --scope parameter can be specified multiple times in the same engine-backup command.

Table 12.2. Manager Database Options

Option Description
--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.

Table 12.3. Backup Options

Option Description
--fast-restore The default backup option used. Allows you to back up and restore a back up faster than the other available options. See engine-backup --help for more backup fine-tuning options.
--small-size Allows you to back up your database using the least amount of disk space. However, it will take more time to back up and restore compared to the --fast-restore option.

12.1.3. Creating a Backup with the engine-backup Command

The Red Hat Enterprise 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
  • reportsdb: A backup of only the Reports database

Important

To restore a database to a fresh installation of Red Hat Enterprise 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.

Procedure 12.1. Example Usage of the engine-backup Command

  1. Log on to the machine running the Red Hat Enterprise 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 or reportsdb to back up the Data Warehouse database or the Reports 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

While the process for restoring a backup using the engine-backup command is straightforward, it involves several additional steps in comparison to that for creating a backup depending on the destination to which the backup is to be restored. For example, the engine-backup command can be used to restore backups to fresh installations of Red Hat Enterprise Virtualization, on top of existing installations of Red Hat Enterprise 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 Enterprise Virtualization version 3.3 environment can only be restored to another Red Hat Enterprise Virtualization version 3.3 environment. To view the version of Red Hat Enterprise 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 Enterprise 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 Enterprise 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.

Procedure 12.2. Restoring a Backup to a Fresh Installation

  1. Log on to the machine on which the Red Hat Enterprise Virtualization Manager is installed. 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 Reports and 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 --no-restore-permissions
      If Reports and Data Warehouse are also being restored as part of the complete backup, provision the additional databases:
      engine-backup --mode=restore --file=file_name --log=log_file_name --provision-db --provision-reports-db --provision-dwh-db --no-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 --no-restore-permissions
      The example above restores a backup of the Manager database.
      # engine-backup --mode=restore --scope=files --scope=reportsdb --file=file_name --log=log_file_name --provision-reports-db --no-restore-permissions
      The example above restores a backup of the Reports database.
      # engine-backup --mode=restore --scope=files --scope=dwhdb --file=file_name --log=log_file_name --provision-dwh-db --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.
  3. Log on to the Manager machine. Run the following command and follow the prompts to configure the restored Manager:
    # engine-setup
The Red Hat Enterprise Virtualization Manager has been restored to the version preserved in the backup. To change the fully qualified domain name of the new Red Hat Enterprise Virtualization system, see Section 17.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 Enterprise 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.

Procedure 12.3. Restoring a Backup to Overwrite an Existing Installation

  1. Log on to the machine on which the Red Hat Enterprise Virtualization Manager is installed.
  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. Restore a full backup or a database-only backup:
    • Restore a full backup:
      # engine-backup --mode=restore --file=file_name --log=log_file_name
    • 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
      The example above restores a backup of the Manager database. If necessary, also restore the Reports and Data Warehouse databases:
      # engine-backup --mode=restore --scope=reportsdb --scope=dwhdb --file=file_name --log=log_file_name
    If successful, the following output displays:
    You should now run engine-setup.
    Done.
  4. Run the following command and follow the prompts to reconfigure the firewall and ensure the ovirt-engine service is correctly configured:
    # engine-setup
The engine database and configuration files for the Red Hat Enterprise Virtualization Manager have been restored to the version in the backup.

12.1.7. Restoring a Backup with Different Credentials

Summary

The engine-backup command can restore a backup to a machine on which the Red Hat Enterprise 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.

Procedure 12.4. Restoring a Backup with Different Credentials

  1. Log on to the machine on which the Red Hat Enterprise Virtualization Manager is installed.
  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
      $ 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 users that own the ovirt_engine_reports and ovirt_engine_dwh databases 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
      If Reports and Data Warehouse are also being restored as part of the complete backup, include the revised credentials for the two additional databases:
      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-reports-db-credentials --reports-db-host=database_location --reports-db-name=database_name --reports-db-user=ovirt_engine_reports --reports-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
      
    • 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
      The example above restores a backup of the Manager database.
      # engine-backup --mode=restore --scope=files --scope=reportsdb --file=file_name --log=log_file_name --change-reports-db-credentials --reports-db-host=database_location --reports-db-name=database_name --reports-db-user=ovirt_engine_reports --reports-db-password
      The example above restores a backup of the Reports 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
      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
Result

The engine database and configuration files for the Red Hat Enterprise Virtualization Manager have been restored to the version in the backup using the supplied credentials, and the Manager has been configured to use the new database.

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 Enterprise Virtualization Manager has been initially configured.
This task is split into two procedures. The first procedure, preparing the remote PostgreSQL database, is a necessary prerequisite for the migration itself and presumes that the server has Red Hat Enterprise Linux installed and has been configured with the appropriate subscriptions.
The second procedure, migrating the database, uses PostgreSQL pg_dump and pg_restore commands to handle the database backup and restore. As such, it is necessary to edit the /etc/ovirt-engine/engine.conf.d/10-setup-database.conf file with the updated information. At a minimum, you must update the location of the new database server. If the database name, role name, or password are modified for the new database server, these values must also be updated in the 10-setup-database.conf file. This procedure uses the default engine database settings to minimize modification of this file.

Procedure 12.5. Preparing the Remote PostgreSQL Database for use with the Red Hat Enterprise Virtualization Manager

  1. Log in to the remote database server and install the PostgreSQL server package:
    # yum install postgresql-server
  2. Initialize the PostgreSQL database, start the postgresql service, and ensure that this service starts on boot:
    # service postgresql initdb
    # service postgresql start
    # chkconfig postgresql on
  3. Connect to the psql command line interface as the postgres user:
    # su - postgres
    $ psql
  4. Create a user for the Manager to use when it writes to and reads from the database. The default user name on the Manager is engine:
    postgres=# create role user_name with login encrypted password 'password';

    Note

    The password for the engine user is located in plain text in /etc/ovirt-engine/engine.conf.d/10-setup-database.conf. Any password can be used when creating the role on the new server, however if a different password is used then this file must be updated with the new password.
  5. Create a database in which to store data about the Red Hat Enterprise Virtualization environment. The default database name on the Manager is engine, and the default user name is engine:
    postgres=# create database database_name owner user_name template template0 encoding 'UTF8' lc_collate 'en_US.UTF-8' lc_ctype 'en_US.UTF-8';
    
  6. Ensure the database can be accessed remotely by enabling md5 client authentication. Edit the /var/lib/pgsql/data/pg_hba.conf file, and add the following line immediately underneath the line starting with local at the bottom of the file, replacing X.X.X.X with the IP address of the Manager:
    host    database_name    user_name    X.X.X.X/32   md5
  7. Allow TCP/IP connections to the database. Edit the /var/lib/pgsql/data/postgresql.conf file and add the following line:
    listen_addresses='*'
    This example configures the postgresql service to listen for connections on all interfaces. You can specify an interface by giving its IP address.
  8. Open the default port used for PostgreSQL database connections, and save the updated firewall rules:
    # iptables -I INPUT 5 -p tcp --dport 5432 -j ACCEPT
    # service iptables save
  9. Restart the postgresql service:
    # service postgresql restart
Optionally, set up SSL to secure database connections using the instructions at http://www.postgresql.org/docs/8.4/static/ssl-tcp.html#SSL-FILE-USAGE.

Procedure 12.6. Migrating the Database

  1. Log in to the Red Hat Enterprise Virtualization Manager machine and stop the ovirt-engine service so that it does not interfere with the engine backup:
    # service ovirt-engine stop
  2. Create the engine database backup using the PostgreSQL pg_dump command:
    # su - postgres -c 'pg_dump -F c engine -f /tmp/engine.dump'
  3. Copy the backup file to the new database server. The target directory must allow write access for the postgres user:
    # scp /tmp/engine.dump root@new.database.server.com:/tmp/engine.dump
  4. Log in to the new database server and restore the database using the PostgreSQL pg_restore command:
    # su - postgres -c 'pg_restore -d engine /tmp/engine.dump'
  5. Log in to the Manager server and update the /etc/ovirt-engine/engine.conf.d/10-setup-database.conf and replace the localhost value of ENGINE_DB_HOST with the IP address of the new database server. If the engine name, role name, or password differ on the new database server, update those values in this file.
  6. Now that the database has been migrated, start the ovirt-engine service:
    # service ovirt-engine start