1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
<!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">-c</span> <span class="pre">CONFIG</span></tt>, <tt class="docutils literal"><span class="pre">--config</span> <span class="pre">CONFIG</span></tt></dt>
<dd>The configuration file to use.</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.</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. 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>The path to a file that contains JSON data.</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.</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></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">-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.</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>
|
