3.2.3_installation_scenarios.md

The Foreman installer can accommodate more complex, multi-host setups when supplied with appropriate parameters.

Using an external database server

Per default foreman-installer will install a PostgreSQL database server onto the Foreman host and create its database. An external database server with an already created database can be used with the following arguments:

{% highlight bash %} foreman-installer
--foreman-db-manage=false
--foreman-db-host=dbserver.example.com
--foreman-db-database=dbname
--foreman-db-username=dbuser
--foreman-db-password=dbpassword {% endhighlight %}

As a post-installation step, to populate the database correctly, run:

{% highlight bash %} foreman-rake db:migrate foreman-rake db:seed foreman-rake apipie:cache:index {% endhighlight %}

Setting up Foreman with additional Smart Proxies

Using the scenarios outlined below, a simple scale-out setup can be created as follows:

1. On the Foreman host, run a complete foreman-installer all-in-one installation to provide Foreman, a Puppetserver and Smart Proxy. This will be the Puppet CA.

For each additional Smart Proxy:

1. Bootstrap certificates
2. Run the standalone installation as detailed below

Note This relies on the puppet ssl subcommand introduced in Puppet 6. Prior to Puppet 6 there was no separate command and it required manual work.

Assuming the Puppetserver with CA is on foreman.example.com, the following command can be run:

puppet ssl bootstrap --server foreman.example.com

This will submit a CSR (Certificate Signing Request) to the Puppet CA running on foreman.example.com. There the request can be signed.

puppetserver ca sign --certname host.example.com

CSRs also show up in the Foreman interface and can be signed there as well.

Standalone Puppetserver

A standalone Puppetserver can be configured along with a smart proxy installation, enabling the Puppet infrastructure to be scaled out. This assumes the SSL certificates have been bootstrapped.

Command line arguments:

{% highlight bash %} foreman-installer
--no-enable-foreman
--no-enable-foreman-cli
--enable-puppet
--puppet-server-ca=false
--puppet-server-foreman-url=https://foreman.example.com
--enable-foreman-proxy
--foreman-proxy-puppetca=false
--foreman-proxy-foreman-base-url=https://foreman.example.com
--foreman-proxy-trusted-hosts=foreman.example.com
--foreman-proxy-oauth-consumer-key=
--foreman-proxy-oauth-consumer-secret= {% endhighlight %}

Fill in the OAuth consumer key and secret values from your Foreman instance, retrieve them from your Foreman server, using: sudo foreman-rake config | grep oauth_consumer, and set the Foreman URLs appropriately. These allow the smart proxy to register automatically with the Foreman instance, or disable with --foreman-proxy-register-in-foreman=false.

PuppetDB integration

An existing PuppetDB server can be integrated into a Puppetserver by adding:

{% highlight bash %} foreman-installer
[...] --puppet-server-puppetdb-host=puppetdb.example.com
--puppet-server-reports=foreman,puppetdb
--puppet-server-storeconfigs-backend=puppetdb {% endhighlight %}

Be aware that foreman-installer does not setup the PuppetDB server itself. Only setups using Puppet's Puppet AIO packages are supported for PuppetDB integration using these parameters.

Foreman server without the Puppetserver

The default "all-in-one" Foreman installation includes a Puppetserver, but this can be disabled. Foreman by default uses Puppet's SSL certificates however, so the certificates must be bootstrapped.

Command line arguments:

{% highlight bash %} foreman-installer
--puppet-server=false
--foreman-proxy-puppet=false
--foreman-proxy-puppetca=false {% endhighlight %}

This will still configure the Puppet agent, but this too can be disabled with --no-enable-puppet to disable the whole Puppet module.

Smart proxy for DNS, DHCP etc.

The smart proxy allows management of various network services, such as DNS, DHCP and TFTP. The installer can set up a basic smart proxy service ready to be configured, or it can install and configure BIND or ISC DHCP ready to go. A certificate should be generated and copied to the host first so Foreman can contact the proxy server.

Command line arguments for a basic smart proxy installation:

{% highlight bash %} foreman-installer
--no-enable-foreman
--no-enable-foreman-cli
--no-enable-puppet
--enable-foreman-proxy
--foreman-proxy-foreman-base-url=https://foreman.example.com
--foreman-proxy-trusted-hosts=foreman.example.com
--foreman-proxy-oauth-consumer-key=
--foreman-proxy-oauth-consumer-secret= {% endhighlight %}

Fill in the OAuth consumer key and secret values from your Foreman instance, retrieve them from your Foreman server, using: sudo foreman-rake config | grep oauth_consumer, and set the Foreman URLs appropriately. These allow the smart proxy to register automatically with the Foreman instance, or disable with --foreman-proxy-register-in-foreman=false.

Command line arguments for a smart proxy configured with just TFTP, BIND, setting DNS forwarders and overriding the default forward and reverse DNS zones:

{% highlight bash %} foreman-installer
--no-enable-foreman
--no-enable-foreman-cli
--no-enable-puppet
--enable-foreman-proxy
--foreman-proxy-tftp=true
--foreman-proxy-puppet=false
--foreman-proxy-puppetca=false
--foreman-proxy-dns=true
--foreman-proxy-dns-interface=eth0
--foreman-proxy-dns-zone=example.com
--foreman-proxy-dns-reverse=0.0.10.in-addr.arpa
--foreman-proxy-dns-forwarders=8.8.8.8
--foreman-proxy-dns-forwarders=8.8.4.4
--foreman-proxy-foreman-base-url=https://foreman.example.com
--foreman-proxy-trusted-hosts=foreman.example.com
--foreman-proxy-oauth-consumer-key=
--foreman-proxy-oauth-consumer-secret= {% endhighlight %}

Ensure the dns-interface argument is updated with the correct network interface name for the DNS server to listen on. After configuration, make sure to create Subnet in Foreman under Infrastructure > Subnets for the particular Smart Proxy which registers automatically.

Command line arguments for a smart proxy configured with just ISC DHCP and a single DHCP subnet:

{% highlight bash %} foreman-installer
--no-enable-foreman
--no-enable-foreman-cli
--no-enable-puppet
--enable-foreman-proxy
--foreman-proxy-puppet=false
--foreman-proxy-puppetca=false
--foreman-proxy-dhcp=true
--foreman-proxy-dhcp-interface=eth0
--foreman-proxy-dhcp-gateway=10.0.0.1
--foreman-proxy-dhcp-range="10.0.0.100 10.0.0.200"
--foreman-proxy-dhcp-nameservers="10.0.1.2,10.0.1.3"
--foreman-proxy-foreman-base-url=https://foreman.example.com
--foreman-proxy-trusted-hosts=foreman.example.com
--foreman-proxy-oauth-consumer-key=
--foreman-proxy-oauth-consumer-secret= {% endhighlight %}

Also ensure here that the dhcp-interface argument is updated for the interface to run DHCP on. After configuration, make sure to create a new Subnet (or import from existing) in the Foreman interface.

While it is possible to define the same DHCP range in Foreman, it's usually good practice to select a range from outside the pool defined in the installer, but still in the subnet. For the example above, it is recommended to define the DHCP range from 10.0.0.1 to 10.0.0.99 in the Foreman UI which gives the following IP address distribution:

• 10.0.0.1 - 10.0.0.99 - addresses reserved during bare-metal provisioning by Foreman
• 10.0.0.100 - 10.0.200 - addresses for dynamic clients in the subnet (discovered hosts, unmanaged hosts)