NAME
knife: - Chef server REST API utility
SYNOPSIS
knife sub-command (options)
DESCRIPTION
This manual page documents knife, a command-line utility used to
interact with a Chef server directly through the RESTful API. Knife
uses sub-commands to take various actions on different types of Chef
objects. Some sub-commands take additional options. General options
follow sub-commands and their options. A configuration file can be
created for common defaults.
Unless otherwise specified, output is in JSON format, and input files
are also JSON format.
GENERAL OPTIONS
-s, --server-url URL
Chef Server URL
-k, --key KEY
API Client Key
-c, --config CONFIG
The configuration file to use
-e, --editor EDITOR
Set the editor to use for interactive commands
-l, --log_level LEVEL
Set the log level (debug, info, warn, error, fatal)
-L, --logfile LOGLOCATION
Set the log file location, defaults to STDOUT
-u, --user USER
API Client Username
-p, --print-after
Show the data after a destructive operation
-v, --version
Show chef version
-y, --yes
Say yes to all prompts for confirmation
-h, --help
Show usage information.
SUB-COMMANDS
Knife sub-commands are structured as "NOUN verb NOUN (options)". The
sub-commands are meant to be intuitively named.
CLIENT SUB-COMMANDS
Sub-commands related to working with clients, which are registered
entities that access the Chef server.
client bulk delete (options)
-r, --regex [REGEX]
Narrow the operation via regular expression
Delete all the clients on the Chef server, or only certain clients
based on a regular expression.
client create CLIENT (options)
-f, --file FILE
Write the key to a file
Create a new client.
client delete CLIENT (options)
Deletes a registered client.
client edit CLIENT (options)
Edit a registered client.
client list (options)
-w, --with-uri
Show corresponding URIs
List all registered clients.
client reregister CLIENT (options)
-f, --file FILE
Write the key to a file
Regenerate the private key for a client.
client show CLIENT (options)
-a, --attribute [ATTR]
Show only one attribute
Show a client.
COOKBOOK SUB-COMMANDS
Cookbooks are the fundamental unit of distribution in Chef. They
encapsulate all the recipes of resources and the assets used to
configure a particular aspect of the infrastructure.
cookbook bulk delete COOKBOOK (options)
-r, --regex [REGEX]
Narrow the operation via regular expression
Delete all the cookbooks on the Chef server, or use a regular
expression to only delete certain cookbooks.
cookbook delete COOKBOOK (options)
Delete a single named COOKBOOK.
cookbook download COOKBOOK (options)
-f, --file FILE
The filename to write to
Download a cookbook from the server as a gzip(1)’ed, tar(1) archive.
cookbook list (options)
-w, --with-uri
Show corresponding URIs
List all cookbooks.
cookbook metadata COOKBOOK (options)
-a, --all
Generate metadata for all cookbooks, rather than just a single
cookbook
Generate cookbook metadata for the named COOKBOOK.
-o, --cookbook-path PATH:PATH
A colon-separated path to look for cookbooks in
cookbook show COOKBOOK [PART] [FILENAME] (options)
-f, --fqdn FQDN
The FQDN of the host to see the file for
-p, --platform PLATFORM
The platform to see the file for
-V, --platform-version VERSION
The platform version to see the file for
Show the particular part of a COOKBOOK. PART can be one of:
attribute definition file provider recipe resource template
cookbook upload COOKBOOK (options)
-a, --all
Upload all cookbooks, rather than just a single cookbook
-o, --cookbook-path PATH:PATH
A colon-separated path to look for cookbooks in
Upload a cookbook to the server.
DATA BAG SUB-COMMANDS
Data bags are stores of JSON blobs. These blobs are called items. They
are free form and indexed by the search mechanism on the Chef server.
data bag create BAG [ITEM] (options)
Create a new data bag, or item in a data bag.
data bag delete BAG [ITEM] (options)
Delete a data bag, or item from a data bag.
data bag edit BAG ITEM (options)
Edit an item in a data bag.
data bag list (options)
-w, --with-uri
Show corresponding URIs
List the available data bags.
data bag show BAG [ITEM] (options)
Show a specific data bag or an item in a data bag.
NODE SUB-COMMANDS
Nodes are the entities which are configured with Chef, typically
servers or workstations. Nodes are registered as a client, typcially of
the same name, but a single client might represent one or more nodes.
node bulk delete (options)
-r, --regex [REGEX]
Narrow the operation via regular expression
Delete all nodes, or only certain nodes based on a regular expression.
node create NODE (options)
Create a new node.
node delete NODE (options)
Delete a single node.
node edit NODE (options)
Edit a node.
node from file FILE (options)
Create a node from a JSON file.
node list (options)
-w, --with-uri
Show corresponding URIs
List all nodes.
node run_list add [NODE] [ENTRY] (options)
-a, --after [ITEM]
Place the ENTRY in the run list after ITEM
Add a recipe or role to the node’s run_list.
node run_list remove [NODE] [ENTRY] (options)
Remove a recipe or role from the node’s run_list.
node show NODE (options)
-a, --attribute [ATTR]
Show only one attribute
-r, --run-list
Show only the run list
Show a node.
ROLE SUB-COMMANDS
Roles provide a mechanism to apply a set of recipes and attributes to
nodes. For example, the ’webserver’ role might instruct Chef to add a
recipe for Apache, and specify a default domain to use.
role bulk delete (options)
-r, --regex [REGEX]
Narrow the operation via regular expression
Delete all roles, or only certain roles based on a regular expression.
role create ROLE (options)
-d, --description
The role description
Create a new role.
role delete ROLE (options)
Delete a role.
role edit ROLE (options) Edit a role.
role from file FILE (options)
Update a role from a file.
role list (options)
-w, --with-uri
Show corresponding URIs
List roles.
role show ROLE (options)
-a, --attribute [ATTR]
Show only one attribute
Show a specific role.
GENERAL SUB-COMMANDS
The following are general sub-commands that do not fit within the other
object types used in Chef.
configure (options)
-r, --repository REPO
The path to your chef-repo
Create a configuration file for knife. This will prompt for values to
enter into the file. See "CONFIGURATION" below for available options.
ec2 instance data [RUN LIST...] (options)
-e, --edit
Edit the instance data
Chef is commonly used with Amazon AWS EC2 nodes. This command will
generate instance metadata that can be used to automatically configure
an EC2 instance with Chef.
search INDEX QUERY (options)
-a, --attribute [ATTR]
Show only one attribute
-i, --id-only
Show only the ID of matching objects
-R, --rows INT
The number of rows to return
-r, --run-list
Show only the run list
-o, --sort SORT
The order to sort the results in
-b, --start ROW
The row to start returning results at
Search indexes are a powerful feature of the Chef server and the search
subcommand allows searching any of the available indexes using the SOLR
query syntax.
CONFIGURATION
The knife configuration file is a Ruby DSL. If it exists, knife uses
the settings for GENERAL OPTIONS defaults.
log_level
A Ruby symbol specifying the log level. Corresponds to the -l or
--log_level option. Default is :info.
log_location
Corresponds to the -L or --logfile option. Default is STDOUT.
node_name
User to authenticate to the Chef server. Corresponds to the -u
or --user option. This is requested from the user when running
this sub-command.
client_key
Private key file to authenticate to the Chef server. Corresponds
to the -k or --key option. This is requested from the user when
running this sub-command.
chef_server_url
URL of the Chef server. Corresponds to the -s or --server-url
option. This is requested from the user when running this sub-
command.
cache_type
The type of cache to use. Default is BasicFile. This can be any
type of Cache that moneta supports: BasicFile, Berkeley, Couch,
DataMapper, File, LMC, Memcache, Memory, MongoDB, Redis, Rufus,
S3, SDBM, Tyrant, Xattr, YAML.
cache_options
Specifies various options to use for caching. Default reads the
Chef client configuration (/etc/chef/checksums).
FILES
~/.chef/knife.rb
Ruby DSL configuration file for Knife. See "CONFIGURATION".
SEE ALSO
Full documentation for Chef and Knife is located on the Chef wiki,
http://wiki.opscode.com/display/chef/Home.
JSON is JavaScript Object Notation and more information can be found at
http://json.org/.
SOLR is an open source search engine. The Chef Server includes a SOLR
installation. More information about SOLR, including search query
syntax, can be found at http://lucene.apache.org/solr/.
AUTHOR
Chef was written by Adam Jacob <adam@ospcode.com> of Opscode
(http://www.opscode.com), with contributions from the community. This
manual page was written by Joshua Timberman <joshua@opscode.com> with
help2man. Permission is granted to copy, distribute and / or modify
this document under the terms of the Apache 2.0 License.
On Debian systems, the complete text of the Apache 2.0 License can be
found in /usr/share/common-licenses/Apache-2.0.