Search
SupportConsoleDevelopersStart a trialContact

Chapter 10. Renaming Satellite Server or Capsule Server

download PDF

To rename Satellite Server or Capsule Server, you must use the satellite-change-hostname script.

If you rename Satellite Server, you must reregister all Satellite clients and configure each Capsule Server to point them to the new Satellite host name. If you use custom SSL certificates, you must regenerate them with the new host name. If you use virt-who, you must update the virt-who configuration files with the new host name.

If you rename Capsule Server, you must reregister all Capsule clients and update the Capsule host name in the Satellite web UI. If you use custom SSL certificates, you must regenerate them with the new host name.

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 Satellite Server

The host name of Satellite Server is used by Satellite Server components, all Capsule Servers, and hosts registered to it for communication. This procedure ensures that you update all references to the new host name.

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.

If you use virt-who, you must update the virt-who configuration files with the new host name after you run the satellite-change-hostname script. For more information, see Modifying a virt-who Configuration in Configuring Virtual Machine Subscriptions in Red Hat Satellite.

Prerequisites

  • Both the hostname and hostname -f commands must return the FQDN of Satellite Server or the satellite-change-hostname script will fail to complete. If the hostname command returns the shortname of Satellite Server instead of the FQDN, use hostnamectl set-hostname old_fqdn to set the old FQDN correctly before attempting to use the satellite-change-hostname script.
  • Perform a backup of Satellite Server before changing a host name. If the renaming process is not successful, you must restore it from a backup. For more information, see Chapter 8, Backing Up Satellite Server and Capsule Server.
  • Optional: If Satellite Server has a custom SSL certificate installed, a new certificate must be obtained for the host’s new name. For more information, see Configuring Satellite Server with a Custom SSL Certificate in Installing Satellite Server from a Connected Network.

Procedure

  1. On 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 default self-signed SSL certificates, enter the following command: 

      # satellite-change-hostname new-satellite \
--username admin \
--password password

    • If your Satellite Server is installed with custom SSL certificates: 

      # satellite-change-hostname new-satellite \
--username admin \
--password password \
--custom-cert "/root/ownca/test.com/test.com.crt" \
--custom-key "/root/ownca/test.com/test.com.key"
  2. Optional: If you have created a custom SSL certificate for the new Satellite Server host name, run the Satellite installation script to install the certificate. For more information about installing a custom SSL certificate, see Deploying a Custom SSL Certificate to Satellite Server in Installing Satellite Server from a Connected Network.

  3. On all Satellite clients, enter the following commands to reinstall the bootstrap RPM, reregister clients, and refresh their subscriptions.

    You can use remote execution feature to perform this step. For more information, see Configuring and Setting up Remote Jobs in Managing Hosts. 

    # yum remove -y katello-ca-consumer*

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

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

# subscription-manager refresh

  4. On all Capsule Servers, 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 \
--puppet-server-foreman-url new-satellite.example.com

  5. On Satellite Server, list all Capsule Servers: 

    # hammer capsule list

  6. On Satellite Server, synchronize content for each Capsule Server: 

    # hammer capsule content synchronize \
--id capsule_id_number

10.2. Renaming Capsule Server

The host name of Capsule Server is referenced by Satellite Server components, and all hosts registered to it. This procedure ensures that you update all references to the new host name.

Note
  • Both the hostname and hostname -f commands must return the FQDN of Capsule Server or the satellite-change-hostname script will fail to complete.
  • If the hostname command returns the shortname of Capsule Server instead of the FQDN, use hostnamectl set-hostname old_fqdn to set the old FQDN correctly before attempting to use the satellite-change-hostname script.

Prerequisites

  • Backup Capsule Server. The satellite-change-hostname script makes irreversible changes to Capsule Server. If the renaming process is not successful, you must restore it from a backup.

    Perform a backup before changing a host name. For more information, see Chapter 8, Backing Up Satellite Server and Capsule Server.

Warning

Until BZ#1829115 is resolved, you must edit the usr/share/katello/hostname-change.rb file on Capsule Server and comment out the following lines before attempting to rename Capsule Server: 

STDOUT.puts "updating hostname in hammer configuration"
self.run_cmd("sed -i.bak -e 's/#{@old_hostname} \
/#{@new_hostname}/g' #{hammer_root_config_path}/*.yml")
self.run_cmd("sed -i.bak -e 's/#{@old_hostname} \
/#{@new_hostname>/g' #{hammer_config_path}/*.yml")

Procedure

  1. On Satellite Server, generate a new certificates archive file for Capsule Server.

    • If you are using the default SSL 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 SSL certificate, create a new SSL certificate for Capsule Server. For more information, see Configuring Capsule Server with a Custom SSL Certificate in Installing Capsule Server.

  2. On Satellite Server, copy the certificates archive file to 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 Capsule Server, run the satellite-change-hostname script and provide 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.

  4. Optional: If you have created a custom certificate for Capsule Server, on Capsule Server, to deploy the certificate, enter the satellite-installer command that the capsule-certs-generate command returns. For more information, see Deploying a Custom SSL Certificate to Capsule Server in Installing Capsule Server.

  5. On all Capsule clients, enter the following commands to reinstall the bootstrap RPM, reregister clients, and refresh their subscriptions.

    You can use remote execution feature to perform this step. For more information, see Configuring and Setting up Remote Jobs in Managing Hosts. 

    # 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

# subscription-manager refresh
  6. In the Satellite web UI, navigate to Infrastructure > Capsules.
  7. Locate Capsule Server in the list, and click Edit to the right of it.
  8. Edit the Name and URL fields to match the Capsule Server’s new host name, then click Submit.
  9. On your DNS server, add a record for the Capsule Server’s new host name, and delete the record for the previous host name.
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.

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.

© 2024 Red Hat, Inc.