Stackvora.tech

RHEL 9: register a system with Red Hat Subscription Manager

Properly registering a Red Hat Enterprise Linux (RHEL) system with Red Hat Subscription Management (RHSM) is a critical first step for accessing updates,…

Properly registering a Red Hat Enterprise Linux (RHEL) system with Red Hat Subscription Management (RHSM) is a critical first step for accessing updates, errata, support, and Red Hat's extensive software repositories. This process ensures your RHEL deployments remain secure, performant, and compliant. This guide details the manual registration process for RHEL 9 systems using the subscription-manager CLI, covering both direct and indirect connection scenarios.

Understanding Red Hat Subscription Manager (RHSM)

RHSM is Red Hat's system for managing subscriptions, entitlements, and content delivery for RHEL and other Red Hat products. When a RHEL system is registered, it establishes a secure connection to Red Hat's Content Delivery Network (CDN), allowing it to pull software packages, security updates, and access support resources.

Key components:

  • Subscription Service: Manages your purchased subscriptions and allocates them to registered systems.
  • Content Delivery Network (CDN): Hosts the RPM packages, ISOs, and other software artifacts.
  • subscription-manager CLI: The primary tool on RHEL systems for interacting with RHSM.
  • Customer Portal: A web interface for managing subscriptions, viewing registered systems, and downloading software.

Prerequisites for Registration

Before attempting to register your RHEL 9 system, ensure the following conditions are met:

  • Red Hat Account: You need an active Red Hat customer portal account with valid RHEL subscriptions.
  • Network Connectivity: The RHEL 9 system must have network access to Red Hat's CDN. This typically means access to subscription.rhsm.redhat.com on port 443 (HTTPS) and potentially other CDN endpoints.
  • Root Privileges: All subscription-manager commands require root privileges.
  • RHEL 9 Installation: A clean or existing RHEL 9 installation. This guide assumes a minimal installation with network configured.

Direct Registration with Username and Password

This is the most common method for individual systems directly connected to the internet.

Step 1: Check System Status

Before registering, it's good practice to check if the system is already registered or if there are any pending actions.

sudo subscription-manager status
sudo subscription-manager identity

If the system is unregistered, subscription-manager status will report "Overall Status: Unknown".

Step 2: Register the System

Use your Red Hat Customer Portal username and password. Replace YOUR_USERNAME with your actual Red Hat login.

sudo subscription-manager register --username="YOUR_USERNAME" --password="YOUR_PASSWORD" --auto-attach

Explanation of options:

  • --username="YOUR_USERNAME": Your Red Hat Customer Portal username.
  • --password="YOUR_PASSWORD": Your Red Hat Customer Portal password. It's generally not recommended to put passwords directly in shell history. If omitted, you will be prompted securely.
  • --auto-attach: This is crucial. It automatically finds and attaches the best available subscription to the registered system. Without this, the system registers but won't have active entitlements.

Upon successful registration, you will see output similar to:

Registering to: subscription.rhsm.redhat.com:443/subscription
The system has been registered with ID: [YOUR_SYSTEM_UUID]
The registered system name is: [YOUR_HOSTNAME]
Subscribed to: Red Hat Enterprise Linux for x86_64

Step 3: Verify Subscription Status

After registration, verify that the system is properly subscribed.

sudo subscription-manager status
sudo subscription-manager list --consumed

subscription-manager status should now show "Overall Status: Current". subscription-manager list --consumed will display details about the attached subscription, including its name, SKU, and expiration date.

Step 4: Enable Repositories and Update

Once subscribed, the appropriate RHEL repositories are automatically enabled. You can then perform system updates.

sudo dnf update -y

This command downloads and installs all available updates for your RHEL 9 system. If you want to list enabled repositories first:

sudo dnf repolist

Registration Using an Activation Key

Activation keys are ideal for automating registrations, especially in cloud environments or for large-scale deployments. They encapsulate user credentials and often pre-configure system groups and attached subscriptions.

Step 1: Create an Activation Key (Customer Portal)

This step is performed in the Red Hat Customer Portal (access.redhat.com/management):

  1. Navigate to Systems > Activation Keys.
  2. Click New Key.
  3. Provide a descriptive Name (e.g., rhel9-prod-key).
  4. Optionally, set a Usage Limit.
  5. Select the appropriate Subscriptions to attach. This is crucial for pre-attaching entitlements.
  6. Click Create. Note the generated key.

Step 2: Register the System with the Activation Key

On your RHEL 9 system, use the --activationkey and --org options.

sudo subscription-manager register --org="YOUR_ORG_ID" --activationkey="YOUR_ACTIVATION_KEY" --auto-attach

Explanation of options:

  • --org="YOUR_ORG_ID": Your Red Hat organization ID. You can find this in the Customer Portal under Systems > Overview or by running sudo subscription-manager identity on an already registered system.
  • --activationkey="YOUR_ACTIVATION_KEY": The key name you created in the Customer Portal.
  • --auto-attach: Ensures subscriptions defined in the activation key are applied.

Verify status and update as in the direct registration method.

Registration Through a Satellite Server

For large, on-premise environments, Red Hat Satellite is the preferred method. Satellite acts as a local proxy for Red Hat content, providing centralized management, content caching, and enhanced security. This section outlines the client-side steps; Satellite setup is outside the scope of this article.

Step 1: Install Katello Agent (Client)

On the RHEL 9 system, the Katello agent (katello-host-tools) and its dependencies are required for communicating with Satellite. You might need to temporarily register to Red Hat CDN or use an isolated repository to get these packages if the system is completely offline from Satellite initially.

sudo dnf install -y katello-host-tools subscription-manager

Step 2: Register to Satellite

Point the client to your Satellite server's URL. This typically involves downloading a CA certificate from the Satellite server first, if not automatically handled by Satellite's bootstrap scripts.

# Example if using Satellite's bootstrap script (recommended)
# This script configures the system with required CA certs and repository definitions.
sudo curl --insecure --output /tmp/bootstrap.sh https://satellite.example.com/pub/bootstrap.sh
sudo chmod +x /tmp/bootstrap.sh
sudo /tmp/bootstrap.sh -l "LOCATION_NAME" -o "ORG_NAME" -g "HOSTGROUP_NAME" -s # -s means subscription-manager based registration

# Manual registration if the above is not applicable or for troubleshooting
# First, ensure the Satellite's CA certificate is trusted.
# Replace satellite.example.com with your Satellite FQDN.
sudo subscription-manager clean
sudo subscription-manager register --org="YOUR_ORG_ID" \
  --serverurl="https://satellite.example.com:443/rhsm" \
  --baseurl="https://satellite.example.com/pulp/content" \
  --activationkey="YOUR_SATELLITE_ACTIVATION_KEY" \
  --auto-attach

The --serverurl and --baseurl parameters are critical for directing the client to the Satellite instance. Activation keys are almost universally used with Satellite for streamlined provisioning and host group assignment.

Verify registration using sudo subscription-manager status and sudo dnf repolist.

Troubleshooting Common Issues

  • "Unable to register system: The subscription management service is unavailable."

    This often indicates a network connectivity issue to subscription.rhsm.redhat.com or your Satellite server. Verify DNS resolution and firewall rules (port 443 outbound).

    ping subscription.rhsm.redhat.com
curl -vvv https://subscription.rhsm.redhat.com/subscription/
  • "No subscription entries matching the provided arguments were found."

    This means --auto-attach failed to find an available and suitable subscription for your system. Ensure you have unallocated subscriptions in your Red Hat account that match the architecture (e.g., x86_64) and product (e.g., RHEL). You might need to manually attach a subscription using its pool ID: 

    sudo subscription-manager list --available --all # Find a suitable pool ID
sudo subscription-manager attach --pool=<POOL_ID>

  • Incorrect Organization ID or Activation Key:

    Double-check the values entered. Both are case-sensitive. Verify them against your Red Hat Customer Portal or Satellite configuration.

  • Expired or Invalid System Certificate:

    If you've unregistered and re-registered multiple times, or experienced system clock issues, your certificates might be problematic. 

    sudo subscription-manager clean # This removes all local subscription data and certificates
sudo subscription-manager register ... # Then re-register

  • Proxy Configuration Issues:

    If your environment requires a proxy for outbound internet access, subscription-manager needs to be aware of it. 

    sudo subscription-manager config --server.proxy_hostname=proxy.example.com --server.proxy_port=8080 --server.proxy_user=proxyuser --server.proxy_password=proxypass
# Alternatively, set environment variables (e.g., in /etc/environment or your shell profile)
# export http_proxy="http://proxy.example.com:8080"
# export https_proxy="http://proxy.example.com:8080"
# export no_proxy="localhost,127.0.0.1,rhsm.redhat.com" # Important for internal services

Back to the knowledge base · Ask the AI assistant