NAME¶
knife-search - The man page for the knife search subcommand.
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
search subcommand in Knife, by using the search functionality in the
Chef Manage, or by using the
/search or
/search/INDEX endpoints
in the Chef Server API. The search engine is based on Apache Solr and is run
from the server.
The
knife search subcommand is used run a search query for information
that is indexed on a server.
Syntax
This argument has the following syntax:
$ knife search INDEX SEARCH_QUERY
where
INDEX is one of
client,
environment,
node,
role, or the name of a data bag and
SEARCH_QUERY is the search
query syntax for the query that will be executed.
INDEX is implied if omitted, and will default to
node. For
example:
$ knife search '*:*' -i
will return something similar to:
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
and is the same search as:
$ knife search node '*:*" -i
If the
SEARCH_QUERY does not contain a colon character (
:), then
the default query pattern is
tags:*#{@query}* OR roles:*#{@query}* OR
fqdn:*#{@query}* OR addresses:*#{@query}*, which means the following two
search queries are effectively the same:
$ knife search ubuntu
or:
$ knife search node "tags:*ubuntu* OR roles:*ubuntu* OR fqdn:*ubuntu* (etc.)"
Options
This sub-command has the following options:
- -a ATTR, --attribute ATTR
- The attribute (or attributes) to show.
- -b ROW, --start ROW
- The row at which return results will begin.
- -c CONFIG_FILE, --config CONFIG_FILE
- The configuration file to use.
- --chef-zero-port PORT
- The port on which chef-zero will listen.
- --[no-]color
- Indicates whether colored output will be used.
- -d, --disable-editing
- Indicates that $EDITOR will not be opened; data will be accepted
as-is.
- --defaults
- Indicates that Knife will use the default value, instead of asking a user
to provide one.
- -e EDITOR, --editor EDITOR
- The $EDITOR that is used for all interactive commands.
- -E ENVIRONMENT, --environment ENVIRONMENT
- The name of the environment. When this option is added to a command, the
command will run only against the named environment.
- -F FORMAT, --format FORMAT
- The output format: summary (default), text, json,
yaml, and pp.
- -h, --help
- Shows help for the command.
- -i, --id-only
- Indicates that only matching object IDs will be shown.
- INDEX
- The name of the index to be queried: client, environment,
node, role, or DATA_BAG_NAME. Default index:
node.
- -k KEY, --key KEY
- The private key that Knife will use to sign requests made by the API
client to the server.
- -l, --long
- Display long output when searching nodes while using the default summary
format.
- -m, --medium
- Display more, but not all, of a node's data when searching using the
default summary format.
- -o SORT, --sort SORT
- The order in which search results will be sorted.
- --print-after
- Indicates that data will be shown after a destructive operation.
- -q SEARCH_QUERY, --query SEARCH_QUERY
- Use to protect search queries that start with a hyphen (-). A -q
query may be specified as an argument or an option, but not both.
- -r, --run-list
- Indicates that only the run-list will be shown.
- -R INT, --rows INT
- The number of rows to be returned.
- -s URL, --server-url URL
- The URL for the server.
- SEARCH_QUERY
- The search query used to identify a a list of items on a server. This
option uses the same syntax as the search sub-command.
- -u USER, --user USER
- 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.
- -v, --version
- The version of the chef-client.
- -V, --verbose
- Set for more verbose outputs. Use -VV for maximum verbosity.
- -y, --yes
- Indicates that the response to all confirmation prompts will be
"Yes" (and that Knife will not ask for confirmation).
- -z, --local-mode
- Indicates that the chef-client will be run in local mode, which allows all
commands that work against the server to also work against the local
chef-repo.
Examples
To search for the IDs of all nodes running on the Amazon EC2 platform, enter:
$ knife search node 'ec2:*' -i
to return something like:
4 items found
ip-0A7CA19F.ec2.internal
ip-0A58CF8E.ec2.internal
ip-0A58E134.ec2.internal
ip-0A7CFFD5.ec2.internal
To search for the instance type (flavor) of all nodes running on the Amazon EC2
platform, enter:
$ knife search node 'ec2:*' -a ec2.instance_type
to return something like:
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
To search for all nodes running Ubuntu, enter:
$ knife search node 'platform:ubuntu'
To search for all nodes running CentOS in the production environment, enter:
$ knife search node 'chef_environment:production AND platform:centos'
To find a nested attribute, use a pattern similar to the following:
$ knife search node <query_to_run> -a <main_attribute>.<nested_attribute>
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:
$ knife search node "languages_ruby_version:1.9.3"
To build a search query that can find a nested attribute:
$ knife search node name:<node_name> -a kernel.machine
To test a search query that will be used in a
knife ssh command:
$ knife search node "role:web NOT name:web03"
where the query in the previous example will search all servers that have the
web role, but not on the server named
web03.
AUTHOR¶
Chef
