chef 0.8.16 → 0.9.0.a3

data/distro/common/man/man8/shef.8

@@ -0,0 +1,45 @@
+.TH SHEF: "8" "March 2010" "Chef: 0.8.4" "System Administration Utilities"
+.SH NAME
+shef: \- Run Chef in an IRB session.
+.SH SYNOPSIS
+.B shef
+\fI(options)\fR
+.SH DESCRIPTION
+.TP
+This manual page documents shef, a command-line REPL console used to run Chef in an IRB session. It includes recipe and attribute file syntax, and interactive debugging features.
+\fB\-S\fR, \fB\-\-server\fR CHEFSERVERURL
+The chef server URL
+.TP
+\fB\-z\fR, \fB\-\-client\fR
+chef\-client shef session
+.TP
+\fB\-c\fR, \fB\-\-config\fR CONFIG
+The configuration file to use
+.TP
+\fB\-j\fR JSON_ATTRIBS
+Load attributes from a JSON file or URL
+.HP
+\fB\-\-json\-attributes\fR
+.TP
+\fB\-s\fR, \fB\-\-solo\fR
+chef\-solo shef session
+.TP
+\fB\-a\fR, \fB\-\-standalone\fR
+standalone shef session
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+Show chef version
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show this message
+.SH "SEE ALSO"
+The full documentation for
+.B shef
+is maintained on the Chef wiki, http://wiki.opscode.com/display/chef/Shef/.
+.SH AUTHOR
+Shef was written by Daniel DeLeo <dan@kallistec.com> as part of Chef, by Opscode, Inc.
+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.
+.PP
+On Debian systems, the complete text of the Apache 2.0 License can be found in
+/usr/share/common-licenses/Apache-2.0.

data/distro/common/markdown/README

@@ -0,0 +1,3 @@
+This directory contains markdown documentation that is used in other places.
+For example, markdown (.mkd) documents that are generated as man pages
+with ronn.

data/distro/common/markdown/knife.mkd

@@ -0,0 +1,520 @@
+knife(8) -- 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
+  * `-f`, `--format` FORMAT:
+    Which format to use for output
+  * `-l`, `--log_level` LEVEL:
+    Set the log level (debug, info, warn, error, fatal)
+  * `-L`, `--logfile` LOGLOCATION:
+    Set the log file location, defaults to STDOUT
+  * `-n`, `--no-editor`:
+    Do not open EDITOR, just accept the data as is
+  * `-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 this message
+
+## SUB-COMMANDS
+
+Knife sub-commands are structured as "_NOUN_ __verb__ _NOUN_ (options)". The sub-commands are meant to be intuitively named. Because the Chef Server API is RESTful, sub-commands generally utilize CRUD operations.
+
+* create (create)
+* list and show (read)
+* edit (update)
+* delete (destroy)
+
+Objects stored on the server support these, as described below.
+
+## GENERAL SUB-COMMANDS
+
+The following are general sub-commands that do not fit within the other object types utilized in the Chef Server API.
+
+__configure__ _(options)_
+
+  * `-i`, `--initial`:
+    Create an initial API Client
+  * `-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. Default values are listed in square brackets if no other entry is typed. See "__CONFIGURATION__" below for available options.
+
+__index rebuild__ _(options)_
+
+  * `-y`, `--yes`:
+    don't bother to ask if I'm sure
+
+Rebuilds all the search indexes on the server.
+
+__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 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: _node_, _role_, _client_, _data bag_.
+
+__ssh QUERY COMMAND__ _(options)_
+
+  * `-a`, `--attribute ATTR       `:
+    The attribute to use for opening the connection - default is fqdn
+  * `-C`, `--concurrency NUM      `:
+    The number of concurrent connections
+  * `-m`, `--manual-list          `:
+    QUERY is a space separated list of servers
+  * `-P`, `--ssh-password PASSWORD`:
+    The ssh password
+  * `-x`, `--ssh-user USERNAME    `:
+    The ssh username
+
+The __ssh__ sub-command opens an ssh session to each of the nodes in the search results of the _QUERY_. This sub-command requires that the net-ssh-multi and highline Ruby libraries are installed. On Debian systems, these are the libnet-ssh-multi-ruby and libhighline-ruby packages. They can also be installed as RubyGems (net-ssh-multi and highline, respectively).
+
+## CLIENT SUB-COMMANDS
+
+Clients are entities that communicate with the Chef Server API.
+
+__client bulk delete REGEX__ _(options)_
+
+Delete clients on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s.
+
+__client create CLIENT__ _(options)_
+
+  * `-a`, `--admin    `:
+    Create the client as an admin
+  * `-f`, `--file FILE`:
+    Write the key to a file
+
+Create a new client. This generates an RSA keypair. The private key will be displayed on _STDOUT_ or written to the named file. The public half will be stored on the Server. For _chef-client_ systems, the private key should be copied to the system as `/etc/chef/client.pem`.
+
+Admin clients should be created for users that will use _knife_ to access the API as an administrator. The private key will generally be copied to `~/.chef/CLIENT.pem` and referenced in the `knife.rb` configuration file.
+
+__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 RSA keypair for a client. The public half will be stored on the server and the private key displayed on _STDOUT_ or written to the named file.
+
+__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 recipes of resources and assets used to configure a particular aspect of the infrastructure. The following sub-commands can be used to manipulate the cookbooks stored on the Chef Server.
+
+__cookbook bulk delete REGEX__ _(options)_
+
+Delete cookbooks on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s.
+
+__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 Chef Server as a gzip(1)'ed, tar(1) archive.
+
+__cookbook list__ _(options)_
+
+  * `-w`, `--with-uri`:
+    Show corresponding URIs
+
+List all the cookbooks.
+
+__cookbook metadata COOKBOOK__ _(options)_
+
+  * `-a`, `--all`:
+    Generate metadata for all cookbooks, rather than just a single cookbook
+  * `-o`, `--cookbook-path PATH:PATH`:
+    A colon-separated path to look for cookbooks in
+
+Generate cookbook metadata for the named _COOKBOOK_. The _PATH_ used here specifies where the "cookbooks" directory is located and corresponds to the `cookbook_path` configuration option.
+
+__cookbook metadata from FILE__ _(options)_
+
+Load the cookbook metadata from a specified file.
+
+__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 a particular part of a _COOKBOOK_. _PART_ can be one of:
+
+  * _attributes_
+  * _definitions_
+  * _files_
+  * _libraries_
+  * _providers_
+  * _recipes_
+  * _resources_
+  * _templates_
+
+__cookbook test [COOKBOOKS...]__ _(options)_
+
+  * `-a`, `--all`:
+    Test all cookbooks, rather than just a single cookbook
+  * `-o`, `--cookbook-path PATH:PATH`:
+    A colon-separated path to look for cookbooks in
+
+Test the specified cookbooks for syntax errors. This uses the built-in Ruby syntax checking option for files in the cookbook ending in `.rb`, and the ERB syntax check for files ending in `.erb` (templates).
+
+__cookbook upload [COOKBOOKS...]__ _(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
+
+Uploads the specified cookbooks to the Chef Server. The actual upload executes a number of commands, most of which occur on the local machine. The cookbook is staged in a temporary location. Then the `cookbook_path` (or `-o PATH`) is processed to search for the named cookbook, and each occurance is copied in the order specified. A syntax check is performed a la `cookbook test`, above. The metadata is generated, a la `cookbook metadata`. A gzip(1)'ed, tar(1) file is created, and is uploaded to the server.
+
+## COOKBOOK SITE SUB-COMMANDS
+
+The following sub-commands are still in the context of cookbooks, but they make use of Opscode's Cookbook Community site, _http://cookbooks.opscode.com/_. That site has an API, and these sub-commands utilize that API, rather than the Chef Server API.
+
+__cookbook site download COOKBOOK [VERSION]__ _(options)_
+
+  * `-f`, `--file FILE`:
+    The filename to write to
+
+Downloads a specific cookbook from the Community site, optionally specifying a certain version.
+
+__cookbook site list__ _(options)_
+
+  * `-w`, `--with-uri`:
+    Show corresponding URIs
+
+Lists available cookbooks from the Community site.
+
+__cookbook site search QUERY__ _(options)_
+
+Searches the Community site with the specified query.
+
+__cookbook site show COOKBOOK [VERSION]__ _(options)_
+
+Shows information from the site about a particular cookbook.
+
+__cookbook site vendor COOKBOOK [VERSION]__ _(options)_
+
+  * `-d`, `--dependencies`:
+    Grab dependencies automatically
+
+Downloads a cookbook and untars it in the cookbooks directory. If _-d_ is specified, all the cookbooks it depends on (via metadata _dependencies_) are downloaded and untarred as well.
+
+## DATA BAG SUB-COMMANDS
+
+Data bags are stores of JSON blobs. These blobs are called items. They are free form JSON and indexed by the Chef Server.
+
+__data bag create BAG [ITEM]__ _(options)_
+
+Create a new data bag, or an item in a data bag.
+
+__data bag delete BAG [ITEM]__ _(options)_
+
+Delete a data bag, or an 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 these are servers or workstations. Nodes are registered as a client, by default by the fully qualified domain name (fqdn). A single client may configure more than one node.
+
+__node bulk delete REGEX__ _(options)_
+
+Delete nodes on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s.
+
+__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
+
+__role bulk delete REGEX__ _(options)_
+
+Delete roles on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s.
+
+__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)_
+
+Create or update a role from a role Ruby DSL (`.rb`) or JSON 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.
+
+## CLOUD COMPUTING SUB-COMMANDS
+
+The next sections describe sub-commands to work with various Cloud Computing APIs to launch server instances with validation and run-time configuration that Chef knows about. These sub-commands require the fog Ruby library. On Debian and Ubuntu systems this is the package `libfog-ruby`. It is also available as a RubyGem, `fog`.
+
+The Rackspace and Terremark sub-commands are early stage of development. Right now when creating instances of these types, knife will assume an Ubuntu image, install Ruby from packages, RubyGems from source and Chef as a RubyGem. As these commands are developed, other installation styles may become available, as options.
+
+## EC2 SUB-COMMANDS
+
+Chef is commonly used with Amazon AWS EC2 nodes. This sub-command will generate instance metadata that can be used to automatically configure an EC2 instance with Chef. This requires an AMI that has Chef preinstalled with a configuration file that can parse the metadata at run-time. At this time this is the only sub-command for EC2, but more may be added later similar to __RACKSPACE__ and __TERREMARK__ below.
+
+__ec2 instance data [RUN LIST...]__ _(options)_
+
+  * `-e`, `--edit`:
+    Edit the instance data
+
+The _RUN LIST_ should be specified as a space separated list of roles or recipes that will be used by the instance to configure the server.
+
+## RACKSPACE SUB-COMMANDS
+
+In addition to EC2 nodes, Chef can be used on Rackspace Cloud nodes. The following sub-commands allow manipulating Rackspace Cloud nodes via the `fog` library.
+
+__rackspace server create [RUN LIST...]__ _(options)_
+
+  * `-K`, `--rackspace-api-key KEY`:
+    Your rackspace API key
+  * `-A USERNAME`, `--rackspace-api-username`:
+    Your rackspace API username
+  * `-f`, `--flavor FLAVOR   `:
+    The flavor of server
+  * `-i`, `--image IMAGE     `:
+    The image of the server
+  * `-N`, `--server-name NAME`:
+    The server name
+
+Creates a new Rackspace Cloud server.
+
+__rackspace server delete SERVER__ _(options)_
+
+Deletes a running Rackspace Cloud server.
+
+__rackspace server list__ _(options)_
+
+Lists running Rackspace Cloud servers.
+
+## TERREMARK SUB-COMMANDS
+
+As above, Chef can also be used on Terremark vCloud nodes. The following sub-commands allow manipulating Terremark vCloud nodes via the `fog` library.
+
+__terremark server create NAME [RUN LIST...]__ _(options)_
+
+  * `-K PASSWORD`, `--terremark-password`:
+    Your terremark password
+  * `-S`, `--terremark-service SERVICE`:
+    Your terremark service name
+  * `-A USERNAME`, `--terremark-username`:
+    Your terremark username
+
+Creates a new Terremark vCloud server.
+
+__terremark server delete SERVER__ _(options)_
+
+Deletes a running Terremark vCloud server.
+
+__terremark server list__ _(options)_
+
+  * `-K PASSWORD`, `--terremark-password`:
+    Your terremark password
+  * `-S`, `--terremark-service SERVICE`:
+    Your terremark service name
+  * `-A USERNAME`, `--terremark-username`:
+    Your terremark username
+
+Lists running Terremark vCloud servers.
+
+## CONFIGURATION
+
+The knife configuration file is a Ruby DSL. If it exists, knife uses these settings for __GENERAL OPTIONS__ defaults.
+
+`log_level`
+
+A Ruby symbol specifying the log level. Corresponds to `-l` or `--log_level` option. Default is _:info_. Valid values are:
+
+  * :info
+  * :debug
+  * :warn
+  * :fatal
+
+`log_location`
+
+Corresponds to the `-L` or `--log-file` option. Defaults is __STDOUT__. Valid values are __STDOUT__ or a filename.
+
+`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).
+
+`validation_client_name`
+
+Specifies the name of the client used to validate new clients. This is requested from the user when running the configuration sub-command.
+
+`validation_key`
+
+Specifies the private key file to use for generating ec2 instance data for validating new clients. This is implied from the `validation_client_name`.
+
+## FILES
+
+_~/.chef/knife.rb_
+
+Ruby DSL configuration file for knife. See "__CONFIGURATION__".
+
+## SEE ALSO
+
+Full documentation for Chef 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 the search query syntax, can be found at http://lucene.apache.org/solr/.
+
+This manual page was generated in nroff from Markdown with ronn. Ryan Tomayko wrote ronn and more information can be found at http://rtomayko.github.com/ronn/ronn.5.html.
+
+## AUTHOR
+
+Chef was written by Adam Jacob <adam@opscode.com> of Opscode (http://www.opscode.com), with contributions from the community. This manual page was written by Joshua Timberman <joshua@opscode.com>. 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`.