+----------------------------------------------------------------+
| WARNING: This is currently an **EXPERIMENTAL** module. Things |
| may change drastically, and in breaking ways, without notice! |
+----------------------------------------------------------------+
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 controller, 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 controller.
See REFERENCE.md for more details.
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.
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.
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_keys: 'AAAAB3Nza[...]qXfdaQ=='
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 controller 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 install puppet-agent
on target nodes via Bolt
, utilize the included puppet-agent
install plan and execute
bolt plan run simp_bolt::painstall --nodes <NODE NAME(S)> --password --sudo-password
.
To apply an existing manifest, su
to the bolt user and execute
bolt apply <manifest> --nodes <NODE NAME(S)> --password --sudo-password
.
Please for refer to the online Bolt documentation for the most up to date documentation.
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.
Please read our Contribution Guide.
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.