These topics are about older versions of Chef. and are no longer actively maintained by Opscode or the Chef community. To read the current documentation for Chef, see
Skip to end of metadata
Go to start of metadata

This content has been moved to

See the following links:

This document describes all the configuration settings available for the Chef executables.

Chef Executables

Each Chef executable is configured through the Chef::Config object. When the executables are run, they load the default config file. Some settings are applicable only when the executable is run as a daemon, so whether daemonizing is possible is noted here.


Config File


























If the file is not found, default values are used from Chef::Config.

In this page, settings are first listed in the Ruby DSL context, followed by a description of the setting and applicable executable context. Similar settings, such as those used only in the webui, are grouped together.

Ruby DSL

These files are written using a Ruby DSL that specifies the setting and its value. Some values will be specified as strings, others as Integers, Floats or Arrays.

Configuration values

amqp settings

These are for the AMQP host and vhost connection. For the consumer_id, chef-indexer is prepended automatically.

Context: chef-server, chef-solr, chef-solr-indexer

cache settings

cache_options: The option(s) to be used when caching. The options available depend on the type of cache being used.

cache_type: The type of cache to use. This can be any type of cache that is supported by the Moneta library (, including basic file stores, file systems with xattrs, DataMapper, Amazon S3, Berkely DB, MongoDB, Redis, SBDM, Tokyo Cabinet, CouchDB, and so on. The default value is: BasicFile.

Context: chef-solo, chef-client

certificate settings

Authenticate the client using the file named in client_key. Use the valdiation_key to automatically register a new client with the server. The validation_key is signed using the validation_client_name for authentication. The validation_client_name located in the server and client configuration files must match.

Context: chef-client, chef-server


Specifies the Chef Server to connect to. Can be any valid HTTP URL, including HTTPS. Learn more about the Chef Server.

When using the Opscode Platform, this will be, where ORGNAME is your organization short name that you created when signing up for the service.

Context: chef-client, chef-server, chef-server-webui, Knife


Specify the URL clients should use to connect to for registering with the server.

Context: chef-client


The number of times the client should attempt to register with the server.

Context: chef-client


A string or array of filesystem locations to search for cookbooks. Processed in the order specified so that the first is considered "upstream" and the last is considered overriding local modifications.


* chef-solo - Loads cookbooks from the specified directory.
* chef-client - Set to the 'cookbooks' subdirectory under Chef::Config:file_cache_path at runtime.
* chef-server - Used for storing cookbook tarball artifacts.
* knife - used for uploading, see Knife's documentation.


Location where the Chef Server stores cookbook tarballs for distribution to clients.

Context: chef-server


Configure CouchDB settings for the Chef Server. These specify the database and URL to use, as well as the version. Chef attempts to determine the CouchDB version at runtime, and this setting is used to determine what API capability can be used.

Context: chef-server


Location where chef-solo can load data bag json files from.

Context: chef-solo



* chef-client - with -E or in the client.rb config file sets the environment for the node running chef.
* knife - with -E or in knife.rb sets the environment for relevant knife commands such as knife bootstrap, cloud creation, and more. See Knife's documentation.


The location in which cookbooks (and other transient data) files are stored when they are synchronized with Chef. (This value can also be used in recipes to download files with the ``remote_file`` resource.)

When using Chef Solo, the location in which cookbooks (and other transient data) files are stored after they have been downloaded from a remote URL. (This value can also be used in recipes to download files with the ``remote_file`` resource.)


Configurable location to store backups of files instead of the directory of the target file, for template, remote_file and file Resources.

Context: chef-solo, chef-client

user and group

System user and group to own the process. Applicable when starting any of the executables as a daemon.

Context: chef-client, chef-server, chef-server-webui, chef-solr, chef-solr-indexer

http_proxy*, https_proxy, no_proxy

Specify the proxy server for HTTP/HTTPS with the http_proxy and https_proxy settings respectively. If the proxy server requires a username and password, use http_proxy_user and http_proxy_pass. For URLs that don't need a proxy, specify a comma separated list of URLs to exclude from proxying with no_proxy.

For example:

Context: chef-client, knife


Number of times to retry HTTP connections, and the delay between each retry, respectively.

Context: chef-client

interval and splay

Run the client on the specified interval, in seconds. The default value is 1800, configured in the chef-client application run time, rather than in the Chef::Config. The splay value is a random number of seconds to add to the interval to reduce potential server load of many clients running at the same time.

Context: chef-client


Specify JSON attributes, including a default run_list, for the node. Overrides whatever other attributes are set from other places like Cookbooks and Roles.

Context: chef-solo, chef-client


Chef 11.0 Only

This configures a feature that is only in the Chef 11 (alpha/development) branch. The feature does not exist in Chef 10.x, so setting it will have no effect.

Chef uses (as of Chef 11) an exclusive lock to ensure that only one instance of chef-client (or solo) is modifying the system at a time. By default, the lock file is located in the file_cache_path so that intentional uses of multiple chef clients will work automatically. If file_cache_path is located on a NFS mount you should choose a different lock file location.

Context: chef-solo, chef-client

log output

Settings for log output. When Chef runs, it will display messages of the log_level or higher, to the specified log_location. If the log_location is set to another location than STDOUT, verbose_logging will tell Chef to also log to STDOUT, otherwise there would be no output other than to the file.

Chef uses Opscode mixlib-log library to handle logging. See Advanced Configuration Settings with Ruby for information on how to log Chef executable output to Unix syslog.

Valid log_levels are, in order of priority:

  • :debug
  • :info
  • :warn
  • :error
  • :fatal

In Chef 0.10.6+, setting verbose_logging to false will suppress notifications about individual resources being processed. These notifications are output at the :info log level. Setting verbose_logging to false can be useful for running chef-client as a daemon. Below is an example of the difference in output when verbose_logging is set to false:

verbose_logging set to true or nil
verbose_logging set to false

Context: All executables


Sets the name of this node, which determines what configuration to apply. Learn more about Nodes. Also sets the client_name, which is used as the name to use when authenticating with a Chef Server. Learn more about Authentication. The default value is set automatically to the fully qualified domain name (fqdn) as detected by Ohai.

Context: chef-solo, chef-client


Location to look for node-specific recipes.

Context: chef-solo, chef-client


When started as a daemon, the executable will write the PID to the specified file. Otherwise, it will use /tmp/

Context: chef-client, chef-server, chef-solr, chef-solr-indexer


URL location of remote cookbook tarball to download with Chef Solo.

Context: chef-solo


Timeout for HTTP REST requests

Context: All executables.


Where Chef Solo should look for role files.

Context: chef-solo.


Whether Chef is being run in "solo" mode or not. Determines if it should attempt to communicate with a Chef Server. It gets set automatically when running chef-solo and if running Shef in solo mode.

Context: chef-solo, Shef.

solr settings

URL of the Solr search engine server.

Context: chef-server, chef-solr, chef-solr-indexer

Settings that control the Solr jetty environment. Points to the jetty environment, the Solr indexes, Solr's home directory, the amount of memory for the JVM running Solr and additional options to pass to Solr's Java, respectively.

Context: chef-solr, chef-solr-indexer

ssl settings

Settings used to create certificate files used for client/server Authentication. These are OpenSSL X509 certificate, key and the CA.

These values are generated automatically and used internally. Most users won't need to modify these settings.

Context: chef-client, chef-server, chef-server-webui

Controls HTTP verify mode, can be none or peer, for HTTPS requests.

Opscode Hosted Chef customers can use :verify_peer as the ssl_verify_mode. Depending on how OpenSSL was installed, the CA path may need to be specified. For example, on an Ubuntu system:

Context: All executables.

upload settings

The checksum_path is the location in which checksums for individual cookbook files (such as recipes) are stored. The checksum itself is stored in CouchDB and is used to reference a file with a filename that is identical to the checksum.

The sandbox_path is the location in which cookbook files are stored (temporarily) during upload.

Context: chef-solo


Default file creation umask.

Context: All executables.

webui options

The Chef Server WebUI is a client to the Chef Server API. It must have a corresponding client name and a client key, specified here. The WebUI default login user for humans is specified with the default password here. The password should be changed immediately when logging in.

With Knife, the chef-webui client and certificate are used to create the initial API client with Knife's -i option.

Context: chef-server-webui, Knife

OpenID is now only used in the Chef Server WebUI. It is optional. WebUI login users can have an OpenID associated. The OpenIDs are not by default stored in CouchDB, instead in the specified location on the filesystem. The difference between identifiers and providers is:

  • identifiers are the actual OpenID like or
  • providers are the OpenID provider like

Context: chef-server-webui

signing_ca settings

Chef automatically generates the CA certificate and key for the Authentication keys it uses. These settings are passed to OpenSSL.

Context: chef-server

Unused Settings

The following unused settings never had their potential fulfilled and may be used in the future.

Deprecated Settings

The following settings are deprecated and no longer used in Chef. They are kept here for historical purposes.

Specifies alternate URLs for various services provided by the Chef Server. "Deprecated" in favor of chef_server_url. These URLs can still be used to split out Chef Server API functionality, but that is an undocumented capability of the Chef Server.

Use http_retry_delay instead.

Originally used to automatically validate new clients. Deprecated for validation_key and validation_client_name.

These settings are deprecated in Chef 0.8+ due to the OpenID authentication scheme for nodes changing to the new pre-shared key based Authentication. OpenID is still used as an optional authentication method for users to the WebUI.

These settings were used for configuring the STOMP queue, which has been deprecated for AMQP (RabbitMQ).

  • None
  1. Jul 31, 2012

    http(s)_proxy setting

    Be sure to test that your proxy server (squid for example) is not caching API replies too aggressively.
    In squid3 I disabled caching of the Chef API using a 'cache deny' ACL