# chef-client

A chef-client is an agent that runs locally on every node that is under management by Chef. 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 Chef 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 is 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 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

## Options

This command has the following syntax:

    chef-client OPTION VALUE OPTION VALUE ...

This command has the following options:

`-A`, `--fatal-windows-admin-check`
  Use to cause a chef-client run to fail when the chef-client does not have administrator privileges in Microsoft Windows.
`--chef-zero-port PORT`
  The port on which chef-zero will listen. If a port is not specified—individually, as range of ports, or from the `chef_zero.port` setting in the client.rb file—the chef-client will scan for ports between 8889-9999 and will pick the first port that is available.
`-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`
  Use to show formatter output instead of logger output.
`--force-logger`
  Use to show logger output 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. When the chef-client is run at intervals, `--splay` and `--interval` values are applied before the chef-client run. Default value: `1800`.
`-j PATH`, `--json-attributes PATH`

  The path to a file that contains JSON data.

  Use this option to define a `run_list` object. For example, a JSON file similar to:

      "run_list": [
        "recipe[base]",
        "recipe[foo]",
        "recipe[bar]",
        "role[webserver]"
      ],

  may be used by running `chef-client -j path/to/file.json`.

  In certain situations this option may be used to update `normal` attributes.

  Warning

  Any other attribute type that is contained in this JSON file will be treated as a `normal` attribute. For example, attempting to update `override` attributes using the `-j` option:

      {
        "name": "dev-99",
        "description": "Install some stuff",
        "override_attributes": {
          "apptastic": {
            "enable_apptastic": "false",
            "apptastic_tier_name": "dev-99.bomb.com"
          }
        }
      }

  will result in a node object similar to:

      {
        "name": "maybe-dev-99",
        "normal": {
        "name": "dev-99",
          "description": "Install some stuff",
          "override_attributes": {
            "apptastic": {
              "enable_apptastic": "false",
              "apptastic_tier_name": "dev-99.bomb.com"
            }
          }
        }
      }

`-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 Chef 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`
  Use to view colored output. 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. This option will not clear the list of cookbooks (and related files) that is cached on the node.
`--once`
  Use to run the chef-client only once and to cancel `interval` and `splay` options.
`-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 RUN_LIST_ITEM`, `--runlist RUN_LIST_ITEM`
  Use to permanently replace the current run-list with the specified run-list items.
`-R`, `--enable-reporting`
  Use to enable Chef reporting, which performs data collection during a chef-client run.
`RECIPE_FILE`
  The path to a recipe. For example, if a recipe file is in the current directory, use `recipe_file.rb`. This is typically used with the `--local-mode` option.
`--run-lock-timeout SECONDS`
  The amount of time (in seconds) to wait for a chef-client run to finish. Default value: not set (indefinite). Set to `0` to cause a second chef-client to exit immediately.
`-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. When the chef-client is run at intervals, `--splay` and `--interval` values are applied before the chef-client run.
`-S CHEF_SERVER_URL`, `--server CHEF_SERVER_URL`
  The URL for the Chef 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`
  Use to run the executable 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`
  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.

## 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