diff options
Diffstat (limited to 'distro/common/man/man1/knife-search.1')
| -rw-r--r-- | distro/common/man/man1/knife-search.1 | 510 |
1 files changed, 267 insertions, 243 deletions
diff --git a/distro/common/man/man1/knife-search.1 b/distro/common/man/man1/knife-search.1 index c248d84b6c..e59be88bd9 100644 --- a/distro/common/man/man1/knife-search.1 +++ b/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.10.0.alpha.0" "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 |