Provided by: chef_13.8.7-4_all bug


       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.

          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


       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.

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

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

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

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

                 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:

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

              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/

       -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

              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

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

              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

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


       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.

       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

       · 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

       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


       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)