Bolt

Bolt is a Ruby command-line tool for executing commands, scripts, and tasks on remote systems using SSH and WinRM.

• Executes commands on remote *nix and Windows systems.
• Distributes and execute scripts, such as Bash, PowerShell, Python.
• Scales to more than 1000 concurrent connections.
• Supports industry standard protocols (SSH/SCP, WinRM/PSRP) and authentication methods (password, publickey).

Supported platforms

• Linux, OSX, Windows
• Ruby 2.0+

For complete usage and installation details, see the Puppet Bolt docs. For contribution information, including alternate installation methods and running from source, see CONTRIBUTING.md.

Installation

On *nix

Bolt depends on gems containing native extensions. To install Bolt on *nix platforms, you must also install a GNU Compiler Collection (GCC) compiler and related dependencies.

1. Install the dependencies for your platform.

   • On CentOS 7 or Red Hat Enterprise Linux 7, run yum install -y make gcc ruby-devel
   • On Fedora 25, run dnf install -y make gcc redhat-rpm-config ruby-devel rubygem-rdoc
   • On Debian 9 or Ubuntu 16.04, run apt-get install -y make gcc ruby-dev
   • On Mac OS X, run xcode-select --install, and then accept the xcode license by running xcodebuild -license accept

2. Install Bolt as a gem by running gem install bolt

On Windows

Install Bolt and its dependencies on Windows systems.

To install and use Bolt on Windows systems, you must also install Ruby. You can download Ruby from https://rubyinstaller.org/ or with the Chocolatey Windows package manager.

1. Install Ruby.
2. Refresh your environment by running refreshenv
3. Install Bolt by running gem install bolt

Configuring Bolt

To configure Bolt create a ~/.puppetlabs/bolt.yml file. Global options live at the top level of the file while transport specific options are configured for each transport. If a config options is set in the config file and passed with the corresponding command line flag the flag will take precedence.

example file:

---
modulepath: "~/.puppetlabs/bolt-code/site:~/.puppetlabs/bolt-code/modules"
concurrency: 10
format: human
ssh:
  insecure: true
  private-key: ~/.ssh/bolt_id

Global configuration options

concurrency: The number of threads to use when executing on remote nodes (default: 100)

format: The format to use when printing results. Options are human and json (default: human)

modulepath: The module path to load tasks and plan code from. This is a list of directories separated by the OS-specific path separator (: on Linux/macOS, ; on Windows).

ssh transport configuration options

insecure: If true, host key validation will be skipped when connecting over SSH. (default: false)

private-key: The path to the private key file to use for SSH authentication.

connect-timeout: Maximum amount of time to allow for an SSH connection to be established, in seconds.

tmpdir: The directory to store temporary files on the target node. (default: location used by mktemp -d, usually /tmp)

run-as: Triggers privilege escalation for commands on the target node as the specified user. Currently only works via sudo.

winrm transport configuration options

connect-timeout: Maximum amount of time to allow for a WinRM connection to be established, in seconds.

insecure: Whether to skip requiring SSL for connections. (default: false)

cacert: The CA certificate used to authenticate SSL connections. (default: uses system CA certificates)

tmpdir: The directory to store temporary files on the target node. (default: [System.IO.Path]::GetTempPath())

extensions: List of file extensions that will be accepted for scripts or tasks. Scripts with these file extensions will rely on the target node's file type association to run. For example, if Python is installed on the system, a .py script should run with python.exe. .ps1, .rb, and .pp are always allowed and run via hard-coded executables.

pcp transport configuration options

service-url: The URL of the Orchestrator service, usually of the form https://puppet:8143. If not specified, will attempt to read local PE Client Tools configuration for the same setting from orchestrator.conf.

cacert: The CA certificate used to authenticate the service-url. If not specified, will attempt to read local PE Client Tools configuration for the same setting from orchestrator.conf.

token-file: The token certificate used to authorize requests to the service-url. If not specified, will attempt to read local PE Client Tools configuration for the same setting from orchestrator.conf. (default: ~/.puppetlabs/token)

task-environment: The environment from which Orchestrator will serve task implementations. (default: production)

Usage examples

Get help

$ bolt --help
Usage: bolt <subcommand> <action> [options]
...

Run a command over SSH

$ bolt command run 'ssh -V' --nodes neptune
neptune:

OpenSSH_5.3p1, OpenSSL 1.0.1e-fips 11 Feb 2013

Ran on 1 node in 0.27 seconds

Run a command over SSH against multiple hosts

$ bolt command run 'ssh -V' --nodes neptune,mars
neptune:

OpenSSH_5.3p1, OpenSSL 1.0.1e-fips 11 Feb 2013

mars:

OpenSSH_6.6.1p1, OpenSSL 1.0.1e-fips 11 Feb 2013

Ran on 2 nodes in 0.27 seconds

Run a command over WinRM

$ bolt command run 'gpupdate /force' --nodes winrm://pluto --user Administrator --password <password>
pluto:

Updating policy...

Computer Policy update has completed successfully.

User Policy update has completed successfully.

Ran on 1 node in 11.21 seconds

Run a command over WinRM against multiple hosts

$ bolt command run '(Get-CimInstance Win32_OperatingSystem).version' --nodes winrm://pluto,winrm://mercury --user Administrator --password <password>
pluto:

6.3.9600

mercury:

10.0.14393

Ran on 2 nodes in 6.03 seconds

Run a bash script

$ bolt script run ./install-puppet-agent.sh --nodes neptune
neptune: Installed puppet-agent 5.1.0

Run a PowerShell script

$ bolt script run Get-WUServiceManager.ps1 --nodes winrm://pluto --user Administrator --password <password>
pluto:

Name                  : Windows Server Update Service
ContentValidationCert : {}
ExpirationDate        : 6/18/5254 9:21:00 PM
IsManaged             : True
IsRegisteredWithAU    : True
IssueDate             : 1/1/2003 12:00:00 AM
OffersWindowsUpdates  : True
RedirectUrls          : System.__ComObject
ServiceID             : 3da21691-e39d-4da6-8a4b-b43877bcb1b7
IsScanPackageService  : False
CanRegisterWithAU     : True
ServiceUrl            :
SetupPrefix           :
IsDefaultAUService    : True

Run the sql task from the mysql module

$ bolt task run mysql::sql database=mydatabase sql="SHOW TABLES" --nodes neptune --modulepath ~/modules

Run the deploy plan from the webserver module

$ bolt plan run webserver::deploy version=1.2 --modulepath ~/modules

Deployed app version 1.2.

Note the --nodes option is not used with plans, as they can contain more complex logic about where code is run. A plan can use normal parameters to accept nodes when applicable, as in the next example.

Run the single_task plan from the sample module in this repo

$ bolt plan run sample::single_task nodes=neptune --modulepath spec/fixtures/modules
neptune got passed the message: hi there

Kudos

Thank you to Marcin Bunsch for allowing Puppet to use the bolt gem name.

Contributing

We welcome error reports and pull requests to Bolt. See CONTRIBUTING.md for how to help.

License

The gem is available as open source under the terms of the Apache 2.0.