Chapter 3. Registering Hosts to Satellite

Procedure

1. In the Satellite web UI, navigate to Hosts > Register Host.
2. Optional: Select a different Organization.
3. Optional: Select a different Location.
4. Optional: From the Host Group list, select the host group to associate the hosts with. Fields that inherit value from Host group: Operating system, Activation Keys and Lifecycle environment.
5. Optional: From the Operating system list, select the operating system of hosts that you want to register.
6. Optional: From the Capsule list, select the Capsule to register hosts through.

7. Optional: Select the Insecure option, if you want to make the first call insecure. During this first call, hosts download the CA file from Satellite. Hosts 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 a 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 the registered 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 the host using the SSH key.

   Instead, you can manually copy and install the CA file on each host before registering the host.

   To do this, find where Satellite stores the CA file by navigating to Administer > Settings > Authentication and locating the value of the SSL CA file setting.

   Copy the CA file to the /etc/pki/ca-trust/source/anchors/ directory on hosts and enter the following commands:

   # update-ca-trust enable
   # update-ca-trust

   Then register the hosts with a secure curl command, such as:

   # curl -sS https://satellite.example.com/register ...

   The following is an example of the curl command with the --insecure option:

   # curl -sS --insecure https://satellite.example.com/register ...

8. Select the Advanced tab.

9. From the Setup REX list, select whether you want to deploy Satellite SSH keys to hosts or not.

   If set to Yes, public SSH keys will be installed on the registered host. The inherited value is based on the host_registration_remote_execution parameter. It can be inherited, for example from a host group, an operating system, or an organization. When overridden, the selected value will be stored on host parameter level.

10. From the Setup Insights list, select whether you want to install insights-client and register the hosts to Insights.

    The Insights tool is available for Red Hat Enterprise Linux only. It has no effect on other operating systems.

    You must enable the following repositories on a registered machine:

    • Red Hat Enterprise Linux 6: rhel-6-server-rpms
    • Red Hat Enterprise Linux 7: rhel-7-server-rpms

    • Red Hat Enterprise Linux 8: rhel-8-for-x86_64-appstream-rpms

      The insights-client package is installed by default on Red Hat Enterprise Linux 8 except in environments whereby Red Hat Enterprise Linux 8 was deployed with "Minimal Install" option.

11. Optional: In the Install packages field, list the packages (separated with spaces) that you want to install on the host upon registration. This can be set by the host_packages parameter.
12. Optional: Select the Update packages option to update all packages on the host upon registration. This can be set by the host_update_packages parameter.
13. Optional: In the Repository field, enter a repository to be added before the registration is performed. For example, it can be useful to make the subscription-manager package available for the purpose of the registration. For Red Hat family distributions, enter the URL of the repository, for example http://rpm.example.com/.
14. Optional: In the Repository GPG key URL field, specify the public key to verify the signatures of GPG-signed packages. It needs to be specified in the ASCII form with the GPG public key header.

15. Optional: In the Token lifetime (hours) field, 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 curl command works. You can set the duration to 0 – 999 999 hours or unlimited.

    Note that Satellite applies the permissions of the user who generates the curl command to authorization of hosts. 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.

16. Optional: In the Remote Execution Interface field, enter the identifier of a network interface that hosts must use for the SSH connection. If you keep this field blank, Satellite uses the default network interface.

17. From the REX pull mode list, select whether you want to deploy Satellite remote execution pull client.

    If set to Yes, the remote execution pull client is installed on the registered host. The inherited value is based on the host_registration_remote_execution_pull parameter. It can be inherited, for example from a host group, an operating system, or an organization. When overridden, the selected value is stored on the host parameter level.

    The registered host must have access to the Red Hat Satellite Client 6 repository.

    For more information about the pull mode, see Section 11.4, “Transport Modes for Remote Execution”.

18. In the Activation Keys field, enter one or more activation keys to assign to hosts.
19. Optional: Select the Lifecycle environment.
20. Optional: Select the Ignore errors option if you want to ignore subscription manager errors.
21. Optional: Select the Force option if you want to remove any katello-ca-consumer rpms before registration and run subscription-manager with the --force argument.
22. Click the Generate button.
23. Copy the generated curl command.
24. On the hosts that you want to register, run the curl command as root.

Procedure

1. In the Satellite web UI, navigate to Configure > Global Parameters to add host parameters globally. Alternatively, you can navigate to Configure > Host Groups and edit or create a host group to add host parameters only to a host group.
2. Enable the Puppet agent using a host parameter in global parameters or a host group. Add a host parameter named enable-puppet7, select the boolean type, and set the value to true.

3. Specify configuration for the Puppet agent using the following host parameters in global parameters or a host group:

   • Add a host parameter named puppet_server, select the string type, and set the value to the hostname of your Puppet server, such as puppet.example.com.
   • Optional: Add a host parameter named puppet_ca_server, select the string type, and set the value to the hostname of your Puppet CA server, such as puppet-ca.example.com. If puppet_ca_server is not set, the Puppet agent will use the same server as puppet_server.
   • Optional: Add a host parameter named puppet_environment, select the string type, and set the value to the Puppet environment you want the host to use.

   Until the BZ2177730 is resolved, you must use host parameters to specify the Puppet agent configuration even in integrated setups where the Puppet server is a Capsule Server.

4. Navigate to Hosts > Register Host and register your host using an appropriate activation key. For more information, see Registering Hosts in Managing Hosts.
5. Navigate to Infrastructure > Capsules.
6. From the list in the Actions column for the required Capsule Server, select Certificates.
7. Click Sign to the right of the required host to sign the SSL certificate for the Puppet agent.

Procedure

1. Log in to the Atomic Host as the root user.

2. Retrieve katello-rhsm-consumer from Satellite Server:

   # wget http://satellite.example.com/pub/katello-rhsm-consumer

3. Change the mode of katello-rhsm-consumer to make it executable:

   # chmod +x katello-rhsm-consumer

4. Run katello-rhsm-consumer:

   # ./katello-rhsm-consumer

5. Register with Subscription Manager:

   # subscription-manager register

1. Manually create a directory:

   # mkdir /etc/puppetlabs/code/environments/example_environment

2. In the Satellite web UI, navigate to Configure > Environments and click Import environment from. The button name includes the FQDN of the internal or external Capsule.
3. Choose the created directory and click Update.

Procedure

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

2. Download the script:

   # curl -O http://satellite.example.com/pub/bootstrap.py

3. Make the script executable:

   # chmod +x bootstrap.py

4. Confirm that the script is executable by viewing the help text:

   • On Red Hat Enterprise Linux 8:

     # /usr/libexec/platform-python bootstrap.py -h

   • On other Red Hat Enterprise Linux versions:

     # ./bootstrap.py -h

5. Enter the bootstrap command with values suitable for your environment.

   For the --server option, specify the FQDN of Satellite Server or a Capsule Server. For the --location, --organization, and --hostgroup options, use quoted names, not labels, as arguments to the options. For advanced use cases, see Section 3.5.2, “Advanced Bootstrap Script Configuration”.

   • On Red Hat Enterprise Linux 8, enter the following command:

     # /usr/libexec/platform-python bootstrap.py \
     --login=admin \
     --server satellite.example.com \
     --location="My_Location" \
     --organization="My_Organization" \
     --hostgroup="My_Host_Group" \
     --activationkey="My_Activation_Key"

   • On Red Hat Enterprise Linux 6 or 7, enter the following command:

     # ./bootstrap.py --login=admin \
     --server satellite.example.com \
     --location="My_Location" \
     --organization="My_Organization" \
     --hostgroup="My_Host_Group" \
     --activationkey="My_Activation_Key"

6. Enter the password of the Satellite user you specified with the --login option.

   The script sends notices of progress to stdout.

7. When prompted by the script, approve the host’s Puppet certificate. In the Satellite web UI, navigate to Infrastructure > Capsules and find the Satellite or Capsule Server you specified with the --server option.
8. From the list in the Actions column, select Certificates.
9. In the Actions column, click Sign to approve the host’s Puppet certificate.
10. Return to the host to see the remainder of the bootstrap process completing.
11. In the Satellite web UI, navigate to Hosts > All hosts and ensure that the host is connected to the correct host group.

12. Optional: After the host registration is complete, remove the script:

    # rm bootstrap.py

Procedure

1. Install the katello-agent package:

   # dnf install katello-agent

2. Start the goferd service:

   # systemctl start goferd

Procedure

1. On the content host, install the katello-host-tools-tracer RPM package:

   # yum install katello-host-tools-tracer

2. Enter the following command:

   # katello-tracer-upload

3. In the Satellite web UI, navigate to Hosts > All hosts, then click the required host name.
4. Click the Traces tab to view Traces. If it is not installed, an Enable Traces button initiates a remote execution job that installs the package.

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

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

     # yum install puppet-agent

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

   . /etc/profile.d/puppet-agent.sh

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

5. Start the Puppet agent service:

   # puppet resource service puppet ensure=running enable=true

6. Create a certificate for the host:

   # puppet ssl bootstrap

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

Procedure

1. If you have Remote Execution configured to use ssh mode, distribute the remote execution SSH keys to the hosts. For more information, see Section 11.12, “Distributing SSH Keys for Remote Execution”.
2. If you have Remote Execution configured to use pull-mqtt mode, deploy the remote execution pull client to the hosts. For more information, see Section 11.5, “Configuring a Host to Use the Pull Client”.

3. Stop the goferd service on content hosts:

   # systemctl stop goferd

4. Disable the goferd service on content hosts:

   # systemctl disable goferd

5. Remove the Katello agent on content hosts:

   Warning

   If your host is installed on Red Hat Virtualization version 4.4 or lower, do not remove the katello-agent package because the removed dependencies corrupt the host.

   # dnf remove katello-agent

6. In the Satellite web UI, navigate to Administer > Settings.
7. Select the Content tab.
8. Set the Use remote execution by default parameter to Yes.