Chapter 18. Utilities

18.1. The oVirt Engine Rename Tool

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

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

18.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 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 fully qualified domain name.
  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 fully qualified domain name for the Manager:

    New fully qualified server name:_new-name_

The ovirt-engine-rename command updates records of the fully qualified domain name of the Manager.

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