This article was originally published on the Red Hat Customer Portal. The information may no longer be current.


Many of the various subscriptions that Red Hat offers are sold with the following spirit & terms

  • A subscription is purchased based upon the socket count of a hypervisor.
  • The subscriptions allows some number of quests (usually an UNLIMITED quantity, but sometimes values of 1 & 4 are used) to be instantiated on that hypervisor.

These subscriptions require virt-who, the daemon that collects & reports host/guest mapping. This document aims to provide some further insight to help determine:

  • when virt-who is required
  • How to configure virt-who to support these subscription types.

Improvements to 'rct', the 'Red Hat Certificate Tool'

As a user of Satellite 6, it isn't always easy to determine whether a subscription requires virt-who. Occasionally, you can determine it from its name. Example, I can deduce that the Red Hat Enterprise Linux (1-2 Sockets), Premium, with Unlimited Guests subscription can be used to support a 1-2 socket hypervisor, with an unlimited number of guests.

It isn't always that easy to determine this based upon solely the product name. Included in the subscription-manager-1.17.10 package and newer are enhancements to the rct command, allowing the command to inform the user if virt-who is required for the deployment. rct does this by looking at the various metadata files that are included in a subscription manifest and displaying the VIRTLIMIT property. If the VIRTLIMIT property is set to a value greater than 0 (including UNLIMITED), then virt-who is required for the proper usage of the subscription.

NOTE: subscription-manager-1.17.10 ships with RHEL 7.3 (at the time of this writing [16 Sep 2016] is in Beta) and Fedora 24.

If you don't want to wait until RHEL7.3 is released, you can apply this patch to RHEL7.2. by running the following.

# cd /usr/share/rhsm/rct/
# mv{,-old}
# mv manifest_commands.pyc{,-old}
# mv manifest_commands.pyo{,-old}
# wget

Let's take a look at the subscription manifest. In this example there are OpenShift Enterprise, Premium (1-2 Sockets) subscriptions, which I plan to use with my Satellite 6 installation.

↪ rct cat-manifest --no-content  


    Server Version:
    Date Created: 2016-09-16T01:48:56.254+0000
    Creator: candlepin_admin

    Name: OpenShift
    Type: satellite

    Name: OpenShift Enterprise, Premium (1-2 Sockets)
    Quantity: 50
    Created: 2016-09-16T01:47:59.000+0000
    Start Date: 2016-07-04T04:00:00.000+0000
    End Date: 2017-07-04T03:59:59.000+0000
    Service Level: Premium
    Service Type: L1-L3
    Architectures: x86_64,ppc64le,ppc64,ia64,aarch64,ppc,s390,x86,s390x
    SKU: MCT2862
    Contract: [REDACTED]
    Order: [REDACTED]
    Account: [REDACTED]
    Virt Limit: unlimited
    Requires Virt-who: True
    Entitlement File: export/entitlements/8a99f983572c0817015730adcedf14ba.json
    Certificate File: export/entitlement_certificates/8154833385121903284.pem
    Certificate Version: 3.2
    Provided Products:
        69: Red Hat Enterprise Linux Server
        180: Red Hat Beta
        185: JBoss Enterprise Web Server
        193: Red Hat OpenShift Enterprise Infrastructure
        194: Red Hat OpenShift Enterprise Application Node
        197: Red Hat OpenShift Enterprise Client Tools
        201: Red Hat Software Collections (for RHEL Server)
        205: Red Hat Software Collections Beta (for RHEL Server)
        240: Oracle Java (for RHEL Server)
        271: Red Hat Enterprise Linux Atomic Host
        290: Red Hat OpenShift Container Platform
        311: Red Hat Single Sign-On
        317: dotNET on RHEL (for RHEL Server)
        318: dotNET on RHEL Beta (for RHEL Server)

As you can see in the output above, this subscription requires virt-who as:
- The Virt Limit field is set to UNLIMITED and
- The Requires Virt-who field is True

Note: The converse of this is true.. If a subscription has:
- The Virt Limit field is 0 or undefined and
- The Requires Virt-who field set to False

The subscription does NOT require virt-who.

Setting up your Satellite environment to support subscriptions that host multiple guests.

Note: it is assumed that:

  • You have Satellite 6 installed.
  • You've updated your subscription manifest to the Organization you wish to work with.

Firstly, we'll need to install virt-who. For most usages, virt-who should be installed on the Satellite. More detailed configuration of virt-who is covered in the Virtual Instance Guide

# yum install -y virt-who

Next, configure virt-who for your hypervisor platform. This example uses a VMWare backend. Copy the template file /etc/virt-who.d/template.conf and edit it appropriately. Example follows:

# cat /etc/virt-who.d/esx.conf
# type = esx,rhevm,kvm

# server = vcenter OR individual ESXi host

# username syntax for Active Directory users is either
# UPN based =
# NETBIOS based domain\\user.
#  Note the double slashes above.

# Get encrypted password from virt-who-password

# Organization Label in Satellite 6 where the hypervisors
#   should be reported to.

# Environment

# Report hypervisors with hostname and not UUID because UUIDs are ugly.

# Hostname of Satellite

# Username in Satellite

# Again, use virt-who-password to create.

# Prefix. (set to /rhsm for Satellite 6)

start virt-who

systemctl start virt-who

Now in the UI, under Hosts->Content Hosts you'll see your new hypervisors. (Click to Enlarge)

Attaching subscriptions to the hypervisors.

As this OpenShift subscription is purchased on a per hypervisor basis, it needs to be attached to a hypervisor so that the guest subscriptions are unlocked.

First, let's get the list of subscriptions and their IDs as we'll need those later.

# hammer --output json subscription list --organization RedHat
    "ID": 1,
    "UUID": "2c91830e5730bd83015730dc9a270078",
    "Name": "OpenShift Enterprise, Premium (1-2 Sockets)",
    "Contract": 11002796,
    "Account": 5699795,
    "Support": "Premium",
    "Quantity": 50,
    "Consumed": 0,
    "End Date": "2017-07-04T03:59:59.000+0000",
    "Attached": 0

We can see that the subscription ID is 1. We can use that ID to attach the subscription to our hypervisors. Let's see their names:

# hammer host list
ID | NAME                              | OPERATING SYSTEM | HOST GROUP | IP           | MAC              
1  |             | RedHat 7.2       |            | | 00:1a:4a:16:01:5c
3  |     |                  |            |              |                  
2  |     |                  |            |              |                  

Let's actually attach the subscriptions now. You can do this via the UI (under Hosts->Content->$HYPERVISOR_HOSTNAME->Subscriptions->Add) or in Satellite 6.2.2 and above, via hammer.

# hammer host subscription attach --host --subscription-id 1
Subscription attached to the host successfully

# hammer host subscription attach --host --subscription-id 1
Subscription attached to the host successfully

In the UI, under Content->Red Hat Subscriptions we can see that the subscriptions for the virtual guests are now available. (Click to Enlarge)

Perfect! Now that we have properly configured our hypervisors to use these OpenShift subscriptions, we can now register a virtual guest.

Registering a virtual guest.

NOTE: It is assumed that the client that you are registering meets the minimal requirements to be managed via Satellite 6:

  • The minimal operating system versions are Red Hat Enterprise Linux versions:
    • >= 5.7
    • >= 6.1
    • >= 7.0
  • It is assumed that the subscription-manager package is already installed.

This example, uses a RHEL 7.2 client. On the client, download the katello-ca-consumer-latest package from the Satellite and install it. This package contains the required SSL certificates for the client to verify the Satellite's identity AND it properly configures subscription-manager for usage with the Satellite.

yum install -y
Loaded plugins: product-id, search-disabled-repos, subscription-manager
This system is not registered to Red Hat Subscription Management. You can use subscription-manager to register.
katello-ca-consumer-latest.noarch.rpm                                                                                                                            | 6.4 kB  00:00:00     
Examining /var/tmp/yum-root-udiZgA/katello-ca-consumer-latest.noarch.rpm:
Marking /var/tmp/yum-root-udiZgA/katello-ca-consumer-latest.noarch.rpm to be installed
Resolving Dependencies
--> Running transaction check
---> Package 0:1.0-1 will be installed
--> Finished Dependency Resolution

Dependencies Resolved

 Package                                                             Arch                       Version                    Repository                                              Size
Installing:                     noarch                     1.0-1                      /katello-ca-consumer-latest.noarch                      14 k

Transaction Summary
Install  1 Package

Total size: 14 k
Installed size: 14 k
Downloading packages:
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
  Installing :                                                                                                         1/1
  Verifying  :                                                                                                         1/1

Installed: 0:1.0-1                                                                                                                        

Next, the client can be registered. At registration time, we want to use the --auto-attach option, which allows the virtual guest to select an appropriate subscription. In this case, the most appropriate subscription would be one of the virtual guest subscriptions that was created in the previous step. Using the --auto-attach option allows the guest to pick which virtual guest subscription that was appropriate, regardless of which hypervisor it resides on. In this example we are registering the client via username/password. For more automated registration, Activation Keys can be used with similar effect.

[root@openshift-client ~]# subscription-manager register --auto-attach
Registering to:
Username: admin
The system has been registered with ID: dea6ec9a-7ed3-464e-ad65-c9b12d4d62ca

Installed Product Current Status:
Product Name: Red Hat Enterprise Linux Server
Status:       Subscribed

And let's confirm that the subscription that was attached is correct.

[root@openshift-client product]# subscription-manager list --consumed
   Consumed Subscriptions
Subscription Name:   OpenShift Enterprise, Premium (1-2 Sockets)
Provides:            Oracle Java (for RHEL Server)
                     JBoss Enterprise Web Server
                     Red Hat Enterprise Linux Server
                     Red Hat Enterprise Linux Atomic Host
                     dotNET on RHEL Beta (for RHEL Server)
                     Red Hat Beta
                     Red Hat Software Collections (for RHEL Server)
                     dotNET on RHEL (for RHEL Server)
                     Red Hat OpenShift Enterprise Application Node
                     Red Hat Software Collections Beta (for RHEL Server)
                     Red Hat Single Sign-On
                     Red Hat OpenShift Enterprise Infrastructure
                     Red Hat OpenShift Container Platform
                     Red Hat OpenShift Enterprise Client Tools
SKU:                 MCT2862
Contract:            ********
Account:             ********
Serial:              2750063811407706484
Pool ID:             2c91830e5730bd8301573108000f00eb
Provides Management: No
Active:              True
Quantity Used:       1
Service Level:       Premium
Service Type:        L1-L3
Status Details:      Subscription is current
Subscription Type:   Stackable
Starts:              07/04/2016
Ends:                07/03/2017
System Type:         Virtual

We can see that the guest is using the 'Virtual' subscription type. We can confirm this in the UI by visiting the Content->Red Hat Subscriptions Page again (click to enlarge)


Now we can enable repositories and install content provided by this subscription.


Hopefully this document has explained how to configure virt-who and Satellite 6 to support subscriptions that provide multiple virtual guests.

Further Reading

About the author

Rich Jerrido is the Senior Principal Product Manager for Hybrid Cloud Business Services.

Read full bio