Learning Kit

Intro to Bolt

Using Bolt: Running commands

Time: 15 minutes
Materials needed: none

You can use Bolt in four different ways, each with increasing complexity and increasing power: 

  1. running commands
  2. running scripts
  3. running tasks
  4. running plans

Keep in mind that while you can use Bolt in all of these ways, you don’t have to. Don’t think that you should always use Bolt plans just because they are the most powerful form of Bolt. Instead, use the simplest technique that solves your automation problems.

Because this course is focused on beginner-level concepts, it will cover only how to use Bolt to run commands and scripts. If you’d like to dive in further to learn about running tasks and plans, refer to the Bolt documentation for running tasks and plans.

Using Bolt: Running Commands

You can use Bolt to run arbitrary PowerShell or Linux/macOS shell commands on one or more target nodes. This is the simplest way to use Bolt, and is sometimes all you need to solve a system administration problem or automate a task.

For example, you could run uptime on a fleet of 100 computers to see if any of them have rebooted in the last 24 hours. Or you could use the ps command to look for runaway processes on any of your macOS machines. Or you could run an apt command to upgrade the MySQL packages on all of your database servers.

It doesn’t matter what operating system your host node is running: you type the same Bolt commands regardless of whether you’re typing them on Linux, macOS, or Windows.

SSH, WinRM, and authentication

When running a command on a target node, Bolt uses a communication protocol appropriate to the target node’s operating system: WinRM for Windows, and SSH for Linux or macOS. Bolt needs to authenticate with target nodes before it can run commands on them. The last section showed you how to configure Bolt with default usernames and passwords for authentication. Alternatively, you can authenticate using the more advanced technique of public/private key pairs. Vagrant set up key pairs automatically for you when it created the target nodes during the Setting Up Target Nodes section of this course, so that’s how you’ll authenticate in this lesson.

Shell vs. PowerShell

When Bolt runs a command on a target node, it can only run commands that are appropriate for the operating system of that target node. So it can only run a shell command on a Linux or macOS target node, and it can only run a PowerShell command on a Windows target node.

Command syntax

The most common way to use Bolt to run a command on a target node is with this syntax:

bolt command run "<COMMAND>" --targets <NODE IDENTIFIER> --user <USERNAME> --password <PASSWORD>`

This command becomes even simpler if you’ve configured a default username and password in inventory.yaml, or if you have a public/private key pair set up:

bolt command run "<COMMAND>" --targets <NODE IDENTIFIER>`

The value can take several forms. To access a Linux or macOS node, use the node’s hostname or IP address. In this lesson you will refer to your Linux target nodes as node1, node2, and node3.

To access a Windows target node, use winrm:// or winrm://. This tells Bolt to use WinRM and not SSH to communicate with the target node. Because of the way Vagrant and Virtualbox set up networking, you’ll need to refer to your Windows target node as winrm://localhost:55985.

As a concrete example, say you wanted to see the time on each of the four target nodes to make sure none of their clocks have drifted. The command date displays the current time, and works on Linux, macOS, and Windows. Here’s how you would use Bolt to run the date command on all three of your Linux target nodes.


1). Enter the command bolt command run "date" --targets node1,node2,node3 Or use the group name you defined in inventory.yaml:

bolt command run "date" --targets all_linux

You should see output similar to this:

Started on node1...
Started on node2...
Started on node3...
Finished on node2:
    Wed Sep 18 20:44:36 UTC 2019
Finished on node3:
    Wed Sep 18 20:44:36 UTC 2019
Finished on node1:
    Wed Sep 18 20:44:36 UTC 2019
Successful on 3 nodes: node1,node2,node3
Ran on 3 nodes in 1.18 seconds

2). To run date on your Windows target node, change the value of the --targets parameter:

bolt command run "date" --targets winrm://localhost:55985

Or replace the hostname with the group name you defined in inventory.yaml file:

bolt command run "hostname" --targets all_windows

The output should look something like this:

Started on localhost...
Finished on localhost:
    Wednesday, September 18, 2019 8:43:43 PM
Successful on 1 node: winrm://localhost:55985
Ran on 1 node in 6.81 seconds

3). To run date on all four of your target nodes, add another group name to the --targets parameter, with commas separating the values:

bolt command run "date" --targets all_linux,all_windows`

Learning more

These examples show just some of the ways you can use Bolt to run commands; there are many configurable parameters not discussed here that make Bolt an even more flexible and powerful tool. For full details, see Bolt’s documentation.

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.