Configuring the Subscription Service

CentOS Subscription Manager Configuration Files

The primary configuration file for CentOS Subscription Manager, both the GUI and CLI tools, is the rhsm.conf configuration file. There are other support files that either influence the CentOS Subscription Manager service or can help administrators better use the Subscription Manager.

All Files Used by CentOS Subscription Manager

All of the files related to the configuration of CentOS Subscription Manager are used by both the GUI and CLI; there's no separate configuration.

Table 14.6. CentOS Subscription Manager Files and Directories

About the rhsm.conf File

The main configuration file for the Subscription Manager is rhsm.conf. This file configures several important aspects of how CentOS Subscription Manager interacts with both entitlements and content services:

• The subscription service connection information, including the server host and port

• The content service to use, in the form of a web address
• The location of all of the different certificates used by the subscription service, including CA certificates for SSL authentication, identity certificates for the system, and entitlement and product certificates

The rhsm.conf file is divided into three sections. Two major sections defined the subscription service ([server]) and content and product delivery ([rhsm]). The third section relates to the rhsmcertd daemon. Each assertion is a simple attribute= value pair. Any of the default values can be edited; all possible attributes are present and active in the default rhsm.conf file.

Example 14.9. Default rhsm.conf File

# CentOS Subscription Manager Configuration File:
# Unified Entitlement Platform Configuration
[server]
# Server hostname:
hostname = subscription.rhn.redhat.com
# Server prefix:
prefix = /subscription
# Server port:
port = 443
# Set to 1 to disable certificate validation:
insecure = 0
# Set the depth of certs which should be checked
# when validating a certificate
ssl_verify_depth = 3
# Server CA certificate location:
ca_cert_dir = /etc/rhsm/ca/
# an http proxy server to use
proxy_hostname =
# port for http proxy server
proxy_port =
# user name for authenticating to an http proxy, if needed
proxy_user =
# password for basic http proxy auth, if needed
proxy_password =
[rhsm]
# Content base URL:
baseurl= https://cdn.redhat.com
# Default CA cert to use when generating yum repo configs:
repo_ca_cert = %(ca_cert_dir)sredhat-uep.pem
# Where the certificates should be stored
productCertDir = /etc/pki/product
entitlementCertDir = /etc/pki/entitlement
consumerCertDir = /etc/pki/consumer
[rhsmcertd]
# Frequency of certificate refresh (in minutes):
certFrequency = 240
# Frequency of autoheal check (1440 min = 1 day):
healFrequency = 1440

Table 14.7. rhsm.conf Parameters

Using the config Command

subscription-manager has a subcommand that can change the rhsm.conf configuration file. Almost all of the connection information used by Subscription Manager to access the subscription server, content server, and any proxies is set in the configuration file, as well as general configuration parameters like the frequency Subscription Manager checks for entitlements updates. There are major divisions in the rhsm.conf file, such as [server] which is used to configure the subscription server. When changing the Subscription Manager configuration, the settings are identified with the format section.parameter and then the new value. For example:

server.hostname=newsubscription.example.com

When changing the value for a parameter, the parameter is passed as an argument to the config command:

[root@server1 ~]# subscription-manager config --section.parameter=newValue

For example, to change the hostname of the subscription service:

[root@server1 ~]# subscription-manager config --server.hostname=subscription.example.com

All of the rhsm.conf file parameters are listed in Table 14.7, "rhsm.conf Parameters". This is most commonly used to change connection settings:

• server.hostname (subscription server)

• server.proxy
• server.proxy_port
• server.proxy_user
• server.proxy_password
• rhsm.baseurl (content server)
• rhsm.certFrequency

The config command also has a --remove option. This deletes the the current value for the parameter without supplying a new parameter. A blank value tells Subscription Manager to use any default values that are set for that parameter rather than a user-defined value. For example:

[root@server1 ~]# subscription-manager config --remove=rhsm.certFrequency
The default value for rhsm.certFrequency will now be used.

If a value does not have a default, then the command returns simply that the value has been removed:

[root@server1 ~]# subscription-manager config --remove=server.proxy
You have removed the value in section server for parameter proxy.

Using an HTTP Proxy

Some network environments may only allow external Internet access or access to content servers by going through an HTTP proxy.

Configuring an HTTP Proxy for GUI Use

The CentOS Subscription Manager GUI can be configured to use an HTTP proxy for all of its connections to the subscription service. (This is also an advanced configuration option at firstboot.) To configure the proxy:

subscription-manager-gui

• Click the Proxy Configuration button at the top of the window in the Tools area.
  
• Check the ...Connect to CentOS Network via an HTTP Proxy checkbox and enter the server location, in the format hostname:port.
  
• If the proxy requires a username/password to allow access, then also select the User authentication checkbox and fill in the user credentials.
• The configuration is automatically applied, so when the proxy is configured, simply close the window.

Configuring HTTP Proxy in the rhsm.conf File

The HTTP proxy settings can be configured in the rhsm.conf file; this is the same as configuring it in the Subscription Manager GUI. The proxy configuration is stored and used for every connection between the subscription service and the local system.

vim /etc/rhsm/rhsm.conf

• Change the settings in the [server] section that relate to the HTTP proxy. All parameters are described in Table 14.7, "rhsm.conf Parameters". There are four parameters directly related to the proxy:
  • proxy_hostname for the IP address or fully-qualified domain name of the proxy server; this is required.

  Leaving the proxy_hostname argument blank means that no HTTP proxy is used.

• proxy_port for the proxy server port.
• proxy_user for the user account to connect to the proxy; this may not be required, depending on the proxy server's configuration.
• proxy_password for the password for the user account to connect to the proxy; this may not be required, depending on the proxy server's configuration.

[server]
# an http proxy server to use
proxy_hostname = proxy.example.com
# port for http proxy server
proxy_port = 443
# user name for authenticating to an http proxy, if needed
proxy_user =
# password for basic http proxy auth, if needed
proxy_password =

Passing HTTP Proxy Information with subscription-manager Commands

Rather than using a permanently-configured HTTP proxy, as the GUI does, HTTP proxy information can be passed with a command invocations. The arguments listed in Table 14.8, "Proxy Arguments" are available to every command used with subscription-manager.

Table 14.8. Proxy Arguments

The proxy information can be passed with any subscription-manager operation. For example:

[root@server1 ~]# subscription-manager subscribe --pool=ff8080812bc382e3012bc3845ca000cb --proxy=proxy.example.com:8443 --proxyuser=jsmith --proxypass=secret

Changing the Subscription Server

The Subscription Manager usually connects to the subscription service, and the public server is configured in the rhsm.conf file. The subscription service connection settings are in the [server] section of the configuration file.

vim /etc/rhsm/rhsm.conf

• Change the settings in the [server] section that relate to the subscription service connection. All parameters are described in Table 14.7, "rhsm.conf Parameters". There are three parameters directly related to the connection:
  • hostname for the IP address or fully-qualified domain name of the machine
• prefix for the subscription service directory
• port for the subscription service port

[server]
hostname=entitlements.server.example.com
prefix=/candlepin
port=8443

Configuring CentOS Subscription Manager to Use a Local Content Provider

By default, the Subscription Manager is configured to use CentOS's content delivery service, which is available at https://cdn.redhat.com. This can be changed to use a different external content delivery system or to use an organization-managed content system, such as Subscription Asset Manager.

vim /etc/rhsm/rhsm.conf

• Change the baseurl directive in the [rhsm] section. This is the full URL to the service.

  [rhsm]
  # Content base URL:
  baseurl= http://content.example.com/content

Managing Secure Connections to the Subscription Server

CentOS Subscription Manager assumes, by default, that the subscription clients connect to the subscription service using a secure (SSL) connection. This requires that the CA certificate of the subscription service be downloaded and available locally for the client and that the appropriate connections be configured.

vim /etc/rhsm/rhsm.conf

• Change the settings in the [server] section that relate to a secure connection. All parameters are described in Table 14.7, "rhsm.conf Parameters". There are three parameters directly related to the connection:
  • insecure to set whether to use a secure (0) or insecure (1) connection
• ca_cert_dir for the directory location for the CA certificate for authentication and verification
• port for the subscription service port; this should be an SSL port if a secure connection is required

[server]
port=8443
insecure = 1
ca_cert = /etc/rhsm/ca

Starting and Stopping the Subscription Service

The CentOS Subscription Manager daemon, rhsmcertd, runs as a service on the system. The daemon, by default, starts with the system, and it can be started, stopped, or checked with the service command.

service rhsmcertd status
rhsmcertd (pid 13084) is running...

Community Enterprise Linux has a tool called chkconfig which manages the automatic startup and shutdown settings for each process on the server, described in "chkconfig". When a system reboots, some services can be automatically restarted. chkconfig also defines startup settings for different run levels of the server.

The CentOS Subscription Manager service, which runs routinely to check for changes in the entitlements for an organization, can be controlled by chkconfig. By default, the CentOS Subscription Manager daemon, rhsmcertd, is configured to run at levels 3, 4, and 5, so that the service is started automatically when the server reboots.

The run level settings can be reset using chkconfig. For example, to enable run level 2:

chkconfig --level 2345 rhsmcertd on

To remove the rhsmcertd from the start list, change the run level settings off:

chkconfig --level 2345 rhsmcertd off

Community Enterprise Linux also has a GUI console that can manage the service and chkconfig settings.

• Open the Services link.

  The system-config-services package must be installed for the Services wizard to be available.

  
• Scroll to the rhsmcertd item in the list of services on the left, and then edit the service as desired.
  

Checking Logs

There are two log files maintained for CentOS Subscription Manager in the /var/log/rhsm directory:

• rhsm.log shows every invocation and result of running the Subscription Manager GUI or CLI

• rhsmcertd.log shows every time a new certificate is generated, which happens on a schedule defined by the certFrequency parameter in the rhsm.conf file.

The rhsm.log log contains the sequence of every Python call for every operation invoked through the Subscription Manager tools. Each entry has this format:

YYYY-MM-DD HH:MM:SS,process_id [MESSAGE_TYPE] call python_script response

The response in the log entry can be very complex, spanning multiple lines, or relatively simply, with just a status code.

Because each log entry in rhsm.log relates to the Python script or function that was called, there can be multiple log entries for a single operation.

Example 14.10. rhsm.log Entry

2010-10-01 17:27:57,874 [INFO] _request() @connection.py:97 - status code: 200
2010-10-01 17:27:57,875 [INFO] perform() @certlib.py:132 - updated:
Total updates: 0
Found (local) serial# []
Expected (UEP) serial# []
Added (new)
  <NONE>
Deleted (rogue):
  <NONE>
Expired (not deleted):
  <NONE>
Expired (deleted):
  <NONE>
2010-10-01 17:27:57,878 [INFO] __init__() @connection.py:193 - Using certificate authentication: key = /etc/pki/consumer/key.pem, cert = /etc/pki/consumer/cert.pem, ca = /etc/pki/CA/candlepin.pem, insecure = True
2010-10-01 17:27:57,878 [INFO] __init__() @connection.py:196 - Connection Established: host: candlepin1.devlab.phx1.redhat.com, port: 443, handler: /candlepin

The entries in the rhsmcertd.log file are much simpler. The log only records when the rhsmcertd daemon starts or stops and every time a certificate is updated.

Example 14.11. rhsmcertd.log Entry

Fri Oct  1 13:27:44 2010: started: interval = 240 minutes
Fri Oct  1 13:27:50 2010: certificates updated

Showing and Hiding Incompatible Subscriptions

The entitlements that are made available to a consumer are filtered, by default, according to whether the architecture for the product matches the architecture of the system. This is compatibility. The CentOS Subscription Manager can be configured to display even incompatible entitlements.

When running the command-line tools, the incompatible facts can be displayed simply by using the --all option:

[root@server1 ~]# subscription-manager list --available --all

To have the incompatible subscriptions displayed in the GUI and through the command-line by default, edit the rhsm.conf configuration file.

vim /etc/rhsm/rhsm.conf

• Change the showIncompatiblePools directive in the [rhsm] section. A value of 0 shows only compatible entitlements.

  [rhsm]
  # Content base URL:
  showIncompatiblePools = 1

Checking and Adding System Facts

Entitlements are available to a system based on whether the software is compatible with the system's architecture. For example, there are different products and subscriptions for 32-bit and 64-bit platforms. CentOS Subscription Manager determines compatibility by collecting a range of facts about the system's hardware and architecture and then comparing it with all available entitlements.

The collected facts can be viewed, updated to acknowledge a hardware or configuration change, or overridden to force compatibility in the specified areas.

The system facts are very similar to the information in /etc/redhat-release or /etc/sysconfig. In both the CentOS Subscription Manager GUI and CLI, the facts are represented as simple attribute: value pairs.

Updating the facts resends the information about the system to the CentOS subscription service so that it can update the list of subscriptions which match the system architecture. Updating the facts is a very good thing to do after hardware upgrades or other important system changes.

Checking Facts from the CentOS Subscription Manager UI

subscription-manager-gui

• In the Tools at the top of the window, click the View System Facts button.
  
• All of the current facts for the system are listed in the table, broken down into categories. Each category is in a closed list; to reveal all of the facts in that category, click the arrow by the category name.
  

  To update the facts, click the Update Facts button in the bottom right of the window.

Checking Facts with subscription-manager

To simply list the facts, run the facts with the --list option.

[root@server1 ~]# subscription-manager facts --list
cpu.architecture: i686
cpu.core(s)_per_socket: 4
cpu.cpu(s): 4
cpu.cpu_family: 6
cpu.cpu_mhz: 2000.010
cpu.cpu_op-mode(s): 32-bit, 64-bit
cpu.cpu_socket(s): 1
cpu.l1d_cache: 32K
cpu.l1i_cache: 32K
cpu.l2_cache: 6144K
cpu.model: 23
cpu.stepping: 6
cpu.thread(s)_per_core: 1
cpu.vendor_id: GenuineIntel
cpu.virtualization: VT-x
distribution.id: Santiago
distribution.name: Red Hat Enterprise Linux Workstation
distribution.version: 5
dmi.baseboard.manufacturer: IBM
dmi.baseboard.product_name: Server Blade
... [snip] ...

To update the facts after a system change, use the --update option with the facts command.

[root@server1 ~]# subscription-manager facts --update

Overriding the Default System Facts

The system facts, as collected, are stored in /var/lib/rhsm/facts/facts.facts. These facts are stored as attribute: value pairs, in a comma-separated list.

{"fact1": "value1","fact2": "value2"}

The primary file is generated and maintained by the Subscription Manager service. However, these values can be overridden to force architecture or platform compatibility (and thereby widening the available compatible subscriptions) by creating additional JSON facts files and dropping them in the /etc/rhsm/facts directory. These JSON files can override existing facts or even add new facts to be used by the subscription service.

Example 14.12. Example Facts Override File

vim /etc/rhsm/facts/my-example.facts
{"uname.machine": "x86","kernel_version": "2.6.32","physical_location": "MTV colo rack 5"}

Regenerating Identity Certificates

To regenerate the consumer's identity certificate (meaning it is revoked and replaced), use the identity command. Although not required, using the --force option will require the username and password and will cause the Subscription Manager to prompt for the credentials if they are not passed in the command:

[root@server1 ~]# subscription-manager identity --regenerate --force
Username: jsmith@example.com
Password:
Identity certificate has been regenerated.

Getting the System UUID

The consumer or system UUID is a unique identifier used in the inventory subscription service. This UUID can be used to re-register the system if there is some kind of corruption or for internal tracking. In the GUI ("Checking Facts from the CentOS Subscription Manager UI"), this is listed as one of the system facts, under the system category:

From the command-line, use the identity command to return the current UUID. The UUID is the Current identity is value.

[root@server1 ~]# subscription-manager identity
Current identity is: 63701087-f625-4519-8ab2-633bb50cb261
name: server1.example.com
org name: 6340056
org id: 8a85f981302cbaf201302d89931e059a

Viewing Package Profiles

A package profile is the list of installed packages on a system (regardless of its subscription status). CentOS Subscription Manager maintains a local list of installed packages to track the subscription status of the system. The package profile contains some general information about each package in the list:

• Package name

• Package version
• Epoch
• Publisher

This package manifest is always visible locally in the My Installed Software tab of the UI or by using the list --installed command with the command-line tools.

The Subscription Manager daemon, rhsmcertd, checks the system periodically - once when it is first registered and then when it runs a refresh operation every four hours - to get the most current list of installed products. When the system is registered and then whenever there is a change to the package list, Subscription Manager sends an updated package profile to the subscription service.

The package profile is stored in a cache file in /var/lib/rhsm/packages/.

Having an updated package profile for a system helps the subscription service identify compatible subscriptions.

Retrieving the Consumer ID, Registration Tokens, and Other Information

Some pieces of information are used frequently when managing entitlements using the subscription-manager script. Information like the consumer ID or subscription pool ID is pulled up and referenced automatically in the CentOS Subscription Manager UI, but it has to be entered manually in the command line.

Table 14.9, "Locations and Descriptions of Entitlement Data" lists common information that is used to manage subscriptions, the operations they're used in, and the places to find the data.

Table 14.9. Locations and Descriptions of Entitlement Data

[root@server1 ~]# subscription-manager identity
Current identity is: 63701087-f625-4519-8ab2-633bb50cb261
name: consumer-1.example.com
org name: 6340056
org id: 8a85f981302cbaf201302d89931e059a

openssl x509 -text -in /etc/pki/consumer/cert.pem
Certificate:
... snip ...
Subject: CN=7d133d55 876f 4f47 83eb 0ee931cb0a97

[root@server1 ~]# subscription-manager list --available
+----------------------+
Available Subscriptions
+----------------------+
ProductName: Community Enterprise Linux, Standard (up to 2 sockets) 3 year
ProductId: MCT0346F3
PoolId: ff8080812bc382e3012bc3845ca000cb
Quantity: 2
Expires: 2011-02-28

[root@server1 ~]# subscription-manager list --consumed
+-----------------------------+
Consumed Product Subscriptions
+-----------------------------+
ProductName: High availability (cluster suite)
ContractNumber: 0
SerialNumber: 11287514358600162
....

[root@server1 ~]# subscription-manager list --available
+----------------------+
Available Subscriptions
+----------------------+
ProductName: RHEL for Physical Servers
ProductId: MKT-rhel-server
... snip ...