Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Appendix C. Building cloud images for Red Hat Satellite

Use this section to build and register images to Red Hat Satellite.

You can use a preconfigured Red Hat Enterprise Linux KVM guest QCOW2 image:

These images contain cloud-init. To function properly, they must use ec2-compatible metadata services for provisioning an SSH key.

Note

For the KVM guest images:

  • The root account in the image is disabled, but sudo access is granted to a special user named cloud-user.
  • There is no root password set for this image. The root password is locked in /etc/shadow by placing !! in the second field.

If you want to create custom Red Hat Enterprise Linux images, see Composing a customized Red Hat Enterprise Linux 9 Image or Composing a customized Red Hat Enterprise Linux 8 Image.

Prerequisites

  • Use a Linux host machine to create an image. In this example, we use a Red Hat Enterprise Linux 7 Workstation.
  • Use virt-manager on your workstation to complete this procedure. If you create the image on a remote server, connect to the server from your workstation with virt-manager.
  • A Red Hat Enterprise Linux 7 ISO file (see Red Hat Enterprise Linux 7.4 Binary DVD).

For more information about installing a Red Hat Enterprise Linux Workstation, see the Red Hat Enterprise Linux 7 Installation Guide.

Before you can create custom images, install the following packages:

  • Install libvirt, qemu-kvm, and graphical tools: 

    # yum install virt-manager virt-viewer libvirt qemu-kvm
    Copy to Clipboard Toggle word wrap

  • Install the following command line tools: 

    # yum install virt-install libguestfs-tools-c
    Copy to Clipboard Toggle word wrap
Note

In the following procedures, enter all commands with the [root@host]# prompt on the workstation that hosts the libvirt environment.

C.2. Supported clients in registration
Copy link

Satellite supports the following operating systems and architectures for registration.

Supported host operating systems

The hosts can use the following operating systems:

  • Red Hat Enterprise Linux 10, 9, and 8
  • Red Hat Enterprise Linux 7 with the ELS Add-On
Supported host architectures

The hosts can use the following architectures:

  • AMD and Intel 64-bit architectures
  • The 64-bit ARM architecture
  • IBM Power Systems, Little Endian
  • 64-bit IBM Z architectures

C.3. Configuring a host for registration
Copy link

Configure your host for registration to Satellite Server or Capsule Server. You can use a configuration management tool to configure multiple hosts at once.

Prerequisites

  • The host must be using a supported operating system. For more information, see Section C.2, “Supported clients in registration”.
  • The system clock on your Satellite Server and any Capsule Servers must be synchronized across the network. If the system clock is not synchronized, SSL certificate verification might fail. For example, you can use the Chrony suite for timekeeping.

Procedure

  1. Enable and start a time-synchronization tool on your host. The host must be synchronized with the same NTP server as Satellite Server and any Capsule Servers. 

    # systemctl enable --now chronyd
    Copy to Clipboard Toggle word wrap

  2. Deploy the SSL CA file on your host so that the host can make a secured registration call.

    1. Find where Satellite stores the SSL CA file by navigating to Administer > Settings > Authentication and locating the value of the SSL CA file setting.
    2. Transfer the SSL CA file to your host securely, for example by using scp.
    3. Login to your host by using SSH.

    4. Copy the certificate to the truststore: 

      # cp My_SSL_CA_file.pem /etc/pki/ca-trust/source/anchors
      Copy to Clipboard Toggle word wrap

    5. Update the truststore: 

      # update-ca-trust
      Copy to Clipboard Toggle word wrap

C.4. Registering a host
Copy link

You can register a host by using registration templates and set up various integration features and host tools during the registration process.

Prerequisites

  • Your Satellite account has the Register hosts role assigned or a role with equivalent permissions.
  • You must have root privileges on the host that you want to register.
  • You must have installed either curl or wget on the host that you want to register.
  • You have configured your host for registration. For more information, see Section C.3, “Configuring a host for registration”.
  • An activation key must be available for your host. For more information, see Managing Activation Keys in Managing content.
  • Optional: If you want to register your host to Red Hat Insights, you must synchronize the rhel-8-for-x86_64-baseos-rpms and rhel-8-for-x86_64-appstream-rpms repositories and make them available in the activation key that you use. This is required to install the insights-client package on your host.
  • Red Hat Satellite Client 6 repository for the operating system version of the host is synchronized on Satellite Server and enabled in the activation key you use. For more information, see Importing Content in Managing content. This repository is required for the remote execution pull client, Puppet agent, Tracer, and other tools.

  • If you want to use Capsule Servers instead of your Satellite Server, ensure that you have configured your Capsule Servers accordingly.

    Important

    It is essential to add your Capsule Server to the list of trusted proxies on Satellite Server!

    For more information, see Configuring Capsule for Host Registration and Provisioning in Installing Capsule Server.

  • If your Satellite Server or Capsule Server is behind an HTTP proxy, configure the Subscription Manager on your host to use the HTTP proxy for connection. For more information, see How to access Red Hat Subscription Manager (RHSM) through a firewall or proxy in the Red Hat Knowledgebase.

Procedure

  1. In the Satellite web UI, navigate to Hosts > Register Host.

  2. Enter the details for how you want the registered host to be configured.

    • If you select a host group from the Host Group list, the following fields inherit their values from the host group:

      • Operating system
      • Activation Keys
      • Lifecycle environment
    • A Capsule behind a load balancer takes precedence over the Capsule selected in the Satellite web UI as the content source of the host.
  3. On the General tab, in the Activation Keys field, enter one or more activation keys to assign to your host.
  4. Click Generate to generate a curl command.
  5. Run the curl command as root on the host that you want to register. After registration completes, any Ansible roles assigned to a host group you specified when configuring the registration template will run on the host.

The registration details that you can specify include the following:

  • On the General tab, in the Capsule field, you can select the Capsule to register your host through. A Capsule behind a load balancer takes precedence over a Capsule selected in the Satellite web UI as the content source of the host.
  • On the General tab, in the Download utility field, you can select wget if you want to register your host by using a wget command. By default, Satellite generates a curl command.

  • On the General tab, you can select the Insecure option to make the first call insecure. During this first call, your host downloads the CA file from Satellite. Your host will use this CA file to connect to Satellite with all future calls making them secure.

    Red Hat recommends that you avoid insecure calls.

    If an attacker, located in the network between Satellite and your host, fetches the CA file from the first insecure call, the attacker will be able to access the content of the API calls to and from your host and the JSON Web Tokens (JWT). Therefore, if you have chosen to deploy SSH keys during registration, the attacker will be able to access your host using the SSH key.

  • On the Advanced tab, in the Repositories field, you can list repositories to be added before the registration is performed. You do not have to specify repositories if you provide them in an activation key.
  • On the Advanced tab, you can configure remote execution, Red Hat Insights, and packages to be installed.

  • On the Advanced tab, in the Token lifetime (hours) field, you can change the validity duration of the JSON Web Token (JWT) that Satellite uses for authentication. The duration of this token defines how long the generated registration command works.

    Note that Satellite applies the permissions of the user who generates the registration command to authorization of your host. If the user loses or gains additional permissions, the permissions of the JWT change too. Therefore, do not delete, block, or change permissions of the user during the token duration.

    The scope of the JWTs is limited to the registration endpoints only and cannot be used anywhere else.

Note

Satellite generates the registration command with parameters that search resources by ID. You can edit the registration command to search the following resources by title:

Organization
URL fragment example: organization=My%20Organization or organization=My+Organization
Location
URL fragment example: location=My%20Location or location=My+Location
Host group

If a host group is nested, include the parent group separated with the slash character (/).

URL fragment example: hostgroup=Parent%20Group%2FMy%20Host%20Group

Operating system
URL fragment example: operatingsystem=My%20Operating%20System or operatingsystem=My+Operating+System

The parameter values must be URL encoded.

CLI procedure

  1. Use the hammer host-registration generate-command to generate the registration command to register your host.
  2. On your host that you want to register, run the registration command as root.

For more information, see the Hammer CLI help with hammer host-registration generate-command --help.

Ansible procedure

  • Use the redhat.satellite.registration_command module.

For more information, see the Ansible module documentation with ansible-doc redhat.satellite.registration_command.

API procedure

  • Use the POST /api/registration_commands resource.

For more information, see the full API reference at https://satellite.example.com/apidoc/v2.html.

Next steps

You can install and configure the Puppet agent on a host manually. A configured Puppet agent is required on the host for Puppet integration with your Satellite. For more information about Puppet, see Managing configurations by using Puppet integration.

Prerequisites

  • Puppet must be enabled in your Satellite. For more information, see Enabling Puppet Integration with Satellite in Managing configurations by using Puppet integration.
  • The host must have a Puppet environment assigned to it.
  • Red Hat Satellite Client 6 repository for the operating system version of the host is synchronized on Satellite Server, available in the content view and the lifecycle environment of the host, and enabled for the host. For more information, see Changing the repository sets status for a host in Satellite in Managing content.

Procedure

  1. Log in to the host as the root user.

  2. Install the Puppet agent package.

    • On hosts running Red Hat Enterprise Linux 8 and above: 

      # dnf install puppet-agent
      Copy to Clipboard Toggle word wrap

    • On hosts running Red Hat Enterprise Linux 7 and below: 

      # yum install puppet-agent
      Copy to Clipboard Toggle word wrap

  3. Add the Puppet agent to PATH in your current shell using the following script: 

    . /etc/profile.d/puppet-agent.sh
    Copy to Clipboard Toggle word wrap

  4. Configure the Puppet agent. Set the environment parameter to the name of the Puppet environment to which the host belongs: 

    # puppet config set server satellite.example.com --section agent
# puppet config set environment My_Puppet_Environment --section agent
    Copy to Clipboard Toggle word wrap

  5. Start the Puppet agent service: 

    # puppet resource service puppet ensure=running enable=true
    Copy to Clipboard Toggle word wrap

  6. Create a certificate for the host: 

    # puppet ssl bootstrap
    Copy to Clipboard Toggle word wrap
  7. In the Satellite web UI, navigate to Infrastructure > Capsules.
  8. From the list in the Actions column for the required Capsule Server, select Certificates.
  9. Click Sign to the right of the required host to sign the SSL certificate for the Puppet agent.

  10. On the host, run the Puppet agent again: 

    # puppet ssl bootstrap
    Copy to Clipboard Toggle word wrap

Procedure

  1. Update the system: 

    # yum update
    Copy to Clipboard Toggle word wrap

  2. Install the cloud-init packages: 

    # yum install cloud-utils-growpart cloud-init
    Copy to Clipboard Toggle word wrap

  3. Open the /etc/cloud/cloud.cfg configuration file: 

    # vi /etc/cloud/cloud.cfg
    Copy to Clipboard Toggle word wrap

  4. Under the heading cloud_init_modules, add: 

    - resolv-conf
    Copy to Clipboard Toggle word wrap

    The resolv-conf option automatically configures the resolv.conf when an instance boots for the first time. This file contains information related to the instance such as nameservers, domain and other options.

  5. Open the /etc/sysconfig/network file: 

    # vi /etc/sysconfig/network
    Copy to Clipboard Toggle word wrap

  6. Add the following line to avoid problems accessing the EC2 metadata service: 

    NOZEROCONF=yes
    Copy to Clipboard Toggle word wrap

  7. Un-register the virtual machine so that the resulting image does not contain the same subscription details for every instance cloned based on it: 

    # subscription-manager repos --disable=*
# subscription-manager unregister
    Copy to Clipboard Toggle word wrap

  8. Power off the instance: 

    # poweroff
    Copy to Clipboard Toggle word wrap

  9. On your Red Hat Enterprise Linux Workstation, connect to the terminal as the root user and navigate to the /var/lib/libvirt/images/ directory: 

    # cd /var/lib/libvirt/images/
    Copy to Clipboard Toggle word wrap

  10. Reset and clean the image using the virt-sysprep command so it can be used to create instances without issues: 

    # virt-sysprep -d rhel7
    Copy to Clipboard Toggle word wrap

  11. Reduce image size using the virt-sparsify command. This command converts any free space within the disk image back to free space within the host: 

    # virt-sparsify --compress rhel7.qcow2 rhel7-cloud.qcow2
    Copy to Clipboard Toggle word wrap

    This creates a new rhel7-cloud.qcow2 file in the location where you enter the command.

C.7. Next steps
Copy link

  • Repeat the procedures for every image that you want to provision with Satellite.
  • Move the image to the location where you want to store for future use.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat