Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

5.4. Renaming a Satellite Server or Capsule Server

Renaming a Satellite Server or Capsule Server requires use of the katello-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.

Warning

Do not change the system host name of your Satellite Server before running the katello-change-hostname script. If the system host name has been changed before running this script, the script will fail when searching for the old host name.

5.4.1. Renaming a Satellite Server
Copy link

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.

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 the Installation Guide.
  • Ensure the system host name has not been changed before running the katello-change-hostname script. If the system host name has been changed, you must revert it to the original host name by using the hostnamectl set-hostname command.
  • Backup the Satellite Server. The katello-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 Chapter 5, Backup and Disaster Recovery.

Procedure 5.8. Rename a Satellite Server

  1. On the Satellite Server, run the katello-change-hostname script, providing the host's new name, and Satellite credentials. 
    # katello-change-hostname new_satellite --username admin \
--password password
    Copy to Clipboard Toggle word wrap
    The message **** Hostname change complete! **** confirms that the rename completed successfully.
  2. (Optional) If you have obtained a new X.509 certificate for the Satellite Server's new host name, run the Satellite installation script to install the certificate. For more information on installing a custom X.509 certificate, see Configuring Satellite Server with a Custom Server Certificate in the Installation Guide.
  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*
      Copy to Clipboard Toggle word wrap 
    2. # rpm -Uvh http://new-satellite.example.com/pub/katello-ca-consumer-latest.noarch.rpm
      Copy to Clipboard Toggle word wrap 
    3. # subscription-manager register --org="Default_Organization" \
--environment="Library" \
--force
      Copy to Clipboard Toggle word wrap
    Use of the Red Hat Satellite remote execution feature is recommended for this step. For details, see Running Jobs on Satellite Hosts in the Host Configuration Guide.
  4. Reattach subscriptions to all Capsule Servers and hosts registered to the Satellite Server, then refresh the subscription. 
    1. # subscription-manager refresh
      Copy to Clipboard Toggle word wrap 
    2. # yum repolist
      Copy to Clipboard Toggle word wrap
    Use of the Red Hat Satellite remote execution feature is recommended for this step. For details, see Running Jobs on Satellite Hosts in the Host Configuration Guide.
  5. On all Capsule Servers, re-run the Satellite installation script to update references to the new host name. 
    # satellite-installer --capsule-parent-fqdn new-satellite.example.com \
--foreman-proxy-foreman-base-url  https://new-satellite.example.com \
--foreman-proxy-trusted-hosts new-satellite.example.com
    Copy to Clipboard Toggle word wrap

5.4.2. Renaming a Capsule Server
Copy link

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

  • (Optional) New X.509 custom certificate files for the Capsule Server. For more information on obtaining a custom X.509 certificate, see Configuring Capsule Server with a Custom Server Certificate in the Installation Guide.
  • Backup the Capsule Server. The katello-change-hostname script makes irreversible changes to the Capsule Server. If the renaming process is not successful, you must restore it from backup.
    Red Hat Satellite does not provide a native backup method for a Capsule Server. For more information, see Chapter 5, Backup and Disaster Recovery.

Procedure 5.9. Rename a Capsule Server

  1. On the Satellite Server, create a new certificates archive file.
    1. If you are using the default Satellite Server certificate: 
      # capsule-certs-generate --capsule-fqdn "new-capsule.example.com" \
--certs-tar "new-capsule.example.com-certs.tar"
      Copy to Clipboard Toggle word wrap
    2. If you are using a custom X.509 certificate on the Capsule Server, see Create the Capsule Server's Certificate Archive File in the Installation Guide.
  2. On the 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:
    Copy to Clipboard Toggle word wrap
  3. On the Capsule Server, run the katello-change-hostname script, providing the host's new name, Satellite credentials, and certificates archive filename. 
    # katello-change-hostname new_capsule --username admin \
--password password \
--certs-tar new-capsule.example.com-certs.tar
    Copy to Clipboard Toggle word wrap
    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 on installing a custom X.509 certificate, see Configuring Satellite Server with a Custom Server Certificate in the Installation Guide.
  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. 
    1. # yum remove -y katello-ca-consumer*
      Copy to Clipboard Toggle word wrap 
    2. # rpm -Uvh http://new-capsule.example.com/pub/katello-ca-consumer-latest.noarch.rpm
      Copy to Clipboard Toggle word wrap 
    3. # subscription-manager register --org="Default_Organization" \
--environment="Library" \
--force
      Copy to Clipboard Toggle word wrap
    Use of the Red Hat Satellite remote execution feature is recommended for this step. For details, see Running Jobs on Satellite Hosts in the Host Configuration Guide.
  6. Reattach subscriptions to all hosts registered to the Capsule Server, then refresh the subscription. 
    1. # subscription-manager refresh
      Copy to Clipboard Toggle word wrap 
    2. # yum repolist
      Copy to Clipboard Toggle word wrap
    Use of the Red Hat Satellite remote execution feature is recommended for this step. For details, see Running Jobs on Satellite Hosts in the Host Configuration Guide.
  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.
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