diff options
| author | Daniel DeLeo <dan@opscode.com> | 2011-04-09 21:14:00 -0700 |
|---|---|---|
| committer | Daniel DeLeo <dan@opscode.com> | 2011-04-09 21:14:00 -0700 |
| commit | fc27dcac230c6a134b93bedb8eedf180b834376d (patch) | |
| tree | a3dcd64ebb7be064f08dddaa3a79b1be02d95ec5 | |
| parent | 6c14edd337323f77aa36c987ee372a5c739c6c5b (diff) | |
| download | chef-fc27dcac230c6a134b93bedb8eedf180b834376d.tar.gz | |
[CHEF-2201] update knife, knife-tag pages
41 files changed, 1858 insertions, 1059 deletions
diff --git a/chef/distro/common/html/knife-bootstrap.1.html b/chef/distro/common/html/knife-bootstrap.1.html index e8c38ec1c5..1c3454e2f7 100644 --- a/chef/distro/common/html/knife-bootstrap.1.html +++ b/chef/distro/common/html/knife-bootstrap.1.html @@ -62,6 +62,8 @@ <a href="#NAME">NAME</a> <a href="#SYNOPSIS">SYNOPSIS</a> <a href="#DESCRIPTION">DESCRIPTION</a> + <a href="#EXAMPLES">EXAMPLES</a> + <a href="#BUGS">BUGS</a> <a href="#SEE-ALSO">SEE ALSO</a> <a href="#AUTHOR">AUTHOR</a> <a href="#DOCUMENTATION">DOCUMENTATION</a> @@ -104,8 +106,7 @@ is to get Chef installed on the target system so it can run Chef Client with a Chef Server. The main assumption is a baseline OS installation exists. This sub-command is used internally by some cloud computing -server create commands and the others will be migrated in a future -version of Chef.</p> +plugins.</p> <p>The bootstrap sub-command supports supplying a template to perform the bootstrap steps. If the distro is not specified (via <code>-d</code> or <code>--distro</code> @@ -122,7 +123,8 @@ sub-command looks in the following locations for the template to use:</p> </ul> -<p>The default bootstrap templates are scripts that get copied to the target node (FQDN). As of Chef 0.9.8, the following distros are supported:</p> +<p>The default bootstrap templates are scripts that get copied to the +target node (FQDN). The following distros are supported:</p> <ul> <li>centos5-gems</li> @@ -132,9 +134,15 @@ sub-command looks in the following locations for the template to use:</p> </ul> -<p>The gems installations will use RubyGems 1.3.6 and Chef installed as a gem. The apt installation will use the Opscode APT repository. The RubyGems installation requires installing gems with native extensions, so development related packages (ruby-dev, build-essential) are installed. These are not installed with the apt installation, as native extensions are already compiled in the required packages.</p> +<p>The gems installations will use RubyGems 1.3.6 and Chef installed as a +gem. The apt installation will use the Opscode APT repository. The +RubyGems installation requires installing gems with native extensions, +so development related packages (ruby-dev, build-essential) are +installed. These are not installed with the apt installation, as native +extensions are already compiled in the required packages.</p> -<p>In addition to handling the software installation, these bootstrap templates do the following:</p> +<p>In addition to handling the software installation, these bootstrap +templates do the following:</p> <ul> <li>Write the validation.pem per the local knife configuration.</li> @@ -143,7 +151,12 @@ sub-command looks in the following locations for the template to use:</p> </ul> -<p>In the case of the RubyGems, the <code>client.rb</code> will be written from scratch with a minimal set of values; see <strong>EXAMPLES</strong>. In the case of APT Package installation, <code>client.rb</code> will have the <code>validation_client_name</code> appended if it is not set to <code>chef-validator</code> (default config value), and the <code>node_name</code> will be added if <code>chef_node_name</code> option is specified.</p> +<p>In the case of the RubyGems, the <code>client.rb</code> will be written from +scratch with a minimal set of values; see <strong>EXAMPLES</strong>. In the case of +APT Package installation, <code>client.rb</code> will have the +<code>validation_client_name</code> appended if it is not set to <code>chef-validator</code> +(default config value), and the <code>node_name</code> will be added if +<code>chef_node_name</code> option is specified.</p> <p>When this is complete, the bootstrapped node will have:</p> @@ -154,7 +167,50 @@ sub-command looks in the following locations for the template to use:</p> </ul> -<p>Additional custom bootstrap templates can be created and stored in <code>.chef/bootstrap/DISTRO.erb</code>, replacing <strong>DISTRO</strong> with the value passed with the <code>-d</code> or <code>--distro</code> option. See <strong>EXAMPLES</strong> for more information.</p> +<p>Additional custom bootstrap templates can be created and stored in +<code>.chef/bootstrap/DISTRO.erb</code>, replacing <strong>DISTRO</strong> with the value passed +with the <code>-d</code> or <code>--distro</code> option. See <strong>EXAMPLES</strong> for more +information.</p> + +<h2 id="EXAMPLES">EXAMPLES</h2> + +<p>Setting up a custom bootstrap is fairly straightforward. Create a +<code>.chef/bootstrap</code> directory in your Chef Repository or in +<code>$HOME/.chef/bootstrap</code>. Then create the ERB template file.</p> + +<pre><code>mkdir ~/.chef/bootstrap +vi ~/.chef/bootstrap/debian5.0-apt.erb +</code></pre> + +<p>For example, to create a new bootstrap template that should be used when +setting up a new Debian node. Edit the template to run the commands, set +up the validation certificate and the client configuration file, and +finally to run chef-client on completion. The bootstrap template can be +called with:</p> + +<pre><code>knife bootstrap mynode.example.com --template-file ~/.chef/bootstrap/debian5.0-apt.erb +</code></pre> + +<p>Or,</p> + +<pre><code>knife bootstrap mynode.example.com --distro debian5.0-apt +</code></pre> + +<p>The <code>--distro</code> parameter will automatically look in the +<code>~/.chef/bootstrap</code> directory for a file named <code>debian5.0-apt.erb</code>.</p> + +<p>Templates provided by the Chef installation are located in +<code>BASEDIR/lib/chef/knife/bootstrap/*.erb</code>, where <em>BASEDIR</em> is the +location where the package or Gem installed the Chef client libraries.</p> + +<h2 id="BUGS">BUGS</h2> + +<p><code>knife bootstrap</code> is not capable of bootstrapping multiple hosts in +parallel.</p> + +<p>The bootstrap script is passed as an argument to <span class="man-ref">sh<span class="s">(1)</span></span> on the remote +system, so sensitive information contained in the script will be visible +to other users via the process list using tools such as <span class="man-ref">ps<span class="s">(1)</span></span>.</p> <h2 id="SEE-ALSO">SEE ALSO</h2> @@ -162,11 +218,11 @@ sub-command looks in the following locations for the template to use:</p> <h2 id="AUTHOR">AUTHOR</h2> -<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> <h2 id="DOCUMENTATION">DOCUMENTATION</h2> -<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. +<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> <h2 id="CHEF">CHEF</h2> diff --git a/chef/distro/common/html/knife-client.1.html b/chef/distro/common/html/knife-client.1.html index f8af84f933..7f13b2e59d 100644 --- a/chef/distro/common/html/knife-client.1.html +++ b/chef/distro/common/html/knife-client.1.html @@ -61,8 +61,7 @@ <div class='man-navigation' style='display:none'> <a href="#NAME">NAME</a> <a href="#SYNOPSIS">SYNOPSIS</a> - <a href="#DESCRIPTION">DESCRIPTION</a> - <a href="#CLIENT-SUB-COMMANDS">CLIENT SUB-COMMANDS</a> + <a href="#SUB-COMMANDS">SUB-COMMANDS</a> <a href="#BULK-DELETE">BULK DELETE</a> <a href="#CREATE">CREATE</a> <a href="#DELETE">DELETE</a> @@ -70,6 +69,7 @@ <a href="#LIST">LIST</a> <a href="#REREGISTER">REREGISTER</a> <a href="#SHOW">SHOW</a> + <a href="#DESCRIPTION">DESCRIPTION</a> <a href="#SEE-ALSO">SEE ALSO</a> <a href="#AUTHOR">AUTHOR</a> <a href="#DOCUMENTATION">DOCUMENTATION</a> @@ -91,24 +91,10 @@ <p><strong>knife</strong> <strong>client</strong> <em>sub-command</em> <em>(options)</em></p> -<h2 id="DESCRIPTION">DESCRIPTION</h2> - -<p>Clients are identities used for communication with the Chef Server API, -roughly equivalent to user accounts on the Chef Server, except that -clients only communicate with the Chef Server API and are authenticated -via request signatures.</p> - -<p>In the typical case, there will be one client object on the server for -each node, and the corresponding client and node will have identical -names.</p> - -<p>In the Chef authorization model, there is one special client, the -"validator", which is authorized to create new non-administrative -clients but has minimal privileges otherwise. This identity is used as a -sort of "guest account" to create a client identity when initially -setting up a host for management with Chef.</p> +<h2 id="SUB-COMMANDS">SUB-COMMANDS</h2> -<h2 id="CLIENT-SUB-COMMANDS">CLIENT SUB-COMMANDS</h2> +<p>Client subcommands follow a basic create, read, update, delete (CRUD) +pattern. The Following subcommands are available:</p> <h2 id="BULK-DELETE">BULK DELETE</h2> @@ -187,17 +173,34 @@ Use care when reregistering the validator client.</p> <p>Show a client. Output format is determined by the --format option.</p> +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>Clients are identities used for communication with the Chef Server API, +roughly equivalent to user accounts on the Chef Server, except that +clients only communicate with the Chef Server API and are authenticated +via request signatures.</p> + +<p>In the typical case, there will be one client object on the server for +each node, and the corresponding client and node will have identical +names.</p> + +<p>In the Chef authorization model, there is one special client, the +"validator", which is authorized to create new non-administrative +clients but has minimal privileges otherwise. This identity is used as a +sort of "guest account" to create a client identity when initially +setting up a host for management with Chef.</p> + <h2 id="SEE-ALSO">SEE ALSO</h2> <p> <strong>knife-node</strong>(1)</p> <h2 id="AUTHOR">AUTHOR</h2> -<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> <h2 id="DOCUMENTATION">DOCUMENTATION</h2> -<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. +<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> <h2 id="CHEF">CHEF</h2> diff --git a/chef/distro/common/html/knife-cookbook-site.1.html b/chef/distro/common/html/knife-cookbook-site.1.html index 97c240fe54..749fecdff5 100644 --- a/chef/distro/common/html/knife-cookbook-site.1.html +++ b/chef/distro/common/html/knife-cookbook-site.1.html @@ -62,6 +62,15 @@ <a href="#NAME">NAME</a> <a href="#SYNOPSIS">SYNOPSIS</a> <a href="#COOKBOOK-SITE-SUB-COMMANDS">COOKBOOK SITE SUB-COMMANDS</a> + <a href="#INSTALL">INSTALL</a> + <a href="#DOWNLOAD">DOWNLOAD</a> + <a href="#LIST">LIST</a> + <a href="#SEARCH">SEARCH</a> + <a href="#SHARE">SHARE</a> + <a href="#UNSHARE">UNSHARE</a> + <a href="#SHOW">SHOW</a> + <a href="#DESCRIPTION">DESCRIPTION</a> + <a href="#EXAMPLES">EXAMPLES</a> <a href="#SEE-ALSO">SEE ALSO</a> <a href="#AUTHOR">AUTHOR</a> <a href="#DOCUMENTATION">DOCUMENTATION</a> @@ -85,18 +94,55 @@ <h2 id="COOKBOOK-SITE-SUB-COMMANDS">COOKBOOK SITE SUB-COMMANDS</h2> -<p>The following sub-commands are still in the context of cookbooks, but they make use of Opscode's Cookbook Community site, <em>http://cookbooks.opscode.com/</em>. That site has an API, and these sub-commands utilize that API, rather than the Chef Server API.</p> +<p><code>knife cookbook site</code> provides the following subcommands:</p> -<p><strong>cookbook site download COOKBOOK [VERSION]</strong> <em>(options)</em></p> +<h2 id="INSTALL">INSTALL</h2> + +<p><strong>cookbook site install COOKBOOK [VERSION]</strong> <em>(options)</em></p> + +<dl> +<dt><code>-d</code>, <code>--dependencies</code></dt><dd>Grab dependencies automatically</dd> +</dl> + + +<p>Uses <span class="man-ref">git<span class="s">(1)</span></span> version control in conjunction with the cookbook site to +install community contributed cookbooks to your local cookbook +repository. Running <code>knife cookbook site install</code> does the following:</p> + +<ol> +<li>A new "pristine copy" branch is created in git for tracking the +upstream;</li> +<li>All existing cookbooks are removed from the branch;</li> +<li>The cookbook is downloaded from the cookbook site in tarball form;</li> +<li>The downloaded cookbook is untarred, and its contents commited via git;</li> +<li>The pristine copy branch is merged into the master branch.</li> +</ol> + + +<p>By installing cookbook with this process, you can locally modify the +upstream cookbook in your master branch ant let git maintain your +changes as a separate patch. When an updated upstream version becomes +available, you will be able to merge the upstream changes while +maintaining your local modifications.</p> + +<p>If <em>-d</em> is specified, the process is applied recursively to all the +cookbooks <em>COOKBOOK</em> depends on (via metadata <em>dependencies</em>).</p> + +<h2 id="DOWNLOAD">DOWNLOAD</h2> + +<p><strong>knife cookbook site download COOKBOOK [VERSION]</strong> <em>(options)</em></p> <dl> <dt><code>-f</code>, <code>--file FILE</code></dt><dd>The filename to write to</dd> </dl> -<p>Downloads a specific cookbook from the Community site, optionally specifying a certain version.</p> +<p>Downloads a specific cookbook from the Community site, optionally +specifying a certain version.</p> + +<h2 id="LIST">LIST</h2> -<p><strong>cookbook site list</strong> <em>(options)</em></p> +<p><strong>knife cookbook site list</strong> <em>(options)</em></p> <dl> <dt><code>-w</code>, <code>--with-uri</code></dt><dd>Show corresponding URIs</dd> @@ -105,11 +151,15 @@ <p>Lists available cookbooks from the Community site.</p> -<p><strong>cookbook site search QUERY</strong> <em>(options)</em></p> +<h2 id="SEARCH">SEARCH</h2> + +<p><strong>knife cookbook site search QUERY</strong> <em>(options)</em></p> -<p>Searches the Community site with the specified query.</p> +<p>Searches for available cookbooks matching the specified query.</p> -<p><strong>cookbook site share COOKBOOK CATEGORY</strong> <em>(options)</em></p> +<h2 id="SHARE">SHARE</h2> + +<p><strong>knife cookbook site share COOKBOOK CATEGORY</strong> <em>(options)</em></p> <dl> <dt><code>-k</code>, <code>--key KEY</code></dt><dd>API Client Key</dd> @@ -118,36 +168,58 @@ </dl> -<p>Uploads the specified cookbook using the given category to the Opscode cookbooks site. Requires a login user and certificate for the Opscode Cookbooks site. See <strong>EXAMPLES</strong> for usage if the Opscode user and certificate pair are not used for authenticating with the Chef Server. In other words, if the Chef Server is not the Opscode Platform.</p> +<p>Uploads the specified cookbook using the given category to the Opscode +cookbooks site. Requires a login user and certificate for the Opscode +Cookbooks site. By default, knife will use the username and API key +you've configured in your configuration file; otherwise you must +explicitly set these values on the command line or use an alternate +configuration file.</p> + +<h2 id="UNSHARE">UNSHARE</h2> -<p><strong>cookbook site unshare COOKBOOK</strong></p> +<p><strong>knife cookbook site unshare COOKBOOK</strong></p> <p>Stops sharing the specified cookbook on the Opscode cookbooks site.</p> -<p><strong>cookbook site show COOKBOOK [VERSION]</strong> <em>(options)</em></p> +<h2 id="SHOW">SHOW</h2> + +<p><strong>knife cookbook site show COOKBOOK [VERSION]</strong> <em>(options)</em></p> <p>Shows information from the site about a particular cookbook.</p> -<p><strong>cookbook site vendor COOKBOOK [VERSION]</strong> <em>(options)</em></p> +<h2 id="DESCRIPTION">DESCRIPTION</h2> -<dl> -<dt><code>-d</code>, <code>--dependencies</code></dt><dd>Grab dependencies automatically</dd> -</dl> +<p>The cookbook site, <a href="http://community.opscode.com/" data-bare-link="true">http://community.opscode.com/</a>, is a cookbook +distribution service operated by Opscode. This service provides users +with a central location to publish cookbooks for sharing with other +community members.</p> + +<p><code>knife cookbook site</code> commands provide an interface to the cookbook +site's HTTP API. For commands that read data from the API, no account is +required. In order to upload cookbooks using the <code>knife cookbook site +share</code> command, you must create an account on the cookbook site and +configure your credentials via command line option or in your knife +configuration file.</p> + +<h2 id="EXAMPLES">EXAMPLES</h2> +<p>Uploading cookbooks to the Opscode cookbooks site:</p> -<p>Uses <code>git</code> version control in conjunction with the cookbook site to download upstream cookbooks. A new vendor branch is created in git, the cookbook downloaded from the site and untarred, then the master branch is merged. This allows the user to track upstream changes to cookbooks while merging in customizations. If <em>-d</em> is specified, all the cookbooks it depends on (via metadata <em>dependencies</em>) are downloaded and untarred as well, each using their own vendor branch.</p> +<pre><code>knife cookbook site share example Other -k ~/.chef/USERNAME.pem -u USERNAME +</code></pre> <h2 id="SEE-ALSO">SEE ALSO</h2> -<p> <strong>knife-environment</strong>(1)</p> +<p> <strong><span class="man-ref">knife-cookbook<span class="s">(1)</span></span></strong> + <a href="http://community.opscode.com/cookbooks" data-bare-link="true">http://community.opscode.com/cookbooks</a></p> <h2 id="AUTHOR">AUTHOR</h2> -<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> <h2 id="DOCUMENTATION">DOCUMENTATION</h2> -<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. +<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> <h2 id="CHEF">CHEF</h2> diff --git a/chef/distro/common/html/knife-cookbook.1.html b/chef/distro/common/html/knife-cookbook.1.html index 007b5d2e42..75d1008e8e 100644 --- a/chef/distro/common/html/knife-cookbook.1.html +++ b/chef/distro/common/html/knife-cookbook.1.html @@ -3,7 +3,7 @@ <head> <meta http-equiv='content-type' value='text/html;charset=utf8'> <meta name='generator' value='Ronn/v0.7.3 (http://github.com/rtomayko/ronn/tree/0.7.3)'> - <title>knife-cookbook(1) - Upload and manage Chef cookbooks</title> + <title>knife-cookbook(1) - upload and manage chef cookbooks</title> <style type='text/css' media='all'> /* style: man */ body#manpage {margin:0} @@ -61,7 +61,23 @@ <div class='man-navigation' style='display:none'> <a href="#NAME">NAME</a> <a href="#SYNOPSIS">SYNOPSIS</a> - <a href="#COOKBOOK-SUB-COMMANDS">COOKBOOK SUB-COMMANDS</a> + <a href="#SUB-COMMANDS">SUB-COMMANDS</a> + <a href="#LIST">LIST</a> + <a href="#SHOW">SHOW</a> + <a href="#UPLOAD">UPLOAD</a> + <a href="#DOWNLOAD">DOWNLOAD</a> + <a href="#DELETE">DELETE</a> + <a href="#BULK-DELETE">BULK DELETE</a> + <a href="#COOKBOOK-CREATE">COOKBOOK CREATE</a> + <a href="#METADATA">METADATA</a> + <a href="#METADATA-FROM-FILE">METADATA FROM FILE</a> + <a href="#TEST">TEST</a> + <a href="#RECIPE-LIST">RECIPE LIST</a> + <a href="#DESCRIPTION">DESCRIPTION</a> + <a href="#SEE-ALSO">SEE ALSO</a> + <a href="#AUTHOR">AUTHOR</a> + <a href="#DOCUMENTATION">DOCUMENTATION</a> + <a href="#CHEF">CHEF</a> </div> <ol class='man-decor man-head man head'> @@ -72,154 +88,278 @@ <h2 id="NAME">NAME</h2> <p class="man-name"> - <code>knife-cookbook</code> - <span class="man-whatis">Upload and manage Chef cookbooks</span> + <code>knife-cookbook</code> - <span class="man-whatis">upload and manage chef cookbooks</span> </p> <h2 id="SYNOPSIS">SYNOPSIS</h2> <p><strong>knife</strong> <strong>cookbook</strong> <em>sub-command</em> <em>(options)</em></p> -<h2 id="COOKBOOK-SUB-COMMANDS">COOKBOOK SUB-COMMANDS</h2> +<h2 id="SUB-COMMANDS">SUB-COMMANDS</h2> -<p>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.</p> +<p><code>knife cookbook</code> supports the following sub commands:</p> -<p><strong>cookbook bulk delete REGEX</strong> <em>(options)</em></p> +<h2 id="LIST">LIST</h2> + +<p><strong>knife cookbook list</strong> <em>(options)</em></p> <dl> -<dt><code>-p</code>, <code>--purge</code></dt><dd>Purge files from backing store. This will disable any cookbook that contains any of the same files as the cookbook being purged.</dd> +<dt><code>-a</code>, <code>--all</code></dt><dd>show all versions of a cookbook instead of just the most recent</dd> +<dt><code>-w</code>, <code>--with-uri</code></dt><dd>show corresponding uris</dd> </dl> -<p>Delete cookbooks on the Chef Server based on a regular expression. The regular expression (<em>REGEX</em>) should be in quotes, not in //'s.</p> +<p>Lists the cookbooks available on the Chef server.</p> + +<h2 id="SHOW">SHOW</h2> -<p><strong>cookbook create COOKBOOK</strong> <em>(options)</em></p> +<p><strong>knife cookbook show cookbook [version] [part] [filename]</strong> <em>(options)</em></p> <dl> -<dt><code>-o</code>, <code>--cookbook-path PATH</code></dt><dd>The directory where the cookbook will be created</dd> -<dt><code>-r</code>, <code>--readme-format FORMAT</code></dt><dd>Format of the README file</dd> -<dt><code>-C</code>, <code>--copyright COPYRIGHT</code></dt><dd>Name of Copyright holder</dd> -<dt><code>-I</code>, <code>--license LICENSE</code></dt><dd>License for cookbook, apachev2 or none</dd> -<dt><code>-E</code>, <code>--email EMAIL</code></dt><dd>Email address of cookbook maintainer</dd> +<dt><code>-f</code>, <code>--fqdn fqdn </code></dt><dd>the fqdn of the host to see the file for</dd> +<dt><code>-p</code>, <code>--platform platform </code></dt><dd>the platform to see the file for</dd> +<dt><code>-v</code>, <code>--platform-version version</code></dt><dd>the platform version to see the file for</dd> </dl> -<p>This is a helper command that creates a new cookbook directory in the <code>cookbook_path</code>. The following directories and files are created for the named cookbook.</p> +<p>show a particular part of a <em>cookbook</em> for the specified <em>version</em>. <em>part</em> can be one of:</p> <ul> -<li>COOKBOOK/attributes</li> -<li>COOKBOOK/definitions</li> -<li>COOKBOOK/files/default</li> -<li>COOKBOOK/libraries</li> -<li>COOKBOOK/metadata.rb</li> -<li>COOKBOOK/providers</li> -<li>COOKBOOK/README.rdoc</li> -<li>COOKBOOK/recipes/default.rb</li> -<li>COOKBOOK/resources</li> -<li>COOKBOOK/templates/default</li> +<li><em>attributes</em></li> +<li><em>definitions</em></li> +<li><em>files</em></li> +<li><em>libraries</em></li> +<li><em>providers</em></li> +<li><em>recipes</em></li> +<li><em>resources</em></li> +<li><em>templates</em></li> </ul> -<p>Supported README formats are 'rdoc' (default), 'md', 'mkd', 'txt'. The README file will be written with the specified extension and a set of helpful starting headers.</p> +<h2 id="UPLOAD">UPLOAD</h2> -<p>Specify <code>-C</code> or <code>--copyright</code> with the name of the copyright holder as your name or your company/organization name in a quoted string. If this value is not specified an all-caps string <code>YOUR_COMPANY_NAME</code> is used which can be easily changed with find/replace.</p> +<p><strong>knife cookbook upload [cookbooks...]</strong> <em>(options)</em></p> -<p>Specify <code>-I</code> or <code>--license</code> with the license that the cookbook is distributed under for sharing with other people or posting to the Opscode Cookbooks site. Be aware of the licenses of files you put inside the cookbook and follow any restrictions they describe. When using <code>none</code> (default) or <code>apachev2</code>, comment header text and metadata file are pre-filled. The <code>none</code> license will be treated as non-redistributable.</p> +<dl> +<dt><code>-a</code>, <code>--all</code></dt><dd>upload all cookbooks, rather than just a single cookbook</dd> +<dt><code>-o</code>, <code>--cookbook-path path:path</code></dt><dd>a colon-separated path to look for cookbooks in</dd> +<dt><code>-E</code>, <code>--environment ENVIRONMENT</code></dt><dd>An <em>ENVIRONMENT</em> to apply the uploaded cookbooks to. Specifying this +option will cause knife to edit the <em>ENVIRONMENT</em> to place a strict +version constraint on the cookbook version(s) uploaded.</dd> +<dt><code>--freeze</code></dt><dd>Sets the frozen flag on the uploaded cookbook(s) Any future attempt +to modify the cookbook without changing the version number will +return an error unless --force is specified.</dd> +<dt class="flush"><code>--force</code></dt><dd>Overrides the frozen flag on a cookbook, allowing you to overwrite a +cookbook version that has previously been uploaded with the --freeze +option.</dd> +</dl> -<p>Specify <code>-E</code> or <code>--email</code> with the email address of the cookbook's maintainer. If this value is not specified, an all-caps string <code>YOUR_EMAIL</code> is used which can easily be changed with find/replace.</p> -<p>The cookbook copyright, license and email settings can be filled in the <code>knife.rb</code>, for example with default values:</p> +<p>Uploads one or more cookbooks from your local cookbook repository(ies) +to the Chef Server. Only files that don't yet exist on the server will +be uploaded.</p> -<pre><code>cookbook_copyright "YOUR_COMPANY_NAME" -cookbook_license "none" -cookbook_email "YOUR_EMAIL" -</code></pre> +<h2 id="DOWNLOAD">DOWNLOAD</h2> -<p><strong>cookbook delete COOKBOOK [VERSION]</strong> <em>(options)</em></p> +<p><strong>knife cookbook download cookbook [version]</strong> <em>(options)</em></p> <dl> -<dt><code>-a</code>, <code>--all</code></dt><dd>Delete all versions</dd> -<dt><code>-p</code>, <code>--purge</code></dt><dd>Purge files from backing store. This will disable any cookbook that contains any of the same files as the cookbook being purged.</dd> +<dt><code>-d</code>, <code>--dir download_directory</code></dt><dd>the directory to download the cookbook into</dd> +<dt><code>-f</code>, <code>--force</code></dt><dd>overwrite an existing directory with the download</dd> +<dt><code>-n</code>, <code>--latest</code></dt><dd>download the latest version of the cookbook</dd> </dl> -<p>Delete the specified <em>VERSION</em> of the named <em>COOKBOOK</em>. If no version is specified, and only one version exists on the server, that version will be deleted. If multiple versions are available on the server, you will be prompted for a version to delete.</p> +<p>download a cookbook from the chef server. if no version is specified and +only one version exists on the server, that version will be downloaded. +if no version is specified and multiple versions are available on the +server, you will be prompted for a version to download.</p> -<p><strong>cookbook download COOKBOOK [VERSION]</strong> <em>(options)</em></p> +<h2 id="DELETE">DELETE</h2> + +<p><strong>knife cookbook delete cookbook [version]</strong> <em>(options)</em></p> <dl> -<dt><code>-d</code>, <code>--dir DOWNLOAD_DIRECTORY</code></dt><dd>The directory to download the cookbook into</dd> -<dt><code>-f</code>, <code>--force</code></dt><dd>Overwrite an existing directory with the download</dd> -<dt><code>-N</code>, <code>--latest</code></dt><dd>Download the latest version of the cookbook</dd> +<dt><code>-a</code>, <code>--all</code></dt><dd>delete all versions</dd> +<dt><code>-p</code>, <code>--purge</code></dt><dd>purge files from backing store. this will disable any cookbook that contains any of the same files as the cookbook being purged.</dd> </dl> -<p>Download a cookbook from the Chef Server. If no version is specified and only one version exists on the server, that version will be downloaded. If no version is specified and multiple versions are available on the server, you will be prompted for a version to download.</p> +<p>delete the specified <em>version</em> of the named <em>cookbook</em>. if no version is +specified, and only one version exists on the server, that version will +be deleted. if multiple versions are available on the server, you will +be prompted for a version to delete.</p> + +<h2 id="BULK-DELETE">BULK DELETE</h2> -<p><strong>cookbook list</strong> <em>(options)</em></p> +<p><strong>knife cookbook bulk delete regex</strong> <em>(options)</em></p> <dl> -<dt><code>-w</code>, <code>--with-uri</code></dt><dd>Show corresponding URIs</dd> +<dt><code>-p</code>, <code>--purge</code></dt><dd>purge files from backing store. this will disable any cookbook that +contains any of the same files as the cookbook being purged.</dd> </dl> -<p>List all the cookbooks.</p> +<p>delete cookbooks on the chef server based on a regular expression. the +regular expression (<em>regex</em>) should be in quotes, not in //'s.</p> -<p><strong>cookbook metadata COOKBOOK</strong> <em>(options)</em></p> +<h2 id="COOKBOOK-CREATE">COOKBOOK CREATE</h2> + +<p><strong>knife cookbook create cookbook</strong> <em>(options)</em></p> <dl> -<dt><code>-a</code>, <code>--all</code></dt><dd>Generate metadata for all cookbooks, rather than just a single cookbook</dd> -<dt><code>-o</code>, <code>--cookbook-path PATH:PATH</code></dt><dd>A colon-separated path to look for cookbooks in</dd> +<dt><code>-o</code>, <code>--cookbook-path path</code></dt><dd>the directory where the cookbook will be created</dd> +<dt><code>-r</code>, <code>--readme-format format</code></dt><dd>format of the readme file</dd> +<dt><code>-c</code>, <code>--copyright copyright</code></dt><dd>name of copyright holder</dd> +<dt><code>-i</code>, <code>--license license</code></dt><dd>license for cookbook, apachev2 or none</dd> +<dt><code>-e</code>, <code>--email email</code></dt><dd>email address of cookbook maintainer</dd> </dl> -<p>Generate cookbook metadata for the named <em>COOKBOOK</em>. The <em>PATH</em> used here specifies where the cookbooks directory is located and corresponds to the <code>cookbook_path</code> configuration option.</p> +<p>this is a helper command that creates a new cookbook directory in the +<code>cookbook_path</code>. the following directories and files are created for the +named cookbook.</p> + +<ul> +<li>cookbook/attributes</li> +<li>cookbook/definitions</li> +<li>cookbook/files/default</li> +<li>cookbook/libraries</li> +<li>cookbook/metadata.rb</li> +<li>cookbook/providers</li> +<li>cookbook/readme.rdoc</li> +<li>cookbook/recipes/default.rb</li> +<li>cookbook/resources</li> +<li>cookbook/templates/default</li> +</ul> + -<p><strong>cookbook metadata from FILE</strong> <em>(options)</em></p> +<p>supported readme formats are 'rdoc' (default), 'md', 'mkd', 'txt'. the +readme file will be written with the specified extension and a set of +helpful starting headers.</p> + +<p>specify <code>-c</code> or <code>--copyright</code> with the name of the copyright holder as +your name or your company/organization name in a quoted string. if this +value is not specified an all-caps string <code>your_company_name</code> is used +which can be easily changed with find/replace.</p> + +<p>specify <code>-i</code> or <code>--license</code> with the license that the cookbook is +distributed under for sharing with other people or posting to the +opscode cookbooks site. be aware of the licenses of files you put inside +the cookbook and follow any restrictions they describe. when using +<code>none</code> (default) or <code>apachev2</code>, comment header text and metadata file +are pre-filled. the <code>none</code> license will be treated as +non-redistributable.</p> + +<p>specify <code>-e</code> or <code>--email</code> with the email address of the cookbook's +maintainer. if this value is not specified, an all-caps string +<code>your_email</code> is used which can easily be changed with find/replace.</p> + +<p>the cookbook copyright, license and email settings can be filled in the +<code>knife.rb</code>, for example with default values:</p> + +<pre><code>cookbook_copyright "your_company_name" +cookbook_license "none" +cookbook_email "your_email" +</code></pre> -<p>Load the cookbook metadata from a specified file.</p> +<h2 id="METADATA">METADATA</h2> -<p><strong>cookbook show COOKBOOK [VERSION] [PART] [FILENAME]</strong> <em>(options)</em></p> +<p><strong>knife cookbook metadata cookbook</strong> <em>(options)</em></p> <dl> -<dt><code>-f</code>, <code>--fqdn FQDN </code></dt><dd>The FQDN of the host to see the file for</dd> -<dt><code>-p</code>, <code>--platform PLATFORM </code></dt><dd>The platform to see the file for</dd> -<dt><code>-V</code>, <code>--platform-version VERSION</code></dt><dd>The platform version to see the file for</dd> +<dt><code>-a</code>, <code>--all</code></dt><dd>generate metadata for all cookbooks, rather than just a single cookbook</dd> +<dt><code>-o</code>, <code>--cookbook-path path:path</code></dt><dd>a colon-separated path to look for cookbooks in</dd> </dl> -<p>Show a particular part of a <em>COOKBOOK</em> for the specified <em>VERSION</em>. <em>PART</em> can be one of:</p> +<p>generate cookbook metadata for the named <em>cookbook</em>. the <em>path</em> used here specifies where the cookbooks directory is located and corresponds to the <code>cookbook_path</code> configuration option.</p> -<ul> -<li><em>attributes</em></li> -<li><em>definitions</em></li> -<li><em>files</em></li> -<li><em>libraries</em></li> -<li><em>providers</em></li> -<li><em>recipes</em></li> -<li><em>resources</em></li> -<li><em>templates</em></li> -</ul> +<h2 id="METADATA-FROM-FILE">METADATA FROM FILE</h2> +<p><strong>knife cookbook metadata from file</strong> <em>(options)</em></p> -<p><strong>cookbook test [COOKBOOKS...]</strong> <em>(options)</em></p> +<p>load the cookbook metadata from a specified file.</p> + +<h2 id="TEST">TEST</h2> + +<p><strong>knife cookbook test [cookbooks...]</strong> <em>(options)</em></p> <dl> -<dt><code>-a</code>, <code>--all</code></dt><dd>Test all cookbooks, rather than just a single cookbook</dd> -<dt><code>-o</code>, <code>--cookbook-path PATH:PATH</code></dt><dd>A colon-separated path to look for cookbooks in</dd> +<dt><code>-a</code>, <code>--all</code></dt><dd>test all cookbooks, rather than just a single cookbook</dd> +<dt><code>-o</code>, <code>--cookbook-path path:path</code></dt><dd>a colon-separated path to look for cookbooks in</dd> </dl> -<p>Test the specified cookbooks for syntax errors. This uses the built-in Ruby syntax checking option for files in the cookbook ending in <code>.rb</code>, and the ERB syntax check for files ending in <code>.erb</code> (templates).</p> +<p>test the specified cookbooks for syntax errors. this uses the built-in +ruby syntax checking option for files in the cookbook ending in <code>.rb</code>, +and the erb syntax check for files ending in <code>.erb</code> (templates).</p> + +<h2 id="RECIPE-LIST">RECIPE LIST</h2> -<p><strong>cookbook upload [COOKBOOKS...]</strong> <em>(options)</em></p> +<p><strong>knife recipe list [PATTERN]</strong></p> + +<p>List available recipes from the server. Specify <em>PATTERN</em> as a regular +expression to limit the results.</p> + +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>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.</p> + +<p>On disk, cookbooks are directories with a defined structure. The +following directories may appear within a cookbook:</p> <dl> -<dt><code>-a</code>, <code>--all</code></dt><dd>Upload all cookbooks, rather than just a single cookbook</dd> -<dt><code>-o</code>, <code>--cookbook-path PATH:PATH</code></dt><dd>A colon-separated path to look for cookbooks in</dd> +<dt>COOKBOOK/attributes/</dt><dd>Ruby files that define default parameters to be used in recipes</dd> +<dt>COOKBOOK/definitions/</dt><dd>Ruby files that contain <em>resource definitions</em></dd> +<dt>COOKBOOK/files/SPECIFICITY</dt><dd>Files of arbitrary type. These files may be downloaded by +<span class="man-ref">chef-client<span class="s">(8)</span></span> when configuring a host.</dd> +<dt>COOKBOOK/libraries/</dt><dd>Ruby files that contain library code needed for recipes</dd> +<dt>COOKBOOK/providers/</dt><dd>Ruby files that contain Lightweight Provider definitions</dd> +<dt>COOKBOOK/recipes/</dt><dd>Ruby files that use Chef's recipe DSL to describe the desired +configuration of a system</dd> +<dt>COOKBOOK/resources/</dt><dd>Ruby files that contain Lightweight Resource definitions</dd> +<dt>COOKBOOK/templates/SPECIFICITY</dt><dd>ERuby (ERb) template files. These are referenced by <em>recipes</em> and +evaluated to dynamically generate configuration files.</dd> </dl> -<p>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 <code>cookbook_path</code> (or <code>-o PATH</code>) is processed to search for the named cookbook, and each occurance is copied in the order specified. A syntax check is performed a la <code>cookbook test</code>, above. The metadata is generated, a la <code>cookbook metadata</code>. A <span class="man-ref">gzip<span class="s">(1)</span></span>'ed, <span class="man-ref">tar<span class="s">(1)</span></span> file is created, and is uploaded to the server.</p> +<p><strong>SPECIFICITY</strong> is a feature of <em>files</em> and <em>templates</em> that allow you +to specify alternate files to be used on a specific OS platform or host. +The default specificity setting is <em>default</em>, that is files in +<code>COOKBOOK/files/default</code> will be used when a more specific copy is not +available. Further documentation for this feature is available on the +Chef wiki: <a href="http://wiki.opscode.com/display/chef/File+Distribution#FileDistribution-FileSpecificity" data-bare-link="true">http://wiki.opscode.com/display/chef/File+Distribution#FileDistribution-FileSpecificity</a></p> + +<p>Cookbooks also contain a metadata file that defines various properties +of the cookbook. The most important of these are the <em>version</em> and the +<em>dependencies</em>. The <em>version</em> is used in combination with environments +to select which copy of a given cookbook is distributed to a node. The +<em>dependencies</em> are used by the server to determine which additional +cookbooks must be distributed to a given host when it requires a +cookbook.</p> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<p> <strong><span class="man-ref">knife-environment<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-cookbook-site<span class="s">(1)</span></span></strong> + <a href="http://wiki.opscode.com/display/chef/Cookbooks" data-bare-link="true">http://wiki.opscode.com/display/chef/Cookbooks</a> + <a href="http://wiki.opscode.com/display/chef/Metadata" data-bare-link="true">http://wiki.opscode.com/display/chef/Metadata</a></p> + +<h2 id="AUTHOR">AUTHOR</h2> + +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> + +<h2 id="DOCUMENTATION">DOCUMENTATION</h2> + +<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> + +<h2 id="CHEF">CHEF</h2> + +<p> Knife is distributed with Chef. <a href="http://wiki.opscode.com/display/chef/Home" data-bare-link="true">http://wiki.opscode.com/display/chef/Home</a></p> <ol class='man-decor man-foot man foot'> diff --git a/chef/distro/common/html/knife-environment.1.html b/chef/distro/common/html/knife-environment.1.html index 42367da8db..975db72a43 100644 --- a/chef/distro/common/html/knife-environment.1.html +++ b/chef/distro/common/html/knife-environment.1.html @@ -94,6 +94,9 @@ <h2 id="SUBCOMMANDS">SUBCOMMANDS</h2> +<p>Environment subcommands follow a basic create, read, update, delete +(CRUD) pattern. The following subcommands are available:</p> + <h2 id="CREATE">CREATE</h2> <p><strong>knife environment create</strong> <em>environment</em> <em>(options)</em></p> @@ -241,11 +244,11 @@ override_attributes "aws_s3_bucket" => "production" <h2 id="AUTHOR">AUTHOR</h2> -<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> <h2 id="DOCUMENTATION">DOCUMENTATION</h2> -<p> This manual page was written by Daniel DeLeo <a href="mailto:dan@opscode.com" data-bare-link="true">dan@opscode.com</a>. +<p> This manual page was written by Daniel DeLeo <a href="mailto:dan@opscode.com" data-bare-link="true">dan@opscode.com</a>. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> <h2 id="CHEF">CHEF</h2> diff --git a/chef/distro/common/html/knife-node.1.html b/chef/distro/common/html/knife-node.1.html index c78eb4a361..4bf1325b4d 100644 --- a/chef/distro/common/html/knife-node.1.html +++ b/chef/distro/common/html/knife-node.1.html @@ -119,6 +119,8 @@ settings.</p> <h2 id="NODE-SUB-COMMANDS">NODE SUB-COMMANDS</h2> +<p>The following <code>node</code> subcommands are available:</p> + <h2 id="BULK-DELETE">BULK DELETE</h2> <p><strong>knife node bulk delete</strong> <em>regex</em> <em>(options)</em></p> @@ -245,11 +247,11 @@ run list, the correct syntax is "role[ROLE_NAME]"</p> <h2 id="AUTHOR">AUTHOR</h2> -<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> <h2 id="DOCUMENTATION">DOCUMENTATION</h2> -<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. +<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> <h2 id="CHEF">CHEF</h2> diff --git a/chef/distro/common/html/knife-role.1.html b/chef/distro/common/html/knife-role.1.html index fb584356ce..95607a6585 100644 --- a/chef/distro/common/html/knife-role.1.html +++ b/chef/distro/common/html/knife-role.1.html @@ -62,6 +62,18 @@ <a href="#NAME">NAME</a> <a href="#SYNOPSIS">SYNOPSIS</a> <a href="#ROLE-SUB-COMMANDS">ROLE SUB-COMMANDS</a> + <a href="#LIST">LIST</a> + <a href="#SHOW">SHOW</a> + <a href="#CREATE">CREATE</a> + <a href="#EDIT">EDIT</a> + <a href="#FROM-FILE">FROM FILE</a> + <a href="#DELETE">DELETE</a> + <a href="#BULK-DELETE">BULK DELETE</a> + <a href="#DESCRIPTION">DESCRIPTION</a> + <a href="#SEE-ALSO">SEE ALSO</a> + <a href="#AUTHOR">AUTHOR</a> + <a href="#DOCUMENTATION">DOCUMENTATION</a> + <a href="#CHEF">CHEF</a> </div> <ol class='man-decor man-head man head'> @@ -81,11 +93,33 @@ <h2 id="ROLE-SUB-COMMANDS">ROLE SUB-COMMANDS</h2> -<p><strong>role bulk delete REGEX</strong> <em>(options)</em></p> +<p>The following <code>role</code> subcommands are available:</p> -<p>Delete roles on the Chef Server based on a regular expression. The regular expression (<em>REGEX</em>) should be in quotes, not in //'s.</p> +<h2 id="LIST">LIST</h2> -<p><strong>role create ROLE</strong> <em>(options)</em></p> +<p><strong>knife role list</strong> <em>(options)</em></p> + +<dl> +<dt><code>-w</code>, <code>--with-uri</code></dt><dd>Show corresponding URIs</dd> +</dl> + + +<p>List roles.</p> + +<h2 id="SHOW">SHOW</h2> + +<p><strong>knife role show ROLE</strong> <em>(options)</em></p> + +<dl> +<dt><code>-a</code>, <code>--attribute ATTR</code></dt><dd>Show only one attribute</dd> +</dl> + + +<p>Show a specific role.</p> + +<h2 id="CREATE">CREATE</h2> + +<p><strong>knife role create ROLE</strong> <em>(options)</em></p> <dl> <dt><code>-d</code>, <code>--description</code></dt><dd>The role description</dd> @@ -94,35 +128,65 @@ <p>Create a new role.</p> -<p><strong>role delete ROLE</strong> <em>(options)</em></p> - -<p>Delete a role.</p> +<h2 id="EDIT">EDIT</h2> -<p><strong>role edit ROLE</strong> <em>(options)</em></p> +<p><strong>knife role edit ROLE</strong> <em>(options)</em></p> <p>Edit a role.</p> -<p><strong>role from file FILE</strong> <em>(options)</em></p> +<h2 id="FROM-FILE">FROM FILE</h2> + +<p><strong>knife role from file FILE</strong> <em>(options)</em></p> <p>Create or update a role from a role Ruby DSL (<code>.rb</code>) or JSON file.</p> -<p><strong>role list</strong> <em>(options)</em></p> +<h2 id="DELETE">DELETE</h2> -<dl> -<dt><code>-w</code>, <code>--with-uri</code></dt><dd>Show corresponding URIs</dd> -</dl> +<p><strong>knife role delete ROLE</strong> <em>(options)</em></p> +<p>Delete a role.</p> -<p>List roles.</p> +<h2 id="BULK-DELETE">BULK DELETE</h2> -<p><strong>role show ROLE</strong> <em>(options)</em></p> +<p><strong>knife role bulk delete REGEX</strong> <em>(options)</em></p> -<dl> -<dt><code>-a</code>, <code>--attribute ATTR</code></dt><dd>Show only one attribute</dd> -</dl> +<p>Delete roles on the Chef Server based on a regular expression. The regular expression (<em>REGEX</em>) should be in quotes, not in //'s.</p> +<h2 id="DESCRIPTION">DESCRIPTION</h2> -<p>Show a specific role.</p> +<p>Roles provide a mechanism to group repeated configuration settings. +Roles are data structures that contain <strong>default_attributes</strong>, and +<strong>override_attributes</strong>, which are nested hashes of configuration +settings, and a <strong>run_list</strong>, which is an ordered list of recipes and +roles that should be applied to a host by chef-client.</p> + +<p><strong>default_attributes</strong> will be overridden if they conflict with a value +on a node that includes the role. Conversely, <strong>override_attributes</strong> +will override any values set on nodes that apply them.</p> + +<p>When <strong>chef-client</strong>(8) configures a host, it will "expand" the +<strong>run_list</strong> included in that host's node data. The expansion process +will recursively replace any roles in the run_list with that role's +run_list.</p> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<p> <strong><span class="man-ref">knife-node<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-environment<span class="s">(1)</span></span></strong> + <a href="http://wiki.opscode.com/display/chef/Roles" data-bare-link="true">http://wiki.opscode.com/display/chef/Roles</a> + <a href="http://wiki.opscode.com/display/chef/Attributes" data-bare-link="true">http://wiki.opscode.com/display/chef/Attributes</a></p> + +<h2 id="AUTHOR">AUTHOR</h2> + +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> + +<h2 id="DOCUMENTATION">DOCUMENTATION</h2> + +<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> + +<h2 id="CHEF">CHEF</h2> + +<p> Knife is distributed with Chef. <a href="http://wiki.opscode.com/display/chef/Home" data-bare-link="true">http://wiki.opscode.com/display/chef/Home</a></p> <ol class='man-decor man-foot man foot'> diff --git a/chef/distro/common/html/knife-search.1.html b/chef/distro/common/html/knife-search.1.html index 63ca5975bd..43182cbf71 100644 --- a/chef/distro/common/html/knife-search.1.html +++ b/chef/distro/common/html/knife-search.1.html @@ -61,6 +61,13 @@ <div class='man-navigation' style='display:none'> <a href="#NAME">NAME</a> <a href="#SYNOPSIS">SYNOPSIS</a> + <a href="#DESCRIPTION">DESCRIPTION</a> + <a href="#SYNTAX">SYNTAX</a> + <a href="#EXAMPLES">EXAMPLES</a> + <a href="#SEE-ALSO">SEE ALSO</a> + <a href="#AUTHOR">AUTHOR</a> + <a href="#DOCUMENTATION">DOCUMENTATION</a> + <a href="#CHEF">CHEF</a> </div> <ol class='man-decor man-head man head'> @@ -85,10 +92,44 @@ <dt><code>-r</code>, <code>--run-list</code></dt><dd>Show only the run list</dd> <dt><code>-o</code>, <code>--sort SORT</code></dt><dd>The order to sort the results in</dd> <dt><code>-b</code>, <code>--start ROW</code></dt><dd>The row to start returning results at</dd> +<dt><code>-m</code>, <code>--medium</code></dt><dd>Display medium sized output when searching nodes using the default +summary format</dd> +<dt><code>-l</code>, <code>--long</code></dt><dd>Display long output when searching nodes using the default summary +format</dd> </dl> -<p>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: <em>node</em>, <em>role</em>, <em>client</em>, <em>data bag</em>.</p> +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>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: +* <em>node</em> +* <em>role</em> +* <em>environment</em> +* <em>data bag</em></p> + +<h2 id="SYNTAX">SYNTAX</h2> + +<h2 id="EXAMPLES">EXAMPLES</h2> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<p> <strong>knife-ssh</strong>(1) + <a href="http://wiki.opscode.com/display/chef/Attributes" data-bare-link="true">http://wiki.opscode.com/display/chef/Attributes</a></p> + +<h2 id="AUTHOR">AUTHOR</h2> + +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> + +<h2 id="DOCUMENTATION">DOCUMENTATION</h2> + +<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> + +<h2 id="CHEF">CHEF</h2> + +<p> Knife is distributed with Chef. <a href="http://wiki.opscode.com/display/chef/Home" data-bare-link="true">http://wiki.opscode.com/display/chef/Home</a></p> <ol class='man-decor man-foot man foot'> diff --git a/chef/distro/common/html/knife-ssh.1.html b/chef/distro/common/html/knife-ssh.1.html index 70b09060d0..c73698dab5 100644 --- a/chef/distro/common/html/knife-ssh.1.html +++ b/chef/distro/common/html/knife-ssh.1.html @@ -61,6 +61,12 @@ <div class='man-navigation' style='display:none'> <a href="#NAME">NAME</a> <a href="#SYNOPSIS">SYNOPSIS</a> + <a href="#DESCRIPTION">DESCRIPTION</a> + <a href="#TERMINAL-MULTIPLEXING-AND-TERMINAL-TAB-SUPPORT">TERMINAL MULTIPLEXING AND TERMINAL TAB SUPPORT</a> + <a href="#SEE-ALSO">SEE ALSO</a> + <a href="#AUTHOR">AUTHOR</a> + <a href="#DOCUMENTATION">DOCUMENTATION</a> + <a href="#CHEF">CHEF</a> </div> <ol class='man-decor man-head man head'> @@ -87,7 +93,56 @@ </dl> -<p>The <em>ssh</em> sub-command opens an ssh session to each of the nodes in the search results of the <em>QUERY</em>. 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).</p> +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>The <em>ssh</em> sub-command opens an ssh session to each of the nodes in the +search results of the <em>QUERY</em>. 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).</p> + +<h2 id="TERMINAL-MULTIPLEXING-AND-TERMINAL-TAB-SUPPORT">TERMINAL MULTIPLEXING AND TERMINAL TAB SUPPORT</h2> + +<p><code>knife ssh</code> integrates with several terminal multiplexer programs to +provide a more convenient means of managing multiple ssh sessions. When +the <em>COMMAND</em> option matches one of these, <code>knife ssh</code> will create +multiple interactive ssh sessions running locally in the terminal +multiplexer instead of invoking the command on the remote host.</p> + +<p>The available multiplexers are: + * <code>interactive</code>:</p> + +<pre><code>A built-in multiplexer. `interactive` supports running commands on a +subset of the connected hosts in parallel +</code></pre> + +<dl> +<dt><strong>screen</strong>(1)</dt><dd>Runs ssh interactively inside <code>screen</code>. ~/.screenrc will be sourced +if it exists.</dd> +<dt class="flush"><strong>tmux</strong>(1)</dt><dd>Runs ssh interactively inside tmux.</dd> +<dt><code>macterm</code> (Mac OS X only)</dt><dd>Opens a Terminal.app window and creates a tab for each ssh session. +You must install the rb-appscript gem before you can use this +option.</dd> +</dl> + + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<p> <strong>knife-search</strong>(1)</p> + +<h2 id="AUTHOR">AUTHOR</h2> + +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> + +<h2 id="DOCUMENTATION">DOCUMENTATION</h2> + +<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> + +<h2 id="CHEF">CHEF</h2> + +<p> Knife is distributed with Chef. <a href="http://wiki.opscode.com/display/chef/Home" data-bare-link="true">http://wiki.opscode.com/display/chef/Home</a></p> <ol class='man-decor man-foot man foot'> diff --git a/chef/distro/common/html/knife-status.1.html b/chef/distro/common/html/knife-status.1.html index ecbf78ec97..d29711da10 100644 --- a/chef/distro/common/html/knife-status.1.html +++ b/chef/distro/common/html/knife-status.1.html @@ -61,6 +61,11 @@ <div class='man-navigation' style='display:none'> <a href="#NAME">NAME</a> <a href="#SYNOPSIS">SYNOPSIS</a> + <a href="#DESCRIPTION">DESCRIPTION</a> + <a href="#SEE-ALSO">SEE ALSO</a> + <a href="#AUTHOR">AUTHOR</a> + <a href="#DOCUMENTATION">DOCUMENTATION</a> + <a href="#CHEF">CHEF</a> </div> <ol class='man-decor man-head man head'> @@ -83,7 +88,33 @@ </dl> -<p>The <em>status</em> sub-command searches the Chef Server for all nodes and displays information about the last time the node checked into the server and executed a <code>node.save</code>. The fields displayed are the relative checkin time, the node name, it's operating system platform and version, the fully-qualified domain name and the default IP address. If the <code>-r</code> option is given, the node's run list will also be displayed. Note that depending on the configuration of the nodes, the FQDN and IP displayed may not be publicly reachable.</p> +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>The <em>status</em> sub-command searches the Chef Server for all nodes and +displays information about the last time the node checked into the +server and executed a <code>node.save</code>. The fields displayed are the relative +checkin time, the node name, it's operating system platform and version, +the fully-qualified domain name and the default IP address. If the <code>-r</code> +option is given, the node's run list will also be displayed. Note that +depending on the configuration of the nodes, the FQDN and IP displayed +may not be publicly reachable.</p> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<p> <strong>knife-search</strong>(1)</p> + +<h2 id="AUTHOR">AUTHOR</h2> + +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> + +<h2 id="DOCUMENTATION">DOCUMENTATION</h2> + +<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> + +<h2 id="CHEF">CHEF</h2> + +<p> Knife is distributed with Chef. <a href="http://wiki.opscode.com/display/chef/Home" data-bare-link="true">http://wiki.opscode.com/display/chef/Home</a></p> <ol class='man-decor man-foot man foot'> diff --git a/chef/distro/common/html/knife-tag.1.html b/chef/distro/common/html/knife-tag.1.html index 0c790e1c8a..e7b010d7fe 100644 --- a/chef/distro/common/html/knife-tag.1.html +++ b/chef/distro/common/html/knife-tag.1.html @@ -62,6 +62,13 @@ <a href="#NAME">NAME</a> <a href="#SYNOPSIS">SYNOPSIS</a> <a href="#TAG-SUBCOMMANDS">TAG SUBCOMMANDS</a> + <a href="#CREATE">CREATE</a> + <a href="#DELETE">DELETE</a> + <a href="#LIST">LIST</a> + <a href="#SEE-ALSO">SEE ALSO</a> + <a href="#AUTHOR">AUTHOR</a> + <a href="#DOCUMENTATION">DOCUMENTATION</a> + <a href="#CHEF">CHEF</a> </div> <ol class='man-decor man-head man head'> @@ -81,6 +88,43 @@ <h2 id="TAG-SUBCOMMANDS">TAG SUBCOMMANDS</h2> +<p>The following <code>tag</code> subcommands are available:</p> + +<h2 id="CREATE">CREATE</h2> + +<p><strong>knife tag create</strong> <em>node</em> <em>tag</em> [<em>...</em>]</p> + +<p>Adds one or more tags to <em>node</em></p> + +<h2 id="DELETE">DELETE</h2> + +<p><strong>knife tag delete</strong> <em>node</em> <em>tag</em> [<em>...</em>]</p> + +<p>Removes one or more tags from <em>node</em></p> + +<h2 id="LIST">LIST</h2> + +<p><strong>knife tag list</strong> <em>node</em></p> + +<p>Lists the tags applied to <em>node</em></p> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<p> <strong><span class="man-ref">knife-node<span class="s">(1)</span></span></strong></p> + +<h2 id="AUTHOR">AUTHOR</h2> + +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> with many contributions from the community.</p> + +<h2 id="DOCUMENTATION">DOCUMENTATION</h2> + +<p> This manual page was written by Daniel DeLeo <a href="mailto:dan@opscode.com" data-bare-link="true">dan@opscode.com</a>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> + +<h2 id="CHEF">CHEF</h2> + +<p> Knife is distributed with Chef. <a href="http://wiki.opscode.com/display/chef/Home" data-bare-link="true">http://wiki.opscode.com/display/chef/Home</a></p> + <ol class='man-decor man-foot man foot'> <li class='tl'>Chef 0.10.0.beta.8</li> diff --git a/chef/distro/common/html/knife.1.html b/chef/distro/common/html/knife.1.html index 1c9b985b07..7ec9b83da6 100644 --- a/chef/distro/common/html/knife.1.html +++ b/chef/distro/common/html/knife.1.html @@ -3,7 +3,7 @@ <head> <meta http-equiv='content-type' value='text/html;charset=utf8'> <meta name='generator' value='Ronn/v0.7.3 (http://github.com/rtomayko/ronn/tree/0.7.3)'> - <title>knife(1) - Chef Server REST API utility</title> + <title>knife(1) - Chef Server API client utility</title> <style type='text/css' media='all'> /* style: man */ body#manpage {margin:0} @@ -62,9 +62,8 @@ <a href="#NAME">NAME</a> <a href="#SYNOPSIS">SYNOPSIS</a> <a href="#DESCRIPTION">DESCRIPTION</a> - <a href="#GENERAL-OPTIONS">GENERAL OPTIONS</a> + <a href="#OPTIONS">OPTIONS</a> <a href="#SUB-COMMANDS">SUB-COMMANDS</a> - <a href="#GENERAL-SUB-COMMANDS">GENERAL SUB-COMMANDS</a> <a href="#CONFIGURATION">CONFIGURATION</a> <a href="#FILES">FILES</a> <a href="#CHEF-WORKFLOW">CHEF WORKFLOW</a> @@ -72,6 +71,9 @@ <a href="#ENVIRONMENT">ENVIRONMENT</a> <a href="#SEE-ALSO">SEE ALSO</a> <a href="#AUTHOR">AUTHOR</a> + <a href="#DOCUMENTATION">DOCUMENTATION</a> + <a href="#LICENSE">LICENSE</a> + <a href="#CHEF">CHEF</a> </div> <ol class='man-decor man-head man head'> @@ -82,30 +84,45 @@ <h2 id="NAME">NAME</h2> <p class="man-name"> - <code>knife</code> - <span class="man-whatis">Chef Server REST API utility</span> + <code>knife</code> - <span class="man-whatis">Chef Server API client utility</span> </p> <h2 id="SYNOPSIS">SYNOPSIS</h2> -<p><strong>knife</strong> <em>sub-command</em> <em>(options)</em></p> +<p><strong>knife</strong> <em>sub-command</em> [<em>argument</em>...] <em>(options)</em></p> <h2 id="DESCRIPTION">DESCRIPTION</h2> -<p>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.</p> +<p>Knife is a command-line utility used to manage data on a Chef server +through the HTTP(S) API. Knife is organized into groups of subcommands +centered around the various object types in Chef. Each category of +subcommand is documented in its own manual page. Available topics are:</p> -<p>Unless otherwise specified, output is in JSON format, and input files -are also JSON format.</p> +<ul> +<li>bootstrap</li> +<li>client</li> +<li>configure</li> +<li>cookbook-site</li> +<li>cookbook</li> +<li>data-bag</li> +<li>environment</li> +<li>exec</li> +<li>index</li> +<li>node</li> +<li>recipe</li> +<li>role</li> +<li>search</li> +<li>ssh</li> +<li>status</li> +<li>tag</li> +</ul> -<p>The Chef class <code>Chef::Config</code> that configures the behavior of how knife -runs has options that correspond to command-line options. These are -noted as <code>Chef::Config</code> values.</p> -<h2 id="GENERAL-OPTIONS">GENERAL OPTIONS</h2> +<p>If the knife manuals are in your <code>MANPATH</code>, you can access help for the +above topics using <code>man knife-TOPIC</code>; otherwise, you can view the +documentation using <code>knife help TOPIC</code>.</p> + +<h2 id="OPTIONS">OPTIONS</h2> <dl> <dt><code>-s</code>, <code>--server-url</code> URL</dt><dd>Chef Server URL, corresponds to <code>Chef::Config</code> <code>chef_server_url</code>.</dd> @@ -120,17 +137,15 @@ noted as <code>Chef::Config</code> values.</p> <dt><code>-p</code>, <code>--print-after</code></dt><dd>Show the data after a destructive operation</dd> <dt><code>-v</code>, <code>--version</code></dt><dd>Show chef version</dd> <dt><code>-y</code>, <code>--yes</code></dt><dd>Say yes to all prompts for confirmation</dd> -<dt><code>-h</code>, <code>--help</code></dt><dd>Show this message</dd> +<dt><code>-h</code>, <code>--help</code></dt><dd>Show the available options for a command.</dd> </dl> -<p>Usage information for sub-commands can be displayed with <code>knife SUB-COMMAND --help</code>.</p> - <h2 id="SUB-COMMANDS">SUB-COMMANDS</h2> -<p>Knife sub-commands are structured as <em>NOUN verb NOUN (options)</em>. The -sub-commands are meant to be intuitively named. Because the Chef Server -API is RESTful, sub-commands generally utilize CRUD operations.</p> +<p>Sub-commands that operate on the basic Chef data types are structured as +<em>NOUN verb NOUN (options)</em>. For all data types, the following commands +are available:</p> <ul> <li>create (create)</li> @@ -140,13 +155,8 @@ API is RESTful, sub-commands generally utilize CRUD operations.</p> </ul> -<p>Objects stored on the server support these, as described below.</p> - -<h2 id="GENERAL-SUB-COMMANDS">GENERAL SUB-COMMANDS</h2> - -<p><strong>recipe list [PATTERN]</strong></p> - -<p>List available recipes from the server. Specify <em>PATTERN</em> as a regular expression to limit the results.</p> +<p>Knife also includes commands that take actions other than displaying or +modifying data on the Chef Server, such as <strong><span class="man-ref">knife-ssh<span class="s">(1)</span></span></strong>.</p> <h2 id="CONFIGURATION">CONFIGURATION</h2> @@ -158,68 +168,32 @@ be <code>.chef/knife.rb</code> in the current directory of the repository.</p> <p>If the config file exists, knife uses these settings for <strong>GENERAL OPTIONS</strong> defaults.</p> -<p><code>log_level</code></p> - -<p>A Ruby symbol specifying the log level. Corresponds to <code>-l</code> or <code>--log_level</code> option. Default is <em>:info</em>. Valid values are:</p> - <ul> -<li>:info</li> -<li>:debug</li> -<li>:warn</li> -<li>:fatal</li> -</ul> - - -<p><code>log_location</code></p> - -<p>Corresponds to the <code>-L</code> or <code>--log-file</code> option. Defaults is <strong>STDOUT</strong>. -Valid values are <strong>STDOUT</strong> or a filename.</p> - -<p><code>node_name</code></p> - -<p>User to authenticate to the Chef server. Corresponds to the <code>-u</code> or -<code>--user</code> option. This is requested from the user when running this -sub-command.</p> - -<p><code>client_key</code></p> - -<p>Private key file to authenticate to the Chef server. Corresponds to the -<code>-k</code> or <code>--key</code> option. This is requested from the user when running -this sub-command.</p> - -<p><code>chef_server_url</code></p> - -<p>URL of the Chef server. Corresponds to the <code>-s</code> or <code>--server-url</code> -option. This is requested from the user when running this sub-command.</p> - -<p><code>cache_type</code></p> - -<p>The type of cache to use. Default is BasicFile. This can be any type of +<li><code>node_name</code>: +User or client identity (i.e., <em>name</em>) to use for authenticating +requests to the Chef Server.</li> +<li><code>client_key</code>: +Private key file to authenticate to the Chef server. Corresponds to the +<code>-k</code> or <code>--key</code> option.</li> +<li><code>chef_server_url</code>: +URL of the Chef server. Corresponds to the <code>-s</code> or <code>--server-url</code> +option. This is requested from the user when running this sub-command.</li> +<li><code>cache_type</code>: +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.</p> - -<p><code>cache_options</code></p> - -<p>Specifies various options to use for caching. Default reads the Chef -client configuration (/etc/chef/checksums).</p> - -<p><code>validation_client_name</code></p> - -<p>Specifies the name of the client used to validate new clients. This is -requested from the user when running the configuration sub-command.</p> - -<p><code>validation_key</code></p> - -<p>Specifies the private key file to use for generating ec2 instance data -for validating new clients. This is implied from the -<code>validation_client_name</code>.</p> - -<p><code>cookbook_copyright</code> -<code>cookbook_email</code> -<code>cookbook_license</code></p> - -<p>Used by <code>knife cookbook create</code> sub-command to specify the copyright +Xattr, YAML.</li> +<li><code>cache_options</code>: +Specifies various options to use for caching. These options are +dependent on the <code>cache_type</code>.</li> +<li><code>validation_client_name</code>: +Specifies the name of the client used to validate new clients.</li> +<li><code>validation_key</code>: +Specifies the private key file to use when bootstrapping new hosts. +See <span class="man-ref">knife-client<span class="s">(1)</span></span> for more information about the validation +client.</li> +<li><code>cookbook_copyright</code>, <code>cookbook_email</code>, <code>cookbook_license</code> +Used by <code>knife cookbook create</code> sub-command to specify the copyright holder, maintainer email and license (respectively) for new cookbooks. The copyright holder is listed as the maintainer in the cookbook's metadata and as the Copyright in the comments of the default recipe. The @@ -228,27 +202,9 @@ determines what preamble to put in the comment of the default recipe, and is listed as the license in the cookbook metadata. Currently supported licenses are "apachev2" and "none". Any other values will result in an empty license in the metadata (needs to be filled in by the -author), and no comment preamble in the default recipe.</p> - -<p><code>knife[:aws_access_key_id]</code> -<code>knife[:aws_secret_access_key]</code></p> - -<p>Specifies the Amazon AWS EC2 credentials to use when running the ec2 sub-commands.</p> - -<p><code>knife[:rackspace_api_username]</code> -<code>knife[:rackspace_api_key]</code></p> - -<p>Specifies the Rackspace Cloud credentials to use when running the rackspace sub-commands.</p> - -<p><code>knife[:terremark_username]</code> -<code>knife[:terremark_password]</code> -<code>knife[:terremark_service]</code></p> - -<p>Specifies the Terremark vCloud credentials to use when running the terremark sub-commands.</p> - -<p><code>knife[:slicehost_password]</code></p> +author), and no comment preamble in the default recipe.</li> +</ul> -<p>Specifies the Slicehost password to use when running the slicdehost sub-commands.</p> <h2 id="FILES">FILES</h2> @@ -279,50 +235,6 @@ recommended though, and git fits with a lot of the workflow paradigms.</p> <h2 id="EXAMPLES">EXAMPLES</h2> -<p>Example client config (<code>/etc/chef/client.rb</code>) from <code>knife configure -client</code>. The same configuration is used when using the <code>knife bootstrap</code> -command with the default <code>gem</code> templates that come with Chef.</p> - -<pre><code>log_level :info -log_location STDOUT -chef_server_url 'https://api.opscode.com/organizations/ORGNAME' -validation_client_name 'ORGNAME-validator' -</code></pre> - -<p>Setting up a custom bootstrap is fairly straightforward. Create -<code>.chef/bootstrap</code> in your Chef Repository directory or in -<code>$HOME/.chef/bootstrap</code>. Then create the ERB template file.</p> - -<pre><code>mkdir ~/.chef/bootstrap -vi ~/.chef/bootstrap/debian5.0-apt.erb -</code></pre> - -<p>For example, to create a new bootstrap template that should be used when -setting up a new Debian node. Edit the template to run the commands, set -up the validation certificate and the client configuration file, and -finally to run chef-client on completion. The bootstrap template can be -called with:</p> - -<pre><code>knife bootstrap mynode.example.com --template-file ~/.chef/bootstrap/debian5.0-apt.erb -</code></pre> - -<p>Or,</p> - -<pre><code>knife bootstrap mynode.example.com --distro debian5.0-apt -</code></pre> - -<p>The <code>--distro</code> parameter will automatically look in the -<code>~/.chef/bootstrap</code> directory for a file named <code>debian5.0-apt.erb</code>.</p> - -<p>Templates provided by the Chef installation are located in -<code>BASEDIR/lib/chef/knife/bootstrap/*.erb</code>, where <em>BASEDIR</em> is the -location where the package or Gem installed the Chef client libraries.</p> - -<p>Uploading cookbooks to the Opscode cookbooks site using the user/certificate specifically:</p> - -<pre><code>knife cookbook site share example Other -k ~/.chef/USERNAME.pem -u USERNAME -</code></pre> - <h2 id="ENVIRONMENT">ENVIRONMENT</h2> <dl> @@ -334,21 +246,42 @@ data editing entirely.</dd> <h2 id="SEE-ALSO">SEE ALSO</h2> -<p>Full documentation for Chef is located on the Chef wiki, http://wiki.opscode.com/display/chef/Home/.</p> +<p> <strong><span class="man-ref">chef-client<span class="s">(8)</span></span></strong> <strong><span class="man-ref">chef-server<span class="s">(8)</span></span></strong> <strong><span class="man-ref">shef<span class="s">(1)</span></span></strong></p> -<p>JSON is JavaScript Object Notation and more information can be found at http://json.org/.</p> +<p> <strong><span class="man-ref">knife-bootstrap<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-client<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-configure<span class="s">(1)</span></span></strong> + <strong><span class="man-ref">knife-cookbook-site<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-cookbook<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-data-bag<span class="s">(1)</span></span></strong> + <strong><span class="man-ref">knife-environment<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-exec<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-index<span class="s">(1)</span></span></strong> + <strong><span class="man-ref">knife-node<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-recipe<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-role<span class="s">(1)</span></span></strong> + <strong><span class="man-ref">knife-search<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-ssh<span class="s">(1)</span></span></strong> <strong><span class="man-ref">knife-tag<span class="s">(1)</span></span></strong></p> -<p>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/.</p> +<p> Complete Chef documentation is available online: <a href="http://wiki.opscode.com/display/chef/Home/" data-bare-link="true">http://wiki.opscode.com/display/chef/Home/</a></p> -<p>Git is a version control system and documented at http://git-scm.com/.</p> +<p> JSON is JavaScript Object Notation <a href="http://json.org/" data-bare-link="true">http://json.org/</a></p> -<p>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.</p> +<p> SOLR is an open source search engine. <a href="http://lucene.apache.org/solr/" data-bare-link="true">http://lucene.apache.org/solr/</a></p> + +<p> <strong><span class="man-ref">git<span class="s">(1)</span></span></strong> is a version control system <a href="http://git-scm.com/" data-bare-link="true">http://git-scm.com/</a></p> + +<p> This manual page was generated from Markdown with <strong><span class="man-ref">ronn<span class="s">(1)</span></span></strong> <a href="http://rtomayko.github.com/ronn/ronn.1.html" data-bare-link="true">http://rtomayko.github.com/ronn/ronn.1.html</a></p> <h2 id="AUTHOR">AUTHOR</h2> -<p>Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> of Opscode (<a href="http://www.opscode.com" data-bare-link="true">http://www.opscode.com</a>), with contributions from the community. This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p> +<p> Chef was written by Adam Jacob <a href="mailto:adam@opscode.com" data-bare-link="true">adam@opscode.com</a> of Opscode + (<a href="http://www.opscode.com" data-bare-link="true">http://www.opscode.com</a>), with contributions from the community.</p> + +<h2 id="DOCUMENTATION">DOCUMENTATION</h2> + +<p> This manual page was written by Joshua Timberman <a href="mailto:joshua@opscode.com" data-bare-link="true">joshua@opscode.com</a>.</p> + +<h2 id="LICENSE">LICENSE</h2> + +<p> Both Chef and this documentation are released under the terms of the + Apache 2.0 License. You may view the license online: <a href="http://www.apache.org/licenses/LICENSE-2.0.html" data-bare-link="true">http://www.apache.org/licenses/LICENSE-2.0.html</a> + On some systems, the complete text of the Apache 2.0 License may be found in <code>/usr/share/common-licenses/Apache-2.0</code>.</p> + +<h2 id="CHEF">CHEF</h2> -<p>On Debian systems, the complete text of the Apache 2.0 License can be found in <code>/usr/share/common-licenses/Apache-2.0</code>.</p> +<p> Knife is distributed with Chef. <a href="http://wiki.opscode.com/display/chef/Home" data-bare-link="true">http://wiki.opscode.com/display/chef/Home</a></p> <ol class='man-decor man-foot man foot'> diff --git a/chef/distro/common/man/man1/knife-bootstrap.1 b/chef/distro/common/man/man1/knife-bootstrap.1 index 92a2f1b0f9..4f8e38aea5 100644 --- a/chef/distro/common/man/man1/knife-bootstrap.1 +++ b/chef/distro/common/man/man1/knife-bootstrap.1 @@ -54,7 +54,7 @@ Execute the bootstrap via sudo Bootstrap a distro using a template . .SH "DESCRIPTION" -Performs a Chef Bootstrap on the target node\. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server\. The main assumption is a baseline OS installation exists\. This sub\-command is used internally by some cloud computing server create commands and the others will be migrated in a future version of Chef\. +Performs a Chef Bootstrap on the target node\. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server\. The main assumption is a baseline OS installation exists\. This sub\-command is used internally by some cloud computing plugins\. . .P The bootstrap sub\-command supports supplying a template to perform the bootstrap steps\. If the distro is not specified (via \fB\-d\fR or \fB\-\-distro\fR option), an Ubuntu 10\.04 host bootstrapped with RubyGems is assumed\. The \fBDISTRO\fR value corresponds to the base filename of the template, in other words \fBDISTRO\fR\.erb\. A template file can be specified with the \fB\-\-template\-file\fR option in which case the \fBDISTRO\fR is not used\. The sub\-command looks in the following locations for the template to use: @@ -71,7 +71,7 @@ The bootstrap sub\-command supports supplying a template to perform the bootstra .IP "" 0 . .P -The default bootstrap templates are scripts that get copied to the target node (FQDN)\. As of Chef 0\.9\.8, the following distros are supported: +The default bootstrap templates are scripts that get copied to the target node (FQDN)\. The following distros are supported: . .IP "\(bu" 4 centos5\-gems @@ -124,6 +124,58 @@ Have run Chef with its default run list if one is specfied\. .P Additional custom bootstrap templates can be created and stored in \fB\.chef/bootstrap/DISTRO\.erb\fR, replacing \fBDISTRO\fR with the value passed with the \fB\-d\fR or \fB\-\-distro\fR option\. See \fBEXAMPLES\fR for more information\. . +.SH "EXAMPLES" +Setting up a custom bootstrap is fairly straightforward\. Create a \fB\.chef/bootstrap\fR directory in your Chef Repository or in \fB$HOME/\.chef/bootstrap\fR\. Then create the ERB template file\. +. +.IP "" 4 +. +.nf + +mkdir ~/\.chef/bootstrap +vi ~/\.chef/bootstrap/debian5\.0\-apt\.erb +. +.fi +. +.IP "" 0 +. +.P +For example, to create a new bootstrap template that should be used when setting up a new Debian node\. Edit the template to run the commands, set up the validation certificate and the client configuration file, and finally to run chef\-client on completion\. The bootstrap template can be called with: +. +.IP "" 4 +. +.nf + +knife bootstrap mynode\.example\.com \-\-template\-file ~/\.chef/bootstrap/debian5\.0\-apt\.erb +. +.fi +. +.IP "" 0 +. +.P +Or, +. +.IP "" 4 +. +.nf + +knife bootstrap mynode\.example\.com \-\-distro debian5\.0\-apt +. +.fi +. +.IP "" 0 +. +.P +The \fB\-\-distro\fR parameter will automatically look in the \fB~/\.chef/bootstrap\fR directory for a file named \fBdebian5\.0\-apt\.erb\fR\. +. +.P +Templates provided by the Chef installation are located in \fBBASEDIR/lib/chef/knife/bootstrap/*\.erb\fR, where \fIBASEDIR\fR is the location where the package or Gem installed the Chef client libraries\. +. +.SH "BUGS" +\fBknife bootstrap\fR is not capable of bootstrapping multiple hosts in parallel\. +. +.P +The bootstrap script is passed as an argument to sh(1) on the remote system, so sensitive information contained in the script will be visible to other users via the process list using tools such as ps(1)\. +. .SH "SEE ALSO" \fBknife\-ssh\fR(1) . diff --git a/chef/distro/common/man/man1/knife-client.1 b/chef/distro/common/man/man1/knife-client.1 index d217ec3312..9ed4e069a6 100644 --- a/chef/distro/common/man/man1/knife-client.1 +++ b/chef/distro/common/man/man1/knife-client.1 @@ -9,16 +9,8 @@ .SH "SYNOPSIS" \fBknife\fR \fBclient\fR \fIsub\-command\fR \fI(options)\fR . -.SH "DESCRIPTION" -Clients are identities used for communication with the Chef Server API, roughly equivalent to user accounts on the Chef Server, except that clients only communicate with the Chef Server API and are authenticated via request signatures\. -. -.P -In the typical case, there will be one client object on the server for each node, and the corresponding client and node will have identical names\. -. -.P -In the Chef authorization model, there is one special client, the "validator", which is authorized to create new non\-administrative clients but has minimal privileges otherwise\. This identity is used as a sort of "guest account" to create a client identity when initially setting up a host for management with Chef\. -. -.SH "CLIENT SUB\-COMMANDS" +.SH "SUB\-COMMANDS" +Client subcommands follow a basic create, read, update, delete (CRUD) pattern\. The Following subcommands are available: . .SH "BULK DELETE" \fBknife client bulk delete\fR \fIregex\fR \fI(options)\fR @@ -85,6 +77,15 @@ Show only one attribute .P Show a client\. Output format is determined by the \-\-format option\. . +.SH "DESCRIPTION" +Clients are identities used for communication with the Chef Server API, roughly equivalent to user accounts on the Chef Server, except that clients only communicate with the Chef Server API and are authenticated via request signatures\. +. +.P +In the typical case, there will be one client object on the server for each node, and the corresponding client and node will have identical names\. +. +.P +In the Chef authorization model, there is one special client, the "validator", which is authorized to create new non\-administrative clients but has minimal privileges otherwise\. This identity is used as a sort of "guest account" to create a client identity when initially setting up a host for management with Chef\. +. .SH "SEE ALSO" \fBknife\-node\fR(1) . diff --git a/chef/distro/common/man/man1/knife-cookbook-site.1 b/chef/distro/common/man/man1/knife-cookbook-site.1 index c3c5fd34ab..156d36c66e 100644 --- a/chef/distro/common/man/man1/knife-cookbook-site.1 +++ b/chef/distro/common/man/man1/knife-cookbook-site.1 @@ -10,10 +10,43 @@ \fBknife\fR \fBcookbook site\fR \fIsub\-command\fR \fI(options)\fR . .SH "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, \fIhttp://cookbooks\.opscode\.com/\fR\. That site has an API, and these sub\-commands utilize that API, rather than the Chef Server API\. +\fBknife cookbook site\fR provides the following subcommands: +. +.SH "INSTALL" +\fBcookbook site install COOKBOOK [VERSION]\fR \fI(options)\fR +. +.TP +\fB\-d\fR, \fB\-\-dependencies\fR +Grab dependencies automatically +. +.P +Uses git(1) version control in conjunction with the cookbook site to install community contributed cookbooks to your local cookbook repository\. Running \fBknife cookbook site install\fR does the following: +. +.IP "1." 4 +A new "pristine copy" branch is created in git for tracking the upstream; +. +.IP "2." 4 +All existing cookbooks are removed from the branch; +. +.IP "3." 4 +The cookbook is downloaded from the cookbook site in tarball form; +. +.IP "4." 4 +The downloaded cookbook is untarred, and its contents commited via git; +. +.IP "5." 4 +The pristine copy branch is merged into the master branch\. +. +.IP "" 0 +. +.P +By installing cookbook with this process, you can locally modify the upstream cookbook in your master branch ant let git maintain your changes as a separate patch\. When an updated upstream version becomes available, you will be able to merge the upstream changes while maintaining your local modifications\. . .P -\fBcookbook site download COOKBOOK [VERSION]\fR \fI(options)\fR +If \fI\-d\fR is specified, the process is applied recursively to all the cookbooks \fICOOKBOOK\fR depends on (via metadata \fIdependencies\fR)\. +. +.SH "DOWNLOAD" +\fBknife cookbook site download COOKBOOK [VERSION]\fR \fI(options)\fR . .TP \fB\-f\fR, \fB\-\-file FILE\fR @@ -22,8 +55,8 @@ The filename to write to .P Downloads a specific cookbook from the Community site, optionally specifying a certain version\. . -.P -\fBcookbook site list\fR \fI(options)\fR +.SH "LIST" +\fBknife cookbook site list\fR \fI(options)\fR . .TP \fB\-w\fR, \fB\-\-with\-uri\fR @@ -32,14 +65,14 @@ Show corresponding URIs .P Lists available cookbooks from the Community site\. . -.P -\fBcookbook site search QUERY\fR \fI(options)\fR +.SH "SEARCH" +\fBknife cookbook site search QUERY\fR \fI(options)\fR . .P -Searches the Community site with the specified query\. +Searches for available cookbooks matching the specified query\. . -.P -\fBcookbook site share COOKBOOK CATEGORY\fR \fI(options)\fR +.SH "SHARE" +\fBknife cookbook site share COOKBOOK CATEGORY\fR \fI(options)\fR . .TP \fB\-k\fR, \fB\-\-key KEY\fR @@ -54,32 +87,41 @@ API Client Username A colon\-separated path to look for cookbooks in . .P -Uploads the specified cookbook using the given category to the Opscode cookbooks site\. Requires a login user and certificate for the Opscode Cookbooks site\. See \fBEXAMPLES\fR for usage if the Opscode user and certificate pair are not used for authenticating with the Chef Server\. In other words, if the Chef Server is not the Opscode Platform\. +Uploads the specified cookbook using the given category to the Opscode cookbooks site\. Requires a login user and certificate for the Opscode Cookbooks site\. By default, knife will use the username and API key you\'ve configured in your configuration file; otherwise you must explicitly set these values on the command line or use an alternate configuration file\. . -.P -\fBcookbook site unshare COOKBOOK\fR +.SH "UNSHARE" +\fBknife cookbook site unshare COOKBOOK\fR . .P Stops sharing the specified cookbook on the Opscode cookbooks site\. . -.P -\fBcookbook site show COOKBOOK [VERSION]\fR \fI(options)\fR +.SH "SHOW" +\fBknife cookbook site show COOKBOOK [VERSION]\fR \fI(options)\fR . .P Shows information from the site about a particular cookbook\. . +.SH "DESCRIPTION" +The cookbook site, \fIhttp://community\.opscode\.com/\fR, is a cookbook distribution service operated by Opscode\. This service provides users with a central location to publish cookbooks for sharing with other community members\. +. .P -\fBcookbook site vendor COOKBOOK [VERSION]\fR \fI(options)\fR +\fBknife cookbook site\fR commands provide an interface to the cookbook site\'s HTTP API\. For commands that read data from the API, no account is required\. In order to upload cookbooks using the \fBknife cookbook site share\fR command, you must create an account on the cookbook site and configure your credentials via command line option or in your knife configuration file\. . -.TP -\fB\-d\fR, \fB\-\-dependencies\fR -Grab dependencies automatically +.SH "EXAMPLES" +Uploading cookbooks to the Opscode cookbooks site: . -.P -Uses \fBgit\fR version control in conjunction with the cookbook site to download upstream cookbooks\. A new vendor branch is created in git, the cookbook downloaded from the site and untarred, then the master branch is merged\. This allows the user to track upstream changes to cookbooks while merging in customizations\. If \fI\-d\fR is specified, all the cookbooks it depends on (via metadata \fIdependencies\fR) are downloaded and untarred as well, each using their own vendor branch\. +.IP "" 4 +. +.nf + +knife cookbook site share example Other \-k ~/\.chef/USERNAME\.pem \-u USERNAME +. +.fi +. +.IP "" 0 . .SH "SEE ALSO" -\fBknife\-environment\fR(1) +\fBknife\-cookbook(1)\fR \fIhttp://community\.opscode\.com/cookbooks\fR . .SH "AUTHOR" Chef was written by Adam Jacob \fIadam@opscode\.com\fR with many contributions from the community\. diff --git a/chef/distro/common/man/man1/knife-cookbook.1 b/chef/distro/common/man/man1/knife-cookbook.1 index 08c1dd35da..2f4fe22d8f 100644 --- a/chef/distro/common/man/man1/knife-cookbook.1 +++ b/chef/distro/common/man/man1/knife-cookbook.1 @@ -4,239 +4,317 @@ .TH "KNIFE\-COOKBOOK" "1" "April 2011" "Chef 0.10.0.beta.8" "Chef Manual" . .SH "NAME" -\fBknife\-cookbook\fR \- Upload and manage Chef cookbooks +\fBknife\-cookbook\fR \- upload and manage chef cookbooks . .SH "SYNOPSIS" \fBknife\fR \fBcookbook\fR \fIsub\-command\fR \fI(options)\fR . -.SH "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\. +.SH "SUB\-COMMANDS" +\fBknife cookbook\fR supports the following sub commands: . -.P -\fBcookbook bulk delete REGEX\fR \fI(options)\fR +.SH "LIST" +\fBknife cookbook list\fR \fI(options)\fR . .TP -\fB\-p\fR, \fB\-\-purge\fR -Purge files from backing store\. This will disable any cookbook that contains any of the same files as the cookbook being purged\. +\fB\-a\fR, \fB\-\-all\fR +show all versions of a cookbook instead of just the most recent . -.P -Delete cookbooks on the Chef Server based on a regular expression\. The regular expression (\fIREGEX\fR) should be in quotes, not in //\'s\. +.TP +\fB\-w\fR, \fB\-\-with\-uri\fR +show corresponding uris . .P -\fBcookbook create COOKBOOK\fR \fI(options)\fR -. -.TP -\fB\-o\fR, \fB\-\-cookbook\-path PATH\fR -The directory where the cookbook will be created +Lists the cookbooks available on the Chef server\. . -.TP -\fB\-r\fR, \fB\-\-readme\-format FORMAT\fR -Format of the README file +.SH "SHOW" +\fBknife cookbook show cookbook [version] [part] [filename]\fR \fI(options)\fR . .TP -\fB\-C\fR, \fB\-\-copyright COPYRIGHT\fR -Name of Copyright holder +\fB\-f\fR, \fB\-\-fqdn fqdn\fR +the fqdn of the host to see the file for . .TP -\fB\-I\fR, \fB\-\-license LICENSE\fR -License for cookbook, apachev2 or none +\fB\-p\fR, \fB\-\-platform platform\fR +the platform to see the file for . .TP -\fB\-E\fR, \fB\-\-email EMAIL\fR -Email address of cookbook maintainer +\fB\-v\fR, \fB\-\-platform\-version version\fR +the platform version to see the file for . .P -This is a helper command that creates a new cookbook directory in the \fBcookbook_path\fR\. The following directories and files are created for the named cookbook\. -. -.IP "\(bu" 4 -COOKBOOK/attributes +show a particular part of a \fIcookbook\fR for the specified \fIversion\fR\. \fIpart\fR can be one of: . .IP "\(bu" 4 -COOKBOOK/definitions -. -.IP "\(bu" 4 -COOKBOOK/files/default +\fIattributes\fR . .IP "\(bu" 4 -COOKBOOK/libraries +\fIdefinitions\fR . .IP "\(bu" 4 -COOKBOOK/metadata\.rb +\fIfiles\fR . .IP "\(bu" 4 -COOKBOOK/providers +\fIlibraries\fR . .IP "\(bu" 4 -COOKBOOK/README\.rdoc +\fIproviders\fR . .IP "\(bu" 4 -COOKBOOK/recipes/default\.rb +\fIrecipes\fR . .IP "\(bu" 4 -COOKBOOK/resources +\fIresources\fR . .IP "\(bu" 4 -COOKBOOK/templates/default +\fItemplates\fR . .IP "" 0 . -.P -Supported README formats are \'rdoc\' (default), \'md\', \'mkd\', \'txt\'\. The README file will be written with the specified extension and a set of helpful starting headers\. -. -.P -Specify \fB\-C\fR or \fB\-\-copyright\fR with the name of the copyright holder as your name or your company/organization name in a quoted string\. If this value is not specified an all\-caps string \fBYOUR_COMPANY_NAME\fR is used which can be easily changed with find/replace\. -. -.P -Specify \fB\-I\fR or \fB\-\-license\fR with the license that the cookbook is distributed under for sharing with other people or posting to the Opscode Cookbooks site\. Be aware of the licenses of files you put inside the cookbook and follow any restrictions they describe\. When using \fBnone\fR (default) or \fBapachev2\fR, comment header text and metadata file are pre\-filled\. The \fBnone\fR license will be treated as non\-redistributable\. -. -.P -Specify \fB\-E\fR or \fB\-\-email\fR with the email address of the cookbook\'s maintainer\. If this value is not specified, an all\-caps string \fBYOUR_EMAIL\fR is used which can easily be changed with find/replace\. -. -.P -The cookbook copyright, license and email settings can be filled in the \fBknife\.rb\fR, for example with default values: +.SH "UPLOAD" +\fBknife cookbook upload [cookbooks\.\.\.]\fR \fI(options)\fR . -.IP "" 4 -. -.nf - -cookbook_copyright "YOUR_COMPANY_NAME" -cookbook_license "none" -cookbook_email "YOUR_EMAIL" -. -.fi +.TP +\fB\-a\fR, \fB\-\-all\fR +upload all cookbooks, rather than just a single cookbook . -.IP "" 0 +.TP +\fB\-o\fR, \fB\-\-cookbook\-path path:path\fR +a colon\-separated path to look for cookbooks in . -.P -\fBcookbook delete COOKBOOK [VERSION]\fR \fI(options)\fR +.TP +\fB\-E\fR, \fB\-\-environment ENVIRONMENT\fR +An \fIENVIRONMENT\fR to apply the uploaded cookbooks to\. Specifying this option will cause knife to edit the \fIENVIRONMENT\fR to place a strict version constraint on the cookbook version(s) uploaded\. . .TP -\fB\-a\fR, \fB\-\-all\fR -Delete all versions +\fB\-\-freeze\fR +Sets the frozen flag on the uploaded cookbook(s) Any future attempt to modify the cookbook without changing the version number will return an error unless \-\-force is specified\. . .TP -\fB\-p\fR, \fB\-\-purge\fR -Purge files from backing store\. This will disable any cookbook that contains any of the same files as the cookbook being purged\. +\fB\-\-force\fR +Overrides the frozen flag on a cookbook, allowing you to overwrite a cookbook version that has previously been uploaded with the \-\-freeze option\. . .P -Delete the specified \fIVERSION\fR of the named \fICOOKBOOK\fR\. If no version is specified, and only one version exists on the server, that version will be deleted\. If multiple versions are available on the server, you will be prompted for a version to delete\. +Uploads one or more cookbooks from your local cookbook repository(ies) to the Chef Server\. Only files that don\'t yet exist on the server will be uploaded\. . -.P -\fBcookbook download COOKBOOK [VERSION]\fR \fI(options)\fR +.SH "DOWNLOAD" +\fBknife cookbook download cookbook [version]\fR \fI(options)\fR . .TP -\fB\-d\fR, \fB\-\-dir DOWNLOAD_DIRECTORY\fR -The directory to download the cookbook into +\fB\-d\fR, \fB\-\-dir download_directory\fR +the directory to download the cookbook into . .TP \fB\-f\fR, \fB\-\-force\fR -Overwrite an existing directory with the download +overwrite an existing directory with the download . .TP -\fB\-N\fR, \fB\-\-latest\fR -Download the latest version of the cookbook +\fB\-n\fR, \fB\-\-latest\fR +download the latest version of the cookbook . .P -Download a cookbook from the Chef Server\. If no version is specified and only one version exists on the server, that version will be downloaded\. If no version is specified and multiple versions are available on the server, you will be prompted for a version to download\. +download a cookbook from the chef server\. if no version is specified and only one version exists on the server, that version will be downloaded\. if no version is specified and multiple versions are available on the server, you will be prompted for a version to download\. . -.P -\fBcookbook list\fR \fI(options)\fR +.SH "DELETE" +\fBknife cookbook delete cookbook [version]\fR \fI(options)\fR . .TP -\fB\-w\fR, \fB\-\-with\-uri\fR -Show corresponding URIs +\fB\-a\fR, \fB\-\-all\fR +delete all versions . -.P -List all the cookbooks\. +.TP +\fB\-p\fR, \fB\-\-purge\fR +purge files from backing store\. this will disable any cookbook that contains any of the same files as the cookbook being purged\. . .P -\fBcookbook metadata COOKBOOK\fR \fI(options)\fR +delete the specified \fIversion\fR of the named \fIcookbook\fR\. if no version is specified, and only one version exists on the server, that version will be deleted\. if multiple versions are available on the server, you will be prompted for a version to delete\. . -.TP -\fB\-a\fR, \fB\-\-all\fR -Generate metadata for all cookbooks, rather than just a single cookbook +.SH "BULK DELETE" +\fBknife cookbook bulk delete regex\fR \fI(options)\fR . .TP -\fB\-o\fR, \fB\-\-cookbook\-path PATH:PATH\fR -A colon\-separated path to look for cookbooks in +\fB\-p\fR, \fB\-\-purge\fR +purge files from backing store\. this will disable any cookbook that contains any of the same files as the cookbook being purged\. . .P -Generate cookbook metadata for the named \fICOOKBOOK\fR\. The \fIPATH\fR used here specifies where the cookbooks directory is located and corresponds to the \fBcookbook_path\fR configuration option\. +delete cookbooks on the chef server based on a regular expression\. the regular expression (\fIregex\fR) should be in quotes, not in //\'s\. . -.P -\fBcookbook metadata from FILE\fR \fI(options)\fR +.SH "COOKBOOK CREATE" +\fBknife cookbook create cookbook\fR \fI(options)\fR . -.P -Load the cookbook metadata from a specified file\. +.TP +\fB\-o\fR, \fB\-\-cookbook\-path path\fR +the directory where the cookbook will be created . -.P -\fBcookbook show COOKBOOK [VERSION] [PART] [FILENAME]\fR \fI(options)\fR +.TP +\fB\-r\fR, \fB\-\-readme\-format format\fR +format of the readme file . .TP -\fB\-f\fR, \fB\-\-fqdn FQDN\fR -The FQDN of the host to see the file for +\fB\-c\fR, \fB\-\-copyright copyright\fR +name of copyright holder . .TP -\fB\-p\fR, \fB\-\-platform PLATFORM\fR -The platform to see the file for +\fB\-i\fR, \fB\-\-license license\fR +license for cookbook, apachev2 or none . .TP -\fB\-V\fR, \fB\-\-platform\-version VERSION\fR -The platform version to see the file for +\fB\-e\fR, \fB\-\-email email\fR +email address of cookbook maintainer . .P -Show a particular part of a \fICOOKBOOK\fR for the specified \fIVERSION\fR\. \fIPART\fR can be one of: +this is a helper command that creates a new cookbook directory in the \fBcookbook_path\fR\. the following directories and files are created for the named cookbook\. . .IP "\(bu" 4 -\fIattributes\fR +cookbook/attributes . .IP "\(bu" 4 -\fIdefinitions\fR +cookbook/definitions . .IP "\(bu" 4 -\fIfiles\fR +cookbook/files/default . .IP "\(bu" 4 -\fIlibraries\fR +cookbook/libraries . .IP "\(bu" 4 -\fIproviders\fR +cookbook/metadata\.rb . .IP "\(bu" 4 -\fIrecipes\fR +cookbook/providers . .IP "\(bu" 4 -\fIresources\fR +cookbook/readme\.rdoc . .IP "\(bu" 4 -\fItemplates\fR +cookbook/recipes/default\.rb +. +.IP "\(bu" 4 +cookbook/resources +. +.IP "\(bu" 4 +cookbook/templates/default . .IP "" 0 . .P -\fBcookbook test [COOKBOOKS\.\.\.]\fR \fI(options)\fR +supported readme formats are \'rdoc\' (default), \'md\', \'mkd\', \'txt\'\. the readme file will be written with the specified extension and a set of helpful starting headers\. +. +.P +specify \fB\-c\fR or \fB\-\-copyright\fR with the name of the copyright holder as your name or your company/organization name in a quoted string\. if this value is not specified an all\-caps string \fByour_company_name\fR is used which can be easily changed with find/replace\. +. +.P +specify \fB\-i\fR or \fB\-\-license\fR with the license that the cookbook is distributed under for sharing with other people or posting to the opscode cookbooks site\. be aware of the licenses of files you put inside the cookbook and follow any restrictions they describe\. when using \fBnone\fR (default) or \fBapachev2\fR, comment header text and metadata file are pre\-filled\. the \fBnone\fR license will be treated as non\-redistributable\. +. +.P +specify \fB\-e\fR or \fB\-\-email\fR with the email address of the cookbook\'s maintainer\. if this value is not specified, an all\-caps string \fByour_email\fR is used which can easily be changed with find/replace\. +. +.P +the cookbook copyright, license and email settings can be filled in the \fBknife\.rb\fR, for example with default values: +. +.IP "" 4 +. +.nf + +cookbook_copyright "your_company_name" +cookbook_license "none" +cookbook_email "your_email" +. +.fi +. +.IP "" 0 +. +.SH "METADATA" +\fBknife cookbook metadata cookbook\fR \fI(options)\fR . .TP \fB\-a\fR, \fB\-\-all\fR -Test all cookbooks, rather than just a single cookbook +generate metadata for all cookbooks, rather than just a single cookbook . .TP -\fB\-o\fR, \fB\-\-cookbook\-path PATH:PATH\fR -A colon\-separated path to look for cookbooks in +\fB\-o\fR, \fB\-\-cookbook\-path path:path\fR +a colon\-separated path to look for cookbooks in . .P -Test the specified cookbooks for syntax errors\. This uses the built\-in Ruby syntax checking option for files in the cookbook ending in \fB\.rb\fR, and the ERB syntax check for files ending in \fB\.erb\fR (templates)\. +generate cookbook metadata for the named \fIcookbook\fR\. the \fIpath\fR used here specifies where the cookbooks directory is located and corresponds to the \fBcookbook_path\fR configuration option\. +. +.SH "METADATA FROM FILE" +\fBknife cookbook metadata from file\fR \fI(options)\fR . .P -\fBcookbook upload [COOKBOOKS\.\.\.]\fR \fI(options)\fR +load the cookbook metadata from a specified file\. +. +.SH "TEST" +\fBknife cookbook test [cookbooks\.\.\.]\fR \fI(options)\fR . .TP \fB\-a\fR, \fB\-\-all\fR -Upload all cookbooks, rather than just a single cookbook +test all cookbooks, rather than just a single cookbook . .TP -\fB\-o\fR, \fB\-\-cookbook\-path PATH:PATH\fR -A colon\-separated path to look for cookbooks in +\fB\-o\fR, \fB\-\-cookbook\-path path:path\fR +a colon\-separated path to look for cookbooks in . .P -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 \fBcookbook_path\fR (or \fB\-o PATH\fR) is processed to search for the named cookbook, and each occurance is copied in the order specified\. A syntax check is performed a la \fBcookbook test\fR, above\. The metadata is generated, a la \fBcookbook metadata\fR\. A gzip(1)\'ed, tar(1) file is created, and is uploaded to the server\. +test the specified cookbooks for syntax errors\. this uses the built\-in ruby syntax checking option for files in the cookbook ending in \fB\.rb\fR, and the erb syntax check for files ending in \fB\.erb\fR (templates)\. +. +.SH "RECIPE LIST" +\fBknife recipe list [PATTERN]\fR +. +.P +List available recipes from the server\. Specify \fIPATTERN\fR as a regular expression to limit the results\. +. +.SH "DESCRIPTION" +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\. +. +.P +On disk, cookbooks are directories with a defined structure\. The following directories may appear within a cookbook: +. +.TP +COOKBOOK/attributes/ +Ruby files that define default parameters to be used in recipes +. +.TP +COOKBOOK/definitions/ +Ruby files that contain \fIresource definitions\fR +. +.TP +COOKBOOK/files/SPECIFICITY +Files of arbitrary type\. These files may be downloaded by chef\-client(8) when configuring a host\. +. +.TP +COOKBOOK/libraries/ +Ruby files that contain library code needed for recipes +. +.TP +COOKBOOK/providers/ +Ruby files that contain Lightweight Provider definitions +. +.TP +COOKBOOK/recipes/ +Ruby files that use Chef\'s recipe DSL to describe the desired configuration of a system +. +.TP +COOKBOOK/resources/ +Ruby files that contain Lightweight Resource definitions +. +.TP +COOKBOOK/templates/SPECIFICITY +ERuby (ERb) template files\. These are referenced by \fIrecipes\fR and evaluated to dynamically generate configuration files\. +. +.P +\fBSPECIFICITY\fR is a feature of \fIfiles\fR and \fItemplates\fR that allow you to specify alternate files to be used on a specific OS platform or host\. The default specificity setting is \fIdefault\fR, that is files in \fBCOOKBOOK/files/default\fR will be used when a more specific copy is not available\. Further documentation for this feature is available on the Chef wiki: \fIhttp://wiki\.opscode\.com/display/chef/File+Distribution#FileDistribution\-FileSpecificity\fR +. +.P +Cookbooks also contain a metadata file that defines various properties of the cookbook\. The most important of these are the \fIversion\fR and the \fIdependencies\fR\. The \fIversion\fR is used in combination with environments to select which copy of a given cookbook is distributed to a node\. The \fIdependencies\fR are used by the server to determine which additional cookbooks must be distributed to a given host when it requires a cookbook\. +. +.SH "SEE ALSO" +\fBknife\-environment(1)\fR \fBknife\-cookbook\-site(1)\fR \fIhttp://wiki\.opscode\.com/display/chef/Cookbooks\fR \fIhttp://wiki\.opscode\.com/display/chef/Metadata\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 diff --git a/chef/distro/common/man/man1/knife-environment.1 b/chef/distro/common/man/man1/knife-environment.1 index 386b520456..e283220cf6 100644 --- a/chef/distro/common/man/man1/knife-environment.1 +++ b/chef/distro/common/man/man1/knife-environment.1 @@ -10,6 +10,7 @@ \fBknife\fR \fBenvironment\fR \fIsub\-command\fR \fI(options)\fR . .SH "SUBCOMMANDS" +Environment subcommands follow a basic create, read, update, delete (CRUD) pattern\. The following subcommands are available: . .SH "CREATE" \fBknife environment create\fR \fIenvironment\fR \fI(options)\fR diff --git a/chef/distro/common/man/man1/knife-node.1 b/chef/distro/common/man/man1/knife-node.1 index 51c7413233..d2a248b2ba 100644 --- a/chef/distro/common/man/man1/knife-node.1 +++ b/chef/distro/common/man/man1/knife-node.1 @@ -19,6 +19,7 @@ When a host communicates with a Chef Server, it authenticates using its \fBnode_ By default \fBchef\-client\fR(8) will create a node using the FQDN of the host for the node name, though this may be overridden by configuration settings\. . .SH "NODE SUB\-COMMANDS" +The following \fBnode\fR subcommands are available: . .SH "BULK DELETE" \fBknife node bulk delete\fR \fIregex\fR \fI(options)\fR diff --git a/chef/distro/common/man/man1/knife-recipe.1 b/chef/distro/common/man/man1/knife-recipe.1 deleted file mode 100644 index a89c570072..0000000000 --- a/chef/distro/common/man/man1/knife-recipe.1 +++ /dev/null @@ -1,13 +0,0 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-RECIPE" "1" "April 2011" "Chef 0.10.0.beta.8" "Chef Manual" -. -.SH "NAME" -\fBknife\-recipe\fR \- List the recipes available on a Chef Server -. -.SH "SYNOPSIS" -\fBknife\fR \fBrecipe list [PATTERN]\fR -. -.P -List the recipes available on the server\. The results shown can be limited with the optional PATTERN, which is a regular expression\. PATTERN should be given in quotes, without slashes\. diff --git a/chef/distro/common/man/man1/knife-role.1 b/chef/distro/common/man/man1/knife-role.1 index c3b9d1716c..7a7fa37bce 100644 --- a/chef/distro/common/man/man1/knife-role.1 +++ b/chef/distro/common/man/man1/knife-role.1 @@ -10,13 +10,30 @@ \fBknife\fR \fBrole\fR \fIsub\-command\fR \fI(options)\fR . .SH "ROLE SUB\-COMMANDS" -\fBrole bulk delete REGEX\fR \fI(options)\fR +The following \fBrole\fR subcommands are available: +. +.SH "LIST" +\fBknife role list\fR \fI(options)\fR +. +.TP +\fB\-w\fR, \fB\-\-with\-uri\fR +Show corresponding URIs . .P -Delete roles on the Chef Server based on a regular expression\. The regular expression (\fIREGEX\fR) should be in quotes, not in //\'s\. +List roles\. +. +.SH "SHOW" +\fBknife role show ROLE\fR \fI(options)\fR +. +.TP +\fB\-a\fR, \fB\-\-attribute ATTR\fR +Show only one attribute . .P -\fBrole create ROLE\fR \fI(options)\fR +Show a specific role\. +. +.SH "CREATE" +\fBknife role create ROLE\fR \fI(options)\fR . .TP \fB\-d\fR, \fB\-\-description\fR @@ -25,40 +42,47 @@ The role description .P Create a new role\. . -.P -\fBrole delete ROLE\fR \fI(options)\fR +.SH "EDIT" +\fBknife role edit ROLE\fR \fI(options)\fR . .P -Delete a role\. +Edit a role\. . -.P -\fBrole edit ROLE\fR \fI(options)\fR +.SH "FROM FILE" +\fBknife role from file FILE\fR \fI(options)\fR . .P -Edit a role\. +Create or update a role from a role Ruby DSL (\fB\.rb\fR) or JSON file\. . -.P -\fBrole from file FILE\fR \fI(options)\fR +.SH "DELETE" +\fBknife role delete ROLE\fR \fI(options)\fR . .P -Create or update a role from a role Ruby DSL (\fB\.rb\fR) or JSON file\. +Delete a role\. +. +.SH "BULK DELETE" +\fBknife role bulk delete REGEX\fR \fI(options)\fR . .P -\fBrole list\fR \fI(options)\fR +Delete roles on the Chef Server based on a regular expression\. The regular expression (\fIREGEX\fR) should be in quotes, not in //\'s\. . -.TP -\fB\-w\fR, \fB\-\-with\-uri\fR -Show corresponding URIs +.SH "DESCRIPTION" +Roles provide a mechanism to group repeated configuration settings\. Roles are data structures that contain \fBdefault_attributes\fR, and \fBoverride_attributes\fR, which are nested hashes of configuration settings, and a \fBrun_list\fR, which is an ordered list of recipes and roles that should be applied to a host by chef\-client\. . .P -List roles\. +\fBdefault_attributes\fR will be overridden if they conflict with a value on a node that includes the role\. Conversely, \fBoverride_attributes\fR will override any values set on nodes that apply them\. . .P -\fBrole show ROLE\fR \fI(options)\fR +When \fBchef\-client\fR(8) configures a host, it will "expand" the \fBrun_list\fR included in that host\'s node data\. The expansion process will recursively replace any roles in the run_list with that role\'s run_list\. . -.TP -\fB\-a\fR, \fB\-\-attribute ATTR\fR -Show only one attribute +.SH "SEE ALSO" +\fBknife\-node(1)\fR \fBknife\-environment(1)\fR \fIhttp://wiki\.opscode\.com/display/chef/Roles\fR \fIhttp://wiki\.opscode\.com/display/chef/Attributes\fR . -.P -Show a specific role\. +.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 diff --git a/chef/distro/common/man/man1/knife-search.1 b/chef/distro/common/man/man1/knife-search.1 index 3b9c518b2c..7958984296 100644 --- a/chef/distro/common/man/man1/knife-search.1 +++ b/chef/distro/common/man/man1/knife-search.1 @@ -33,5 +33,29 @@ The order to sort the results in \fB\-b\fR, \fB\-\-start ROW\fR The row to start returning results at . -.P -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: \fInode\fR, \fIrole\fR, \fIclient\fR, \fIdata bag\fR\. +.TP +\fB\-m\fR, \fB\-\-medium\fR +Display medium sized output when searching nodes using the default summary format +. +.TP +\fB\-l\fR, \fB\-\-long\fR +Display long output when searching nodes using the default summary format +. +.SH "DESCRIPTION" +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: * \fInode\fR * \fIrole\fR * \fIenvironment\fR * \fIdata bag\fR +. +.SH "SYNTAX" +. +.SH "EXAMPLES" +. +.SH "SEE ALSO" +\fBknife\-ssh\fR(1) \fIhttp://wiki\.opscode\.com/display/chef/Attributes\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 diff --git a/chef/distro/common/man/man1/knife-ssh.1 b/chef/distro/common/man/man1/knife-ssh.1 index 2361280720..9b9ce7787a 100644 --- a/chef/distro/common/man/man1/knife-ssh.1 +++ b/chef/distro/common/man/man1/knife-ssh.1 @@ -29,5 +29,46 @@ The ssh password \fB\-x\fR, \fB\-\-ssh\-user USERNAME\fR The ssh username . -.P +.SH "DESCRIPTION" The \fIssh\fR sub\-command opens an ssh session to each of the nodes in the search results of the \fIQUERY\fR\. 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)\. +. +.SH "TERMINAL MULTIPLEXING AND TERMINAL TAB SUPPORT" +\fBknife ssh\fR integrates with several terminal multiplexer programs to provide a more convenient means of managing multiple ssh sessions\. When the \fICOMMAND\fR option matches one of these, \fBknife ssh\fR will create multiple interactive ssh sessions running locally in the terminal multiplexer instead of invoking the command on the remote host\. +. +.P +The available multiplexers are: * \fBinteractive\fR: +. +.IP "" 4 +. +.nf + +A built\-in multiplexer\. `interactive` supports running commands on a +subset of the connected hosts in parallel +. +.fi +. +.IP "" 0 +. +.TP +\fBscreen\fR(1) +Runs ssh interactively inside \fBscreen\fR\. ~/\.screenrc will be sourced if it exists\. +. +.TP +\fBtmux\fR(1) +Runs ssh interactively inside tmux\. +. +.TP +\fBmacterm\fR (Mac OS X only) +Opens a Terminal\.app window and creates a tab for each ssh session\. You must install the rb\-appscript gem before you can use this option\. +. +.SH "SEE ALSO" +\fBknife\-search\fR(1) +. +.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 diff --git a/chef/distro/common/man/man1/knife-status.1 b/chef/distro/common/man/man1/knife-status.1 index 45280bec1b..e59dc0afd1 100644 --- a/chef/distro/common/man/man1/knife-status.1 +++ b/chef/distro/common/man/man1/knife-status.1 @@ -13,5 +13,17 @@ \fB\-r\fR, \fB\-\-run\-list RUN_LIST\fR Show the run list . -.P +.SH "DESCRIPTION" The \fIstatus\fR sub\-command searches the Chef Server for all nodes and displays information about the last time the node checked into the server and executed a \fBnode\.save\fR\. The fields displayed are the relative checkin time, the node name, it\'s operating system platform and version, the fully\-qualified domain name and the default IP address\. If the \fB\-r\fR option is given, the node\'s run list will also be displayed\. Note that depending on the configuration of the nodes, the FQDN and IP displayed may not be publicly reachable\. +. +.SH "SEE ALSO" +\fBknife\-search\fR(1) +. +.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 diff --git a/chef/distro/common/man/man1/knife-tag.1 b/chef/distro/common/man/man1/knife-tag.1 index 85de474f4e..eb853c94df 100644 --- a/chef/distro/common/man/man1/knife-tag.1 +++ b/chef/distro/common/man/man1/knife-tag.1 @@ -10,4 +10,34 @@ \fBknife\fR \fBtag\fR \fIsubcommand\fR \fI(options)\fR . .SH "TAG SUBCOMMANDS" - +The following \fBtag\fR subcommands are available: +. +.SH "CREATE" +\fBknife tag create\fR \fInode\fR \fItag\fR [\fI\.\.\.\fR] +. +.P +Adds one or more tags to \fInode\fR +. +.SH "DELETE" +\fBknife tag delete\fR \fInode\fR \fItag\fR [\fI\.\.\.\fR] +. +.P +Removes one or more tags from \fInode\fR +. +.SH "LIST" +\fBknife tag list\fR \fInode\fR +. +.P +Lists the tags applied to \fInode\fR +. +.SH "SEE ALSO" +\fBknife\-node(1)\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 Daniel DeLeo \fIdan@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 diff --git a/chef/distro/common/man/man1/knife.1 b/chef/distro/common/man/man1/knife.1 index d019e20320..64c6bc9d5e 100644 --- a/chef/distro/common/man/man1/knife.1 +++ b/chef/distro/common/man/man1/knife.1 @@ -4,21 +4,68 @@ .TH "KNIFE" "1" "April 2011" "Chef 0.10.0.beta.8" "Chef Manual" . .SH "NAME" -\fBknife\fR \- Chef Server REST API utility +\fBknife\fR \- Chef Server API client utility . .SH "SYNOPSIS" -\fBknife\fR \fIsub\-command\fR \fI(options)\fR +\fBknife\fR \fIsub\-command\fR [\fIargument\fR\.\.\.] \fI(options)\fR . .SH "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\. +Knife is a command\-line utility used to manage data on a Chef server through the HTTP(S) API\. Knife is organized into groups of subcommands centered around the various object types in Chef\. Each category of subcommand is documented in its own manual page\. Available topics are: . -.P -Unless otherwise specified, output is in JSON format, and input files are also JSON format\. +.IP "\(bu" 4 +bootstrap +. +.IP "\(bu" 4 +client +. +.IP "\(bu" 4 +configure +. +.IP "\(bu" 4 +cookbook\-site +. +.IP "\(bu" 4 +cookbook +. +.IP "\(bu" 4 +data\-bag +. +.IP "\(bu" 4 +environment +. +.IP "\(bu" 4 +exec +. +.IP "\(bu" 4 +index +. +.IP "\(bu" 4 +node +. +.IP "\(bu" 4 +recipe +. +.IP "\(bu" 4 +role +. +.IP "\(bu" 4 +search +. +.IP "\(bu" 4 +ssh +. +.IP "\(bu" 4 +status +. +.IP "\(bu" 4 +tag +. +.IP "" 0 . .P -The Chef class \fBChef::Config\fR that configures the behavior of how knife runs has options that correspond to command\-line options\. These are noted as \fBChef::Config\fR values\. +If the knife manuals are in your \fBMANPATH\fR, you can access help for the above topics using \fBman knife\-TOPIC\fR; otherwise, you can view the documentation using \fBknife help TOPIC\fR\. . -.SH "GENERAL OPTIONS" +.SH "OPTIONS" . .TP \fB\-s\fR, \fB\-\-server\-url\fR URL @@ -70,13 +117,10 @@ Say yes to all prompts for confirmation . .TP \fB\-h\fR, \fB\-\-help\fR -Show this message -. -.P -Usage information for sub\-commands can be displayed with \fBknife SUB\-COMMAND \-\-help\fR\. +Show the available options for a command\. . .SH "SUB\-COMMANDS" -Knife sub\-commands are structured as \fINOUN verb NOUN (options)\fR\. The sub\-commands are meant to be intuitively named\. Because the Chef Server API is RESTful, sub\-commands generally utilize CRUD operations\. +Sub\-commands that operate on the basic Chef data types are structured as \fINOUN verb NOUN (options)\fR\. For all data types, the following commands are available: . .IP "\(bu" 4 create (create) @@ -93,13 +137,7 @@ delete (destroy) .IP "" 0 . .P -Objects stored on the server support these, as described below\. -. -.SH "GENERAL SUB\-COMMANDS" -\fBrecipe list [PATTERN]\fR -. -.P -List available recipes from the server\. Specify \fIPATTERN\fR as a regular expression to limit the results\. +Knife also includes commands that take actions other than displaying or modifying data on the Chef Server, such as \fBknife\-ssh(1)\fR\. . .SH "CONFIGURATION" The knife configuration file is a Ruby DSL to set configuration parameters for Knife\'s \fBGENERAL OPTIONS\fR\. The default location for the config file is \fB~/\.chef/knife\.rb\fR\. If managing multiple Chef repositories, per\-repository config files can be created\. The file must be \fB\.chef/knife\.rb\fR in the current directory of the repository\. @@ -107,103 +145,31 @@ The knife configuration file is a Ruby DSL to set configuration parameters for K .P If the config file exists, knife uses these settings for \fBGENERAL OPTIONS\fR defaults\. . -.P -\fBlog_level\fR -. -.P -A Ruby symbol specifying the log level\. Corresponds to \fB\-l\fR or \fB\-\-log_level\fR option\. Default is \fI:info\fR\. Valid values are: -. .IP "\(bu" 4 -:info +\fBnode_name\fR: User or client identity (i\.e\., \fIname\fR) to use for authenticating requests to the Chef Server\. . .IP "\(bu" 4 -:debug +\fBclient_key\fR: Private key file to authenticate to the Chef server\. Corresponds to the \fB\-k\fR or \fB\-\-key\fR option\. . .IP "\(bu" 4 -:warn +\fBchef_server_url\fR: URL of the Chef server\. Corresponds to the \fB\-s\fR or \fB\-\-server\-url\fR option\. This is requested from the user when running this sub\-command\. . .IP "\(bu" 4 -:fatal -. -.IP "" 0 -. -.P -\fBlog_location\fR -. -.P -Corresponds to the \fB\-L\fR or \fB\-\-log\-file\fR option\. Defaults is \fBSTDOUT\fR\. Valid values are \fBSTDOUT\fR or a filename\. -. -.P -\fBnode_name\fR -. -.P -User to authenticate to the Chef server\. Corresponds to the \fB\-u\fR or \fB\-\-user\fR option\. This is requested from the user when running this sub\-command\. -. -.P -\fBclient_key\fR -. -.P -Private key file to authenticate to the Chef server\. Corresponds to the \fB\-k\fR or \fB\-\-key\fR option\. This is requested from the user when running this sub\-command\. -. -.P -\fBchef_server_url\fR -. -.P -URL of the Chef server\. Corresponds to the \fB\-s\fR or \fB\-\-server\-url\fR option\. This is requested from the user when running this sub\-command\. -. -.P -\fBcache_type\fR -. -.P -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\. -. -.P -\fBcache_options\fR -. -.P -Specifies various options to use for caching\. Default reads the Chef client configuration (/etc/chef/checksums)\. -. -.P -\fBvalidation_client_name\fR +\fBcache_type\fR: 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\. . -.P -Specifies the name of the client used to validate new clients\. This is requested from the user when running the configuration sub\-command\. -. -.P -\fBvalidation_key\fR -. -.P -Specifies the private key file to use for generating ec2 instance data for validating new clients\. This is implied from the \fBvalidation_client_name\fR\. -. -.P -\fBcookbook_copyright\fR \fBcookbook_email\fR \fBcookbook_license\fR -. -.P -Used by \fBknife cookbook create\fR sub\-command to specify the copyright holder, maintainer email and license (respectively) for new cookbooks\. The copyright holder is listed as the maintainer in the cookbook\'s metadata and as the Copyright in the comments of the default recipe\. The maintainer email is used in the cookbook metadata\. The license determines what preamble to put in the comment of the default recipe, and is listed as the license in the cookbook metadata\. Currently supported licenses are "apachev2" and "none"\. Any other values will result in an empty license in the metadata (needs to be filled in by the author), and no comment preamble in the default recipe\. -. -.P -\fBknife[:aws_access_key_id]\fR \fBknife[:aws_secret_access_key]\fR -. -.P -Specifies the Amazon AWS EC2 credentials to use when running the ec2 sub\-commands\. -. -.P -\fBknife[:rackspace_api_username]\fR \fBknife[:rackspace_api_key]\fR -. -.P -Specifies the Rackspace Cloud credentials to use when running the rackspace sub\-commands\. +.IP "\(bu" 4 +\fBcache_options\fR: Specifies various options to use for caching\. These options are dependent on the \fBcache_type\fR\. . -.P -\fBknife[:terremark_username]\fR \fBknife[:terremark_password]\fR \fBknife[:terremark_service]\fR +.IP "\(bu" 4 +\fBvalidation_client_name\fR: Specifies the name of the client used to validate new clients\. . -.P -Specifies the Terremark vCloud credentials to use when running the terremark sub\-commands\. +.IP "\(bu" 4 +\fBvalidation_key\fR: Specifies the private key file to use when bootstrapping new hosts\. See knife\-client(1) for more information about the validation client\. . -.P -\fBknife[:slicehost_password]\fR +.IP "\(bu" 4 +\fBcookbook_copyright\fR, \fBcookbook_email\fR, \fBcookbook_license\fR Used by \fBknife cookbook create\fR sub\-command to specify the copyright holder, maintainer email and license (respectively) for new cookbooks\. The copyright holder is listed as the maintainer in the cookbook\'s metadata and as the Copyright in the comments of the default recipe\. The maintainer email is used in the cookbook metadata\. The license determines what preamble to put in the comment of the default recipe, and is listed as the license in the cookbook metadata\. Currently supported licenses are "apachev2" and "none"\. Any other values will result in an empty license in the metadata (needs to be filled in by the author), and no comment preamble in the default recipe\. . -.P -Specifies the Slicehost password to use when running the slicdehost sub\-commands\. +.IP "" 0 . .SH "FILES" \fI~/\.chef/knife\.rb\fR @@ -244,79 +210,6 @@ Watch Chef configure systems! A note about git: Opscode and many folks in the Chef community use git, but it is not required, except in the case of the \fBcookbook site vendor\fR sub\-command, as it uses git directly\. Version control is strongly recommended though, and git fits with a lot of the workflow paradigms\. . .SH "EXAMPLES" -Example client config (\fB/etc/chef/client\.rb\fR) from \fBknife configure client\fR\. The same configuration is used when using the \fBknife bootstrap\fR command with the default \fBgem\fR templates that come with Chef\. -. -.IP "" 4 -. -.nf - -log_level :info -log_location STDOUT -chef_server_url \'https://api\.opscode\.com/organizations/ORGNAME\' -validation_client_name \'ORGNAME\-validator\' -. -.fi -. -.IP "" 0 -. -.P -Setting up a custom bootstrap is fairly straightforward\. Create \fB\.chef/bootstrap\fR in your Chef Repository directory or in \fB$HOME/\.chef/bootstrap\fR\. Then create the ERB template file\. -. -.IP "" 4 -. -.nf - -mkdir ~/\.chef/bootstrap -vi ~/\.chef/bootstrap/debian5\.0\-apt\.erb -. -.fi -. -.IP "" 0 -. -.P -For example, to create a new bootstrap template that should be used when setting up a new Debian node\. Edit the template to run the commands, set up the validation certificate and the client configuration file, and finally to run chef\-client on completion\. The bootstrap template can be called with: -. -.IP "" 4 -. -.nf - -knife bootstrap mynode\.example\.com \-\-template\-file ~/\.chef/bootstrap/debian5\.0\-apt\.erb -. -.fi -. -.IP "" 0 -. -.P -Or, -. -.IP "" 4 -. -.nf - -knife bootstrap mynode\.example\.com \-\-distro debian5\.0\-apt -. -.fi -. -.IP "" 0 -. -.P -The \fB\-\-distro\fR parameter will automatically look in the \fB~/\.chef/bootstrap\fR directory for a file named \fBdebian5\.0\-apt\.erb\fR\. -. -.P -Templates provided by the Chef installation are located in \fBBASEDIR/lib/chef/knife/bootstrap/*\.erb\fR, where \fIBASEDIR\fR is the location where the package or Gem installed the Chef client libraries\. -. -.P -Uploading cookbooks to the Opscode cookbooks site using the user/certificate specifically: -. -.IP "" 4 -. -.nf - -knife cookbook site share example Other \-k ~/\.chef/USERNAME\.pem \-u USERNAME -. -.fi -. -.IP "" 0 . .SH "ENVIRONMENT" . @@ -325,22 +218,34 @@ knife cookbook site share example Other \-k ~/\.chef/USERNAME\.pem \-u USERNAME The text editor to use for editing data\. The \-\-editor option takes precedence over this value, and the \-\-no\-editor option supresses data editing entirely\. . .SH "SEE ALSO" -Full documentation for Chef is located on the Chef wiki, http://wiki\.opscode\.com/display/chef/Home/\. +\fBchef\-client(8)\fR \fBchef\-server(8)\fR \fBshef(1)\fR . .P -JSON is JavaScript Object Notation and more information can be found at http://json\.org/\. +\fBknife\-bootstrap(1)\fR \fBknife\-client(1)\fR \fBknife\-configure(1)\fR \fBknife\-cookbook\-site(1)\fR \fBknife\-cookbook(1)\fR \fBknife\-data\-bag(1)\fR \fBknife\-environment(1)\fR \fBknife\-exec(1)\fR \fBknife\-index(1)\fR \fBknife\-node(1)\fR \fBknife\-recipe(1)\fR \fBknife\-role(1)\fR \fBknife\-search(1)\fR \fBknife\-ssh(1)\fR \fBknife\-tag(1)\fR . .P -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/\. +Complete Chef documentation is available online: \fIhttp://wiki\.opscode\.com/display/chef/Home/\fR . .P -Git is a version control system and documented at http://git\-scm\.com/\. +JSON is JavaScript Object Notation \fIhttp://json\.org/\fR . .P -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\. +SOLR is an open source search engine\. \fIhttp://lucene\.apache\.org/solr/\fR . -.SH "AUTHOR" -Chef was written by Adam Jacob \fIadam@opscode\.com\fR of Opscode (\fIhttp://www\.opscode\.com\fR), with contributions from the community\. 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\. +.P +\fBgit(1)\fR is a version control system \fIhttp://git\-scm\.com/\fR . .P -On Debian systems, the complete text of the Apache 2\.0 License can be found in \fB/usr/share/common\-licenses/Apache\-2\.0\fR\. +This manual page was generated from Markdown with \fBronn(1)\fR \fIhttp://rtomayko\.github\.com/ronn/ronn\.1\.html\fR +. +.SH "AUTHOR" +Chef was written by Adam Jacob \fIadam@opscode\.com\fR of Opscode (\fIhttp://www\.opscode\.com\fR), with contributions from the community\. +. +.SH "DOCUMENTATION" +This manual page was written by Joshua Timberman \fIjoshua@opscode\.com\fR\. +. +.SH "LICENSE" +Both Chef and this documentation are released under the terms of the Apache 2\.0 License\. You may view the license online: \fIhttp://www\.apache\.org/licenses/LICENSE\-2\.0\.html\fR On some systems, the complete text of the Apache 2\.0 License may be found in \fB/usr/share/common\-licenses/Apache\-2\.0\fR\. +. +.SH "CHEF" +Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR diff --git a/chef/distro/common/markdown/man1/knife-bootstrap.mkd b/chef/distro/common/markdown/man1/knife-bootstrap.mkd index 8fba685804..7789faec8e 100644 --- a/chef/distro/common/markdown/man1/knife-bootstrap.mkd +++ b/chef/distro/common/markdown/man1/knife-bootstrap.mkd @@ -34,8 +34,7 @@ Performs a Chef Bootstrap on the target node. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server. The main assumption is a baseline OS installation exists. This sub-command is used internally by some cloud computing -server create commands and the others will be migrated in a future -version of Chef. +plugins. The bootstrap sub-command supports supplying a template to perform the bootstrap steps. If the distro is not specified (via `-d` or `--distro` @@ -49,22 +48,34 @@ sub-command looks in the following locations for the template to use: * `bootstrap` directory in the `$PWD/.chef`. * `bootstrap` directory in the users `$HOME/.chef`. -The default bootstrap templates are scripts that get copied to the target node (FQDN). As of Chef 0.9.8, the following distros are supported: +The default bootstrap templates are scripts that get copied to the +target node (FQDN). The following distros are supported: * centos5-gems * fedora13-gems * ubuntu10.04-gems * ubuntu10.04-apt -The gems installations will use RubyGems 1.3.6 and Chef installed as a gem. The apt installation will use the Opscode APT repository. The RubyGems installation requires installing gems with native extensions, so development related packages (ruby-dev, build-essential) are installed. These are not installed with the apt installation, as native extensions are already compiled in the required packages. +The gems installations will use RubyGems 1.3.6 and Chef installed as a +gem. The apt installation will use the Opscode APT repository. The +RubyGems installation requires installing gems with native extensions, +so development related packages (ruby-dev, build-essential) are +installed. These are not installed with the apt installation, as native +extensions are already compiled in the required packages. -In addition to handling the software installation, these bootstrap templates do the following: +In addition to handling the software installation, these bootstrap +templates do the following: - Write the validation.pem per the local knife configuration. - Write a default config file for Chef (`/etc/chef/client.rb`) using values from the `knife.rb`. - Create a JSON attributes file containing the specified run list and run Chef. -In the case of the RubyGems, the `client.rb` will be written from scratch with a minimal set of values; see __EXAMPLES__. In the case of APT Package installation, `client.rb` will have the `validation_client_name` appended if it is not set to `chef-validator` (default config value), and the `node_name` will be added if `chef_node_name` option is specified. +In the case of the RubyGems, the `client.rb` will be written from +scratch with a minimal set of values; see __EXAMPLES__. In the case of +APT Package installation, `client.rb` will have the +`validation_client_name` appended if it is not set to `chef-validator` +(default config value), and the `node_name` will be added if +`chef_node_name` option is specified. When this is complete, the bootstrapped node will have: @@ -72,8 +83,45 @@ When this is complete, the bootstrapped node will have: - Be validated with the configured Chef Server. - Have run Chef with its default run list if one is specfied. -Additional custom bootstrap templates can be created and stored in `.chef/bootstrap/DISTRO.erb`, replacing __DISTRO__ with the value passed with the `-d` or `--distro` option. See __EXAMPLES__ for more information. +Additional custom bootstrap templates can be created and stored in +`.chef/bootstrap/DISTRO.erb`, replacing __DISTRO__ with the value passed +with the `-d` or `--distro` option. See __EXAMPLES__ for more +information. +## EXAMPLES +Setting up a custom bootstrap is fairly straightforward. Create a +`.chef/bootstrap` directory in your Chef Repository or in +`$HOME/.chef/bootstrap`. Then create the ERB template file. + + mkdir ~/.chef/bootstrap + vi ~/.chef/bootstrap/debian5.0-apt.erb + +For example, to create a new bootstrap template that should be used when +setting up a new Debian node. Edit the template to run the commands, set +up the validation certificate and the client configuration file, and +finally to run chef-client on completion. The bootstrap template can be +called with: + + knife bootstrap mynode.example.com --template-file ~/.chef/bootstrap/debian5.0-apt.erb + +Or, + + knife bootstrap mynode.example.com --distro debian5.0-apt + +The `--distro` parameter will automatically look in the +`~/.chef/bootstrap` directory for a file named `debian5.0-apt.erb`. + +Templates provided by the Chef installation are located in +`BASEDIR/lib/chef/knife/bootstrap/*.erb`, where _BASEDIR_ is the +location where the package or Gem installed the Chef client libraries. + +## BUGS +`knife bootstrap` is not capable of bootstrapping multiple hosts in +parallel. + +The bootstrap script is passed as an argument to sh(1) on the remote +system, so sensitive information contained in the script will be visible +to other users via the process list using tools such as ps(1). ## SEE ALSO __knife-ssh__(1) diff --git a/chef/distro/common/markdown/man1/knife-client.mkd b/chef/distro/common/markdown/man1/knife-client.mkd index 8764d7d71c..e7b732ef71 100644 --- a/chef/distro/common/markdown/man1/knife-client.mkd +++ b/chef/distro/common/markdown/man1/knife-client.mkd @@ -5,23 +5,9 @@ knife-client(1) -- Manage Chef API Clients __knife__ __client__ _sub-command_ _(options)_ -## DESCRIPTION -Clients are identities used for communication with the Chef Server API, -roughly equivalent to user accounts on the Chef Server, except that -clients only communicate with the Chef Server API and are authenticated -via request signatures. - -In the typical case, there will be one client object on the server for -each node, and the corresponding client and node will have identical -names. - -In the Chef authorization model, there is one special client, the -"validator", which is authorized to create new non-administrative -clients but has minimal privileges otherwise. This identity is used as a -sort of "guest account" to create a client identity when initially -setting up a host for management with Chef. - -## CLIENT SUB-COMMANDS +## SUB-COMMANDS +Client subcommands follow a basic create, read, update, delete (CRUD) +pattern. The Following subcommands are available: ## BULK DELETE __knife client bulk delete__ _regex_ _(options)_ @@ -86,6 +72,22 @@ __client show__ _client name_ _(options)_ Show a client. Output format is determined by the --format option. +## DESCRIPTION +Clients are identities used for communication with the Chef Server API, +roughly equivalent to user accounts on the Chef Server, except that +clients only communicate with the Chef Server API and are authenticated +via request signatures. + +In the typical case, there will be one client object on the server for +each node, and the corresponding client and node will have identical +names. + +In the Chef authorization model, there is one special client, the +"validator", which is authorized to create new non-administrative +clients but has minimal privileges otherwise. This identity is used as a +sort of "guest account" to create a client identity when initially +setting up a host for management with Chef. + ## SEE ALSO __knife-node__(1) diff --git a/chef/distro/common/markdown/man1/knife-cookbook-site.mkd b/chef/distro/common/markdown/man1/knife-cookbook-site.mkd index 81adf0c54f..01d57c1056 100644 --- a/chef/distro/common/markdown/man1/knife-cookbook-site.mkd +++ b/chef/distro/common/markdown/man1/knife-cookbook-site.mkd @@ -6,28 +6,58 @@ knife-cookbook-site(1) -- Install and update open source cookbooks __knife__ __cookbook site__ _sub-command_ _(options)_ ## COOKBOOK SITE SUB-COMMANDS +`knife cookbook site` provides the following subcommands: -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. +## INSTALL +__cookbook site install COOKBOOK [VERSION]__ _(options)_ -__cookbook site download COOKBOOK [VERSION]__ _(options)_ + * `-d`, `--dependencies`: + Grab dependencies automatically + +Uses git(1) version control in conjunction with the cookbook site to +install community contributed cookbooks to your local cookbook +repository. Running `knife cookbook site install` does the following: + +1. A new "pristine copy" branch is created in git for tracking the + upstream; +2. All existing cookbooks are removed from the branch; +3. The cookbook is downloaded from the cookbook site in tarball form; +4. The downloaded cookbook is untarred, and its contents commited via git; +5. The pristine copy branch is merged into the master branch. + +By installing cookbook with this process, you can locally modify the +upstream cookbook in your master branch ant let git maintain your +changes as a separate patch. When an updated upstream version becomes +available, you will be able to merge the upstream changes while +maintaining your local modifications. + +If _-d_ is specified, the process is applied recursively to all the +cookbooks _COOKBOOK_ depends on (via metadata _dependencies_). + +## DOWNLOAD +__knife 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. +Downloads a specific cookbook from the Community site, optionally +specifying a certain version. -__cookbook site list__ _(options)_ +## LIST +__knife cookbook site list__ _(options)_ * `-w`, `--with-uri`: Show corresponding URIs Lists available cookbooks from the Community site. -__cookbook site search QUERY__ _(options)_ +## SEARCH +__knife cookbook site search QUERY__ _(options)_ -Searches the Community site with the specified query. +Searches for available cookbooks matching the specified query. -__cookbook site share COOKBOOK CATEGORY__ _(options)_ +## SHARE +__knife cookbook site share COOKBOOK CATEGORY__ _(options)_ * `-k`, `--key KEY`: API Client Key @@ -36,26 +66,44 @@ __cookbook site share COOKBOOK CATEGORY__ _(options)_ * `-o`, `--cookbook-path PATH:PATH`: A colon-separated path to look for cookbooks in -Uploads the specified cookbook using the given category to the Opscode cookbooks site. Requires a login user and certificate for the Opscode Cookbooks site. See __EXAMPLES__ for usage if the Opscode user and certificate pair are not used for authenticating with the Chef Server. In other words, if the Chef Server is not the Opscode Platform. +Uploads the specified cookbook using the given category to the Opscode +cookbooks site. Requires a login user and certificate for the Opscode +Cookbooks site. By default, knife will use the username and API key +you've configured in your configuration file; otherwise you must +explicitly set these values on the command line or use an alternate +configuration file. -__cookbook site unshare COOKBOOK__ +## UNSHARE +__knife cookbook site unshare COOKBOOK__ Stops sharing the specified cookbook on the Opscode cookbooks site. -__cookbook site show COOKBOOK [VERSION]__ _(options)_ +## SHOW +__knife cookbook site show COOKBOOK [VERSION]__ _(options)_ Shows information from the site about a particular cookbook. -__cookbook site vendor COOKBOOK [VERSION]__ _(options)_ +## DESCRIPTION +The cookbook site, <http://community.opscode.com/>, is a cookbook +distribution service operated by Opscode. This service provides users +with a central location to publish cookbooks for sharing with other +community members. - * `-d`, `--dependencies`: - Grab dependencies automatically +`knife cookbook site` commands provide an interface to the cookbook +site's HTTP API. For commands that read data from the API, no account is +required. In order to upload cookbooks using the `knife cookbook site +share` command, you must create an account on the cookbook site and +configure your credentials via command line option or in your knife +configuration file. -Uses `git` version control in conjunction with the cookbook site to download upstream cookbooks. A new vendor branch is created in git, the cookbook downloaded from the site and untarred, then the master branch is merged. This allows the user to track upstream changes to cookbooks while merging in customizations. If _-d_ is specified, all the cookbooks it depends on (via metadata _dependencies_) are downloaded and untarred as well, each using their own vendor branch. +## EXAMPLES +Uploading cookbooks to the Opscode cookbooks site: + knife cookbook site share example Other -k ~/.chef/USERNAME.pem -u USERNAME ## SEE ALSO - __knife-environment__(1) + __knife-cookbook(1)__ + <http://community.opscode.com/cookbooks> ## AUTHOR Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. diff --git a/chef/distro/common/markdown/man1/knife-cookbook.mkd b/chef/distro/common/markdown/man1/knife-cookbook.mkd index 02ae6f3f90..32bdcfdbc5 100644 --- a/chef/distro/common/markdown/man1/knife-cookbook.mkd +++ b/chef/distro/common/markdown/man1/knife-cookbook.mkd @@ -1,136 +1,253 @@ -knife-cookbook(1) -- Upload and manage Chef cookbooks +knife-cookbook(1) -- upload and manage chef cookbooks ======================================== ## SYNOPSIS __knife__ __cookbook__ _sub-command_ _(options)_ -## COOKBOOK SUB-COMMANDS +## SUB-COMMANDS +`knife cookbook` supports the following 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. +## LIST +__knife cookbook list__ _(options)_ -__cookbook bulk delete REGEX__ _(options)_ - - * `-p`, `--purge`: - Purge files from backing store. This will disable any cookbook that contains any of the same files as the cookbook being purged. - -Delete cookbooks on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s. - -__cookbook create COOKBOOK__ _(options)_ - - * `-o`, `--cookbook-path PATH`: - The directory where the cookbook will be created - * `-r`, `--readme-format FORMAT`: - Format of the README file - * `-C`, `--copyright COPYRIGHT`: - Name of Copyright holder - * `-I`, `--license LICENSE`: - License for cookbook, apachev2 or none - * `-E`, `--email EMAIL`: - Email address of cookbook maintainer - -This is a helper command that creates a new cookbook directory in the `cookbook_path`. The following directories and files are created for the named cookbook. - -* COOKBOOK/attributes -* COOKBOOK/definitions -* COOKBOOK/files/default -* COOKBOOK/libraries -* COOKBOOK/metadata.rb -* COOKBOOK/providers -* COOKBOOK/README.rdoc -* COOKBOOK/recipes/default.rb -* COOKBOOK/resources -* COOKBOOK/templates/default - -Supported README formats are 'rdoc' (default), 'md', 'mkd', 'txt'. The README file will be written with the specified extension and a set of helpful starting headers. + * `-a`, `--all`: + show all versions of a cookbook instead of just the most recent + * `-w`, `--with-uri`: + show corresponding uris -Specify `-C` or `--copyright` with the name of the copyright holder as your name or your company/organization name in a quoted string. If this value is not specified an all-caps string `YOUR_COMPANY_NAME` is used which can be easily changed with find/replace. +Lists the cookbooks available on the Chef server. -Specify `-I` or `--license` with the license that the cookbook is distributed under for sharing with other people or posting to the Opscode Cookbooks site. Be aware of the licenses of files you put inside the cookbook and follow any restrictions they describe. When using `none` (default) or `apachev2`, comment header text and metadata file are pre-filled. The `none` license will be treated as non-redistributable. +## SHOW +__knife cookbook show cookbook [version] [part] [filename]__ _(options)_ -Specify `-E` or `--email` with the email address of the cookbook's maintainer. If this value is not specified, an all-caps string `YOUR_EMAIL` is used which can easily be changed with find/replace. + * `-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 -The cookbook copyright, license and email settings can be filled in the `knife.rb`, for example with default values: +show a particular part of a _cookbook_ for the specified _version_. _part_ can be one of: - cookbook_copyright "YOUR_COMPANY_NAME" - cookbook_license "none" - cookbook_email "YOUR_EMAIL" + * _attributes_ + * _definitions_ + * _files_ + * _libraries_ + * _providers_ + * _recipes_ + * _resources_ + * _templates_ -__cookbook delete COOKBOOK [VERSION]__ _(options)_ +## UPLOAD +__knife cookbook upload [cookbooks...]__ _(options)_ * `-a`, `--all`: - Delete all versions - * `-p`, `--purge`: - Purge files from backing store. This will disable any cookbook that contains any of the same files as the cookbook being purged. - -Delete the specified _VERSION_ of the named _COOKBOOK_. If no version is specified, and only one version exists on the server, that version will be deleted. If multiple versions are available on the server, you will be prompted for a version to delete. - -__cookbook download COOKBOOK [VERSION]__ _(options)_ - - * `-d`, `--dir DOWNLOAD_DIRECTORY`: - The directory to download the cookbook into + upload all cookbooks, rather than just a single cookbook + * `-o`, `--cookbook-path path:path`: + a colon-separated path to look for cookbooks in + * `-E`, `--environment ENVIRONMENT`: + An _ENVIRONMENT_ to apply the uploaded cookbooks to. Specifying this + option will cause knife to edit the _ENVIRONMENT_ to place a strict + version constraint on the cookbook version(s) uploaded. + * `--freeze`: + Sets the frozen flag on the uploaded cookbook(s) Any future attempt + to modify the cookbook without changing the version number will + return an error unless --force is specified. + * `--force`: + Overrides the frozen flag on a cookbook, allowing you to overwrite a + cookbook version that has previously been uploaded with the --freeze + option. + +Uploads one or more cookbooks from your local cookbook repository(ies) +to the Chef Server. Only files that don't yet exist on the server will +be uploaded. + +## DOWNLOAD +__knife cookbook download cookbook [version]__ _(options)_ + + * `-d`, `--dir download_directory`: + the directory to download the cookbook into * `-f`, `--force`: - Overwrite an existing directory with the download - * `-N`, `--latest`: - Download the latest version of the cookbook - -Download a cookbook from the Chef Server. If no version is specified and only one version exists on the server, that version will be downloaded. If no version is specified and multiple versions are available on the server, you will be prompted for a version to download. - -__cookbook list__ _(options)_ + overwrite an existing directory with the download + * `-n`, `--latest`: + download the latest version of the cookbook - * `-w`, `--with-uri`: - Show corresponding URIs - -List all the cookbooks. +download a cookbook from the chef server. if no version is specified and +only one version exists on the server, that version will be downloaded. +if no version is specified and multiple versions are available on the +server, you will be prompted for a version to download. -__cookbook metadata COOKBOOK__ _(options)_ +## DELETE +__knife cookbook delete cookbook [version]__ _(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. + delete all versions + * `-p`, `--purge`: + purge files from backing store. this will disable any cookbook that contains any of the same files as the cookbook being purged. -__cookbook metadata from FILE__ _(options)_ +delete the specified _version_ of the named _cookbook_. if no version is +specified, and only one version exists on the server, that version will +be deleted. if multiple versions are available on the server, you will +be prompted for a version to delete. -Load the cookbook metadata from a specified file. +## BULK DELETE +__knife cookbook bulk delete regex__ _(options)_ -__cookbook show COOKBOOK [VERSION] [PART] [FILENAME]__ _(options)_ + * `-p`, `--purge`: + purge files from backing store. this will disable any cookbook that + contains any of the same files as the cookbook being purged. + +delete cookbooks on the chef server based on a regular expression. the +regular expression (_regex_) should be in quotes, not in //'s. + +## COOKBOOK CREATE +__knife cookbook create cookbook__ _(options)_ + + * `-o`, `--cookbook-path path`: + the directory where the cookbook will be created + * `-r`, `--readme-format format`: + format of the readme file + * `-c`, `--copyright copyright`: + name of copyright holder + * `-i`, `--license license`: + license for cookbook, apachev2 or none + * `-e`, `--email email`: + email address of cookbook maintainer + +this is a helper command that creates a new cookbook directory in the +`cookbook_path`. the following directories and files are created for the +named cookbook. + +* cookbook/attributes +* cookbook/definitions +* cookbook/files/default +* cookbook/libraries +* cookbook/metadata.rb +* cookbook/providers +* cookbook/readme.rdoc +* cookbook/recipes/default.rb +* cookbook/resources +* cookbook/templates/default + +supported readme formats are 'rdoc' (default), 'md', 'mkd', 'txt'. the +readme file will be written with the specified extension and a set of +helpful starting headers. + +specify `-c` or `--copyright` with the name of the copyright holder as +your name or your company/organization name in a quoted string. if this +value is not specified an all-caps string `your_company_name` is used +which can be easily changed with find/replace. + +specify `-i` or `--license` with the license that the cookbook is +distributed under for sharing with other people or posting to the +opscode cookbooks site. be aware of the licenses of files you put inside +the cookbook and follow any restrictions they describe. when using +`none` (default) or `apachev2`, comment header text and metadata file +are pre-filled. the `none` license will be treated as +non-redistributable. + +specify `-e` or `--email` with the email address of the cookbook's +maintainer. if this value is not specified, an all-caps string +`your_email` is used which can easily be changed with find/replace. + +the cookbook copyright, license and email settings can be filled in the +`knife.rb`, for example with default values: + + cookbook_copyright "your_company_name" + cookbook_license "none" + cookbook_email "your_email" - * `-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_ for the specified _VERSION_. _PART_ can be one of: - - * _attributes_ - * _definitions_ - * _files_ - * _libraries_ - * _providers_ - * _recipes_ - * _resources_ - * _templates_ - -__cookbook test [COOKBOOKS...]__ _(options)_ +## METADATA +__knife cookbook metadata cookbook__ _(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 + 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 -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). +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 upload [COOKBOOKS...]__ _(options)_ +## METADATA FROM FILE +__knife cookbook metadata from file__ _(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 +load the cookbook metadata from a specified file. -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. +## TEST +__knife 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). + +## RECIPE LIST +__knife recipe list [PATTERN]__ + +List available recipes from the server. Specify _PATTERN_ as a regular +expression to limit the results. + +## DESCRIPTION +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. + +On disk, cookbooks are directories with a defined structure. The +following directories may appear within a cookbook: + + * COOKBOOK/attributes/: + Ruby files that define default parameters to be used in recipes + * COOKBOOK/definitions/: + Ruby files that contain _resource definitions_ + * COOKBOOK/files/SPECIFICITY: + Files of arbitrary type. These files may be downloaded by + chef-client(8) when configuring a host. + * COOKBOOK/libraries/: + Ruby files that contain library code needed for recipes + * COOKBOOK/providers/: + Ruby files that contain Lightweight Provider definitions + * COOKBOOK/recipes/: + Ruby files that use Chef's recipe DSL to describe the desired + configuration of a system + * COOKBOOK/resources/: + Ruby files that contain Lightweight Resource definitions + * COOKBOOK/templates/SPECIFICITY: + ERuby (ERb) template files. These are referenced by _recipes_ and + evaluated to dynamically generate configuration files. + +__SPECIFICITY__ is a feature of _files_ and _templates_ that allow you +to specify alternate files to be used on a specific OS platform or host. +The default specificity setting is _default_, that is files in +`COOKBOOK/files/default` will be used when a more specific copy is not +available. Further documentation for this feature is available on the +Chef wiki: <http://wiki.opscode.com/display/chef/File+Distribution#FileDistribution-FileSpecificity> + +Cookbooks also contain a metadata file that defines various properties +of the cookbook. The most important of these are the _version_ and the +_dependencies_. The _version_ is used in combination with environments +to select which copy of a given cookbook is distributed to a node. The +_dependencies_ are used by the server to determine which additional +cookbooks must be distributed to a given host when it requires a +cookbook. + +## SEE ALSO + __knife-environment(1)__ __knife-cookbook-site(1)__ + <http://wiki.opscode.com/display/chef/Cookbooks> + <http://wiki.opscode.com/display/chef/Metadata> + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + 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. + + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> diff --git a/chef/distro/common/markdown/man1/knife-environment.mkd b/chef/distro/common/markdown/man1/knife-environment.mkd index 7ee223f86d..2eebffbce6 100644 --- a/chef/distro/common/markdown/man1/knife-environment.mkd +++ b/chef/distro/common/markdown/man1/knife-environment.mkd @@ -6,6 +6,8 @@ knife-environment(1) -- Define cookbook policies for the environments in your in __knife__ __environment__ _sub-command_ _(options)_ ## SUBCOMMANDS +Environment subcommands follow a basic create, read, update, delete +(CRUD) pattern. The following subcommands are available: ## CREATE __knife environment create__ _environment_ _(options)_ diff --git a/chef/distro/common/markdown/man1/knife-node.mkd b/chef/distro/common/markdown/man1/knife-node.mkd index 4b5d1cf4f8..5937897ed8 100644 --- a/chef/distro/common/markdown/man1/knife-node.mkd +++ b/chef/distro/common/markdown/man1/knife-node.mkd @@ -28,7 +28,7 @@ host for the node name, though this may be overridden by configuration settings. ## NODE SUB-COMMANDS - +The following `node` subcommands are available: ## BULK DELETE __knife node bulk delete__ _regex_ _(options)_ diff --git a/chef/distro/common/markdown/man1/knife-recipe.mkd b/chef/distro/common/markdown/man1/knife-recipe.mkd deleted file mode 100644 index c795f13e92..0000000000 --- a/chef/distro/common/markdown/man1/knife-recipe.mkd +++ /dev/null @@ -1,24 +0,0 @@ -knife-recipe(1) -- List the recipes available on a Chef Server -======================================== - -## SYNOPSIS - -__knife__ __recipe list [PATTERN]__ - -List the recipes available on the server. The results shown can be -limited with the optional PATTERN, which is a regular expression. -PATTERN should be given in quotes, without slashes. - -## SEE ALSO - __knife-cookbook__(1) - -## AUTHOR - Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. - -## DOCUMENTATION - 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. - -## CHEF - Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> - diff --git a/chef/distro/common/markdown/man1/knife-role.mkd b/chef/distro/common/markdown/man1/knife-role.mkd index ac7b42f27e..7e0dac9bc5 100644 --- a/chef/distro/common/markdown/man1/knife-role.mkd +++ b/chef/distro/common/markdown/man1/knife-role.mkd @@ -5,29 +5,26 @@ knife-role(1) -- Group common configuration settings __knife__ __role__ _sub-command_ _(options)_ -## DESCRIPTION -Roles provide a mechanism to group repeated configuration settings. -Roles are data structures that contain __default\_attributes__, and -__override_attributes__, which are nested hashes of configuration -settings, and a __run_list__, which is an ordered list of recipes and -roles that should be applied to a host by chef-client. +## ROLE SUB-COMMANDS +The following `role` subcommands are available: -__default_attributes__ will be overridden if they conflict with a value -on a node that includes the role. Conversely, __override_attributes__ -will override any values set on nodes that apply them. +## LIST +__knife role list__ _(options)_ -When __chef-client__(8) configures a host, it will "expand" the -__run_list__ included in that host's node data. The expansion process -will recursively replace any roles in the run\_list with that role's -run\_list. + * `-w`, `--with-uri`: + Show corresponding URIs +List roles. -## ROLE SUB-COMMANDS +## SHOW +__knife role show ROLE__ _(options)_ -__knife role bulk delete REGEX__ _(options)_ + * `-a`, `--attribute ATTR`: + Show only one attribute -Delete roles on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s. +Show a specific role. +## CREATE __knife role create ROLE__ _(options)_ * `-d`, `--description`: @@ -35,36 +32,45 @@ __knife role create ROLE__ _(options)_ Create a new role. -__knife role delete ROLE__ _(options)_ - -Delete a role. - +## EDIT __knife role edit ROLE__ _(options)_ Edit a role. +## FROM FILE __knife role from file FILE__ _(options)_ Create or update a role from a role Ruby DSL (`.rb`) or JSON file. -__knife role list__ _(options)_ +## DELETE +__knife role delete ROLE__ _(options)_ - * `-w`, `--with-uri`: - Show corresponding URIs +Delete a role. -List roles. +## BULK DELETE +__knife role bulk delete REGEX__ _(options)_ -__knife role show ROLE__ _(options)_ +Delete roles on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s. - * `-a`, `--attribute ATTR`: - Show only one attribute +## DESCRIPTION +Roles provide a mechanism to group repeated configuration settings. +Roles are data structures that contain __default\_attributes__, and +__override_attributes__, which are nested hashes of configuration +settings, and a __run_list__, which is an ordered list of recipes and +roles that should be applied to a host by chef-client. -Show a specific role. +__default_attributes__ will be overridden if they conflict with a value +on a node that includes the role. Conversely, __override_attributes__ +will override any values set on nodes that apply them. +When __chef-client__(8) configures a host, it will "expand" the +__run_list__ included in that host's node data. The expansion process +will recursively replace any roles in the run\_list with that role's +run\_list. ## SEE ALSO - __knife-node__(1) - + __knife-node(1)__ __knife-environment(1)__ + <http://wiki.opscode.com/display/chef/Roles> <http://wiki.opscode.com/display/chef/Attributes> ## AUTHOR diff --git a/chef/distro/common/markdown/man1/knife-search.mkd b/chef/distro/common/markdown/man1/knife-search.mkd index 50ec98592d..3e35a7969f 100644 --- a/chef/distro/common/markdown/man1/knife-search.mkd +++ b/chef/distro/common/markdown/man1/knife-search.mkd @@ -40,7 +40,6 @@ query syntax. The following data types are indexed for search: ## SEE ALSO __knife-ssh__(1) - <http://wiki.opscode.com/display/chef/Attributes> ## AUTHOR diff --git a/chef/distro/common/markdown/man1/knife-ssh.mkd b/chef/distro/common/markdown/man1/knife-ssh.mkd index c8da64d306..07dbaa0fa2 100644 --- a/chef/distro/common/markdown/man1/knife-ssh.mkd +++ b/chef/distro/common/markdown/man1/knife-ssh.mkd @@ -49,8 +49,6 @@ The available multiplexers are: ## SEE ALSO __knife-search__(1) - <http://wiki.opscode.com/display/chef/Attributes> - ## AUTHOR Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. diff --git a/chef/distro/common/markdown/man1/knife-status.mkd b/chef/distro/common/markdown/man1/knife-status.mkd index f333f53fb5..07f0ff305a 100644 --- a/chef/distro/common/markdown/man1/knife-status.mkd +++ b/chef/distro/common/markdown/man1/knife-status.mkd @@ -23,8 +23,6 @@ may not be publicly reachable. ## SEE ALSO __knife-search__(1) - <http://wiki.opscode.com/display/chef/Attributes> - ## AUTHOR Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. diff --git a/chef/distro/common/markdown/man1/knife-tag.mkd b/chef/distro/common/markdown/man1/knife-tag.mkd index c43c0631dd..6a1a2c4b56 100644 --- a/chef/distro/common/markdown/man1/knife-tag.mkd +++ b/chef/distro/common/markdown/man1/knife-tag.mkd @@ -6,3 +6,34 @@ knife-tag(1) -- Apply tags to nodes on a Chef Server __knife__ __tag__ _subcommand_ _(options)_ ## TAG SUBCOMMANDS +The following `tag` subcommands are available: + +## CREATE +__knife tag create__ _node_ _tag_ [_..._] + +Adds one or more tags to _node_ + +## DELETE +__knife tag delete__ _node_ _tag_ [_..._] + +Removes one or more tags from _node_ + +## LIST +__knife tag list__ _node_ + +Lists the tags applied to _node_ + + +## SEE ALSO + __knife-node(1)__ + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Daniel DeLeo <dan@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + diff --git a/chef/distro/common/markdown/man1/knife.mkd b/chef/distro/common/markdown/man1/knife.mkd index ebd056c920..fb29861138 100644 --- a/chef/distro/common/markdown/man1/knife.mkd +++ b/chef/distro/common/markdown/man1/knife.mkd @@ -1,28 +1,39 @@ -knife(1) -- Chef Server REST API utility +knife(1) -- Chef Server API client utility ======================================== ## SYNOPSIS -__knife__ _sub-command_ _(options)_ +__knife__ _sub-command_ [_argument_...] _(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. - -The Chef class `Chef::Config` that configures the behavior of how knife -runs has options that correspond to command-line options. These are -noted as `Chef::Config` values. - -## GENERAL OPTIONS - +Knife is a command-line utility used to manage data on a Chef server +through the HTTP(S) API. Knife is organized into groups of subcommands +centered around the various object types in Chef. Each category of +subcommand is documented in its own manual page. Available topics are: + + * bootstrap + * client + * configure + * cookbook-site + * cookbook + * data-bag + * environment + * exec + * index + * node + * recipe + * role + * search + * ssh + * status + * tag + +If the knife manuals are in your `MANPATH`, you can access help for the +above topics using `man knife-TOPIC`; otherwise, you can view the +documentation using `knife help TOPIC`. + +## OPTIONS * `-s`, `--server-url` URL: Chef Server URL, corresponds to `Chef::Config` `chef_server_url`. * `-k`, `--key` KEY: @@ -48,29 +59,21 @@ noted as `Chef::Config` values. * `-y`, `--yes`: Say yes to all prompts for confirmation * `-h`, `--help`: - Show this message - -Usage information for sub-commands can be displayed with `knife SUB-COMMAND --help`. + Show the available options for a command. ## 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. +Sub-commands that operate on the basic Chef data types are structured as +_NOUN verb NOUN (options)_. For all data types, the following commands +are available: * create (create) * list and show (read) * edit (update) * delete (destroy) -Objects stored on the server support these, as described below. - -## GENERAL SUB-COMMANDS - -__recipe list [PATTERN]__ - -List available recipes from the server. Specify _PATTERN_ as a regular expression to limit the results. - +Knife also includes commands that take actions other than displaying or +modifying data on the Chef Server, such as __knife-ssh(1)__. ## CONFIGURATION @@ -82,94 +85,40 @@ be `.chef/knife.rb` in the current directory of the repository. If the config file 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`. - -`cookbook_copyright` -`cookbook_email` -`cookbook_license` - -Used by `knife cookbook create` sub-command to specify the copyright -holder, maintainer email and license (respectively) for new cookbooks. -The copyright holder is listed as the maintainer in the cookbook's -metadata and as the Copyright in the comments of the default recipe. The -maintainer email is used in the cookbook metadata. The license -determines what preamble to put in the comment of the default recipe, -and is listed as the license in the cookbook metadata. Currently -supported licenses are "apachev2" and "none". Any other values will -result in an empty license in the metadata (needs to be filled in by the -author), and no comment preamble in the default recipe. - -`knife[:aws_access_key_id]` -`knife[:aws_secret_access_key]` - -Specifies the Amazon AWS EC2 credentials to use when running the ec2 sub-commands. - -`knife[:rackspace_api_username]` -`knife[:rackspace_api_key]` - -Specifies the Rackspace Cloud credentials to use when running the rackspace sub-commands. - -`knife[:terremark_username]` -`knife[:terremark_password]` -`knife[:terremark_service]` - -Specifies the Terremark vCloud credentials to use when running the terremark sub-commands. - -`knife[:slicehost_password]` - -Specifies the Slicehost password to use when running the slicdehost sub-commands. + * `node_name`: + User or client identity (i.e., _name_) to use for authenticating + requests to the Chef Server. + * `client_key`: + Private key file to authenticate to the Chef server. Corresponds to the + `-k` or `--key` option. + * `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. These options are + dependent on the `cache_type`. + * `validation_client_name`: + Specifies the name of the client used to validate new clients. + * `validation_key`: + Specifies the private key file to use when bootstrapping new hosts. + See knife-client(1) for more information about the validation + client. + * `cookbook_copyright`, `cookbook_email`, `cookbook_license` + Used by `knife cookbook create` sub-command to specify the copyright + holder, maintainer email and license (respectively) for new cookbooks. + The copyright holder is listed as the maintainer in the cookbook's + metadata and as the Copyright in the comments of the default recipe. The + maintainer email is used in the cookbook metadata. The license + determines what preamble to put in the comment of the default recipe, + and is listed as the license in the cookbook metadata. Currently + supported licenses are "apachev2" and "none". Any other values will + result in an empty license in the metadata (needs to be filled in by the + author), and no comment preamble in the default recipe. ## FILES @@ -197,44 +146,6 @@ recommended though, and git fits with a lot of the workflow paradigms. ## EXAMPLES -Example client config (`/etc/chef/client.rb`) from `knife configure -client`. The same configuration is used when using the `knife bootstrap` -command with the default `gem` templates that come with Chef. - - log_level :info - log_location STDOUT - chef_server_url 'https://api.opscode.com/organizations/ORGNAME' - validation_client_name 'ORGNAME-validator' - -Setting up a custom bootstrap is fairly straightforward. Create -`.chef/bootstrap` in your Chef Repository directory or in -`$HOME/.chef/bootstrap`. Then create the ERB template file. - - mkdir ~/.chef/bootstrap - vi ~/.chef/bootstrap/debian5.0-apt.erb - -For example, to create a new bootstrap template that should be used when -setting up a new Debian node. Edit the template to run the commands, set -up the validation certificate and the client configuration file, and -finally to run chef-client on completion. The bootstrap template can be -called with: - - knife bootstrap mynode.example.com --template-file ~/.chef/bootstrap/debian5.0-apt.erb - -Or, - - knife bootstrap mynode.example.com --distro debian5.0-apt - -The `--distro` parameter will automatically look in the -`~/.chef/bootstrap` directory for a file named `debian5.0-apt.erb`. - -Templates provided by the Chef installation are located in -`BASEDIR/lib/chef/knife/bootstrap/*.erb`, where _BASEDIR_ is the -location where the package or Gem installed the Chef client libraries. - -Uploading cookbooks to the Opscode cookbooks site using the user/certificate specifically: - - knife cookbook site share example Other -k ~/.chef/USERNAME.pem -u USERNAME ## ENVIRONMENT * `EDITOR`: @@ -243,19 +154,36 @@ Uploading cookbooks to the Opscode cookbooks site using the user/certificate spe data editing entirely. ## SEE ALSO + __chef-client(8)__ __chef-server(8)__ __shef(1)__ -Full documentation for Chef is located on the Chef wiki, http://wiki.opscode.com/display/chef/Home/. + __knife-bootstrap(1)__ __knife-client(1)__ __knife-configure(1)__ + __knife-cookbook-site(1)__ __knife-cookbook(1)__ __knife-data-bag(1)__ + __knife-environment(1)__ __knife-exec(1)__ __knife-index(1)__ + __knife-node(1)__ __knife-recipe(1)__ __knife-role(1)__ + __knife-search(1)__ __knife-ssh(1)__ __knife-tag(1)__ -JSON is JavaScript Object Notation and more information can be found at http://json.org/. + Complete Chef documentation is available online: <http://wiki.opscode.com/display/chef/Home/> -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/. + JSON is JavaScript Object Notation <http://json.org/> -Git is a version control system and documented at http://git-scm.com/. + SOLR is an open source search engine. <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. + __git(1)__ is a version control system <http://git-scm.com/> + + This manual page was generated from Markdown with __ronn(1)__ <http://rtomayko.github.com/ronn/ronn.1.html> ## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> of Opscode + (<http://www.opscode.com>), with contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + +## LICENSE + Both Chef and this documentation are released under the terms of the + Apache 2.0 License. You may view the license online: <http://www.apache.org/licenses/LICENSE-2.0.html> + On some systems, the complete text of the Apache 2.0 License may be found in `/usr/share/common-licenses/Apache-2.0`. -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. +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> -On Debian systems, the complete text of the Apache 2.0 License can be found in `/usr/share/common-licenses/Apache-2.0`. diff --git a/chef/lib/chef/application/knife.rb b/chef/lib/chef/application/knife.rb index 335d3bfe88..879e109e83 100644 --- a/chef/lib/chef/application/knife.rb +++ b/chef/lib/chef/application/knife.rb @@ -24,7 +24,7 @@ class Chef::Application::Knife < Chef::Application NO_COMMAND_GIVEN = "You need to pass a sub-command (e.g., knife SUB-COMMAND)\n" - banner "Usage: #{$0} sub-command (options)" + banner "Usage: knife sub-command (options)" option :config_file, :short => "-c CONFIG", diff --git a/chef/lib/chef/knife/cookbook_list.rb b/chef/lib/chef/knife/cookbook_list.rb index f8edb990de..349181d177 100644 --- a/chef/lib/chef/knife/cookbook_list.rb +++ b/chef/lib/chef/knife/cookbook_list.rb @@ -32,7 +32,7 @@ class Chef option :all_versions, :short => "-a", - :long => "--show-all-versions", + :long => "--all", :description => "Show all available versions." def run diff --git a/chef/lib/chef/knife/help.rb b/chef/lib/chef/knife/help.rb index f0e5f155a3..d2d2d79c13 100644 --- a/chef/lib/chef/knife/help.rb +++ b/chef/lib/chef/knife/help.rb @@ -25,14 +25,18 @@ class Chef def run if name_args.empty? ui.info "Usage: knife SUBCOMMAND (options)" - show_usage + ui.msg "" + # This command is atypical, the user is likely not interested in usage of + # this command, but knife in general. So hack the banner. + opt_parser.banner = "General Knife Options:" + ui.msg opt_parser.to_s ui.msg "" ui.info "For further help:" ui.info(<<-MOAR_HELP) knife help list list help topics knife help knife show general knife help knife help TOPIC display the manual for TOPIC - knife COMMAND --help show the options for a command + knife SUBCOMMAND --help show the options for a command MOAR_HELP exit 1 else |