chef 11.6.2 → 11.8.0.rc.1

data/distro/common/man/man1/knife-search.1

@@ -1,280 +1,304 @@
-.\" generated with Ronn/v0.7.3
-.\" http://github.com/rtomayko/ronn/tree/0.7.3
-.
-.TH "KNIFE\-SEARCH" "1" "October 2013" "Chef 11.6.2" "Chef Manual"
-.
-.SH "NAME"
-\fBknife\-search\fR \- Find objects on a Chef Server by query
-.
-.SH "SYNOPSIS"
-\fBknife\fR \fBsearch INDEX QUERY\fR \fI(options)\fR
-.
+.TH "KNIFE-SEARCH" "1" "Chef 11.8.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
+..
+.\" Man page generated from reStructuredText.
+.
+.sp
+Search indexes allow queries to be made for any type of data that is indexed by the 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, by using the search functionality in the Management Console, or 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 server.
+.sp
+The \fBknife search\fP subcommand is used run a search query for information that is indexed on a server.
+.sp
+\fBCommon Options\fP
+.sp
+The following options can be run with all Knife sub\-commands and plug\-ins:
+.INDENT 0.0
 .TP
-\fB\-a\fR, \fB\-\-attribute ATTR\fR
-Show only one attribute
-.
+.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP
+The configuration file to use.
 .TP
-\fB\-i\fR, \fB\-\-id\-only\fR
-Show only the ID of matching objects
-.
+.B \fB\-\-color\fP
+Indicates that colored output will be used.
 .TP
-\fB\-q\fR, \fB\-\-query QUERY\fR
-The search query; useful to protect queries starting with \-
-.
+.B \fB\-d\fP, \fB\-\-disable\-editing\fP
+Indicates that $EDITOR will not be opened; data will be accepted as\-is.
 .TP
-\fB\-R\fR, \fB\-\-rows INT\fR
-The number of rows to return
-.
+.B \fB\-\-defaults\fP
+Indicates that Knife will use the default value, instead of asking a user to provide one.
 .TP
-\fB\-r\fR, \fB\-\-run\-list\fR
-Show only the run list
-.
+.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP
+The $EDITOR that is used for all interactive commands.
 .TP
-\fB\-o\fR, \fB\-\-sort SORT\fR
-The order to sort the results in
-.
+.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
-\fB\-b\fR, \fB\-\-start ROW\fR
-The row to start returning results at
-.
+.B \fB\-f FILE_NAME\fP, \fB\-\-file FILE_NAME\fP
+Indicates that the private key will be saved to a specified file name.
 .TP
-\fB\-m\fR, \fB\-\-medium\fR
-Display medium sized output when searching nodes using the default summary format
-.
+.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
-\fB\-l\fR, \fB\-\-long\fR
-Display long output when searching nodes using the default summary format
-.
-.SH "DESCRIPTION"
-Search is a feature of the Chef Server that allows you to use a full\-text search engine to query information about your infrastructure and applications\. You can utilize this service via search calls in a recipe or the knife search command\. The search syntax is based on Lucene\.
-.
-.SH "INDEXES"
-Search indexes are a feature of the Chef Server and the search sub\-command allows querying any of the available indexes using SOLR query syntax\. The following data types are indexed for search:
-.
-.IP "\(bu" 4
-\fInode\fR
-.
-.IP "\(bu" 4
-\fIrole\fR
-.
-.IP "\(bu" 4
-\fIenvironment\fR
-.
-.IP "\(bu" 4
-\fIclients\fR
-.
-.IP "\(bu" 4
-\fIdata bag\fR
-.
-.IP "" 0
-.
-.P
-Data bags are indexed by the data bag\'s name\. For example, to search a data bag named "admins":
-.
-.IP "" 4
-.
+.B \fB\-h\fP, \fB\-\-help\fP
+Shows help for the command.
+.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 server.
+.TP
+.B \fB\-\-no\-color\fP
+Indicates that color will not be used in the output.
+.TP
+.B \fB\-p PASSWORD\fP, \fB\-\-password PASSWORD\fP
+The user password.
+.TP
+.B \fB\-\-print\-after\fP
+Indicates that data will be shown after a destructive operation.
+.TP
+.B \fB\-s URL\fP, \fB\-\-server\-url URL\fP
+The URL for the server.
+.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 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
+Indicates that the response to all confirmation prompts will be "Yes" (and that Knife will not ask for confirmation).
+.UNINDENT
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
 .nf
-
-knife search admins "field:search_pattern"
-.
+.ft C
+$ knife search INDEX SEARCH_QUERY
+.ft P
 .fi
-.
-.IP "" 0
-.
-.SH "QUERY SYNTAX"
-Queries have the form \fBfield:search_pattern\fR where \fBfield\fR is a key in the JSON description of the relevant objects (nodes, roles, environments, or data bags)\. Both \fBfield\fR and \fBsearch_pattern\fR are case\-sensitive\. \fBsearch_pattern\fR can be an exact, wildcard, range, or fuzzy match (see below)\. The \fBfield\fR supports exact matching and limited wildcard matching\.
-.
-.P
-Searches will return the relevant objects (nodes, roles, environments, or data bags) where the \fBsearch_pattern\fR matches the object\'s value of \fBfield\fR\.
-.
-.SS "FIELD NAMES"
-Field names are the keys within the JSON description of the object being searched\. Nested Keys can be searched by placing an underscore ("_") between key names\.
-.
-.SS "WILDCARD MATCHING FOR FIELD NAMES"
-The field name also has limited support for wildcard matching\. Both the "*" and "?" wildcards (see below) can be used within a field name; however, they cannot be the first character of the field name\.
-.
-.SS "EXACT MATCHES"
-Without any search modifiers, a search returns those fields for which the \fBsearch_pattern\fR exactly matches the value of \fBfield\fR in the JSON description of the object\.
-.
-.SS "WILDCARD MATCHES"
-Search support both single\- and multi\-character wildcard searches within a search pattern\.
-.
-.P
-\'?\' matches exactly one character\.
-.
-.P
-\'*\' matches zero or more characters\.
-.
-.SS "RANGE MATCHES"
-Range searches allows one to match values between two given values\. To match values between X and Y, inclusively, use square brackets:
-.
-.IP "" 4
-.
+.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:
+.sp
 .nf
-
-knife search INDEX \'field:[X TO Y]
-.
+.ft C
+$ knife search \(aq*:*\(aq \-i
+.ft P
 .fi
-.
-.IP "" 0
-.
-.P
-To match values between X and Y, exclusively, use curly brackets:
-.
-.IP "" 4
-.
+.sp
+will return something similar to:
+.sp
 .nf
+.ft C
+8 items found
 
-knife search INDEX \'field:{X TO Y}\'
-.
+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
-.
-.IP "" 0
-.
-.P
-Values are sorted in lexicographic order\.
-.
-.SS "FUZZY MATCHES"
-Fuzzy searches allows one to match values based on the Levenshtein Distance algorithm\. To perform a fuzzy match, append a tilda (~) to the search term:
-.
-.IP "" 4
-.
+.sp
+and is the same search as:
+.sp
 .nf
-
-knife search INDEX \'field:term~\'
-.
+.ft C
+$ knife node search \(aq*:*" \-i
+.ft P
 .fi
-.
-.IP "" 0
-.
-.P
-This search would return nodes whose \fBfield\fR was \'perm\' or \'germ\'\.
-.
-.SS "BOOLEAN OPERATORS"
-The boolean operators NOT, AND, and OR are supported\. To find values of \fBfield\fR that are not X:
-.
-.IP "" 4
-.
+.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:
+.sp
 .nf
-
-knife search INDEX \'field:(NOT X)\'
-.
+.ft C
+$ knife search ubuntu
+.ft P
 .fi
-.
-.IP "" 0
-.
-.P
-To find records where \fBfield1\fR is X and \fBfield2\fR is Y:
-.
-.IP "" 4
-.
+.sp
+or:
+.sp
 .nf
-
-knife search INDEX \'field1:X AND field2:Y\'
-.
+.ft C
+$ knife search node "tags:*ubuntu* OR roles:*ubuntu* OR fqdn:*ubuntu* (etc.)"
+.ft P
 .fi
-.
-.IP "" 0
-.
-.P
-To find records where \fBfield\fR is X or Y:
-.
-.IP "" 4
-.
+.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\-i\fP, \fB\-\-id\-only\fP
+Indicates that only matching object IDs will be shown.
+.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\-l\fP, \fB\-\-long\fP
+Display long output when searching nodes while using the default summary format.
+.TP
+.B \fB\-m\fP, \fB\-\-medium\fP
+Display more, but not all, of a node\(aqs data when searching using the default summary format.
+.TP
+.B \fB\-o SORT\fP, \fB\-\-sort SORT\fP
+The order in which search results will be sorted.
+.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
+Indicates that only the run\-list will be shown.
+.TP
+.B \fB\-R INT\fP, \fB\-\-rows INT\fP
+The number of rows to be returned.
+.TP
+.B \fBSEARCH_QUERY\fP
+The search query used to identify a a list of items on a server. This option uses the same syntax as the \fBsearch\fP sub\-command.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To search for the IDs of all nodes running on the Amazon EC2 platform, enter:
+.sp
 .nf
-
-knife search INDEX \'field:X OR field:Y\'
-.
+.ft C
+$ knife search node \(aqec2:*\(aq \-i
+.ft P
 .fi
-.
-.IP "" 0
-.
-.SS "QUOTING AND SPECIAL CHARACTERS"
-In order to avoid having special characters and escape sequences within your search term interpreted by either Ruby or the shell, enclose them in single quotes\.
-.
-.P
-Search terms that include spaces should be enclosed in double\-quotes:
-.
-.IP "" 4
-.
+.sp
+to return something like:
+.sp
 .nf
+.ft C
+4 items found
 
-knife search INDEX \'field:"term with spaces"\'
-.
+ip\-0A7CA19F.ec2.internal
+
+ip\-0A58CF8E.ec2.internal
+
+ip\-0A58E134.ec2.internal
+
+ip\-0A7CFFD5.ec2.internal
+.ft P
 .fi
-.
-.IP "" 0
-.
-.P
-The following characters must be escaped:
-.
-.IP "" 4
-.
+.sp
+To search for the instance type (flavor) of all nodes running on the Amazon EC2 platform, enter:
+.sp
 .nf
-
-+ \- && || ! ( ) { } [ ] ^ " ~ * ? : \e
-.
+.ft C
+$ knife search node \(aqec2:*\(aq \-a ec2.instance_type
+.ft P
 .fi
-.
-.IP "" 0
-.
-.SH "EXAMPLES"
-Find the nodes with the fully\-qualified domain name (FQDN) www\.example\.com:
-.
-.IP "" 4
-.
+.sp
+to return something like:
+.sp
 .nf
+.ft C
+4 items found
 
-knife search node \'fqdn:www\.example\.com\'
-.
+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
-.
-.IP "" 0
-.
-.P
-Find the nodes running a version of Ubuntu:
-.
-.IP "" 4
-.
+.sp
+To search for all nodes running Ubuntu, enter:
+.sp
 .nf
-
-knife search node \'platform:ubuntu*\'
-.
+.ft C
+$ knife search node \(aqplatform:ubuntu\(aq
+.ft P
 .fi
-.
-.IP "" 0
-.
-.P
-Find all nodes running CentOS in the production environment:
-.
-.IP "" 4
-.
+.sp
+To search for all nodes running CentOS in the production environment, enter:
+.sp
 .nf
-
-knife search node \'chef_environment:production AND platform:centos\'
-.
+.ft C
+$ knife search node \(aqchef_environment:production AND platform:centos\(aq
+.ft P
 .fi
+.sp
+To find a nested attribute, use a pattern similar to the following:
+.sp
+.nf
+.ft C
+$ knife search node <query_to_run> \-a <main_attribute>.<nested_attribute>
+.ft P
+.fi
+.sp
+To build a search query to use more than one attribute, use an underscore ( _ ) to separate each attribute. For example, the following query will search for all nodes running a specific version of Ruby:
+.sp
+.nf
+.ft C
+$ knife search node "languages_ruby_version:1.9.3"
+.ft P
+.fi
+.sp
+To build a search query that can find a nested attribute:
+.sp
+.nf
+.ft C
+$ knife search node name:<node_name> \-a kernel.machine
+.ft P
+.fi
+.sp
+To test a search query that will be used in a \fBknife ssh\fP command:
+.sp
+.nf
+.ft C
+$ knife search node "role:web AND NOT name:web03"
+.ft P
+.fi
+.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
+Opscode
+.\" Generated by docutils manpage writer.
 .
-.IP "" 0
-.
-.SH "KNOWN BUGS"
-.
-.IP "\(bu" 4
-Searches against the client index return no results in most cases\. (CHEF\-2477)
-.
-.IP "\(bu" 4
-Searches using the fuzzy match operator (~) produce an error\. (CHEF\-2478)
-.
-.IP "" 0
-.
-.SH "SEE ALSO"
-\fBknife\-ssh\fR(1) \fIhttp://wiki\.opscode\.com/display/chef/Attributes\fR Lucene Query Parser Syntax \fIhttp://lucene\.apache\.org/java/2_3_2/queryparsersyntax\.html\fR
-.
-.SH "AUTHOR"
-Chef was written by Adam Jacob \fIadam@opscode\.com\fR with many contributions from the community\.
-.
-.SH "DOCUMENTATION"
-This manual page was written by Joshua Timberman \fIjoshua@opscode\.com\fR\. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2\.0 License\.
-.
-.SH "CHEF"
-Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR