Chapter 10. Renaming a Satellite Server or Capsule Server

Renaming a Satellite Server or Capsule Server requires use of the satellite-change-hostname script. Red Hat Satellite contains references to the host’s name and these changes are made using the script. Renaming a Satellite Server affects itself, all Capsule Servers and all hosts registered to it. Renaming a Capsule Server affects itself and all hosts registered to it.

Warning

The renaming process shuts down all Satellite Server services on the host being renamed. When the renaming is complete, all services are restarted.

10.1. Renaming a Satellite Server

The host name of a Satellite Server is used by Satellite Server components, all Capsule Servers, and hosts registered to it for communication. Renaming a Satellite Server requires that these references be updated.

If you use external authentication, you must reconfigure Satellite Server for external authentication after you run the satellite-change-hostname script. The satellite-change-hostname script breaks external authentication for Satellite Server. For more information about configuring external authentication, see Chapter 13, Configuring External Authentication

Prerequisites

  • (Optional) If the Satellite Server has a custom X.509 certificate installed, a new certificate must be obtained in the host’s new name. When all hosts are re-registered to the Satellite Server, the new certificate is installed. For more information on obtaining a custom X.509 certificate, see Configuring Satellite Server with a Custom Server Certificate in Installing Satellite Server from a Connected Network.
  • Backup the Satellite Server. The satellite-change-hostname script makes irreversible changes to the Satellite Server. If the renaming process is not successful, you must restore it from backup. For more information, see Section 13.2, “Using Identity Management”.

Rename a Satellite Server

  1. On the Satellite Server, choose the appropriate method to run the satellite-change-hostname script, providing the new host name and Satellite credentials:

    • If your Satellite Server is installed with self-signed certificates:

      # satellite-change-hostname new_satellite \
      --username admin \
      --password password
    • If your Satellite Server is installed with SSL certificates:

      # satellite-change-hostname new_satellite \
      --username admin \
      --password password \
      -c "/root/ownca/test.com/test.com.crt" \
      -k "/root/ownca/test.com/test.com.key"

    The message ***** Hostname change complete! ***** confirms that the rename completed successfully.

  2. (Optional) If you have obtained a new X.509 certificate for the new Satellite Server host name, run the Satellite installation script to install the certificate. For more information about installing a custom X.509 certificate, see Configuring Satellite Server with a Custom Server Certificate in Installing Satellite Server from a Connected Network.
  3. On all Capsule Servers and hosts registered to the Satellite Server, reinstall the bootstrap RPM and re-register them to the Satellite Server. Substitute the example organization and environment values with those matching your environment.

    1.  

      # yum remove -y katello-ca-consumer*
    2.  

      # rpm -Uvh http://new-satellite.example.com/pub/katello-ca-consumer-latest.noarch.rpm
    3.  

      # subscription-manager register \
      --org="Default_Organization" \
      --environment="Library" \
      --force

    Use of the Red Hat Satellite remote execution feature is recommended for this step. For more information, see Configuring and Running Remote Commands in Managing Hosts.

  4. Reattach subscriptions to all Capsule Servers and hosts registered to the Satellite Server, then refresh the subscription.

    1.  

      # subscription-manager refresh
    2.  

      # yum repolist

    Use of the Red Hat Satellite remote execution feature is recommended for this step. For more information, see Configuring and Running Remote Commands in Managing Hosts.

  5. On all Capsule Servers, re-run the Satellite installation script to update references to the new host name.

    # satellite-installer --foreman-proxy-content-parent-fqdn new-satellite.example.com \
    --foreman-proxy-foreman-base-url https://new-satellite.example.com \
    --foreman-proxy-trusted-hosts new-satellite.example.com
  6. On the Satellite Server, synchronize content for each Capsule Server.

    1. List all Capsule Servers with their ID numbers:

      # hammer capsule list
    2. Enter the following command for each Capsule Server:

      # hammer capsule content synchronize \
      --id capsule_id_number

10.2. Renaming a Capsule Server

The host name of a Capsule Server is referenced by Satellite Server components, and all hosts registered to it. Renaming a Capsule Server requires that these references be updated.

Prerequisites

Renaming a Capsule Server:

  1. On Satellite Server, create a new certificates archive file.

    • If you are using the default Satellite Server certificate, enter the following command:

      # capsule-certs-generate --foreman-proxy-fqdn new-capsule.example.com \
      --certs-tar /root/new-capsule.example.com-certs.tar

      Ensure that you enter the full path to the .tar file.

    • If you are using a custom X.509 certificate on the Capsule Server, see Create the Capsule Server’s Certificate Archive File in Installing Capsule Server.
  2. On Satellite Server, copy the certificates archive file to the Capsule Server, providing the root user’s password when prompted. In this example the archive file is copied to the root user’s home directory, but you may prefer to copy it elsewhere.

    # scp /root/new-capsule.example.com-certs.tar root@capsule.example.com:
  3. On the Capsule Server, run the satellite-change-hostname script, providing the host’s new name, Satellite credentials, and certificates archive filename.

    # satellite-change-hostname new_capsule --username admin \
    --password password \
    --certs-tar /root/new-capsule.example.com-certs.tar

    Ensure that you enter the full path to the .tar file.

    The message ***** Hostname change complete! ***** confirms that the rename completed successfully.

  4. Optional: If you have obtained a new X.509 certificate in the Capsule Server’s new host name, run the Satellite installation script to install the certificate. For more information about installing a custom X.509 certificate, see Install the Capsule Server’s Custom Certificate in Installing Capsule Server.
  5. On all hosts registered to the Capsule Server, reinstall the bootstrap RPM and re-register them to the Capsule Server. Substitute the example organization and environment values with those matching your environment.

    # yum remove -y katello-ca-consumer*
    # rpm -Uvh http://new-capsule.example.com/pub/katello-ca-consumer-latest.noarch.rpm
    # subscription-manager register --org="Default_Organization" \
    --environment="Library" \
    --force

    Use of the Red Hat Satellite remote execution feature is recommended for this step. For more information, see Running Jobs on Hosts in Managing Hosts.

  6. Reattach subscriptions to all hosts registered to the Capsule Server, then refresh the subscription.

    # subscription-manager refresh
    # yum repolist
  7. Edit the Capsule Server’s name.

    1. In the Satellite web UI, navigate to Infrastructure > Capsules.
    2. Find the Capsule Server in the list, and click Edit in that row.
    3. Edit the Name and URL fields to match the Capsule Server’s new host name, then click Submit.
  8. On your DNS server, add a record for the Capsule Server’s new host name, and delete the record for the previous host name.