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
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
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
HTTPS connections are supported by providing the
chef-run over WinRM does not support certificate-based authentication to target hosts.
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
To specify properties and actions, use a
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.
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
cd /cookbooks chef-run host1 my_cookbook chef-run host1 my_cookbook::non_default_recipe
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:
[chef] cookbook_repo_paths = [ "/path/1", "/path/b" ]
cookbook_path ['/path/1', '/path/b']
If you run
chef-run host1 my_cookbook and the current directory does not have a cookbook named
chef-run searches the configured paths, with those configured in
~/.chef-workstation/config.toml taking priority over those in
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'
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.
name "really_complicated" ... depends "pretty_simple"
name "really_complicated" default_source :supermarket default_source :chef_repo, "../" run_list "really_complicated::first" cookbook "pretty_simple"
log "lets include some stuff" include_recipe "pretty_simple::second"
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
You can specify different cookbook sources in
Policyfile.rb, including a private supermarket. See the Policyfile documentation for examples.
You can configure remote nodes managed with
chef-run to send run information to Chef Automate. First, generate an auth token.
[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.
Was this page helpful?