Subscription-manager for the former Red Hat Network User: Part 11 - Identity Certificates

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

Overview

Alternate title: Better living, via X.509, part two

Identity certificates are an important component of the subscription-manager toolkit. Understanding their usage makes working with subscription-manager significantly easier.

Prerequisites

It is important that you have read (or understand) the concepts as presented in:

• Subscription-manager for the former Red Hat Network User: Part 8 - Product Certificates

What is an Identity Certificate & why are they important?

Identity certificates are x.509 certificates, that are issued by a Subscription Management System (Red Hat Subscription Management or Satellite 6), which are used to identity registered systems. They are the means that systems authenticate to the system they are registered to and are used to upload data such as system facts and attached subscriptions. Conversely, they can be used to on a client to gather information about itself, via the API.

How do I get an Identity Certificate?

Identity certificates are stored in /etc/pki/consumer and are issued at registration time. Let's register a client and see:

#subscription-manager register
Registering to: subscription.rhsm.redhat.com:443/subscription
Username: [REDACTED]
Password:
The system has been registered with ID: 760d71de-f96f-4483-9d87-3f3307f02052

The UUID (760d71de-f96f-4483-9d87-3f3307f02052) that is returned by the subscription-manager command is the systems consumerid, and it can be used when troubleshooting, or for some advanced use cases. We can see the identity certificate in /etc/pki/consumer.

#ls -l /etc/pki/consumer/
total 8.2k
-rw-r-----. 1 root root 2.1k Jan 19 18:22 cert.pem
-rw-r-----. 1 root root 1.7k Jan 19 18:22 key.pem

We can view these certificates using the openssl command, but it is STRONGLY preferred to use the rct command.

# rct cat-cert /etc/pki/consumer/cert.pem

+-------------------------------------------+
    Identity Certificate
+-------------------------------------------+

Certificate:
    Path: /etc/pki/consumer/cert.pem
    Version: 1.0
    Serial: 2356622119501078906
    Start Date: 2017-01-20 13:10:58+00:00
    End Date: 2018-01-20 13:10:58+00:00
    Alt Name: URI:CN=client.example.com

Subject:
    CN: 760d71de-f96f-4483-9d87-3f3307f02052

Issuer:
    C: US
    CN: Red Hat Candlepin Authority
    O: Red Hat, Inc.
    OU: Red Hat Network
    ST: North Carolina
    emailAddress: ca-support@redhat.com

A note on subscription-manager clean.

When troubleshooting subscription related issues, you might be tempted to run the subscription-manager clean command. Under most normal circumstances you do not want to run this command. As the subscription-manager manual states:

CLEAN OPTIONS
    The clean command removes all of the subscription and identity data from the local system without affecting the system information  in
    the  subscription management service.  This means that any of the subscriptions applied to the system are not available for other sys‐
    tems to use. The clean command is useful in cases where the local subscription information is corrupted or lost somehow, and the  sys‐
    tem will be re-registered using the register --consumerid=EXISTING_ID command.

More often than not, you'd want to use the subscription-manager refresh or subscription-manager unregister commands (depending on the circumstances)

The subscription-manager clean command is equivalent to wiping the local system's identity WITHOUT informing the system it is registered to. (For the former RHN users, this is equivalent to deleting /etc/sysconfig/rhn/systemid). Ifsubscription-manager clean` is run, one of the following should happen:

• Manual intervention should occur to delete the systems profile if the system is being retired, as its profile may still have subscriptions attached that you may want to use elsewhere. OR
• Manual intervention should occur to reconnect the system to its old profile.

Assume that by accident, the subscription-manager clean command was run on a system. How do we recover from accidentally running subscription-manager clean?

On this test system, let's attach a subscription. I'll use a Satellite subscription in this example:

Find a Satellite sub.

#subscription-manager list --all \
  --available --matches 'Red Hat Satellite'
+-------------------------------------------+
    Available Subscriptions
+-------------------------------------------+
Subscription Name:   Red Hat Satellite
Provides:            Red Hat Satellite Capsule Beta
                     Red Hat Software Collections (for RHEL Server)
                     Red Hat Satellite Capsule
                     Red Hat Satellite with Embedded Oracle
                     Red Hat Beta
                     Red Hat Satellite Beta
                     Red Hat Satellite 6 Beta
                     Red Hat Enterprise Linux High Availability (for RHEL Server)
                     Red Hat Enterprise Linux Server
                     Red Hat Satellite
                     Red Hat Software Collections Beta (for RHEL Server)
                     Red Hat Enterprise Linux Load Balancer (for RHEL Server)
                     Red Hat Satellite 5 Managed DB
SKU:                 MCT0370
Contract:            10881778
Pool ID:             8a85f98152d000770152d1d330140fee
Provides Management: Yes
Available:           12
Suggested:           1
Service Level:       Premium
Service Type:        L1-L3
Subscription Type:   Standard
Ends:                02/10/2017
System Type:         Physical

Attach the Satellite sub.

#subscription-manager attach --pool 8a85f98152d000770152d1d330140fee

Next, let's run subscription-manager clean to wipe the systems identity.

# subscription-manager clean
All local data removed

And now let's run yum or subscription-manager commands to try to install content or work with subscriptions.

#yum repolist
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.
repolist: 0

#subscription-manager identity
This system is not yet registered. Try 'subscription-manager register --help' for more information.

The system believes it is unregistered. We could re-register the system normally, but that would potentially consume an additional subscription. (Since we may not have deleted the old profile yet). How do we reconnect this system to its old profile?

Luckily, subscription-manager has an option for this provided via the --consumerid parameter to the subscription-manager register command.

But we need the consumerid. And it can be found in one of two ways:

• In /var/log/rhsm/rhsm.log.

# grep 'Consumer Identity' /var/log/rhsm/rhsm.log
 @managercli.py:359 - Consumer Identity name=client.example.com uuid=760d71de-f96f-4483-9d87-3f3307f02052

• Or via the Customer Portal.

Visit the systems page, find the system in question and you'll find the system's UUID listed.

Example (Click to Enlarge) Now that we have the systems UUID (760d71de-f96f-4483-9d87-3f3307f02052) again, we can re-register with using the --consumerid parameter

# subscription-manager register \
 --consumerid=760d71de-f96f-4483-9d87-3f3307f02052
Registering to: subscription.rhsm.redhat.com:443/subscription
Username:[REDACTED]
Password:
The system has been registered with ID: 760d71de-f96f-4483-9d87-3f3307f02052

And let's check with subscription-manager status & subscription-manager list --consumed

# subscription-manager status
+-------------------------------------------+
   System Status Details
+-------------------------------------------+
Overall Status: Current


#subscription-manager list --consumed
+-------------------------------------------+
   Consumed Subscriptions
+-------------------------------------------+
Subscription Name:   Red Hat Satellite
Provides:            Red Hat Satellite
                     Red Hat Enterprise Linux Server
                     Red Hat Beta
                     Red Hat Software Collections (for RHEL Server)
                     Red Hat Satellite Beta
                     Red Hat Satellite 5 Managed DB Beta
                     Red Hat Software Collections Beta (for RHEL Server)
                     Red Hat Satellite 6 Beta
                     Red Hat Satellite Capsule Beta
                     Red Hat Enterprise Linux Load Balancer (for RHEL Server)
                     Red Hat Satellite 5 Managed DB
                     Red Hat Satellite with Embedded Oracle
                     Red Hat Satellite Capsule
                     Red Hat Enterprise Linux High Availability (for RHEL Server)
SKU:                 MCT0370
Contract:            10881778
Account:             5644938
Serial:              8242148226459104076
Pool ID:             8a85f98152d000770152d1d330140fee
Provides Management: Yes
Active:              True
Quantity Used:       1
Service Level:       Premium
Service Type:        L1-L3
Status Details:      Subscription is current
Subscription Type:   Standard
Starts:              02/11/2016
Ends:                02/10/2017
System Type:         Physical

SUCCESS!!. The --consumerid parameter is useful not only in this usage, but also if a server is rebuilt and you want to attach to its previous profile.

Advanced usage

As the identity certificate is used to authenticate the client, it can be leveraged to grab information about the guest from the API.

Using the curl command you can determine this information for Red Hat Subscription Management. First, you need to know the UUID of the system you wish to grab this data for. This can be gathered from the 'system identity' field of the subscription-manager identity command. (or from rct cat-cert /etc/pki/consumer/cert.pem as previously shown)

$ subscription-manager identity
system identity: 760d71de-f96f-4483-9d87-3f3307f02052
name: client.example.com
org name: [REDACTED]
org ID: [REDACTED]

Next, issue a curl command to gather this data

UUID=760d71de-f96f-4483-9d87-3f3307f02052
curl -sk \
 --cert /etc/pki/consumer/cert.pem \
 --key /etc/pki/consumer/key.pem \
 -X GET https://subscription.rhsm.redhat.com/subscription/consumers/$UUID/ | json_reformat

Note, as you are using the systems own identity certificate for authentication, it can only query data about itself. Username/password authentication is needed to query all the hosts in an account. This method can be used to gather other properties of hosts, which may not be exposed via RHSM's Web UI, or to get data (like the system's facts) in a more structured format (JSON)

Further reading

• Subscription-manager for the former Red Hat Network User: Part 1
• Subscription-manager for the former Red Hat Network User: Part 2 - Subscription-manager learns grep
• Subscription-manager for the former Red Hat Network User: Part 3 - Understanding virt-who
• Subscription-manager for the former Red Hat Network User: Part 4 - Understanding Subscription Manifests
• Subscription-manager for the former Red Hat Network User: Part 5 - working with subscriptions that require virt-who
• Subscription-manager for the former Red Hat Network User: Part 6 - understanding and improving the renewal experience
• Subscription-manager for the former Red Hat Network User: Part 7 - understanding the Red Hat Content Delivery Network
• Subscription-manager for the former Red Hat Network User: Part 8 - Product Certificates
• Subscription-manager for the former Red Hat Network User: Part 9 - A Case Study with activation keys.
  -Subscription-manager for the former Red Hat Network User: Part 10 - Instance Based Subscriptions
• Activation Key Enhancements with Red Hat Satellite 6.1
• Red Hat Satellite Virtual Instances Guide