4.7.1. Classification and Data¶
4.7.1.1. Node Classification in SIMP¶
From the Puppet, Inc. website:
Hiera is a key/value lookup tool for configuration data, built to set node-specific data without repeating yourself.
SIMP uses Hiera to attempt to make configuration of the overall system easier for our end users by providing a simple, centralized, method for setting class parameters using automatic parameter lookup.
It is highly recommended that you read the Hiera Documentation prior to jumping into using a SIMP system.
4.7.1.2. Hiera in SIMP¶
SIMP users are expected to make extensive use of Hiera to set parameters, particularly those that are deep within the code.
The default Hiera hierarchy used by SIMP defined at the environment level in the Hiera configuration file and looks like the following:
---
version: 5
defaults:
datadir: data
data_hash: yaml_data
hierarchy:
- name: Per-node data
paths:
- "hosts/%{trusted.certname}.yaml"
- "hosts/%{facts.fqdn}.yaml"
- "hosts/%{facts.hostname}.yaml"
- name: Per-domain data
paths:
- "domains/%{facts.domain}.yaml"
- name: Per-OS data
paths:
- "%{facts.os.family}.yaml"
- "%{facts.os.name}/%{facts.os.release.full}.yaml"
- "%{facts.os.name}/%{facts.os.release.major}.yaml"
- "%{facts.os.name}.yaml"
- name: Per-hostgroup data - See site.pp for more information
paths:
- "hostgroups/%{hostgroup}.yaml"
- name: General data
paths:
- "default.yaml"
- "common.yaml"
- name: SIMP specific data - Please do not modify
paths:
- "simp_config_settings.yaml"
- "scenarios/%{simp_scenario}.yaml"
Warning
This may not be accurate for your version of SIMP, please check your local Hiera settings!
The rest of this document will use this hierarchy as a reference.
4.7.1.3. Assigning Classes to Nodes¶
The SIMP profile module includes other classes needed for a secure
baseline, which are discussed below in the SIMP scenarios
section. The lists of included classed are controlled by the simp::classes
and simp::server::classes
class parameters:
- The
simp::classes
parameter is available for all nodes. - The
simp::server::classes
parameter is available only for the SIMP server (Puppet master).
To preserve various levels of ordering and overrides, it is highly recommended
that you use the simp::classes
and simp::server::classes
class parameters
in Hiera to manage standard class inclusions.
This allows you to use the --
knockout prefix to exclude classes at any level
of your hierarchy, which, in turn, allows you to use your own modules to manage
specific applications that SIMP manages by default.
---
simp::classes:
- gnome
---
simp::classes:
- '--ntpd'
---
simp::classes:
- '--ntpd'
simp::server::classes:
- '--ntpd'
4.7.1.3.1. Legacy Method¶
SIMP also includes class inclusion functionality via a top-level classes
array in your Hiera hierarchy. Though this is no longer recommended, it is
still supported.
In this case, instead of using the knockout prefix, there is also a
class_exclusions
array that will be used to remove classes from the
include list. Note, however, this array cannot be applied to any classes
included via simp::classes
or simp::server::classes
.
4.7.1.4. Assigning Defined Types to Nodes¶
Defined types do not have the ability to receive parameters via Hiera in the
traditional sense. To include a defined type on a node, one could use
create_resources
, but this is messy and discouraged. Instead, create your
own profile or a site
module with site-specific manifests. For example,
/etc/puppetlabs/code/environments/production/modules/site/manifests/my_site.pp
.
Note
You can find a working example of this in the Configure PXE Boot section of the documentation
4.7.1.5. SIMP Scenarios¶
SIMP scenarios are groups of classes, settings, and simp_options that ensure the system is compliant and secure.
There are currently four SIMP scenarios:
- simp
- simp_lite
- poss
- remote_access
The simp scenario includes all security features enabled by default, including iptables and svckill. This scenario is what stock SIMP used to look like in previous releases.
The simp_lite scenario offers many security features, with a few explicitly turned off. This scenario was designed to make it easier to implement SIMP in an existing environment, because it might not be trivial to flip SELinux to Enforcing on all nodes.
The poss option is the barebones option. It only includes the pupmod
class, to configure Puppet agent on clients. All of the simp_options default to
false, so SIMP will not do a lot of modification to clients through Puppet when
using this scenario.
The remote_access scenario includes the SSH module and the authentication stack, namely PAM and nsswitch. This scenario is useful for those who want to retain remote access to their machine while leaving virtually everything else untouched.
These scenarios are defined in the pupmod-simp-simp module. For more details refer to this module.
Note
The SIMP or Puppet master is exempt from most of these settings, and will be
using most features from the simp scenario by default. The SIMP server
should only have services on it related to Puppet and systems management,
and SIMP modules all work with all security features enabled. See the
puppet.your.domain.yaml
in the data/hosts
directory for
details.
4.7.1.6. The SIMP Compliance Engine¶
The SIMP Compliance Engine allows users to enable validation and enforcement of inbuilt and/or custom compliance. SIMP Community Edition contains freely available profiles generally maintained by the community. SIMP Enterprise Edition contains additional profiles targeted more at commercial regulations. Enforcement is done at the Puppet class parameter level and validation may be done against both classes and defined resource types.
This capability is provided by the simp-compliance_markup Puppet module and
will be renamed at some point in the future to simp-compliance_engine
for
clarity.
Important
Your system must be configured to use at least Hiera version 5 for the Compliance Engine to function properly.
SIMP 6.3+ supports this capability out of the box but earlier versions may need to perform a Hiera migration.
4.7.1.6.1. Enabling the SIMP Compliance Engine¶
In the Puppet implementation, the Compliance Engine is a Hiera backend that provides data from SIMP compliance profile data sets for use in configuring Puppet classes via automatic parameter lookup.
The following example demonstrates how to enable the SIMP Compliance Engine in
an example hiera.yaml
configuration.
---
version: 5
defaults:
datadir: "data"
data_hash: "yaml_data"
hierarchy:
# Anything defined at this level of the hierarchy will override settings
# in the SIMP Compliance Engine
- name: "Higher Priority Items"
paths:
- "mandatory.yaml"
- name: "SIMP Compliance Engine"
lookup_key: "compliance_markup::enforcement"
# Anything defined at this level of the hierarchy will be overridden by
# the SIMP Compliance Engine.
- name: "Lower Priority Items"
paths:
- "optional.yaml"
Note
Hierarchy lookups happen from top to bottom and stop at the first match. This means that if the SIMP Compliance Engine is in enforcing mode and is at the top of the hierarchy, then it cannot be overridden except by an ENC. See the Hiera config file syntax page for additional information.
After configuring Hiera, you then need to include the compliance_markup
class.
include 'compliance_markup'
4.7.1.6.2. Discovering Available Profiles¶
Prior to SIMP 6.4, all profile data was embedded into the
simp-compliance_markup
module. As of 6.4, the data has been split across
the modules with each SIMP module containing the module’s specific profile data
in the SIMP
directory.
Data for modules that are not maintained by the SIMP organization are still
housed in simp-compliance_markup
.
At this time, SIMP CE comes with two publicly available profiles, disa_stig
and nist_800_53:rev4
.
A simp
subcommand will eventually be provided to help discover available
profiles in different environments but, for now, you can use the following code
snippet:
ruby -r yaml -e "puts Dir. \
glob('/etc/puppetlabs/code/environments/production/modules/*/{SIMP,simp}/compliance_profiles/*.yaml'). \
map{|x| begin YAML.load_file(x); rescue; end; }.compact. \
map{|x| x['profiles'] && x['profiles'].keys}. \
compact.flatten.sort.uniq"
4.7.1.6.3. Profile Enforcement¶
The selection of profiles to enforce is based on the lookup_key
entry in
the hiera.yaml
configuration as shown in the previous section.
In this case, the lookup_key
, is compliance_markup::enforcement
and
should be set in Hiera as an Array of compliance profiles that you would like
to apply, in priority order.
If you wanted to conform with the requirements of the DISA STIG, you
would apply the disa_stig
profile as shown below:
---
compliance_markup::enforcement:
- "disa_stig"
The next run of Puppet on the nodes to which this Hiera data applies would then have their parameters set to meet the STIG requirements as mapped by parameter in the associated compliance profile.
Additional profiles may be made available by various Puppet modules, such as those provided by SIMP EE.
4.7.1.6.4. Code-Level Compliance Validation¶
The SIMP Compliance Engine also provides a mechanism for generating reports based on the Puppet parameters that are set at compile time and where those differ from the parameters that are expected for a particular compliance profile.
Note
Enforcement and validation are two distinct capabilities and the settings of one do not affect the other. This allows you to validate against multiple profiles independently of any particular enforcement setting.
In the following example, we want to validate against the nist_800_53_r4
profile:
---
compliance_markup::validate_profiles:
- "nist_800_53_r4"
By default, reports will be generated on the Puppet server and written to the
server’s vardir
which, by default, is
/opt/puppetlabs/server/data/puppetserver/simp/compliance_reports
. Only the
latest compliance report for a host is stored. The report is a YAML format that
may easily be offloaded for analysis and processing and fully documented in the
simp-compliance_markup Puppet module.
4.7.1.7. SIMP File Structure¶
The default Puppet environment in SIMP is located at
/etc/puppetlabs/code/environments/production
and contains almost all
necessary files for a Puppet infrastructure. It will look like this:
/etc/puppetlabs/code/environments/production/
├── environment.conf
├── data/
├── manifests/
└── modules/
environment.conf
- Sets the environment to include the SIMP Secondary Environment modulepath.
manifests/
- Contains SIMP’s
site.pp
.
- Contains SIMP’s
data/
- Default location of the YAML files used by Hiera; contains your node data.
modules/
- Default install location of Puppet modules. Populated automatically for you
by
simp config
.
- Default install location of Puppet modules. Populated automatically for you
by
The skeleton for SIMP’s Puppet environment is installed by the
simp-environment-skeleton
RPM into
/usr/share/simp/environment-skeleton/puppet
. This skeleton is copied into
the production
Puppet environment by simp config
. However, at any
time, you can regenerate this skeleton SIMP Omni-Environment by using
simp environment new
.
4.7.1.8. Second Modulepath¶
SIMP utilizes a second modulepath in the SIMP Omni-Environment to ensure
that deployment tools like r10k
do not squash keydist
and some krb5
files. For the production
environment, the path is
/var/simp/environments/production/site_files/
.
PKI Certificates are stored there.
4.7.1.9. Hiera¶
There are three Hiera Configuration Layers in Hiera 5. SIMP configures
Hiera at the environment level, via
/etc/puppetlabs/code/environments/<environment name>/hiera.yaml
. The
global level configuration file at /etc/puppetlabs/puppet/hiera.yaml
still
exists but its hierarchy is empty in a fresh system and probably should remain
that way for general usage.
The default hiera.yaml
for a SIMP environment is shown in Hiera in SIMP
and its syntax is explained in Hiera configuration file. The corresponding
Hiera data directory layout in a fresh SIMP system (or a new environment created
by simp environment new
) is as follows:
/etc/puppetlabs/code/environments/production/data/
├── default.yaml
├── hostgroups/
├── hosts/
├── scenarios/
└── simp_config_settings.yaml
data/simp_config_settings.yaml
- Contains the variables needed to configure SIMP. Added by
simp config
.
- Contains the variables needed to configure SIMP. Added by
data/scenarios/
- Directory containing settings for SIMP Scenarios. The scenario selected is
set in
manifests/site.pp
. This is done automatically for you when you runsimp config
.
- Directory containing settings for SIMP Scenarios. The scenario selected is
set in
data/hosts/
- Settings for specific hosts. By populating this directory with host name
files, you can assign parameters to specific hosts. Based on SIMP’s
hiera.yaml
, Hiera looks for the name in following formats:%{trusted.certname}.yaml
%{facts.fqdn}.yaml
%{facts.hostname}.yaml
- Settings for specific hosts. By populating this directory with host name
files, you can assign parameters to specific hosts. Based on SIMP’s
data/hostgroups/
- Settings for specific groups of hosts. The
hostgroup
of a node is computed using a top-scope$hostgroup
variable. By default, this is set via SIMP’s top-levelsite.pp
. Then, nodes assigned to$hostgroup
will read Hiera from a file named<hostgroup>.yaml
in this directory.
- Settings for specific groups of hosts. The
data/default.yaml
- Settings that should be applied to all systems in the environment.
Important
Do not change or update the scenarios YAML files or
simp_config_settings.yaml
. If you want to change any of the settings
contained in these files for one or more hosts, override the settings in
Hiera files earlier in the hierarchy, instead.