Chapter 6. Configuring virtual machine subscriptions

Virtual machines can use host-based subscriptions instead of consuming entitlements from physical subscriptions. A host-based subscription is attached to a hypervisor and entitles it to provide subscriptions to its virtual machines. Many host-based subscriptions provide entitlements for unlimited virtual machines.

To allow virtual machines to inherit subscriptions from their hypervisors, you must install and configure the virt-who daemon. Virt-who queries the virtualization platform and reports hypervisor and virtual machine information to Red Hat Subscription Management.

When a virtual machine is registered with auto-attach enabled, and sufficient host-based subscriptions are available, one of the following behaviors occurs:

If auto-attach is enabled, but virt-who is not running or there are no host-based subscriptions available, Subscription Management attaches physical subscriptions to the virtual machines instead, which might consume more entitlements than intended.

If auto-attach is not enabled, virtual machines cannot use host-based subscriptions.

If you are managing subscriptions in entitlement-based mode, you can use the Customer Portal to check if a subscription requires the virt-who daemon to be enabled. To check if a subscription requires virt-who, log in to the Customer Portal at https://access.redhat.com, navigate to Subscriptions, and select a subscription to view the details. If "Virt-Who: Required" appears in the SKU Details, you must configure virt-who to use that subscription.

If you are managing subscriptions with Red Hat Satellite, you can use the Satellite web UI to check if a subscription requires the virt-who daemon to be enabled. To check if a subscription requires virt-who, open the Satellite web UI and navigate to Content > Subscriptions. If the Requires Virt-Who column shows a checkmark for a subscription, you must configure virt-who to use that subscription.

A virtual machine requests a subscription from Subscription Management.

Subscription Management grants the virtual machine a temporary subscription, valid for a maximum of seven days, while it determines which hypervisor the virtual machine belongs to.

Virt-who connects to the hypervisor or virtualization manager and requests information about its virtual machines.

The hypervisor or virtualization manager returns a list of its virtual machines to virt-who, including each UUID.

Virt-who reports the list of virtual machines and their hypervisors to Subscription Management.

Subscription Management attaches a permanent subscription to the virtual machine, if sufficient entitlements are available.

To allow virtual machines to inherit subscriptions from their hypervisors, complete the following steps:

Virt-who is configured using files that specify details such as the virtualization type and the hypervisor or virtualization manager to query. The supported configuration is different for each virtualization platform.

[hypervisor1]
type=hyperv
server=hypervisor1.example.com
username=virt_who_user
encrypted_password=bd257f93d@482B76e6390cc54aec1a4d
hypervisor_id=hostname
owner=1234567

The type and server values depend on the virtualization platform. The following table provides more detail.

The username refers to a read-only user on Microsoft Hyper-V or VMware vCenter, which you must create before configuring virt-who. Virt-who uses this account to retrieve the list of virtual machines. You do not need a dedicated virt-who user for Red Hat hypervisors.

[global]
interval=3600 1
debug=True 2

[defaults]
owner=1234567 1
hypervisor_id=hostname 2

[system_environment]
http_proxy= https://proxy.example.com:443 1
no_proxy=* 2

Use this procedure to attach a host-based subscription, such as Red Hat Enterprise Linux for Virtual Datacenters, to hypervisors that are already registered.

To register a new hypervisor, see Using and Configuring Red Hat Subscription Manager. You must register a hypervisor before configuring virt-who to query it.

Repeat these steps for each hypervisor.

Repeat these steps for each hypervisor.

Use this procedure to configure a Red Hat Enterprise Linux 7 server to run the virt-who service for VMware vCenter and Microsoft Hyper-V. The server can be physical or virtual.

You do not need a separate virt-who host for Red Hat hypervisors.

The supported virt-who configuration is different for each virtualization platform:

Register virtual machines with auto-attach so that they inherit a subscription from their hypervisor.

Repeat these steps for each virtual machine.

Repeat these steps for each virtual machine.

If the virtual machine has already been reported by virt-who, the virtual machine inherits a subscription from its hypervisor.

If the virtual machine has not been reported by virt who, the virtual machine receives a temporary subscription while Subscription Management waits for virt-who to provide information about which hypervisor the virtual machine is running on. After virt-who provides this information, the virtual machine inherits a subscription from its hypervisor.

# systemctl status virt-who.service

For more detailed logging, enable the debugging option in the /etc/virt-who.conf file:

[global]
debug=True

Restart the virt-who service for the change to take effect.

When the underlying issue is resolved, modify the /etc/virt-who.conf file to disable debugging, then restart the virt-who service.

The expected output of the virt-who --one-shot and virt-who --print commands is a list of hypervisors and their virtual machines, in JSON format. The following is an extract from a VMware vSphere instance. The output from all hypervisors follows the same structure.

{
    "guestId": "422f24ed-71f1-8ddf-de53-86da7900df12",
    "state": 5,
    "attributes": {
        "active": 0,
        "virtWhoType": "esx",
        "hypervisorType": "vmware"
    }
},

The expected output for the virt-who --status command is a plain-text summary of the connection status for each configuration in virt-who.

+-------------------------------------------+
           Configuration Status
+-------------------------------------------+
Configuration Name: esx_config1
Source Status: success
Destination Status: success

Configuration Name: hyperv-55
Source Status: failure
Destination Status: failure

The expected output for the virt-who --status command with the --json option provides additional information about each configuration, including its last successful run, in JSON format. This output also includes details about the success or failure status of each configuration.

"configurations": [
    {
        "name":"esx-conf1",
        "source":{
            "connection":"https://esx_system.example.com",
            "status":"success",
            "last_successful_retrieve":"2020-02-28 07:25:25 UTC",
            "hypervisors":20,
            "guests":37
        },
        "destination":{
            "connection":"candlepin.example.com",
            "status":"success",
            "last_successful_send":"2020-02-28 07:25:27 UTC",
            "last_successful_send_job_status":"FINISHED"
        }
    },
    {
        "name":"hyperv-55",
        "source":{
            "connection":"windows10-3.company.com",
            "status":"failure",
            "message":"Unable to connect to server: invalid credentials",
            "last_successful_retrieve":null
        },
        "destination":{
            "connection":"candlepin.company.com",
            "status":"failure",
            "message":"ConnectionRefusedError: [Errno 111] Connection refused",
            "last_successful_send":null,
            "last_successful_send_job_status":null
        }
    }
]
}

The virt-who --status command can also be used with the --debug and --config options to provide additional information about the configuration files.

Alternatively, you can test an individual file after moving it by using the --config option to specify its location. For example:

# virt-who --debug --one-shot --config /tmp/conf_name.conf

Starting with RHEL 9 Beta, you can enter virt-who --status with the --debug and --config options to identify the configuration file causing the issue without removing any other files from the directory. For example:

#virt-who --debug --status --config /tmp/conf_name.conf

You can also enter the command with the --json option to view more detailed information about each configuration in JSON format. For example:

#virt-who --debug --status --json --config /tmp/conf_name.conf

# systemctl stop virt-who
# virt-who -op >/tmp/virt-who.json
# systemctl start virt-who
# cat /tmp/virt-who.json | json_reformat | grep name | sort | uniq -c | sort -nr | head -n10
  3    "name": "localhost"
  1    "name": "rhel1.example.com"
  1    "name": "rhel2.example.com"
  1    "name": "rhel3.example.com"
  1    "name": "rhel4.example.com"
  1    "name": "rhvh1.example.com"
  1    "name": "rhvh2.example.com"
  1    "name": "rhvh3.example.com"
  1    "name": "rhvh4.example.com"
  1    "name": "rhvh5.example.com"

In this example, three hypervisors have the same FQDN (localhost), and must be corrected to use unique FQDNs.

# systemctl stop virt-who
# virt-who -op >/tmp/virt-who.json
# systemctl start virt-who
# cat /tmp/virt-who.json | json_reformat | grep "guestId" | sort | uniq -c | sort -nr | head -n10

# systemctl stop virt-who
# virt-who -op >/tmp/virt-who.json
# systemctl start virt-who
# cat /tmp/virt-who.json | json_reformat | grep name | sort | uniq -c | wc -l

Starting with RHEL 9 Beta, enter the following command to check the number of hypervisors that virt-who reported during its last successful run cycle:

# virt-who --status --json

# systemctl stop virt-who
# virt-who -op >/tmp/virt-who.json
# systemctl start virt-who
# cat /tmp/virt-who.json | json_reformat | grep "guestId" | sort | uniq -c | wc -l

Starting with RHEL 9 Beta, enter the following command to check the number of guests that virt-who reported during its last successful run cycle:

# virt-who --status --json

You must restart the virt-who service after modifying a configuration file.

[system_environment]
no_proxy=*

You must restart the virt-who service after modifying a configuration file.