chef 12.10.24 → 12.11.18

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

@@ -1,359 +1,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.
-.
+.\" 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.
+.