Administering Foreman

1. 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.

1.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.

1.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.

1.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.

1.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.

1.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 1. 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.

1.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
```

1.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

2. Renewing certificates

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

2.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.

Next steps

If you have Smart Proxy servers, you must update their certificates to trust the renewed Foreman server certificates. For more information, see Configuring Smart Proxy server with SSL certificates in Installing a Smart Proxy Server nightly on Enterprise Linux.

2.2. Renewal of SSL certificates

When you use SSL certificates with Foreman, you must renew them before they expire and redeploy them using the same installer options as during the original installation.

2.3. Planning for self-signed CA certificate renewal

If you need to update the Certification Authority (CA) certificate on your Foreman server, 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

Add the new SSL certificate to the CA certificate file on Foreman server and keep the old SSL certificate.
Renew the certificates on Foreman server and 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.
Renew the certificates on Foreman server and any Smart Proxy servers.
Deploy the new CA certificate on hosts.

Additional resources

Refreshing the self-signed CA certificate on hosts in Managing hosts

Pre-release version Report issue