Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions _includes/manuals/nightly/3.1.2_hardware_requirements.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@

The hardware requirements for Foreman depend primarily on the number of requests that it will receive, which depends on the number of configuration management clients, web UI activity and other systems using the API.

The default installation when including Puppet server will require:
The default installation when including OpenVox Server will require:

* 4GB memory
* 2GB disk space

For a bare minimum installation with few clients and no Puppet server, the requirements are:
For a bare minimum installation with few clients and no OpenVox Server, the requirements are:

* 2GB memory
* 1GB disk space

#### Scaling notes

* The default Puma configuration is 2 workers with a maximum of 16 threads and a minimum of 0 threads per worker.
* When using a Puppet server, consult the requirements outlined in the [Puppet server system requirements](https://puppet.com/docs/puppet/latest/server/install_from_packages.html#system-requirements).
* When using the OpenVox Server, consult the [requirements](https://docs.openvoxproject.org/openvox/latest/system_requirements.html) & recommendations outlined in the [OpenVox Server tuning guide](https://docs.openvoxproject.org/openvox-server/latest/tuning_guide.html).
* Disk usage will increase as more data is stored in the database, mostly for facts and reports. See the [reports cronjob configuration](manuals/{{page.version}}/index.html#3.5.4PuppetReports) to change how they are expired.
12 changes: 6 additions & 6 deletions _includes/manuals/nightly/3.2.2_installer_options-params.md

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The options in this file are extracted from the installer automatically. We probably haven't done that in a while, but it should be automated. https://github.com/theforeman/theforeman.org/blob/gh-pages/scripts/installer/get-params should be used.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

okay I will pull the openvox repo setup in a new PR and then update the various modules that are the source for _includes/manuals/nightly/3.2.2_installer_options-params.md:
https://github.com/theforeman/theforeman.org/pull/2313/changes

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a start theforeman/puppet-foreman_proxy#905 ¯_(ツ)_/¯

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Original file line number Diff line number Diff line change
Expand Up @@ -801,19 +801,19 @@
</tr>
<tr>
<td style='white-space:nowrap'>--foreman-proxy-puppet-ssl-ca</td>
<td>SSL CA used to verify connections when accessing the Puppet master API</td>
<td>SSL CA used to verify connections when accessing the OpenVox server API</td>
</tr>
<tr>
<td style='white-space:nowrap'>--foreman-proxy-puppet-ssl-cert</td>
<td>SSL certificate used when accessing the Puppet master API</td>
<td>SSL certificate used when accessing the OpenVox server API</td>
</tr>
<tr>
<td style='white-space:nowrap'>--foreman-proxy-puppet-ssl-key</td>
<td>SSL private key used when accessing the Puppet master API</td>
<td>SSL private key used when accessing the OpenVox server API</td>
</tr>
<tr>
<td style='white-space:nowrap'>--foreman-proxy-puppet-url</td>
<td>URL of the Puppet master itself for API requests</td>
<td>URL of the OpenVox server itself for API requests</td>
</tr>
<tr>
<td style='white-space:nowrap'>--foreman-proxy-puppetca</td>
Expand Down Expand Up @@ -1169,7 +1169,7 @@
</tr>
<tr>
<td style='white-space:nowrap'>--puppet-report</td>
<td>Send reports to the Puppet Master</td>
<td>Send reports to the OpenVox Server</td>
</tr>
<tr>
<td style='white-space:nowrap'>--puppet-run-hour</td>
Expand Down Expand Up @@ -1285,7 +1285,7 @@
</tr>
<tr>
<td style='white-space:nowrap'>--puppet-server-crl-enable</td>
<td>Turn on crl checking. Defaults to true when server_ca is true. Otherwise Defaults to false. Note unless you are using an external CA. It is recommended to set this to true. See $server_ca_crl_sync to enable syncing from CA Puppet Master</td>
<td>Turn on crl checking. Defaults to true when server_ca is true. Otherwise Defaults to false. Note unless you are using an external CA. It is recommended to set this to true. See $server_ca_crl_sync to enable syncing from CA OpenVox Server</td>
</tr>
<tr>
<td style='white-space:nowrap'>--puppet-server-custom-trusted-oid-mapping</td>
Expand Down
2 changes: 1 addition & 1 deletion _includes/manuals/nightly/3.2.2_installer_options.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ kafo-export-params -c /etc/foreman-installer/scenarios.d/foreman.yaml -f html
#### Answers file

The answers file describes the classes that will be applied to the host to
install Foreman, along with their parameters. The foreman-installer package stores it at `/etc/foreman-installer/scenarios.d/foreman-answers.yaml`. By default, the *all-in-one* setup will include Foreman, a puppetmaster, Puppet agent, and the Smart Proxy:
install Foreman, along with their parameters. The foreman-installer package stores it at `/etc/foreman-installer/scenarios.d/foreman-answers.yaml`. By default, the *all-in-one* setup will include Foreman, an OpenVox server, OpenVox agent, and the Smart Proxy:

{% highlight yaml %}
---
Expand Down
4 changes: 2 additions & 2 deletions _includes/manuals/nightly/3.3.1_rpm_packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ Foreman is packaged for the following RPM based distributions:

For most users, it's highly recommended to use the [installer](manuals/{{page.version}}/index.html#3.2ForemanInstaller) as the packages only provide the software and a standalone Foreman service. The installer installs these packages, then additionally configures Foreman to run under Apache with PostgreSQL, plus can configure a complete Puppet setup integrated with Foreman.

### Pre-requisites: Puppet
### Pre-requisites: OpenVox

It's recommended to [configure the Puppet repositories](https://puppet.com/docs/puppet/latest/install_agents.html#task-9788) to obtain the latest version of Puppet available. The version in EPEL is not supported.
It's recommended to [configure the OpenVox repositories](https://docs.openvoxproject.org/openvox/latest/install_linux.html) to obtain the latest version of OpenVox available.

### Available repositories

Expand Down
2 changes: 1 addition & 1 deletion _includes/manuals/nightly/3.5.2_configuration_options.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ Default: root@&lt;your domain&gt;.

##### always_show_configuration_status

When reporting the configuration status of hosts, usually only hosts with outdated reports, or a Puppet proxy/master set and no reports will be considered out of sync. When true, all hosts will be considered out of sync until a report is received. This setting should be enabled in environments where Foreman is used for reporting without smart proxies.
When reporting the configuration status of hosts, usually only hosts with outdated reports, or a OpenVox Server set and no reports will be considered out of sync. When true, all hosts will be considered out of sync until a report is received. This setting should be enabled in environments where Foreman is used for reporting without smart proxies.
Default: false

##### authorize_login_delegation
Expand Down
16 changes: 9 additions & 7 deletions _includes/manuals/nightly/3.5.5_facts_and_the_enc.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@

Foreman can act as a classifier to Puppet through the External Nodes interface. This is a mechanism provided by Puppet to ask for configuration data from an external service, via a script on the Puppet server.
Foreman can act as a classifier to OpenVox through the External Nodes interface. This is a mechanism provided by Puppet to ask for configuration data from an external service, via a script on the Puppet server.

The external nodes script we supply also deals with uploading facts from hosts to Foreman, so we will discuss the two things together.

#### Configuration

##### Puppet server
##### OpenVox server

Download [the ENC script](https://raw.githubusercontent.com/theforeman/puppet-puppetserver_foreman/master/files/enc.rb) to `/etc/puppetlabs/puppet/node.rb` (Puppet AIO) or `/etc/puppet/node.rb` (non-AIO). The name is arbitrary, but must match configuration below, and ensure it's executable by "puppet" with `chmod +x /etc/puppet/node.rb`.

Expand All @@ -29,14 +29,16 @@ Unless it already exists from setting up reporting, create a new configuration f

Edit the URL field to point to your Foreman instance, and the SSL fields for the hostname of the Puppet server (which may be the same host). Paths to Puppet's SSL certificates will be under /var/lib/puppet/ssl/ and puppetdir will be under /var/lib/puppet when using Puppet with non-AIO. More information on SSL certificates is at [Securing communications with SSL](/manuals/{{page.version}}/index.html#5.4SecuringCommunicationswithSSL).

Add the following lines to the [master] section of puppet.conf:
Add the following lines to the [server] section of puppet.conf:

```ini
[master]
[server]
external_nodes = /etc/puppetlabs/puppet/node.rb
node_terminus = exec
```

(in the past, the `[master]` section was recommened. That section is deprecated)

Restart the Puppet server. When the next agent checks in, the script will upload
fact data for this host to Foreman, and download the ENC data.

Expand All @@ -54,7 +56,7 @@ No agent configuration is necessary to use this functionality.
Make sure that the puppet user can execute the ENC script and it works:

```
sudo -u puppet /etc/puppet/node.rb [the name of a node, eg agent.local]
sudo -u puppet /etc/puppetlabs/puppet/node.rb [the name of a node, eg agent.local]
```

should output something like:
Expand All @@ -71,11 +73,11 @@ environment: *id001
This output should match the information displayed when you click on the YAML button
on the Host page in Foreman.

For further information see the [Puppet Labs docs on external nodes](https://puppet.com/docs/puppet/latest/nodes_external.html)
For further information see the [OpenVox docs on external nodes](https://docs.openvoxproject.org/openvox/latest/nodes_external.html).

##### Debugging the ENC

1. If Puppet agents receive empty catalogs, check the puppet.conf master configuration has the ENC script configured. Also check the output of the ENC for the hostname logged by Puppet (which may be different) to see if Foreman is reporting the correct configuration.
1. If Puppet agents receive empty catalogs, check the puppet.conf OpenVox server configuration has the ENC script configured. Also check the output of the ENC for the hostname logged by Puppet (which may be different) to see if Foreman is reporting the correct configuration.
1. If the hostname.yaml facts file is missing, this is typically a Puppet misconfiguration.
1. Failures to upload facts or download the ENC data may be a network issue (check the URL and SSL settings) or an error on the Foreman server. Check /var/log/foreman/production.log for two requests, `POST "/api/hosts/facts"` and `GET "/node/client.example.com?format=yml"` and for any errors within the block of log messages.

Expand Down
2 changes: 1 addition & 1 deletion _includes/manuals/nightly/4.3.6_smartproxy_puppet.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ To get a list of environments, classes and their parameters, the proxy queries t
#:api_timeout: 30
```

The Puppetserver has to permit these API queries. The [HOCON-formatted auth.conf style](https://docs.puppet.com/puppetserver/latest/config_file_auth.html) is at /etc/puppetlabs/puppetserver/conf.d/auth.conf and requires these rules:
The OpenVox server has to permit these API queries. The [HOCON-formatted auth.conf style](https://docs.openvoxproject.org/openvox-server/latest/config_file_auth.html) is at /etc/puppetlabs/puppetserver/conf.d/auth.conf and requires these rules:

```hocon
{
Expand Down
26 changes: 13 additions & 13 deletions _includes/manuals/nightly/5.4.1_comms_puppetserver.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@

In a typical ENC-based setup with reporting, Puppet servers require access to Foreman for three tasks:
In a typical ENC-based setup with reporting, OpenVox servers require access to Foreman for three tasks:

1. Retrieval of external nodes information (classes, parameters)
2. Uploading of host facts
3. Uploading of host reports

All traffic here is initiated by the Puppet server itself. Other traffic from Foreman to the Puppet server for certificate signing etc. is handled via smart proxies (SSL configuration covered in the next section).
All traffic here is initiated by the OpenVox server itself. Other traffic from Foreman to the OpenVox server for certificate signing etc. is handled via smart proxies (SSL configuration covered in the next section).

#### Configuration options

The Foreman interface authorizes access to Puppet server interfaces based on its list of registered smart proxies with the *Puppet* feature, and identifies hosts using client SSL certificates.
The Foreman interface authorizes access to OpenVox server interfaces based on its list of registered smart proxies with the *Puppet* feature, and identifies hosts using client SSL certificates.

Five main settings control the authentication, the first are in Foreman under *Settings*, *Authentication*:

* *require_ssl_smart_proxies* (default: true), requires a client SSL certificate on the Puppet server requests, and will verify the CN of the certificate against the smart proxies. If false, it uses the reverse DNS of the IP address making the request.
* *require_ssl_smart_proxies* (default: true), requires a client SSL certificate on the OpenVox server requests, and will verify the CN of the certificate against the smart proxies. If false, it uses the reverse DNS of the IP address making the request.
* *restrict_registered_smart_proxies* (default: true), only permits access to hosts that have a registered smart proxy with the *Puppet* feature.
* *trusted_hosts*, a whitelist of hosts that overrides the check for a registered smart proxy

Expand All @@ -24,17 +24,17 @@ And two in `config/settings.yaml`:

#### Enabling full SSL communications

Using Apache HTTP with mod_ssl is recommended. For simple setups, the Puppet certificate authority (CA) can be used, with Foreman and other hosts using certificates generated by `puppet cert`.
Using Apache HTTP with mod_ssl is recommended. For simple setups, the OpenVox certificate authority (CA) can be used, with Foreman and other hosts using certificates generated by `puppet cert`.

1. Set Foreman's *require_ssl_smart_proxies*, *restrict_registered_smart_proxies* and *require_ssl* to _true_.
2. The mod_ssl configuration must contain:
<ol><li>*SSLCACertificateFile* set to the Puppet CA</li>
<ol><li>*SSLCACertificateFile* set to the OpenVox CA</li>
<li>*SSLVerifyClient optional*</li>
<li>*SSLOptions +StdEnvVars +ExportCertData*</li></ol>
3. Puppet ENC/report processor configuration (e.g. `/etc/puppetlabs/puppet/foreman.yaml` or `/etc/puppet/foreman.yaml`) should have these settings:
<ol><li>*:ssl_ca* set to the Puppet CA</li>
<li>*:ssl_cert* set to the Puppet server's certificate</li>
<li>*:ssl_key* set to the Puppet server's private key</li></ol>
3. OpenVox ENC/report processor configuration (e.g. `/etc/puppetlabs/puppet/foreman.yaml` or `/etc/puppet/foreman.yaml`) should have these settings:
<ol><li>*:ssl_ca* set to the OpenVox CA</li>
<li>*:ssl_cert* set to the OpenVox server's certificate</li>
<li>*:ssl_key* set to the OpenVox server's private key</li></ol>

##### Troubleshooting

Expand All @@ -47,10 +47,10 @@ Warning messages will be printed to Foreman's log file (typically `/var/log/fore

##### Advanced SSL notes

A typical small setup will use a single Puppet CA and certificates it provides for the Foreman host and Puppet server hosts. In larger setups with multiple CAs or an internal CA, this will require more careful configuration to ensure all hosts can trust each other.
A typical small setup will use a single OpenVox CA and certificates it provides for the Foreman host and OpenVox server hosts. In larger setups with multiple CAs or an internal CA, this will require more careful configuration to ensure all hosts can trust each other.

* Ensure the Common Name (CN) is present in certificates used by Foreman (as clients will validate it) and Puppet server clients (used to verify against smart proxies).
* Foreman's SSL terminator must be able to validate Puppet server client SSL certificates. In Apache with mod_ssl, the *SSLCACertificateFile* option must point to the CA used to validate clients and *SSLVerifyClient* set to _optional_.
* Ensure the Common Name (CN) is present in certificates used by Foreman (as clients will validate it) and OpenVox server clients (used to verify against smart proxies).
* Foreman's SSL terminator must be able to validate OpenVox server client SSL certificates. In Apache with mod_ssl, the *SSLCACertificateFile* option must point to the CA used to validate clients and *SSLVerifyClient* set to _optional_.
* Environment variables from the SSL terminator are used to get the client certificate and verification status. mod_ssl's *SSLOptions +StdEnvVars +ExportCertData* setting enables this. Variable names are defined by *ssl_client_cert_env*, *ssl_client_dn_env* and *ssl_client_verify_env* settings in Foreman.

#### Reduced security: HTTP host-based authentication
Expand Down
2 changes: 1 addition & 1 deletion _includes/manuals/nightly/5.4_communications.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@

The Foreman web application needs to communicate securely with associated smart proxies and Puppet servers, plus users and applications connecting to the web interface. This section details recommended SSL configurations.
The Foreman web application needs to communicate securely with associated smart proxies and OpenVox servers, plus users and applications connecting to the web interface. This section details recommended SSL configurations.
4 changes: 2 additions & 2 deletions _includes/manuals/nightly/5.5.1_backup.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@ For all other distribution do similar command:

tar -czvf etc_foreman_dir.tar.gz /etc/foreman

#### Puppet server
#### OpenVox server

On the Puppet server node, issue the following command to backup Puppet
On the OpenVox server node, issue the following command to backup Puppet
certificates on Red Hat compatible systems

tar --selinux -czvf var_lib_puppet_dir.tar.gz /etc/puppetlabs/puppet/ssl
Expand Down
8 changes: 4 additions & 4 deletions _includes/manuals/nightly/5.5.2_recovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@ It is recommended to extract files to an empty directory first and inspect the
content before overwriting current files (change -C option to an empty
directory).

#### Puppet server
#### OpenVox server

On the Puppet server node, issue the following command to restore Puppet
On the OpenVox server node, issue the following command to restore OpenVox
certificates on Red Hat compatible systems

tar --selinux -xzvf var_lib_puppet_dir.tar.gz -C /
Expand Down Expand Up @@ -62,7 +62,7 @@ However if the FQDN does change, check and update the following items:
* *Provisioning > unattended_url* - URL of the Foreman web API for unattended provisioning
* *Provisioning > ssl_certificate*, *ssl_priv_key* - paths to SSL certificate and key used for smart proxy communications
* The registered smart proxy URL if installed, edit via *Infrastructure > Smart Proxies*
* Puppet SSL certs: generate new ones with `puppet cert generate NEW_FQDN`
* OpenVox SSL certs: generate new ones with `puppet cert generate NEW_FQDN`
* Apache configs: update `conf.d/*-{foreman,puppet}.conf` with new SSL cert/key filenames, ServerName and VirtualHost IP addresses if applicable
* Smart proxy configuration files in `/etc/foreman-proxy`:
* `settings.yml` - update SSL cert/key filenames
Expand All @@ -71,4 +71,4 @@ However if the FQDN does change, check and update the following items:
* `settings.d/puppet_proxy_puppet_api.yml` - update SSL cert/key filenames
* `settings.d/realm.yml` - update `realm_principal` if the principal name has changed
* `settings.d/templates.yml` - update `template_url` for URL of the Foreman web API
* Puppet servers: URLs and cert/key filenames in `/etc/puppetlabs/puppet/foreman.yaml` or `/etc/puppet/foreman.yaml`
* OpenVox servers: URLs and cert/key filenames in `/etc/puppetlabs/puppet/foreman.yaml` or `/etc/puppet/foreman.yaml`