chef-run (executable)

chef-run is a tool to execute ad-hoc tasks on one or more target nodes using Chef Infra Client. To start with, familiarize yourself with chef-run’s arguments and flags by running chef-run -h.

Apply a Resource to a Single Node over SSH

In its simplest form, chef-run targets a single machine and execute a single resource on that machine:

chef-run ssh://my_user@host1:2222 directory /tmp/foo --identity-file ~/.ssh/id_rsa

SSH is the default protocol. When using SSH, chef-run attempts to read defaults from your ~/.ssh/config file. Given the following SSH configuration:

Host host1
  IdentityFile /Users/me/.ssh/id_rsa
  User my_user
  Port 2222

You could specify the chef-run command as:

chef-run host1 directory /tmp/foo

To use password authentication instead of an identity file, specify the password as part of the connection information or by using the command line flag:

chef-run my_user:a_password@host1:2222 directory /tmp/foo
chef-run my_user@host1:2222 directory /tmp/foo --password a_password

Applying a Resource to a Single Node over WinRM

To target WinRM you must specify the winrm protocol as part of the connection information:

chef-run 'winrm://my_user:my_p4ssword!@host' directory /tmp/foo

WinRM connections only support password authentication. Provide username and password as shown in the example, or via the --user and --password flags.

HTTPS connections are supported by providing the --ssl flag.

chef-run over WinRM does not support certificate-based authentication to target hosts.

Specifying resource properties and actions

You can specify all the Chef Infra resources in the command line. Enter the chef-run command first, followed by the resource type in the second place, and the resource name in the third place. For example:

chef-run host1 group awesome_group

This command specifies the group resource with a name of awesome_group.

To specify properties and actions, use a key=value syntax:

chef-run host1 group awesome_group gid=1001
chef-run host1 user super_person gid=1001 'password=complex=p@ssword!!'
chef-run host1 user super_person action=remove

See the documentation for each resource to see available properties available to customize. As shown in the previous example, you can quote the key=value pair if the value contains a character that would be interpreted by the shell.

Running a Recipe

To run a full recipe, specify a recipe using its path:

chef-run host1 /path/to/recipe.rb
chef-run host1 recipe.rb

If your recipe is in a cookbook you can also specify that cookbook:

chef-run host1 /cookbooks/my_cookbook/recipes/default.rb
chef-run host1 /cookbooks/my_cookbook

If you specify the path to the cookbook chef-run will execute the default recipe from the cookbook on the target node.

chef-run also supports looking up your cookbook in a local cookbook repository. Assuming you have your cookbook repository at /cookbooks, run:

cd /cookbooks
chef-run host1 my_cookbook
chef-run host1 my_cookbook::non_default_recipe

::recipe_name tells chef-run to run a recipe other than the default. chef-run reads your local Chef Workstation configuration file ~/.chef-workstation/config.toml and Chef configuration file ~/.chef/config.rb. It looks for cookbooks in the paths specified in both files. The configuration value is an array and looks something like this:

For ~/.chef-workstation/config.toml:

[chef]
cookbook_repo_paths = [
  "/path/1",
  "/path/b"
]

and for ~/.chef/config.rb:

cookbook_path ['/path/1', '/path/b']

If you run chef-run host1 my_cookbook and the current directory does not have a cookbook named my_cookbook, then chef-run searches the configured paths, with those configured in ~/.chef-workstation/config.toml taking priority over those in ~/.chef/config.rb.

To specify the search paths as command line arguments instead of using a configuration file, use:

chef-run host1 my_cookbook --cookbook-repo-paths '/path/1,/path/b'

Configuring Cookbook Dependencies and Sources

When converging a target node chef-run creates a Policyfile bundle that includes the cookbook specified. If the cookbook you specified has its own Policyfile.rb that will be respected.

In your metadata.rb file:

name "really_complicated"
...
depends "pretty_simple"

In your Policyfile.rb file:

name "really_complicated"
default_source :supermarket
default_source :chef_repo, "../"

run_list "really_complicated::first"

cookbook "pretty_simple"

In your recipes/first.rb

log "lets include some stuff"
include_recipe "pretty_simple::second"

Running chef-run host1 really_complicated::first collects all the really_complicated cookbook dependencies (pretty_simple) first, in preparation for converging the target node. When running on that node the first recipe finds its local dependency on the pretty_simple cookbook and then runs its second recipe.

You can specify different cookbook sources in Policyfile.rb, including a private supermarket. See the Policyfile documentation for examples.

Connecting to Chef Automate 2

You can configure remote nodes managed with chef-run to send run information to Chef Automate. First, generate an auth token.

Next, add the token to config.toml, specifying the appropriate url and token for the automate server:

[data_collector]
url="https://127.0.0.1/data-collector/v0/"
token="abc123="

Target nodes need network access to port 443 of the Chef Automate instance for sending chef-client run information.