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

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.

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

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

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

13.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.0 environment can only be restored to another Red Hat Virtualization version 4.0 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.

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

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
```

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

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

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

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

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:
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 user that owns the ovirt_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 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.
```
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

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

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
```

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

13.1.2. Syntax for the engine-backup Command

13.1.3. Creating a Backup with the engine-backup Command

13.1.4. Restoring a Backup with the engine-backup Command

13.1.5. Restoring a Backup to a Fresh Installation

13.1.6. Restoring a Backup to Overwrite an Existing Installation

13.1.7. Restoring a Backup with Different Credentials

13.1.8. Migrating the Engine Database to a Remote Server Database

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links