# redhat_subscription – Manage registration and subscriptions to RHSM using the `subscription-manager` command

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## Synopsis

- Manage registration and subscription to the Red Hat Subscription Management entitlement platform using the `subscription-manager` command

## Requirements

The below requirements are needed on the host that executes this module.

- subscription-manager

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
activationkey - |  | supply an activation key for use with registration

auto_attach
boolean
added in 2.5

Choices:
- no ←
- yes

Upon successful registration, auto-consume available subscriptions
Added in favor of deprecated autosubscribe in 2.5.
aliases: autosubscribe

consumer_id - |  | References an existing consumer ID to resume using a previous registration for this system. If the system's identity certificate is lost or corrupted, this option allows it to resume using its previous identity and subscriptions. The default is to not specify a consumer ID so a new ID is created.
consumer_name - |  | Name of the system to register, defaults to the hostname
consumer_type - |  | The type of unit to register, defaults to system
environment - |  | Register with a specific environment in the destination org. Used with Red Hat Satellite 6.x or Katello

force_register
boolean

Choices:
- no ←
- yes

Register the system even if it is already registered

org_id - |  | Organization ID to use in conjunction with activationkey
password - |  | access.redhat.com or Sat6 password
pool - | Default: "^$" | Specify a subscription pool name to consume. Regular expressions accepted. Use pool_ids instead if possible, as it is much faster. Mutually exclusive with pool_ids.

pool_ids
-
added in 2.4

Default:
[]

Specify subscription pool IDs to consume. Prefer over pool when possible as it is much faster. A pool ID may be specified as a `string` - just the pool ID (ex. `0123456789abcdef0123456789abcdef`), or as a `dict` with the pool ID as the key, and a quantity as the value (ex. `0123456789abcdef0123456789abcdef: 2`. If the quantity is provided, it is used to consume multiple entitlements from a pool (the pool must support this). Mutually exclusive with pool.

release - added in 2.8 |  | Set a release version
rhsm_baseurl - |  | Specify CDN baseurl
rhsm_repo_ca_cert - added in 2.7 |  | Specify an alternative location for a CA certificate for CDN
server_hostname - |  | Specify an alternative Red Hat Subscription Management or Sat6 server
server_insecure - |  | Enable or disable https server certificate verification when connecting to `server_hostname`
server_proxy_hostname - added in 2.4 |  | Specify a HTTP proxy hostname
server_proxy_password - added in 2.4 |  | Specify a password for HTTP proxy with basic authentication
server_proxy_port - added in 2.4 |  | Specify a HTTP proxy port
server_proxy_user - added in 2.4 |  | Specify a user for HTTP proxy with basic authentication

state
-

Choices:
- present ←
- absent

whether to register and subscribe (`present`), or unregister (`absent`) a system

syspurpose
dictionary
added in 2.9

Default:
{}

Set syspurpose attributes in file `/etc/rhsm/syspurpose/syspurpose.json` and synchronize these attributes with RHSM server. Syspurpose attributes help attach the most appropriate subscriptions to the system automatically. When `syspurpose.json` file already contains some attributes, then new attributes overwrite existing attributes. When some attribute is not listed in the new list of attributes, the existing attribute will be removed from `syspurpose.json` file. Unknown attributes are ignored.

| addons list |  | Syspurpose attribute addons
| role - |  | Syspurpose attribute role
| service_level_agreement - |  | Syspurpose attribute service_level_agreement

sync
boolean

Choices:
- no ←
- yes

When this option is true, then syspurpose attributes are synchronized with RHSM server immediately. When this option is false, then syspurpose attributes will be synchronized with RHSM server by rhsmcertd daemon.

| usage - |  | Syspurpose attribute usage
username - |  | access.redhat.com or Sat6 username

## Notes

Note

- In order to register a system, subscription-manager requires either a username and password, or an activationkey and an Organization ID.
- Since 2.5 values for server_hostname, server_insecure, rhsm_baseurl, server_proxy_hostname, server_proxy_port, server_proxy_user and server_proxy_password are no longer taken from the `/etc/rhsm/rhsm.conf` config file and default to None.

## Examples

    - name: Register as user (joe_user) with password (somepass) and auto-subscribe to available content.
      redhat_subscription:
        state: present
        username: joe_user
        password: somepass
        auto_attach: true

    - name: Same as above but subscribe to a specific pool by ID.
      redhat_subscription:
        state: present
        username: joe_user
        password: somepass
        pool_ids: 0123456789abcdef0123456789abcdef

    - name: Register and subscribe to multiple pools.
      redhat_subscription:
        state: present
        username: joe_user
        password: somepass
        pool_ids:
          - 0123456789abcdef0123456789abcdef
          - 1123456789abcdef0123456789abcdef

    - name: Same as above but consume multiple entitlements.
      redhat_subscription:
        state: present
        username: joe_user
        password: somepass
        pool_ids:
          - 0123456789abcdef0123456789abcdef: 2
          - 1123456789abcdef0123456789abcdef: 4

    - name: Register and pull existing system data.
      redhat_subscription:
        state: present
        username: joe_user
        password: somepass
        consumer_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    - name: Register with activationkey and consume subscriptions matching Red Hat Enterprise Server or Red Hat Virtualization
      redhat_subscription:
        state: present
        activationkey: 1-222333444
        org_id: 222333444
        pool: '^(Red Hat Enterprise Server|Red Hat Virtualization)$'

    - name: Update the consumed subscriptions from the previous example (remove Red Hat Virtualization subscription)
      redhat_subscription:
        state: present
        activationkey: 1-222333444
        org_id: 222333444
        pool: '^Red Hat Enterprise Server$'

    - name: Register as user credentials into given environment (against Red Hat Satellite 6.x), and auto-subscribe.
      redhat_subscription:
        state: present
        username: joe_user
        password: somepass
        environment: Library
        auto_attach: true

    - name: Register as user (joe_user) with password (somepass) and a specific release
      redhat_subscription:
        state: present
        username: joe_user
        password: somepass
        release: 7.4

    - name: Register as user (joe_user) with password (somepass), set syspurpose attributes and synchronize them with server
      redhat_subscription:
        state: present
        username: joe_user
        password: somepass
        auto_attach: true
        syspurpose:
          usage: "Production"
          role: "Red Hat Enterprise Server"
          service_level_agreement: "Premium"
          addons:
            - addon1
            - addon2
          sync: true

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
subscribed_pool_ids complex | success | List of pool IDs to which system is now subscribed Sample: {'8a85f9815ab905d3015ab928c7005de4': '1'}

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Barnaby Court (@barnabycourt)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.