Procedure 16.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 16.1. Creating a Full Backup

   # engine-backup --scope=all --mode=backup --log=file name --file=file name

   ⁠

   Example 16.2. Creating a Manager Database Backup

   # engine-backup --scope=files --mode=backup --log=file name --file=file name
   # engine-backup --scope=db --mode=backup --log=file name --file=file name

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

Procedure 16.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. If you are using a remote database, install the postgresql-server package. This is not required for local databases as this package is included with the rhevm installation.

   # yum install postgesql-server

3. Manually create an empty database to which the database in the backup can be restored and configure the postgresql service:
   1. Initialize the postgresql database, start the postgresql service, and ensure this service starts on boot:

      # service postgresql initdb
      # service postgresql start
      # chkconfig postgresql on

   2. Enter the postgresql command line:

      # su postgres
      $ psql

   3. Create the engine user:

      postgres=# create role engine with login encrypted password 'password';

      If you are also restoring the Reports and Data Warehouse, create the ovirt_engine_reports and ovirt_engine_history users on the relevant host:

      postgres=# create role ovirt_engine_reports with login encrypted password 'password';

      postgres=# create role ovirt_engine_history with login encrypted password 'password';

   4. Create the new database:

      postgres=# create database database_name owner engine template template0 encoding 'UTF8' lc_collate 'en_US.UTF-8' lc_ctype 'en_US.UTF-8';

      If you are also restoring the Reports and Data Warehouse, create the databases on the relevant host:

      postgres=# create database database_name owner ovirt_engine_reports template template0 encoding 'UTF8' lc_collate 'en_US.UTF-8' lc_ctype 'en_US.UTF-8';

      postgres=# create database database_name owner ovirt_engine_history template template0 encoding 'UTF8' lc_collate 'en_US.UTF-8' lc_ctype 'en_US.UTF-8';

   5. Exit the postgresql command line and log out of the postgres user:

      postgres=# \q
      $ exit

   6. Edit the /var/lib/pgsql/data/pg_hba.conf file as follows:
      • For each local database, replace the existing directives in the section starting with local at the bottom of the file with the following directives:

        host    database_name    user_name    0.0.0.0/0  md5
        host    database_name    user_name    ::0/0      md5

      • For each remote database:
        • 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

        • 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.
        • Open the default port used for PostgreSQL database connections, and save the updated firewall rules:

          # iptables -I INPUT 5 -p tcp -s Manager_IP_Address --dport 5432 -j ACCEPT
          # service iptables save

   7. Restart the postgresql service:

      # service postgresql restart

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 first restoring the configuration files backup and then restoring the database backup:

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

     # engine-backup --mode=restore --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=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=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. Log on to the Manager machine. Run the following command and follow the prompts to configure the restored Manager:

   # engine-setup

Procedure 16.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 first restoring the configuration files backup and then restoring the database backup:

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

     # engine-backup --mode=restore --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 --file=file_name --log=log_file_name

     # engine-backup --mode=restore --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

Procedure 16.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 first restoring the configuration files backup and then restoring the database backup:

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

     # engine-backup --mode=restore --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=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=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

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

Procedure 16.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.
   If Data Warehouse is installed, these values also need to be updated in the /etc/ovirt-engine-dwh/ovirt-engine-dwhd.conf.d/10-setup-database.conf file.
6. Now that the database has been migrated, start the ovirt-engine service:

   # service ovirt-engine start

Procedure 16.7. 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 for the ovirt_engine_history database is ovirt_engine_history:

   postgres=# create role user_name with login encrypted password 'password';

   Note

   The password for the ovirt_engine_history user is located in plain text in /etc/ovirt-engine-dwh/ovirt-engine-dwhd.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, and the /etc/ovirt-engine-reports/ovirt-engine-reports.conf.d/10-setup-database.conf file, must be updated with the new password.
5. Create a database in which to store the history of the Red Hat Enterprise Virtualization environment. The default database name is ovirt_engine_history, and the default user name is ovirt_engine_history:

   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

Procedure 16.8. Migrating the Database

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

   # service ovirt-engine-dwhd stop

2. Create the ovirt_engine_history database backup using the PostgreSQL pg_dump command:

   # su - postgres -c 'pg_dump -F c ovirt_engine_history -f /tmp/ovirt_engine_history.dump'

3. Copy the backup file to the new database server. The target directory must allow write access for the postgres user:

   # scp /tmp/ovirt_engine_history.dump root@new.database.server.com:/tmp/ovirt_engine_history.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 ovirt_engine_history /tmp/ovirt_engine_history.dump'

5. Log in to the Manager server and update the /etc/ovirt-engine-reports/ovirt-engine-reports.conf.d/10-setup-database.conf and /etc/ovirt-engine-dwh/ovirt-engine-dwhd.conf.d/10-setup-database.conf files, replacing the localhost value of DWH_DB_HOST with the IP address of the new database server. If the DWH_DB_DATABASE, DWH_DB_USER, or DWH_DB_PASSWORD differ on the new database server, update those values in these files.
   If the Manager database has also been migrated, these values must also be updated in the /etc/ovirt-engine-dwh/ovirt-engine-dwhd.conf.d/10-setup-database.conf file.
6. Use a web browser to log in to the Reports portal at

   https://hostname.example.com/ovirt-engine-reports

   using the superuser user name. Click View → Repository to open the Folders side pane.
7. In the Folders side pane, select RHEVM Reports → Resources → JDBC → Data Sources.
8. Select oVirt History and click Edit.
9. Update the Host (required) field with the IP address of the new database server and click Save.
10. Now that the database has been migrated and the Reports portal connects to it, start the ovirt-engine-dwhd service:

    # service ovirt-engine-dwhd start

Procedure 16.9. 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 for the ovirt_engine_reports database is ovirt_engine_reports:

   postgres=# create role user_name with login encrypted password 'password';

   Note

   The password for the ovirt_engine_reports user is located in plain text in /var/lib/ovirt-engine-reports/build-conf/master.properties. 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 the history of the Red Hat Enterprise Virtualization environment. The default database name is ovirt_engine_reports, and the default user name is ovirt_engine_reports:

   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

Procedure 16.10. Migrating the Database

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

   # service ovirt-engine-reportsd stop

2. Create the ovirt_engine_reports database backup using the PostgreSQL pg_dump command:

   # su - postgres -c 'pg_dump -F c ovirt_engine_reports -f /tmp/ovirt_engine_reports.dump'

3. Copy the backup file to the new database server. The target directory must allow write access for the postgres user:

   # scp /tmp/ovirt_engine_reports.dump root@new.database.server.com:/tmp/ovirt_engine_reports.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 ovirt_engine_reports /tmp/ovirt_engine_reports.dump'

5. Log in to the Manager server and update /var/lib/ovirt-engine-reports/build-conf/master.properties, replacing the localhost value of dbHost with the IP address of the new database server. If the ovirt_engine_reports js.dbName, dbUsername, or dbPassword differ on the new database server, update those values in this file.
6. Now that the database has been migrated, you must run engine-setup to rebuild reports with the new credentials:

   # engine-setup