client.rb

The client.rb file configures Chef Infra Client on a node and has the following characteristics:

This file is loaded every time the chef-client executable is run.
On Windows machines, the default location for this file is C:\chef\client.rb. On all other systems the default location for this file is /etc/chef/client.rb.
Use the --config option from the command line to override the default location of the configuration file.
This file is not created by default

Settings

This configuration file has the following settings:

add_formatter

A 3rd-party formatter. (See nyan-cat for an example of a 3rd-party formatter.) Each formatter requires its own entry.

allowed_automatic_attributes

An array that allows automatic attributes, preventing non-allowed attributes from being saved.

For more information, see Attribute Persistence.

allowed_default_attributes

An array that allows default attributes, preventing non-allowed attributes from being saved.

For more information, see Attribute Persistence.

allowed_normal_attributes

An array that allows normal attributes, preventing non-allowed attributes from being saved.

For more information, see Attribute Persistence.

allowed_override_attributes

An array that allows override attributes, preventing non-allowed attributes from being saved.

For more information, see Attribute Persistence.

authentication_protocol_version

Sets the authentication protocol that’s used to communicate with Chef Infra Server. For example, specify protocol version 1.3 to enable support for SHA-256 algorithms:

knife[:authentication_protocol_version] = '1.3'

Note

Authentication protocol 1.3 is only supported on Chef Server versions 12.4.0 and above.

automatic_attribute_blacklist

EOL in Chef Infra Client 18. Use blocked_automatic_attributes.

An array that blocks automatic attributes, preventing blocked attributes from being saved.

automatic_attribute_whitelist

EOL in Chef Infra Client 18. Use allowed_automatic_attributes.

An array that allows automatic attributes, preventing non-allowed attributes from being saved.

blocked_automatic_attributes

An array that blocks automatic attributes, preventing blocked attributes from being saved.

For more information, see Attribute Persistence.

blocked_default_attributes

An array that blocks default attributes, preventing block attributes from being saved.

For more information, see Attribute Persistence.

blocked_normal_attributes

An array allows normal attributes, preventing non-allowed attributes from being saved.

For more information, see Attribute Persistence.

blocked_override_attributes

An array blocks override attributes, preventing blocked attributes from being saved.

For more information, see Attribute Persistence.

cache_path

The home directory for the user that runs Chef Infra Client as a non-root user.

checksum_path

The location in which checksum files are stored. These are used to validate individual cookbook files, such as recipes. The checksum itself is stored in the Chef Infra Server database and is then compared to a file in the checksum path that has a filename identical to the checksum.

chef_guid

The node UUID used by Chef Automate. Setting this allows the node UUID to be specified, and can be carried across instances of a node.

chef_license

Used to accept the Chef license. Can be set to accept or accept-no-persist, which persists the license acceptance to disk. If passed to versions where the license isn’t required this configuration option is a no-op.

chef_repo_path

The path to the chef-repo containing cookbooks and other files, such as environments or data bags, when running Chef Infra Client in local mode.

chef_server_url

The URL of the Chef Infra Server. For example:

https://localhost/organizations/ORG_NAME

chef_zero.enabled

Enable chef-zero. This setting requires local_mode to be set to true.

Default value: true if running in local-mode, otherwise false.

chef_zero.port

The port on which chef-zero is to listen. If specified as a range, Chef Infra Client will take the first available port in the range. For example 10,20,30 or 10000-20000.

Default value: 8889-9999.

clear_gem_sources

Globally sets the default of the clear_sources property on the gem_package and chef_gem resources.

Default value: false.

client_fork

Contain Chef Infra Client runs in a secondary process with dedicated RAM. When a Chef Infra Client run is complete, the RAM is returned to the parent process. This setting helps ensure that a Chef Infra Client uses a steady amount of RAM over time because the parent process doesn’t run recipes. This setting also helps prevent memory leaks such as those that can be introduced by the code contained within a poorly designed cookbook.

Default value: true. Set to false to disable running Chef Infra Client in fork node.

Note

Must be set to false up to Chef Infra Client 13.11.3 to gather the standard return code offered by exit_status true. Later versions run as expected without changes to the configuration file.

client_key

The location of the file that contains the client key.

Default value: /etc/chef/client.pem.

client_registration_retries

The number of times a Chef Infra Client will attempt to register with a Chef Infra Server.

Default value: 5.

client_d_dir

A directory that contains additional configuration files for Chef Infra Client.

cookbook_path

The sub-directory for Chef Infra Client cookbooks. 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.

cookbook_sync_threads

The number of helper threads available for parallel cookbook synchronization. Increasing this value may increase the frequency of gateway errors from the Chef Infra Server (503 and 504 errors). Decreasing this number reduces the frequency of gateway errors, if present.

Default value: 10.

data_bag_decrypt_minimum_version

The minimum required version of data bag encryption. Possible values: 1, 2, and 3. Use the default value of 3 for additional encrypted data bag security.

data_bag_path

The location from which a data bag is loaded.

Default value: /var/chef/data_bags.

data_collector.server_url

The fully qualified URL to the data collector server API.

data_collector.token

The shared data collector security token. When configured, the token will be passed as an HTTP header named x-data-collector-token which the server can choose to accept or reject.

data_collector.mode

The Chef Infra Client mode in which the Data Collector will be enabled. Possible values: :solo, :client, or :both. The :solo value is used for Chef Infra Client operating in Chef Solo Mode or Chef Solo Legacy Mode.

Default value: both.

data_collector.raise_on_failure

When enabled, Chef Infra Client raises an error if it can’t successfully POST to the data collector server.

Default value: false.

default_attribute_blacklist

EOL in Chef Infra Client 18. Use blocked_default_attributes.

Normal that blocks default attributes, preventing block attributes from being saved.

default_attribute_whitelist

EOL in Chef Infra Client 18. Use allowed_default_attributes.

Normal that allows default attributes, preventing non-allowed attributes from being saved.

diff_disabled

Cause Chef Infra Client to 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 Chef Infra Client can create a diff.

Default value: 10000000.

diff_output_threshold

The maximum size (in bytes) of a diff file Chef Infra Client can create.

Default value: 1000000.

disable_event_logger

Enable or disable sending Chef Infra Client internal state events to the Windows “Application” event log. Set to false to send events to the Windows “Application” event log at the start and end of a Chef Infra Client run, and also if a Chef Infra Client run fails. Use log_location to set the destination of your Chef Infra Client logs to the Windows event log. Set to true to disable event logging.

Default value: false.

enable_reporting

Cause Chef Infra Client to send run data to Chef Automate server.

Default value: true

enable_reporting_url_fatals

Cause a Chef Infra Client run to fail when run data can’t be sent to the Chef Automate server (for any reason).

Default value: false

enable_selinux_file_permission_fixup

SELinux environments only. Cause Chef Infra Client to attempt to apply the correct file permissions to an updated file using the restorecon command. Set to false to prevent Chef Infra Client from attempting this action.

encrypted_data_bag_secret

The path to a secrets file which can decrypt encrypted data bags.

enforce_default_paths

Turn on path sanity in resources that shellout so that expected paths like /sbin or /bin are added to the PATH.

Disabled by default.

enforce_path_sanity

EOL in Chef Infra Client 18. Use enforce_default_paths.

Turn on path sanity in resources that shellout so that expected paths like /sbin or /bin are added to the PATH.

Disabled by default.

environment

The name of the Chef Infra environment.

environment_path

The path to the environment file.

Default value: /var/chef/environments.

exit_status

When set to :enabled, Chef Infra Client will use standardized exit codes for the Chef Infra Client run status, and any non-standard exit codes will be converted to 1 or GENERIC_FAILURE. This setting can also be set to :disabled to use the pre-Chef Infra Client 13 exit code behavior.

Default value: nil.

file_atomic_update

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 for each resource to override this setting.)

Default value: true.

Warning

Changing this setting to false may cause file corruption, data loss, or instability. Use the atomic_update property on the cookbook_file, file, remote_file, and template resources to tune this behavior at the recipe level.

file_backup_path

The location in which backup files are stored. If this value is empty, backup files are 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’re synchronized. This value can also be used in recipes to download files with the remote_file resource.

file_staging_uses_destdir

How file staging (using 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: true.

fips

Allows OpenSSL to enforce FIPS-validated security during a Chef Infra Client run. Set to true to enable FIPS-validated security.

force_formatter

Using force_formatter makes Chef Infra Client default to formatter output when STDOUT isn’t a TTY.

force_logger

Using force_logger makes Chef Infra Client default to logger output when STDOUT is a TTY.

ftp_proxy

The proxy server for FTP connections.

ftp_proxy_pass

The password for the proxy server when the proxy server is using an FTP connection.

Default value: nil.

ftp_proxy_user

The user name for the proxy server when the proxy server is using an FTP connection.

Default value: nil.

group

The group that owns a process. This is required when starting any executable as a daemon.

Default value: nil.

gem_installer_bundler_options

Additional options to pass to bundler when installing metadata for cookbook.

Default value: nil.

For example:

gem_installer_bundler_options = [
  "--local", "--clean"
]

gem_installer_bundler_options = "--local"

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 a HTTP connection.

Default value: nil.

http_proxy_user

The user name for the proxy server when the proxy server is using a 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 a HTTPS connection.

Default value: nil.

https_proxy_user

The user name for the proxy server when the proxy server is using a HTTPS connection.

Default value: nil.

interval

The frequency (in seconds) at which Chef Infra Client runs when running in daemonized mode. We don’t recommend running in daemonized mode. Instead you should rely on scheduled execution from system schedulers like systemd timers, cron jobs, or Windows Scheduled Tasks.

Default value: 1800.

json_attribs

The path to a file that contains JSON data.

listen

Run chef-zero in socketless mode. Set to false to disable port binding and HTTP requests on localhost.

local_key_generation

Whether the Chef Infra Server or Chef Infra Client generates the private/public key pair. When true, Chef Infra Client generates the key pair, and then sends the public key to the Chef Infra Server.

Default value: true.

local_mode

Run Chef Infra Client in local mode. This allows all commands that work against the Chef Infra Server to also work against the local chef-repo.

lockfile

The location of the Chef Infra Client lock file. This value is typically platform dependent, so it should be a location defined by file_cache_path. The default location of a lock file shouldn’t be on an NFS mount.

Default value: a location defined by file_cache_path.

log_level

The level of logging to be stored in a log file. Possible levels: :auto (default), :trace, :debug, :info, :warn, :error, or :fatal. The :auto level will use :warn when a terminal is available or :info when a terminal isn’t available.

log_location

The location of the log file. Possible values: /path/to/log_location, STDOUT, STDERR, :win_evt (Windows Event Logger), or :syslog (writes to the syslog daemon facility with the originator set as chef-client). The application log will specify the source as Chef.

Default value: STDOUT.

migrate_key_to_keystore

Set to true to tell the Chef Infra Client to create a new key pair in a PFX certificate object and store that in the local machine certificate store. Chef Infra Client will check for the presence of that key when the headers to connect to Chef Infra Server are built and will use it if present. Windows only.

minimal_ohai

Run a minimal set of Ohai plugins providing data necessary for the execution of Chef Infra Client’s built-in resources. Setting this to true will skip many large and time consuming plugins such as cloud or packages. Setting this to true may break cookbooks that assume all Ohai data will be present.

named_run_list

A specific named runlist defined in the node’s applied Policyfile which should be used when running Chef Infra Client.

no_lazy_load

Download all cookbook files and templates at the beginning of a Chef Infra Client run.

Default value: true.

no_proxy

A comma-separated list of URLs that don’t need a proxy.

Default value: nil.

node_name

The unique identifier of the node. This determines which configuration should be applied and sets the client_name, which is the name used when authenticating to a Chef Infra Server. By default, Chef Infra Client will use the system’s FQDN as the node name. In general, Chef recommends that you leave this setting blank and let the client assign the FQDN of the node as the node_name during each Chef Infra Client run.

node_path

The location in which nodes are stored during a Chef Infra Client run in local mode.

Default value: /var/chef/node.

normal_attribute_blacklist

EOL in Chef Infra Client 18. Use blocked_normal_attributes.

An array that blocks normal attributes, preventing blocked attributes from being saved.

override_attribute_blacklist

EOL in Chef Infra Client 18. Use blocked_override_attributes.

An array that blocks override attributes, preventing blocked attributes from being saved.

normal_attribute_whitelist

EOL in Chef Infra Client 18. Use allowed_normal_attributes.

An array that allows normal attributes, preventing non-allowed attributes from being saved.

override_attribute_whitelist

EOL in Chef Infra Client 18. Use allowed_override_attributes.

An array that allows override attributes, preventing non-allowed attributes from being saved.

pid_file

The location in which a process identification number (pid) is saved. An executable, when started as a daemon, writes the pid to the specified file.

Default value: /tmp/name-of-executable.pid.

policy_group

The name of a policy group that exists on the Chef Infra Server. policy_name must also be specified.

policy_group_path

The location of policy_groups on disk.

policy_name

The name of a policy, as identified by the name setting in a Policyfile.rb file. policy_group must also be specified.

policy_path

The location of policies on disk.

recipe_url

A URL to download recipes from when running in local mode.

rest_timeout

The time (in seconds) after which an HTTP REST request is to time out.

Default value: 300.

role_path

The location in which role files are located.

Default value: /var/chef/roles.

rubygems_url

The location to source rubygems. It can be set to a string or array of strings for URIs to set as rubygems sources. This allows individuals to setup an internal mirror of rubygems for “airgapped” environments.

Default value: https://www.rubygems.org. If a source is specified in either gem_package of chef_gem resources it will be added to the values provided here.

run_lock_timeout

The amount of time (in seconds) to wait for a Chef Infra Client lock file to be deleted. A Chef Infra Client run won’t start when a lock file is present. If a lock file isn’t deleted before this time expires, the pending Chef Infra Client run exits.

Default value: not set (indefinite). Set to 0 to cause a second Chef Infra Client to exit immediately.

script_path

An array of paths to search for knife exec scripts if they’re not in the current directory

skip_gem_metadata_installation

when skip_gem_metadata_installation is set to true, cookbook gem installation will be skipped.

Default value: false

splay

A random number between zero and splay that is added to interval. Use splay to help balance the load on the Chef Infra Server by ensuring that many Chef Infra Client runs aren’t occurring at the same interval.

Default value: nil.

stream_execute_output

Always stream the output of execute resources even if the live_stream property isn’t set to true.

Default value: false

show_download_progress

Using show_download_progress will display the overall progress of a remote_file download.

Default value: false

download_progress_interval

When show_download_progress is set to true this is the interval in seconds to write out download progress.

Default value: 10

ssl_ca_file

The file in which the OpenSSL key is saved. Chef Infra Client generates this setting automatically and most users don’t need to modify it.

ssl_ca_path

The path to where the OpenSSL key is located. Chef Infra Client generates this setting automatically and most users don’t need to modify it.

ssl_client_cert

The OpenSSL X.509 certificate used for mutual certificate validation. This setting is only necessary when mutual certificate validation is configured on the Chef Infra Server.

Default value:nil.

ssl_client_key

The OpenSSL X.509 key used for mutual certificate validation. This setting is only necessary when mutual certificate validation is configured on the Chef Infra Server.

Default value: nil.

ssl_verify_mode

Set the verify mode for HTTPS requests.

Use :verify_none for no validation of SSL certificates.
Use :verify_peer for validation of all SSL certificates, including the Chef Infra Server connections, S3 connections, and any HTTPS remote_file resource URLs used in Chef Infra Client runs. This is the recommended setting.

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

Default value: :verify_peer.

trusted_certs_dir

A directory that contains additional SSL certificates to trust. Any certificates in this directory will be added to whatever CA bundle ruby is using. Use this to add self-signed certs for your Chef Infra Server or local HTTP file servers.

Default value: trusted_certs directory in your chef configuration directory.

umask

The file mode creation mask, or umask.

Default value: 0022.

use_policyfile

Chef Infra Client automatically checks the configuration, node JSON, and the stored node on the Chef Infra Server to determine if Policyfile files are in use, and then automatically updates this flag.

Default value: false.

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 chef-validator key that Chef Infra Client uses to access the Chef Infra Server during the initial Chef Infra Client run. This is only used by the legacy validator based bootstrapping.

validation_key

The location of the file that contains the key used when a Chef Infra Client is registered with a Chef Infra Server. A validation key is signed using the validation_client_name for authentication.

Default value: /etc/chef/validation.pem. This is only used by the legacy validator based bootstrapping.

verbose_logging

Set the log level. Options: true, nil, and false. When this is set to false, notifications about individual resources being processed are suppressed (and are output at the :info logging level). Setting this to false can be useful when a Chef Infra Client is run as a daemon.

Default value: nil.

verify_api_cert

Verify the SSL certificate on the Chef Infra Server. When true, Chef Infra Client always verifies the SSL certificate. When false, Chef Infra Client uses the value of ssl_verify_mode to determine if the SSL certificate requires verification.

Default value: false.

Automatic Proxy Config

If http_proxy, https_proxy, ftp_proxy, or no_proxy is set in the client.rb file but not set in the ENV, Chef Infra Client will configure the ENV variable based on these (and related) settings. For example:

http_proxy 'http://proxy.example.org:8080'
http_proxy_user 'myself'
http_proxy_pass 'Password1'

Or an alternative way to define the proxy (if the previous version does not work):

http_proxy 'http://myself:Password1@proxy.example.org:8080'

will be set to:

ENV['http_proxy'] = 'http://myself:Password1@proxy.example.org:8080'

.d Directories

You can use multiple configuration files by putting them in .d configuration directories, for example /etc/chef/client.d.

To use a .d directory, create a directory with the same name as the configuration file but replace the .rb suffix with .d.

The default locations for .d directories in Chef Infra are:

For Chef Infra Client, use /etc/chef/client.d.
For Chef development tooling such as knife, use ~/.chef/config.d.
For Chef Solo, use /etc/chef/solo.d.

The standard .rb configuration file and all configuration .rb files in the .d directory are merged as one file. For example, knife would load and merge the following files:

~/.chef/config.rb
~/.chef/config.d/company_settings.rb
~/.chef/config.d/ec2_configuration.rb

Non-.rb files in a .d directory are ignored, for example old_settings.rb.bak.

Note

If you have the same setting in multiple configuration files, ensure that it has the same value in all files.

Ohai Settings

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

ohai.directory

The directory in which Ohai plugins are located.

ohai.disabled_plugins

An array of Ohai plugins to be disabled on a node. The list of plugins included in Ohai can be found in the ohai/lib/ohai/plugins source. For example, disabling a single plugin:

ohai.disabled_plugins = [
  :MyPlugin
]

or disabling multiple plugins:

ohai.disabled_plugins = [
  :MyPlugin,
  :MyPlugin2,
  :MyPlugin3
]

When a plugin is disabled, the Chef Infra Client log file will contain entries similar to:

[2014-06-13T23:49:12+00:00] DEBUG: Skipping disabled plugin MyPlugin

ohai.hints_path

The path to the file that contains hints for Ohai.

ohai.log_level

The level of logging to be stored in a log file.

ohai.log_location

The location of the log file.

ohai.plugin_path

An array of paths at which Ohai plugins are located. Default value: [<CHEF_GEM_PATH>/ohai-9.9.9/lib/ohai/plugins]. When custom Ohai plugins are added, the paths must be added to the array. For example, a single plugin:

ohai.plugin_path << '/etc/chef/ohai_plugins'

and for multiple plugins:

ohai.plugin_path += [
  '/etc/chef/ohai_plugins',
  '/path/to/other/plugins'
  ]

Note

The Ohai executable ignores settings in the client.rb file when Ohai is run independently of Chef Infra Client.

Example

A sample client.rb file that contains the most simple way to connect to Hosted Chef

chef_server_url  'https://api.chef.io/organizations/<orgname>'
validation_client_name '<orgname>-validator'
validation_key '/etc/chef/validator.pem'
client_key '/etc/chef/client.pem'