Provided by: chef_12.3.0-3ubuntu1_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,

       · 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


       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:

       -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,
                 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: /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.

              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:

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

              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.

              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.


       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

       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

                $ 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)