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.

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

Checksums of files used in remote_file and template Resources are stored in a cache using Moneta, which can be configured using these options.

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 specified for the server must match the same name when with the client configuration.

Context: chef-client, chef-server

chef_server_url

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 https://api.opscode.com/organizations/ORGNAME, 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

client_url

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

Context: chef-client

client_registration_retries

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

Context: chef-client

cookbook_path

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.

Context:

* 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.

cookbook_tarball_path

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

Context: chef-server

couchdb_*

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

data_bag_path

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

Context: chef-solo

environment

Context:

* 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.

file_cache_path

Where to locally store cache files like cookbooks and other transient data.

Context:

* chef-solo - When downloading cookbooks from a remote URL, store them in this location.
* chef-client - Where synchronized cookbooks are stored.

This value can also be used in Recipes to download files with the remote_file resource.

file_backup_path

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

http_retry_*

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

json_attribs

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

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:

Context: All executables

node_name

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 [LEG:Authentication]. The default value is set automatically to the fully qualified domain name (fqdn) as detected by Ohai.

Context: chef-solo, chef-client

node_path

Location to look for node-specific recipes.

Context: chef-solo, chef-client

pid_file

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

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

recipe_url

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

Context: chef-solo

rest_timeout

Timeout for HTTP REST requests

Context: All executables.

role_path

Where Chef Solo should look for role files.

Context: chef-solo.

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 [LEG: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.

umask

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 username.myopenid.com or http://username.myopenid.com.
• providers are the OpenID provider like myopenid.com.

Context: chef-server-webui

signing_ca settings

Chef automatically generates the CA certificate and key for the [LEG: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 [LEG: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).