Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CHEF-CLIENT(8)			  chef-client			CHEF-CLIENT(8)

       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,

       o Registering and authenticating	the node with the Chef server

       o Building the node object

       o Synchronizing cookbooks

       o Compiling the resource	collection by loading  each  of	 the  required
	 cookbooks, including recipes, attributes, and all other dependencies

       o Taking	the appropriate	and required actions to	configure the node

       o Looking for exceptions	and notifications, handling each as required

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

	  A  client.rb	file  is used to specify the configuration details for
	  the chef-client.

	  o This file is loaded	every time this	executable is run

	  o 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

	  o This file is not created by	default

	  o When  a  client.rb file is present in this directory, the settings
	    contained within that file will override the default configuration

       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	speci-
	      fied---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 sin-
	      gle 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  re-
	      source  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.

	      Use to show formatter output instead of logger output.

	      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 val-
	      ues 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": [

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

	      In  certain  situations this option may be used to update	normal

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

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

		 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": ""

       -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	start-
	      ing any executable as a daemon. Default value: STDOUT.

	      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  op-
	      tion  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-exe-

       -r RUN_LIST_ITEM, --runlist RUN_LIST_ITEM
	      Use to permanently replace the current run-list with the	speci-
	      fied run-list items.

       -R, --enable-reporting
	      Use  to  enable  Chef  reporting,	which performs data collection
	      during a chef-client run.

	      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 de-
	      termine  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.

	      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 de-
	      cisions 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 com-
	      mands that work against the Chef server to also work against the
	      local chef-repo.

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

       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:

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

       o Use su	to become the root user, and then run the chef-client. For ex-

		$ su

	    and	then:

		$ chef-client

       o Use the sudo utility

		$ sudo chef-client

       o 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

       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:

       o Log in	to the administrator account. (This is not the same as an  ac-
	 count in the administrator's security group.)

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

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

	    This will prompt for the administrator account password.

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

       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


				   Chef	12.0			CHEF-CLIENT(8)


Want to link to this manual page? Use this URL:

home | help