--- name: "chef-client" section: "8" platform: "linux" package: "chef" version: "13.8.7-4" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/chef-client" --- # chef-client(8) The man page for the chef-client command line tool. 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: The chef-client executable is run as a command-line tool. NOTE: ## NAME chef-client - The man page for the chef-client command line tool. 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: # ``` 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 ``` ## AUTHOR Chef