diff options
Diffstat (limited to 'distro/common/html/ctl_chef_client.html')
-rw-r--r-- | distro/common/html/ctl_chef_client.html | 270 |
1 files changed, 0 insertions, 270 deletions
diff --git a/distro/common/html/ctl_chef_client.html b/distro/common/html/ctl_chef_client.html deleted file mode 100644 index dbdca11487..0000000000 --- a/distro/common/html/ctl_chef_client.html +++ /dev/null @@ -1,270 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - - <title>chef-client — chef-client Man Pages</title> - - <link rel="stylesheet" href="_static/guide.css" type="text/css" /> - <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> - - <script type="text/javascript"> - var DOCUMENTATION_OPTIONS = { - URL_ROOT: './', - VERSION: '', - COLLAPSE_INDEX: false, - FILE_SUFFIX: '.html', - HAS_SOURCE: true - }; - </script> - <script type="text/javascript" src="_static/jquery.js"></script> - <script type="text/javascript" src="_static/underscore.js"></script> - <script type="text/javascript" src="_static/doctools.js"></script> - - - </head> - <body> -<div style="background-color: #212c35; text-align: left; padding: 0px 0px 0px 0px"> -<a href="http://docs.getchef.com/"><img src="_static/chef_html_logo.png" border="0" alt="Chef"/></a> -</div> - - - - - <div class="document"> - <div class="documentwrapper"> - - <div class="body"> - - <div class="section" id="chef-client"> -<h1>chef-client<a class="headerlink" href="#chef-client" title="Permalink to this headline">¶</a></h1> -<p>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:</p> -<ul class="simple"> -<li>Registering and authenticating the node with the Chef server</li> -<li>Building the node object</li> -<li>Synchronizing cookbooks</li> -<li>Compiling the resource collection by loading each of the required cookbooks, including recipes, attributes, and all other dependencies</li> -<li>Taking the appropriate and required actions to configure the node</li> -<li>Looking for exceptions and notifications, handling each as required</li> -</ul> -<p>The chef-client executable is run as a command-line tool.</p> -<div class="admonition note"> -<p class="first admonition-title">Note</p> -<p>A client.rb file is used to specify the configuration details for the chef-client.</p> -<ul class="last simple"> -<li>This file is loaded every time this executable is run</li> -<li>On UNIX- and Linux-based machines, the default location for this file is <tt class="docutils literal"><span class="pre">/etc/chef/client.rb</span></tt>; on Microsoft Windows machines, the default location for this file is <tt class="docutils literal"><span class="pre">C:\chef\client.rb</span></tt>; use the <tt class="docutils literal"><span class="pre">--config</span></tt> option from the command line to change this location</li> -<li>This file is not created by default</li> -<li>When a client.rb file is present in this directory, the settings contained within that file will override the default configuration settings</li> -</ul> -</div> -<div class="section" id="options"> -<h2>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2> -<p>This command has the following syntax:</p> -<div class="highlight-python"><div class="highlight"><pre>chef-client OPTION VALUE OPTION VALUE ... -</pre></div> -</div> -<p>This command has the following options:</p> -<dl class="docutils"> -<dt><tt class="docutils literal"><span class="pre">-A</span></tt>, <tt class="docutils literal"><span class="pre">--fatal-windows-admin-check</span></tt></dt> -<dd>Use to cause a chef-client run to fail when the chef-client does not have administrator privileges in Microsoft Windows.</dd> -<dt><tt class="docutils literal"><span class="pre">--chef-zero-port</span> <span class="pre">PORT</span></tt></dt> -<dd>The port on which chef-zero will listen. If a port is not specified—individually, as range of ports, or from the <tt class="docutils literal"><span class="pre">chef_zero.port</span></tt> 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.</dd> -<dt><tt class="docutils literal"><span class="pre">-F</span> <span class="pre">FORMAT</span></tt>, <tt class="docutils literal"><span class="pre">--format</span> <span class="pre">FORMAT</span></tt></dt> -<dd><p class="first">The output format: <tt class="docutils literal"><span class="pre">doc</span></tt> (default) or <tt class="docutils literal"><span class="pre">min</span></tt>.</p> -<p>Use <tt class="docutils literal"><span class="pre">doc</span></tt> to print the progress of the chef-client run using full strings that display a summary of updates as they occur.</p> -<p>Use <tt class="docutils literal"><span class="pre">min</span></tt> 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 (<tt class="docutils literal"><span class="pre">.</span></tt>) is printed for events that do not have meaningful status information, such as loading a file or synchronizing a cookbook. For resources, a dot (<tt class="docutils literal"><span class="pre">.</span></tt>) is printed when the resource is up to date, an <tt class="docutils literal"><span class="pre">S</span></tt> is printed when the resource is skipped by <tt class="docutils literal"><span class="pre">not_if</span></tt> or <tt class="docutils literal"><span class="pre">only_if</span></tt>, and a <tt class="docutils literal"><span class="pre">U</span></tt> is printed when the resource is updated.</p> -<p class="last">Other formatting options are available when those formatters are configured in the client.rb file using the <tt class="docutils literal"><span class="pre">add_formatter</span></tt> option.</p> -</dd> -<dt><tt class="docutils literal"><span class="pre">--force-formatter</span></tt></dt> -<dd>Use to show formatter output instead of logger output.</dd> -<dt><tt class="docutils literal"><span class="pre">--force-logger</span></tt></dt> -<dd>Use to show logger output instead of formatter output.</dd> -<dt><tt class="docutils literal"><span class="pre">-g</span> <span class="pre">GROUP</span></tt>, <tt class="docutils literal"><span class="pre">--group</span> <span class="pre">GROUP</span></tt></dt> -<dd>The name of the group that owns a process. This is required when starting any executable as a daemon.</dd> -<dt><tt class="docutils literal"><span class="pre">-h</span></tt>, <tt class="docutils literal"><span class="pre">--help</span></tt></dt> -<dd>Shows help for the command.</dd> -<dt><tt class="docutils literal"><span class="pre">-i</span> <span class="pre">SECONDS</span></tt>, <tt class="docutils literal"><span class="pre">--interval</span> <span class="pre">SECONDS</span></tt></dt> -<dd>The frequency (in seconds) at which the chef-client runs. When the chef-client is run at intervals, <tt class="docutils literal"><span class="pre">--splay</span></tt> and <tt class="docutils literal"><span class="pre">--interval</span></tt> values are applied before the chef-client run. Default value: <tt class="docutils literal"><span class="pre">1800</span></tt>.</dd> -<dt><tt class="docutils literal"><span class="pre">-j</span> <span class="pre">PATH</span></tt>, <tt class="docutils literal"><span class="pre">--json-attributes</span> <span class="pre">PATH</span></tt></dt> -<dd><p class="first">The path to a file that contains JSON data.</p> -<p>Use this option to define a <tt class="docutils literal"><span class="pre">run_list</span></tt> object. For example, a JSON file similar to:</p> -<div class="highlight-javascript"><div class="highlight"><pre><span class="s2">"run_list"</span><span class="o">:</span> <span class="p">[</span> - <span class="s2">"recipe[base]"</span><span class="p">,</span> - <span class="s2">"recipe[foo]"</span><span class="p">,</span> - <span class="s2">"recipe[bar]"</span><span class="p">,</span> - <span class="s2">"role[webserver]"</span> -<span class="p">],</span> -</pre></div> -</div> -<p>may be used by running <tt class="docutils literal"><span class="pre">chef-client</span> <span class="pre">-j</span> <span class="pre">path/to/file.json</span></tt>.</p> -<p>In certain situations this option may be used to update <tt class="docutils literal"><span class="pre">normal</span></tt> attributes.</p> -<div class="last admonition warning"> -<p class="first admonition-title">Warning</p> -<p>Any other attribute type that is contained in this JSON file will be treated as a <tt class="docutils literal"><span class="pre">normal</span></tt> attribute. For example, attempting to update <tt class="docutils literal"><span class="pre">override</span></tt> attributes using the <tt class="docutils literal"><span class="pre">-j</span></tt> option:</p> -<div class="highlight-javascript"><div class="highlight"><pre><span class="p">{</span> - <span class="s2">"name"</span><span class="o">:</span> <span class="s2">"dev-99"</span><span class="p">,</span> - <span class="s2">"description"</span><span class="o">:</span> <span class="s2">"Install some stuff"</span><span class="p">,</span> - <span class="s2">"override_attributes"</span><span class="o">:</span> <span class="p">{</span> - <span class="s2">"apptastic"</span><span class="o">:</span> <span class="p">{</span> - <span class="s2">"enable_apptastic"</span><span class="o">:</span> <span class="s2">"false"</span><span class="p">,</span> - <span class="s2">"apptastic_tier_name"</span><span class="o">:</span> <span class="s2">"dev-99.bomb.com"</span> - <span class="p">}</span> - <span class="p">}</span> -<span class="p">}</span> -</pre></div> -</div> -<p>will result in a node object similar to:</p> -<div class="last highlight-javascript"><div class="highlight"><pre><span class="p">{</span> - <span class="s2">"name"</span><span class="o">:</span> <span class="s2">"maybe-dev-99"</span><span class="p">,</span> - <span class="s2">"normal"</span><span class="o">:</span> <span class="p">{</span> - <span class="s2">"name"</span><span class="o">:</span> <span class="s2">"dev-99"</span><span class="p">,</span> - <span class="s2">"description"</span><span class="o">:</span> <span class="s2">"Install some stuff"</span><span class="p">,</span> - <span class="s2">"override_attributes"</span><span class="o">:</span> <span class="p">{</span> - <span class="s2">"apptastic"</span><span class="o">:</span> <span class="p">{</span> - <span class="s2">"enable_apptastic"</span><span class="o">:</span> <span class="s2">"false"</span><span class="p">,</span> - <span class="s2">"apptastic_tier_name"</span><span class="o">:</span> <span class="s2">"dev-99.bomb.com"</span> - <span class="p">}</span> - <span class="p">}</span> - <span class="p">}</span> -<span class="p">}</span> -</pre></div> -</div> -</div> -</dd> -<dt><tt class="docutils literal"><span class="pre">-k</span> <span class="pre">KEY_FILE</span></tt>, <tt class="docutils literal"><span class="pre">--client_key</span> <span class="pre">KEY_FILE</span></tt></dt> -<dd>The location of the file which contains the client key. Default value: <tt class="docutils literal"><span class="pre">/etc/chef/client.pem</span></tt>.</dd> -<dt><tt class="docutils literal"><span class="pre">-K</span> <span class="pre">KEY_FILE</span></tt>, <tt class="docutils literal"><span class="pre">--validation_key</span> <span class="pre">KEY_FILE</span></tt></dt> -<dd>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 <tt class="docutils literal"><span class="pre">validation_client_name</span></tt> for authentication. Default value: <tt class="docutils literal"><span class="pre">/etc/chef/validation.pem</span></tt>.</dd> -<dt><tt class="docutils literal"><span class="pre">-l</span> <span class="pre">LEVEL</span></tt>, <tt class="docutils literal"><span class="pre">--log_level</span> <span class="pre">LEVEL</span></tt></dt> -<dd>The level of logging that will be stored in a log file.</dd> -<dt><tt class="docutils literal"><span class="pre">-L</span> <span class="pre">LOGLOCATION</span></tt>, <tt class="docutils literal"><span class="pre">--logfile</span> <span class="pre">c</span></tt></dt> -<dd>The location in which log file output files will be saved. If this location is set to something other than <tt class="docutils literal"><span class="pre">STDOUT</span></tt>, 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: <tt class="docutils literal"><span class="pre">STDOUT</span></tt>.</dd> -<dt><tt class="docutils literal"><span class="pre">--[no-]color</span></tt></dt> -<dd>Use to view colored output. Default setting: <tt class="docutils literal"><span class="pre">--color</span></tt>.</dd> -<dt><tt class="docutils literal"><span class="pre">-N</span> <span class="pre">NODE_NAME</span></tt>, <tt class="docutils literal"><span class="pre">--node-name</span> <span class="pre">NODE_NAME</span></tt></dt> -<dd>The name of the node.</dd> -<dt><tt class="docutils literal"><span class="pre">-o</span> <span class="pre">RUN_LIST_ITEM</span></tt>, <tt class="docutils literal"><span class="pre">--override-runlist</span> <span class="pre">RUN_LIST_ITEM</span></tt></dt> -<dd>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.</dd> -<dt><tt class="docutils literal"><span class="pre">--once</span></tt></dt> -<dd>Use to run the chef-client only once and to cancel <tt class="docutils literal"><span class="pre">interval</span></tt> and <tt class="docutils literal"><span class="pre">splay</span></tt> options.</dd> -<dt><tt class="docutils literal"><span class="pre">-P</span> <span class="pre">PID_FILE</span></tt>, <tt class="docutils literal"><span class="pre">--pid</span> <span class="pre">PID_FILE</span></tt></dt> -<dd>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: <tt class="docutils literal"><span class="pre">/tmp/name-of-executable.pid</span></tt>.</dd> -<dt><tt class="docutils literal"><span class="pre">-r</span> <span class="pre">RUN_LIST_ITEM</span></tt>, <tt class="docutils literal"><span class="pre">--runlist</span> <span class="pre">RUN_LIST_ITEM</span></tt></dt> -<dd>Use to permanently replace the current run-list with the specified run-list items.</dd> -<dt><tt class="docutils literal"><span class="pre">-R</span></tt>, <tt class="docutils literal"><span class="pre">--enable-reporting</span></tt></dt> -<dd>Use to enable Chef reporting, which performs data collection during a chef-client run.</dd> -<dt><tt class="docutils literal"><span class="pre">RECIPE_FILE</span></tt></dt> -<dd>The path to a recipe. For example, if a recipe file is in the current directory, use <tt class="docutils literal"><span class="pre">recipe_file.rb</span></tt>. This is typically used with the <tt class="docutils literal"><span class="pre">--local-mode</span></tt> option.</dd> -<dt><tt class="docutils literal"><span class="pre">--run-lock-timeout</span> <span class="pre">SECONDS</span></tt></dt> -<dd>The amount of time (in seconds) to wait for a chef-client run to finish. Default value: not set (indefinite). Set to <tt class="docutils literal"><span class="pre">0</span></tt> to cause a second chef-client to exit immediately.</dd> -<dt><tt class="docutils literal"><span class="pre">-s</span> <span class="pre">SECONDS</span></tt>, <tt class="docutils literal"><span class="pre">--splay</span> <span class="pre">SECONDS</span></tt></dt> -<dd>A number (in seconds) to add to the <tt class="docutils literal"><span class="pre">interval</span></tt> 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, <tt class="docutils literal"><span class="pre">--splay</span></tt> and <tt class="docutils literal"><span class="pre">--interval</span></tt> values are applied before the chef-client run.</dd> -<dt><tt class="docutils literal"><span class="pre">-S</span> <span class="pre">CHEF_SERVER_URL</span></tt>, <tt class="docutils literal"><span class="pre">--server</span> <span class="pre">CHEF_SERVER_URL</span></tt></dt> -<dd>The URL for the Chef server.</dd> -<dt><tt class="docutils literal"><span class="pre">-u</span> <span class="pre">USER</span></tt>, <tt class="docutils literal"><span class="pre">--user</span> <span class="pre">USER</span></tt></dt> -<dd>The user that owns a process. This is required when starting any executable as a daemon.</dd> -<dt><tt class="docutils literal"><span class="pre">-v</span></tt>, <tt class="docutils literal"><span class="pre">--version</span></tt></dt> -<dd>The version of the chef-client.</dd> -<dt><tt class="docutils literal"><span class="pre">-W</span></tt>, <tt class="docutils literal"><span class="pre">--why-run</span></tt></dt> -<dd>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.</dd> -<dt><tt class="docutils literal"><span class="pre">-z</span></tt>, <tt class="docutils literal"><span class="pre">--local-mode</span></tt></dt> -<dd>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.</dd> -</dl> -</div> -<div class="section" id="run-with-elevated-privileges"> -<h2>Run with Elevated Privileges<a class="headerlink" href="#run-with-elevated-privileges" title="Permalink to this headline">¶</a></h2> -<p>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.</p> -<div class="section" id="linux"> -<h3>Linux<a class="headerlink" href="#linux" title="Permalink to this headline">¶</a></h3> -<p>On Linux, the following error sometimes occurs when the permissions used to run the chef-client are incorrect:</p> -<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>chef-client -<span class="o">[</span>Tue, 29 Nov 2011 19:46:17 -0800<span class="o">]</span> INFO: *** Chef 10.X.X *** -<span class="o">[</span>Tue, 29 Nov 2011 19:46:18 -0800<span class="o">]</span> WARN: Failed to <span class="nb">read </span>the private key /etc/chef/client.pem: <span class="c">#<Errno::EACCES: Permission denied - /etc/chef/client.pem></span> -</pre></div> -</div> -<p>This can be resolved by running the command as root. There are a few ways this can be done:</p> -<ul> -<li><p class="first">Log in as root and then run the chef-client</p> -</li> -<li><p class="first">Use <tt class="docutils literal"><span class="pre">su</span></tt> to become the root user, and then run the chef-client. For example:</p> -<blockquote> -<div><div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>su -</pre></div> -</div> -<p>and then:</p> -<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>chef-client -</pre></div> -</div> -</div></blockquote> -</li> -<li><p class="first">Use the sudo utility</p> -<blockquote> -<div><div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>sudo chef-client -</pre></div> -</div> -</div></blockquote> -</li> -<li><p class="first">Give a user access to read <tt class="docutils literal"><span class="pre">/etc/chef</span></tt> and also the files accessed by the chef-client. This requires super user privileges and, as such, is not a recommended approach</p> -</li> -</ul> -</div> -<div class="section" id="windows"> -<h3>Windows<a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h3> -<p>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:</p> -<ul> -<li><p class="first">Log in to the administrator account. (This is not the same as an account in the administrator’s security group.)</p> -</li> -<li><p class="first">Run the chef-client process from the administrator account while being logged into another account. Run the following command:</p> -<blockquote> -<div><div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>runas /user:Administrator <span class="s2">"cmd /C chef-client"</span> -</pre></div> -</div> -<p>This will prompt for the administrator account password.</p> -</div></blockquote> -</li> -<li><p class="first">Open a command prompt by right-clicking on the command prompt application, and then selecting <strong>Run as administrator</strong>. After the command window opens, the chef-client can be run as the administrator</p> -</li> -</ul> -</div> -</div> -<div class="section" id="examples"> -<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2> -<p><strong>Start a Chef run when the chef-client is running as a daemon</strong></p> -<p>A chef-client that is running as a daemon can be woken up and started by sending the process a <tt class="docutils literal"><span class="pre">SIGUSR1</span></tt>. For example, to trigger a chef-client run on a machine running Linux:</p> -<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>sudo killall -USR1 chef-client -</pre></div> -</div> -<p><strong>Start a Chef run manually</strong></p> -<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ps auxw|grep chef-client -</pre></div> -</div> -<p>to return something like:</p> -<div class="highlight-bash"><div class="highlight"><pre>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 -</pre></div> -</div> -<p>and then enter:</p> -<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>sudo <span class="nb">kill</span> -USR1 66066 -</pre></div> -</div> -</div> -</div> - - - </div> - - </div> - - - <div class="clearer"></div> - </div> - - - - - </body> -</html>
\ No newline at end of file |