Chef Workstation Configuration

Configuration

Chef Workstation App and chef-run configuration is managed in config.toml. Chef Workstation will create config.toml the first time you use chef-run, if one does not already exist. To configure other tools, see their respective pages found in the ChefDK documentation.

Default location

Chef Workstation looks for the config.toml in a default location.

Windows

  • Powershell: $env:USERPROFILE\.chef-workstation\config.toml
  • cmd.exe: %USERPROFILE%\.chef-workstation\config.toml

Linux and Mac

/home/$USER/.chef-workstation/config.toml

Settings

Telemetry

Configure telemetry behaviors for Chef Workstation components.

Example

[telemetry]
enable=true
dev=false

enable

Description
When true, anonymous usage data and bug reports are sent to Chef. See Chef’s Privacy Statement for the type and usage of gathered data.
Value
true, false
Default
true
Used by
chef-run
CHEF_TELEMETRY_OPT_OUT
When set to any value, chef-run will not capture or send telemetry data.

dev

Description
When set to any value, chef-run will not capture or send telemetry data. Only set this if you have access to Chef’s internal QA environment - otherwise the telemetry data will not be successfully captured by Chef. If you have access to Chef’s internal QA environment, if dev and enable are both true, anonymous data is reported to Chef’s QA environment.
Values
true, false
Default
false
Used by
chef-run, Chef Workstation App

Log

Control logging level and location.

Example

[log]
level="debug"
location="C:\Users\username\chef-workstation.log"

level

Description
Determines what messages are logged from locally-run Chef Workstation commands to the to the local log file.
Values
"debug", "warn", "info", "error", "fatal"
Default
"warn"
Used by
chef-run

location

Description
The location of the local Chef Workstation log file.
Values
Value must be a valid, writable file path.
Default
`“$USERHOME/.chef-workstation/logs/default.log”
Used by
chef-run

Cache

Configure caching options.

Example

[cache]
path="/home/users/username/.cache/chef-workstation"

path

Description
The base path used to store cached cookbooks and downloads.
Default
$USERHOME/.chef-workstation/cache
Values
This must reference a valid, writable directory.
Used by
chef-run

Connection

Control default connection behaviors.

Example

[connection]
default_protocol="winrm"
default_user="username"

default_protocol

Description
Default protocol for connecting to target hosts.
Values
"ssh", "winrm"
Default
"ssh"
Used by
chef-run
CLI flag
--protocol PROTO

default_user

Description
Default username for target host authentication.
Values
A username that exists on the target hosts.
Default
root (Linux), administrator (Windows)
Used by
chef-run
CLI flag
--user USERNAME

Connection.winrm

Control connection behaviors for the WinRM protocol.

Example

[connection.winrm]
ssl=true
ssl_verify=false

ssl

Description
Enable SSL for WinRM session encryption
Values
true, false
Default
false
Used by
chef-run
CLI flag
--[no]-ssl

ssl_verify

Description :Intended for use in testing environments that use self-signed certificates on Windows nodes.

Default
true
Values
true, false
Used by
chef-run
CLI flag
–ssl-[no]-verify

Chef

Configure remote Chef running on instances.

Example

[chef]
trusted_certs_dir="/home/username/mytrustedcerts"
cookbook_repo_paths = [
  "/home/username/cookbooks",
  "/var/chef/cookbooks"
]

trusted_certs_dir

Description
Describes where to find Chef’s trusted certificates. Used to ensure trusted certs are provided to the chef-client run on target nodes.
Values
A directory containing the trusted certificates for use in the Chef ecosystem.
Default
Look first for .chef/config.rb and use that value if provided; otherwise "/opt/chef-workstation/embedded/ssl/certs/"
Used by
chef-run

cookbook_repo_paths

Description
Path or paths to use for cookbook resolution. When multiple cookbook paths are provided and a cookbook exists in more than one of them, the cookbook found in the last-most directory will be used. Considering the example, when resolving cookbook mycb: if mycb existed in both /home/username/cookbooks and /var/chef/cookbooks, mycb in /var/chef/cookbooks will be used.
Values
A string referencing a valid cookbook path, or an array of such strings. See example for syntax.
Default
cookbook_path value from .chef/config.rb, otherwise not found
Used by
chef-run
CLI flag
--cookbook-repo-paths PATH1,PATH2,..PATHn

Updates

Control the behavior of automatic update checking for Chef Workstation.

Example

[updates]
enable=true
channel="current"

enable

Description
Enable update checking for Chef Workstation updates.
Values
true, false
Default
true
Used by
Chef Workstation App

channel

Description
Set the update channel to use when checking for Chef Workstation updates. "stable" is the recommended value. Switch to "current" is not guaranteed to be stable, and should only be used if you are comfortable with the risks associated.
Values
"stable", "current"
Default
"stable"
Used by
Chef Workstation App

Data_collector

Configure reporting of chef-client runs triggered via chef-run.

Example

[data_collector]
url="https://1.1.1.1/data-collector/v0/"
token="ABCDEF0123456789"

url

Description
URL of an Automate data collection endpoint. This URL is provided to the target host, allowing them to report in to Automate when chef-run is used to converge the targets. A valid token generated by automate is required.
Values
A valid automate data collector endpoint.
Default
not set.
Used by
chef-run

token

Description
An Automate API token, used on target host to authenticate to the url provided.
Values
A valid token generated by Automate.
Default
not set.
Used by
chef-run

Dev

These options are intended for development and troubleshooting of Chef Workstation tools. Their usage is not supported and is subject to change.

Example

[dev]
spinner=false

spinner

Description
Use animated spinners and progress indicators in the terminal output.
Values
true, false
Default
true
Used by
chef-run