The require_ssl_smart_proxies setting has been dropped and Foreman now behaves as if the value was true (the default). This means it’s no longer possible to use reverse DNS instead of client certificates over HTTPS connections. Upgrading users should ensure a valid Public Key Infrastructure (PKI) exists.

For more information see the RFC and PR.

Foreman 2.1 introduced EL8 support and Katello 4.0 (on Foreman 2.4) followed. While it’s currently undecided when EL7 support will be dropped exactly, this is an early notice given the considerable number of EL7 deployments. For fresh installations, EL8 should considered the preferred target. Existing installations should start thinking about a migration plan.

Note that this is only support to run Foreman and Foreman Proxy themselves on EL7. Managing EL7 systems remains supported. See the RFC for more information.

The Foreman installer has code for both AIO and non-AIO configurations, switching behavior automatically based on the version of Puppet installed (usually during the first run when answers are stored). Only AIO installations are tested.

Puppetserver is the application for serving Puppet agents used by default since Puppet 4. Both Fedora and Debian have not packaged Puppetserver for their non-AIO packages. The Puppetlabs packages must be used.

Foreman is known to be compatible with all Facter 1.x to 3.x releases.

The Foreman installer and packages are generally incompatible with Puppet Enterprise, however with some manual reconfiguration, individual Foreman components such as the smart proxy should work if needed (some further unsupported documentation can be found on the wiki). The installer in particular will conflict with a Puppet Enterprise installation. It is recommended that Foreman is installed using Puppet ``open source''.

Follow the instructions in section 2.1 Quickstart installation

The installation run is non-interactive, but the configuration can be customized by supplying any of the options listed in foreman-installer --help, or by running foreman-installer -i for interactive mode. More examples are given in the Installation Options section. Adding -v will disable the progress bar and display all changes, while --noop will run without making any changes. To run the installer, execute:

After it completes, the installer will print some details about where to find Foreman and the Smart Proxy. Output should be similar to this:

Every parameter available in the installer can be set using command line arguments to foreman-installer. Run foreman-installer --help for most options, or foreman-installer --full-help for a list of every available option.

When running the installer, all arguments passed on the command line will be persisted by default to /etc/foreman-installer/scenarios.d/foreman-answers.yaml and used automatically on subsequent runs, without needing to specify those arguments again. This persistence can be disabled with the -b option.

The installer also provides a text driven interface to customize configuration parameters, and can be run by executing:

The installer contains a number of high level modules (e.g. foreman'', puppet'') and additionally a number of smaller modules for additional functionality, such as plugins and compute resource support. These can be added with the –enable'' switches, or the default options can be disabled with –no-enable'' switches.

More information about compute resources can be found in the Compute Resources section and plugins in the Plugins section.

Note: When you can specify a hash, you need to specify each option individually to foreman-installer.

For example the hash {show_diff ⇒ true, stringify_facts ⇒ false} for --puppet-server-additional-settings becomes --puppet-server-additional-settings=show_diff:true --puppet-server-additional-settings=stringify_facts:false.

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:

Other examples are given in the next section, or /usr/share/foreman-installer/README.md.

Additional configuration options can be given in /etc/foreman-installer/custom-hiera.yaml for some of the Puppet modules that are used internally by Foreman installer. The contents of this file will be passed to Hiera during the Foreman installer execution so can set class parameters for other modules such as apache, mysql, and postgresql.

For example, the TraceEnable option may be controlled by disabling the apache::trace_enable parameter in this file:

Please note that the parameters used by these modules may change between versions of Foreman, so it’s important to check the versions in use and the appropriate module documentation or source code when editing this configuration file. Modifications cannot be supported or migrated by Foreman.

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:

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

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

For each additional Smart Proxy:

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:

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

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

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:

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.

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

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.

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:

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

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:

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:

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:

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:

All RHEL and derivatives must be subscribed to EPEL to provide additional dependencies. Install epel-release from here to automatically configure it.

All RHEL and derivatives require software collections from the CentOS SCLorg Special Interest Group (SIG). Foreman uses the rh-ruby27, rh-postgresql12, and rh-redis5 collections - which are from RHSCL.

The rh-ruby27, rh-postgresql12, and rh-redis5 SCL can be installed from the sources below. These sources are noted only for completeness:

RHEL 7 hosts must also be subscribed to the RHEL 7 Optional repository or child channel in RHN.

To enable the optional repository on a RHEL 7 system using subscription-manager, run:

If you encounter any errors during the installation, please file a bug report!

Add one of the following lines to your /etc/apt/sources.list (alternatively in a separate file in /etc/apt/sources.list.d/foreman.list):

You may also want some plugins from the plugin repo (required for the Foreman Installer):

The public key for secure APT can be downloaded here

You can add this key with:

The key fingerprint is

Remember to update your package lists!

The packages are split by gem dependencies - there are 15 packages to choose from. These are:

Main package:

Database gems:

Optional functionality:

Command line interface:

Installation instructions are:

The packages should auto-run db:migrate and db:seed if /etc/foreman/database.yml exists. So the initial DB setup is only needed during first install, upgrades should just work.

See upgrade instructions

Foreman configuration is managed from two places; a configuration file config/settings.yaml and from the SETTINGS/Foreman Settings page. A full description of the configuration options is given at foreman_configuration

Foreman requires a database of its own to operate - database sharing is unsupported. PostgreSQL is the only database that is considered supported for production use. The installer can set this up for you.

In all cases, please use the production settings.

to initialize the database schema and content, run:

For more information please see the database configuration page here

At this point, you might want to go through the to see how can you import your data into Foreman.

if you installed via rpm, just start the foreman service, or start the builtin web server by typing:

and point your browser to http://foreman:3000

Read Puppet_Reports to learn how to get your nodes to report to Foreman.

This settings file can be found at /etc/foreman/logging.yaml, or config/logging.yaml on a source installation. It controls the default logging locations, formatting and log levels per Rails environment.

In a normal installation, only the `production'' environment is relevant - development and test are only used in source installations. The file has comments for the most common configuration options, which can be changed here or overridden from the `logging directive in the main settings.yaml config file (see above).

You will probably want to delete your reports after some time to limit database growth. To do so, you can set a cronjob:

Available conditions:

To expires all reports regardless of their status:

To expire all non-interesting reports after one day:

Foreman passes all associated parameters, classes,and class parameters, to the Host, including those inherited from host groups, domains, or global settings. See section Managing Puppet for more information on assigning configuration to hosts.

By default, Foreman adds hosts to its database that it learns about through facts, provided the ``create_new_host_when_facts_are_uploaded'' setting is enabled.

Locations and organizations can be inferred from the foreman_location'' or foreman_organization'' facts as supplied by the host. The names of these facts can be changed with the location_fact'' and organization_fact'' settings respectively. Foreman will update hosts on each fact upload based on the value of these facts.

If these facts aren’t supplied, then the default_location'' and default_organization'' settings can be used to set values globally when a host doesn’t have a location or an organization set.

More information in the Configuration section.

There are several options for pushing fact data to Foreman if you are using Foreman for reporting/inventory only.

Configuration is loaded from a set of directories in this order:

In each of these directories hammer tries to load cli_config.yml and anything in the cli.modules.d subdirectory which is the recommended location for configuration of hammer modules.

Later directories and files have precedence if they redefine the same option. Files from cli.modules.d are loaded in alphabetical order.

Hammer uses yaml formatting for its configuration. The config file template is contained in the hammer_cli gem.

and can be copied to one of the locations above and changed as needed. The packaged version of hammer copies the template to /etc for you.

Plugins are disabled by default. You have to edit the config file and enable them manually under modules option, as can be seen in the sample config below.

Plugin specific configuration should be nested under plugin’s name.

Make sure by executing database is migrated. It should produce no errors or output:

You should clear the cache and the existing sessions:

After database migrations, some space can sometimes be reclaimed. It’s a good idea to perform a full database vacuum for PostgreSQL rather than relying on the autovacuum feature to claim maximum space possible.

If you used foreman-installer to set up your existing Foreman instance we recommend running it again after upgrading. Note that the installer can modify config files so this may overwrite your custom changes. You can run the installer in noop mode so you can see what would be changed.

To see what would happen

You may see ERRORS such as /Stage[main]/Foreman_proxy::Register/Foreman_smartproxy[foreman-hostname.domain]: Could not evaluate: Connection refused - connect(2) due to httpd / apache2 service being stopped. These can be safely ignored.

To apply these changes, run the installer again without options

No operating system selected.

In order to catch all configuration changes and manage them properly you should install and run rpmconf from the EPEL repository along with vim-enhanced (for vimdiff).

This step is irrelevant for the chosen operating system.

Start the application server. This is redundant if you previously ran foreman-installer in step 3B.

No operating system selected.

Go to Administer > LDAP Authentication, click on New LDAP Source and enter the following details about the LDAP server:

Under the account tab, the details of an account used to read LDAP entries is required if anonymous binds and reads are disabled. This should be a dedicated service account with bind, read and search permissions on the user and group entries in the directory server.

This may use the variable $login which will be replaced by the login of the authenticating user, however this is deprecated and will result in reduced functionality (as it only works at authentication time).

When configuring an LDAPS connection, the certificate authority needs to be trusted. When using Active Directory Certificate Services, ensure to export the Enterprise PKI CA Certificate using the Base-64 encoded X.509 format.

If your LDAP server uses a certificate chain with intermediate CAs, all of the root and intermediate certificates in the chain must be trusted.

On Red Hat based OSes:

On Debian or Ubuntu, also ensure the file has a .crt extension:

By checking Automatically create accounts in Foreman, any LDAP user will have their Foreman account automatically created the first time they log into Foreman.

You can assign multiple organizations/locations to your LDAP authentication sources. This will assign users that are automatically created to the set of organizations/locations associated with the LDAP authentication source. Please notice this assignment happens only when users are created automatically via LDAP, and not upon every login.

Changing the organization/location of a LDAP authentication source will not automatically change these attributes on the users in that authentication source.

To use this feature, the relevant LDAP attributes must be specified on the next tab (e.g. firstname, lastname, email), as these will be used to populate the Foreman account.

Foreman needs to know how to map internal user account attributes to their LDAP counterparts, such as login, name, and e-mail. Examples for common directory servers are provided below.

Note that LDAP attribute names are case sensitive.

Foreman also has the ability to use a user’s photo stored in LDAP as their Foreman avatar, by setting the jpegPhoto attribute mapping.

Additional Information:

All of the examples below use a dedicated service account called `foreman'. This should be set up with bind, read and search permissions on the user and group entries and with a strong, random password.

A Foreman user group can be associated to a group stored in an LDAP server, so membership of the LDAP group automatically adds a user to the Foreman user group. User groups can be associated with roles, enabling users to log into Foreman and be automatically granted permissions via their membership of an LDAP group. Read more about permissions in the Roles and Permissions section.

To configure the association, create or edit a user group via Administer > User groups. The group name may be any value (no direct relation to the LDAP group). Under the Roles tab, select roles granting permissions to Foreman, or tick the Admin checkbox to enable administrator level access.

On the External groups tab, click the Add external user group button to open a new form. In the Name field, enter the exact name of the LDAP group (usually the common name/CN) and select the server from the dropdown list of LDAP authentication sources. Click the Submit button to save changes.

When a user logs in for the first time (assuming on the fly account creation), the ldap:refresh_usergroups cronjob runs (every 30 minutes by default) or the Refresh button is pressed next to the external user group entry, Foreman will synchronize the group membership from LDAP.

When using Active Directory, please be aware that users will be able to log in for up to an hour after a password change using the old password. This is a function of the AD domain controller and not Foreman.

To change this password expiry period, see Microsoft KB906305 for the necessary registry change.

Foreman allows only 30 failed attempts in the last 5 minutes per one IP address by default. Any subsequent login attempts are not allowed and error message is shown: ``Too many tries, please try again in a few minutes.'' If this is triggered by accident, the silent period can be removed by deleting failed login cache entries:

This will only work when using the file store Rails cache implementation.

If you want to use on the fly user creation, make sure that Foreman can fetch from your LDAP all the required information to create a valid user. For example, on-the-fly user creation won’t work if you don’t have valid email addresses in your directory (you will get an `Invalid username/password' error message when trying to log in).

These may be created, deleted and edited on the Roles page. Each role will contain permission filters, which define the actions allowed in a certain resource. Once your role is created, you can associate it with one or more users and user groups.

There is one built-in system role, `Default role'. This is a set of permissions that every user will be granted, in addition to any other roles that they have. Foreman provides you with a set of seeded roles. These roles can be assigned to users but cannot be modified in any way. They serve as a sane set of defaults and a quick starting point. If you wish to base your custom role on one of these, you can clone it and modify the clone.

Roles can be also associated to Locations or Organizations if these are allowed. Unlike other objects this does not mean that Roles would be only available in a particular scope. Roles are always global for the entirety of Foreman. The association means that filters of such role are scoped to a particular Organization or Location. Imagine you want to create a role representing Administrator of Organization A. You can clone an existing Organization admin role and associate it with Organization A. If you later assign this role to some users, they will be granted all admin permissions but only on resources of Organization A. Note that some resources are not scopeable by Organization and Locations. Filters for such resources grant permissions globally.

The seeded Organization admin role is similar to the Manager role. They are both being automatically extended with permissions introduced in new Foreman versions, as well as permissions introduced by plugins. The difference is that Organization admin role does not contain permissions for managing organizations, only for viewing them. Since organization administrator does not usually need to create or modify other organizations, the Organization admin role fits better this scenario.

System admin role is a seeded role with very powerful abilities. The purpose of this role is to set up environment for others to use. It can create organizations/locations but does not have access to the resources inside them. System admin can create new users and assign them to locations/organizations and add roles to the users. System admin can view and edit settings. But most importantly, users with this role can even delegate roles that they themselves do not own. Users having this role can potentially step out of it by creating a new user with roles/permissions that they do not have as System admin and log in as the newly created user. Therefore only trusted users should be allowed to have this role.

Filters are defined within the context of a role, clicking on the `filters and permissions' link. A filter allows a user to choose a resource (Hosts, Host groups, etc…) and the permissions that should be granted for that resource. After a filter has been created, users given a role containing this filter will have the permissions for the resource specified at the filter.

If the filter is marked as `Unlimited?', the permissions created in this filter will apply to all objects in the chosen resource. For instance, if the resource is Host, and the permissions are `view' and `index', and `Unlimited?' is checked, users that have a role with this filter will be able to `view' and `index' all hosts in the system.

When `Unlimited?' is unchecked, a text box allowing to define more granular filtering will be enabled. You can write a search query and permissions in this filter will be applied to the results of that query only. An example of a query for the resource Host could be `os = RedHat'. In this case, the permissions in this filter will be applied only to Hosts whose Operating System is set to Red Hat. You can test your search queries at the index page of your resource, in this case that would be `/hosts'.

Some example queries for the resource Host:

These pools of queries can be combined by adding them together or the filters can be used to restrict the selected resource to a smaller and smaller subset of the total. Think of them as set operations.

As already mentioned, a Role can be assigned to Organizations and Locations. In such case, all filters for resources that support such scoping automatically apply the same Organizations and Locations. If you want to combine filters with different Organizations or Locations assignments, you can use `Override' check box. When checked you can override Organizations and Location for a filter. If you uncheck this field, the filter starts inheriting its role Organizations and Locations after submitting again. If you want to reset all role filters to start inheriting, you can use `Disable all filters overriding' button on role’s `Filters' tab.

image::static/images/screenshots/4.1.2_filters_override.png[Disable all filters override]

We recommend managing Organizations and Locations association on Role level to keep the setup simple and clear.

Note: If the ``Administrator'' check box is checked for a user, filtering will not take effect.

These determine the operations that are allowed to be performed upon the resources to which they refer. For a few simple items like bookmarks, this operates as expected - it grants permission for all bookmarks. But for most resources, such as the hosts a user is able to operate on, there is an additional layer of security called filtering.

When editing a filter there is a search field at the bottom that narrows the scope of the permissions granted to a subset of the resource objects. Most permission types support this search field however there are some exceptions. The permission for creating objects can’t be limited by a search query because the object does not exist during creation. Therefore a user is granted the create permission if they are associated with any filter containing this permission (limited by search or not).

Following table lists some of permissions and their impact:

Go to the Audit tab to see a view of what has changed. This view can be filtered by the type of change or by the object that was altered (e.g. search for a hostname to see all changes relating to that host). You also get the parent object - so if a parameter was modified, you can see what host/group that parameter belongs to. The timestamp of the change and the user who performed it will be listed.

Template changes also store a diff of the changes, and the ability to roll back to a previous version of the template.

You will probably want to delete your old audits after some time. To achieve this, there is a cronjob. This job invokes rake task audits:expire. There is no default value for number of days to keep because every user has different needs. However, you can configure an amount of days to keep in Foreman in Settings (Administer → Settings → General (Tab) → Save audits interval) to fit to your needs. You can leave value empty to no expire old audits. Also this task can be invoked manually whenever required. Invocation can be done by foreman rake audits:expire. If the days parameter is not provided, the task is trying to take configured value from Settings. If this value is also empty, task is closed and no audits are expired.

Available parameters: * days ⇒ number of days to keep audits (defaults to 90)

To expire all audits older then 7 days

Note that you can also set a cronjob which will delete your audits periodically using this rake task.

Here, anonymization clears links to user accounts and their IP addresses, but keeps all other audit data in database.

You can anonymize your old audits instead of deleting the audit entries. Use task foreman-rake audits:anonymize for this similarly to audits:expire.

Example:

Audits inherit organizations and locations of resources for which they have been created. Imagine you have a subnet assigned to organization A. Whenever you modify this subnet, the audit will be visible only in organization A. When you later add this subnet to organization B, new audits will appear in both organizations A and B. All audits created previously remain untouched. Resources that can’t be assigned to any organization or location will be always visible in all organizations and locations, meaning the change has affected all organizations and locations.

Audited resources can change in time, e.g. they have new attributes. Also audit definitions changes, e.g. new association starts to be tracked in new version of Foreman. All these changes only apply to newly created audits, old audits can’t be updated and will always contain only data known back in time they were created. Starting with Foreman 1.20, audits are scoped to organizations and locations. All audits created before are unassigned, meaning only admin can see them.

Searching is through ``field = value'' or free text queries, which can be combined with logical operators (and, or, not) and parentheses to handle more complex logic. To give some examples:

The fields available depend on the type of resource that’s being searched, and the names of the attributes vary depending on the context. The name'' field on the host groups list is equivalent to the hostgroup'' field on the hosts list. Requests to add additional searchable fields are welcome, and may be filed in the ``Search'' category in the bug tracker.

The search engine is provided by the scoped_search library, which maps search queries directly to SQL queries. The Query Language documentation provides A more complete specification of the syntax available.

Foreman supports the ability to make search bookmarks, allows users to quickly jump to predefined search conditions. Available bookmarks can be selected from the dropdown menu to the right of the search box, or managed from Administer > Bookmarks.

Some of the bookmarks are provided by default, e.g. to search for active or inactive hosts, or to only view reports with events.

To save a query, Use the dropdown menu to the right of the search box and click ``Bookmark this search''. When saving, the bookmark can be labeled as public, so all other users are able to see and use it too.

If you ignore the auto-completer and just enter text in the search field, Foreman will try searching for that text across multiple fields.

For example, if you just enter 12 in the hosts search box, the results will include all hosts with 12 in their IP address, MAC address or name. In general the fields used for free text search are kept to a minimum for performance and accuracy reasons. It’s preferable to search using a specific field, e.g. when searching for an IP address, use ip ~ 12 instead of 12.

The `has'' operator matches values that are present, e.g. to search for hosts that are on a compute resource, use `has compute_resource.

Similarly, this can be negated, so to search for hosts without host groups, you can use not has hostgroup.

When querying using = and != operators then exact, case sensitive matches will be returned. When running ~ (like) and !~ (unlike) operators, the matching is case insensitive.

In search queries, white spaces are used as a delimiter. Here are some examples of the way a query will be interpreted:

In the second and third example, ``successfully'' is an additional term that is interpreted as a free text search

The ~ and !~ search operators are translated to the LIKE and NOT LIKE SQL queries respectively, which support two basic wildcards, _ and %.

is a wildcard for a single character replacement. For example, the search name ~ fo will match both foo'' and for''.

The % and wildcard will replace zero or more characters. For example, the search name ~ corp% will match both corp'' and corporation''. The more common ’’ wildcard is not a SQL wildcard but may be used instead.

When the ~ or !~ search is processed, a %' wildcard is automatically added at the beginning and end of the value if no wildcard is used, so it will by default match at any location inside a string. For example, the search `name ~ foo is equivalent to name ~ %foo% and the search name ~ foo% will only match ``foo'' at the beginning of the value.

Many date and time formats are accepted in search queries. Here are some examples:

The date can have different separators, 10-July-2011'' will be interpreted in the same way as 10/July/2010'' or 10 July 2011'' Month names may be the full English name or a three letter abbreviation, e.g. Jan'' will be interpreted as January''. Many other formats are also acceptable, however it is not recommended to use ambiguous formats such as 3/4/2011''

The valid date time operators are `=', `<' and `>' which are interpreted as `at', `before' and `after' respectively. This is how the search term interpeted:

The right hand part of a date-time condition is parsed and translated into a specific date-time, 30 minutes ago'' is translated to now - 30 minutes''.

A search query like installed_at = Yesterday is translated into a period query, it will be translated at runtime to match a range of date-times. For example, if running on Jan 1, it would be translated into ``(installed_at >= Jan 1,2012 00:00) and (installed_at < Dec 31,2011 00:00)''.

Each Foreman user can have multiple SSH keys assigned when editing a user. These keys alone do not serve any purpose, but are available for use in provisioning templates and can be accessed via ENC data. They provide an easy way to manage users and login ssh keys on hosts without the need for LDAP. If you want users to be able to login to a host using the data provided in Foreman, you need to include the create_users snippet in your provisioning template. There is a puppet module available to keep user data in sync with Foreman and your hosts.

There are several ways to create Puppet environments within Foreman.

This is done from the Host Edit page, on the Host tab. Selecting an environment will filter the classes visible on the Puppet Classes tab to just the classes in the selected environment.

You can also also mass-assign an environment to a group of hosts - tick the checkboxes of the required hosts in the Hosts list, and then select Change Environment from the Select Action dropdown menu at the top of the page.

You can assign an environment to a hostgroup as well. This functions as a form of default - a user creating a new host and selecting the hostgroup will automatically have the environment pre-selected. The user is not prevented from changing the environment of the new host, it simply saves a few clicks if they are happy with it.

Go to Configure > Classes and click the Import button. This will not be visible unless you have at least one Puppet server with a puppet-enabled Smart Proxy. Only classes from modules will be imported, and the Puppet manifests must be valid in order for the Smart Proxy to parse them. Use puppet parser validate to test the syntax of Puppet manifests.

More information about configuring the Smart Proxy to read environments and Puppet classes is in the Smart Proxy Puppet section.

To cause Puppet to apply your classes, you will need to assign them to your hosts. This can be achieved in a number of ways - the best method may vary depending on how many classes you intend to assign and whether any parameters need to be overridden.

In Puppet’s DSL, accessing a global parameter or variable is done using $::example (preferred) or $example for a parameter named ``example'' in Foreman. More information about accessing variables is available in the Puppet Language: Variables documentation. When looking at the ENC (YAML) output from Foreman, a global parameter will look like this:

When using class parameters, a class will first be defined with a parameter and may be accessed either using the local name or fully-qualified, e.g.

When looking at the ENC (YAML) output from Foreman, a class and class parameter will look like this:

Global parameters in Foreman can be added in the following places:

Class parameters in Foreman can be set in:

Host inherit their list of global parameters from the following locations, in order of increasing precedence:

The final (most specific) level of global parameters applies only to a single host. Edit a Host and switch to the Parameters tab, and you will see all of its inherited parameters from the previous levels. You can override any of these previously-defined parameters or define new ones here.

Global parameters support multiple data types and validation as per type selected. With types support, searching by parameter value is no longer allowed.

To see how Foreman is passing the parameters to Puppet, go to a Host and click the YAML button. You will be shown the exact YAML data sent to the Puppet server - the parameters will be in the ``parameters'' hash.

By default, parameterized class support is enabled in Foreman. This can be checked from Administer > Settings > Puppet and ensure Parametrized_Classes_in_ENC is set to true.

Now you’ll need to import some parameterized classes from your Puppet server. If you don’t have any parameterized classes in your modules dir, the foreman-installer has several, you can download a few modules from the Puppet Forge. Once you have some parameterized modules, import your classes (see 4.2.2 Classes)

This example will work with the foreman class from the installer. Click on the class, and you should get a page with 3 tabs, like so:

The middle tab, ``Smart Class Parameter'', is the important one. Click onto that, and you should see something like this:

On the left, we have a list of possible parameters that the class supports. On the right, we have the configuration options for the parameter selected.

Lets configure the foreman class to change the user the foreman processes run as. Select the user parameter, at the end of the list. Now lets go through the options:

Ok, so let’s configure our user parameter. We want to tick Override, set type to String'' and set the default value to foreman'', like so:

image::static/images/screenshots/param_classes/1.14/user_param.png[User Param]

Tip: you can set Override on all parameters on a class from the Puppet classes list, clicking the dropdown menu on the right and clicking ``Override all parameters''.

Most importantly, the Override option has to be enabled for Foreman to control this variable, otherwise it will never be managed and will not appear in the ENC output.

The Default value will be supplied in the ENC output and should be a supported value, such as a string, YAML or JSON structure or use template features (see following sections). When the Omit checkbox is enabled, no default value will be present in the ENC output unless an override matches. Puppet will instead use the class default or data binding (Hiera) as usual.

The default will be imported from the Puppet manifest initially, but if the class uses an inherited params pattern, it may contain an unhelpful string such as ${$foreman::params::user}. Foreman is unable to parse the actual value in this case as it might change when evaluated. Change the suggested default to the actual value, or tick the Omit checkbox.

We’ve configured the default, but that’s not very useful. We need to be able to override the default for hosts or groups of hosts. To do that we need the ``Override Value For Specific Hosts'' section at the bottom of the page.

Let’s say that any machine in the development'' Puppet environment should use a value of foremandev'' instead of foreman'' for the user'' parameter. Add environment'' to the end of the matchers list, then click the New Matcher-Value'' button, and fill it out like this:

This is a basic configuration - for more complex examples of using matchers, see the Smart Matchers section.

If Foreman manages the value of a class parameter (``override = true''), it’s also possible to update a host-specific override from the host itself. That way you don’t have to grant access to the Puppet Classes page to everyone. From a Host, click Edit, go to the Parameters tab, and you’ll see the variable, the class-scope, and the current value. You can then override the value for that host:

image::static/images/screenshots/param_classes/1.14/hostedit.png[Host Edit]

If the value is hidden you can click the unhide button to temporarily see the value while you edit. Clicking the button won’t change the hidden property for the parameter, only show it for editing purpose.

image::static/images/screenshots/param_classes/1.14/hide_button.png[Hide button]

If you go back and look at the Puppet class, you’ll see Foreman has added a matcher for that host:

image::static/images/screenshots/param_classes/1.10/hostmatch.png[Host Matcher]

The same override button is available on a host group’s Parameters tab. For more complex logic, like matching on facts, use the Puppet Class page.

Smart class parameters are based on the smart matchers technology, and have a number of advanced features such as validation and multiple data types. More about these can be found in the Smart Matchers section.

Overrides are processed in the order of precedence set in the Order field, from most to least specific (first match wins, unless merging is enabled). This is a list of host attributes and fact names that overrides will be checked against. If no override from this list matches, the default value is used.

Example attributes that may be listed are:

The default order is set under Administer > Settings > Puppet > Default_variables_Lookup_Path and is fqdn'', hostgroup'', os'', domain''.

Note that there’s a name conflict between the operatingsystem'' fact and Foreman’s attribute operatingsystem'' (same as ``os'' above), and Foreman’s attribute will be the one that is used, so will include the version number.

Once defaults have been filled in for your parameter, you can then add criteria to match against - click the Add Matcher button under your parameter, and more input fields will appear:

As an example, let’s say that any machine in the development'' puppet environment should use a value of foremandev'' instead of foreman'' for the user'' parameter. Add ``environment'' to the end of the matchers list, then click the Add Matcher-Value button, and fill it out like this:

The match field currently supports string equality only, the values must match exactly.

The type of data we want to pass to Puppet can be set in the Parameter type field. Most commonly a string, but many other data types are supported:

There’s no easy way to tell what type of data the Puppet manifest is expecting, so you will need to read through the code/documentation that comes with a particular module to find out. Changing the type field requires an appropriately set ``Default Value'' field.

The Optional input validator section can be used to restrict the allowed values for the parameter. It is important to note that the validation applies to changes made from the Host edit page as well as the Puppet Classes edit page.

The input validation section is hidden by default but can be opened by clicking on its title. When changing the parameter type this section will be automatically expanded to change the validations according to the new type.

For example, to restrict the user'' field to either foreman'' or ``foremandev'', tick the Required checkbox, and then set:

Because Foreman offers templating capabilities, you can utilise pre-existing variables, macros and or functions within your parameterized classes. This is especially useful if you need to send a string to Puppet/Chef, but have a need to embed host specific information within the string, such as the host’s FQDN.

Let’s look a quick example situation: we need to configure RabbitMQ and have it use our existing Puppet SSL certs. Using what we’ve learnt above, we jump into the RabbitMQ class and configure the ``ssl cert'' parameter as such:

image::static/images/screenshots/param_classes/1.14/template-variable-rabbit-ssl-cert.png[Template Variable]

As you can see we’re utilising a template variable within the parameter’s string just like we would in a normal template file. The important part of this string, as we’re sure you’ve gathered, is the ``@host.name'' element. This pulls the FQDN from Foreman’s facts and inserts it into the string.

More information regarding templates can be found on the wiki. This page also contains the pre-existing functions and macros you can use in your templates and parameter classes.

RPM and Debian packages are available, see the Install from Packages section for configuration and install the foreman-proxy package.

You can get the latest stable code from GitHub (git://github.com/theforeman/smart-proxy.git[via git]).

The smart proxy will run with the following requirements (aside from rubygem dependencies):

The Microsoft smart-proxy installation procedure is very basic compared to the RPM or APT based solution. You need to run smart-proxy from the source as well as install Ruby and Ruby DevKit.

Usually can be found at /etc/foreman-proxy/settings.yml or in the config/settings.yml subdirectory. You can use the settings.yml.example file inside the config directory as a template for your own settings.yml.

Configuration of each subsystem is usually in /etc/foreman-proxy/settings.d/ or in the config/settings.d/ subdirectory. If you don’t plan to use one of the subsystems, please disable them in these configuration files. For more information see Smartproxy Configuration.

Or if you installed it via a package simply start the foreman-proxy service.

For example:

The first non-comment line of all configuration files must be three dashes.

If daemon is present and true then the Smart Proxy will attempt to disconnect itself from the controlling terminal and daemonize itself on startup, writing its pid (process ID) into the specified file.

The proxy’s output is captured to the log_file and may be filtered via the usual Unix syslog levels:

See Ruby’s Logger class for details.

The log_file setting may be set to STDOUT'' which causes log messages to be logged to standard output, for capture by the running process (e.g. systemd with journal). When log_file is set to SYSLOG'', all messages will be sent to syslog.

A limited number of recent log messages are kept in memory using a ring buffer, which can be exposed in the API and to Foreman by enabling the Logs feature.

The number of all log messages is controlled by the log_buffer setting, and a second buffer of error messages is controlled by the log_buffer_errors setting. The total of the two will directly affect the maximum amount of memory used, which is approximately 500kB in the default configuration of 3,000 recent messages.

By default the Smart Proxy listens on all interfaces, which can be changed to limit access to a network:

On EL7, the default value for bind_host is ::. Keep in mind that if IPv6 has been disabled at the kernel level, you will need to change it to * manually.

The Smart Proxy has a number of different modules which can be enabled either for HTTP, for HTTPS or for access on both services. It is highly recommended to enable most only on HTTPS and only enable modules on HTTP when required (e.g. templates) or if no SSL is desired.

The two port options control which TCP port(s) the Smart Proxy will listen on. At least one must be enabled for the proxy to start. It is recommended to only set https_port unless an HTTP-only module is active, which also requires the three ssl_* settings to be set.

Be careful when enabling http_port, ensure settings.d/ files are enabled only on HTTPS or trusted_hosts is set appropriately so modules are not exposed without security on HTTP.

Modules are enabled in their per-module configuration file in /etc/foreman-proxy/settings.d/ with the :enabled directive, which can be set to:

The existence of all the three ssl key entries below requires the use of an SSL connection.

NOTE that both client certificates need to be signed by the same CA, which must be in the ssl_ca_file, in order for this to work see SSL for more information

Specific SSL cipher suites can be disabled by using the :ssl_disabled_ciphers: option. For more information on which cipher suites are enabled by default and how to correctly disable specific ones, please see SSL cipher suites.

The TLS versions can be disabled if requiring a specific version. So while insecure SSLv3 and TLS v1.0 are disabled by default, setting the array of :tls_disabled_versions: to include 1.1 will disable this version, too.

This is the list of hosts from which the smart proxy will accept connections. For HTTPS connections, the name must match the common name (CN) within the subject DN and for HTTP connections, it must match the hostname from reverse DNS.

For HTTPS connections, the name must match the common name (CN) within the subject DN and for HTTP connections, it must match the hostname from reverse DNS. When :forward_verify is enabled (default: true) then the reverse lookup is verified against the forward lookup of the hostname (aka forward-confirmed reverse DNS/FCrDNS).

Some modules may allow connections from all hosts rather than only the trusted_hosts list, particularly if they intend to deal with requests directly from managed hosts rather than only from Foreman.

An empty trusted_hosts list will permit no hosts access:

While if the setting is not specified, any host may make requests to the smart proxy, which permits management of any enabled modules and features.

Some modules make requests back to Foreman, e.g. when relaying requests from client hosts. The following setting changes the destination URL:

And the following settings change the SSL certificates used to authenticate to Foreman and to verify its certificate. In a typical installation, Foreman and the Smart Proxy may both use certificates signed the same certificate authority, so these default to the values of the ssl_* settings defined above.

The SSH BMC provider provides a limited level of BMC functionality by running commands over an SSH connection to the host using a trusted SSH key.

It has the following configuration options for authentication, for the remote SSH user and private SSH key:

The following configuration options control the commands executed by the provider on the remote host:

No power on support is possible with this provider.

Activate the DHCP management module within the Smart Proxy instance. This is used to query for available IP addresses (looking at existing leases and reservations), add new and delete existing reservations. It cannot manage subnet declarations, which should be managed by another means (e.g. puppet-dhcp).

The DHCP module is capable of managing the ISC DHCP server, Microsoft Active Directory and Libvirt instances.

Builtin providers are:

Extra providers are available as plugins and can be installed through packages. See the following pages for more information:

To enable the DHCP module and enable a provider, dhcp.yml must contain:

For providers from plugins, check the plugin documentation to determine the exact provider name.

The module manages a DHCP server on the local host by default, but for providers that can be run remotely, the server address can be changed:

Note that if the DHCP server is running remotely, some providers (notably ISC) require that the configuration files must be accessible to the Smart Proxy still. This can be achieved with a network file system, e.g. NFS.

All available subnets will be loaded and can be managed by default, but this can have a performance penalty. If only some subnets are used, specify them as follows in network_address/network_mask notation:

Each provider has its own configuration file in the same directory with its own settings, e.g. dhcp_isc.yml. This usually needs additional configuration after changing the use_provider setting.

The dhcp_isc provider uses a combination of the ISC DHCP server OMAPI management interface and parsing of configuration and lease files. This requires it to be run either on the same host as the DHCP server or to have network filesystem access to these files.

This provider requires the config and leases settings in the dhcp_isc.yml configuration file, which should be set to the location of the DHCP server config and lease files. On a Red Hat or Fedora server use:

On a Debian or Ubuntu DHCP server, use the following values instead:

The foreman-proxy account must be able to read both configuration files. In particular, check the permissions on the parent directory (e.g. /etc/dhcp) permit world read/execute.

If the DHCP server is secured with an ``omapi_key'', the following entries must be set with the same values:

If the DHCP server is listening on a non-standard OMAPI port (i.e. not 7911), then change this with:

For DHCP servers running on a different host, change :server in the main dhcp.yml configuration file.

The native_ms provider manages reservations in Microsoft Active Directory via its native API.

Possible configuration options in dhcp_native_ms.yml are:

When disable_ddns is true (default), dynamic DNS updates will be disabled for all hosts that the smart proxy creates. This will slightly slow the host creation process but will ensure that the DHCP server will not create or delete DNS entries on behalf of these clients. It’s preferable to disable this feature at the scope level.

Provider that manages reservations and leases via dnsmasq through libvirt API. It uses ruby-libvirt gem to connect to the local or remote instance of libvirt daemon.

Possible configuration options in dhcp_libvirt.yml are:

When configuring local or remote connections, make sure the foreman-proxy effective user has UNIX permissions to libvirt socket or ssh keys are deployed when using remote connection.

More information about using this provider is in the Libvirt section.

ISC implementation is based on the OMAPI interface, which means:

It is required that this procedure is executed as an administrator.

It is not required that the smart proxy be on the same host as the MS DHCP server. The smart proxy just needs to be on a Windows host with connectivity to the DHCP server. If this is the case, make sure the smart proxy service runs as a user with sufficient privileges.

Note: Refer to the installation guide for general setup.

Activate the DNS management module within the Smart Proxy instance. This is used to update and remove DNS records from existing DNS zones.

The DNS module can manipulate any DNS server that complies with the ISC Dynamic DNS Update standard and can therefore be used to manage both Microsoft Active Directory and BIND servers. Updates can also be made using GSS-TSIG, see the second section below. Additional providers are available for managing libvirt’s embedded DNS server (dnsmasq) and Microsoft Active Directory using dnscmd, for static DNS records, avoiding scavenging.

Builtin providers are:

Extra providers are available as plugins and can be installed through packages. See the following pages for more information:

To enable the DNS module and enable a provider, dns.yml must contain:

For providers from plugins, check the plugin documentation to determine the exact provider name.

The default TTL of DNS records added by the Smart Proxy is 86400 seconds (one day). This can be changed with the dns_ttl setting:

Each provider has its own configuration file in the same directory with its own settings, e.g. dns_nsupdate.yml. This usually needs additional configuration after changing the use_provider setting.

The dns_nsupdate provider uses the nsupdate command to make dynamic updates to the DNS server records. This works on a wide variety of RFC2136-compliant servers.

DNS servers that support Kerberos authentication, e.g. FreeIPA or Microsoft Active Directory, should use the dns_nsupdate_gss provider instead.

This provider has the following settings in the dns_nsupdate.yml configuration file:

The dns_key specifies a file containing a shared secret used to generate a signature for the update request (TSIG record), thus authenticating the smart proxy to the DNS server.

If you use a key file or keytab, make sure that only the foreman-proxy account can read that file.

If neither the dns_key or GSS-TSIG is used then the update request is sent without any signature. Unsigned update requests are considered insecure. Some DNS servers can be configured to accept only signed signatures.

The dns_server option is used if the Smart Proxy is not located on the same physical host as the DNS server. If it is not specified then localhost is presumed.

For servers that support Kerberos/GSS-TSIG to authenticate DNS updates, the dns_nsupdate_gss provider should be used. This typically applies to FreeIPA and Microsoft Active Directory servers. This is equivalent to the nsupdate -g command.

This provider has the following settings in the dns_nsupdate_gss.yml configuration file:

See the section on GSS-TSIG DNS below for steps on setting up the requisite accounts and keytabs with both AD and FreeIPA.

The dns_server option is used if the Smart Proxy is not located on the same physical host as the DNS server. If it is not specified then localhost is presumed.

While the dns_nsupdate provider creates dynamic records in Active Directory, the dns_dnscmd provider uses the dnscmd tool to create static DNS records in AD, which are not affected by scavenging. This requires that the Smart Proxy is installed on a Windows server with dnscmd available.

The dns_server option is used if the Smart Proxy is not located on the same physical host as the DNS server. If it is not specified then localhost is presumed.

Provider that manages reservations and leases via dnsmasq through libvirt API. It uses ruby-libvirt gem to connect to the local or remote instance of libvirt daemon.

Possible configuration options in dns_libvirt.yml are:

When configuring local or remote connections, make sure the foreman-proxy effective user has UNIX permissions to libvirt socket or ssh keys are deployed when using remote connection.

More information about using this provider is in the Libvirt section.

Bind configuration manipulation is based on nsupdate, which means that in theory could also be used to manipulate other dns servers which support nsupdate (such as Microsoft DNS server).

In order to communicate securely with your dns server, you would need a key which will be used by nsupdate and your named daemon using ddns-confgen or dnssec-keygen

execute `ddns-confgen -k foreman -a hmac-md5' - this should output something like the following:

You should create a new file (such as /etc/rndc.key or other) and store the key “foreman \{…} in it. in the proxy Settings file you should point to this file location - make sure that the proxy have read permissions to this file.

In your named file, you could add the update-policy statement or something like this named example file if you need more fine grained permissions.

Both BIND as configured in FreeIPA and Microsoft AD DNS servers can accept DNS updates using GSS-TSIG authentication. This uses Kerberos principals to authenticate to the DNS server. Under Microsoft AD, this is known as ``Secure Dynamic Update''.

A user has to be created in Active Directory that will be used by the Smart Proxy, e.g. foremanproxy. This will automatically create a service principal, e.g. foremanproxy@EXAMPLE.COM.

Test the Kerberos login with that user on the Smart Proxy using kinit:

This requires that your SRV records in DNS or /etc/krb5.conf file is setup correctly. By default many systems use DNS to locate the Kerberos DC. A KDC can also be statically set in this file. There are dozens of documents on how to do this on the net.

If login works, the keytab file can be created using ktutil. First clear the Kerberos ticket cache:

Now create the keytab file with ktutil:

Once the keytab file has been created, test it using kinit:

If this works, clear the Kerberos ticket cache once again using kdestroy.

Store the keytab at /etc/foreman-proxy/dns.keytab, ensure permissions are 0600 and the owner is foreman-proxy. If you are using SELinux, do not forget to update the file context.

The DNS zone Dynamic Updates option on the DNS zones can now be set to Secure Only.

Restart the smart proxy service. Next, go to Update the configuration in Foreman.

A service principal is required for the Smart Proxy, e.g. foremanproxy/proxy.example.com@EXAMPLE.COM.

First of all, create a new principal (FreeIPA service) for Foreman, e.g. ipa service-add foremanproxy/proxy.example.com@EXAMPLE.COM.

Then fetch the keytab, e.g. ipa-getkeytab -p foremanproxy/proxy.example.com@EXAMPLE.COM -s ipa-server.example.com -k /etc/foreman-proxy/dns.keytab.

Store the keytab at /etc/foreman-proxy/dns.keytab, ensure permissions are 0600 and the owner is foreman-proxy.

The ACL on updates to the DNS zone then needs to permit the service principal. In the FreeIPA web UI, under the DNS zone, go to the Settings tab, verify that Dynamic update'' for that zone is set to True'', and add to the BIND update policy a new grant:

Note the \047 is written verbatim, and don’t forget the semicolon. ACLs should be updated for both forward and reverse zones as desired.

Update the proxy DNS configuration file (/etc/foreman-proxy/settings.d/dns.yml) with the following setting:

And the DNS GSS configuration file (/etc/foreman-proxy/settings.d/dns_nsupdate_gss.yml) with:

Ensure the dns_key setting is not specified, or is commented out.

Restart the smart proxy service. Next, go to Update the configuration in Foreman.

After you have added a DNS smart proxy, you must instruct Foreman to rescan the configuration on each affected smart proxy by using the drop-down menu by its name and selecting ``Refresh Features''.

Now, you are allowed to enable this in each subnet (reverse lookup of domain) and domain (forward lookup of domain) that you want this smart proxy to assist. You do this by navigating there and selecting it in the drop-down menu for DNS.

Parsing manifests is done by Puppet itself, which means the manifests must be valid and pass syntax checks, else they won’t show up. Use puppet parser validate example.pp to validate the content of a manifest.

To get a list of environments, classes and their parameters, the proxy queries the Puppetserver on its own API. The URL and settings used for the proxy to Puppetserver API query can be controlled with the following settings in /etc/foreman-proxy/settings.d/puppet_proxy_puppet_api.yml:

The Puppetserver has to permit these API queries. The HOCON-formatted auth.conf style is at /etc/puppetlabs/puppetserver/conf.d/auth.conf and requires these rules:

The puppetca_hostname_whitelisting provider directly manages Puppet’s autosign.conf file. This will create an autosign entry for a host during deployment and remove it when deployment is finished. Furthermore it allows you to manage entries manually using the Foreman WebUI.

The autosignfile setting in puppetca_hostname_whitelisting.yml is used to find autosign.conf:

The location of the file can be determined with puppet config print autosign.

The proxy requires write access to the puppet autosign.conf file, which is usually owner and group puppet, and has mode 0644 according to the puppet defaults. Ensure the foreman-proxy user is added to the puppet group ( e.g. gpasswd -a foreman-proxy puppet or usermod -aG puppet foreman-proxy)

puppet.conf:

The puppetca_token_whitelisting provider uses a token-based certificate signing managed by the Smart Proxy itself and queried by Puppet during Provisioning. This provider adds more security and logging to the autosigning process but does not allow for manual creation of autosigning entries.

This provider has the following settings in puppetca_token_whitelisting.yml:

By changing sign_all to true you will disable token verification and sign all certificate requests. The setting token_ttl defines how long a token after creation is valid in minutes. tokens_file sets the path to the file used to store tokens during deployment, the foreman-proxy user requires read and write access to this file.

You can also change the certificate used for encrypting the token file by setting certificate. By default it uses the certificate of the Smart Proxy defined in settings.yml as ssl_certificate.

To integrate this in Puppet the script puppet_sign.rb provided by the Smart Proxy has to be used for verfication of the tokens during certificate signing. If installed via package the script should be already located at /usr/libexec/foreman-proxy/puppet_sign.rb. For manual installation the script can be found on Github. Using the latest version should be fine, if you encounter problems try the one released with your Smart Proxy version. The script has to be executable by the same user running the Puppet server, typically puppet.

After deploying the script the Puppet configuration has to be changed to point the autosign setting to the script.

Note this is used in Puppet 5 and earlier as determined by the puppet_version setting in puppetca.yml.

This implementation is used for managing certificates. It uses the puppet cert command and typically requires sudo access for the proxy.

The ssldir setting is required and can be determined with puppet config print ssldir. Puppet AIO defaults to using /etc/puppetlabs/puppet/ssl.

By default sudo is used but can be disabled with puppetca_use_sudo setting. The sudo command is dermined via the PATH variable or can be explicitly set with the sudo_command setting.

For sudo to work correctly, it must be configured to allow puppet cert with NOPASSWD and without requiretty. Under a Puppet AIO installation, configuration should be:

Under a non-AIO Puppet installation:

Note this is used in Puppet 6 and newer as determined by the puppet_version setting in puppetca.yml.

As the name implies, Puppetserver’s HTTP API is used to manage certificates. In its configuration file puppetca_http_api.yml the connection details are configured:

The Puppet server does not need to be on the same host, but only the puppetca_token_whitelisting provider supports this. Note the Puppetserver also needs to allow access to the Smart Proxy.

Activate the realm management module within the Smart Proxy instance. This manages Kerberos realms or domains, allowing Foreman to add and remove hosts to enable them to join the realm/domain automatically during provisioning.

Builtin providers are:

The configuration for each provider should be in its respective file, i.e: /etc/foreman-proxy/settings.d/realm_freeipa.yml.

The following settings control authentication of the proxy to the realm for management of hosts. In realm_freeipa.yml:

The FreeIPA implementation of the realm proxy is able to add a host entry to FreeIPA, send the hostgroup name, and request a one-time registration password.

Activate the TFTP management module within the Smart Proxy instance. This is designed to manage files on a TFTP server, e.g. bootloaders for OS installation and PXE menu files.

The tftproot value is directory into which TFTP files are copied and then served from. The TFTP daemon will also be expected to chroot to this location. This component is only supported in a Unix environment.