Table of Contents

• Description
  • This is a SIMP module
• Setup
  • What simp_bolt affects
  • Beginning with simp_bolt
• Usage
• Reference
• Limitations
• Development
  • Acceptance tests

+----------------------------------------------------------------+
| WARNING: This is currently an **EXPERIMENTAL** module. Things  |
| may change drastically, and in breaking ways, without notice!  |
+----------------------------------------------------------------+

Description

This module manages Puppet Bolt. It installs and configures the necessary packages on systems specified as Bolt controllers and configures accounts as specified on both controllers and target systems to be managed with Bolt.

Bolt is an open source task runner developed by Puppet that permits automation on an as-needed basis. This means that all actions are initiated from the Bolt server, eliminating reliance upon remote agent software for task execution. More complex tasks can be implemented using Puppet modules, which does require the installation of an agent for executions, but all tasks are still initiated from the Bolt server.

See REFERENCE.md for more details.

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they may be submitted to our bug tracker.

This module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:

• When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.
• If used independently, all SIMP-managed security subsystems are disabled by default and must be explicitly opted into by administrators. Please review the parameters in simp/simp_options for details.

Setup

What simp_bolt affects

The simp_bolt module can create a local user account on target systems, simp_bolt by default, that has the ability to su to the root user on the system. Every effort has been taken to implement this as securely as possible by including options to manage user security settings.

Due to the potential to lock out the account, the root user is not permitted to be specified as the target user account. The target user can be restricted to only login via ssh from specified hosts and also limited to only one login session at a time for the execution of tasks. Multiple ssh keys can be specified for the target user to permit different user accounts on the controller to run bolt and provide a degree of attestation.

The target user's home directory defaults to /var/local/simp_bolt. This location is used for temporary files on the target systems. This can be configured to a different location if desired.

Bolt logs are written to /var/log/puppetlabs/bolt by default, and the directory structure will be created if necessary. This can also be configured to an alternate location.

By default, Bolt collects various analytics associated with a random UUID, non-identifiable user, details are available at Analytics data collection . The simp_bolt module overrides and disables this by default, but it can be re-enabled in Hiera.

The simp_bolt module optionally leverages the simp/pam and simp/sudo modules for implementation and will prompt for their installation if you attempt to use items that require them.

Beginning with simp_bolt

To configure a system as a Bolt controller, include simp_bolt and specify the system as a bolt_controller in Hiera.

simp_bolt::bolt_controller: true

To configure a system that will be managed by Bolt, simply include simp_bolt and specify the system as a bolt_target in Hiera.

simp_bolt::bolt_target: true

Additionally, either a password or SSH key must be specified for Bolt to SSH to remote systems. Both can be specified in Hiera. Passwords should be in passwd-compatible salted hash form.

simp_bolt::user::password: '$6$0BVLUF[...]16OtkdiY1'
simp_bolt::user::ssh_authorized_key: 'AAAAB3Nza[...]qXfdaQ=='

Usage

Once the simp_bolt module has been applied to a server and one or more target systems, Bolt is ready for use. All commands provided assume you have changed users to the appropriate account using su on the Bolt server system. Entering the command bolt by itself will display the help information.

To run a remote command, su to the bolt user and execute bolt command run <COMMAND> --nodes <NODE NAME(S)> --password --sudo-password. By omitting values for password and sudo-password from the command line, the user will be prompted to enter the password so it will not be displayed on the command line. Commands can be run on multiple nodes by specifying additional values, using commas to separate entries.

To view available modules, su to the bolt user and execute bolt puppetfile show-modules. Additional modules already on the system can be added by specifying the full path to their parent directory in Hiera:

simp_bolt::config::modulepath: /path/to/modules

To apply an existing manifest, su to the bolt user and execute bolt apply <manifest> --nodes <NODE NAME(S)> --password --sudo-password.

Reference

Please for refer to the online Bolt documentation for the most up to date documentation.

Limitations

SIMP Puppet modules are generally intended for use on Red Hat Enterprise Linux and compatible distributions, such as CentOS. Please see the metadata.json file for the most up-to-date list of supported operating systems, Puppet versions, and module dependencies.

Development

Please read our Contribution Guide.

Acceptance tests

This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests run the following:

bundle install
bundle exec rake beaker:suites

Please refer to the SIMP Beaker Helpers documentation for more information.

Reference

Table of Contents

Classes

• simp_bolt: Installs and configures Puppet Bolt for use within the SIMP enviroment
• simp_bolt::controller: Installs and configures Puppet Bolt for use within the SIMP enviroment
• simp_bolt::controller::config: Set the global configuration and transport options for Bolt.
• simp_bolt::controller::install: This class is called from simp_bolt for install.
• simp_bolt::target: Configure a system to be managed by Puppet Bolt
• simp_bolt::target::user: Configure a 'simp_bolt' system user and login capabilities

Classes

simp_bolt

This class will not do anything on the target system by default. You must opt-in to adding either the controller or the target configuration.

Parameters

The following parameters are available in the simp_bolt class.

target_user_name

Data type: String[1]

The username of the account to use on target systems

Default value: 'simp_bolt'

target_user_home

Data type: Stdlib::Unixpath

The full path to the user's home directory on target systems

Default value: "/var/local/${target_user_name}"

target_sudo_user

Data type: Optional[String[1]]

The user that the username user may escalate to on target systems

Default value: 'root'

bolt_controller

Data type: Boolean

Install and configure Puppet Bolt.

• Configuration specifics should be managed via the simp_bolt::controller parameters.

Default value: false

bolt_target

Data type: Boolean

Configure the system as a target for Bolt management

• Configuration specifics should be managed via the simp_bolt::target parameters.

Default value: false

package_name

Data type: String

The name of the Puppet Bolt rpm package

Default value: 'puppet-bolt'

simp_bolt::controller

Installs and configures Puppet Bolt for use within the SIMP enviroment

Parameters

The following parameters are available in the simp_bolt::controller class.

local_user_name

Data type: Optional[String[1]]

The username of the local user account to launch bolt commands

• NOTE: Ensure that this user is local to the host since Puppet will be managing files in the user's home directory.

Default value: undef

local_group_name

Data type: Optional[String[1]]

The default group name of the local user account

Default value: $local_user_name

local_user_home

Data type: Optional[Stdlib::Unixpath]

The full path to the local user's home directory

Default value: undef

simp_bolt::controller::config

NOTE: THIS IS A PRIVATE CLASS

Addtional details on the options can be found at https://puppet.com/docs/bolt/latest/bolt_configuration_options.html.

Parameters

The following parameters are available in the simp_bolt::controller::config class.

local_group

Data type: Optional[String[1]]

The local group to be used for file permissions associated with the local_user account. The default is the $username account specified in the user.pp manifest.

Default value: getvar(simp_bolt::controller::local_group_name)

local_user_home

The home directory of the local account to be used for running Bolt. The default is the $home directory for the account specified in the user.pp manifest.

local_user

Data type: Optional[String[1]]

The local account to be used for running Bolt. The default is the $username account specified in the user.pp manifest.

Default value: getvar(simp_bolt::controller::local_user_name)

config_hash

Data type: Optional[Hash]

If specified, will be passed to the to_yaml function and output at the entire configuation of the bolt.yaml configuation file.

• No further options will be honored if this is specified

Default value: undef

color

Data type: Boolean

Whether to use colored output when printing messages to the console. By default, in Bolt, this is true.

Default value: true

concurrency

Data type: Optional[Integer[0]]

The number of threads to use when executing on remote nodes. By default, in Bolt, this is 100.

Default value: undef

default_transport

Data type: Simp_bolt::Transport

The default transport to use when not specified in the URL or inventory.

Default value: 'ssh'

disable_analytics

Data type: Boolean

Disable all vendor 'phone-home' mechanics in Bolt.

Default value: true

format

Data type: Optional[Enum['human','json']]

The format to use when printing results; either human or json. By default, in Bolt, this is human.

Default value: undef

hiera_config

Data type: Optional[String[1]]

The path to the Hiera config file. By default, in Bolt, this is hiera.yaml in the Bolt project directory at ~/.puppetlabs/bolt.

Default value: undef

inventoryfile

Data type: Optional[String[1]]

Path to a structured data inventory file used to refer to groups of nodes on the command line and from plans. By default, in Bolt, this is inventory.yaml in the Bolt project directory at ~/.puppetlabs/bolt.

Default value: undef

log_console_level

Data type: Simp_bolt::LogLevel

The type of information to display on the console. Valid options are debug, info, notice, warn, and error. The default is info.

Default value: 'info'

log_file

Data type: Stdlib::Unixpath

The path and name of the log file.

Default value: '/var/log/puppetlabs/bolt/bolt.log'

log_file_level

Data type: Simp_bolt::LogLevel

The type of information to record in the log file. Valid options are debug, info, notice, warn, and error. By default in Bolt this is info.

Default value: 'info'

log_file_append

Data type: Boolean

Add output to an existing log file. By default in Bolt this is true.

Default value: false

modulepath

Data type: Optional[String[1]]

The module path for loading tasks and plan code, formatted as a string containing a list of directories. The first directory listed will be the default for downloaded modules. By default, in Bolt, this is "modules:site-modules:site" within the Bolt project directory in ~/.puppetlabs/bolt.

Default value: undef

local_home

Data type: Stdlib::Unixpath

Default value: pick(getvar(simp_bolt::controller::local_user_home), '/var/local/simp_bolt')

transport_options

Data type: Hash[Simp_bolt::Transport, Hash]

Default value: { 'ssh' => { 'tmpdir' => $simp_bolt::target_user_home, 'user' => $simp_bolt::target_user_name, 'run-as' => getvar(simp_bolt::target_sudo_user) }.delete_undef_values }

simp_bolt::controller::install

NOTE: THIS IS A PRIVATE CLASS

simp_bolt::target

Configure a system to be managed by Puppet Bolt

Parameters

The following parameters are available in the simp_bolt::target class.

create_user

Data type: Boolean

Create the user on the target system

Default value: false

user_name

Data type: String[1]

The username to use for remote access

• Has no effect if $create_user is false

Default value: $simp_bolt::target_user_name

disallowed_users

Data type: Array[String[1]]

Users that may not be used for the remote bolt login user

Default value: ['root']

user_password

Data type: Optional[String[8]]

The password for the user in passwd-compatible salted hash form

• Has no effect if $create_user is false

Default value: undef

user_home

Data type: Stdlib::Unixpath

The full path to the user's home directory

• Has no effect if $create_user is false

Default value: $simp_bolt::target_user_home

user_uid

Data type: Integer[500]

The UID of the user

• Has no effect if $create_user is false

Default value: 1779

user_gid

Data type: Integer[500]

The GID of the user

• Has no effect if $create_user is false

Default value: $user_uid

user_ssh_authorized_keys

Data type: Optional[Array[String[1]]]

The SSH public key for authorized Bolt users

• See the native ssh_authorized_key resource definition for details

Default value: undef

user_ssh_authorized_key_type

Data type: String[1]

The SSH public key type

• See the native ssh_authorized_key resource definition for details

Default value: 'ssh-rsa'

user_sudo_user

Data type: Optional[String[1]]

The user that the username user may escalate to

If set to undef, will not manage sudo settings on the target system for this user.

Default value: getvar(simp_bolt::target_sudo_user)

user_sudo_password_required

Data type: Boolean

Require password for user to sudo

Default value: false

user_sudo_commands

Data type: Array[String[1],1]

The commands that the username user is allowed to execute via sudo as one of the allowed users

Default value: ['ALL']

user_allowed_from

Data type: Array[String[1]]

The pam_access compatible locations that the user will be logging in from

• Set to ['ALL'] to allow from any location
• If empty, will disable the use of pam_access for this user

Default value: [pick(fact('puppet_server'), 'LOCAL')]

user_max_logins

Data type: Optional[Integer[1]]

The pam_limits restricting the number of concurrent sessions permitted for username

If set to undef, will not restrict the maximum number of logins for the user

Default value: 2

simp_bolt::target::user

NOTE: THIS IS A PRIVATE CLASS**

Parameters

The following parameters are available in the simp_bolt::target::user class.

create

Data type: Boolean

Create the user on the target system

Default value: $simp_bolt::target::create_user

username

Data type: String

The username to use for remote access

Default value: $simp_bolt::target::user_name

password

Data type: Optional[String[8]]

The password for the user in passwd-compatible salted hash form

Default value: getvar(simp_bolt::target::user_password)

home

Data type: Stdlib::Unixpath

The full path to the user's home directory

Default value: $simp_bolt::target::user_home

uid

Data type: Integer

The UID of the user

Default value: $simp_bolt::target::user_uid

gid

Data type: Integer

The GID of the user

Default value: $simp_bolt::target::user_gid

ssh_authorized_key

The SSH public key for the user

• See the native ssh_authorized_key resource definition for details

ssh_authorized_key_type

Data type: String[1]

The SSH public key type

• See the native ssh_authorized_key resource definition for details

Default value: $simp_bolt::target::user_ssh_authorized_key_type

sudo_users

The users that the username user may escalate to

sudo_password_required

Data type: Boolean

Require password for user to sudo

Default value: $simp_bolt::target::user_sudo_password_required

sudo_commands

Data type: Array[String[1]]

The commands that the username user is allowed to execute via sudo as one of the allowed users

Default value: $simp_bolt::target::user_sudo_commands

allowed_from

Data type: Array[String[1]]

The pam_access compatible locations that the user will be logging in from

• Set to ['ALL'] to allow from any location

Default value: $simp_bolt::target::user_allowed_from

max_logins

Data type: Optional[Integer[1]]

The pam_limits restricting the number of concurrent sessions permitted for username

Default value: getvar(simp_bolt::target::user_max_logins)

ssh_authorized_keys

Data type: Optional[Array[String[1]]]

Default value: getvar(simp_bolt::target::user_ssh_authorized_keys)

sudo_user

Data type: Optional[String[1]]

Default value: getvar(simp_bolt::target::user_sudo_user)

• Tue Jul 02 2019 Trevor Vaughan tvaughan@onyxpoint.com - 0.1.1

• Updated README.md
• Added REFERENCE.md

• Fri Jun 21 2019 Michael Morrone michael.morrone@onyxpoint.com - 0.1.0

• Initial commit.
• Install and configure Puppet Bolt.
• Added Hiera configuration.
• Added acceptance test for deploying a puppet module.