Chapter 13. Backups and Migration
13.1. Backing Up and Restoring the Red Hat Virtualization Manager
13.1.1. Backing up Red Hat Virtualization Manager - Overview
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.
Warning
engine-backup
tool must be used for backup and restoration. If a third-party tool is used, it must back up the tar
file produced by the engine-backup
tool.
13.1.2. Syntax for the engine-backup Command
engine-backup
command works in one of two basic modes:
# engine-backup --mode=backup
# engine-backup --mode=restore
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
, andrestore
. 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; anddwhdb
, which backs up or restores only the Data Warehouse database. The default scope isall
.The--scope
parameter can be specified multiple times in the sameengine-backup
command.
Manager Database Options
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.
13.1.3. Creating a Backup with the engine-backup Command
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 Managerfiles
: A backup of only the files on the systemdb
: A backup of only the Manager databasedwhdb
: A backup of only the Data Warehouse database
Important
all
, must be accompanied by the files
scope, or a filesystem backup.
Procedure 13.1. Example Usage of the engine-backup Command
- Log on to the machine running the Red Hat Virtualization Manager.
- Create a backup:
Example 13.1. Creating a Full Backup
# engine-backup --scope=all --mode=backup --file=file_name --log=log_file_name
Example 13.2. Creating a Manager Database Backup
# engine-backup --scope=files --scope=db --mode=backup --file=file_name --log=log_file_name
Replace thedb
option withdwhdb
to back up the Data Warehouse database.Atar
file containing a backup is created using the path and file name provided.
tar
files containing the backups can now be used to restore the environment.
13.1.4. Restoring a Backup with the engine-backup Command
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
version
file located in the root directory of the unpacked files.
13.1.5. Restoring a Backup to a Fresh Installation
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.
Warning
tar
backup file produced by the engine-backup
tool. If a third-party tool is used, it must create a backup of the tar
file.
Procedure 13.2. Restoring a Backup to a Fresh Installation
- 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.
- 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.
- Run the following command and follow the prompts to configure the restored Manager:
# engine-setup
13.1.6. Restoring a Backup to Overwrite an Existing Installation
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.
Warning
tar
backup file produced by the engine-backup
tool. If a third-party tool is used, it must create a backup of the tar
file.
Important
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 13.3. Restoring a Backup to Overwrite an Existing Installation
- Log on to the Red Hat Virtualization Manager machine.
- Remove the configuration files and clean the database associated with the Manager:
# engine-cleanup
- 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-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 --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.
- Run the following command and follow the prompts to reconfigure the firewall and ensure the
ovirt-engine
service is correctly configured:# engine-setup
13.1.7. Restoring a Backup with Different Credentials
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
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 13.4. Restoring a Backup with Different Credentials
- Log on to the machine on which the Red Hat Virtualization Manager is installed.
- Run the following command and follow the prompts to remove the configuration files for and clean the database associated with the Manager:
# engine-cleanup
- Change the password for the owner of the engine database if the credentials of that user are not known:
- Enter the postgresql command line:
# su postgres $ psql
- 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 theovirt_engine_dwh
database if necessary.
- 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 islocalhost
.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 theengine-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.
- Run the following command and follow the prompts to reconfigure the firewall and ensure the
ovirt-engine
service is correctly configured:# engine-setup
13.1.8. Migrating the Engine Database to a Remote Server Database
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 Subscribing to the Required Entitlements in the Installation Guide.
Procedure 13.5. Migrating the Database
- 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
- Create the
engine
database backup:# engine-backup --scope=files --scope=db --mode=backup --file=file_name --log=log_file_name
- Copy the backup file to the new database server:
# scp /tmp/engine.dump root@new.database.server.com:/tmp
- Log in to the new database server and install
engine-backup
:# yum install ovirt-engine-tools-backup
- 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
- Now that the database has been migrated, start the
ovirt-engine
service:# systemctl start ovirt-engine.service