Administering Foreman

1. Tuning performance with predefined profiles

If your Foreman deployment includes a large number of hosts, you can use predefined tuning profiles to configure your Foreman server to use the optimal amount of CPU cores and memory. This can help improve Foreman performance.

Procedure

Select the profile that best matches your use case:

Table 1. Predefined tuning profiles
Tuning profile	Number of hosts	RAM	Number of CPU cores
default	0 – 5000	20G	4
medium	5001 – 10000	32G	8
large	10001 – 20000	64G	16
extra-large	20001 – 60000	128G	32
extra-extra-large	60000+	256G	48+

Apply a predefined tuning profile to your Foreman server:
```
# foremanctl deploy --tuning My_profile
```
Replace My_profile with the name of the profile you want to apply.

2. Backing up Foreman

You can back up your Foreman deployment to ensure the continuity of your Foreman deployment and associated data in case a disaster occurs. If your deployment uses custom configurations, you must consider how to handle these custom configurations when you plan your backup and disaster recovery policy.

2.1. Planning Foreman backup

Backing up your Foreman server requires you to plan scheduling, storage, and security so you avoid disruption and protect sensitive data.

2.1.1. Available backup methods

You can create an offline backup of your Foreman server.

Offline backup

All Foreman services are stopped during an offline backup to ensure data consistency. The backup process includes the following actions:

Preflight checks to verify that no tasks are running and that the database is consistent.
Service shutdown to stop all Foreman services cleanly.
PostgreSQL database dumps to backup content and configuration.
Configuration backup to archive the foremanctl state and configuration.
Content backup to back up Pulp content directory. This is an optional action. You can skip this action by using the --skip-pulp-content option with the foremanctl backup command.
Service restart to restore all Foreman services.

2.1.2. Best practices for backing up Foreman

Apply these recommendations when scheduling and storing backups so you protect sensitive data and avoid conflicts with other administrators.

Foreman community recommends backing up Foreman to a separate storage device on a separate system. The foremanctl backup command creates a backup of your Foreman server and all associated data.

Foreman services are unavailable during the backup. Coordinate with other administrators to ensure no conflicting tasks run during the backup window.

Warning

Request other users of Foreman server to save any changes and warn them that Foreman services are unavailable for the duration of the backup. Ensure no other tasks are scheduled for the same time as the backup.

You can schedule a backup by using cron.

Note	During offline backups, the services are inactive and Foreman is in a maintenance mode. A firewall rejects traffic from outside on port 443 to ensure there are no modifications triggered.

Encrypt or move the backup to a secure location to minimize the risk of damage or unauthorized access to the hosts. A backup has sensitive information from the /root/ssl-build directory. For example, it can have hostnames, SSH keys, request files and SSL certificates.
Because the foremanctl backup command does not automatically delete old backups, consider implementing backup retention policies, including rotating old backups and monitoring backup storage usage.

2.1.3. Directories created during backups

Foreman organizes backups in time-stamped subdirectories, which helps you identify and select the correct backup when restoring your system.

The foremanctl backup command creates a time-stamped subdirectory in the backup directory that you specify. The foremanctl backup command does not overwrite backups, therefore you must select the correct directory or subdirectory when restoring from a backup or an incremental backup.

Foreman creates the following default backup directory:

foreman-backup on Foreman server

If you want to set a custom directory name, add the --preserve-directory option and add a directory name. The backup is then stored in the directory you provide in the command line. If you use the --preserve-directory option, no data is removed if the backup fails.

2.1.4. Estimating the size of a backup

Estimate how much disk space a Foreman backup requires so you can ensure enough storage is available and avoid backup failures.

A full backup requires space to store the following data:

Uncompressed Foreman database and configuration files
Compressed Foreman database and configuration files
An extra 20% of the total estimated space to ensure a reliable backup

Compression occurs after the archives are created to decrease the time when Foreman services are unavailable.

Procedure

Estimate the size of uncompressed directories containing Foreman database and configuration files:

# du -sh /var/lib/pgsql/data /var/lib/pulp
100G    /var/lib/pgsql/data
100G	/var/lib/pulp

# du -csh /var/lib/tftpboot /etc /root/ssl-build \
/var/www/html/pub /opt/puppetlabs
16M   /var/lib/tftpboot
37M   /etc
900K  /root/ssl-build
100K  /var/www/html/pub
2M    /opt/puppetlabs
942M  total

Calculate how much space is required to store the compressed data.

The following table describes the compression ratio of all data items included in the backup:

Table 2. Backup data compression ratio
Data type	Directory	Ratio	Example results
PostgreSQL database files	`/var/lib/pgsql/data`	80 – 85%	100 GB → 20 GB
Pulp RPM files	`/var/lib/pulp`	(not compressed)	100 GB
Configuration files	`/var/lib/tftpboot` `/etc` `/root/ssl-build` `/var/www/html/pub` `/opt/puppetlabs`	85%	942 MB → 141 MB

In this example, the compressed backup data occupies 120 GB in total.

To calculate the amount of available space you require to store a backup, calculate the sum of the estimated values of compressed and uncompressed backup data, and add an extra 20% to ensure a reliable backup.

This example requires 201 GB plus 120 GB for the uncompressed and compressed backup data, 321 GB in total. With 64 GB of extra space, 385 GB must be allocated for the backup location.

2.2. Performing a full backup

Run a full offline backup on Foreman server to capture all Foreman content and configuration. A full backup is useful when you want to prepare for a future restore from scratch.

Prerequisites

Your backup location must have sufficient available disk space to store the backup. For more information, see Estimating the size of a backup.
To enable Foreman to save the backup to an NFS share, the root user of your Foreman server must be able to write to the NFS share. NFS export options such as root_squash and all_squash are known to prevent this. For more information, see Red Hat Enterprise Linux Configuring and using network files services and Red Hat Enterprise Linux Securing network services.

Warning

Procedure

Back up your Foreman server:
```
# foremanctl backup /var/foreman-backup
```

2.3. Performing a backup without Pulp content

Run an offline backup that excludes the contents of the Pulp directory. A backup without Pulp content is useful for debugging purposes and is only intended to provide access to configuration files without backing up the Pulp database.

Warning

Do not use a backup without Pulp content to restore your Foreman server for production use cases.

Prerequisites

Your backup location must have sufficient available disk space to store the backup. For more information, see Estimating the size of a backup.

Procedure

Back up your Foreman server without Pulp content:

# foremanctl backup --skip-pulp-content /var/backup_directory

3. Renewing certificates

You can renew default self-signed server and client certificates as well as the default self-signed certificate authority on Foreman server to prevent them from expiring. You can also renew the custom SSL certificate as well as the custom certificate authority certificate on Foreman server and on Smart Proxy server.

3.1. Renewing self-signed certificates on Foreman server

You can renew expired self-signed server and client certificates on Foreman server to restore secure connections. You can also specify a custom validity period instead of the default 7300 days.

Procedure

Renew server and client certificates:
```
# foremanctl deploy --certificate-renew
```
To set a custom validity period, append --certificate-validity-days My_Days with the validity period in days for the new certificate.

Verification

In your browser, go to your Foreman server login page, for example, https://foreman.example.com, and inspect the certificate in the browser. This is typically displayed as a shield, padlock, or tune icon next to the address bar depending on your browser.
On the command line, verify the new certificate validity period:
```
# echo | openssl s_client -connect 127.0.0.1:443 2>/dev/null | openssl x509 -noout -dates
```
The output displays the notBefore and notAfter dates of the certificate, where notBefore is the date when the certificate becomes valid and notAfter is the date when it expires.

3.2. Renewing self-signed CA certificates

The self-signed certiticate authority (CA) certificate on your Foreman server is valid for 20 years by default. If you need to renew it because the expiration date is close, follow the below procedure.

Procedure

Renew CA certificates:
```
# foremanctl deploy --certificate-ca-renew
```
To set a custom validity period, append --certificate-ca-validity-days My_Days with the validity period in days for the new certificate.

Verification

In your browser, go to your Foreman server login page, for example, https://foreman.example.com, and inspect the CA certificate in the browser. This is typically displayed as a shield, padlock, or tune icon next to the address bar depending on your browser.
On the command line, verify the new certificate validity period:
```
# echo | openssl s_client -connect 127.0.0.1:443 2>/dev/null
```
The output displays the whole SSL connection information. Check the NotBefore and NotAfter dates of CA entry in the "Certificate chain" section, where NotBefore is the date when the certificate becomes valid and NotAfter is the date when it expires.

Next steps

Refresh the CA certificate on your Smart Proxy servers. For more information, see Configuring Smart Proxy server with SSL certificates in Installing a Smart Proxy Server nightly on Enterprise Linux.
Refresh the CA certificate on your hosts. For more information, see Refreshing the self-signed CA certificate on hosts in Managing hosts.

3.3. Renewing a custom SSL certificate on Foreman server

You can deploy a renewed custom SSL certificate on Foreman server to replace an expiring certificate and maintain trusted access to the Foreman web UI and API.

Prerequisites

You have created a new Certificate Signing Request (CSR) and sent it to the Certificate Authority to sign the certificate. Refer to the Configuring Foreman server with a custom SSL certificate guide before creating a new CSR because the Server certificate must have X.509 v3 Key Usage and Extended Key Usage extensions with required values. In return, you will receive the Foreman server certificate and CA bundle.

Procedure

Deploy the renewed CA certificates to Foreman server:

# foremanctl deploy \
--certificate-source custom_server \
--certificate-server-certificate "/root/foreman_cert/foreman_cert.pem" \
--certificate-server-key "/root/foreman_cert/foreman_cert_key.pem" \
--certificate-server-ca-certificate "/root/foreman_cert/ca_cert_bundle.pem"

Verification

Access the Foreman web UI from your local machine. For example, https://foreman.example.com.
In your browser, view the certificate details to verify the deployed certificate.

3.4. Renewing a custom server CA certificate

If you need to update the certification authority (CA) certificate that signed your Foreman server and Smart Proxy servers certificates, add the new CA certificate and use a temporary dual CA certificate file to retain the HTTPS connections to your Foreman server during the renewal.

Procedure

Check if the existing server certificate can be validated with the new CA certififcate.

# openssl verify -CAfile /root/foreman_cert/old_ca_cert_bundle.pem /root/foreman_cert/foreman_cert.pem

If the check did not succeed, use both the old and the new CA certificate while updating consumers.

Add the new SSL certificate to the CA certificate file on Foreman server and keep the old SSL certificate.

# cat /root/foreman_cert/old_ca_cert_bundle.pem /root/foreman_cert/new_ca_cert_bundle.pem > /root/foreman_cert/ca_cert_bundle.pem

Renew the certificates on Foreman server.

# foremanctl deploy \
--certificate-source custom_server \
--certificate-server-certificate "/root/foreman_cert/foreman_cert.pem" \
--certificate-server-key "/root/foreman_cert/foreman_cert_key.pem" \
--certificate-server-ca-certificate "/root/foreman_cert/ca_cert_bundle.pem"

Refresh the certificates on any Smart Proxy servers.
Deploy the dual CA certificate on hosts.
Remove the old certificate from the CA certificates file on Foreman server, so the CA certificate file contains only the new SSL certificate.
```
# cat /root/foreman_cert/new_ca_cert_bundle.pem > /root/foreman_cert/ca_cert_bundle.pem
```

Renew the certificates on Foreman server.

# foremanctl deploy \
--certificate-source custom_server \
--certificate-server-certificate "/root/foreman_cert/foreman_cert.pem" \
--certificate-server-key "/root/foreman_cert/foreman_cert_key.pem" \
--certificate-server-ca-certificate "/root/foreman_cert/ca_cert_bundle.pem"

Refresh the certificates on any Smart Proxy servers.
Deploy the new CA certificate on hosts.

Additional resources

Pre-release version Report issue