Installing Foreman Server with Katello 4.21 plugin (containerized) on Enterprise Linux

Important

The foremanctl deployment utility is a Technology Preview feature only. Technology Preview features are not supported by Foreman community. Foreman community does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

1. Planning Foreman server installation

Review the following guidelines, requirements, and considerations before proceeding with the installation.

1.1. Operating system requirements

Your operating system and installation method must meet the following requirements before you can install Foreman.

The following operating system is supported for deploying Foreman:

Enterprise Linux 9 (x86_64)

Installing Foreman on a system with Extra Packages for Enterprise Linux (EPEL) is not supported.

Additional resources

Glossary term for Enterprise Linux

1.2. System requirements

Your system must meet the following general requirements before you can install Foreman server.

Follow these system requirements when installing Foreman server:

Install Foreman server on a freshly provisioned system that serves no other function except to run Foreman server. Do not use an existing system because the Foreman installer will affect the configuration of several components.
Ensure you have administrative user (root) access to the system.
Ensure the system meets the following requirements:
- 4 CPU cores
- 20 GB RAM or higher
- 4 GB RAM of swap space or higher
- A unique host name, which can contain lower-case letters, numbers, dots (.) and hyphens (-)
If you use custom certificates, ensure that the Common Name (CN) of the custom certificate is a fully qualified domain name (FQDN). Foreman server and Smart Proxy server do not support shortnames in the hostnames.
Ensure SELinux is enabled, either in enforcing or permissive mode. Installation with disabled SELinux is not supported. For more information, see Security considerations in Planning for Foreman.
Ensure the system clock on the system is synchronized across the network. If the system clock is not synchronized, SSL certificate verification might fail.
Ensure the system uses the UTF-8 encoding. If your territory is USA and your language is English, set en_US.utf-8 as the system-wide locale settings. For more information about configuring system locale in Enterprise Linux, see Configuring the system locale in Red Hat Enterprise Linux 9 Configuring basic system settings.
If you use an external identity provider in your deployment, ensure that the provider did not create the apache user account on the system. This user account can cause conflicts with the local users that Foreman server creates.

1.3. Storage requirements

Your system must meet the following storage requirements before you can install Foreman server.

Follow these storage requirements when installing Foreman server:

Ensure that the directories used by Foreman server have sufficient disk space available:

Table 1. Storage requirements for a Foreman server installation
Directory	Installation Size	Runtime Size
/var/log	10 MB	10 GB
/var/lib/pgsql	1 GB	20 GB
/usr	10 GB	Not Applicable
/opt/puppetlabs	500 MB	Not Applicable
/var/lib/pulp	1 MB	300 GB
/var/lib/containers	20 GB	30 GB

These values are based on expected use case scenarios and can vary according to individual environments. The runtime size was measured with Enterprise Linux 7, 8, and 9 repositories synchronized.

If you mount the /tmp directory as a separate file system, use the exec mount option in the /etc/fstab file.

If /tmp is already mounted with the noexec option, change the option to exec and remount the file system. This is a requirement for the puppetserver service to work.
If you mount the /var/lib/pulp directory as an NFS share, specify the SELinux context of the /var/lib/pulp directory in the file system table. Add the following lines to /etc/fstab:
```
nfs.example.com:/nfsshare  /var/lib/pulp  nfs  context="system_u:object_r:pulpcore_var_lib_t:s0"  1 2
```
If the NFS share is already mounted, remount it using the above configuration and restore the SELinux context:
```
# restorecon -R /var/lib/pulp
```
Do not use symbolic links for /var/lib/pulp/.

Additional resources

Disk partitions in Red Hat Enterprise Linux 9 Managing storage devices

1.4. Best practices for optimizing storage

Consider the following storage guidelines for increased storage efficiency.

The exact amount of storage you require for log messages depends on your installation and setup. You can manage the size of the log files by using logrotate.
Consider mounting /var on LVM storage. This can help the system to scale because most Foreman server data is stored in the /var directory.
Use high-bandwidth, low-latency storage for the /var/lib/pulp/ and /var/lib/pgsql directories. Using high latency, low-bandwidth storage causes performance degradation because Foreman has many operations that are I/O intensive.
Use a file system with low input-output latency. Do not use the GFS2 file system because the input-output latency is too high.

Additional resources

Logging and reporting problems in Administering Foreman

1.5. IPv4 and IPv6 requirements

You can install Foreman in an IPv4 network or in an IPv6 network. Your system must meet the following requirements for a successful installation and operation.

The following requirements apply to installations in an IPv4 network:

Ensure an IPv6 loopback is configured on the base system. The loopback is typically configured by default. Do not disable it. Using the ipv6.disable=1 kernel parameter or the net.ipv6.conf.lo.disable_ipv6 = 1 sysctl option will break the installation.

The following requirements apply to installations in an IPv6 network:

If you rely on content from IPv4-only networks, use an external dual-stack HTTP proxy. Configure Foreman to use this dual-stack (supporting both IPv4 and IPv6) HTTP proxy as the default HTTP proxy.
Foreman does not support configuring an HTTP proxy using a direct IPv6 address. Instead, configure the HTTP proxy with a FQDN that resolves to the IPv6 address.

If you intend to provision hosts in an IPv6 network, the following requirements also apply:

Deploy an external DHCPv6 server and configure it manually to communicate with the network boot process and to manage IP address assignment because Foreman cannot integrate with a DHCPv6 server and manage its configuration. For more information about DHCPv6 server configuration, see Options in unmanaged DHCPv6 in Provisioning hosts.
Configure Foreman for UEFI HTTP boot provisioning. Although Foreman provisioning templates include IPv6 support for PXE and HTTP (iPXE) provisioning, the UEFI HTTP Boot provisioning is the only tested and certified provisioning workflow.

1.6. AWS Requirements

Additional resources

Installing and running Foreman server and Smart Proxy servers on Amazon Web Services (AWS) has additional requirements to your environment.

Amazon Web Service requirements

Use Storage requirements in Installing Foreman Server with Katello 4.21 plugin (containerized) on Enterprise Linux to understand and assign the correct storage to your AWS EBS volumes. See also an AWS storage optimized instance for further guidance.
Create EBS volumes for directories expected to contain larger amounts of data like /var/lib/pulp and ensure they are correctly mounted on start-up and before continuing the installation.
Optional: Store other data on a separate EBS volume.
If you want Foreman server and Smart Proxy server to communicate using external DNS hostnames, open the required ports for communication in the AWS Security Group that is associated with the instance.

AWS permission requirements

Create and access Enterprise Linux images in AWS
Edit network access in AWS Security
Create EC2 instances and EBS volumes
Launch EC2 instances
Import and export of virtual machines in AWS
Usage of AWS Direct Connect

Foreman requirements

Ensure that your Amazon EC2 instance meets or exceeds requirements for Foreman:

For Foreman server, see Preparing environment for Foreman server installation in Installing Foreman Server with Katello 4.21 plugin (containerized) on Enterprise Linux.
For Smart Proxy servers, see Preparing your environment for installation in Installing a Smart Proxy Server 3.19 on Enterprise Linux.

Additional resources

2. Preparing environment for Foreman server installation

Ensure that your network environment is ready for the Foreman server installation.

2.1. Opening required ports

By opening the required ports, you ensure that the components of Foreman architecture can communicate. You must also ensure that the required network ports are open on any network-based firewalls.

Note

Some cloud solutions must be specifically configured to allow communications between machines because they isolate machines similarly to network-based firewalls. If you use an application-based firewall, ensure that the application-based firewall permits all applications that are listed in the tables and known to your firewall. If possible, disable the application checking and allow open port communication based on the protocol.

If you do not use firewall-cmd to configure the Linux firewall, implement using the tool of your choice.

Procedure

Open the ports for clients on Foreman server:

# firewall-cmd \
--add-port="8000/tcp" \
--add-port="9090/tcp"

Allow access to services on Foreman server:

# firewall-cmd \
--add-service=dns \
--add-service=dhcp \
--add-service=tftp \
--add-service=http \
--add-service=https \
--add-service=puppetmaster

Make the changes persistent:
```
# firewall-cmd --runtime-to-permanent
```

Verification

View all firewall zones and allowed services:
```
# firewall-cmd --list-all
```

Additional resources

2.2. Verifying DNS resolution

Verify the full forward and reverse DNS resolution using a fully-qualified domain name to prevent issues while installing Foreman.

Procedure

Ensure that the host name and local host resolve correctly:

# ping -c1 localhost
# ping -c1 `hostname -f` # my_system.domain.com

Successful name resolution results in output similar to the following:

# ping -c1 localhost
PING localhost (127.0.0.1) 56(84) bytes of data.
64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.043 ms

--- localhost ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.043/0.043/0.043/0.000 ms

# ping -c1 `hostname -f`
PING hostname.gateway (XX.XX.XX.XX) 56(84) bytes of data.
64 bytes from hostname.gateway (XX.XX.XX.XX): icmp_seq=1 ttl=64 time=0.019 ms

--- localhost.gateway ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.019/0.019/0.019/0.000 ms

To avoid discrepancies with static and transient host names, set all the host names on the system by entering the following command:

# hostnamectl set-hostname name

Warning

Name resolution is critical to the operation of Foreman. If Foreman cannot properly resolve its fully qualified domain name, tasks such as content management, subscription management, and provisioning will fail.

2.3. Configuring the HTTP proxy to connect to Red Hat CDN

You can configure an HTTP proxy to connect to Red Hat CDN when your network requires proxy access for subscription management and content delivery.

Prerequisites

Your network gateway and the HTTP proxy must allow access to the following hosts:

Host name Port Protocol

subscription.rhsm.redhat.com

443

HTTPS

cdn.redhat.com

443

HTTPS

Host name	Port	Protocol
subscription.rhsm.redhat.com	443	HTTPS
cdn.redhat.com	443	HTTPS

Foreman server uses SSL to communicate with the Red Hat CDN securely. An SSL interception proxy interferes with this communication. These hosts must be allowlisted on your HTTP proxy.

For a list of IP addresses used by the Red Hat CDN (cdn.redhat.com), see the Knowledgebase article Public CIDR Lists for Red Hat on the Red Hat Customer Portal.

To configure the Subscription Manager with the HTTP proxy, follow the procedure below.

Procedure

On Foreman server, complete the following details in the /etc/rhsm/rhsm.conf file:

# an http proxy server to use (enter server FQDN)
proxy_hostname = http-proxy.example.com

# port for http proxy server
proxy_port = 8080

# user name for authenticating to an http proxy, if needed
proxy_user =

# password for basic http proxy auth, if needed
proxy_password =

2.4. Configuring repositories

Configure the required repositories.

Procedure

Clear any metadata:
```
# dnf clean all
```

Install the foreman-release.rpm package:

# dnf install https://yum.theforeman.org/releases/3.19/el9/x86_64/foreman-release.rpm

Install the katello-repos-latest.rpm package:

# dnf install https://yum.theforeman.org/katello/4.21/katello/el9/x86_64/katello-repos-latest.rpm

Verification

Verify that the required repositories are enabled:
```
# dnf repolist enabled
```

3. Installing Foreman server

Use the following procedures to install Foreman server and perform the initial configuration.

Note	You cannot register Foreman server to itself.

3.1. Deploy Foreman server configuration with the default database

You can deploy a Foreman server in a default configuration by using the foremanctl deploy command.

To extend the default deployment, you can select one or more features or add one or more configuration options.

The initial deployment also installs PostgreSQL databases on the same server.

Note

Any additional run of the foremanctl deploy command recreates configuration files used by the Foreman services based on the parameters given in this and previous runs. This way, you can add additional settings to your deployment or change previous configurations.

For more information on how to apply custom configuration on other services, see Performing additional configuration on Foreman server.

Prerequisites

Your system conforms with the requirements. For more information, see Planning Foreman server installation.
Your system is prepared for the installation. For more information, see Preparing environment for Foreman server installation.
Your system has the foremanctl package installed.

Procedure

Update the system to the latest available version:
```
# dnf upgrade
```
Optional: Inspect the features available for deployment:
```
# foremanctl features
```
You can enable one or more features by adding the --add-feature Feature-1 --add-feature Feature-2 option to the foremanctl deploy command.

Deploy the configuration on the server:

# foremanctl deploy \
--initial-admin-username My_Admin_User_Name \
--initial-admin-password My_Admin_Password \
--initial-organization "My_Organization" \
--initial-location "My_Location"

Note

The options prefixed with initial- affect only new databases.

Specify a meaningful value for the initial-organization option. This can be your company name. The foreman-installer tool creates an internal label that matches the value, and you cannot change it later. If you do not specify a value, an organization called Default Organization with the label Default_Organization is created. You can rename the organization name but not the label.

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

3.2. Deploy Foreman server configuration with an external database

By default, the Foreman deployment includes installing a PostgreSQL database on the same host as Foreman server. However, in certain Foreman deployments, using external databases instead of the default local databases can help with the server load or have other benefits.

To extend the default deployment, you can select one or more features or add one or more configuration options.

Note

For more information on how to apply custom configuration on other services, see Performing additional configuration on Foreman server.

Prerequisites

You have considered whether using an external database is beneficial for your use case. For more information, see PostgreSQL as an external database considerations in Administering Foreman.
PostgreSQL is installed on an external database host you prepared. For more information, see Installing PostgreSQL in Administering Foreman.
Your system conforms with the requirements. For more information, see Planning Foreman server installation.
Your system is prepared for the installation. For more information, see Preparing environment for Foreman server installation.
Your system has the foremanctl package installed.

Procedure

Update the system to the latest available version:
```
# dnf upgrade
```
Optional: Inspect the features available for deployment:
```
# foremanctl features
```
You can enable one or more features by adding the --add-feature Feature-1 --add-feature Feature-2 option to the foremanctl deploy command.

Deploy the configuration on the server:

# foremanctl deploy \
--initial-admin-username My_Admin_User_Name \
--initial-admin-password My_Admin_Password \
--initial-organization "My_Organization" \
--initial-location "My_Location" \
--database-mode external \
--database-host My_Database_Host \
--database-port My_Database_Port \
--database-ssl-mode {disable,allow,prefer,require,verify-ca,verify-full} \
--database-ssl-ca My_Database_SSL_CA \
--candlepin-database-name My_Candlepin_Database_Name \
--candlepin-database-password My_Candlepin_Database_Password \
--candlepin-database-user My_Candlepin_Database_User \
--pulp-database-name My_Pulp_Database_Name \
--pulp-database-password My_Pulp_Database_Password \
--pulp-database-user My_Pulp_Database_User \
--pulp-worker-count My_Pulp_Worker_Count \
--foreman-database-name My_Foreman_Database_Name \
--foreman-database-user My_Foreman_Database_User \
--foreman-database-password My_Foreman_Database_Password

Note

The options prefixed with initial- affect only new databases.

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

3.3. Importing Red Hat subscription manifests into Foreman

You can import a Red Hat subscription manifest into Foreman to provide subscription allocation to your organization in Foreman.

Note	Simple Content Access (SCA) is set on the organization, not the manifest. Importing a manifest does not change your organization’s Simple Content Access status.

Simple Content Access simplifies the subscription experience for administrators.

Additional resources

Subscription Management Administration Guide for Red Hat Enterprise Linux on the Red Hat Customer Portal

3.3.1. Obtaining a Red Hat subscription manifest

You can create and export a Red Hat subscription manifest to prepare subscriptions for import into Foreman.

Procedure

Export your Red Hat subscription manifest from the Red Hat Hybrid Cloud Console. For more information, see Creating and managing manifests for a connected Satellite Server in Subscription Central.

3.3.2. Importing a Red Hat subscription manifest by using Foreman web UI

You can import a Red Hat subscription manifest into Foreman server by using Foreman web UI. Import the manifest so that you can enable and synchronize Red Hat repositories in your organization.

Prerequisites

You have a Red Hat subscription manifest file. For more information, see Obtaining a Red Hat subscription manifest.

Procedure

In the Foreman web UI, ensure the context is set to the organization you want to use.
Navigate to Content > Subscriptions.
Click Manage Manifest.
In the Manage Manifest window, click Choose File.
Navigate to the location that contains the Red Hat subscription manifest file, then click Open.

3.3.3. Importing a Red Hat subscription manifest by using Hammer CLI

You can import a Red Hat subscription manifest into Foreman server by using Hammer CLI. Import the manifest so that you can enable and synchronize Red Hat repositories in your organization.

Prerequisites

You have a Red Hat subscription manifest file. For more information, see Obtaining a Red Hat subscription manifest.

Procedure

Copy the Red Hat subscription manifest file from your local machine to Foreman server:
```
$ scp ~/manifest_file.zip root@foreman.example.com:~/.
```
Log in to Foreman server over SSH as the root user.

Import the Red Hat subscription manifest file:

$ hammer subscription upload \
--file ~/manifest_file.zip \
--organization "My_Organization"

4. Performing additional configuration on Foreman server

You can enable additional features on Foreman server, such as Insights integration, pull-based transport for remote execution, or the usage of HTTP proxies. While you can configure these features after the initial setup, you can also configure many of them during the installation by using the corresponding foremanctl options.

4.1. Configuring Foreman server to use an HTTP proxy

Use the following procedures to configure Foreman to use an HTTP proxy.

4.1.1. Adding a default HTTP proxy by using Foreman web UI

If your network uses an HTTP proxy, you can configure Foreman server to use an HTTP proxy for requests to the Red Hat Content Delivery Network (CDN) or another content source. Use the FQDN instead of the IP address where possible to avoid losing connectivity because of network changes.

The following procedure configures an HTTP proxy only for downloading content for Foreman.

Procedure

In the Foreman web UI, navigate to Infrastructure > HTTP Proxies.
Click New HTTP Proxy.
In the Name field, enter the name for the HTTP proxy.
In the Url field, enter the URL of the HTTP proxy in the following format: https://http-proxy.example.com:8080.
Optional: If authentication is required, in the Username field, enter the username to authenticate with.
Optional: If authentication is required, in the Password field, enter the password to authenticate with.
To test connection to the proxy, click Test Connection.
Select the Default content HTTP proxy option to set the new HTTP proxy as default for content synchronization.
Click Submit.

4.1.2. Adding a default HTTP proxy by using Hammer CLI

The following procedure configures an HTTP proxy only for downloading content for Foreman.

Procedure

Verify that the http_proxy, https_proxy, and no_proxy variables are not set:
```
# unset http_proxy https_proxy no_proxy
```

Add an HTTP proxy entry to Foreman and set the HTTP proxy as default for content synchronization:

$ hammer http-proxy create \
--name=My_HTTP_Proxy \
--username=My_HTTP_Proxy_User_Name \
--password=My_HTTP_Proxy_Password \
--url http://http-proxy.example.com:8080 \
--content-default-http-proxy true

4.1.3. Using an HTTP proxy for all Foreman HTTP requests by using Foreman web UI

If your Foreman server must remain behind a firewall that blocks HTTP and HTTPS, you can configure an HTTP proxy for communication with external systems, including compute resources, by using the Foreman web UI.

Note that if you are using compute resources for provisioning, and you want to use a different HTTP proxy with the compute resources, the HTTP proxy that you set for all Foreman communication takes precedence over the HTTP proxies that you set for compute resources.

Procedure

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

4.1.4. Using an HTTP proxy for all Foreman HTTP requests by using Hammer CLI

Procedure

Use an HTTP proxy:

$ hammer settings set --name=http_proxy --value=My_HTTP_Proxy_URL

4.1.5. Excluding hosts from receiving proxied requests by using Foreman web UI

If you use an HTTP proxy for all Foreman HTTP or HTTPS requests, you can prevent certain hosts from communicating through the HTTP proxy.

Procedure

In the Foreman web UI, navigate to Administer > Settings.
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.
Click the tick icon to save your changes.

4.1.6. Excluding hosts from receiving proxied requests by using Hammer CLI

If you use an HTTP proxy for all Foreman HTTP or HTTPS requests, you can prevent certain hosts from communicating through the HTTP proxy.

Procedure

Enter the following command:

$ hammer settings set --name=http_proxy_except_list --value=[hostname1.hostname2...]

4.1.7. Resetting the HTTP proxy by using Foreman web UI

If you want to reset the current HTTP proxy setting, unset the Default HTTP Proxy setting.

Procedure

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

4.1.8. Resetting the HTTP proxy by using Hammer CLI

If you want to reset the current HTTP proxy setting, unset the Default HTTP Proxy setting.

Procedure

Set the content_default_http_proxy setting to an empty string:

$ hammer settings set --name=content_default_http_proxy --value=""

4.2. Configuring an alternate CNAME for Foreman

You can configure an alternate CNAME for Foreman. This might be useful if you want to deploy the Foreman web interface on a different domain name than the one that is used by client systems to connect to Foreman. You must plan the alternate CNAME configuration in advance prior to installing Smart Proxies and registering hosts to Foreman to avoid redeploying new certificates to hosts.

4.2.1. Configuring Foreman with an alternate CNAME

You can configure an alternate CNAME for Foreman with the default Foreman certificate. Note that the procedures for users of a default Foreman certificate and custom certificate differ.

Procedure

Add an alternate CNAME to a new installation or an existing deployment of Foreman with a default Foreman certificate:
```
# foremanctl --certificate-cname My-Alternate-FQDN.example.com
```
If you use Foreman with a custom certificate, when creating a custom certificate, include the alternate CNAME records to the custom certificate. For more information, see Creating a Custom SSL Certificate for Foreman server.

4.2.2. Configuring hosts to use an alternate Foreman CNAME for content management

If Foreman is configured with an alternate CNAME, you can configure hosts to use the alternate Foreman CNAME for content management. To do this, you must point hosts to the alternate Foreman CNAME prior to registering the hosts to Foreman. You can do this using the bootstrap script or manually.

Perform these steps on the hosts you want to configure.

Procedure

If you want to configure the host with the bootstrap script, run the bootstrap script with the --server My-Alternate-FQDN.example.com option to register the host to the alternate Foreman CNAME:
```
# ./bootstrap.py --server My-Alternate-FQDN.example.com
```

If you want to configure the host manually, edit the /etc/rhsm/rhsm.conf file to update hostname and baseurl settings to point to the alternate host name, for example:

[server]
# Server hostname:
hostname = My-Alternate-FQDN.example.com

content omitted

[rhsm]
# Content base URL:
baseurl=https://My-Alternate-FQDN.example.com/pulp/content/

Next steps

Now you can register the host with the subscription-manager.

4.3. Configuring Foreman server with a custom SSL certificate

By default, Foreman uses a self-signed SSL certificate to enable encrypted communications between Foreman server, Smart Proxy servers, and all hosts. If you cannot use a Foreman self-signed certificate, you can configure Foreman server to use an SSL certificate signed by an external certificate authority (CA).

When you configure Foreman with custom SSL certificates, you must fulfill the following requirements:

You must use the privacy-enhanced mail (PEM) encoding for the SSL certificates.
You must not use the same SSL certificate for both Foreman server and Smart Proxy server.
The same CA must sign certificates for Foreman server and Smart Proxy server.
An SSL certificate must not also be a CA certificate.
An SSL certificate must include a subject alt name (SAN) entry that matches the common name (CN).
An SSL certificate must be allowed for Key Encipherment using a Key Usage extension.
An SSL certificate must not have a shortname as the CN.
You must not set a passphrase for the private key.
If you use a certificate signed by an intermediate CA, you must provide the full chain of certificates. Your certificate must start with the Root CA, contain one or more intermediate CAs, and end with your server certificate.

4.3.1. Creating a custom SSL certificate for Foreman server

Use this procedure to create a custom SSL certificate for Foreman server. If you already have a custom SSL certificate for Foreman server, skip this procedure.

Procedure

To store all the source certificate files, create a directory that is accessible only to the root user:
```
# mkdir /root/foreman_cert
```
Create a private key with which to sign the certificate signing request (CSR). The private key must be unencrypted:
```
# openssl genrsa -out /root/foreman_cert/foreman_cert_key.pem 4096
```
If you already have a private key, skip this step.
Optional: Verify that the key is unencrypted:
```
# openssl pkey -noout -in /root/foreman_cert/foreman_cert_key.pem
```
If the command does not ask for a password, the key is unencrypted. If your private key is password-protected, remove the password.

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

[ req ]
req_extensions = v3_req
distinguished_name = req_distinguished_name
prompt = no

[ req_distinguished_name ]
commonName = foreman.example.com

[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[ alt_names ]
DNS.1 = foreman.example.com

For more information about the [ v3_req ] parameters and their purpose, see RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.

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 = foreman.example.com
countryName = My_Country_Name
stateOrProvinceName = My_State_Or_Province_Name
localityName = My_Locality_Name
organizationName = My_Organization_Or_Company_Name
organizationalUnitName = My_Organizational_Unit_Name
```
The options used in the configuration file include the following:

countryName

The country represented by a two-letter code

stateOrProvinceName

Full name of the state or province

localityName

Full name of the locality (example: New York)

organizationalUnitName

Division responsible for the certificate (example: IT department)
Generate CSR:
```
# openssl req -new \
-key /root/foreman_cert/foreman_cert_key.pem \
-config /root/foreman_cert/openssl.cnf \
-out /root/foreman_cert/foreman_cert_csr.pem
```
The options used in the configuration file include the following:

-key

Path to the private key

-config

Path to the configuration file

-out

Path to the CSR to generate
Send the certificate signing request to the certificate authority (CA). The same CA must sign certificates for Foreman server and Smart Proxy 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.

4.3.2. Deploying a custom SSL certificate to Foreman server

Use this procedure to configure your Foreman server to use a custom SSL certificate signed by a Certificate Authority.

Important

Do not store the SSL certificates or .tar bundles in /tmp or /var/tmp directory. The operating system removes files from these directories periodically. As a result, foremanctl fails to execute while enabling features or upgrading Foreman server.

Procedure

Update certificates on your 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"
```
The options used in the command include the following:

--certificate-source=custom_server

Sets the certificate source to custom server certificates provided by the user.

--certificate-server-certificate

Path to Foreman server certificate file that is signed by a Certificate Authority.

--certificate-server-key

Path to the private key for the Foreman server certificate.

--certificate-server-ca-certificate

Path to the Certificate Authority bundle.

Verification

On a computer with network access to Foreman server, navigate to the following URL: https://foreman.example.com.
In your browser, view the certificate details to verify the deployed certificate.

4.4. Resetting SSL certificate to default self-signed certificate on Foreman server

If you want to revert to the default configuration, you can reset a custom SSL certificate to the default self-signed certificate on your Foreman server.

Procedure

Reset the SSL certificate to default self-signed certificate:
```
# foremanctl deploy --certificate-source=default
```

Verification

Verify that the following parameters in /etc/foreman-installer/scenarios.d/foreman-answers.yaml have no values:

server_cert:
server_key:
server_cert_req:
server_ca_cert:

Additional resources

Pre-release version Report issue