Installing Satellite Server in a Connected Network Environment

Procedure

1. Enter the following command with any additional options that you want to use:

   # satellite-installer --scenario satellite \
   --foreman-initial-organization "My_Organization" \
   --foreman-initial-location "My_Location" \
   --foreman-initial-admin-username admin_user_name \
   --foreman-initial-admin-password admin_password

   The script displays its progress and writes logs to /var/log/foreman-installer/satellite.log.

Procedure

1. In the Satellite web UI, navigate to Content > Red Hat Repositories.
2. In the Available Repositories pane, enable the Recommended Repositories to get the list of repositories.
3. Click Red Hat Satellite Client 6 for RHEL 9 x86_64 (RPMs) or Red Hat Satellite Client 6 for RHEL 8 x86_64 (RPMs) to expand the repository set.

4. For the x86_64 architecture, click the + icon to enable the repository.

   If the Satellite Client 6 items are not visible, it may be because they are not included in the Red Hat Subscription Manifest obtained from the Customer Portal. To correct that, log in to the Customer Portal, add these repositories, download the Red Hat Subscription Manifest and import it into Satellite. For more information, see Managing Red Hat Subscriptions in Managing Content.

   Enable the Satellite Client 6 repository for every supported major version of Red Hat Enterprise Linux running on your hosts. After enabling a Red Hat repository, a Product for this repository is automatically created.

Procedure

1. In the Satellite web UI, navigate to Content > Red Hat Repositories.
2. In the Available Repositories pane, enable the Recommended Repositories to get the list of repositories.

3. In the Available Repositories pane, click on Satellite Client 6 (for RHEL 7 Server) (RPMs) or Satellite Client 6 (for RHEL 6 Server - ELS) (RPMs) to expand the repository set.

   If the Satellite Client 6 items are not visible, it may be because they are not included in the Red Hat Subscription Manifest obtained from the Customer Portal. To correct that, log in to the Customer Portal, add these repositories, download the Red Hat Subscription Manifest and import it into Satellite. For more information, see Managing Red Hat Subscriptions in Managing Content.

4. For the x86_64 architecture, click the + icon to enable the repository. Enable the Satellite Client 6 repository for every supported major version of Red Hat Enterprise Linux running on your hosts. After enabling a Red Hat repository, a Product for this repository is automatically created.

Procedure

1. In the Satellite web UI, navigate to Content > Sync Status.
2. Click the arrow next to the Red Hat Enterprise Linux for x86_64 product to view available content.
3. Select Red Hat Satellite Client 6 for RHEL 9 x86_64 RPMs or Red Hat Satellite Client 6 for RHEL 8 x86_64 RPMs whichever is applicable.
4. Click Synchronize Now.

Procedure

1. In the Satellite web UI, navigate to Content > Sync Status.
2. Click the arrow next to the Red Hat Enterprise Linux Server or Red Hat Enterprise Linux Server - Extended Life Cycle Support whichever product is applicable to view available content.
3. Select Red Hat Satellite Client 6 (for RHEL 7 Server) RPMs x86_64 or Red Hat Satellite Client 6 for RHEL 6 Server - ELS RPMs x86_64 based on your operating system version.
4. Click Synchronize Now.

Procedure

1. In the Satellite web UI, navigate to Infrastructure > HTTP Proxies.
2. Click New HTTP Proxy.
3. In the Name field, enter the name for the HTTP proxy.
4. In the Url field, enter the URL of the HTTP proxy in the following format: https://proxy.example.com:8080.
5. Optional: If authentication is required, in the Username field, enter the username to authenticate with.
6. Optional: If authentication is required, in the Password field, enter the password to authenticate with.
7. To test connection to the proxy, click the Test Connection button.
8. Click Submit.
9. In the Satellite web UI, navigate to Administer > Settings, and click the Content tab.
10. Set the Default HTTP Proxy setting to the created HTTP proxy.

CLI procedure

1. Verify that the http_proxy, https_proxy, and no_proxy variables are not set.

   # unset http_proxy
   # unset https_proxy
   # unset no_proxy

2. Add an HTTP proxy entry to Satellite:

   # hammer http-proxy create --name=myproxy \
   --url http://myproxy.example.com:8080  \
   --username=proxy_username \
   --password=proxy_password

3. Configure Satellite to use this HTTP proxy by default:

   # hammer settings set --name=content_default_http_proxy --value=myproxy

Procedure

1. On Satellite, to verify the ports that are permitted by SELinux for the HTTP cache, enter a command as follows:

   # semanage port -l | grep http_cache
   http_cache_port_t       tcp    8080, 8118, 8123, 10001-10010
   [output truncated]

2. To configure SELinux to permit a port for the HTTP cache, for example 8088, enter a command as follows:

   # semanage port -a -t http_cache_port_t -p tcp 8088

Procedure

1. In the Satellite web UI, navigate to Administer > Settings.
2. In the HTTP(S) proxy row, select the adjacent Value column and enter the proxy URL.
3. Click the tick icon to save your changes.

Procedure

1. In the Satellite web UI, navigate to Administer > Settings.
2. In the HTTP(S) proxy except hosts row, select the adjacent Value column and enter the names of one or more hosts that you want to exclude from proxy requests.
3. Click the tick icon to save your changes.

Procedure

1. In the Satellite web UI, navigate to Administer > Settings, and click the Content tab.
2. Set the Default HTTP Proxy setting to no global default.

Procedure

1. To store all the source certificate files, create a directory that is accessible only to the root user:

   # mkdir /root/satellite_cert

2. Create a private key with which to sign the certificate signing request (CSR).

   Note that the private key must be unencrypted. If you use a password-protected private key, remove the private key password.

   If you already have a private key for this Satellite Server, skip this step.

   # openssl genrsa -out /root/satellite_cert/satellite_cert_key.pem 4096

3. Create the /root/satellite_cert/openssl.cnf configuration file for the CSR and include the following content:

1. Optional: If you want to add Distinguished Name (DN) details to the CSR, add the following information to the [ req_distinguished_name ] section:

   [req_distinguished_name]
   CN = satellite.example.com
   countryName =My_Country_Name 1
   stateOrProvinceName = My_State_Or_Province_Name 2
   localityName = My_Locality_Name 3
   organizationName = My_Organization_Or_Company_Name
   organizationalUnitName = My_Organizational_Unit_Name 4

   1

   Two letter code

   2

   Full name

   3

   Full name (example: New York)

   4

   Division responsible for the certificate (example: IT department)

2. Generate CSR:

   # openssl req -new \
   -key /root/satellite_cert/satellite_cert_key.pem \ 1
   -config /root/satellite_cert/openssl.cnf \ 2
   -out /root/satellite_cert/satellite_cert_csr.pem 3

   1

   Path to the private key

   2

   Path to the configuration file

   3

   Path to the CSR to generate

3. Send the certificate signing request to the certificate authority (CA). The same CA must sign certificates for Satellite Server and Capsule Server.

   When you submit the request, specify the lifespan of the certificate. The method for sending the certificate request varies, so consult the CA for the preferred method. In response to the request, you can expect to receive a CA bundle and a signed certificate, in separate files.

Procedure

1. Validate the custom SSL certificate input files. Note that for the katello-certs-check command to work correctly, Common Name (CN) in the certificate must match the FQDN of Satellite Server.

   # katello-certs-check \
   -c /root/satellite_cert/satellite_cert.pem \      1
   -k /root/satellite_cert/satellite_cert_key.pem \  2
   -b /root/satellite_cert/ca_cert_bundle.pem        3

   1

   Path to Satellite Server certificate file that is signed by a Certificate Authority.

   2

   Path to the private key that was used to sign Satellite Server certificate.

   3

   Path to the Certificate Authority bundle.

   If the command is successful, it returns two satellite-installer commands, one of which you must use to deploy a certificate to Satellite Server.

   Example output of katello-certs-check

   Validation succeeded.
   
   To install the Red Hat Satellite Server with the custom certificates, run:
   
     satellite-installer --scenario satellite \
       --certs-server-cert "/root/satellite_cert/satellite_cert.pem" \
       --certs-server-key "/root/satellite_cert/satellite_cert_key.pem" \
       --certs-server-ca-cert "/root/satellite_cert/ca_cert_bundle.pem"
   
   To update the certificates on a currently running Red Hat Satellite installation, run:
   
     satellite-installer --scenario satellite \
       --certs-server-cert "/root/satellite_cert/satellite_cert.pem" \
       --certs-server-key "/root/satellite_cert/satellite_cert_key.pem" \
       --certs-server-ca-cert "/root/satellite_cert/ca_cert_bundle.pem" \
       --certs-update-server --certs-update-server-ca

   Note that you must not access or modify /root/ssl-build.

2. From the output of the katello-certs-check command, depending on your requirements, enter the satellite-installer command that installs a new Satellite with custom SSL certificates or updates certificates on a currently running Satellite.

   If you are unsure which command to run, you can verify that Satellite is installed by checking if the file /etc/foreman-installer/scenarios.d/.installed exists. If the file exists, run the second satellite-installer command that updates certificates.

   Important

   satellite-installer needs the certificate archive file after you deploy the certificate. Do not modify or delete it. It is required, for example, when upgrading Satellite Server.

3. On a computer with network access to Satellite Server, navigate to the following URL: https://satellite.example.com.
4. In your browser, view the certificate details to verify the deployed certificate.

Procedure

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=satellite-6.13-for-rhel-8-x86_64-rpms \
   --enable=satellite-maintenance-6.13-for-rhel-8-x86_64-rpms \
   --enable=rhel-8-for-x86_64-baseos-rpms \
   --enable=rhel-8-for-x86_64-appstream-rpms

3. Enable the following modules:

   # dnf module enable satellite:el8

   Note

   Enablement of the module satellite:el8 warns about a conflict with postgresql:10 and ruby:2.5 as these modules are set to the default module versions on Red Hat Enterprise Linux 8. The module satellite:el8 has a dependency for the modules postgresql:12 and ruby:2.7 that will be enabled with the satellite:el8 module. These warnings do not cause installation process failure, hence can be ignored safely. For more information about modules and lifecycle streams on Red Hat Enterprise Linux 8, see Red Hat Enterprise Linux Application Streams Life Cycle.

Procedure

1. To install PostgreSQL, enter the following command:

   # dnf install postgresql-server postgresql-evr

2. To initialize PostgreSQL, enter the following command:

   # postgresql-setup initdb

3. Edit the /var/lib/pgsql/data/postgresql.conf file:

   # vi /var/lib/pgsql/data/postgresql.conf

   Note that the default configuration of external PostgreSQL needs to be adjusted to work with Satellite. The base recommended external database configuration adjustments are as follows:

   • checkpoint_completion_target: 0.9
   • max_connections: 500
   • shared_buffers: 512MB
   • work_mem: 4MB

4. Remove the # and edit to listen to inbound connections:

   listen_addresses = '*'

5. Edit the /var/lib/pgsql/data/pg_hba.conf file:

   # vi /var/lib/pgsql/data/pg_hba.conf

6. Add the following line to the file:

     host  all   all   Satellite_ip/32   md5

7. To start, and enable PostgreSQL service, enter the following commands:

   # systemctl enable --now 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 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"
    # PGPASSWORD='Pulpcore_Password' psql -h postgres.example.com -p 5432 -U pulp -d pulpcore -c "SELECT 1 as ping"

Procedure

1. To configure the external databases for Satellite, enter the following command:

   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 \
     --foreman-proxy-content-pulpcore-manage-postgresql false \
     --foreman-proxy-content-pulpcore-postgresql-host postgres.example.com \
     --foreman-proxy-content-pulpcore-postgresql-db-name pulpcore \
     --foreman-proxy-content-pulpcore-postgresql-password Pulpcore_Password
     --foreman-proxy-content-pulpcore-postgresql-user pulp

   To enable the Secure Sockets Layer (SSL) protocol for these external databases, add the following options:

   --foreman-db-sslmode verify-full
   --foreman-db-root-cert <path_to_CA>
   --katello-candlepin-db-ssl true
   --katello-candlepin-db-ssl-verify true
   --katello-candlepin-db-ssl-ca <path_to_CA>
   --foreman-proxy-content-pulpcore-postgresql-ssl true
   --foreman-proxy-content-pulpcore-postgresql-ssl-root-ca <path_to_CA>

Procedure

1. Obtain the Certificate from the LDAP Server.

   1. If you use Active Directory Certificate Services, export the Enterprise PKI CA Certificate using the Base-64 encoded X.509 format. See How to configure Active Directory authentication with TLS on Satellite for information on creating and exporting a CA certificate from an Active Directory server.

   2. Download the LDAP server certificate to a temporary location onto Satellite Server and remove it when finished.

      For example, /tmp/example.crt. The filename extensions .cer and .crt are only conventions and can refer to DER binary or PEM ASCII format certificates.

2. Trust the Certificate from the LDAP Server.

   Satellite Server requires the CA certificates for LDAP authentication to be individual files in /etc/pki/tls/certs/ directory.

   1. Use the install command to install the imported certificate into the /etc/pki/tls/certs/ directory with the correct permissions:

      # install /tmp/example.crt /etc/pki/tls/certs/

   2. Enter the following command as root to trust the example.crt certificate obtained from the LDAP server:

      # ln -s example.crt /etc/pki/tls/certs/$(openssl \
      x509 -noout -hash -in \
      /etc/pki/tls/certs/example.crt).0

   3. Restart the httpd service:

      # systemctl restart httpd

Procedure

1. Set the Network Information System (NIS) service boolean to true to prevent SELinux from stopping outgoing LDAP connections:

   # setsebool -P nis_enabled on

2. In the Satellite web UI, navigate to Administer > Authentication Sources.
3. Click Create LDAP Authentication Source.
4. On the LDAP server tab, enter the LDAP server’s name, host name, port, and server type. The default port is 389, the default server type is POSIX (alternatively you can select FreeIPA or Active Directory depending on the type of authentication server). For TLS encrypted connections, select the LDAPS checkbox to enable encryption. The port should change to 636, which is the default for LDAPS.
5. On the Account tab, enter the account information and domain name details. See Section 5.1.3, “Description of LDAP Settings” for descriptions and examples.
6. On the Attribute mappings tab, map LDAP attributes to Satellite attributes. You can map login name, first name, last name, email address, and photo attributes. See Section 5.1.4, “Example Settings for LDAP Connections” for examples.
7. On the Locations tab, select locations from the left table. Selected locations are assigned to users created from the LDAP authentication source, and available after their first login.
8. On the Organizations tab, select organizations from the left table. Selected organizations are assigned to users created from the LDAP authentication source, and available after their first login.
9. Click Submit.

10. Configure new accounts for LDAP users:

    • If you did not select Automatically Create Accounts In Satellite checkbox, see Creating a User in Administering Red Hat Satellite to create user accounts manually.
    • If you selected the Automatically Create Accounts In Satellite checkbox, LDAP users can now log in to Satellite using their LDAP accounts and passwords. After they log in for the first time, the Satellite administrator has to assign roles to them manually. For more information on assigning user accounts appropriate roles in Satellite, see Assigning Roles to a User in Administering Red Hat Satellite.

Procedure

1. On the Red Hat Identity Management server, to authenticate, enter the following command and enter your password when prompted:

   # kinit admin

2. To verify that you have authenticated, enter the following command:

   # klist

3. On the Red Hat Identity Management server, create a host entry for Satellite Server and generate a one-time password, for example:

   # ipa host-add --random hostname

   Note

   The generated one-time password must be used on the client to complete Red Hat Identity Management-enrollment.

   For more information on host configuration properties, see Host entry in IdM LDAP in Configuring and managing Identity Management.

4. Create an HTTP service for Satellite Server, for example:

   # ipa service-add HTTP/hostname

   For more information on managing services, see Red Hat Enterprise Linux 8 Accessing Identity Management Services guide.

5. On Satellite Server, install the IPA client:

   Warning

   This command might restart Satellite services during the installation of the package. For more information about installing and updating packages on Satellite, see Managing Packages on the Base Operating System of Satellite Server or Capsule Server in Administering Red Hat Satellite.

   # satellite-maintain packages install ipa-client

6. On Satellite Server, enter the following command as root to configure Red Hat Identity Management-enrollment:

   # ipa-client-install --password OTP

   Replace OTP with the one-time password provided by the Red Hat Identity Management administrator.

7. Set Red Hat Identity Management as the authentication provider, using one of the following commands:

   • If you only want to enable access to the Satellite web UI but not the Satellite API, enter:

     # satellite-installer \
     --foreman-ipa-authentication=true

   • If you want to enable access both to the Satellite web UI and the Satellite API, enter:

     # satellite-installer \
     --foreman-ipa-authentication-api=true \
     --foreman-ipa-authentication=true

     Warning

     Enabling access to both the Satellite API and the Satellite web UI can lead to security problems. After an IdM user receives a Kerberos ticket-granting ticket (TGT) by entering kinit user_name, an attacker can obtain an API session. The attack is possible even if the user did not previously enter the Satellite login credentials anywhere, for example in the browser.

8. Restart Satellite services:

   # satellite-maintain service restart

Procedure

1. On the Red Hat Identity Management server, to authenticate, enter the following command and enter your password when prompted:

   # kinit admin

2. To verify that you have authenticated, enter the following command:

   # klist

3. Create HBAC service and rule on the Red Hat Identity Management server and link them together. The following examples use the PAM service name satellite-prod. Execute the following commands on the Red Hat Identity Management server:

   # ipa hbacsvc-add satellite-prod
   # ipa hbacrule-add allow_satellite_prod
   # ipa hbacrule-add-service allow_satellite_prod --hbacsvcs=satellite-prod

4. Add the user who is to have access to the service satellite-prod, and the hostname of Satellite Server:

   # ipa hbacrule-add-user allow_satellite_prod --user=username
   # ipa hbacrule-add-host allow_satellite_prod --hosts=satellite.example.com

   Alternatively, host groups and user groups can be added to the allow_satellite_prod rule.

5. To check the status of the rule, execute:

   # ipa hbacrule-find satellite-prod
   # ipa hbactest --user=username --host=satellite.example.com --service=satellite-prod

6. Ensure the allow_all rule is disabled on the Red Hat Identity Management server. For instructions on how to do so without disrupting other services see the How to configure HBAC rules in IdM article on the Red Hat Customer Portal.

7. Configure the Red Hat Identity Management integration with Satellite Server as described in Section 5.2.1, “Configuring Red Hat Identity Management Authentication on Satellite Server”. On Satellite Server, define the PAM service as root:

   # satellite-installer --foreman-pam-service=satellite-prod

Procedure

1. Install the required packages:

   # satellite-maintain packages install adcli krb5-workstation \
   oddjob oddjob-mkhomedir realmd samba-common-tools sssd

2. Enroll Satellite Server with the AD server. You may need to have administrator permissions to perform the following command:

   # realm join -v EXAMPLE.ORG --membership-software=samba -U Administrator

   Note

   You must use the Samba client software to enroll with the AD server to be able to create the HTTP keytab in Section 5.3.3, “Configuring Direct AD Integration with GSS-Proxy”.

Procedure

1. Create the /etc/ipa/ directory and the default.conf file:

   # mkdir /etc/ipa
   # touch /etc/ipa/default.conf

2. To the default.conf file, add the following content:

   [global]
   server = unused
   realm = EXAMPLE.ORG

3. Create the /etc/net-keytab.conf file with the following content:

   [global]
   workgroup = EXAMPLE
   realm = EXAMPLE.ORG
   kerberos method = system keytab
   security = ads

4. Determine the effective user ID of the Apache user:

   # id apache

   Apache user must not have access to the keytab file.

5. Create the /etc/gssproxy/00-http.conf file with the following content:

   [service/HTTP]
   mechs = krb5
   cred_store = keytab:/etc/httpd/conf/http.keytab
   cred_store = ccache:/var/lib/gssproxy/clients/krb5cc_%U
   euid = ID_of_Apache_User

6. Create a keytab entry:

   # KRB5_KTNAME=FILE:/etc/httpd/conf/http.keytab net ads keytab add HTTP -U administrator -d3 -s /etc/net-keytab.conf
   # chown root.apache /etc/httpd/conf/http.keytab
   # chmod 640 /etc/httpd/conf/http.keytab

7. Enable IPA authentication in Satellite:

   # satellite-installer --foreman-ipa-authentication=true

8. Start and enable the gssproxy service:

   # systemctl restart gssproxy
   # systemctl enable gssproxy

9. To configure the Apache server to use the gssproxy service, create a systemd drop-in file and add the following content to it:

   # mkdir -p /etc/systemd/system/httpd.service.d/
   # vi /etc/systemd/system/httpd.service.d/gssproxy.conf
   [Service]
   Environment=GSS_USE_PROXY=1

10. Apply changes to the service:

    # systemctl daemon-reload

11. Start and enable the httpd service:

    # systemctl restart httpd

1. Retrieve the Kerberos ticket of the LDAP user, using the following command:

   # kinit ldapuser

2. View the Kerberos ticket, using the following command:

   # klist

3. View output from successful SSO-based authentication, using the following command:

   # curl -k -u : --negotiate https://satellite.example.com/users/extlogin

   This returns the following response:

   <html><body>You are being <a href="https://satellite.example.com/users/4-ldapuserexample-com/edit">redirected</a>.</body></html>

Procedure

1. Enable HBAC:

   1. Create an external group and add the AD group to it.
   2. Add the new external group to a POSIX group.
   3. Use the POSIX group in a HBAC rule.

2. Configure sssd to transfer additional attributes of AD users.

   • Add the AD user attributes to the nss and domain sections in /etc/sssd/sssd.conf. For example:

     [nss]
     user_attributes=+mail, +sn, +givenname
     [domain/EXAMPLE.com]
     ...
     krb5_store_password_if_offline = True
     ldap_user_extra_attrs=email:mail, lastname:sn, firstname:givenname
     
     [ifp]
     allowed_uids = ipaapi, root
     user_attributes=+email, +firstname, +lastname

   • Verify the AD attributes value.

     # dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserAttr string:ad-user@ad-domain array:string:email,firstname,lastname

1. Users authenticate to Satellite using the Satellite web UI.
2. Users authenticate to Satellite using the Satellite CLI.

Procedure

1. On Satellite Server, install the following packages:

   # satellite-maintain packages install mod_auth_openidc keycloak-httpd-client-install python3-lxml

2. Register Satellite to Red Hat Single Sign-On as a client. Note that you the registration process for logging in using the web UI and the CLI are different. You can register two clients Satellite clients to Red Hat Single Sign-On to be able to log in to Satellite from the web UI and the CLI.

   • If you want you users to authenticate to Satellite using the web UI, create a client as follows:

     # keycloak-httpd-client-install --app-name foreman-openidc \
     --keycloak-server-url "https://RHSSO.example.com" \
     --keycloak-admin-username "admin" \
     --keycloak-realm "Satellite_Realm" \
     --keycloak-admin-realm master \
     --keycloak-auth-role root-admin \
     -t openidc -l /users/extlogin --force

     Enter the password for the administer account when prompted. This command creates a client for Satellite in Red Hat Single Sign-On.

     Then, configure Satellite to use Red Hat Single Sign-On as an authentication source:

     # satellite-installer --foreman-keycloak true \
     --foreman-keycloak-app-name "foreman-openidc" \
     --foreman-keycloak-realm "Satellite_Realm"

   • If you want your users to authenticate to Satellite using the CLI, create a client as follows:

     # keycloak-httpd-client-install --app-name hammer-openidc \
     --keycloak-server-url "https://RHSSO.example.com" \
     --keycloak-admin-username "admin" \
     --keycloak-realm "Satellite_Realm" \
     --keycloak-admin-realm master \
     --keycloak-auth-role root-admin \
     -t openidc -l /users/extlogin --force

     Enter the password for the administer account when prompted. This command creates a client for Satellite in Red Hat Single Sign-On.

3. Restart the httpd service:

   # systemctl restart httpd

Procedure

1. In the Red Hat Single Sign-On web UI, navigate to Clients and click the Satellite client.

2. Configure access type:

   • If you want your users to authenticate to Satellite using the Satellite web UI, from the Access Type list, select confidential.
   • If you want your users to authenticate to Satellite using the CLI, from the Access Type list, select public.

3. In the Valid redirect URI fields, add a valid redirect URI.

   • If you want your users to authenticate to Satellite using the Satellite web UI, in the blank field below the existing URI, enter a URI in the form https://satellite.example.com/users/extlogin. Note that you must add the string /users/extlogin after the Satellite FQDN.

     After completing this step, the Satellite client for logging in using the Satellite web UI must have the following Valid Redirect URIs:

     https://satellite.example.com/users/extlogin/redirect_uri
     https://satellite.example.com/users/extlogin

   • If you want your users to authenticate to Satellite using the CLI, in the blank field below the existing URI, enter urn:ietf:wg:oauth:2.0:oob.

     After completing this step, the Satellite client for logging in using the CLI must have the following Valid Redirect URIs:

     https://satellite.example.com/users/extlogin/redirect_uri
     urn:ietf:wg:oauth:2.0:oob

4. Click Save.
5. Click the Mappers tab and click Create to add an audience mapper.
6. In the Name field, enter a name for the audience mapper.
7. From the Mapper Type list, select Audience.
8. From the Included Client Audience list, select the Satellite client.
9. Click Save.
10. Click Create to add a group mapper so that you can specify authorization in Satellite based on group membership.
11. In the Name field, enter a name for the group mapper.
12. From the Mapper Type list, select Group Membership.
13. In the Token Claim Name field, enter groups.
14. Set the Full group path setting to OFF.
15. Click Save.

Procedure

1. To authenticate to the Satellite CLI using the code grant type, enter the following command:

   # hammer auth login oauth \
   --two-factor \
   --oidc-token-endpoint 'https://RHSSO.example.com/auth/realms/ssl-realm/protocol/openid-connect/token' \
   --oidc-authorization-endpoint 'https://RHSSO.example.com/auth' \
   --oidc-client-id 'satellite.example.com-foreman-openidc' \
   --oidc-redirect-uri urn:ietf:wg:oauth:2.0:oob

   The command prompts you to enter a success code.

2. To retrieve the success code, navigate to the URL that the command returns and provide the required information.
3. Copy the success code that the web UI returns.
4. In the command prompt of hammer auth login oauth, enter the success code to authenticate to the Satellite CLI.

Procedure

1. In the Satellite web UI, navigate to Administer > User Groups, and click the Create User Group button.
2. In the Name field, enter a name for the user group. The name should not be the same as in the Active Directory.
3. Do not add users and user groups to the right-hand columns. Click the Roles tab.
4. Select the Administer checkbox.
5. Click the External Groups tab.
6. Click Add external user group.
7. In the Name field, enter the name of the Active Directory group.
8. From the list, select EXTERNAL.

1. Users authenticate to Satellite using the Satellite web UI.
2. Users authenticate to Satellite using the Satellite CLI.

Procedure

1. On Satellite Server, install the following packages:

   # satellite-maintain packages install mod_auth_openidc keycloak-httpd-client-install python3-lxml

2. Register Satellite to Red Hat Single Sign-On as a client. Note that you the registration process for logging in using the web UI and the CLI are different. You can register two clients Satellite clients to Red Hat Single Sign-On to be able to log in to Satellite from the web UI and the CLI.

   • If you want you users to authenticate to Satellite using the web UI, create a client as follows:

     # keycloak-httpd-client-install --app-name foreman-openidc \
     --keycloak-server-url "https://RHSSO.example.com" \
     --keycloak-admin-username "admin" \
     --keycloak-realm "Satellite_Realm" \
     --keycloak-admin-realm master \
     --keycloak-auth-role root-admin \
     -t openidc -l /users/extlogin --force

     Enter the password for the administer account when prompted. This command creates a client for Satellite in Red Hat Single Sign-On.

     Then, configure Satellite to use Red Hat Single Sign-On as an authentication source:

     # satellite-installer --foreman-keycloak true \
     --foreman-keycloak-app-name "foreman-openidc" \
     --foreman-keycloak-realm "Satellite_Realm"

   • If you want your users to authenticate to Satellite using the CLI, create a client as follows:

     # keycloak-httpd-client-install --app-name hammer-openidc \
     --keycloak-server-url "https://RHSSO.example.com" \
     --keycloak-admin-username "admin" \
     --keycloak-realm "Satellite_Realm" \
     --keycloak-admin-realm master \
     --keycloak-auth-role root-admin \
     -t openidc -l /users/extlogin --force

     Enter the password for the administer account when prompted. This command creates a client for Satellite in Red Hat Single Sign-On.

3. Restart the httpd service:

   # systemctl restart httpd

Procedure

1. In the Red Hat Single Sign-On web UI, navigate to Clients and click the Satellite client.

2. Configure access type:

   • If you want your users to authenticate to Satellite using the Satellite web UI, from the Access Type list, select confidential.
   • If you want your users to authenticate to Satellite using the CLI, from the Access Type list, select public.

3. In the Valid redirect URI fields, add a valid redirect URI.

   • If you want your users to authenticate to Satellite using the Satellite web UI, in the blank field below the existing URI, enter a URI in the form https://satellite.example.com/users/extlogin. Note that you must add the string /users/extlogin after the Satellite FQDN.

     After completing this step, the Satellite client for logging in using the Satellite web UI must have the following Valid Redirect URIs:

     https://satellite.example.com/users/extlogin/redirect_uri
     https://satellite.example.com/users/extlogin

   • If you want your users to authenticate to Satellite using the CLI, in the blank field below the existing URI, enter urn:ietf:wg:oauth:2.0:oob.

     After completing this step, the Satellite client for logging in using the CLI must have the following Valid Redirect URIs:

     https://satellite.example.com/users/extlogin/redirect_uri
     urn:ietf:wg:oauth:2.0:oob

4. Click Save.
5. Click the Mappers tab and click Create to add an audience mapper.
6. In the Name field, enter a name for the audience mapper.
7. From the Mapper Type list, select Audience.
8. From the Included Client Audience list, select the Satellite client.
9. Click Save.
10. Click Create to add a group mapper so that you can specify authorization in Satellite based on group membership.
11. In the Name field, enter a name for the group mapper.
12. From the Mapper Type list, select Group Membership.
13. In the Token Claim Name field, enter groups.
14. Set the Full group path setting to OFF.
15. Click Save.

Procedure

1. In the Red Hat Single Sign-On web UI, navigate to the Satellite realm.
2. Navigate to Authentication, and click the OTP Policy tab.
3. Ensure that the Supported Applications field includes FreeOTP or Google Authenticator.
4. Configure the OTP settings to suit your requirements.
5. Optional: If you want to use TOTP authentication as a default authentication method for all users, click the Flows tab, and to the right of the OTP Form setting, select REQUIRED.
6. Click the Required Actions tab.
7. To the right of the Configure OTP row, select the Default Action checkbox.

Procedure

1. Log in to Satellite, Satellite redirects you to the Red Hat Single Sign-On login screen.
2. Enter your username and password, and click Log In.
3. The first attempt to log in, Red Hat Single Sign-On requests you to configure your client by scanning the barcode and entering the pin displayed.
4. After you configure your client and enter a valid PIN, Red Hat Single Sign-On redirects you to Satellite and logs you in.

Procedure

1. To authenticate to the Satellite CLI using the code grant type, enter the following command:

   # hammer auth login oauth \
   --two-factor \
   --oidc-token-endpoint 'https://RHSSO.example.com/auth/realms/ssl-realm/protocol/openid-connect/token' \
   --oidc-authorization-endpoint 'https://RHSSO.example.com/auth' \
   --oidc-client-id 'satellite.example.com-foreman-openidc' \
   --oidc-redirect-uri urn:ietf:wg:oauth:2.0:oob

   The command prompts you to enter a success code.

2. To retrieve the success code, navigate to the URL that the command returns and provide the required information.
3. Copy the success code that the web UI returns.
4. In the command prompt of hammer auth login oauth, enter the success code to authenticate to the Satellite CLI.

Procedure

1. In the Satellite web UI, navigate to Administer > User Groups, and click the Create User Group button.
2. In the Name field, enter a name for the user group. The name should not be the same as in the Active Directory.
3. Do not add users and user groups to the right-hand columns. Click the Roles tab.
4. Select the Administer checkbox.
5. Click the External Groups tab.
6. Click Add external user group.
7. In the Name field, enter the name of the Active Directory group.
8. From the list, select EXTERNAL.

Procedure

1. On your Red Hat Enterprise Linux host, install the ISC DHCP Service and Berkeley Internet Name Domain (BIND) utilities packages:

   # dnf install dhcp-server bind-utils

2. Generate a security token:

   # tsig-keygen -a hmac-md5 omapi_key

3. Edit the dhcpd configuration file for all subnets and add the key generated by tsig-keygen. The following is an example:

   # cat /etc/dhcp/dhcpd.conf
   default-lease-time 604800;
   max-lease-time 2592000;
   log-facility local7;
   
   subnet 192.168.38.0 netmask 255.255.255.0 {
   	range 192.168.38.10 192.168.38.100;
   	option routers 192.168.38.1;
   	option subnet-mask 255.255.255.0;
   	option domain-search "virtual.lan";
   	option domain-name "virtual.lan";
   	option domain-name-servers 8.8.8.8;
   }
   
   omapi-port 7911;
   key omapi_key {
   	algorithm hmac-md5;
   	secret "My_Secret";
   };
   omapi-key omapi_key;

   Note that the option routers value is the IP address of your Satellite Server or Capsule Server that you want to use with an external DHCP service.

4. On Satellite Server, define each subnet. Do not set DHCP Capsule for the defined Subnet yet.

   To prevent conflicts, set up the lease and reservation ranges separately. For example, if the lease range is 192.168.38.10 to 192.168.38.100, in the Satellite web UI define the reservation range as 192.168.38.101 to 192.168.38.250.

5. Configure the firewall for external access to the DHCP server:

   # firewall-cmd --add-service dhcp \
   && firewall-cmd --runtime-to-permanent

6. On Satellite Server, determine the UID and GID of the foreman user:

   # id -u foreman
   993
   # id -g foreman
   990

7. On the DHCP server, create the foreman user and group with the same IDs as determined in a previous step:

   # groupadd -g 990 foreman
   # useradd -u 993 -g 990 -s /sbin/nologin foreman

8. To ensure that the configuration files are accessible, restore the read and execute flags:

   # chmod o+rx /etc/dhcp/
   # chmod o+r /etc/dhcp/dhcpd.conf
   # chattr +i /etc/dhcp/ /etc/dhcp/dhcpd.conf

9. Enable and start the DHCP service:

   # systemctl enable --now dhcpd

10. Export the DHCP configuration and lease files using NFS:

    # dnf install nfs-utils
    # systemctl enable --now nfs-server

11. Create directories for the DHCP configuration and lease files that you want to export using NFS:

    # mkdir -p /exports/var/lib/dhcpd /exports/etc/dhcp

12. To create mount points for the created directories, add the following line to the /etc/fstab file:

    /var/lib/dhcpd /exports/var/lib/dhcpd none bind,auto 0 0
    /etc/dhcp /exports/etc/dhcp none bind,auto 0 0

13. Mount the file systems in /etc/fstab:

    # mount -a

14. Ensure the following lines are present in /etc/exports:

    /exports 192.168.38.1(rw,async,no_root_squash,fsid=0,no_subtree_check)
    
    /exports/etc/dhcp 192.168.38.1(ro,async,no_root_squash,no_subtree_check,nohide)
    
    /exports/var/lib/dhcpd 192.168.38.1(ro,async,no_root_squash,no_subtree_check,nohide)

    Note that the IP address that you enter is the Satellite or Capsule IP address that you want to use with an external DHCP service.

15. Reload the NFS server:

    # exportfs -rva

16. Configure the firewall for DHCP omapi port 7911:

    # firewall-cmd --add-port=7911/tcp
    # firewall-cmd --runtime-to-permanent

17. Optional: Configure the firewall for external access to NFS. Clients are configured using NFSv3.

    # firewall-cmd --zone public --add-service mountd \
    && firewall-cmd --zone public --add-service rpc-bind \
    && firewall-cmd --zone public --add-service nfs \
    && firewall-cmd --runtime-to-permanent

Procedure

1. Install the nfs-utils package:

   # dnf install nfs-utils

2. Create the DHCP directories for NFS:

   # mkdir -p /mnt/nfs/etc/dhcp /mnt/nfs/var/lib/dhcpd

3. Change the file owner:

   # chown -R foreman-proxy /mnt/nfs

4. Verify communication with the NFS server and the Remote Procedure Call (RPC) communication paths:

   # showmount -e DHCP_Server_FQDN
   # rpcinfo -p DHCP_Server_FQDN

5. Add the following lines to the /etc/fstab file:

   DHCP_Server_FQDN:/exports/etc/dhcp /mnt/nfs/etc/dhcp nfs
   ro,vers=3,auto,nosharecache,context="system_u:object_r:dhcp_etc_t:s0" 0 0
   
   DHCP_Server_FQDN:/exports/var/lib/dhcpd /mnt/nfs/var/lib/dhcpd nfs
   ro,vers=3,auto,nosharecache,context="system_u:object_r:dhcpd_state_t:s0" 0 0

6. Mount the file systems on /etc/fstab:

   # mount -a

7. To verify that the foreman-proxy user can access the files that are shared over the network, display the DHCP configuration and lease files:

   # su foreman-proxy -s /bin/bash
   bash-4.2$ cat /mnt/nfs/etc/dhcp/dhcpd.conf
   bash-4.2$ cat /mnt/nfs/var/lib/dhcpd/dhcpd.leases
   bash-4.2$ exit

8. Enter the satellite-installer command to make the following persistent changes to the /etc/foreman-proxy/settings.d/dhcp.yml file:

   # satellite-installer --foreman-proxy-dhcp=true \
   --foreman-proxy-dhcp-provider=remote_isc \
   --foreman-proxy-plugin-dhcp-remote-isc-dhcp-config /mnt/nfs/etc/dhcp/dhcpd.conf \
   --foreman-proxy-plugin-dhcp-remote-isc-dhcp-leases /mnt/nfs/var/lib/dhcpd/dhcpd.leases \
   --foreman-proxy-plugin-dhcp-remote-isc-key-name=omapi_key \
   --foreman-proxy-plugin-dhcp-remote-isc-key-secret=jNSE5YI3H1A8Oj/tkV4...A2ZOHb6zv315CkNAY7DMYYCj48Umw== \
   --foreman-proxy-plugin-dhcp-remote-isc-omapi-port=7911 \
   --enable-foreman-proxy-plugin-dhcp-remote-isc \
   --foreman-proxy-dhcp-server=DHCP_Server_FQDN

9. Associate the DHCP service with the appropriate subnets and domain.

Creating a Kerberos Principal on the IdM Server

1. Obtain a Kerberos ticket for the account obtained from the IdM administrator:

   # kinit idm_user

2. Create a new Kerberos principal for Satellite Server to use to authenticate on the IdM server.

   # ipa service-add capsule/satellite.example.com

Installing and Configuring the IdM Client

1. On the base operating system of either the Satellite or Capsule that is managing the DNS service for your deployment, install the ipa-client package:

   # satellite-maintain packages install ipa-client

2. Configure the IdM client by running the installation script and following the on-screen prompts:

   # ipa-client-install

3. Obtain a Kerberos ticket:

   # kinit admin

4. Remove any preexisting keytab:

   # rm /etc/foreman-proxy/dns.keytab

5. Obtain the keytab for this system:

   # ipa-getkeytab -p capsule/satellite.example.com@EXAMPLE.COM \
   -s idm1.example.com -k /etc/foreman-proxy/dns.keytab

   Note

   When adding a keytab to a standby system with the same host name as the original system in service, add the r option to prevent generating new credentials and rendering the credentials on the original system invalid.

6. For the dns.keytab file, set the group and owner to foreman-proxy:

   # chown foreman-proxy:foreman-proxy /etc/foreman-proxy/dns.keytab

7. Optional: To verify that the keytab file is valid, enter the following command:

   # kinit -kt /etc/foreman-proxy/dns.keytab \
   capsule/satellite.example.com@EXAMPLE.COM

Configuring DNS Zones in the IdM web UI

1. Create and configure the zone that you want to manage:

   1. Navigate to Network Services > DNS > DNS Zones.
   2. Select Add and enter the zone name. For example, example.com.
   3. Click Add and Edit.

   4. Click the Settings tab and in the BIND update policy box, add the following to the semi-colon separated list:

      grant capsule\047satellite.example.com@EXAMPLE.COM wildcard * ANY;

   5. Set Dynamic update to True.
   6. Enable Allow PTR sync.
   7. Click Save to save the changes.

2. Create and configure the reverse zone:

   1. Navigate to Network Services > DNS > DNS Zones.
   2. Click Add.
   3. Select Reverse zone IP network and add the network address in CIDR format to enable reverse lookups.
   4. Click Add and Edit.

   5. Click the Settings tab and in the BIND update policy box, add the following to the semi-colon separated list:

      grant capsule\047satellite.example.com@EXAMPLE.COM wildcard * ANY;

   6. Set Dynamic update to True.
   7. Click Save to save the changes.

Configuring the Satellite or Capsule Server that Manages the DNS Service for the Domain

1. Use the satellite-installer command to configure the Satellite or Capsule that manages the DNS Service for the domain:

   • On Satellite, enter the following command:

     satellite-installer --scenario satellite \
     --foreman-proxy-dns=true \
     --foreman-proxy-dns-managed=false \
     --foreman-proxy-dns-provider=nsupdate_gss \
     --foreman-proxy-dns-server="idm1.example.com" \
     --foreman-proxy-dns-tsig-principal="capsule/satellite.example.com@EXAMPLE.COM" \
     --foreman-proxy-dns-tsig-keytab=/etc/foreman-proxy/dns.keytab

   • On Capsule, enter the following command:

     satellite-installer --scenario capsule \
     --foreman-proxy-dns=true \
     --foreman-proxy-dns-managed=false \
     --foreman-proxy-dns-provider=nsupdate_gss \
     --foreman-proxy-dns-server="idm1.example.com" \
     --foreman-proxy-dns-tsig-principal="capsule/satellite.example.com@EXAMPLE.COM" \
     --foreman-proxy-dns-tsig-keytab=/etc/foreman-proxy/dns.keytab

Updating the Configuration in the Satellite web UI

1. In the Satellite web UI, navigate to Infrastructure > Capsules, locate the Satellite Server, and from the list in the Actions column, select Refresh.

2. Configure the domain:

   1. In the Satellite web UI, navigate to Infrastructure > Domains and select the domain name.
   2. In the Domain tab, ensure DNS Capsule is set to the Capsule where the subnet is connected.

3. Configure the subnet:

   1. In the Satellite web UI, navigate to Infrastructure > Subnets and select the subnet name.
   2. In the Subnet tab, set IPAM to None.
   3. In the Domains tab, select the domain that you want to manage using the IdM server.
   4. In the Capsules tab, ensure Reverse DNS Capsule is set to the Capsule where the subnet is connected.
   5. Click Submit to save the changes.

Enabling External Updates to the DNS Zone in the IdM Server

1. On the IdM Server, add the following to the top of the /etc/named.conf file:

   ########################################################################
   
   include "/etc/rndc.key";
   controls  {
   inet _IdM_Server_IP_Address_ port 953 allow { _Satellite_IP_Address_; } keys { "rndc-key"; };
   };
   ########################################################################

2. Reload the named service to make the changes take effect:

   # systemctl reload named

3. In the IdM web UI, navigate to Network Services > DNS > DNS Zones and click the name of the zone. In the Settings tab, apply the following changes:

   1. Add the following in the BIND update policy box:

      grant "rndc-key" zonesub ANY;

   2. Set Dynamic update to True.
   3. Click Update to save the changes.

4. Copy the /etc/rndc.key file from the IdM server to the base operating system of your Satellite Server. Enter the following command:

   # scp /etc/rndc.key root@satellite.example.com:/etc/rndc.key

5. To set the correct ownership, permissions, and SELinux context for the rndc.key file, enter the following command:

   # restorecon -v /etc/rndc.key
   # chown -v root:named /etc/rndc.key
   # chmod -v 640 /etc/rndc.key

6. Assign the foreman-proxy user to the named group manually. Normally, satellite-installer ensures that the foreman-proxy user belongs to the named UNIX group, however, in this scenario Satellite does not manage users and groups, therefore you need to assign the foreman-proxy user to the named group manually.

   # usermod -a -G named foreman-proxy

7. On Satellite Server, enter the following satellite-installer command to configure Satellite to use the external DNS server:

   # satellite-installer --scenario satellite \
   --foreman-proxy-dns=true \
   --foreman-proxy-dns-managed=false \
   --foreman-proxy-dns-provider=nsupdate \
   --foreman-proxy-dns-server="IdM_Server_IP_Address" \
   --foreman-proxy-keyfile=/etc/rndc.key \
   --foreman-proxy-dns-ttl=86400

Testing External Updates to the DNS Zone in the IdM Server

1. Ensure that the key in the /etc/rndc.key file on Satellite Server is the same key file that is used on the IdM server:

   key "rndc-key" {
           algorithm hmac-md5;
           secret "secret-key==";
   };

2. On Satellite Server, create a test DNS entry for a host. For example, host test.example.com with an A record of 192.168.25.20 on the IdM server at 192.168.25.1.

   # echo -e "server 192.168.25.1\n \
   update add test.example.com 3600 IN A 192.168.25.20\n \
   send\n" | nsupdate -k /etc/rndc.key

3. On Satellite Server, test the DNS entry:

   # nslookup test.example.com 192.168.25.1
   Server:		192.168.25.1
   Address:	192.168.25.1#53
   
   Name:	test.example.com
   Address: 192.168.25.20

4. To view the entry in the IdM web UI, navigate to Network Services > DNS > DNS Zones. Click the name of the zone and search for the host by name.

5. If resolved successfully, remove the test DNS entry:

   # echo -e "server 192.168.25.1\n \
   update delete test.example.com 3600 IN A 192.168.25.20\n \
   send\n" | nsupdate -k /etc/rndc.key

6. Confirm that the DNS entry was removed:

   # nslookup test.example.com 192.168.25.1

   The above nslookup command fails and returns the SERVFAIL error message if the record was successfully deleted.

Updating the Configuration in the Satellite web UI

1. In the Satellite web UI, navigate to Infrastructure > Capsules.
2. For each Capsule that you want to update, from the Actions list, select Refresh.

3. Configure the domain:

   1. In the Satellite web UI, navigate to Infrastructure > Domains and click the domain name that you want to configure.
   2. In the Domain tab, set DNS Capsule to the Capsule where the subnet is connected.

4. Configure the subnet:

   1. In the Satellite web UI, navigate to Infrastructure > Subnets and select the subnet name.
   2. In the Subnet tab, set IPAM to DHCP or Internal DB.
   3. In the Domains tab, select the domain that you want to manage using Satellite or Capsule.
   4. In the Capsules tab, set Reverse DNS Capsule to the Capsule where the subnet is connected.
   5. Click Submit to save the changes.