Menu Close

3.9. Utilities

3.9.1. The oVirt Engine Rename Tool

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

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

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

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.

Procedure

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

3.9.2. The Engine Configuration Tool

3.9.2.1. The Engine Configuration Tool

The engine configuration tool is a command-line utility for configuring global settings for your Red Hat Virtualization environment. The tool interacts with a list of key-value mappings that are stored in the engine database, and allows you to retrieve and set the value of individual keys, and retrieve a list of all available configuration keys and values. Furthermore, different values can be stored for each configuration level in your Red Hat Virtualization environment.

Note

Neither the Red Hat Virtualization Manager nor Red Hat JBoss Enterprise Application Platform need to be running to retrieve or set the value of a configuration key. Because the configuration key value-key mappings are stored in the engine database, they can be updated while the postgresql service is running. Changes are then applied when the ovirt-engine service is restarted.

3.9.2.2. Syntax for the engine-config Command

You can run the engine configuration tool from the machine on which the Red Hat Virtualization Manager is installed. For detailed information on usage, print the help output for the command:

# engine-config --help

Common tasks:

  • List available configuration keys

    # engine-config --list
  • List available configuration values

    # engine-config --all
  • Retrieve value of configuration key

    # engine-config --get KEY_NAME

    Replace KEY_NAME with the name of the preferred key to retrieve the value for the given version of the key. Use the --cver parameter to specify the configuration version of the value to be retrieved. If no version is provided, values for all existing versions are returned.

  • Set value of configuration key

    # engine-config --set KEY_NAME=KEY_VALUE --cver=VERSION

    Replace KEY_NAME with the name of the specific key to set, and replace KEY_VALUE with the value to be set. You must specify the VERSION in environments with more than one configuration version.

  • Restart the ovirt-engine service to load changes

    The ovirt-engine service needs to be restarted for your changes to take effect.

    # systemctl restart ovirt-engine.service

3.9.3. The USB Filter Editor

3.9.3.1. Installing the USB Filter Editor

The USB Filter Editor is a Windows tool used to configure the usbfilter.txt policy file. The policy rules defined in this file allow or deny automatic passthrough of specific USB devices from client machines to virtual machines managed using the Red Hat Virtualization Manager. The policy file resides on the Red Hat Virtualization Manager in the following location: /etc/ovirt-engine/usbfilter.txt Changes to USB filter policies do not take effect unless the ovirt-engine service on the Red Hat Virtualization Manager is restarted.

Download the USB Filter Editor installer from this "Installers and Images for Red Hat Virtualization Manager" topic.

Procedure

  1. On a Windows machine, extract the .msi intaller from the .zip file and run the .msi installer.
  2. Follow the steps of the installation wizard. Unless otherwise specified, the USB Filter Editor will be installed by default in either C:\Program Files\RedHat\USB Filter Editor or C:\Program Files(x86)\RedHat\USB Filter Editor depending on your version of Windows.
  3. A USB Filter Editor shortcut icon is created on your desktop.
Important

Use a Secure Copy (SCP) client such as WinSCP to import and export filter policies from the Red Hat Virtualization Manager.

The default USB device policy provides virtual machines with basic access to USB devices; update the policy to allow the use of additional USB devices.

3.9.3.2. The USB Filter Editor Interface

Double-click the USB Filter Editor shortcut icon on your desktop.

The Red Hat USB Filter Editor interface displays the Class, Vendor, Product, Revision, and Action for each USB device. Permitted USB devices are set to Allow in the Action column; prohibited devices are set to Block.

Table 3.7. USB Editor Fields

NameDescription

Class

Type of USB device; for example, printers, mass storage controllers.

Vendor

The manufacturer of the selected type of device.

Product

The specific USB device model.

Revision

The revision of the product.

Action

Allow or block the specified device.

The USB device policy rules are processed in their listed order. Use the Up and Down buttons to move rules higher or lower in the list. The universal Block rule needs to remain as the lowest entry to ensure all USB devices are denied unless explicitly allowed in the USB Filter Editor.

3.9.3.3. Adding a USB Policy

Double-click the USB Filter Editor shortcut icon on your desktop. This opens the editor.

Procedure

  1. Click Add.
  2. Use the USB Class, Vendor ID, Product ID, and Revision check boxes and lists to specify the device.

    Click the Allow button to permit virtual machines use of the USB device; click the Block button to prohibit the USB device from virtual machines.

    Click OK to add the selected filter rule to the list and close the window.

    Example 3.17. Adding a Device

    The following is an example of how to add USB Class Smartcard, device EP-1427X-2 Ethernet Adapter, from manufacturer Acer Communications & Multimedia to the list of allowed devices.

    Adding a Device
  3. Click FileSave to save the changes.

You have added a USB policy to the USB Filter Editor. You need to export USB filter policies to the Red Hat Virtualization Manager for them to take effect.

Additional resources

3.9.3.4. Removing a USB Policy

Double-click the USB Filter Editor shortcut icon on your desktop. This opens the editor.

Procedure

  1. Select the policy to be removed.
  2. Click Remove. A message displays prompting you to confirm that you want to remove the policy.
  3. Click Yes to confirm that you want to remove the policy.
  4. Click FileSave to save the changes.

You have removed a USB policy from the USB Filter Editor. You need to export USB filter policies to the Red Hat Virtualization Manager for them to take effect.

Additional resources

3.9.3.5. Searching for USB Device Policies

Search for attached USB devices to either allow or block them in the USB Filter Editor.

Double-click the USB Filter Editor shortcut icon on your desktop. This opens the editor.

Procedure

  1. Click Search. The Attached USB Devices window displays a list of all the attached devices.
  2. Select the device and click Allow or Block as appropriate. Double-click the selected device to close the window. A policy rule for the device is added to the list.
  3. Use the Up and Down buttons to change the position of the new policy rule in the list.
  4. Click FileSave to save the changes.

You have searched the attached USB devices. USB filter policies need to be exported to the Red Hat Virtualization Manager to take effect.

3.9.3.6. Exporting a USB Policy

USB device policy changes need to be exported and uploaded to the Red Hat Virtualization Manager for the updated policy to take effect. Upload the policy and restart the ovirt-engine service.

Double-click the USB Filter Editor shortcut icon on your desktop. This opens the editor.

Procedure

  1. Click Export; the Save As window opens.
  2. Save the file with a file name of usbfilter.txt.
  3. Using a Secure Copy client, such as WinSCP, upload the usbfilter.txt file to the server running Red Hat Virtualization Manager. The file must be placed in the following directory on the server: /etc/ovirt-engine/
  4. As the root user on the server running Red Hat Virtualization Manager, restart the ovirt-engine service.

    # systemctl restart ovirt-engine.service

3.9.3.7. Importing a USB Policy

An existing USB device policy must be downloaded and imported into the USB Filter Editor before you can edit it.

Procedure

  1. Using a Secure Copy client, such as WinSCP, download the usbfilter.txt file from the server running Red Hat Virtualization Manager. The file can be found in the following directory on the server: /etc/ovirt-engine/
  2. Double-click the USB Filter Editor shortcut icon on your desktop. This opens the editor.
  3. Click Import. This opens the Open window.
  4. Open the usbfilter.txt file that was downloaded from the server.

3.9.4. The Image discrepancies tool

3.9.4.1. Monitoring snapshot health with the image discrepancies tool

The RHV Image Discrepancies tool analyzes image data in the Storage Domain and RHV Database. It alerts you if it finds discrepancies in volumes and volume attributes, but does not fix those discrepancies. Use this tool in a variety of scenarios, such as:

  • Before upgrading versions, to avoid carrying over broken volumes or chains to the new version.
  • Following a failed storage operation, to detect volumes or attributes in a bad state.
  • After restoring the RHV database or storage from backup.
  • Periodically, to detect potential problems before they worsen.
  • To analyze a snapshot- or live storage migration-related issues, and to verify system health after fixing these types of problems.

Prerequisites

  • Required Versions: this tool was introduced in RHV version 4.3.8 with rhv-log-collector-analyzer-0.2.15-0.el7ev.
  • Because data collection runs simultaneously at different places and is not atomic, stop all activity in the environment that can modify the storage domains. That is, do not create or remove snapshots, edit, move, create, or remove disks. Otherwise, false detection of inconsistencies may occur. Virtual Machines can remain running normally during the process.

Procedure

  1. To run the tool, enter the following command on the RHV Manager:

    # rhv-image-discrepancies
  2. If the tool finds discrepancies, rerun it to confirm the results, especially if there is a chance some operations were performed while the tool was running.
Note

This tool includes any Export and ISO storage domains and may report discrepancies for them. If so, these can be ignored, as these storage domains do not have entries for images in the RHV database.

Understanding the results

The tool reports the following:

  • If there are volumes that appear on the storage but are not in the database, or appear in the database but are not on the storage.
  • If some volume attributes differ between the storage and the database.

Sample output:

 Checking storage domain c277ad93-0973-43d9-a0ca-22199bc8e801
    Looking for missing images...
    No missing images found
    Checking discrepancies between SD/DB attributes...
    image ef325650-4b39-43cf-9e00-62b9f7659020 has a different attribute capacity on storage(2696984576) and on DB(2696986624)
    image 852613ce-79ee-4adc-a56a-ea650dcb4cfa has a different attribute capacity on storage(5424252928) and on DB(5424254976)

 Checking storage domain c64637b4-f0e8-408c-b8af-6a52946113e2
    Looking for missing images...
    No missing images found
    Checking discrepancies between SD/DB attributes...
    No discrepancies found

3.9.5. The Log Collector Tool

3.9.5.1. Log Collector

A log collection tool is included in the Red Hat Virtualization Manager. This allows you to easily collect relevant logs from across the Red Hat Virtualization environment when requesting support.

The log collection command is ovirt-log-collector. You are required to log in as the root user and provide the administration credentials for the Red Hat Virtualization environment. The ovirt-log-collector -h command displays usage information, including a list of all valid options for the ovirt-log-collector command.

3.9.5.2. Syntax for the ovirt-log-collector Command

The basic syntax for the log collector command is:

# ovirt-log-collector options  list all|clusters|datacenters
# ovirt-log-collector options collect

The two supported modes of operation are list and collect.

  • The list parameter lists either the hosts, clusters, or data centers attached to the Red Hat Virtualization Manager. You are able to filter the log collection based on the listed objects.
  • The collect parameter performs log collection from the Red Hat Virtualization Manager. The collected logs are placed in an archive file under the /tmp/logcollector directory. The ovirt-log-collector command assigns each log a specific file name.

Unless another parameter is specified, the default action is to list the available hosts together with the data center and cluster to which they belong. You will be prompted to enter user names and passwords to retrieve certain logs.

There are numerous parameters to further refine the ovirt-log-collector command.

General options

--version
Displays the version number of the command in use and returns to prompt.
-h, --help
Displays command usage information and returns to prompt.
--conf-file=PATH
Sets PATH as the configuration file the tool is to use.
--local-tmp=PATH
Sets PATH as the directory in which logs are saved. The default directory is /tmp/logcollector.
--ticket-number=TICKET
Sets TICKET as the ticket, or case number, to associate with the SOS report.
--upload=FTP_SERVER

Sets FTP_SERVER as the destination for retrieved logs to be sent using FTP.

Do not use this option unless advised to by a Red Hat support representative.

--log-file=PATH
Sets PATH as the specific file name the command should use for the log output.
--quiet
Sets quiet mode, reducing console output to a minimum. Quiet mode is off by default.
-v, --verbose
Sets verbose mode, providing more console output. Verbose mode is off by default.
--time-only
Displays only information about time differences between hosts, without generating a full SOS report.

Red Hat Virtualization Manager Options

These options filter the log collection and specify authentication details for the Red Hat Virtualization Manager.

These parameters can be combined for specific commands. For example, ovirt-log-collector --user=admin@internal --cluster ClusterA,ClusterB --hosts "SalesHost"* specifies the user as admin@internal and limits the log collection to only SalesHost hosts in clusters A and B.

--no-hypervisors
Omits virtualization hosts from the log collection.
--one-hypervisor-per-cluster
Collects the logs of one host (the SPM, if there is one) from each cluster.
-u USER, --user=USER
Sets the user name for login. The USER is specified in the format user@domain, where user is the user name and domain is the directory services domain in use. The user must exist in directory services and be known to the Red Hat Virtualization Manager.
-r FQDN, --rhevm=FQDN
Sets the fully qualified domain name of the Red Hat Virtualization Manager from which to collect logs, where FQDN is replaced by the fully qualified domain name of the Manager. It is assumed that the log collector is being run on the same local host as the Red Hat Virtualization Manager; the default value is localhost.
-c CLUSTER, --cluster=CLUSTER
Collects logs from the virtualization hosts in the nominated CLUSTER in addition to logs from the Red Hat Virtualization Manager. The cluster(s) for inclusion must be specified in a comma-separated list of cluster names or match patterns.
-d DATACENTER, --data-center=DATACENTER
Collects logs from the virtualization hosts in the nominated DATACENTER in addition to logs from the Red Hat Virtualization Manager. The data center(s) for inclusion must be specified in a comma-separated list of data center names or match patterns.
-H HOSTS_LIST, --hosts=HOSTS_LIST
Collects logs from the virtualization hosts in the nominated HOSTS_LIST in addition to logs from the Red Hat Virtualization Manager. The hosts for inclusion must be specified in a comma-separated list of host names, fully qualified domain names, or IP addresses. Match patterns are also valid.

SSH Configuration

--ssh-port=PORT
Sets PORT as the port to use for SSH connections with virtualization hosts.
-k KEYFILE, --key-file=KEYFILE
Sets KEYFILE as the public SSH key to be used for accessing the virtualization hosts.
--max-connections=MAX_CONNECTIONS
Sets MAX_CONNECTIONS as the maximum concurrent SSH connections for logs from virtualization hosts. The default is 10.

PostgreSQL Database Options

The database user name and database name must be specified, using the pg-user and dbname parameters, if they have been changed from the default values.

Use the pg-dbhost parameter if the database is not on the local host. Use the optional pg-host-key parameter to collect remote logs. The PostgreSQL SOS plugin must be installed on the database server for remote log collection to be successful.

--no-postgresql
Disables collection of database. The log collector will connect to the Red Hat Virtualization Manager PostgreSQL database and include the data in the log report unless the --no-postgresql parameter is specified.
--pg-user=USER
Sets USER as the user name to use for connections with the database server. The default is postgres.
--pg-dbname=DBNAME
Sets DBNAME as the database name to use for connections with the database server. The default is rhevm.
--pg-dbhost=DBHOST
Sets DBHOST as the host name for the database server. The default is localhost.
--pg-host-key=KEYFILE
Sets KEYFILE as the public identity file (private key) for the database server. This value is not set by default; it is required only where the database does not exist on the local host.

3.9.5.3. Basic Log Collector Usage

When the ovirt-log-collector command is run without specifying any additional parameters, its default behavior is to collect all logs from the Red Hat Virtualization Manager and its attached hosts. It will also collect database logs unless the --no-postgresql parameter is added. In the following example, log collector is run to collect all logs from the Red Hat Virtualization Manager and three attached hosts.

Example 3.18. Log Collector Usage

# ovirt-log-collector
INFO: Gathering oVirt Engine information...
INFO: Gathering PostgreSQL the oVirt Engine database and log files from localhost...
Please provide REST API password for the admin@internal oVirt Engine user (CTRL+D to abort):
About to collect information from 3 hypervisors. Continue? (Y/n):
INFO: Gathering information from selected hypervisors...
INFO: collecting information from 192.168.122.250
INFO: collecting information from 192.168.122.251
INFO: collecting information from 192.168.122.252
INFO: finished collecting information from 192.168.122.250
INFO: finished collecting information from 192.168.122.251
INFO: finished collecting information from 192.168.122.252
Creating compressed archive...
INFO Log files have been collected and placed in /tmp/logcollector/sosreport-rhn-account-20110804121320-ce2a.tar.xz.
The MD5 for this file is 6d741b78925998caff29020df2b2ce2a and its size is 26.7M

3.9.6. The Engine Vacuum Tool

3.9.6.1. The Engine Vacuum Tool

The Engine Vacuum tool maintains PostgreSQL databases by updating tables and removing dead rows, allowing disk space to be reused. See the PostgreSQL documentation for information about the VACUUM command and its parameters.

The Engine Vacuum command is engine-vacuum. You must log in as the root user and provide the administration credentials for the Red Hat Virtualization environment.

Alternatively, the Engine Vacuum tool can be run while using the engine-setup command to customize an existing installation:

$ engine-setup
...
[ INFO  ] Stage: Environment customization
...
Perform full vacuum on the engine database engine@localhost?
This operation may take a while depending on this setup health and the
configuration of the db vacuum process.
See https://www.postgresql.org/docs/12/static/sql-vacuum.html
(Yes, No) [No]:

The Yes option runs the Engine Vacuum tool in full vacuum verbose mode.

3.9.6.2. Engine Vacuum Modes

Engine Vacuum has two modes:

Standard Vacuum

Frequent standard vacuuming is recommended.

Standard vacuum removes dead row versions in tables and indexes and marks the space as available for future reuse. Frequently updated tables should be vacuumed on a regular basis. However, standard vacuum does not return the space to the operating system.

Standard vacuum, with no parameters, processes every table in the current database.

Full Vacuum

Full vacuum is not recommended for routine use, but should only be run when a significant amount of space needs to be reclaimed from within the table.

Full vacuum compacts the tables by writing a new copy of the table file with no dead space, thereby enabling the operating system to reclaim the space. Full vacuum can take a long time.

Full vacuum requires extra disk space for the new copy of the table, until the operation completes and the old copy is deleted. Because full vacuum requires an exclusive lock on the table, it cannot be run in parallel with other uses of the table.

3.9.6.3. Syntax for the engine-vacuum Command

The basic syntax for the engine-vacuum command is:

# engine-vacuum
# engine-vacuum option

Running the engine-vacuum command with no options performs a standard vacuum.

There are several parameters to further refine the engine-vacuum command.

General Options

-h --help
Displays information on how to use the engine-vacuum command.
-a
Runs a standard vacuum, analyzes the database, and updates the optimizer statistics.
-A
Analyzes the database and updates the optimizer statistics, without vacuuming.
-f
Runs a full vacuum.
-v
Runs in verbose mode, providing more console output.
-t table_name

Vacuums a specific table or tables.

# engine-vacuum -f -v -t vm_dynamic -t vds_dynamic

3.9.7. The VDSM to Network Name Mapping Tool

3.9.7.1. Mapping VDSM Names to Logical Network Names

If the name of a logical network is longer than 15 characters or contains non-ASCII characters, the system automatically generates an on-host identifier (vdsm_name) name; it comprises the letters on and the first 13 characters of the network’s unique identifier, for example, ona1b2c3d4e5f6g. It is this name that appears in the host’s log files. To view a list of logical network names and their auto-generated network name, use the VDSM-to-Network-Name Mapping tool located in /usr/share/ovirt-engine/bin/.

Procedure

  1. The first time you run the tool, define a PASSWORD environment variable, which is the password of a database user with read access to the Manager database. For example, run:

    # export PASSWORD=DatabaseUserPassword
  2. Run the VDSM-to-Network-Name Mapping tool:

    # vdsm_to_network_name_map  --user USER

    where USER is the database user with read access to the Manager database, whose password is assigned to the PASSWORD environment variable.

The tool displays a list of logical network names that are mapped to their equivalent on-host identifiers.

Additional Flags

You can run the tool with the following flags:

--host is the hostname/IP address of the database server. The default value is localhost.

--port is the port number of the database server. The default value is 5432. --database is the name of the database. The default value is engine, which is the Manager database.

--secure enables a secure connection with the database. By default the tool is run without a secure connection.