subscription-manager(8) - Linux man page

Name

subscription-manager - Register machines and manage subscriptions to products.

Synopsis

subscription-manager command [options]

Description

subscription-manager is a client program that registers a system with the Certificate-Based Red Hat Network. To register your system with RHN Classic or with an RHN Satellite 5.x system, then use the rhn_register tool.

Red Hat provides content updates and support by issuing subscriptions for its products. These subscriptions are allocated to systems (machines); once a system is subscribed to content, it is entitled to install and update that software product. IT administrators need to track these subscriptions and how they are assigned. This entitlement and subscription management is a feature available for Red Hat platforms version 5.7 (and later) and version 6.1 (and later).

For RHEL systems, content is delivered through the Red Hat Customer Portal. Subscriptions and systems are managed globally through the Red Hat entitlement service, which is integrated with the Customer Portal. Subscriptions are managed for the local system by using the Red Hat Subscription Manager tool. Subscription Manager is a local client which connects a system with the entitlement service.

subscription-manager is the command-line based client for the Red Hat Subscription Manager tool.

The Subscription Manager performs several key operations:

* It registers machines to the Red Hat entitlement service and adds the machine to the systems inventory. Once a machine is registered, it can receive updates based on its subscriptions to any kind of software products.

* It lists both available and used (consumed) subscriptions.

* It allows administrators to both subscribe and unsubscribe a system from specific subscriptions.

Subscription Manager can be used to autosubscribe a system, as well. The subscription-manager command can even be invoked as part of a kickstart process.

Available subscriptions are based on the specific information about the machine's architecture. An entitlement is only considered available if the platform and hardware can support that specific product.

Subscription Manager also collects and summarizes system facts related it its hardware, operating system, and other characteristics. These facts can be edited in the Subscription Manager configuration and displayed through Subscription Manager.

There is also a Subscription Manager GUI, which can be invoked simply by running subscription-manager-gui from the command line.

Entitlement and subscription management is only available for RHEL 5.7/6.1 and later systems. Older systems should register to Red Hat Network Classic using the rhn_register command.

Commands And Options

subscription-manager has specific options available for each command, depending on what operation is being performed. The Subscription Manager commands are related to the different subscription operations:

1. register

2. unregister

3. identity

4. activate

5. subscribe

6. unsubscribe

7. refresh

8. list

9. facts

10. clean

COMMON OPTIONS

-h, --help

Prints the specific help information for the given command.

--debug=DEBUG

Sets the debug level to use for verbose output.

--proxy=PROXY

Uses an HTTP proxy. The PROXY name has the format hostname:port.

--proxyuser=PROXYUSERNAME

Gives the username to use to authenticate to the HTTP proxy.

--proxypass=PROXYPASSWORD

Gives the password to use to authenticate to the HTTP proxy.

REGISTER OPTIONS

The register command registers a new machine to the entitlement service.

--username=USERNAME

Gives the username for the account which is registering the system; this user account is usually tied to the user account for the content delivery system which supplies the content. Optional, for user-based authentication.

--password=PASSWORD

Gives the user account password. This is required.

--type=CONSUMERTYPE

Sets the type of consumer to register. Most systems will use the default value of system. For development or test systems, this can be

person , which indicates a personal (rather than organizational) entitlement subscription. Other systems can be candlepin for a local content service or domain for an IP domain.

--name=CONSUMERNAME

Sets the name of the consumer (machine) to register. This defaults to be the same as the hostname.

--consumerid=CONSUMERID

References an existing consumer ID to reregister a system. The consumer ID is used as an inventory number for the system in the entitlements service database. If the entitlements data are lost or corrupted, reregistering the system restores it.

--autosubscribe

Automatically subscribes this system to the best-matched compatible subscription.

--force

Registers the system even if it is already registered. Normally, any register operations will fail if the machine is already registered. With --force, the existing consumer entry is unregistered first, all of its subscriptions are returned to the pool, and then the consumer is registered as a new consumer.

UNREGISTER OPTIONS

The unregister command unregisters a machine, which strips its subscriptions and removes the machine from the entitlement service.

This command has no options.

IDENTITY OPTIONS

The identity command handles the UUID of a system, which identifies the system to the entitlement service after registration. This command can simply return the UUID or it can be used to restore the registration of a previously-registered system to the entitlement service.

--regenerate

Requests that the entitlement service issue a new identity certificate for the system, using an existing UUID in the original identity certificate. If this is used alone, then the identity command also uses the original identity certificate to bind to the entitlement server, using certificate-based authentication.

--username=USERNAME

Gives the username for the account which is registering the system; this user account is usually tied to the user account for the content delivery system which supplies the content. Optional, for user-based authentication.

--password=PASSWORD

Gives the user account password. Optional, for user-based authentication.

--force

Regenerates the identity certificate for the system using username/password authentication. This is used with the --regenerate option. --regenerate alone will use an existing identity certificate to authenticate to the entitlement service. If the certificate is missing or corrupted or in other circumstances, then it may be better to use user authentication rather than certificate-based authentication. In that case, the --force option requires the username or password to be given either as an argument or in response to a prompt.

ACTIVATE OPTIONS

The activate command is used for machines that are purchased from third-party vendors that include a subscription. The activation process essentially autosubscribes the machine to the pre-selected subscription that the vendor supplied.

--email=EMAIL

Gives the email account to send the activation notification message to.

--email_locale=LOCALE

Sets the locale to use for the message. If none is given, then it defaults to the local system's locale.

SUBSCRIBE OPTIONS

The subscribe command allocates a specific subscription to the machine.

--pool=POOLID

Gives the ID for the entitlements pool (collection of products) to subscribe the machine to. This option is required, unless --auto is used.

--auto

Automatically subscribes this system to the best-matched compatible subscription or subscriptions.

UNSUBSCRIBE OPTIONS

The unsubscribe command removes a subscription allocation from the machine. (This does not uninstall the associated products.)

--serial=SERIALNUMBER

Gives the serial number of the entitlement certificate for the specific product that is being unsubscribed. Entitlement certificates for subscribed products are in a certificate, in /etc/pki/entitlement/<serial_number>.pem.

--all

Unsubscribes the system from all of the products it's subscribed to.

REFRESH OPTIONS

The refresh command pulls the latest entitlement data from the server. Normally, the system polls the entitlement server at a set interval (4 hours by default) to check for any changes in the available subscriptions. The refresh command checks with the entitlement server right then, outside the normal interval.

This command has no options.

LIST OPTIONS

The list command lists all of the subscriptions that are compatible with a machine. The options allow the list to be filtered by subscriptions that are used by the machine or unused subscriptions that are available to the machine.

--available

Lists available subscriptions which the machine has not subscribed to.

--consumed

Lists all of the subscriptions that the machine is currently subscribed to.

--ondate=YYYY-MM-DD

Sets the date to use to search for active and available subscriptions. The default (if not explicitly passed) is today's date; using a later date looks for subscriptions which will be active then. This is only used with the --available option.

--installed

Lists products which are currently installed on the system which may (or may not) have subscriptions associated with them, as well as subscribed products which may (or may not) be installed.

--all

Lists all possible subscriptions that have been purchased by the organization, even if they don't match the architecture of the system. This is used with the --available option.

FACTS OPTIONS

The facts command lists the system information, like the release version, number of CPUs, and other architecture information.

--list

Lists the system information. These are simple attribute: value pairs that reflect much of the information in the /etc/sysconfig directory.

cpu.architecture: x86_64
cpu.core(s)_per_socket: 1
cpu.cpu(s): 2
cpu.cpu_family: 6
cpu.cpu_mhz: 1861.776
cpu.cpu_op-mode(s): 64-bit
cpu.cpu_socket(s): 2
cpu.hypervisor_vendor: KVM
cpu.model: 2
cpu.numa_node(s): 1
cpu.numa_node0_cpu(s): 0,1
cpu.stepping: 3
cpu.thread(s)_per_core: 1
cpu.vendor_id: GenuineIntel
cpu.virtualization_type: full
distribution.id: Santiago
distribution.name: Red Hat Enterprise Linux Workstation
distribution.version: 6.1
----

--update

Updates the system information. This is particularly important whenever there is a hardware change (such as adding a CPU) or a system upgrade because these changes can affect the subscriptions that are compatible with the system.

CLEAN OPTIONS

The clean command removes all of the subscription and identity data from the local system without affecting the consumer information in the entitlement service. This means that any of the subscriptions consumed by the system are still consumed and are not available for other systems to use. The clean command is useful in cases where the local entitlement information is corrupted or lost somehow, and the system will be reregistered using the register --consumerid=EXISTING_ID command.

This command has no options.

Usage

subscription-manager has two major tasks:

1. Handling the registration for a given system to an entitlement service

2. Handling the product subscriptions for a machine.

subscription-manager makes it easier for network administrators to maintain parity between software subscriptions and updates and their installed products by tracking and managing what machines are subscribed to and when those subscriptions expire or are exceeded.

REGISTERING AND UNREGISTERING MACHINES

A machine is either registered to an entitlement and content service -- which makes all of the subscriptions available to the machine -- or it is not registered. Unregistered machines necessarily lack valid software entitlements because there is no way to record that the subscriptions have been used or to renew them.

Machines are usually registered to an entitlement service as part of their initial configuration, such as the firstboot or kickstart process. However, machines can be registered manually after they are configured, can be removed from a content service, or reregistered.

If a machine has never been registered (not even during firstboot), then the register command will register the machine with whatever entitlement service is configured in the /etc/rhsm/rhsm.conf file. This command requires, at a minimum, the username and password for an account to connect to the entitlement service. If the credentials aren't passed with the command, then subscription-manager prompts for the username and password interactively.

For example:

subscription-manager register --username=admin --password=secret

Some information is assigned automatically. Subscription Manager automatically generates a unique consumer ID for the system which is used by the entitlement service and it assigns a consumer type, which indicates what kinds of software are available for the machine. The name for the consumer entry can be manually assigned (for use within a local inventory system, for instance). A handful of subscriptions (such as specialized servers for content or identity management) have their own specific consumer type. For example:

subscription-manager register --username=admin --password=secret --type=system --name=server1

If a system is registered and then somehow its entitlement information is lost -- a drive crashes or the certificates are deleted or corrupted -- the system can be reregistered, with all of its subscriptions restored, by registering with the existing consumer ID.

subscription-manager register --username=admin --password=secret --consumerid=1234abcd

A consumer uses an SSL client certificate (its identity certificate) to authenticate to the entitlements system to check for updates or changes to subscriptions. If the identity certificate is lost or corrupted, it can be regenerated using the identity command.

subscription-manager identity --regenerate

Using the --force option will prompt for the username and password for the account, if one isn't given, and then return the new consumer ID and the hostname of the registered system.

subscription-manager identity --force
Username: jsmith
Password:
eff9a4c9-3579-49e5-a52f-83f2db29ab52 server.example.com

A machine is unregistered and removed as a consumer from the entitlements service simply by running the unregister command. Unregistering and unsubscribing a service can free up entitlement subscriptions when a machine is taken offline or moved to a different department.

subscription-manager unregister

LISTING, SUBSCRIBING, AND UNSUBSCRIBING TO PRODUCTS

A subscription is essentially the right to install, use, and receive updates for a Red Hat product. (Sometimes multiple individual software products are bundled together into a single subscription.) When a machine is registered, the entitlements and content service is aware of the machine and has a list of all of the possible product subscriptions that the machine can install and use. A machine is allocated a product subscription by subscribing to the entitlement pool that makes that product available. A machine releases that entitlement (meaning, it unassigns that product so that another machine can use that entitlement count) by unsubscribing.

list command shows you what subscriptions are available specifically to the system (meaning subscriptions which are active, have available quantities, and match the hardware and architecture) or all subscriptions for the organization. Using the --ondate option shows subscriptions that are or will be active at a specific time (otherwise, it shows subscriptions which are active today).

subscription-manager list --available --ondate=2012-01-31
+-------------------------------------------+
    Available Subscriptions
+-------------------------------------------+

ProductName:        Awesome OS Server
ProductId:          AOS001
PoolId:             8a90f88e2e3802ab012e380345de0203
Quantity:           5
Expires:            2012-02-17

The list command can also be used to show what products you currently have installed, as a way of tracking what products you have versus what subscriptions you have on the machine.

subscription-manager list --installed

+-------------------------------------------+
    Installed Product Status
+-------------------------------------------+

ProductName:         Red Hat Enterprise Linux Entitlement
Status:              Not Subscribed
Expires:
Subscription:
ContractNumber:
AccountNumber:

ProductName:         Awesome OS Server
Status:              Not Installed
Expires:             2012-02-20
Subscription:        54129829316535230
ContractNumber:      39
AccountNumber:       12331131231

Subscribing a machine requires the ID for the entitlement pool (the --pool option). For example:

subscription-manager subscribe --pool=ff8080812bc382e3012bc3845da100d2

As with the register command, the system can be autosubscribed to the best-fitting subscriptions using the --auto option:

subscription-manager subscribe --auto

Unsubscribing a machine removes it from the product or entitlement pool, which releases that entitlement subscription it had consumed. The machine remains registered with the entitlement service. Each product has an identifying X.509 certificate installed with it. To unsubscribe from a subscription for a specific product, specify the serial number of the certificate:

subscription-manager unsubscribe --serial=1128750306742160

Giving the unsubscribe command with the --all option unsubscribes the machine from every subscription it has consumed.

An option with registration, --autosubscribe , will automatically subscribe the newly-registered system to the entitlements pool which best matches the system architecture and configuration. This option allows the system to be subscribed as part of the registration process, rather than separately managing subscriptions.

subscription-manager register --username=admin --password=secret --autosubscribe

UPDATING FACTS

The information about a system, such as its hardware and CPU, its operating system versions, and memory, are collected by Subscription Manager in a list of facts. Subscription Manager uses these facts to determine what purchased entitlements are compatible with the system. Whenever these facts changes (such as installing an additional CPU), the facts can be updated immediately using the facts command.

subscription-manager facts --update

The collected facts can also be overridden by creating a JSON file in the /etc/rhsm/facts/ directory. These have simple formats that define a fact and value:

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

Any fact override file must have a .facts extension.

When these fact files are added, running the facts command will update the collected facts with the new, manual facts or values.

ENTITLEMENTS AND KICKSTART

The subscription-manager tool can be run as a post-install script as part of the kickstart installation process. This allows entitlement management (registration and subscription) to be automated along with installation. For example:

%post --log=/root/ks-post.log
/usr/sbin/subscription-manager register --username admin --password secret --autosubscribe --force

GETTING INFORMATION FROM CERTIFICATES

Both Subscription Manager and product information is contained in X.509 certificates. To obtain this information, use tools like openssl or pk12util to pretty-print the certificate information. For example:

openssl x509 -text -in /etc/pki/consumer/cert.pem

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 9 (0x9)
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: CN=server.example.com, C=US, L=Mountain View
        Validity
            Not Before: Sep 21 19:01:01 2010 GMT
            Not After : Sep 21 19:01:01 2011 GMT
        Subject: CN=78cf3c59-24ec-4228-a039-1b554ea21319
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:cd:22:86:2b:77:1b:40:b2:be:8e:06:8e:b8:df:

Files

* /etc/pki/consumer/*.pem

* /etc/pki/entitlement/<serial>.pem

* /etc/pki/product/*.pem

* /etc/rhsm/rhsm.conf

* /etc/rhsm/facts/*.facts

Authors

Deon Lackey, <dlackey@redhat.com>, and Pradeep Kilambi, <pkilambi@redhat.com>