10.5. Registration

This section shows you how to register hosts to Satellite Server or Capsule Server. There are two main methods for registering a host:
Hosts registered to the Satellite Server via Red Hat Subscription Manager, which can occur either during the post phase of a kickstart or through the terminal, will appear on the Content Hosts page accessible through HostsContent Hosts. Hosts provisioned by Satellite Server appear on the Hosts page accessible through HostsAll hosts.

10.5.1. Configuring a Host for Registration

Red Hat Enterprise Linux hosts register to the Customer Portal Subscription Management by default. You must update each host configuration so that they receive updates from the correct Satellite Server or Capsule Server.

Prerequisites

  • Hosts must be using the following Red Hat Enterprise Linux version:
    • 5.7 or later
    • 6.4 or later
    • 7.0 or later
  • All architectures of Red Hat Enterprise Linux are supported (i386, x86_64, s390x, ppc_64).
  • Ensure that the Satellite Servers, any Capsule Servers, and all hosts are synchronized with the same NTP server.
  • Ensure that a time synchronization tool is up and running on the Satellite Servers, any Capsule Servers, and the hosts.
    • For Red Hat Enterprise Linux 6:
      # chkconfig ntpd on; service ntpd start
    • For Red Hat Enterprise Linux 7:
      # systemctl start chronyd; systemctl enable chronyd
  • Ensure that the daemon rhsmcertd is running on the hosts.
    • For Red Hat Enterprise Linux 6:
      # service rhsmcertd start
    • For Red Hat Enterprise Linux 7:
      # systemctl start rhsmcertd
The following procedure shows how to configure your host to register to Red Hat Satellite.

Procedure 10.2. To Configure a Host for Registration:

  1. Take note of the fully qualified domain name (FQDN) of the Satellite Server or Capsule Server, for example server.example.com.
  2. On the host, open a terminal and log in as root.
  3. Install the consumer RPM from the Satellite Server or Capsule Server to which the host is to be registered. The consumer RPM updates the content source location of the host and allows the host to download content from the content source specified in Red Hat Satellite.
    # rpm -Uvh http://server.example.com/pub/katello-ca-consumer-latest.noarch.rpm

    Important

    Any running Docker Daemons will be restarted.

    Note

    katello-ca-consumer-hostname-1.0-1.noarch.rpm is an additional katello-ca-consumer RPM available that contains the server's host name. The katello-ca-consumer-latest.noarch.rpm rpm will always reflect the most updated version. Both serve the same purpose.

10.5.2. Registering a Host

Prerequisites

  • Ensure that an activation key associated with the appropriate content view and environment exists for the host. If not, see Chapter 7, Configuring Activation Keys for more information. By default, an activation key has the auto-attach function enabled. The feature is commonly used with hosts used as hypervisors.
  • Ensure that the version of the subscription-manager utility installed is 1.10 or higher. The package is available in the standard Red Hat Enterprise Linux repository.

Procedure 10.3. To Register Hosts:

  1. On the host, open a terminal and log in as root.
  2. Clear any old host data related to Red Hat Subscription Manager (RHSM):
    # subscription-manager clean
    
  3. Register the host using RHSM:
    # subscription-manager register --org your_org_name --activationkey your_activation_key

    Example 10.1. Command Output after Registration:

    # subscription-manager register --org MyOrg --activationkey TestKey-1
    The system has been registered with id: 62edc0f8-855b-4184-b1b8-72a9dc793b96
    

Note

You can use the --environment option to override the content view and life cycle environment defined by the activation key. For example, to register a host to the content view "MyView" in a "Development" life cycle environment:
 # subscription-manager register --org your_org_name --environment Development/MyView --activationkey your_activation_key

Note

For Red Hat Enterprise Linux 6.3 hosts, the release version defaults to Red Hat Enterprise Linux 6 Server and needs to be pointed to the 6.3 repository.

Procedure 10.4. To Point Red Hat Enterprise Linux 6.3 to the Repository:

  1. On Red Hat Satellite, select HostsContent Hosts.
  2. Click the name of the host that needs to be changed.
  3. In the Content Host Content section click the edit icon to the right of Release Version.
  4. Select "6.3" from the Release Version drop-down menu.
  5. Click Save.

10.5.3. Installing the Katello Agent

The following procedure shows how to install the Katello agent on a host registered to Satellite 6. The katello-agent package depends on the gofer package that provides the goferd service. This service must be enabled so that the Red Hat Satellite Server or Capsule Server can provide information about errata that are applicable for content hosts.

Prerequisites

Satellite version 6.1 and later require that you enable the Satellite Tools repository. The Red Hat Common repositories are no longer used and are not compatible with Satellite version 6.1 and later.
The Satellite Tools repository must be enabled, synchronized to the Red Hat Satellite Server and made available to your hosts as it provides the required packages.

Procedure 10.5. To Verify the Satellite Tools Repository is Enabled:

  1. Open the Satellite web UI, navigate to ContentRed Hat Repositories and click on the RPMs tab.
  2. Find and expand the Red Hat Enterprise Linux Server item.
  3. Find and expand the Red Hat Satellite Tools 6.2 (for RHEL VERSION Server) (RPMs) item.
    If the Red Hat Satellite Tools 6.2 items are not visible, it may be because they are not included in the subscription manifest obtained from the Customer Portal. To correct that, log in to the Customer Portal, add these repositories, download the subscription manifest and import it into Satellite.
  4. Ensure the Enabled check box beside the repository's name is selected. If not, select it.
Enable the Satellite Tools repository for every supported major version of Red Hat Enterprise Linux running on your hosts.

Procedure 10.6. To Install Katello Agent:

  1. On the host, verify that the satellite-tools repository is enabled. If you registered the host using an activation key with auto-attache enabled, the repository is enabled automatically already.
    # yum repolist enabled | grep -i satellite-tools
    If the satellite-tools is not enabled, enable it using the following command:
    # subscription-manager repos --enable=rhel-version-server-satellite-tools-6.2-rpms
  2. Install the katello-agent RPM package using the following command:
    # yum install katello-agent
  3. Ensure the goferd service is running.
    • On Red Hat Enterprise Linux 6, enter the following command:
      # service goferd start
    • On Red Hat Enterprise Linux 7, enter the following command:
      # systemctl start goferd

10.5.4. Installing and Configuring the Puppet Agent

This section describes how to install and configure the Puppet agent on a host. When you have correctly installed and configured the Puppet agent, you can navigate to HostsAll hosts to list all hosts visible to Red Hat Satellite Server.

Prerequisites

The Satellite Tools repository must be enabled, synchronized to the Red Hat Satellite Server and made available to your hosts as it provides the required packages.

Procedure 10.7. To Verify the Satellite Tools Repository is Enabled:

  1. Open the Satellite web UI, navigate to ContentRed Hat Repositories and click on the RPMs tab.
  2. Find and expand the Red Hat Enterprise Linux Server item.
  3. Find and expand the Red Hat Satellite Tools 6.2 (for RHEL VERSION Server) (RPMs) item.
    If the Red Hat Satellite Tools 6.2 items are not visible, it may be because they are not included in the subscription manifest obtained from the Customer Portal. To correct that, log in to the Customer Portal, add these repositories, download the subscription manifest and import it into Satellite.
  4. Ensure the Enabled check box beside the repository's name is selected. If not, select it.

Procedure 10.8. To Install and Enable the Puppet Agent:

  1. On the host, open a terminal console and log in as the root user.
  2. Verify that the satellite-tools repository is enabled, using the following command:
    # yum repolist enabled | grep -i satellite-tools
    If the satellite-tools is not enabled, enable it using the following command:
    # subscription-manager repos --enable=rhel-version-server-satellite-tools-6.2-rpms
  3. Install the Puppet agent RPM package using the following command:
    # yum install puppet
    
  4. Configure the puppet agent to start at boot:
    • On Red Hat Enterprise Linux 6:
      # chkconfig puppet on
    • On Red Hat Enterprise Linux 7:
      # systemctl enable puppet
Prerequisites

The following conditions must be met before configuring the Puppet Agent:

  • The host must be registered to the Red Hat Satellite Server.
  • The Satellite Tools repository must be enabled.
  • Puppet packages must be installed on the host.

Procedure 10.9. To Configure the Puppet Agent:

  1. Configure the Puppet agent by specifying the server and environment settings in the /etc/puppet/puppet.conf file:
    # vi /etc/puppet/puppet.conf
    
    [main]
        # The Puppet log directory.
        # The default value is '$vardir/log'.
        logdir = /var/log/puppet
    
        # Where Puppet PID files are kept.
        # The default value is '$vardir/run'.
        rundir = /var/run/puppet
    
        # Where SSL certificates are kept.
        # The default value is '$confdir/ssl'.
        ssldir = /var/lib/puppet/ssl
    
    ...
    
    [agent]
        # The file in which puppetd stores a list of the classes
        # associated with the retrieved configuratiion.  Can be loaded in
        # the separate ``puppet`` executable using the ``--loadclasses``
        # option.
        # The default value is '$confdir/classes.txt'.
        classfile = $vardir/classes.txt
        pluginsync = true
        report = true
        ignoreschedules = true
        daemon = false
        ca_server = satellite.example.com
        server = satellite.example.com
        environment = KT_Example_Org_Library_RHEL6Server_3
    
        # Where puppetd caches the local configuration.  An
        # extension indicating the cache format is added automatically.
        # The default value is '$confdir/localconfig'.
        localconfig = $vardir/localconfig
    
    ...
    

    Important

    Set the environment parameter to the name of the Puppet environment to which the host belongs. A Puppet environment is a collection of Puppet modules that can be associated with a host or a host group.
    • To find the host's Puppet environment, navigate to HostsAll Hosts and inspect the Environment column in the host table.
    • To assign a Puppet environment to a host, navigate to HostsAll Hosts and click Edit next to the selected host.
    • To list Puppet environments enabled on the Satellite Server, navigate to ConfigureEnvironments. You can also inspect the /etc/puppet/environments/ directory on the Satellite Server to find what Puppet modules and manifests are associated with Puppet environments.
    For more information see the Red Hat Satellite Puppet Guide.
  2. Run the Puppet agent on the host:
    # puppet agent -t --server satellite.example.com
  3. Sign the SSL certificate for the Puppet client through the Satellite Server web UI:
    1. Log in to the Satellite Server through the web UI.
    2. Select InfrastructureCapsules.
    3. Select Certificates from the drop-down menu to the right of the required Capsule.
    4. Click Sign to the right of the required host.
    5. Enter the puppet agent command again:
      # puppet agent -t --server satellite.example.com

Note

When the Puppet agent is configured on the host it will be listed under All Hosts but only when Any Organization is selected as the host will not be assigned to an organization or location. To assign the host to an organization, see Section 10.9, “Assigning a Host to a Specific Organization” or to assign the host to a location, see Section 10.10, “Assigning a Host to a Specific Location”.

10.5.5. Registering Hosts to Satellite 6 Using The Bootstrap Script

The bootstrap script, which is included in 6.2 and higher, can be used to register new hosts or migrate existing hosts to Satellite 6.
The bootstrap script handles content registration, product certificates, and Puppet configuration. The bootstrap script has the advantage of taking a Red Hat Enterprise Linux system, regardless of where it is registered (RHN, Satellite 5, SAM, RHSM), or if it is registered at all, and subscribing it to Satellite 6.
The bootstrap script package, katello-client-bootstrap, is installed by default on the Satellite Server's base system and the script itself is installed in the /var/www/html/pub/ directory to make it available to hosts. It can be accessed using a URL in the following form:
satellite6.example.com/pub/bootstrap.py
The script includes documentation in a readme file. To view the file on the Satellite CLI:
$ less /usr/share/doc/katello-client-bootstrap-version/README.md

Procedure 10.10. Installing the Bootstrap Script on the Host:

As the script is only required once, and only for the root user, you can place it in /root and remove it after use, or place it in /usr/local/sbin. This example will use /root.
As root, install the bootstrap script on the host as follows:
  1. Ensure you are in the correct directory. For example, to change to /root:
    # cd
  2. Download the script:
    # wget http://satellite6.example.com/pub/bootstrap.py
    This will install the script to the current directory.
  3. Make the script executable:
    # chmod +x bootstrap.py
  4. To confirm that the script can now be run, view the usage statement as follows:
    # ./bootstrap.py -h
  5. Optionally, when the transition process is complete, remove the script:
    # cd
    # rm bootstrap.py

Procedure 10.11. Running the Bootstrap Script

Prerequisites

  1. Enter the bootstrap command as follows with values suitable for your environment.
    For the --server option, specify the FQDN name of Satellite Server or Capsule Server. For --location, --organization, and --hostgroup options, use quoted names, not labels, as arguments to the options. See Section 10.5.6, “Advanced Bootstrap Script Configuration” for advanced use cases.
    # bootstrap.py --login=admin \
    --server satellite6.example.com \
    --location="Example Location" \
    --organization="Example Organization" \
    --hostgroup="Example Host Group" \
    --activationkey=activation_key
    The script will prompt you for the password corresponding to the Satellite user name you entered with the --login option.
  2. The script will run and send notices of progress to stdout. Watch for output prompting you to approve the certificate. For example:
    [NOTIFICATION], [2016-04-26 10:16:00], [Visit the UI and approve this certificate via Infrastructure->Capsules]
    [NOTIFICATION], [2016-04-26 10:16:00], [if auto-signing is disabled]
    [RUNNING], [2016-04-26 10:16:00], [/usr/bin/puppet agent --test --noop --tags no_such_tag --waitforcert 10]
    The host will wait indefinitely until an administrator approves the Puppet certificate.
    1. In the web UI, navigate to InfrastructureCapsules.
    2. Select Certificates to the right of the name of the Capsule corresponding to the FQDN given with --server option.
    3. In the Actions column select Sign to approve the host's Puppet certificate.
    4. Return to the host to see the remainder of the bootstrap process completing.
  3. In the web UI, navigate to HostsAll hosts and ensure that the host is connected to the correct host group.
If the Katello agent is not installed on the host, proceed to Section 10.5.3, “Installing the Katello Agent”.

10.5.6. Advanced Bootstrap Script Configuration

The standard workflow of using the bootstrap script has been outlined in Procedure 10.11, “Running the Bootstrap Script”. This section covers some more examples.
Migrating a host from one Satellite 6 to another Satellite 6.
Use the script with --force, and the script will remove the katello-ca-consumer-* packages from the old Satellite and install the katello-ca-consumer-* packages from the new Satellite. For example:
# bootstrap.py --login=admin \
--server satellite6.example.com \
--location="Example Location" \
--organization="Example Organization" \
--hostgroup="Example Host Group" \
--activationkey=activation_key \
--force
Migrating a host from Red Hat Network (RHN) or Satellite 5 to Satellite 6.
The bootstrap script detects the presence of /etc/syconfig/rhn/systemid and a valid connection to RHN as an indicator that the system is registered to a legacy platform. The script then calls rhn-classic-migrate-to-rhsm to migrate the system from RHN. By default, the script does not delete the system's legacy profile due to auditing reasons. To remove the legacy profile, use --legacy-purge and use --legacy-login to supply an user account that has appropriate permissions to remove a profile. Enter the user account password when prompted. For example:
# bootstrap.py --login=admin \
--server satellite6.example.com \
--location="Example Location" \
--organization="Example Organization" \
--hostgroup="Example Host Group" \
--activationkey=activation_key \
--legacy-purge \
--legacy-login rhn-user
Registering a host to Satellite 6, omitting Puppet setup.
By default, the bootstrap script configures the host for content management and configuration management. If you have an existing configuration management system and do not want to install puppet on the host, use --skip-puppet. For example:
# bootstrap.py --login=admin \
--server satellite6.example.com \
--location="Example Location" \
--organization="Example Organization" \
--hostgroup="Example Host Group" \
--activationkey=activation_key \
--skip-puppet
Registering a host to Satellite 6 for content management only.
To register a system as a content host, and leave out the provisioning and configuration management functions, use --skip-foreman. For example:
# bootstrap.py --server satellite6.example.com \
--organization="Example Organization" \
--activationkey=activation_key \
--skip-foreman
Changing the method the bootstrap script uses to download the consumer RPM.
By default, the bootstrap script uses HTTP to download the consumer RPM (server.example.com/pub/katello-ca-consumer-latest.noarch.rpm). In some environments, it is desired to only allow HTTPS between the host and Satellite. Use --download-method to change the download method from HTTP to HTTPS. For example:
# bootstrap.py --login=admin \
--server satellite6.example.com \
--location="Example Location" \
--organization="Example Organization" \
--hostgroup="Example Host Group" \
--activationkey=activation_key \
--download-method https
Providing the host's IP address to Satellite
On hosts with multiple interfaces or multiple IP addresses on one interface, you may need to override the auto-detection of the IP address and provide a specific IP address to Satellite. Use --ip. For example:
# bootstrap.py --login=admin \
--server satellite6.example.com \
--location="Example Location" \
--organization="Example Organization" \
--hostgroup="Example Host Group" \
--activationkey=activation_key \
--ip 192.x.x.x
Enabling Remote Execution on the host.
Use --rex and --rex-user to enable remote execution and add the required SSH keys for the specified user. For example:
# bootstrap.py --login=admin \
--server satellite6.example.com \
--location="Example Location" \
--organization="Example Organization" \
--hostgroup="Example Host Group" \
--activationkey=activation_key \
--rex \
--rex-user root
Creating a domain for a host at registration time.
To create a host record, the DNS domain of a host needs to exist in Satellite prior to running script. If the domain does not exist, add it using --add-domain. For example:
# bootstrap.py --login=admin \
--server satellite6.example.com \
--location="Example Location" \
--organization="Example Organization" \
--hostgroup="Example Host Group" \
--activationkey=activation_key \
--add-domain
Providing an arbitrary Fully Qualified Domain Name (FQDN) for the host.
If the host's host name is not an FQDN, or is not RFC compliant (containing a character such as an underscore), the script will fail at the host name validation stage. Use --fqdn to specify the FQDN that will be reported to Satellite. To do so, you will need to set create_new_host_when_facts_are_uploaded and create_new_host_when_report_is_uploaded to false using hammer. For example,
# hammer settings set \
--name  create_new_host_when_facts_are_uploaded \
--value false
# hammer settings set \
--name  create_new_host_when_report_is_uploaded \
--value false
# bootstrap.py --login=admin \
--server satellite6.example.com \
--location="Example Location" \
--organization="Example Organization" \
--hostgroup="Example Host Group" \
--activationkey=activation_key \
--fqdn node100.example.com