simp-beaker-helpers 1.18.8

data/.travis.yml

@@ -0,0 +1,36 @@
+---
+language: ruby
+cache: bundler
+sudo: false
+before_install:
+  - rm Gemfile.lock || true
+bundler_args: "--without development --path .vendor"
+notifications:
+  email: false
+rvm:
+  - 2.4.4
+env:
+  - SIMP_SKIP_NON_SIMPOS_TESTS=1
+script:
+  - bundle exec rake spec
+before_deploy:
+  - bundle exec rake clobber
+  - "export GEM_VERSION=`ruby -r ./lib/simp/beaker_helpers/version.rb -e 'puts Simp::BeakerHelpers::VERSION'`"
+  - '[[ $TRAVIS_TAG =~ ^${GEM_VERSION}$ ]]'
+deploy:
+  - provider: rubygems
+    gemspec: simp-beaker-helpers.gemspec
+    gem: simp-beaker-helpers
+    api_key:
+      secure: "AlnBx0dBSxn+S97n0h14ltKUOA+6v0bc7QZPIcwGJV9nnf1hKH3pf9La1TVknEx7XgpAcM9jusQJ7hBlqvSq8z8SFF0bZk1EgSRIKc1cuYPLiGyUM2O7+AFHyCy3iCnPvKeoQmE/BJb5O1dGnbmSbf4A0fqLxA7jiHG1j7z+cnmJB1i67wovDfl13TsOXyBfbespWBMMc0BKAw56FPs9XggAk2cNusS3hd5tqW1AZPT2/xwt+d8ngkmO96u8QcichYRFQ+w+XW4H0w935wNg/dWiskJlt7TIYVAh4Ko5s2DZKf52Tne8TugALSn0LhRatpp7sw1FTTpteCW8UqK8uwGC2hM4pZViAOv4P1YObz2IPOZPriBl+cCayJdMKnotkUJliAMnw5TLiSWKLou+S0Pdj2h3fJZWdOEwRPMzIVoJtsOHG3GdNcPL6f7iU0vP/wr6FeR3uWa+fA7NHRi2Du955O8JpogjdrW08ahcAEwhtI3A4mrA08wN09axsrwr093uDRm/5h4FHyAhExJ0YiA/6kcPpUvILcLStyHe0RQDICQMdsQo2DSbnL65w3QjFa2fML2Shf9cRwX06+ia2BxozWzFD/6p3RiRtPxphnbFiUdjYSGWcwCcUgbJx9SW04lSSxOhpyItuXgxZqiybkzstXd6riu5zwg1R8TWk34="
+    on:
+      tags: true
+      rvm: 2.4.4
+      condition: "($SKIP_PUBLISH != true)"
+  - provider: releases
+    api_key:
+      secure: "I41p4aqjkrNDHJhZ5gWC4gzn7BVwEYRm5Q3PAxQRSIUDB/QTVgNqZx8YptkuIvSGpw8kIywyZg3NKdzGUO8aJJ0NlXapL7e9qQIigkYhdaCZjZFG5zIxdOFs4sVoz/6vnQT9JIcGWy7uS5xiNOulGvfEWU78+e+I9yPdT74RApve5VAVT/km5lV5ldRnwwehLnTx+volUlnOD8rwfizoVLqFTrfRfr4cVMF605UYyaiVxHF50hywFRZoAdVcMEhlLQnQXfz/ZsLMJLJm9eCpjQ989N0oX6theSLCcv7QtHcWMXydjWMcpuTfBZSFrwUVbC23uMOKTJVEWq5LMG3m2L6hP3//2gvUzGhOVLvoGuC+erboB7QoXdcoOgXY+dTZPMcPBxpArdDLWVQSLTvPs05QzpaUdRLVMC/kD1d1EudlEicgkNgNDBhBn3089nVmvKndbKLvj+23a5AQVVbs+8C0x+SJvTc9N2N+bmuH7jIJPrEvWK4xwcQa+g2M/EBv05jaEdSErlVa6B6UKCH0Lea9rpy1se9vn5OzpaaMCCJIpcpQqHDjo0PMAQXBSbqjKcBei6lR5fIFl5UO9gWP1v8PGPuCzGTBivQ92XlgV1TWXmdbJHwIuSbJx3Ali7Wp19RR4E4uHC+TPFssvgkh9ZLkORnWWS35wzzU1LkwWx0="
+    on:
+      tags: true
+      rvm: 2.4.4
+      condition: "($SKIP_PUBLISH != true)"

data/CHANGELOG.md

@@ -0,0 +1,231 @@
+### 1.18.8 / 2020-07-14
+* Allow the beaker version to be pinned by environment variable
+
+### 1.18.7 / 2020-07-07
+* Fix host reference bug when switching to FIPS mode
+* Ensure that net-ssh 6+ can access older FIPS systems
+
+### 1.18.6 / 2020-06-24
+* Fix Vagrant snapshot issues
+
+### 1.18.5 / 2020-06-24
+* Allow Vagrant to connect to EL8+ hosts in FIPS mode
+* Add EL8 support to the SSG scans
+
+### 1.18.4 / 2020-03-31
+* Fix capturing error messages when inspec fails to generate results
+
+### 1.18.3 / 2020-02-24
+* Fix the Windows library loading location.
+  * No longer attempt to load windows libraries by default unless the system is
+    actually Windows
+
+### 1.18.2 / 2020-02-24
+
+* The previous location for loading the Windows libraries would not work in a
+  `:before` block. This moves it into its own module space.
+* Bump to the working version of beaker and beaker-puppet
+
+### 1.18.1 / 2020-02-12
+* Fix gemspec dependencies
+* Fix the windows library loading location
+
+### 1.18.0 / 2020-02-06
+* Update Windows support
+  * Add require beaker-windows and note installation of gem if missing
+  * Add geotrust global CA certificate in fix_eratta_on
+* Added convenience helper methods
+  * Add puppet_environment_path_on
+  * Add file_content_on which is multi-platform safe unlike the built-in
+    file_contents_on
+  * Add hiera_config_path_on
+  * Add get_hiera_config_on
+  * Add set_hiera_config_on
+
+### 1.17.1 / 2019-11-01
+* Only pull in the beaker rake tasks from the puppetlabs helpers
+
+### 1.17.0 / 2019-10-22
+* Allow users to perform exclusion filters on SSG results
+* Allow users to pass Arrays of items to match for SSG results
+
+### 1.16.2 / 2019-10-10
+* Pull latest inspec package now that the upstream bug is fixed
+
+### 1.16.1 / 2019-09-25
+* Remove debugging pry that was accidentally left in
+
+### 1.16.0 / 2019-09-23
+* Added a sosreport function to gather SOS Reports from EL systems
+
+### 1.15.2 / 2019-09-13
+* Fix an issue where the inspec reports were not processed properly
+
+### 1.15.1 / 2019-08-26
+* Ensure that any user on the SUT can use the RedHat entitlements
+
+### 1.15.0 / 2019-08-08
+* Add the ability to handle registration of Red Hat hosts with the RHN.
+
+### 1.14.6 / 2019-08-15
+* Add Windows client support to the beaker helpers functions
+  * Added an `is_windows?(sut)` function
+  * Work around issues with calling `sut.puppet` on Windows SUTs
+  * Update `copy_fixture_modules_to` to support Windows (slow copy)
+  * Add Windows support to `puppet_modulepath_on`
+
+### 1.14.5 / 2019-08-14
+* Update the CentOS SSG hooks to properly work with CentOS 6
+
+### 1.14.4 / 2019-07-26
+* Bump the version of Highline to 2.0+ due to bugs in the latest 1.X series
+
+### 1.14.3 / 2019-06-24
+* Add RPM-GPG-KEY-SIMP-6 to the SIMP dependencies repo created
+  by install_simp_repo.
+
+### 1.14.2 / 2019-05-16
+* Move the minimum supported puppet version to Puppet 5 since Puppet 4 has been
+  removed from the download servers completely. Beaker may re-add support for
+  the new location so not removing the mappings at this time.
+* Fixed a bug where a hash item was incorrect and not properly passing along
+  configuration items.
+
+### 1.14.1 / 2019-04-15
+* Handle license acceptance option needed for new versions of inspec.
+
+### 1.14.0 / 2019-04-08
+* Added function, install_simp_repo, to install the simp online repos.
+  The repos are defined in a hash in the function. All the repos
+  will be configured and enabled.   To disable one or more of them pass
+  in an array of names of the repos to disable.
+
+### 1.13.1 / 2019-02-02
+* Ensure that SUTs have an FQDN set and not just a short hostname
+* Work around issue where the SSG doesn't build the STIG for CentOS any longer.
+* Add a work around for getting the docker SUT ID due to breaking changes in
+  the beaker-docker gem
+
+### 1.13.0 / 2018-11-09
+* Make the SSG reporting consistent with the InSpec reporting
+  * Thanks to Liz Nemsick for the original result processing code
+
+### 1.12.2 / 2018-10-25
+* Skip most of fix_errata_on on windows platforms
+
+### 1.12.1 / 2018-10-24
+* Fall back to SSH file copies automatically when rsync does not work due to
+  test cases that affect ssh directly and that will cause new sessions to fail.
+
+### 1.12.0 / 2018-10-22
+* When using suites, allow users to loop through multiple specified nodesets as
+  a colon delimited list or loop through all nodesets by passing 'ALL'.
+* If 'ALL' is passed, the 'default' suite will be run first.
+
+### 1.11.3 / 2018-10-22
+* Made the inspec report less confusing overall by noting where checks are
+  overridden
+* Fix errors in the previous ssh key copy
+
+### 1.11.2 / 2018-10-11
+* Copy ssh keys in home directories to simp standard '/etc/ssh/local_keys/'
+  to avoid error when certain simp puppet modules are applied
+* Fix enable_fips_mode_on(), which no longer works on centos/7 vagrant boxes.
+
+### 1.11.1 / 2018-10-03
+* Deprecate the 'terminus' parameter in 'write_hieradata_to' and 'set_hieradata_on'
+* Add 'copy_hiera_data_to' method to replace the one from beaker-hiera
+* Add 'hiera_datadir' method to replace the one from beaker-hiera
+* Change InSpec to use the 'reporter' option instead of 'format'
+* Update the SSG to point to the new ComplianceAsCode repository
+
+### 1.11.0 / 2018-10-01
+* Add support for Beaker 4
+
+### 1.10.14 / 2018-08-01
+* Pinned `net-telnet` to `~> 0.1.1` for all releases due to dropping support
+  for Ruby less than 2.3 in `0.2.X`. This should be removed once we drop
+  support for Ruby 1.9 (late October 2018).
+
+### 1.10.13 / 2018-07-24
+* Update puppet to puppet-agent mapping table for puppet-agent 1.10.14
+
+### 1.10.12 / 2018-07-09
+* Forced all parallelization to `false` by default due to random issues with
+  Beaker
+
+### 1.10.11 / 2018-06-25
+* Pinned `fog-openstack` to `0.1.25` for all releases due to dropping support
+  for Ruby 1.9 in `0.1.26`. This should be removed once we drop support for
+  Ruby 1.9 (late October 2018)
+* Added removal of `.vendor` directory which was preventing successful
+  deployment status in Travis CI
+
+### 1.10.10 / 2018-06-22
+* Version bump due to being released without a git tag
+
+### 1.10.9 / 2018-06-22
+* Ensure that the SSG is built from the latest tag instead of master
+* Provide the option to pass a specific branch to the SSG builds
+* Pin the suite base directory off of the global base directory instead of
+  local to wherever the system happens to be at the time.
+
+### 1.10.8 / 2018-05-18
+* New env var BEAKER_no_fix_interfaces, set to skip the fix that brings up all
+  vagrant interfaces
+* Parallelized pre-test setup actions that are used across all hosts using `block_on`
+* Add runtime dependency on `highline` for the `inspec` reporting
+
+### 1.10.7 / 2018-05-11
+* Updated README
+* Changed acceptance tests to use `beaker:suites`
+* Removed all Puppet 5+ mappings and updated the install method to figure out
+  what to use based on the available gems so that everything is now consistent
+
+### 1.10.6 / 2018-05-07
+* Added Simp::BeakerHelpers.tmpname method to work around the removal of
+  Dir::Tmpname in Ruby 2.5
+
+### 1.10.5 / 2018-04-27
+* Fix issue with direct copy to/from docker containers
+* Add necessary package for SSG builds
+* Added the downloaded inspec_deps directory to the clean list
+
+### 1.10.4 / 2018-04-25
+* Fix Inspec report failures
+* Fix SSG build failures
+* Allow the SSG remediation acceptance test to fail
+
+### 1.10.3 / 2018-03-23
+* Avoid warnings when using `puppet config print`
+
+### 1.10.2 / 2018-03-04
+* Reimplemented `pluginsync_on` with a Puppet manifest to completely mimic
+  a native pluginsync
+  - Syncs _all_ assets (e.g., augeas lenses) instead of just the facts
+  - Simpler
+  - Much faster, especially with many modules or SUTs
+
+### 1.10.1 / 2018-02-13
+* Updated the Puppet version mapping list for Puppet 5
+* Fixed a bug in the way that the latest Puppet 5 version was being determined
+
+### 1.10.0 / 2018-01-23
+* Add support for Puppet 5
+  * Note: you need to set 'puppet_collection' to 'puppet5' to test Puppet 5 and
+    'aio' (or leave it out) to test Puppet less than 5
+* Fix support for passing the 'ALL' suite to run all suites
+* Updates per Rubocop
+
+* Ensure that `rsync` is not used once `fips` is enabled on the SUT
+  * If `fips` is enabled on the SUT, but not the running host, rsync
+    connections have a high likelihood of failing
+
+### 1.9.0 / 2018-01-01
+* Ensure that all host IP addresses get added to the internally generated PKI
+  keys as subjectAltNames. Kubernetes needs this and it does not hurt to have
+  in place for testing.
+
+### 1.8.10 / 2017-11-02
+* Fix bug in which dracut was not run on CentOS6, when dracut-fips was
+  installed for a FIPS-enabled test.

data/Gemfile

@@ -0,0 +1,51 @@
+# ------------------------------------------------------------------------------
+# NOTE: SIMP Puppet rake tasks support ruby 2.1.9
+# ------------------------------------------------------------------------------
+gem_sources = ENV.fetch('GEM_SERVERS','https://rubygems.org').split(/[, ]+/)
+
+gem_sources.each { |gem_source| source gem_source }
+
+# read dependencies in from the gemspec
+gemspec
+
+# mandatory gems
+gem 'bundler'
+gem 'rake'
+
+group :system_tests do
+  beaker_gem_options = ENV.fetch('BEAKER_GEM_OPTIONS', ['>= 4.17.0', '< 5.0.0'])
+
+  if "#{beaker_gem_options}".include?(':')
+    # Just pass in BEAKER_GEM_OPTIONS as a string that would represent the usual
+    # hash of options.
+    #
+    # Something like: BEAKER_GEM_OPTIONS=':git => "https://my.repo/beaker.git", :tag => "1.2.3"'
+    #
+    # No, this isn't robust, but it's not really an 'every day' sort of thing
+    # and safer than an `eval`
+    begin
+      gem 'beaker', Hash[
+        beaker_gem_options.split(',').map do |x| # Split passed options on k/v pairs
+          x.gsub('"', '').strip.split(/:\s|\s+=>\s+/) # Allow for either format hash keys
+        end.map do |k,v|
+          [
+            k.delete(':').to_sym, # Convert all keys to symbols
+            v.strip
+          ]
+        end
+      ] # Convert the whole thing to a valid Hash
+    rescue => e
+      raise "Invalid BEAKER_GEM_OPTIONS: '#{beaker_gem_options}' => '#{e}'"
+    end
+  else
+    gem 'beaker', beaker_gem_options
+  end
+
+  gem 'beaker-rspec'
+  gem 'beaker-windows'
+  gem 'net-ssh'
+  gem 'puppet', ENV.fetch('PUPPET_VERSION', '~> 5.0')
+  gem 'puppetlabs_spec_helper'
+  gem 'rubocop'
+  gem 'rubocop-rspec'
+end

data/LICENSE

@@ -0,0 +1,27 @@
+rubygem-simp-beaker-helpers - methods to help Beaker scaffolding SIMP tests
+
+--
+
+Per Section 105 of the Copyright Act of 1976, these works are not entitled to
+domestic copyright protection under US Federal law.
+
+The US Government retains the right to pursue copyright protections outside of
+the United States.
+
+The United States Government has unlimited rights in this software and all
+derivatives thereof, pursuant to the contracts under which it was developed and
+the License under which it falls.
+
+---
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,543 @@
+# simp-beaker-helpers
+
+Methods to assist beaker acceptance tests for SIMP.
+
+#### Table of Contents
+
+<!-- vim-markdown-toc GFM -->
+
+* [Overview](#overview)
+* [Setup](#setup)
+  * [Beginning with simp-beaker-helpers](#beginning-with-simp-beaker-helpers)
+* [Rake Tasks](#rake-tasks)
+  * [`rake beaker:suites`](#rake-beakersuites)
+  * [Suite Execution](#suite-execution)
+    * [Environment Variables](#environment-variables)
+    * [Global Suite Configuration](#global-suite-configuration)
+      * [Supported Config:](#supported-config)
+    * [Individual Suite Configuration](#individual-suite-configuration)
+      * [Supported Config:](#supported-config-1)
+* [Nodeset Enhancements](#nodeset-enhancements)
+  * [YUM Repo Support](#yum-repo-support)
+* [Methods](#methods)
+    * [`copy_to`](#copy_to)
+    * [`copy_fixture_modules_to`](#copy_fixture_modules_to)
+    * [`fix_errata_on`](#fix_errata_on)
+    * [`run_fake_pki_ca_on`](#run_fake_pki_ca_on)
+    * [`copy_pki_to`](#copy_pki_to)
+    * [`copy_keydist_to`](#copy_keydist_to)
+    * [`pfact_on`](#pfact_on)
+    * [`pluginsync_on`](#pluginsync_on)
+    * [`write_hieradata_to`](#write_hieradata_to)
+    * [`set_hieradata_on`](#set_hieradata_on)
+    * [`clear_temp_hieradata`](#clear_temp_hieradata)
+    * [`latest_puppet_agent_version_for(puppet_version)`](#latest_puppet_agent_version_forpuppet_version)
+    * [`install_puppet`](#install_puppet)
+* [Environment variables](#environment-variables-1)
+    * [`BEAKER_fips`](#beaker_fips)
+    * [`BEAKER_fips_module_version`](#beaker_fips_module_version)
+    * [`BEAKER_spec_prep`](#beaker_spec_prep)
+    * [`BEAKER_SIMP_parallel`](#beaker_simp_parallel)
+    * [`BEAKER_stringify_facts`](#beaker_stringify_facts)
+    * [`BEAKER_use_fixtures_dir_for_modules`](#beaker_use_fixtures_dir_for_modules)
+    * [`BEAKER_no_fix_interfaces`](#beaker_no_fix_interfaces)
+    * [PUPPET_VERSION](#puppet_version)
+    * [BEAKER_RHSM_USER](#beaker_rhsm_user)
+    * [BEAKER_RHSM_PASS](#beaker_rhsm_pass)
+    * [BEAKER_inspec_version](#beaker_inspec_version)
+* [Examples](#examples)
+  * [Prep OS, Generate and copy PKI certs to each SUT](#prep-os-generate-and-copy-pki-certs-to-each-sut)
+  * [Specify the version of Puppet to run in the SUTs](#specify-the-version-of-puppet-to-run-in-the-suts)
+* [Experimental Features](#experimental-features)
+  * [Snapshot Support](#snapshot-support)
+    * [Running Tests with Snapshots](#running-tests-with-snapshots)
+    * [Adding Snapshots to your Tests](#adding-snapshots-to-your-tests)
+      * [Taking a Snapshot](#taking-a-snapshot)
+      * [Base Snapshots](#base-snapshots)
+      * [Restoring a Snapshot](#restoring-a-snapshot)
+      * [Listing Snapshots](#listing-snapshots)
+* [License](#license)
+
+<!-- vim-markdown-toc -->
+
+## Overview
+
+## Setup
+
+### Beginning with simp-beaker-helpers
+
+Add this to your project's `Gemfile`:
+
+```ruby
+gem 'simp-beaker-helpers'
+```
+
+Add this to your project's `spec/spec_helper_acceptance.rb`:
+```ruby
+require 'simp/beaker_helpers'
+include Simp::BeakerHelpers
+```
+
+## Rake Tasks
+
+New `rake` tasks are available to help you use `beaker` more effectively.
+
+These can be included in your `Rakefile` by adding the following:
+
+```
+require 'simp/rake/beaker'
+Simp::Rake::Beaker.new(File.dirname(__FILE__))
+```
+
+### `rake beaker:suites`
+
+The 'beaker:suites' rake task provides the ability to run isolated test sets
+with a full reset of the Beaker environment.
+
+These are entirely isolated runs of Beaker and have been designed to be used
+for situations where you need to eliminate all of the cruft from your previous
+runs to perform a new type of test.
+
+### Suite Execution
+
+By default the only suite that will be executed is `default`.  Since each suite
+is executed in a new environment, spin up can take a lot of time. Therefore,
+the default is to only run the default suite.
+
+If there is a suite where the metadata contains `default_run` set to the
+Boolean `true`, then that suite will be part of the default suite execution.
+
+You can run all suites by setting the passed suite name to `ALL` (case
+sensitive).
+
+#### Environment Variables
+
+* BEAKER_suite_runall
+  * Run all Suites
+
+* BEAKER_suite_basedir
+  * The base directory where suites will be defined
+  * Default: spec/acceptance
+
+#### Global Suite Configuration
+
+A file `config.yml` can be placed in the `suites` directory to control certain
+aspects of the suite run.
+
+##### Supported Config:
+
+```yaml
+---
+# Fail the entire suite at the first failure
+'fail_fast' : <true|false> => Default: true
+```
+
+#### Individual Suite Configuration
+
+Each suite may contain a YAML file, metadata.yml, which will be used to provide
+information to the suite of tests.
+
+##### Supported Config:
+
+```yaml
+---
+'name' : '<User friendly name for the suite>'
+
+# Run this suite by default
+'default_run' : <true|false> => Default: false
+```
+
+## Nodeset Enhancements
+
+### YUM Repo Support
+
+Nodes in your nodesets will create YUM repository entries according to the
+following Hash:
+
+```yaml
+---
+yum_repos:
+   <repo_name>:
+     <yum_resource_parameter>: <value>
+```
+
+The `baseurl` and `gpgkey` parameters can also take an Array if you need to
+point at more than one location.
+
+This would look like the following:
+
+```yaml
+---
+yum_repos:
+   <repo_name>:
+     baseurl:
+       - http://some.random.host
+       - https://some.other.random.host
+     gpgkey:
+       - https://my.gpg.host
+       - https://my.other.gpg.host
+```
+
+## Methods
+
+#### `copy_to`
+
+Abstracts copying files and directories in the most efficient manner possible.
+
+* If your system is a ``docker`` container it uses ``docker cp``
+* If your system is anything else:
+  * Attempts to use ``rsync`` if it is present on both sides
+  * Falls back to ``scp``
+
+All copy semantics are consistent with what you would expect from ``scp_to``
+
+#### `copy_fixture_modules_to`
+
+Copies the local fixture modules (under `spec/fixtures/modules`) onto a list of
+SUTs.
+
+```ruby
+copy_fixture_modules_to( suts = hosts, opts = {} )
+```
+  - **`suts`**   = _(Array,String)_ list of SUTs to copy modules to
+  - **`opts`**   = _(Hash)_ Options passed on to `copy_module_to()` for each SUT
+
+By default, this will copy modules to the first path listed in each SUT's
+`modulepath` and simulate a pluginsync so the Beaker DSL's `facter_on` will
+still work.
+
+If you need to use a non-default module path:
+```ruby
+# WARNING: this will use the same :target_module_dir for each SUT
+copy_fixture_modules_to( hosts, {
+   :target_module_dir => '/path/to/my/modules',
+})
+```
+
+If you want to disable pluginsync:
+```ruby
+# WARNING: `fact_on` will not see custom facts
+copy_fixture_modules_to( hosts, {
+   :pluginsync => false
+})
+```
+
+#### `fix_errata_on`
+
+Apply any OS fixes we need on each SUT
+`fix_errata_on( suts = hosts )`
+
+
+#### `run_fake_pki_ca_on`
+
+Generate a fake openssl CA + certs for each host on a given SUT and copy the
+files back to a local directory.
+
+**NOTE:** this needs to generate everything inside an SUT.  It is assumed the
+SUT will have the appropriate openssl in its environment.
+
+`run_fake_pki_ca_on( ca_sut = master, suts = hosts, local_dir = '' )`
+
+ - **`ca_sut`**    = the SUT to generate the CA & certs on
+ - **`suts`**      = list of SUTs to generate certs for
+ - **`local_dir`** = local path where the CA+cert directory tree should copied back to
+
+#### `copy_pki_to`
+
+Copy a single SUT's PKI certs (with cacerts) onto the SUT.  This simulates the result of `pki::copy` without requiring a full master and `simp-pki` module.
+
+The directory structure copied to the SUT is:
+```
+  SUT_BASE_DIR/
+              pki/
+                  cacerts/cacerts.pem
+                  public/fdqn.pub
+                  private/fdqn.pem
+
+```
+
+`copy_pki_to(sut, local_pki_dir, sut_base_dir = '/etc/pki/simp-testing')`
+
+
+#### `copy_keydist_to`
+
+Copy a CA keydist/ directory of CA+host certs into an SUT.
+
+This simulates the output of FakeCA's `gencerts_nopass.sh` into `keydist/` and is useful for constructing a Puppet master SUT that will distribute PKI keys via agent runs.
+
+`copy_keydist_to( ca_sut = master )`
+
+
+#### `pfact_on`
+
+Look up a fact on a given SUT using the `puppet fact` face.  This honors whatever facter-related settings the SUT's Puppet installation has been configured to use (i.e., `factpath`, `stringify_facts`, etc).
+
+`pfact_on( sut, fact_name )`
+
+
+#### `pluginsync_on`
+
+Simulates a `pluginsync` (useful for deploying custom facts) on given SUTs.
+
+`pluginsync_on( suts = hosts )`
+
+#### `write_hieradata_to`
+
+Writes a YAML file in the Hiera :datadir of a Beaker::Host.
+
+**NOTE**: This is useless unless Hiera is configured to use the data file.
+`Beaker::DSL::Helpers::Hiera#write_hiera_config_on` from [beaker-hiera](https://github.com/puppetlabs/beaker-hiera) may be used to configure Hiera.
+
+`write_hieradata_to(host, hieradata, terminus = 'default')`
+
+ - **`host`**      = _(Array,String,Symbol)_ One or more hosts to act upon
+ - **`hieradata`** = _(Hash)_ The full hiera data structure to write to the system
+ - **`terminus`**  = _(String)_ The file basename minus the file extension in which to write the Hiera data
+
+#### `set_hieradata_on`
+
+Writes a YAML file in the Hiera :datdir of a Beaker::Host, then configures the host to use that file exclusively.
+
+**NOTE**: This is authoritative; you cannot mix this with other Hiera data sources.
+
+`set_hieradata_on(host, hieradata, terminus = 'default')`
+
+ - **`host`**      = _(Array,String,Symbol)_ One or more hosts to act upon
+ - **`hieradata`** = _(Hash)_ The full hiera data structure to write to the system
+ - **`terminus`**  = _(String)_ The file basename minus the file extension in which to write the Hiera data
+
+####  `clear_temp_hieradata`
+
+Clean up all temporary hiera data files; meant to be called from `after(:all)`
+
+`clear_temp_hieradata`
+
+#### `latest_puppet_agent_version_for(puppet_version)`
+
+Finds the latest `puppet-agent` version based on the passed gem version and can
+accept the usual Gem comparison syntax (e.g., '4.0', '=4.2', '~> 4.3.1', '5')
+
+Returns the `puppet-agent` package version or `nil` if not found.
+
+#### `install_puppet`
+
+Performs an assessment of all set parameters and installs the correct
+`puppet-agent` based on those parameters based on the following logic.
+
+If the environment variable `BEAKER_PUPPET_AGENT_VERSION` or
+`PUPPET_INSTALL_VERSION` or `PUPPET_VERSION` is set, it will use that value
+to determine the `puppet-agent` version to install.
+
+If it is unable to determine the `puppet-agent` version from any `*VERSION`
+environment variables and the environment variable `BEAKER_PUPPET_COLLECTION`
+is set, it will use this to determine which puppet collection to install from.
+(Presently, this only works with Puppet 5.x and is set as `puppet5`.)
+
+If it cannot determinte the `puppet-agent` version from any environment
+variables, it will default the version to the value of
+Simp::BeakerHelpers::DEFAULT_PUPPET_AGENT_VERSION, which is currently '1.10.4'.
+
+## Environment variables
+
+#### `BEAKER_fips`
+
+_(Default: `no`)_ When set to `yes`, Beaker will enable [FIPS mode](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security_Guide/sect-Security_Guide-Federal_Standards_And_Regulations-Federal_Information_Processing_Standard.html) on all SUTs before running tests.
+
+**NOTE:** FIPS mode is only enabled on RedHat family hosts.
+
+#### `BEAKER_fips_module_version`
+
+_(Default: unset)_ Set to a version of the simp-fips Puppet module released
+to Puppet Forge, when you want to specify the version of that module used to
+implement enable FIPS. When unset, the latest version is used.
+
+**NOTE:** This has no effect if the `simp-fips` module is already included in your fixtures.yml
+
+#### `BEAKER_spec_prep`
+
+_(Default: `yes`)_  Ensures that each fixture module is present under
+`spec/fixtures/modules`.  If any fixture modules are missing, it will run `rake
+spec_prep` to populate the missing modules using `.fixtures.yml`.  Note that
+this will _not_ update modules that are already present under
+`spec/fixtures/modules`.
+
+#### `BEAKER_SIMP_parallel`
+
+_(Default: `no`)_  Execute each SIMP host setup method such as
+`Simp::BeakerHelpers::copy_fixure_modules_to` and `Simp::BeakerHelpers::fix_errata_on`
+on all hosts in a node set in parallel. Uses parallelization provided by Beaker.
+
+**NOTE:** Beaker's parallelization capability does not always work, so a word
+to the wise is sufficient.
+
+#### `BEAKER_stringify_facts`
+#### `BEAKER_use_fixtures_dir_for_modules`
+
+#### `BEAKER_no_fix_interfaces`
+
+Set to skip code that makes sure all interfaces are up
+
+#### PUPPET_VERSION
+
+The `PUPPET_VERSION` environment variable will install the latest
+`puppet-agent` package that provides that version of Puppet.  This honors
+`Gemfile`-style expressions like `"~> 4.8.0"`
+
+`BEAKER_PUPPET_AGENT_VERSION` and `PUPPET_INSTALL_VERSION` are synonyms of
+`PUPPET_VERSION`.
+
+#### BEAKER_RHSM_USER
+
+The username to use with Red Hat Subscription Manager when dealing with a RHEL host.
+
+Will not be output to the screen.
+
+#### BEAKER_RHSM_PASS
+
+The password to use with Red Hat Subscription Manager when dealing with a RHEL host.
+
+Will not be output to the screen.
+
+Note:  When using Subscription Manager, make sure your nodeset has the setting validation: false.   Otherwise Beaker:Rspec
+might try to install packages before subscription manager is configured.
+
+#### BEAKER_inspec_version
+
+The version of InSpec to use when running inspec tests. Currently hard-coded to
+`4.16.14` due to a bug introduced in `4.16.15`.
+
+Let to 'latest' to use the latest available in the upstream repos.
+
+## Examples
+
+### Prep OS, Generate and copy PKI certs to each SUT
+This pattern serves to prepare component modules that use PKI
+
+```ruby
+# spec/spec_acceptance_helpers.rb
+require 'beaker-rspec'
+require 'tmpdir'
+require 'simp/beaker_helpers'
+include Simp::BeakerHelpers
+
+unless ENV['BEAKER_provision'] == 'no'
+  hosts.each do |host|
+    # Install Puppet
+    if host.is_pe?
+      install_pe
+    else
+      install_puppet
+    end
+  end
+end
+
+
+RSpec.configure do |c|
+  # ensure that environment OS is ready on each host
+  fix_errata_on hosts
+
+  # Readable test descriptions
+  c.formatter = :documentation
+
+  # Configure all nodes in nodeset
+  c.before :suite do
+    begin
+      # Install modules and dependencies from spec/fixtures/modules
+      copy_fixture_modules_to( hosts )
+      Dir.mktmpdir do |cert_dir|
+        run_fake_pki_ca_on( default, hosts, cert_dir )
+        hosts.each{ |host| copy_pki_to( host, cert_dir, '/etc/pki/simp-testing' )}
+      end
+    rescue StandardError, ScriptError => e
+      require 'pry'; binding.pry if ENV['PRY']
+    end
+  end
+end
+```
+
+### Specify the version of Puppet to run in the SUTs
+
+```bash
+# puppet-agent 1.8.3 will be installed in VMs
+PUPPET_VERSION="~> 4.8.0" bundle exec rake beaker:suites
+
+# puppet-agent 1.9.2 will be installed in VMs
+PUPPET_INSTALL_VERSION=1.9.2 bundle exec rake beaker:suites
+
+# The latest puppet 5 will be installed in VMs
+PUPPET_VERSION="5" bundle exec rake beaker:suites
+
+# puppet-agent 1.10.4 will be installed in VMs
+bundle exec rake beaker:suites
+```
+
+## Experimental Features
+
+### Snapshot Support
+
+Rudimentary support for snapshotting VMs has been added. This currently only
+works for local `vagrant` systems and relies on the underlying `vagrant
+snapshot` command working for the underlying hypervisor. VirtualBox is highly
+recommended and `libvirt` is known to not work due to limitiations in
+`vagrant`.
+
+This was added to attempt to be able to restart tests from given checkpoints
+that encompass extremely long running test segments. This is particularly
+relevant when you are trying to set up a large support infrastructure but need
+to debug later stages of your tests over time.
+
+#### Running Tests with Snapshots
+
+To enable snapshots during your initial test runs, run your test as follows:
+
+```bash
+BEAKER_destroy=no BEAKER_simp_snapshot=yes rake beaker:suites
+```
+
+Then, on subsequent runs, run your test as follows:
+
+```bash
+BEAKER_provision=no BEAKER_destroy=no BEAKER_simp_snapshot=yes rake beaker:suites
+```
+#### Adding Snapshots to your Tests
+
+The following demonstrates the general idea behind using snapshots. Note, the
+decision to directly call the module methods was made to ensure that people
+knew explicitly when this capability was being called since it affects the
+underlying OS configuration.
+
+##### Taking a Snapshot
+
+`Simp::BeakerHelpers::Snapshot.save(sut, '<name of snapshot>')` will save a
+snapshot with the given name. If the snapshot already exists, it will be
+forceably overwritten.
+
+
+##### Base Snapshots
+
+Any time a snapshot is saved, if an initial base snapshot doesn't exist, one
+will be created. You can restore back to the base snapshot using
+`Simp::BeakerHelpers::Snapshot.restore_to_base(sut)`.
+
+These are specifically created to ensure that we don't run into issues with
+trying to remove the parent of all snapshots since some hypervisors do not
+allow this.
+
+##### Restoring a Snapshot
+
+`Simp::BeakerHelpers::Snapshot.restore(sut, '<name of snapshot>)` will restore
+to the named snapshot.
+
+Attempting to restore to a snapshot that doesn't exist is an error.
+
+##### Listing Snapshots
+
+`Simp::BeakerHelpers::Snapshot.list(sut)` will return an Array of all snapshot
+names for that system.
+
+`Simp::BeakerHelpers::Snapshot.exist?(sut, '<name of snapshot>')` will return a
+Boolean based on whether or not the snapshot with the given name is present on
+the system.
+
+## License
+See [LICENSE](LICENSE)