chef 11.6.2 → 11.8.0.rc.1

data/distro/common/man/man1/knife-cookbook-site.1

@@ -1,145 +1,477 @@
-.\" generated with Ronn/v0.7.3
-.\" http://github.com/rtomayko/ronn/tree/0.7.3
-.
-.TH "KNIFE\-COOKBOOK\-SITE" "1" "October 2013" "Chef 11.6.2" "Chef Manual"
-.
-.SH "NAME"
-\fBknife\-cookbook\-site\fR \- Install and update open source cookbooks
-.
-.SH "SYNOPSIS"
-\fBknife\fR \fBcookbook site\fR \fIsub\-command\fR \fI(options)\fR
-.
-.SH "COOKBOOK SITE SUB\-COMMANDS"
-\fBknife cookbook site\fR provides the following subcommands:
-.
-.SH "INSTALL"
-\fBcookbook site install COOKBOOK [VERSION]\fR \fI(options)\fR
-.
+.TH "KNIFE-COOKBOOK-SITE" "1" "Chef 11.8.0" "" "knife cookbook site"
+.SH NAME
+knife-cookbook-site \- The man page for the knife cookbook site subcommand.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.\" Man page generated from reStructuredText.
+.
+.sp
+The Cookbooks Site API is used to provide access to the cookbooks community hosted at \fI\%https://cookbooks.opscode.com\fP. All of the cookbooks in the community are accessible through a REST API located at \fI\%https://cookbooks.opscode.com/api/v1/\fP by using any of the supported endpoints. In most cases, using Knife and the \fBknife cookbook site\fP sub\-command (and any of its arguments) is the recommended method of interacting with these cookbooks, but in some cases, using the REST API directly may make sense.
+.sp
+The \fBknife cookbook site\fP subcommand is used to interact with cookbooks that are located at \fI\%https://cookbooks.opscode.com\fP. A user account is required for any community actions that write data to this site. The following arguments do not require a user account: \fBdownload\fP, \fBsearch\fP, \fBinstall\fP, and \fBlist\fP.
+.sp
+This subcommand has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook site [ARGUMENT] (options)
+.ft P
+.fi
+.SH COMMON OPTIONS
+.sp
+The following options can be run with all Knife sub\-commands and plug\-ins:
+.INDENT 0.0
 .TP
-\fB\-D\fR, \fB\-\-skip\-dependencies\fR
-Skip automatic installation of dependencies\.
-.
+.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP
+The configuration file to use.
 .TP
-\fB\-o\fR, \fB\-\-cookbook\-path PATH\fR
-Install cookbooks to PATH
-.
+.B \fB\-\-color\fP
+Indicates that colored output will be used.
 .TP
-\fB\-B\fR, \fB\-\-branch BRANCH\fR
-Default branch to work with [defaults to master]
-.
-.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 and 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
-Unless \fI\-\-skip\-dependencies\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
-.
+.B \fB\-d\fP, \fB\-\-disable\-editing\fP
+Indicates that $EDITOR will not be opened; data will be accepted as\-is.
 .TP
-\fB\-f\fR, \fB\-\-file FILE\fR
-The filename to write to
-.
+.B \fB\-\-defaults\fP
+Indicates that Knife will use the default value, instead of asking a user to provide one.
 .TP
-\fB\-\-force\fR
-Force download deprecated cookbook
-.
-.P
-Downloads a specific cookbook from the Community site, optionally specifying a certain version\.
-.
-.SH "LIST"
-\fBknife cookbook site list\fR \fI(options)\fR
-.
+.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP
+The $EDITOR that is used for all interactive commands.
 .TP
-\fB\-w\fR, \fB\-\-with\-uri\fR
-Show corresponding URIs
-.
-.P
-Lists available cookbooks from the Community site\.
-.
-.SH "SEARCH"
-\fBknife cookbook site search QUERY\fR \fI(options)\fR
-.
-.P
-Searches for available cookbooks matching the specified query\.
-.
-.SH "SHARE"
-\fBknife cookbook site share COOKBOOK CATEGORY\fR \fI(options)\fR
-.
+.B \fB\-E ENVIRONMENT\fP, \fB\-\-environment ENVIRONMENT\fP
+The name of the environment. When this option is added to a command, the command will run only against the named environment.
 .TP
-\fB\-k\fR, \fB\-\-key KEY\fR
-API Client Key
-.
+.B \fB\-f FILE_NAME\fP, \fB\-\-file FILE_NAME\fP
+Indicates that the private key will be saved to a specified file name.
 .TP
-\fB\-u\fR, \fB\-\-user USER\fR
-API Client Username
-.
+.B \fB\-F FORMAT\fP, \fB\-\-format FORMAT\fP
+The output format: \fBsummary\fP (default), \fBtext\fP, \fBjson\fP, \fByaml\fP, and \fBpp\fP.
 .TP
-\fB\-o\fR, \fB\-\-cookbook\-path PATH:PATH\fR
-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\. 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\.
-.
-.SH "UNSHARE"
-\fBknife cookbook site unshare COOKBOOK\fR
-.
-.P
-Stops sharing the specified cookbook on the Opscode cookbooks site\.
-.
-.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
-\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\.
-.
-.SH "EXAMPLES"
-Uploading cookbooks to the Opscode cookbooks site:
-.
-.IP "" 4
-.
+.B \fB\-h\fP, \fB\-\-help\fP
+Shows help for the command.
+.TP
+.B \fB\-k KEY\fP, \fB\-\-key KEY\fP
+The private key that Knife will use to sign requests made by the API client to the server.
+.TP
+.B \fB\-\-no\-color\fP
+Indicates that color will not be used in the output.
+.TP
+.B \fB\-p PASSWORD\fP, \fB\-\-password PASSWORD\fP
+The user password.
+.TP
+.B \fB\-\-print\-after\fP
+Indicates that data will be shown after a destructive operation.
+.TP
+.B \fB\-s URL\fP, \fB\-\-server\-url URL\fP
+The URL for the server.
+.TP
+.B \fB\-u USER\fP, \fB\-\-user USER\fP
+The user name used by Knife to sign requests made by the API client to the server. Authentication will fail if the user name does not match the private key.
+.TP
+.B \fB\-v\fP, \fB\-\-version\fP
+The version of the chef\-client.
+.TP
+.B \fB\-V\fP, \fB\-\-verbose\fP
+Set for more verbose outputs. Use \fB\-VV\fP for maximum verbosity.
+.TP
+.B \fB\-y\fP, \fB\-\-yes\fP
+Indicates that the response to all confirmation prompts will be "Yes" (and that Knife will not ask for confirmation).
+.UNINDENT
+.SH DOWNLOAD
+.sp
+The \fBdownload\fP argument is used to download a cookbook from the community website. A cookbook will be downloaded as a tar.gz archive and placed in the current working directory. If a cookbook (or cookbook version) has been deprecated and the \fB\-\-force\fP option is not used, Knife will alert the user that the cookbook is deprecated and then will provide the name of the most recent non\-deprecated version of that cookbook.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
 .nf
-
-knife cookbook site share example Other \-k ~/\.chef/USERNAME\.pem \-u USERNAME
-.
+.ft C
+$ knife cookbook site download COOKBOOK_NAME [COOKBOOK_VERSION] (options)
+.ft P
 .fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fBCOOKBOOK_VERSION\fP
+The version of a cookbook to be downloaded. If a cookbook has only one version, this option does not need to be specified. If a cookbook has more than one version and this option is not specified, Knife will prompt for a version.
+.TP
+.B \fB\-f\fP, \fB\-\-force\fP
+Indicates that an existing directory will be overwritten.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To download the cookbook "getting\-started", enter:
+.sp
+.nf
+.ft C
+$ knife cookbook site download getting\-started
+.ft P
+.fi
+.sp
+to return something like:
+.sp
+.nf
+.ft C
+Downloading getting\-started from the cookbooks site at version 0.3.0 to
+  /Users/sdanna/opscodesupport/getting\-started\-0.3.0.tar.gz
+Cookbook saved: /Users/sdanna/opscodesupport/getting\-started\-0.3.0.tar.gz
+.ft P
+.fi
+.SH INSTALL
+.sp
+The \fBinstall\fP argument is used to install a cookbook that has been downloaded from the community site to a local git repository . This action uses the git version control system in conjunction with the \fI\%https://cookbooks.opscode.com\fP site to install community\-contributed cookbooks to the local chef\-repo. Using this argument does the following:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP 1. 3
+A new "pristine copy" branch is created in git for tracking the upstream.
+.IP 2. 3
+All existing versions of a cookbook are removed from the branch.
+.IP 3. 3
+The cookbook is downloaded from \fI\%https://cookbooks.opscode.com\fP in the tar.gz format.
+.IP 4. 3
+The downloaded cookbook is untarred and its contents are committed to git and a tag is created.
+.IP 5. 3
+The "pristine copy" branch is merged into the master branch.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+This process allows the upstream cookbook in the master branch to be modified while letting git maintain changes as a separate patch. When an updated upstream version becomes available, those changes can be merged while maintaining any local modifications.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook site install COOKBOOK_NAME [COOKBOOK_VERSION] (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-b\fP, \fB\-\-use\-current\-branch\fP
+Indicates that the current branch will be used.
+.TP
+.B \fB\-B BRANCH\fP, \fB\-\-branch BRANCH\fP
+The name of the default branch. This will default to the master branch.
+.TP
+.B \fBCOOKBOOK_VERSION\fP
+The version of the cookbook to be installed. If a version is not specified, the most recent version of the cookbook will be installed.
+.TP
+.B \fB\-D\fP, \fB\-\-skip\-dependencies\fP
+Indicates that all cookbooks to which the installed cookbook has a dependency will not be installed.
+.TP
+.B \fB\-o PATH:PATH\fP, \fB\-\-cookbook\-path PATH:PATH\fP
+The directory in which cookbook are created. This can be a colon\-separated path.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To install the cookbook "getting\-started", enter:
+.sp
+.nf
+.ft C
+$ knife cookbook site install getting\-started
+.ft P
+.fi
+.sp
+to return something like:
+.sp
+.nf
+.ft C
+Installing getting\-started to /Users/sdanna/opscodesupport/.chef/../cookbooks
+Checking out the master branch.
+Creating pristine copy branch chef\-vendor\-getting\-started
+Downloading getting\-started from the cookbooks site at version 0.3.0 to
+  /Users/sdanna/opscodesupport/.chef/../cookbooks/getting\-started.tar.gz
+Cookbook saved: /Users/sdanna/opscodesupport/.chef/../cookbooks/getting\-started.tar.gz
+Removing pre\-existing version.
+Uncompressing getting\-started version /Users/sdanna/opscodesupport/.chef/../cookbooks.
+removing downloaded tarball
+1 files updated, committing changes
+Creating tag cookbook\-site\-imported\-getting\-started\-0.3.0
+Checking out the master branch.
+Updating 4d44b5b..b4c32f2
+Fast\-forward
+ cookbooks/getting\-started/README.rdoc              |    4 +++
+ cookbooks/getting\-started/attributes/default.rb    |    1 +
+ cookbooks/getting\-started/metadata.json            |   29 ++++++++++++++++++++
+ cookbooks/getting\-started/metadata.rb              |    6 ++++
+ cookbooks/getting\-started/recipes/default.rb       |   23 +++++++++++++++
+ .../templates/default/chef\-getting\-started.txt.erb |    5 +++
+ 6 files changed, 68 insertions(+), 0 deletions(\-)
+ create mode 100644 cookbooks/getting\-started/README.rdoc
+ create mode 100644 cookbooks/getting\-started/attributes/default.rb
+ create mode 100644 cookbooks/getting\-started/metadata.json
+ create mode 100644 cookbooks/getting\-started/metadata.rb
+ create mode 100644 cookbooks/getting\-started/recipes/default.rb
+ create mode 100644 cookbooks/getting\-started/templates/default/chef\-getting\-started.txt.erb
+Cookbook getting\-started version 0.3.0 successfully installed
+.ft P
+.fi
+.SH LIST
+.sp
+The \fBlist\fP argument is used to view a list of cookbooks that are currently available at \fI\%https://cookbooks.opscode.com\fP.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook site list
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-w\fP, \fB\-\-with\-uri\fP
+Indicates that the corresponding URIs will be shown.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To view a list of cookbooks at \fI\%https://cookbooks.opscode.com\fP server, enter:
+.sp
+.nf
+.ft C
+$ knife cookbook site list
+.ft P
+.fi
+.sp
+to return:
+.sp
+.nf
+.ft C
+1password             homesick              rabbitmq
+7\-zip                 hostname              rabbitmq\-management
+AmazonEC2Tag          hosts                 rabbitmq_chef
+R                     hosts\-awareness       rackspaceknife
+accounts              htop                  radiant
+ack\-grep              hudson                rails
+activemq              icinga                rails_enterprise
+ad                    id3lib                redis\-package
+ad\-likewise           iftop                 redis2
+ant                   iis                   redmine
+[...truncated...]
+.ft P
+.fi
+.SH SEARCH
+.sp
+The \fBsearch\fP argument is used to search for a cookbook at \fI\%https://cookbooks.opscode.com\fP. A search query is used to return a list of cookbooks at \fI\%https://cookbooks.opscode.com\fP and uses the same syntax as the \fBknife search\fP sub\-command.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook site search SEARCH_QUERY (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This command does not have any specific options.
+.sp
+\fBExamples\fP
+.sp
+To search for all of the cookbooks that can be used with Apache, enter:
+.sp
+.nf
+.ft C
+$ knife cookbook site search apache*
+.ft P
+.fi
+.sp
+to return something like:
+.sp
+.nf
+.ft C
+apache2:
+  cookbook:              http://cookbooks.opscode.com/api/v1/cookbooks/apache2
+  cookbook_description:  Installs and configures apache2 using Debian symlinks with helper definitions
+  cookbook_maintainer:   opscode
+  cookbook_name:         apache2
+instiki:
+  cookbook:              http://cookbooks.opscode.com/api/v1/cookbooks/instiki
+  cookbook_description:  Installs instiki, a Ruby on Rails wiki server under passenger+Apache2.
+  cookbook_maintainer:   jtimberman
+  cookbook_name:         instiki
+kickstart:
+  cookbook:              http://cookbooks.opscode.com/api/v1/cookbooks/kickstart
+  cookbook_description:  Creates apache2 vhost and serves a kickstart file.
+  cookbook_maintainer:   opscode
+  cookbook_name:         kickstart
+[...truncated...]
+.ft P
+.fi
+.SH SHARE
+.sp
+The \fBshare\fP argument is used to add a cookbook to \fI\%https://cookbooks.opscode.com\fP. This action will require a user account and a certificate for \fI\%http://community.opscode.com\fP. By default, Knife will use the user name and API key that is identified in the configuration file used during the upload; otherwise these values must be specified on the command line or in an alternate configuration file. If a cookbook already exists on \fI\%https://cookbooks.opscode.com\fP, then only an owner or maintainer of that cookbook can make updates.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook site share COOKBOOK_NAME CATEGORY (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fBCATEGORY\fP
+The cookbook category: \fBDatabases\fP, \fBWeb Servers\fP, \fBProcess Management\fP, \fBMonitoring and Trending\fP, \fBProgramming Languages\fP, \fBPackage Management\fP, \fBApplications\fP, \fBNetworking\fP, \fBOperations Systems and Virtualization\fP, \fBUtilities\fP, or \fBOther\fP.
+.TP
+.B \fB\-o PATH:PATH\fP, \fB\-\-cookbook\-path PATH:PATH\fP
+The directory in which cookbook are created. This can be a colon\-separated path.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To share a cookbook named "apache2":
+.sp
+.nf
+.ft C
+$ knife cookbook site share "apache2" "Web Servers"
+.ft P
+.fi
+.SH SHOW
+.sp
+The \fBshow\fP argument is used to view information about a cookbook on \fI\%https://cookbooks.opscode.com\fP.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook site show COOKBOOK_NAME [COOKBOOK_VERSION]
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fBCOOKBOOK_VERSION\fP
+The version of a cookbook to be shown. If a cookbook has only one version, this option does not need to be specified. If a cookbook has more than one version and this option is not specified, a list of cookbook versions will be returned.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To show the details for a cookbook named "haproxy":
+.sp
+.nf
+.ft C
+$ knife cookbook site show haproxy
+.ft P
+.fi
+.sp
+to return something like:
+.sp
+.nf
+.ft C
+average_rating:
+category:        Networking
+created_at:      2009\-10\-25T23:51:07Z
+description:     Installs and configures haproxy
+external_url:
+latest_version:  http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_3
+maintainer:      opscode
+name:            haproxy
+updated_at:      2011\-06\-30T21:53:25Z
+versions:
+   http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_3
+   http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_2
+   http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_1
+   http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_0
+   http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/0_8_1
+   http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/0_8_0
+   http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/0_7_0
+.ft P
+.fi
+.sp
+To view information in JSON format, use the \fB\-F\fP common option as part of the command like this:
+.sp
+.nf
+.ft C
+$ knife role show devops \-F json
+.ft P
+.fi
+.sp
+Other formats available include \fBtext\fP, \fByaml\fP, and \fBpp\fP.
+.SH UNSHARE
+.sp
+The \fBunshare\fP argument is used to stop the sharing of a cookbook at \fI\%https://cookbooks.opscode.com\fP. Only the maintainer of a cookbook may perform this action.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook site unshare COOKBOOK_NAME
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This command does not have any specific options.
+.sp
+\fBExamples\fP
+.sp
+To unshare a cookbook named "getting\-started", enter:
+.sp
+.nf
+.ft C
+$ knife cookbook site unshare getting\-started
+.ft P
+.fi
+.SH AUTHOR
+Opscode
+.\" Generated by docutils manpage writer.
 .
-.IP "" 0
-.
-.SH "SEE ALSO"
-\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\.
-.
-.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