Chapter 3. Migrating to External Databases


As part of the installation process for Red Hat Satellite, the satellite-installer command installs MongoDB and PostgreSQL databases on the same server as Satellite. In certain Satellite deployments, using external databases can help with the server load. If your Satellite deployment requires external databases, you can migrate your internal databases to external databases.

Depending on your requirements, you can use external databases for either MongoDB or PostgreSQL database, or both.

Red Hat does not provide support or tools for external database maintenance. This includes backups, upgrades, and database tuning. Customers using an external database require their own database administrator to support and maintain the database.

To view whether your Satellite Server has embedded or external databases, you can query the status of your databases. For example, enter the following command with the --only and add postgresql or rh-mongodb34-mongod:

For PostgreSQL, enter the following command:

# satellite-maintain service status --only postgresql
Copy to Clipboard

For MongoDB, enter the following command:

# satellite-maintain service status --only rh-mongodb34-mongod
Copy to Clipboard

If your Satellite deployment requires external databases, use the following information to set up and point to external databases from Satellite.

FIPS-related Restrictions

Until BZ#1743706 is resolved, you cannot use an external MongoDB with Satellite in FIPS mode.

3.1. MongoDB as an External Database Considerations

Pulp uses the MongoDB database. If you want to use MongoDB as an external database, the following information can help you discern if this option is right for your Satellite configuration.

Advantages of External MongoDB

  • Increase in free memory and free CPU on Satellite
  • Flexibility to tune the MongoDB server’s system without adversely affecting Satellite operations

Disadvantages of External MongoDB

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

If you suspect that your Mongo database is slow, you can work with Red Hat Support to troubleshoot. You might be encountering a configuration problem or existing performance problems with Satellite 6 that moving to an external database server might not help. Red Hat Support can examine existing known issues and also work with the Satellite Engineering team to determine the root cause.

3.2. 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 discern if this option is right for your Satellite configuration.

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.3. Overview

To create and use external databases for Satellite, you must complete the following procedures:

  1. Use Storage Requirements and Guidelines in Installing Satellite Server from a Connected Network to plan the storage requirements for your external databases.
  2. Prepare PostgreSQL with databases for Foreman and Candlepin and respective Foreman and Candlepin users with ownership roles.
  3. Prepare MongoDB with the Pulp user owning the pulp_database.
  4. Back up your existing Satellite databases.
  5. Migrate the internal Satellite databases to external databases.
  6. Edit the arguments of the satellite-installer command to point to the new databases, and run satellite-installer.

Preparing Red Hat Enterprise Linux Server 7 for Database Installation

You require a freshly provisioned system with the latest Red Hat Enterprise Linux Server 7 that meets the storage requirements from Storage Requirements and Guidelines in the Installing Satellite Server from a Connected Network.

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 system that you want to use for the external database.

  1. Attach a Satellite subscription to your server. For more information, see Identifying and Attaching the Satellite Subscription to the Host in the Installing Satellite Server from a Connected Network.
  2. To install MongoDB and PostgreSQL servers on Red Hat Enterprise Linux Server 7, you must 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
    Copy to Clipboard

3.4. Installing MongoDB

You can install only the same version of MongoDB that is installed with the satellite-installer tool during an internal database installation. You can install MongoDB using Red Hat Software Collections (RHSCL) repositories or from an external source, as long as the version is supported. Satellite supports MongoDB version 3.4.

  1. To install MongoDB, enter the following command:

    # yum install rh-mongodb34 rh-mongodb34-syspaths
    Copy to Clipboard
  2. Start and enable the rh-mongodb34-mongod service:

    # systemctl start rh-mongodb34-mongod
    # systemctl enable rh-mongodb34-mongod
    Copy to Clipboard
  3. Create a Pulp user on MongoDB:

    # mongo pulp_database \
    --eval "db.createUser({user:'pulp',pwd:'pulp_password',roles:[{role:'dbOwner', db:'pulp_database'},{ role: 'readWrite', db: 'pulp_database'}]})"
    Copy to Clipboard
  4. Edit the /etc/opt/rh/rh-mongodb34/mongod.conf file to enable authentication in the security section:

    security:
      authorization: enabled
    Copy to Clipboard
  5. In the /etc/opt/rh/rh-mongodb34/mongod.conf file, specify the bind IP:

    bindIp: your_mongodb_server_bind_IP,::1
    Copy to Clipboard
  6. Restart the rh-mongodb34-mongod service:

    # systemctl restart rh-mongodb34-mongod
    Copy to Clipboard
  7. Open port 27017 for MongoDB:

    # firewall-cmd --add-port=27017/tcp
    # firewall-cmd --add-port=27017/tcp --permanent
    Copy to Clipboard
  8. From Satellite Server, test that you can access the database. If the connection succeeds, the command returns 1.

    # scl enable rh-mongodb34 " mongo --host mongo.example.com \
    -u pulp -p pulp_password --port 27017 --eval 'ping:1' pulp_database"
    Copy to Clipboard

3.5. Installing PostgreSQL

You can install only the same version of PostgreSQL that is installed with the satellite-installer tool during an internal database installation. Satellite supports only a specific version of PostgreSQL that is available through Red Hat Enterprise Linux Server 7 repositories. You can install PostgreSQL using Red Hat Enterprise Linux Server 7 repositories or from an external source, as long as the version is supported. For more information about the repository that contains the supported version of PostgreSQL, and what version is supported, see the Package Manifest.

  1. To install PostgreSQL, enter the following command:

    # yum install postgresql-server
    Copy to Clipboard

    +. To initialize, start, and enable PostgreSQL, enter the following commands:

    # postgresql-setup initdb
    # systemctl start postgresql
    # systemctl enable postgresql
    Copy to Clipboard
  2. Edit the /var/lib/pgsql/data/postgresql.conf file:

    # vi /var/lib/pgsql/data/postgresql.conf
    Copy to Clipboard
  3. Remove the # and edit the following line to listen for inbound connections:

    listen_addresses = '*'
    Copy to Clipboard
  4. Edit the /var/lib/pgsql/data/pg_hba.conf file:

    # vi /var/lib/pgsql/data/pg_hba.conf
    Copy to Clipboard
  5. Add the following line to the file:

      host  all   all   satellite_server_ip/24   md5
    Copy to Clipboard
  6. Restart postgreSQL service to update with the changes:

    # systemctl restart postgresql
    Copy to Clipboard
  7. Switch to the postgres user and start the PostgreSQL client:

    $ su - postgres -c psql
    Copy to Clipboard
  8. Create two users, databases, and dedicated roles, one for Foreman and one for Candlepin:

    CREATE USER "foreman" WITH PASSWORD 'Foreman_Password';
    CREATE USER "candlepin" WITH PASSWORD 'Candlepin_Password';
    CREATE DATABASE foreman OWNER foreman;
    CREATE DATABASE candlepin OWNER candlepin;
    Copy to Clipboard
  9. Open the postgresql port on the external PostgreSQL server:

    # firewall-cmd --add-service=postgresql
    # firewall-cmd --add-service=postgresql --permanent
    Copy to Clipboard
  10. From Satellite Server, test that you can access the database. If the connection succeeds, the commands return 1.

    # PGPASSWORD='Foreman_Password' psql -h postgres.example.com  -p 5432 -U foreman -d foreman -c "SELECT 1 as ping"
    # PGPASSWORD='Candlepin_Password' psql -h postgres.example.com -p 5432 -U candlepin -d candlepin -c "SELECT 1 as ping"
    Copy to Clipboard

To Migrate to External Databases

To migrate internal databases to external databases, complete the following steps:

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

    # satellite-maintain service stop
    Copy to Clipboard
  2. Start the postgreSQL and mongod services:

    # systemctl start postgresql
    # systemctl start mongod
    Copy to Clipboard
  3. Back up the internal databases:

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

    PGPASSWORD='Satellite_Password' pg_restore -h postgres.example.com -U foreman -d foreman < /var/migration_backup/foreman.dump
    PGPASSWORD='Candlepin_Password' pg_restore -h postgres.example.com -U candlepin -d candlepin < /var/migration_backup/candlepin.dump
    mongorestore --host mongo.example.com --db pulp_database --username pulp --password pulp_password /var/migration_backup/mongo_dump
    Copy to Clipboard
  5. Use the satellite-installer command to update Satellite to point to the new databases:

    satellite-installer --scenario satellite \
        --foreman-db-host postgres.example.com \
        --foreman-db-password Foreman_Password \
        --foreman-db-database foreman \
        --foreman-db-manage false \
        --katello-candlepin-db-host postgres.example.com \
        --katello-candlepin-db-name candlepin \
        --katello-candlepin-db-password Candlepin_Password \
        --katello-candlepin-manage-db false \
        --katello-pulp-db-username pulp \
        --katello-pulp-db-password pulp_password \
        --katello-pulp-db-seeds mongo.example.com:27017 \
        --katello-pulp-db-name pulp_database \
        --katello-pulp-manage-db false
    Copy to Clipboard
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