summaryrefslogtreecommitdiff
path: root/distro/common/html/knife_search.html
blob: 22d69b11d754d15c969f50363053740f61561ca5 (plain)
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
<!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>knife search &mdash; 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="knife-search">
<h1>knife search<a class="headerlink" href="#knife-search" title="Permalink to this headline">¶</a></h1>
<p>Search indexes allow queries to be made for any type of data that is indexed by the Chef server, including data bags (and data bag items), environments, nodes, and roles. A defined query syntax is used to support search patterns like exact, wildcard, range, and fuzzy. A search is a full-text query that can be done from several locations, including from within a recipe, by using the <tt class="docutils literal"><span class="pre">search</span></tt> subcommand in knife, the <tt class="docutils literal"><span class="pre">search</span></tt> method in the Recipe DSL, and by using the <tt class="docutils literal"><span class="pre">/search</span></tt> or <tt class="docutils literal"><span class="pre">/search/INDEX</span></tt> endpoints in the Chef server API. The search engine is based on Apache Solr and is run from the Chef server.</p>
<p>The <strong>knife search</strong> subcommand is used run a search query for information that is indexed on a Chef server.</p>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<p>This subcommand has the following syntax:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search INDEX SEARCH_QUERY
</pre></div>
</div>
<p>where <tt class="docutils literal"><span class="pre">INDEX</span></tt> is one of <tt class="docutils literal"><span class="pre">client</span></tt>, <tt class="docutils literal"><span class="pre">environment</span></tt>, <tt class="docutils literal"><span class="pre">node</span></tt>, <tt class="docutils literal"><span class="pre">role</span></tt>, or the name of a data bag and <tt class="docutils literal"><span class="pre">SEARCH_QUERY</span></tt> is the search query syntax for the query that will be executed.</p>
<p><tt class="docutils literal"><span class="pre">INDEX</span></tt> is implied if omitted, and will default to <tt class="docutils literal"><span class="pre">node</span></tt>. For example:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search <span class="s1">&quot;*:*&quot;</span> -i
</pre></div>
</div>
<p>will return something similar to:</p>
<div class="highlight-bash"><div class="highlight"><pre>8 items found

centos-62-dev
opensuse-1203
ubuntu-1304-dev
ubuntu-1304-orgtest
ubuntu-1204-ohai-test
ubuntu-1304-ifcfg-test
ohai-test
win2k8-dev
</pre></div>
</div>
<p>and is the same search as:</p>
<div class="highlight-bash"><div class="highlight"><pre>$ knife search node &quot;*:*&quot; -i
</pre></div>
</div>
<p>If the <tt class="docutils literal"><span class="pre">SEARCH_QUERY</span></tt> does not contain a colon character (<tt class="docutils literal"><span class="pre">:</span></tt>), then the default query pattern is <tt class="docutils literal"><span class="pre">tags:*#{&#64;query}*</span> <span class="pre">OR</span> <span class="pre">roles:*#{&#64;query}*</span> <span class="pre">OR</span> <span class="pre">fqdn:*#{&#64;query}*</span> <span class="pre">OR</span> <span class="pre">addresses:*#{&#64;query}*</span></tt>, which means the following two search queries are effectively the same:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search ubuntu
</pre></div>
</div>
<p>or:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search node <span class="s2">&quot;tags:*ubuntu* OR roles:*ubuntu* OR fqdn:*ubuntu* (etc.)&quot;</span>
</pre></div>
</div>
</div>
<div class="section" id="options">
<h2>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Review the list of <a class="reference internal" href="knife_common_options.html"><em>common options</em></a> available to this (and all) knife subcommands and plugins.</p>
</div>
<p>This sub-command has the following options:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">-a</span> <span class="pre">ATTR</span></tt>, <tt class="docutils literal"><span class="pre">--attribute</span> <span class="pre">ATTR</span></tt></dt>
<dd>The attribute (or attributes) to show.</dd>
<dt><tt class="docutils literal"><span class="pre">-b</span> <span class="pre">ROW</span></tt>, <tt class="docutils literal"><span class="pre">--start</span> <span class="pre">ROW</span></tt></dt>
<dd>The row at which return results will begin.</dd>
<dt><tt class="docutils literal"><span class="pre">-i</span></tt>, <tt class="docutils literal"><span class="pre">--id-only</span></tt></dt>
<dd>Use to show only matching object IDs.</dd>
<dt><tt class="docutils literal"><span class="pre">INDEX</span></tt></dt>
<dd>The name of the index to be queried: <tt class="docutils literal"><span class="pre">client</span></tt>, <tt class="docutils literal"><span class="pre">environment</span></tt>, <tt class="docutils literal"><span class="pre">node</span></tt>, <tt class="docutils literal"><span class="pre">role</span></tt>, or <tt class="docutils literal"><span class="pre">DATA_BAG_NAME</span></tt>. Default index: <tt class="docutils literal"><span class="pre">node</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">-l</span></tt>, <tt class="docutils literal"><span class="pre">--long</span></tt></dt>
<dd>Use to display all attributes in the output and to show the output as JSON.</dd>
<dt><tt class="docutils literal"><span class="pre">-m</span></tt>, <tt class="docutils literal"><span class="pre">--medium</span></tt></dt>
<dd>Use to display normal attributes in the output and to show the output as JSON.</dd>
<dt><tt class="docutils literal"><span class="pre">-o</span> <span class="pre">SORT</span></tt>, <tt class="docutils literal"><span class="pre">--sort</span> <span class="pre">SORT</span></tt></dt>
<dd>The order in which search results will be sorted.</dd>
<dt><tt class="docutils literal"><span class="pre">-q</span> <span class="pre">SEARCH_QUERY</span></tt>, <tt class="docutils literal"><span class="pre">--query</span> <span class="pre">SEARCH_QUERY</span></tt></dt>
<dd>Use to protect search queries that start with a hyphen (-). A <tt class="docutils literal"><span class="pre">-q</span></tt> query may be specified as an argument or an option, but not both.</dd>
<dt><tt class="docutils literal"><span class="pre">-r</span></tt>, <tt class="docutils literal"><span class="pre">--run-list</span></tt></dt>
<dd>Use to show only the run-list.</dd>
<dt><tt class="docutils literal"><span class="pre">-R</span> <span class="pre">INT</span></tt>, <tt class="docutils literal"><span class="pre">--rows</span> <span class="pre">INT</span></tt></dt>
<dd>The number of rows to be returned.</dd>
<dt><tt class="docutils literal"><span class="pre">SEARCH_QUERY</span></tt></dt>
<dd>The search query used to identify a a list of items on a Chef server. This option uses the same syntax as the <tt class="docutils literal"><span class="pre">search</span></tt> sub-command.</dd>
</dl>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<p>The following examples show how to use this knife subcommand:</p>
<p><strong>Search by platform ID</strong></p>
<p>To search for the IDs of all nodes running on the Amazon EC2 platform, enter:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search node <span class="s1">&quot;ec2:*&quot;</span> -i
</pre></div>
</div>
<p>to return something like:</p>
<div class="highlight-bash"><div class="highlight"><pre>4 items found

ip-0A7CA19F.ec2.internal

ip-0A58CF8E.ec2.internal

ip-0A58E134.ec2.internal

ip-0A7CFFD5.ec2.internal
</pre></div>
</div>
<p><strong>Search by instance type</strong></p>
<p>To search for the instance type (flavor) of all nodes running on the Amazon EC2 platform, enter:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search node <span class="s1">&quot;ec2:*&quot;</span> -a ec2.instance_type
</pre></div>
</div>
<p>to return something like:</p>
<div class="highlight-bash"><div class="highlight"><pre>4 items found

ec2.instance_type:  m1.large
id:                 ip-0A7CA19F.ec2.internal

ec2.instance_type:  m1.large
id:                 ip-0A58CF8E.ec2.internal

ec2.instance_type:  m1.large
id:                 ip-0A58E134.ec2.internal

ec2.instance_type:  m1.large
id:                 ip-0A7CFFD5.ec2.internal
</pre></div>
</div>
<p><strong>Search by node</strong></p>
<p>To search for all nodes running Ubuntu, enter:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search node <span class="s1">&quot;platform:ubuntu&quot;</span>
</pre></div>
</div>
<p><strong>Search by node and environment</strong></p>
<p>To search for all nodes running CentOS in the production environment, enter:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search node <span class="s1">&quot;chef_environment:production AND platform:centos&quot;</span>
</pre></div>
</div>
<p><strong>Search for nested attributes</strong></p>
<p>To find a nested attribute, use a pattern similar to the following:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search node &lt;query_to_run&gt; -a &lt;main_attribute&gt;.&lt;nested_attribute&gt;
</pre></div>
</div>
<p><strong>Search for multiple attributes</strong></p>
<p>To build a search query to use more than one attribute, use an underscore (<tt class="docutils literal"><span class="pre">_</span></tt>) to separate each attribute. For example, the following query will search for all nodes running a specific version of Ruby:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search node <span class="s2">&quot;languages_ruby_version:1.9.3&quot;</span>
</pre></div>
</div>
<p><strong>Search for nested attributes using a search query</strong></p>
<p>To build a search query that can find a nested attribute:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search node name:&lt;node_name&gt; -a kernel.machine
</pre></div>
</div>
<p><strong>Use a test query</strong></p>
<p>To test a search query that will be used in a <strong>knife ssh</strong> command:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>knife search node <span class="s2">&quot;role:web NOT name:web03&quot;</span>
</pre></div>
</div>
<p>where the query in the previous example will search all servers that have the <tt class="docutils literal"><span class="pre">web</span></tt> role, but not on the server named <tt class="docutils literal"><span class="pre">web03</span></tt>.</p>
</div>
</div>


          </div>

      </div>

  
      <div class="clearer"></div>
    </div>




  </body>
</html>