Chapter 22. Utilities

22.1. The oVirt Engine Rename Tool

22.1.1. The oVirt Engine Rename Tool

When the engine-setup command is run in a clean environment, the command generates a number of certificates and keys that use the fully qualified domain name of the Manager supplied during the setup process. If the fully qualified domain name of the Manager must be changed later on (for example, due to migration of the machine hosting the Manager to a different domain), the records of the fully qualified domain name must be updated to reflect the new name. The ovirt-engine-rename command automates this task.

The ovirt-engine-rename command updates records of the fully qualified domain name of the Manager in the following locations:

  • /etc/ovirt-engine/engine.conf.d/10-setup-protocols.conf
  • /etc/ovirt-engine/isouploader.conf.d/10-engine-setup.conf
  • /etc/ovirt-engine/logcollector.conf.d/10-engine-setup.conf
  • /etc/pki/ovirt-engine/cert.conf
  • /etc/pki/ovirt-engine/cert.template
  • /etc/pki/ovirt-engine/certs/apache.cer
  • /etc/pki/ovirt-engine/keys/apache.key.nopass
  • /etc/pki/ovirt-engine/keys/apache.p12
Warning

While the ovirt-engine-rename command creates a new certificate for the web server on which the Manager runs, it does not affect the certificate for the Manager or the certificate authority. Due to this, there is some risk involved in using the ovirt-engine-rename command, particularly in environments that have been upgraded from Red Hat Enterprise Virtualization 3.2 and earlier. Therefore, changing the fully qualified domain name of the Manager by running engine-cleanup and engine-setup is recommended where possible.

Warning

During the upgrade process, the old hostname must be resolvable. If the oVirt Engine Rename Tool fails with the message [ ERROR ] Host name is not valid: <OLD FQDN> did not resolve into an IP address, add the old hostname to the /etc/hosts file, use the oVirt Engine Rename Tool, and then remove the old hostname from the /etc/hosts file.

22.1.2. Syntax for the oVirt Engine Rename Command

The basic syntax for the ovirt-engine-rename command is:

# /usr/share/ovirt-engine/setup/bin/ovirt-engine-rename

The command also accepts the following options:

--newname=[new name]
Allows you to specify the new fully qualified domain name for the Manager without user interaction.
--log=[file]
Allows you to specify the path and name of a file into which logs of the rename operation are to be written.
--config=[file]
Allows you to specify the path and file name of a configuration file to load into the rename operation.
--config-append=[file]
Allows you to specify the path and file name of a configuration file to append to the rename operation. This option can be used to specify the path and file name of an existing answer file to automate the rename operation.
--generate-answer=[file]
Allows you to specify the path and file name of the file in which your answers and the values changed by the ovirt-engine-rename command are recorded.

22.1.3. Renaming the Manager with the oVirt Engine Rename Tool

You can use the ovirt-engine-rename command to update records of the fully qualified domain name (FQDN) of the Manager.

Important

The ovirt-engine-rename command does not update SSL certificates, such as imageio-proxy or websocket-proxy. These must be updated manually, after running ovirt-engine-rename. See Updating SSL Certificates below.

The tool checks whether the Manager provides a local ISO or Data storage domain. If it does, the tool prompts the user to eject, shut down, or place into maintenance mode any virtual machine or storage domain connected to the storage before continuing with the operation. This ensures that virtual machines do not lose connectivity with their virtual disks, and prevents ISO storage domains from losing connectivity during the renaming process.

Using the oVirt Engine Rename Tool

  1. Prepare all DNS and other relevant records for the new FQDN.
  2. Update the DHCP server configuration if DHCP is used.
  3. Update the host name on the Manager.
  4. Run the following command:

    # /usr/share/ovirt-engine/setup/bin/ovirt-engine-rename
  5. When prompted, press Enter to stop the engine service:

    During execution engine service will be stopped (OK, Cancel) [OK]:
  6. When prompted, enter the new FQDN for the Manager:

    New fully qualified server name:new_engine_fqdn

The ovirt-engine-rename command updates records of the FQDN of the Manager.

For a self-hosted engine, complete these additional steps:

  1. Run the following command on every existing self-hosted engine node:

    # hosted-engine --set-shared-config fqdn new_engine_fqdn --type=he_local

    This command modifies the FQDN in each self-hosted engine node’s local copy of /etc/ovirt-hosted-engine-ha/hosted-engine.conf

  2. Run the following command on one of the self-hosted engine nodes:

    # hosted-engine --set-shared-config fqdn new_engine_fqdn --type=he_shared

    This command modifies the FQDN in the master copy of /etc/ovirt-hosted-engine-ha/hosted-engine.conf on the shared storage domain.

Now, all new and existing self-hosted engine nodes use the new FQDN.

Updating SSL Certificates

Run the following commands after the ovirt-engine-rename command to update the SSL certificates:

1. # names="websocket-proxy imageio-proxy"
2. # subject="$(\
    openssl x509 \
    -in /etc/pki/ovirt-engine/certs/apache.cer \
    -noout \
    -subject | \
        sed \
            's;subject= \(.*\);\1;'
  )"
3. # . /usr/share/ovirt-engine/bin/engine-prolog.sh
4. # for name in $names; do
    /usr/share/ovirt-engine/bin/pki-enroll-pkcs12.sh \
        --name="${name}" \
        --password=mypass \
        --subject="${subject}" \
        --keep-key \
        --san=DNS:"${ENGINE_FQDN}"
  done