Chef

Table Of Contents

client.rb

A client.rb file is used to specify the configuration details for the chef-client.

  • This file is loaded every time this executable is run
  • On UNIX- and Linux-based machines, the default location for this file is /etc/chef/client.rb; on Microsoft Windows machines, the default location for this file is C:\chef\client.rb; use the --config option from the command line to change this location
  • This file is not created by default
  • When a client.rb file is present in this directory, the settings contained within that file will override the default configuration settings

Settings

This configuration file has the following settings:

Setting Description
add_formatter Use to specify a 3rd-party formatter. (See nyan-cat for an example of a 3rd-party formatter.) Each formatter requires its own entry.
cache_path Optional. Use to specify the home directory for the user that is running the chef-client as a non-root user.
checksum_path The location in which checksums for individual cookbook files (such as recipes) are stored. The checksum itself is stored in CouchDB and is compared to a file in this location that has a filename that is identical to the checksum.
chef_server_url The URL for the Chef server.
chef_zero.enabled Use to enable chef-zero. Default value: false.
chef_zero[:port] The port on which chef-zero will listen. Default value: 8889.
client_key The location of the file which contains the client key. Default value: /etc/chef/client.pem.
client_registration_retries The number of times a chef-client should attempt to register with a Chef server. Default value: 5.
cookbook_path The sub-directory for cookbooks on the chef-client. This value can be a string or an array of file system locations, processed in the specified order. The last cookbook is considered to override local modifications.
data_bag_decrypt_minimum_version The minimum required version of data bag encryption. Possible values: 0, 1, and 2. When all of the machines in an organization are running chef-client version 11.6 (or higher), it is recommended that this value be set to 2.
data_bag_path The location from which a data bag is loaded. Default value: /var/chef/data_bags.
diff_disabled Use to have the chef-client create a diff when changes are made to a file. Default value: false.
diff_filesize_threshold The maximum size (in bytes) of a file for which the chef-client can create a diff. Default value: 10000000.
diff_output_threshold The maximum size (in bytes) of a diff file created by the chef-client. Default value: 1000000.
enable_reporting

Use to have the chef-client send data to the Enterprise Chef server for use with Reporting.

Warning

This setting is available only when using Reporting, an add-on for Enterprise Chef that collects reporting data about nodes.

enable_reporting_url_fatals

Use to have the chef-client run fail when Reporting data cannot be sent to the Enterprise Chef server (for any reason).

Warning

This setting is available only when using Reporting, an add-on for Enterprise Chef that collects reporting data about nodes.

enable_selinux_file_permission_fixup SELinux environments only. Use to have the chef-client attempt to apply the correct file permissions to an updated file via the restorecon command. Set this value to false to prevent the chef-client from attempting this action.
encrypted_data_bag_secret The subdirectory in which encrypted data bag secrets are located.
environment The name of the environment.
environment_path The path to the environment. Default value: /var/chef/environments.
file_atomic_update Use to apply atomic file updates to all resources. Set to true for global atomic file updates. Set to false for global non-atomic file updates. (Use the atomic_update setting on a per-resource basis to override this setting.) Default value: true.
file_backup_path The location in which backup files are stored. If this value is empty, backup files will be stored in the directory of the target file. Default value: /var/chef/backup.
file_cache_path The location in which cookbooks (and other transient data) files are stored when they are synchronized. (This value can also be used in recipes to download files with the remote_file resource.)
file_staging_uses_destdir Use to specify how file staging (via temporary files) is done. When true, temporary files are created in the directory in which files will reside. When false, temporary files are created under ENV['TMP']. Default value: false.
group The group that owns a process. This is required when starting any executable as a daemon. Default value: nil.
http_proxy The proxy server for HTTP connections. Default value: nil.
http_proxy_pass The password for the proxy server when the proxy server is using an HTTP connection. Default value: nil.
http_proxy_user The user name for the proxy server when the proxy server is using an HTTP connection. Default value: nil.
http_retry_count The number of retry attempts. Default value: 5.
http_retry_delay The delay (in seconds) between retry attempts. Default value: 5.
https_proxy The proxy server for HTTPS connections. Default value: nil.
https_proxy_pass The password for the proxy server when the proxy server is using an HTTPS connection. Default value: nil.
https_proxy_user The user name for the proxy server when the proxy server is using an HTTPS connection. Default value: nil.
interval The frequency (in seconds) at which the chef-client runs. Default value: 1800.
json_attribs The path to a file that contains JSON data.
local_key_generation Use to specify whether the Chef server or chef-client will generate the private/public key pair. When true, the chef-client will generate the key pair, and then send the public key to the Chef server.
local_mode Use to run the chef-client in local mode. This allows all commands that work against the Chef server to also work against the local chef-repo.
lockfile A lock used by the chef-client to ensure that only one instance of chef-client or chef-solo is modifying the system at any time. By default, the lock file is located in the file_cache_path so that intentional uses of multiple instances work automatically. If file_cache_path is located on an NF mount a different location for the lock file is recommended.
log_level The level of logging that will be stored in a log file. Possible levels: :auto (default), debug, info, warn, error, or fatal.
log_location The location in which log file output files will be saved. If this location is set to something other than STDOUT, standard output logging will still be performed (otherwise there would be no output other than to a file). Default value: STDOUT.
no_lazy_load Use to download all cookbook files and templates at the beginning of the chef-client run. Default value: false.
no_proxy A comma-separated list of URLs that do not need a proxy. Default value: nil.
node_name The name of the node. This is used to determine which configuration should be applied and to set the client_name (which is the name used when authenticating to a Chef server). The default value is set automatically to be the FQDN of the chef-client, as detected by Ohai. In general, leaving this setting blank and letting Ohai assign the FQDN of the node as the node_name during each chef-client run is the recommended approach.
node_path The location in which nodes are stored when the chef-client is run in local mode. Default value: /var/chef/node.
pid_file The location in which a process identification number (pid) is saved. An executable, when started as a daemon, will write the pid to the specified file. Default value: /tmp/name-of-executable.pid.
rest_timeout The time (in seconds) after which an HTTP REST request will time out.
role_path The location in which role files are located. Default value: /var/chef/roles.
splay A number (in seconds) to add to the interval that is used to determine the frequency of chef-client runs. This number can help prevent server load when there are many clients running at the same time. Default value: nil.
ssl_ca_file The file in which the OpenSSL key is saved. This setting is generated automatically by the chef-client and most users will not need to modify it.
ssl_ca_path The path to where the OpenSSL key is located. This setting is generated automatically by the chef-client and most users will not need to modify it.
ssl_client_cert The OpenSSL X.509 certificate. This setting is generated automatically by the chef-client and most users will not need to modify it.
ssl_client_key The OpenSSL X.509 key. This setting is generated automatically by the chef-client and most users will not need to modify it.
ssl_verify_mode

The verify mode for HTTPS requests.

  • Use :verify_none to do no validation of SSL certificates.
  • Use :verify_peer to do validation of all SSL certificates, including the Chef server connections, S3 connections, and any HTTPS remote_file resource URLs used in the chef-client run. This is the recommended setting.

Depending on how OpenSSL is configured, the ssl_ca_path may need to be specified.

syntax_check_cache_path All files in a cookbook must contain valid Ruby syntax. Use this setting to specify the location in which Knife caches information about files that have been checked for valid Ruby syntax.
umask The file mode creation mask, or umask. Default value: 0022.
user The user that owns a process. This is required when starting any executable as a daemon. Default value: nil.
validation_client_name The name of the server that–along with the validation_key–is used to determine whether a chef-client may register with a Chef server. The validation_client_name located in the server and client configuration files must match.
validation_key The location of the file which contains the key used when a chef-client is registered with a Chef server. A validation key is signed using the validation_client_name for authentication. Default value: /etc/chef/validation.pem.
verbose_logging Use to set the log level. Options: true, nil, and false. When this is set to false, notifications about individual resources being processed will be suppressed (and will be output at the :info logging level). Setting this to false can be useful when a chef-client is run as a daemon. Default value: nil.
verify_api_cert Use verify_api_cert to only do SSL validation of the chef server connection; may be needed if the chef-client needs to talk to other services that have broken SSL certificates. Default value: false.
whitelist

A Hash that contains the whitelist used by Push Jobs. For example:

whitelist {
  "job-name" => "command",
  "job-name" => "command",
  "chef-client" => "chef-client"
}

A job entry may also be "job-name" => {:lock => true}, which will check the lockfile setting in the client.rb file before starting the job.

Warning

The whitelist setting is available only when using Push Jobs, a tool that runs jobs against nodes in an Enterprise Chef organization.

Ohai Settings

Ohai configuration settings can be added to the client.rb file.

Setting Description
Ohai::Config[:directory] The directory in which Ohai plugins are located.
Ohai::Config[:disabled_plugins]

An array of Ohai plugins to be disabled on a node. For example:

Ohai::Config[:disabled_plugins] = [
             :MyPlugin
                 ]

or:

Ohai::Config[:disabled_plugins] = [
             :MyPlugin,
                 :MyPlugin,
                 :MyPlugin
                 ]

or to disable both Ohai 6 and Ohai 7 versions:

Ohai::Config[:disabled_plugins] = [
             :MyPlugin,
                 :MyPlugin,
                 "my_ohai_6_plugin"
                 ]
Ohai::Config[:hints_path] The path to the file that contains hints for Ohai.
Ohai::Config[:log_level] The level of logging that will be stored in a log file.
Ohai::Config[:logfile] The location in which log file output files will be saved. If this location is set to something other than STDOUT, standard output logging will still be performed (otherwise there would be no output other than to a file).
Ohai::Config[:version] The version of Ohai.

Note

The Ohai executable ignores settings in the client.rb file when Ohai is run independently of the chef-client.

Example

A sample client.rb file that contains all possible settings (listed alphabetically):

add_formatter :nyan
add_formatter :foo
add_formatter :bar
cache_path File.join(File.expand_path("~"), ".chef", "cache")
checksum_path "/var/chef/checksums"
chef_repo_path "/path/to/chef-repo"
chef_server_url "http://localhost:4000"
chef_zero.enabled true
chef_zero[:port] 8889
client_key "/etc/chef/client.pem"
client_registration_retries 5
cookbook_path [
              "/var/chef/cookbooks",
              "/var/chef/site-cookbooks"
              ]
data_bag_decrypt_minimum_version "2"
data_bag_path "/var/chef/data_bags"
diff_disabled false
diff_filesize_threshold 10000000
diff_output_threshold 1000000
enable_reporting true
enable_reporting_url_fatals false
enable_selinux_file_permission_fixup true
encrypted_data_bag_secret "/etc/chef/encrypted_data_bag_secret"
environment "production"
environment_path "/var/chef/environments"
file_atomic_update true
file_backup_path "/var/chef/backup"
file_cache_path "/var/chef/cache"
file_staging_uses_destdir false
group nil
http_proxy "http://proxy.vmware.com:3128"
http_proxy_pass "1234567890"
http_proxy_user "my_username"
http_retry_count 5
http_retry_delay 5
https_proxy "http://proxy.vmware.com:3128"
https_proxy_pass "1234567890"
httpx_proxy_user "my_username"
interval 1800
json_attribs nil
local_key_generation false
local_mode true
lockfile nil
log_level :info
log_location STDOUT
no_lazy_load false
no_proxy "*.vmware.com,10.*"
node_name "mynode.example.com"
node_path "/var/chef/node"
pid_file "/tmp/chef-client.pid"
rest_timeout 300
role_path "/var/chef/roles"
splay nil
ssl_ca_file nil
ssl_ca_path nil "/etc/ssl/certs"
ssl_client_cert ""
ssl_client_key ""
ssl_verify_mode :verify_peer
syntax_check_cache_path ""
umask 0022
user nil
validation_client_name "chef-validator"
validation_key "/etc/chef/validation.pem"
verbose_logging true
verify_api_cert false
whitelist {
           "job-name" => "command",
           "job-name" => "command",
           "chef-client" => "chef-client"
          }