# chef-client

A chef-client is an agent that runs locally on every node that is registered with the server. When a chef-client is run, it will perform all of the steps that are required to bring the node into the expected state, including:

- Registering and authenticating the node with the server
- Building the node object
- Synchronizing cookbooks
- Compiling the resource collection by loading each of the required cookbooks, including recipes, attributes, and all other dependencies
- Taking the appropriate and required actions to configure the node
- Looking for exceptions and notifications, handling each as required

The chef-client executable can be run as a command-line tool.

Note

A client.rb file is used to specify the configuration details for the chef-client. This file is the default configuration file and is loaded every time the chef-client executable is run. The chef-client executable can be run as a daemon. On UNIX- and Linux-based machines, the configuration file is located at: `/etc/chef/client.rb`. On Microsoft Windows machines, the configuration file is located at `C:\chef\client.rb`.

## Options

This command has the following syntax:

    chef-client OPTION VALUE OPTION VALUE ...

This command has the following options:

`-A`, `--fatal-windows-admin-check`
  Indicates that a chef-client run should fail if the chef-client does not have administrator privileges in Microsoft Windows.
`--chef-zero-port PORT`
  The port on which chef-zero will listen.
`-F FORMAT`, `--format FORMAT`

  The output format: `doc` (default) or `min`.

  Use `doc` to print the progress of the chef-client run using full strings that display a summary of updates as they occur.

  Use `min` to print the progress of the chef-client run using single characters. A summary of updates is printed at the end of the chef-client run. A dot (`.`) is printed for events that do not have meaningful status information, such as loading a file or synchronizing a cookbook. For resources, a dot (`.`) is printed when the resource is up to date, an `S` is printed when the resource is skipped by `not_if` or `only_if`, and a `U` is printed when the resource is updated.

  Other formatting options are available when those formatters are configured in the client.rb file using the `add_formatter` option.

`--force-formatter`
  Indicates that formatter output will be used instead of logger output.
`--force-logger`
  Indicates that logger output will be used instead of formatter output.
`-g GROUP`, `--group GROUP`
  The name of the group that owns a process. This is required when starting any executable as a daemon.
`-h`, `--help`
  Shows help for the command.
`-i SECONDS`, `--interval SECONDS`
  The frequency (in seconds) at which the chef-client runs. Default value: `1800`.
`-j PATH`, `--json-attributes PATH`
  The path to a file that contains JSON data.
`-k KEY_FILE`, `--client_key KEY_FILE`
  The location of the file which contains the client key. Default value: `/etc/chef/client.pem`.
`-K KEY_FILE`, `--validation_key KEY_FILE`
  The location of the file which contains the key used when a chef-client is registered with a server. A validation key is signed using the `validation_client_name` for authentication. Default value: `/etc/chef/validation.pem`.
`-l LEVEL`, `--log_level LEVEL`
  The level of logging that will be stored in a log file.
`-L LOGLOCATION`, `--logfile c`
  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). This is recommended when starting any executable as a daemon. Default value: `STDOUT`.
`--[no-]color`
  Indicates whether colored output will be used. Default setting: `--color`.
`-N NODE_NAME`, `--node-name NODE_NAME`
  The name of the node.
`-o RUN_LIST_ITEM`, `--override-runlist RUN_LIST_ITEM`
  Replace the current run list with the specified items.
`--once`
  Indicates that the chef-client is run once and that interval and splay options are cancelled.
`-P PID_FILE`, `--pid 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`.
`-R`, `--enable-reporting`
  Indicates that data collection reporting is enabled during a chef-client run.
`-s SECONDS`, `--splay SECONDS`
  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.
`-S CHEF_SERVER_URL`, `--server CHEF_SERVER_URL`
  The URL for the server.
`-u USER`, `--user USER`
  The user that owns a process. This is required when starting any executable as a daemon.
`-v`, `--version`
  The version of the chef-client.
`-W`, `--why-run`
  Indicates that the executable will be run in why-run mode, which is a type of chef-client run that does everything except modify the system. Use why-run mode to understand why the chef-client makes the decisions that it makes and to learn more about the current and proposed state of the system.
`-z`, `--local-mode`
  Indicates that the chef-client will be run in local mode, which allows all commands that work against the server to also work against the local chef-repo.

## Run with Elevated Privileges

The chef-client may need to be run with elevated privileges in order to get a recipe to converge correctly. On UNIX and UNIX-like operating systems this can be done by running the command as root. On Microsoft Windows this can be done by running the command prompt as an administrator.

### Linux

On Linux, the following error sometimes occurs when the permissions used to run the chef-client are incorrect:

    $ chef-client
    [Tue, 29 Nov 2011 19:46:17 -0800] INFO: *** Chef 10.X.X ***
    [Tue, 29 Nov 2011 19:46:18 -0800] WARN: Failed to read the private key /etc/chef/client.pem: #<Errno::EACCES: Permission denied - /etc/chef/client.pem>

This can be resolved by running the command as root. There are a few ways this can be done:

- Log in as root and then run the chef-client

- Use `su` to become the root user, and then run the chef-client. For example:

  >     $ su

and then:

>     $ chef-client

- Use the sudo utility

  >     $ sudo chef-client

- Give a user access to read `/etc/chef` and also the files accessed by the chef-client. This requires super user privileges and, as such, is not a recommended approach

### Windows

On Microsoft Windows, running without elevated privileges (when they are necessary) is an issue that fails silently. It will appear that the chef-client completed its run successfully, but the changes will not have been made. When this occurs, do one of the following to run the chef-client as the administrator:

- Log in to the administrator account. (This is not the same as an account in the administrator’s security group.)

- Run the chef-client process from the administrator account while being logged into another account. Run the following command:

  >     $ runas /user:Administrator "cmd /C chef-client"

  > This will prompt for the administrator account password.

- Open a command prompt by right-clicking on the command prompt application, and then selecting Run as administrator. After the command window opens, the chef-client can be run as the administrator

## Examples

Start a Chef run when the chef-client is running as a daemon

A chef-client that is running as a daemon can be woken up and started by sending the process a `SIGUSR1`. For example, to trigger a chef-client run on a machine running Linux:

    $ sudo killall -USR1 chef-client

Start a Chef run manually

    $ ps auxw|grep chef-client

to return something like:

    root           66066   0.9  0.0  2488880    264 s001  S+   10:26AM   0:03.05
    /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/ruby /usr/bin/chef-client -i 3600 -s 20

and then enter:

    $ sudo kill -USR1 66066