Chapter 3. Migrating from Internal Satellite Databases to External Databases

download PDF

When you install Red Hat Satellite, the satellite-installer command installs PostgreSQL databases on the same server as Satellite. If you are using the default internal databases but want to start using external databases to help with the server load, you can migrate your internal databases to external databases.

To confirm whether your Satellite Server has internal or external databases, you can query the status of your databases:

For PostgreSQL, enter the following command:

# satellite-maintain service status --only postgresql

Red Hat does not provide support or tools for external database maintenance. This includes backups, upgrades, and database tuning. You must have your own database administrator to support and maintain external databases.

To migrate from the default internal databases to external databases, you must complete the following procedures:

  1. Section 3.2, “Preparing a Host for External Databases”. Prepare a Red Hat Enterprise Linux 7 server to host the external databases.
  2. Section 3.3, “Installing PostgreSQL”. Prepare PostgreSQL with databases for Satellite, Pulp and Candlepin with dedicated users owning them.
  3. Section 3.4, “Migrating to External Databases”. Edit the parameters of satellite-installer to point to the new databases, and run satellite-installer.

3.1. PostgreSQL as an External Database Considerations

Foreman, Katello, and Candlepin use the PostgreSQL database. If you want to use PostgreSQL as an external database, the following information can help you decide if this option is right for your Satellite configuration. Satellite supports PostgreSQL version 12.1.

Advantages of External PostgreSQL:

  • Increase in free memory and free CPU on Satellite
  • Flexibility to set shared_buffers on the PostgreSQL database to a high number without the risk of interfering with other services on Satellite
  • Flexibility to tune the PostgreSQL server’s system without adversely affecting Satellite operations

Disadvantages of External PostgreSQL

  • Increase in deployment complexity that can make troubleshooting more difficult
  • The external PostgreSQL server is an additional system to patch and maintain
  • If either Satellite or the PostgreSQL database server suffers a hardware or storage failure, Satellite is not operational
  • If there is latency between the Satellite server and database server, performance can suffer

If you suspect that the PostgreSQL database on your Satellite is causing performance problems, use the information in Satellite 6: How to enable postgres query logging to detect slow running queries to determine if you have slow queries. Queries that take longer than one second are typically caused by performance issues with large installations, and moving to an external database might not help. If you have slow queries, contact Red Hat Support.

3.2. Preparing a Host for External Databases

Install a freshly provisioned system with the latest Red Hat Enterprise Linux 7 server to host the external databases.

Subscriptions for Red Hat Software Collections and Red Hat Enterprise Linux do not provide the correct service level agreement for using Satellite with external databases. You must also attach a Satellite subscription to the base operating system that you want to use for the external databases.



  1. Use the instructions in Attaching the Satellite Infrastructure Subscription to attach a Satellite subscription to your server.
  2. Disable all repositories and enable only the following repositories:

    # subscription-manager repos --disable '*'
    # subscription-manager repos --enable=rhel-server-rhscl-7-rpms \
    --enable=rhel-7-server-rpms --enable=rhel-7-server-satellite-6.10-rpms

3.3. Installing PostgreSQL

You can install only the same version of PostgreSQL that is installed with the satellite-installer tool during an internal database installation. You can install PostgreSQL using Red Hat Enterprise Linux Server 7 repositories or from an external source, as long as the version is supported. Satellite supports PostgreSQL version 12.1.


  1. To install PostgreSQL, enter the following command:

    # yum install rh-postgresql12-postgresql-server \
    rh-postgresql12-syspaths \
  2. To initialize PostgreSQL, enter the following command:

    # postgresql-setup initdb
  3. Edit the /var/opt/rh/rh-postgresql12/lib/pgsql/data/postgresql.conf file:

    # vi /var/opt/rh/rh-postgresql12/lib/pgsql/data/postgresql.conf
  4. Remove the # and edit to listen to inbound connections:

    listen_addresses = '*'
  5. Edit the /var/opt/rh/rh-postgresql12/lib/pgsql/data/pg_hba.conf file:

    # vi /var/opt/rh/rh-postgresql12/lib/pgsql/data/pg_hba.conf
  6. Add the following line to the file:

      host  all   all   Satellite_ip/24   md5
  7. To start, and enable PostgreSQL service, enter the following commands:

    # systemctl start postgresql
    # systemctl enable postgresql
  8. Open the postgresql port on the external PostgreSQL server:

    # firewall-cmd --add-service=postgresql
    # firewall-cmd --runtime-to-permanent
  9. Switch to the postgres user and start the PostgreSQL client:

    $ su - postgres -c psql
  10. Create three databases and dedicated roles: one for Satellite, one for Candlepin, and one for Pulp:

    CREATE USER "foreman" WITH PASSWORD 'Foreman_Password';
    CREATE USER "candlepin" WITH PASSWORD 'Candlepin_Password';
    CREATE USER "pulp" WITH PASSWORD 'Pulpcore_Password';
    CREATE DATABASE foreman OWNER foreman;
    CREATE DATABASE candlepin OWNER candlepin;
    CREATE DATABASE pulpcore OWNER pulp;
  11. Exit the postgres user:

    # \q
  12. From Satellite Server, test that you can access the database. If the connection succeeds, the commands return 1.

    # PGPASSWORD='Foreman_Password' psql -h  -p 5432 -U foreman -d foreman -c "SELECT 1 as ping"
    # PGPASSWORD='Candlepin_Password' psql -h -p 5432 -U candlepin -d candlepin -c "SELECT 1 as ping"
    # PGPASSWORD='Pulpcore_Password' psql -h -p 5432 -U pulp -d pulpcore -c "SELECT 1 as ping"

3.4. Migrating to External Databases

Back up and transfer existing data, then use the satellite-installer command to configure Satellite to connect to an external PostgreSQL database server.


  • You have installed and configured a PostgreSQL server on a Red Hat Enterprise Linux server.


  1. On Satellite Server, stop the satellite-maintain services:

    # satellite-maintain service stop
  2. Start the PostgreSQL services:

    # systemctl start postgresql
  3. Back up the internal databases:

    # satellite-maintain backup online --skip-pulp-content --preserve-directory -y /var/migration_backup
  4. Transfer the data to the new external databases:

    PGPASSWORD='Foreman_Password' pg_restore -h -U foreman -d foreman < /var/migration_backup/foreman.dump
    PGPASSWORD='Candlepin_Password' pg_restore -h -U candlepin -d candlepin < /var/migration_backup/candlepin.dump
    PGPASSWORD='Pulpcore_Password' pg_restore -h -U pulp -d pulpcore < /var/migration_backup/pulpcore.dump
  5. Use the satellite-installer command to update Satellite to point to the new databases:

    satellite-installer --scenario satellite \
        --foreman-db-host \
        --foreman-db-password Foreman_Password \
        --foreman-db-database foreman \
        --foreman-db-manage false \
        --katello-candlepin-db-host \
        --katello-candlepin-db-name candlepin \
        --katello-candlepin-db-password Candlepin_Password \
        --katello-candlepin-manage-db false \
        --foreman-proxy-content-pulpcore-manage-postgresql false \
        --foreman-proxy-content-pulpcore-postgresql-host \
        --foreman-proxy-content-pulpcore-postgresql-db-name pulpcore \
        --foreman-proxy-content-pulpcore-postgresql-password Pulpcore_Password
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


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.