summaryrefslogtreecommitdiff
path: root/distro/common/man/man1/knife-search.1
blob: 3b8189853096beb53de34712f526d2301207c2c8 (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
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
.\" Man page generated from reStructuredText.
.
.TH "KNIFE-SEARCH" "1" "Chef 12.0" "" "knife search"
.SH NAME
knife-search \- The man page for the knife search subcommand.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
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 \fBsearch\fP subcommand in knife, the \fBsearch\fP method in the Recipe DSL, and by using the \fB/search\fP or \fB/search/INDEX\fP endpoints in the Chef server API\&. The search engine is based on Apache Solr and is run from the Chef server\&.
.sp
The \fBknife search\fP subcommand is used run a search query for information that is indexed on a Chef server\&.
.sp
\fBSyntax\fP
.sp
This subcommand has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search INDEX SEARCH_QUERY
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where \fBINDEX\fP is one of \fBclient\fP, \fBenvironment\fP, \fBnode\fP, \fBrole\fP, or the name of a data bag and \fBSEARCH_QUERY\fP is the search query syntax for the query that will be executed.
.sp
\fBINDEX\fP is implied if omitted, and will default to \fBnode\fP\&. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search \(aq*:*\(aq \-i
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will return something similar to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and is the same search as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search node \(aq*:*" \-i
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the \fBSEARCH_QUERY\fP does not contain a colon character (\fB:\fP), then the default query pattern is \fBtags:*#{@query}* OR roles:*#{@query}* OR fqdn:*#{@query}* OR addresses:*#{@query}*\fP, which means the following two search queries are effectively the same:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search ubuntu
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search node "tags:*ubuntu* OR roles:*ubuntu* OR fqdn:*ubuntu* (etc.)"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This sub\-command has the following options:
.INDENT 0.0
.TP
.B \fB\-a ATTR\fP, \fB\-\-attribute ATTR\fP
The attribute (or attributes) to show.
.TP
.B \fB\-b ROW\fP, \fB\-\-start ROW\fP
The row at which return results will begin.
.TP
.B \fB\-c CONFIG_FILE\fP, \fB\-\-config CONFIG_FILE\fP
The configuration file to use.
.TP
.B \fB\-\-chef\-zero\-port PORT\fP
The port on which chef\-zero will listen.
.TP
.B \fB\-\-[no\-]color\fP
Use to view colored output.
.TP
.B \fB\-d\fP, \fB\-\-disable\-editing\fP
Use to prevent the $EDITOR from being opened and to accept data as\-is.
.TP
.B \fB\-\-defaults\fP
Use to have knife use the default value instead of asking a user to provide one.
.TP
.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP
The $EDITOR that is used for all interactive commands.
.TP
.B \fB\-E ENVIRONMENT\fP, \fB\-\-environment ENVIRONMENT\fP
The name of the environment. When this option is added to a command, the command will run only against the named environment.
.TP
.B \fB\-F FORMAT\fP, \fB\-\-format FORMAT\fP
The output format: \fBsummary\fP (default), \fBtext\fP, \fBjson\fP, \fByaml\fP, and \fBpp\fP\&.
.TP
.B \fB\-h\fP, \fB\-\-help\fP
Shows help for the command.
.TP
.B \fB\-i\fP, \fB\-\-id\-only\fP
Use to show only matching object IDs.
.TP
.B \fBINDEX\fP
The name of the index to be queried: \fBclient\fP, \fBenvironment\fP, \fBnode\fP, \fBrole\fP, or \fBDATA_BAG_NAME\fP\&. Default index: \fBnode\fP\&.
.TP
.B \fB\-k KEY\fP, \fB\-\-key KEY\fP
The private key that knife will use to sign requests made by the API client to the Chef server\&.
.TP
.B \fB\-l\fP, \fB\-\-long\fP
Use to display all attributes in the output and to show the output as JSON\&.
.TP
.B \fB\-m\fP, \fB\-\-medium\fP
Use to display normal attributes in the output and to show the output as JSON\&.
.TP
.B \fB\-o SORT\fP, \fB\-\-sort SORT\fP
The order in which search results will be sorted.
.TP
.B \fB\-\-print\-after\fP
Use to show data after a destructive operation.
.TP
.B \fB\-q SEARCH_QUERY\fP, \fB\-\-query SEARCH_QUERY\fP
Use to protect search queries that start with a hyphen (\-). A \fB\-q\fP query may be specified as an argument or an option, but not both.
.TP
.B \fB\-r\fP, \fB\-\-run\-list\fP
Use to show only the run\-list.
.TP
.B \fB\-R INT\fP, \fB\-\-rows INT\fP
The number of rows to be returned.
.TP
.B \fB\-s URL\fP, \fB\-\-server\-url URL\fP
The URL for the Chef server\&.
.TP
.B \fBSEARCH_QUERY\fP
The search query used to identify a a list of items on a Chef server\&. This option uses the same syntax as the \fBsearch\fP sub\-command.
.TP
.B \fB\-u USER\fP, \fB\-\-user USER\fP
The user name used by knife to sign requests made by the API client to the Chef server\&. Authentication will fail if the user name does not match the private key.
.TP
.B \fB\-v\fP, \fB\-\-version\fP
The version of the chef\-client\&.
.TP
.B \fB\-V\fP, \fB\-\-verbose\fP
Set for more verbose outputs. Use \fB\-VV\fP for maximum verbosity.
.TP
.B \fB\-y\fP, \fB\-\-yes\fP
Use to respond to all confirmation prompts with "Yes". knife will not ask for confirmation.
.TP
.B \fB\-z\fP, \fB\-\-local\-mode\fP
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\&.
.UNINDENT
.sp
\fBExamples\fP
.sp
To search for the IDs of all nodes running on the Amazon EC2 platform, enter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search node \(aqec2:*\(aq \-i
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to return something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
4 items found

ip\-0A7CA19F.ec2.internal

ip\-0A58CF8E.ec2.internal

ip\-0A58E134.ec2.internal

ip\-0A7CFFD5.ec2.internal
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To search for the instance type (flavor) of all nodes running on the Amazon EC2 platform, enter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search node \(aqec2:*\(aq \-a ec2.instance_type
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to return something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To search for all nodes running Ubuntu, enter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search node \(aqplatform:ubuntu\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To search for all nodes running CentOS in the production environment, enter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search node \(aqchef_environment:production AND platform:centos\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To find a nested attribute, use a pattern similar to the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search node <query_to_run> \-a <main_attribute>.<nested_attribute>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To build a search query to use more than one attribute, use an underscore (\fB_\fP) to separate each attribute. For example, the following query will search for all nodes running a specific version of Ruby:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search node "languages_ruby_version:1.9.3"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To build a search query that can find a nested attribute:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search node name:<node_name> \-a kernel.machine
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To test a search query that will be used in a \fBknife ssh\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife search node "role:web NOT name:web03"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where the query in the previous example will search all servers that have the \fBweb\fP role, but not on the server named \fBweb03\fP\&.
.SH AUTHOR
Chef
.\" Generated by docutils manpage writer.
.