diff options
| author | jamescott <jamescott@opscode.com> | 2013-10-18 12:59:08 -0700 |
|---|---|---|
| committer | sersut <serdar@opscode.com> | 2013-10-18 13:42:10 -0700 |
| commit | 957f369948268d00c071d30db0519354d560bfef (patch) | |
| tree | c944c7d309c9eeec04782ea5ecf7c30a42d17de6 | |
| parent | 16fbe1b5225abd6cfcf2c86f0f59fe7ae46ead45 (diff) | |
| download | chef-957f369948268d00c071d30db0519354d560bfef.tar.gz | |
Update the man pages for chef & knife.
33 files changed, 5512 insertions, 2402 deletions
diff --git a/distro/common/man/man1/chef-shell.1 b/distro/common/man/man1/chef-shell.1 index f18312af5b..d865ce52ae 100644 --- a/distro/common/man/man1/chef-shell.1 +++ b/distro/common/man/man1/chef-shell.1 @@ -1,220 +1,115 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 +.TH "CHEF-SHELL" "1" "Chef 11.8.0" "" "chef-shell" +.SH NAME +chef-shell \- The man page for the chef-shell command line tool. +. +.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 +chef\-shell is a recipe debugging tool that allows the use of breakpoints within recipes. chef\-shell runs as an Interactive Ruby (IRb) session. chef\-shell supports both recipe and attribute file syntax, as well as interactive debugging features. +.IP Note +chef\-shell is the new name for Shef as of Chef 11.x. chef\-shell is backwards compatible and aside from the name change, has the same set of functionality as with previous releases. +.RE +.sp +The chef\-shell executable can be run as a command\-line tool. +.SH MODES +.sp +chef\-shell is tool that allows Knife to be run using an Interactive Ruby (IRb) session. chef\-shell currently supports recipe and attribute file syntax, as well as interactive debugging features. chef\-shell has three run modes: +.TS +center; +|l|l|. +_ +T{ +Mode +T} T{ +Description +T} +_ +T{ +Standalone +T} T{ +No cookbooks are loaded, and the run list is empty. This mode is the default. +T} +_ +T{ +Solo +T} T{ +chef\-shell acts as a chef\-solo client. It attempts to load the chef\-solo configuration file and JSON attributes. If the JSON attributes set a run list, it will be honored. Cookbooks will be loaded in the same way that chef\-solo loads them. chef\-solo mode is activated with the \fB\-s\fP or \fB\-\-solo\fP command line option, and JSON attributes are specified in the same way as for chef\-solo, with \fB\-j /path/to/chef\-solo.json\fP. +T} +_ +T{ +Client +T} T{ +chef\-shell acts as a chef\-client. During startup, it reads the chef\-client configuration file and contacts the server to get attributes and cookbooks. The run list will be set in the same way as normal chef\-client runs. chef\-client mode is activated with the \fB\-z\fP or \fB\-\-client\fP options. You can also specify the configuration file with \fB\-c CONFIG\fP and the server URL with \fB\-S SERVER_URL\fP. +T} +_ +.TE +.SH OPTIONS +.sp +This command has the following syntax: +.sp +.nf +.ft C +chef\-shell OPTION VALUE OPTION VALUE ... +.ft P +.fi +.sp +This command has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-standalone\fP +Indicates that chef\-shell will be run in standalone mode. +.TP +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. +.TP +.B \fB\-h\fP, \fB\-\-help\fP +Shows help for the command. +.TP +.B \fB\-j PATH\fP, \fB\-\-json\-attributes PATH\fP +The path to a file that contains JSON data. Use this option to override attributes that are set from other locations, such as from within a cookbook or by a role. +.TP +.B \fB\-l LEVEL\fP, \fB\-\-log_level LEVEL\fP +The level of logging that will be stored in a log file: \fBdebug\fP, \fBinfo\fP, \fBwarn\fP, \fBerror\fP, or \fBfatal\fP. +.TP +.B \fB\-s\fP, \fB\-\-solo\fP +Indicates that chef\-shell will be run in chef\-solo mode. +.TP +.B \fB\-S CHEF_SERVER_URL\fP, \fB\-\-server CHEF_SERVER_URL\fP +The URL for the server. +.TP +.B \fB\-v\fP, \fB\-\-version\fP +The version of the chef\-client. +.TP +.B \fB\-z\fP, \fB\-\-client\fP +Indicates that chef\-shell will be run in chef\-client mode. +.UNINDENT +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.TH "CHEF\-SHELL" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBchef\-shell\fR \- Interactive Chef Console -. -.SH "SYNOPSIS" -\fBchef\-shell\fR [\fInamed configuration\fR] \fI(options)\fR -. -.TP -\fB\-S\fR, \fB\-\-server CHEF_SERVER_URL\fR -The chef server URL -. -.TP -\fB\-z\fR, \fB\-\-client\fR -chef\-client mode -. -.TP -\fB\-c\fR, \fB\-\-config CONFIG\fR -The configuration file to use -. -.TP -\fB\-j\fR, \fB\-\-json\-attributes JSON_ATTRIBS\fR -Load attributes from a JSON file or URL -. -.TP -\fB\-l\fR, \fB\-\-log\-level LOG_LEVEL\fR -Set the logging level -. -.TP -\fB\-s\fR, \fB\-\-solo\fR -chef\-solo session -. -.TP -\fB\-a\fR, \fB\-\-standalone\fR -standalone session -. -.TP -\fB\-v\fR, \fB\-\-version\fR -Show chef version -. -.TP -\fB\-h\fR, \fB\-\-help\fR -Show command options -. -.P -When no \-\-config option is specified, chef\-shell attempts to load a default configuration file: -. -.IP "\(bu" 4 -If a \fInamed configuration\fR is given, chef\-shell will load ~/\.chef/\fInamed configuration\fR/chef_shell\.rb -. -.IP "\(bu" 4 -If no \fInamed configuration\fR is given chef\-shell will load ~/\.chef/chef_shell\.rb if it exists -. -.IP "\(bu" 4 -chef\-shell falls back to loading /etc/chef/client\.rb or /etc/chef/solo\.rb if \-z or \-s options are given and no chef_shell\.rb can be found\. -. -.IP "\(bu" 4 -The \-\-config option takes precedence over implicit configuration paths\. -. -.IP "" 0 -. -.SH "DESCRIPTION" -\fBchef\-shell\fR is an irb(1) (interactive ruby) session customized for Chef\. \fBchef\-shell\fR serves two primary functions: it provides a means to interact with a Chef Server interactively using a convenient DSL; it allows you to define and run Chef recipes interactively\. -. -.SH "SYNTAX" -chef\-shell uses irb\'s subsession feature to provide multiple modes of interaction\. In addition to the primary mode which is entered on start, \fBrecipe\fR and \fBattributes\fR modes are available\. -. -.SH "PRIMARY MODE" -The following commands are available in the primary session: -. -.TP -\fBhelp\fR -Prints a list of available commands -. -.TP -\fBversion\fR -Prints the Chef version -. -.TP -\fBrecipe\fR -Switches to \fBrecipe\fR mode -. -.TP -\fBattributes\fR -Switches to \fBattributes\fR mode -. -.TP -\fBrun_chef\fR -Initiates a chef run -. -.TP -\fBreset\fR -reinitializes chef\-shell session -. -.TP -\fBecho :on|:off\fR -Turns irb\'s echo function on or off\. Echo is \fIon\fR by default\. -. -.TP -\fBtracing :on|:off\fR -Turns irb\'s function tracing feature on or off\. Tracing is extremely verbose and expected to be of interest primarily to developers\. -. -.TP -\fBnode\fR -Returns the \fInode\fR object for the current host\. See knife\-node(1) for more information about nodes\. -. -.TP -\fBohai\fR -Prints the attributes of \fInode\fR -. -.P -In addition to these commands, chef\-shell provides a DSL for accessing data on the Chef Server\. When working with remote data in chef\-shell, you chain method calls in the form \fIobject type\fR\.\fIoperation\fR, where \fIobject type\fR is in plural form\. The following object types are available: -. -.IP "\(bu" 4 -\fBnodes\fR -. -.IP "\(bu" 4 -\fBroles\fR -. -.IP "\(bu" 4 -\fBdata_bags\fR -. -.IP "\(bu" 4 -\fBclients\fR -. -.IP "\(bu" 4 -\fBcookbooks\fR -. -.IP "" 0 -. -.P -For each \fIobject type\fR the following operations are available: -. -.TP -\fIobject type\fR\.all(\fI&block\fR) -Loads all items from the server\. If the optional code \fIblock\fR is given, each item will be passed to the block and the results returned, similar to ruby\'s \fBEnumerable#map\fR method\. -. -.TP -\fIobject type\fR\.show(\fIobject name\fR) -Aliased as \fIobject type\fR\.load -. -.IP -Loads the singular item identified by \fIobject name\fR\. -. -.TP -\fIobject type\fR\.search(\fIquery\fR, \fI&block\fR) -Aliased as \fIobject type\fR\.find -. -.IP -Runs a search against the server and returns the matching items\. If the optional code \fIblock\fR is given each item will be passed to the block and the results returned\. -. -.IP -The \fIquery\fR may be a Solr/Lucene format query given as a String, or a Hash of conditions\. If a Hash is given, the options will be ANDed together\. To join conditions with OR, use negative queries, or any advanced search syntax, you must provide give the query in String form\. -. -.TP -\fIobject type\fR\.transform(:all|\fIquery\fR, \fI&block\fR) -Aliased as \fIobject type\fR\.bulk_edit -. -.IP -Bulk edit objects by processing them with the (required) code \fIblock\fR\. You can edit all objects of the given type by passing the Symbol \fB:all\fR as the argument, or only a subset by passing a \fIquery\fR as the argument\. The \fIquery\fR is evaluated in the same way as with \fBsearch\fR\. -. -.IP -The return value of the code \fIblock\fR is used to alter the behavior of \fBtransform\fR\. If the value returned from the block is \fBnil\fR or \fBfalse\fR, the object will not be saved\. Otherwise, the object is saved after being passed to the block\. This behavior can be exploited to create a dry run to test a data transformation\. -. -.SH "RECIPE MODE" -Recipe mode implements Chef\'s recipe DSL\. Exhaustively documenting this DSL is outside the scope of this document\. See the following pages in the Chef documentation for more information: -. -.IP "\(bu" 4 -\fIhttp://wiki\.opscode\.com/display/chef/Resources\fR -. -.IP "\(bu" 4 -\fIhttp://wiki\.opscode\.com/display/chef/Recipes\fR -. -.IP "" 0 -. -.P -Once you have defined resources in the recipe, you can trigger a convergence run via \fBrun_chef\fR -. -.SH "EXAMPLES" -. -.IP "\(bu" 4 -A "Hello World" interactive recipe -. -.IP -chef > recipe chef:recipe > echo :off chef:recipe > file "/tmp/hello_world" chef:recipe > run_chef [Sat, 09 Apr 2011 08:56:56 \-0700] INFO: Processing file[/tmp/hello_world] action create ((irb#1) line 2) [Sat, 09 Apr 2011 08:56:56 \-0700] INFO: file[/tmp/hello_world] created file /tmp/hello_world chef:recipe > pp ls \'/tmp\' ["\.", "\.\.", "hello_world"] -. -.IP "\(bu" 4 -Search for \fInodes\fR by role, and print their IP addresses -. -.IP -chef > nodes\.find(:roles => \'monitoring\-server\') {|n| n[:ipaddress] } => ["10\.254\.199\.5"] -. -.IP "\(bu" 4 -Remove the role \fIobsolete\fR from every node in the system -. -.IP -chef > nodes\.transform(:all) {|n| n\.run_list\.delete(\'role[obsolete]\') } => [node[chef098b2\.opschef\.com], node[ree\-woot], node[graphite\-dev], node[fluke\.localdomain], node[ghost\.local], node[kallistec]] -. -.IP "" 0 -. -.SH "BUGS" -\fBchef\-shell\fR often does not perfectly replicate the context in which chef\-client(8) configures a host, which may lead to discrepancies in observed behavior\. -. -.P -\fBchef\-shell\fR has to duplicate much code from chef\-client\'s internal libraries and may become out of sync with the behavior of those libraries\. -. -.SH "SEE ALSO" -chef\-client(8) knife(1) \fIhttp://wiki\.opscode\.com/display/chef/Chef+Shell\fR -. -.SH "AUTHOR" -Chef was written by Adam Jacob \fIadam@opscode\.com\fR with many contributions from the community\. chef\-shell was written by Daniel DeLeo\. -. -.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" -chef\-shell is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR diff --git a/distro/common/man/man1/knife-bootstrap.1 b/distro/common/man/man1/knife-bootstrap.1 index 796b3e3172..b62031e6d8 100644 --- a/distro/common/man/man1/knife-bootstrap.1 +++ b/distro/common/man/man1/knife-bootstrap.1 @@ -1,201 +1,197 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-BOOTSTRAP" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\-bootstrap\fR \- Install Chef Client on a remote host -. -.SH "SYNOPSIS" -\fBknife\fR \fBbootstrap\fR \fI(options)\fR -. +.TH "KNIFE-BOOTSTRAP" "1" "Chef 11.8.0" "" "knife bootstrap" +.SH NAME +knife-bootstrap \- The man page for the knife bootstrap 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 +A bootstrap is a process that installs the chef\-client on a target system so that it can run as a chef\-client and communicate with a server. +.sp +The \fBknife bootstrap\fP subcommand is used run a bootstrap operation that installs the chef\-client on the target system. The bootstrap operation must specify the IP address or FQDN of the target system. +.IP Note +To bootstrap the chef\-client on Microsoft Windows machines, the \fI\%knife-windows\fP plugins is required, which includes the necessary bootstrap scripts that are used to do the actual installation. +.RE +.sp +\fBCommon Options\fP +.sp +The following options can be run with all Knife sub\-commands and plug\-ins: +.INDENT 0.0 .TP -\fB\-i\fR, \fB\-\-identity\-file IDENTITY_FILE\fR -The SSH identity file used for authentication -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-N\fR, \fB\-\-node\-name NAME\fR -The Chef node name for your new node -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -\fB\-P\fR, \fB\-\-ssh\-password PASSWORD\fR -The ssh password -. +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. .TP -\fB\-x\fR, \fB\-\-ssh\-user USERNAME\fR -The ssh username -. +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. .TP -\fB\-p\fR, \fB\-\-ssh\-port PORT\fR -The ssh port -. +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. .TP -\fB\-\-bootstrap\-version VERSION\fR -The version of Chef to install -. +.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\-\-bootstrap\-proxy PROXY_URL\fR -\fBThe proxy server for the node being bootstrapped\fR -. +.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\-\-prerelease\fR -Install pre\-release Chef gems -. +.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\-r\fR, \fB\-\-run\-list RUN_LIST\fR -Comma separated list of roles/recipes to apply -. +.B \fB\-h\fP, \fB\-\-help\fP +Shows help for the command. .TP -\fB\-\-template\-file TEMPLATE\fR -Full path to location of template to use -. +.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 -\fB\-\-sudo\fR -Execute the bootstrap via sudo -. +.B \fB\-\-no\-color\fP +Indicates that color will not be used in the output. .TP -\fB\-d\fR, \fB\-\-distro DISTRO\fR -Bootstrap a distro using a template -. +.B \fB\-p PASSWORD\fP, \fB\-\-password PASSWORD\fP +The user password. .TP -\fB\-\-[no\-]host\-key\-verify\fR -Enable host key verification, which is the default behavior\. -. +.B \fB\-\-print\-after\fP +Indicates that data will be shown after a destructive operation. .TP -\fB\-\-hint HINT_NAME[=HINT_FILE]\fR -Provide the name of a hint (with option JSON file) to set for use by Ohai plugins\. -. -.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 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: -. -.IP "\(bu" 4 -\fBbootstrap\fR directory in the installed Chef Knife library\. -. -.IP "\(bu" 4 -\fBbootstrap\fR directory in the \fB$PWD/\.chef\fR\. -. -.IP "\(bu" 4 -\fBbootstrap\fR directory in the users \fB$HOME/\.chef\fR\. -. -.IP "" 0 -. -.P -The default bootstrap templates are scripts that get copied to the target node (FQDN)\. The following distros are supported: -. -.IP "\(bu" 4 -centos5\-gems -. -.IP "\(bu" 4 -fedora13\-gems -. -.IP "\(bu" 4 -ubuntu10\.04\-gems -. -.IP "\(bu" 4 -ubuntu10\.04\-apt -. -.IP "" 0 -. -.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\. -. -.P -In addition to handling the software installation, these bootstrap templates do the following: -. -.IP "\(bu" 4 -Write the validation\.pem per the local knife configuration\. -. -.IP "\(bu" 4 -Write a default config file for Chef (\fB/etc/chef/client\.rb\fR) using values from the \fBknife\.rb\fR\. -. -.IP "\(bu" 4 -Create a JSON attributes file containing the specified run list and run Chef\. -. -.IP "" 0 -. -.P -In the case of the RubyGems, the \fBclient\.rb\fR will be written from scratch with a minimal set of values; see \fBEXAMPLES\fR\. In the case of APT Package installation, \fBclient\.rb\fR will have the \fBvalidation_client_name\fR appended if it is not set to \fBchef\-validator\fR (default config value), and the \fBnode_name\fR will be added if \fBchef_node_name\fR option is specified\. -. -.P -When this is complete, the bootstrapped node will have: -. -.IP "\(bu" 4 -Latest Chef version installed from RubyGems or APT Packages from Opscode\. This may be a later version than the local system\. -. -.IP "\(bu" 4 -Be validated with the configured Chef Server\. -. -.IP "\(bu" 4 -Have run Chef with its default run list if one is specfied\. -. -.IP "" 0 -. -.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 -. +.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 +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp .nf - -mkdir ~/\.chef/bootstrap -vi ~/\.chef/bootstrap/debian5\.0\-apt\.erb -. +.ft C +$ knife bootstrap FQDN_or_IP_ADDRESS (options) +.ft P .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 -. +.sp +\fBOptions\fP +.sp +This subcommand has the following options: +.INDENT 0.0 +.TP +.B \fB\-A\fP, \fB\-\-forward\-agent\fP +Indicates that SSH agent forwarding is enabled. +.TP +.B \fB\-\-bootstrap\-proxy PROXY_URL\fP +The proxy server for the node that is the target of a bootstrap operation. +.TP +.B \fB\-\-bootstrap\-version VERSION\fP +The version of the chef\-client to install. +.TP +.B \fB\-d DISTRO\fP, \fB\-\-distro DISTRO\fP +The template file to be used during a bootstrap operation. The following distributions are supported: \fBchef\-full\fP (the default bootstrap), \fBcentos5\-gems\fP, \fBfedora13\-gems\fP, \fBubuntu10.04\-gems\fP, \fBubuntu10.04\-apt\fP, \fBubuntu12.04\-gems\fP, and the name of a custom bootstrap template file. When this option is used, Knife will search for the template file in the following order: the \fBbootstrap/\fP folder in the current working directory, the \fBbootstrap/\fP folder in the chef\-repo, the \fBbootstrap/\fP folder in the \fB~/.chef/\fP directory, or a default bootstrap file. Do not use the \fB\-\-template\-file\fP option when \fB\-\-distro\fP is specified. +.TP +.B \fB\-G GATEWAY\fP, \fB\-\-ssh\-gateway GATEWAY\fP +The SSH tunnel or gateway that is used to run a bootstrap action on a machine that is not accessible from the workstation. +.TP +.B \fB\-\-hint HINT_NAME[=HINT_FILE]\fP +An Ohai hint to be set on the target of the bootstrap. The hint is contained in a file and is formatted as JSON: \fB{"attribute":"value","attribute":"value"...}\fP. \fBHINT_NAME\fP is the name of the hint and \fBHINT_FILE\fP is the name of the hint file located at \fB/etc/chef/ohai/hints/HINT_FILE.json\fP. Use multiple \fB\-\-hint\fP options in the command to specify multiple hints. +.TP +.B \fB\-i IDENTITY_FILE\fP, \fB\-\-identity\-file IDENTITY_FILE\fP +The SSH identity file used for authentication. Key\-based authentication is recommended. +.TP +.B \fB\-j JSON_ATTRIBS\fP, \fB\-\-json\-attributes JSON_ATTRIBS\fP +A JSON string that is added to the first run of a chef\-client. +.TP +.B \fB\-N NAME\fP, \fB\-\-node\-name NAME\fP +The name of the node. +.TP +.B \fB\-\-[no\-]host\-key\-verify\fP +Use \fB\-\-no\-host\-key\-verify\fP to disable host key verification. Default setting: \fB\-\-host\-key\-verify\fP. +.TP +.B \fB\-p PORT\fP, \fB\-\-ssh\-port PORT\fP +The SSH port. +.TP +.B \fB\-P PASSWORD\fP, \fB\-\-ssh\-password PASSWORD\fP +The SSH password. This can be used to pass the password directly on the command line. If this option is not specified (and a password is required) Knife will prompt for the password. +.TP +.B \fB\-\-prerelease\fP +Indicates that pre\-release gems should be installed. +.TP +.B \fB\-r RUN_LIST\fP, \fB\-\-run\-list RUN_LIST\fP +A comma\-separated list of roles and/or recipes to be applied. +.TP +.B \fB\-\-secret SECRET\fP +The encryption key that is used for values contained within a data bag. +.TP +.B \fB\-\-secret\-file FILE\fP +The path to the file that contains the encryption key. +.TP +.B \fB\-\-sudo\fP +Indicates that a bootstrap operation should be executed using sudo. +.TP +.B \fB\-\-template\-file TEMPLATE\fP +The path to a template file that will be used during a bootstrap operation. Do not use the \fB\-\-distro\fP option when \fB\-\-template\-file\fP is specified. +.TP +.B \fB\-\-use\-sudo\-password\fP +Indicates that a bootstrap operation is done using sudo, with the password specified by the \fB\-P\fP (or \fB\-\-ssh\-password\fP) option. +.TP +.B \fB\-x USERNAME\fP, \fB\-\-ssh\-user USERNAME\fP +The SSH user name. +.UNINDENT +.sp +\fBExamples\fP +.sp +To pass an SSH password as part of the command: +.sp .nf - -knife bootstrap mynode\.example\.com \-\-template\-file ~/\.chef/bootstrap/debian5\.0\-apt\.erb -. +.ft C +$ knife bootstrap 192.168.1.1 \-x username \-P PASSWORD \-\-sudo +.ft P .fi -. -.IP "" 0 -. -.P -Or, -. -.IP "" 4 -. +.sp +To use a file that contains a private key: +.sp .nf - -knife bootstrap mynode\.example\.com \-\-distro debian5\.0\-apt -. +.ft C +$ knife bootstrap 192.168.1.1 \-x username \-i ~/.ssh/id_rsa \-\-sudo +.ft P .fi +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.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) -. -.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/distro/common/man/man1/knife-client.1 b/distro/common/man/man1/knife-client.1 index 20db3ebe93..79d433dce9 100644 --- a/distro/common/man/man1/knife-client.1 +++ b/distro/common/man/man1/knife-client.1 @@ -1,99 +1,368 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 +.TH "KNIFE-CLIENT" "1" "Chef 11.8.0" "" "knife client" +.SH NAME +knife-client \- The man page for the knife client subcommand. . -.TH "KNIFE\-CLIENT" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" +.nr rst2man-indent-level 0 . -.SH "NAME" -\fBknife\-client\fR \- Manage Chef API Clients -. -.SH "SYNOPSIS" -\fBknife\fR \fBclient\fR \fIsub\-command\fR \fI(options)\fR -. -.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 -. -.P -Delete clients where the client name matches the regular expression \fIregex\fR on the Chef Server\. The regular expression should be given as a quoted string, and not surrounded by forward slashes\. -. -.SH "CREATE" -\fBknife client create\fR \fIclient name\fR \fI(options)\fR +.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 +When a node runs the chef\-client for the first time, it generally does not yet have an API client identity, and so it cannot make authenticated requests to the server. This is where the validation client\-\-\-known as the chef\-validator\-\-\-comes in. When the chef\-client runs, it checks if it has a client key. If the client key does not exist, it then attempts to borrow the identity of the chef\-validator to register itself with the server. In order to register with the server, the private key for the chef\-validator needs to be copied to the host and placed in /etc/chef/validation.pem. +.sp +Once the chef\-client has registered itself with the server, it no longer uses the validation client for anything. It is recommended that you delete the private key for the chef\-validator from the host after the host has registered or use the \fBdelete_validation\fP recipe that can be found in the \fBchef\-client\fP cookbook (\fI\%https://github.com/opscode-cookbooks/chef-client\fP). +.sp +The \fBknife client\fP subcommand is used to manage an API client list and their associated RSA public key\-pairs. This allows authentication requests to be made to the server by any entity that uses the Chef Server API, such as the chef\-client and Knife. +.sp +This subcommand has the following syntax: +.sp +.nf +.ft C +$ knife client [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\-a\fR, \fB\-\-admin\fR -Create the client as an admin -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-f\fR, \fB\-\-file FILE\fR -Write the key to a file -. -.P -Create a new client\. This generates an RSA keypair\. The private key will be displayed on \fISTDOUT\fR or written to the named file\. The public half will be stored on the Server\. For \fIchef\-client\fR systems, the private key should be copied to the system as \fB/etc/chef/client\.pem\fR\. -. -.P -Admin clients should be created for users that will use \fIknife\fR to access the API as an administrator\. The private key will generally be copied to \fB~/\.chef/client\e_name\.pem\fR and referenced in the \fBknife\.rb\fR configuration file\. -. -.SH "DELETE" -\fBknife client delete\fR \fIclient name\fR \fI(options)\fR -. -.P -Deletes a registered client\. -. -.SH "EDIT" -\fBclient edit\fR \fIclient name\fR \fI(options)\fR -. -.P -Edit a registered client\. -. -.SH "LIST" -\fBclient list\fR \fI(options)\fR -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -\fB\-w\fR, \fB\-\-with\-uri\fR -Show corresponding URIs -. -.P -List all registered clients\. -. -.SH "REREGISTER" -\fBclient reregister\fR \fIclient name\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 -Write the key to a file -. -.P -Regenerate the RSA keypair for a client\. The public half will be stored on the server and the private key displayed on \fISTDOUT\fR or written to the named file\. This operation will invalidate the previous keypair used by the client, preventing it from authenticating with the Chef Server\. Use care when reregistering the validator client\. -. -.SH "SHOW" -\fBclient show\fR \fIclient name\fR \fI(options)\fR -. +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. .TP -\fB\-a\fR, \fB\-\-attribute ATTR\fR -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) -. -.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\. +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. +.TP +.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 +.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 +.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 +.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 BULK DELETE +.sp +The \fBbulk delete\fP argument is used to delete any API client that matches a pattern defined by a regular expression. The regular expression must be within quotes and not be surrounded by forward slashes (/). +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife client bulk delete REGEX +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.SH CREATE +.sp +The \fBcreate\fP argument is used to create a new API client. This process will generate an RSA key pair for the named API client. The public key will be stored on the server and the private key will be displayed on \fBSTDOUT\fP or written to a named file. +.INDENT 0.0 +.IP \(bu 2 +For the chef\-client, the private key should be copied to the system as /etc/chef/client.pem. +.IP \(bu 2 +For Knife, the private key is typically copied to ~/.chef/client_name.pem and referenced in the knife.rb configuration file. +.UNINDENT +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife client create CLIENT_NAME (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-admin\fP +Indicates that a client will be created as an admin client. This is required when users of the open source server need to access the Chef Server API as an administrator. This option only works when used with the open source server and will have no effect when used with Hosted Chef or Private Chef. +.UNINDENT +.sp +\fBExamples\fP +.sp +To create a Chef Admin client with the name "exampleorg" and save its private key to a file, enter: +.sp +.nf +.ft C +$ knife client create exampleorg \-a \-f "/etc/chef/client.pem" +.ft P +.fi +.sp +When running the \fBcreate\fP argument on Hosted Chef or Private Chef, be sure to omit the \fB\-a\fP option: +.sp +.nf +.ft C +$ knife client create exampleorg \-f "/etc/chef/client.pem" +.ft P +.fi +.SH DELETE +.sp +The \fBdelete\fP argument is used to delete a registered API client. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife client delete CLIENT_NAME +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To delete a client with the name "client_foo", enter: +.sp +.nf +.ft C +$ knife client delete client_foo +.ft P +.fi +.sp +Type \fBY\fP to confirm a deletion. +.SH EDIT +.sp +The \fBedit\fP argument is used to edit the details of a registered API client. When this argument is run, Knife will open $EDITOR to enable editing of the \fBadmin\fP attribute. (None of the other attributes should be changed using this argument.) When finished, Knife will update the server with those changes. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife client edit CLIENT_NAME +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To edit a client with the name "exampleorg", enter: +.sp +.nf +.ft C +$ knife client edit exampleorg +.ft P +.fi +.SH LIST +.sp +The \fBlist\fP argument is used to view a list of registered API client. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife client list (options) +.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 verify the API client list for the server, enter: +.sp +.nf +.ft C +$ knife client list +.ft P +.fi +.sp +to return something similar to: +.sp +.nf +.ft C +exampleorg +i\-12345678 +rs\-123456 +.ft P +.fi +.sp +To verify that an API client can authenticate to the +server correctly, try getting a list of clients using \fB\-u\fP and \fB\-k\fP options to specify its name and private key: +.sp +.nf +.ft C +$ knife client list \-u ORGNAME \-k .chef/ORGNAME.pem +.ft P +.fi +.SH REREGISTER +.sp +The \fBreregister\fP argument is used to regenerate an RSA key pair for an API client. The public key will be stored on the server and the private key will be displayed on \fBSTDOUT\fP or written to a named file. +.IP Note +Running this argument will invalidate the previous RSA key pair, making it unusable during authentication to the server. +.RE +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife client reregister CLIENT_NAME (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-f FILE_NAME\fP, \fB\-\-file FILE_NAME\fP +Indicates that the private key will be saved to a specified file name. +.UNINDENT +.sp +\fBExamples\fP +.sp +To regenerate the RSA key pair for a client named "testclient" and save it to a file named "rsa_key", enter: +.sp +.nf +.ft C +$ knife client regenerate testclient \-f rsa_key +.ft P +.fi +.SH SHOW +.sp +The \fBshow\fP argument is used to show the details of an API client. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife client show CLIENT_NAME (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a ATTR\fP, \fB\-\-attribute ATTR\fP +The attribute (or attributes) to show. +.UNINDENT +.sp +\fBExamples\fP +.sp +To view a client named "testclient", enter: +.sp +.nf +.ft C +$ knife client show testclient +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +admin: false +chef_type: client +json_class: Chef::ApiClient +name: testclient +public_key: +.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 AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.SH "CHEF" -Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR diff --git a/distro/common/man/man1/knife-configure.1 b/distro/common/man/man1/knife-configure.1 index 20f3c78961..e06793e219 100644 --- a/distro/common/man/man1/knife-configure.1 +++ b/distro/common/man/man1/knife-configure.1 @@ -1,58 +1,150 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-CONFIGURE" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\-configure\fR \- Generate configuration files for knife or Chef Client -. -.SH "SYNOPSIS" -\fBknife\fR \fBconfigure\fR [client] \fI(options)\fR -. -.SH "DESCRIPTION" -Generates a knife\.rb configuration file interactively\. When given the \-\-initial option, also creates a new administrative user\. -. -.SH "CONFIGURE SUBCOMMANDS" -\fBknife configure\fR \fI(options)\fR -. +.TH "KNIFE-CONFIGURE" "1" "Chef 11.8.0" "" "knife configure" +.SH NAME +knife-configure \- The man page for the knife configure 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 \fBknife configure\fP subcommand is used to create the knife.rb and client.rb files so that they can be distributed to workstations and nodes. +.sp +\fBCommon Options\fP +.sp +The following options can be run with all Knife sub\-commands and plug\-ins: +.INDENT 0.0 .TP -\fB\-i\fR, \fB\-\-initial\fR -Create an initial API Client -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-r\fR, \fB\-\-repository REPO\fR -The path to your chef\-repo -. -.P -Create a configuration file for knife\. This will prompt for values to enter into the file\. Default values are listed in square brackets if no other entry is typed\. See \fBknife\fR(1) for a description of configuration options\. -. -.P -\fBknife configure client\fR \fIdirectory\fR -. -.P -Read the \fIknife\.rb\fR config file and generate a config file suitable for use in \fI/etc/chef/client\.rb\fR and copy the validation certificate into the specified \fIdirectory\fR\. -. -.SH "EXAMPLES" -. -.IP "\(bu" 4 -On a freshly installed Chef Server, use \fIknife configure \-i\fR to create an administrator and knife configuration file\. Leave the field blank to accept the default value\. On most systems, the default values are acceptable\. -. -.IP -user@host$ knife configure \-i Please enter the chef server URL: [http://localhost:4000] Please enter a clientname for the new client: [username] Please enter the existing admin clientname: [chef\-webui] Please enter the location of the existing admin client\'s private key: [/etc/chef/webui\.pem] Please enter the validation clientname: [chef\-validator] Please enter the location of the validation key: [/etc/chef/validation\.pem] Please enter the path to a chef repository (or leave blank): Creating initial API user\.\.\. Created (or updated) client[username] Configuration file written to /home/username/\.chef/knife\.rb -. -.IP -This creates a new administrator client named \fIusername\fR, writes a configuration file to \fI/home/username/\.chef/knife\.rb\fR, and the private key to \fI/home/username/\.chef/username\.pem\fR\. The configuration file and private key may be copied to another system to facilitate administration of the Chef Server from a remote system\. Depending on the value given for the Chef Server URL, you may need to modify that setting after copying to a remote host\. -. -.IP "" 0 -. -.SH "SEE ALSO" -\fBknife\fR(1) \fBknife\-client\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\. +.B \fB\-\-color\fP +Indicates that colored output will be used. +.TP +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. +.TP +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. +.TP +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. +.TP +.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 +.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 +.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 +.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 +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife configure (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This subcommand has the following options: +.INDENT 0.0 +.TP +.B \fB\-\-admin\-client\-name NAME\fP +The name of the client, typically the name of the admin client. +.TP +.B \fB\-\-admin\-client\-key PATH\fP +The path to the private key used by the client, typically a file named \fBadmin.pem\fP. +.TP +.B \fB\-i\fP, \fB\-\-initial\fP +Use to create a API client, typically an administrator client on a freshly\-installed server. +.TP +.B \fB\-r REPO\fP, \fB\-\-repository REPO\fP +The path to the chef\-repo. +.TP +.B \fB\-\-validation\-client\-name NAME\fP +The name of the validation client. +.TP +.B \fB\-\-validation\-key PATH\fP +The path to the validation key used by the client, typically a file named \fBvalidation.pem\fP. +.UNINDENT +.sp +\fBExamples\fP +.sp +To create a knife.rb file, enter: +.sp +.nf +.ft C +$ knife configure +.ft P +.fi +.sp +To configure a client.rb, enter: +.sp +.nf +.ft C +$ knife configure client \(aq/directory\(aq +.ft P +.fi +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.SH "CHEF" -Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR diff --git a/distro/common/man/man1/knife-cookbook-site.1 b/distro/common/man/man1/knife-cookbook-site.1 index 900f5bcd55..8a2b535333 100644 --- a/distro/common/man/man1/knife-cookbook-site.1 +++ b/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.10.0.alpha.0" "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 diff --git a/distro/common/man/man1/knife-cookbook.1 b/distro/common/man/man1/knife-cookbook.1 index 15d4516b4e..c9b4e807dc 100644 --- a/distro/common/man/man1/knife-cookbook.1 +++ b/distro/common/man/man1/knife-cookbook.1 @@ -1,332 +1,642 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-COOKBOOK" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\-cookbook\fR \- upload and manage chef cookbooks -. -.SH "SYNOPSIS" -\fBknife\fR \fBcookbook\fR \fIsub\-command\fR \fI(options)\fR -. -.SH "SUB\-COMMANDS" -\fBknife cookbook\fR supports the following sub commands: -. -.SH "LIST" -\fBknife cookbook list\fR \fI(options)\fR -. -.TP -\fB\-a\fR, \fB\-\-all\fR -show all versions of a cookbook instead of just the most recent -. -.TP -\fB\-w\fR, \fB\-\-with\-uri\fR -show corresponding uris -. -.P -Lists the cookbooks available on the Chef server\. -. -.SH "SHOW" -\fBknife cookbook show cookbook [version] [part] [filename]\fR \fI(options)\fR -. -.TP -\fB\-f\fR, \fB\-\-fqdn fqdn\fR -the fqdn of the host to see the file for -. -.TP -\fB\-p\fR, \fB\-\-platform platform\fR -the platform to see the file for -. -.TP -\fB\-v\fR, \fB\-\-platform\-version version\fR -the platform version to see the file for -. +.TH "KNIFE-COOKBOOK" "1" "Chef 11.8.0" "" "knife cookbook" +.SH NAME +knife-cookbook \- The man page for the knife cookbook 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 +A cookbook is the fundamental unit of configuration and policy distribution. Each cookbook defines a scenario, such as everything needed to install and configure MySQL, and then it contains all of the components that are required to support that scenario, including: +.INDENT 0.0 +.IP \(bu 2 +Attribute values that are set on nodes +.IP \(bu 2 +Definitions that allow the creation of reusable collections of resources +.IP \(bu 2 +File distributions +.IP \(bu 2 +Libraries that extend the chef\-client and/or provide helpers to Ruby code +.IP \(bu 2 +Recipes that specify which resources to manage and the order in which those resources will be applied +.IP \(bu 2 +Custom resources and providers +.IP \(bu 2 +Templates +.IP \(bu 2 +Versions +.IP \(bu 2 +Metadata about recipes (including dependencies), version constraints, supported platforms, and so on +.UNINDENT +.sp +The \fBknife cookbook\fP subcommand is used to interact with cookbooks that are located on the server or the local chef\-repo. +.sp +This subcommand has the following syntax: +.sp +.nf +.ft C +$ knife cookbook [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\-w\fR, \fB\-\-with\-uri\fR -Show corresponding URIs -. -.P -show a particular part of a \fIcookbook\fR for the specified \fIversion\fR\. \fIpart\fR can be one of: -. -.IP "\(bu" 4 -\fIattributes\fR -. -.IP "\(bu" 4 -\fIdefinitions\fR -. -.IP "\(bu" 4 -\fIfiles\fR -. -.IP "\(bu" 4 -\fIlibraries\fR -. -.IP "\(bu" 4 -\fIproviders\fR -. -.IP "\(bu" 4 -\fIrecipes\fR -. -.IP "\(bu" 4 -\fIresources\fR -. -.IP "\(bu" 4 -\fItemplates\fR -. -.IP "" 0 -. -.SH "UPLOAD" -\fBknife cookbook upload [cookbooks\.\.\.]\fR \fI(options)\fR -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-a\fR, \fB\-\-all\fR -upload all cookbooks, rather than just a single cookbook -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -\fB\-o\fR, \fB\-\-cookbook\-path path:path\fR -a colon\-separated path to look for cookbooks in -. +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. .TP -\fB\-d\fR, \fB\-\-upload\-dependencies\fR -Uploads additional cookbooks that this cookbook lists in as dependencies in its metadata\. -. +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. .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\. -. +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. .TP -\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\. -. +.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\-\-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 -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 -As the command parses the name args as 1\.\.n cookbook names: \fBknife cookbook upload COOKBOOK COOKBOOK \.\.\.\fR works for one to many cookbooks\. -. -.SH "DOWNLOAD" -\fBknife cookbook download cookbook [version]\fR \fI(options)\fR -. +.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\-d\fR, \fB\-\-dir download_directory\fR -the directory to download the cookbook into -. +.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\-f\fR, \fB\-\-force\fR -overwrite an existing directory with the download -. +.B \fB\-h\fP, \fB\-\-help\fP +Shows help for the command. .TP -\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\. -. -.SH "DELETE" -\fBknife cookbook delete cookbook [version]\fR \fI(options)\fR -. +.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 -\fB\-a\fR, \fB\-\-all\fR -delete all versions -. +.B \fB\-\-no\-color\fP +Indicates that color will not be used in the output. .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 -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\. -. -.SH "BULK DELETE" -\fBknife cookbook bulk delete regex\fR \fI(options)\fR -. +.B \fB\-p PASSWORD\fP, \fB\-\-password PASSWORD\fP +The user password. .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 -delete cookbooks on the chef server based on a regular expression\. the regular expression (\fIregex\fR) should be in quotes, not in //\'s\. -. -.SH "COOKBOOK CREATE" -\fBknife cookbook create cookbook\fR \fI(options)\fR -. +.B \fB\-\-print\-after\fP +Indicates that data will be shown after a destructive operation. .TP -\fB\-o\fR, \fB\-\-cookbook\-path path\fR -the directory where the cookbook will be created -. +.B \fB\-s URL\fP, \fB\-\-server\-url URL\fP +The URL for the server. .TP -\fB\-r\fR, \fB\-\-readme\-format format\fR -format of the readme file md, mkd, txt, rdoc -. +.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 -\fB\-C\fR, \fB\-\-copyright copyright\fR -name of copyright holder -. +.B \fB\-v\fP, \fB\-\-version\fP +The version of the chef\-client. .TP -\fB\-i\fR, \fB\-\-license license\fR -license for cookbook, apachev2 or none -. +.B \fB\-V\fP, \fB\-\-verbose\fP +Set for more verbose outputs. Use \fB\-VV\fP for maximum verbosity. .TP -\fB\-m\fR, \fB\-\-email email\fR -email address of cookbook maintainer -. -.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 +.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 BULK DELETE +.sp +The \fBbulk delete\fP argument is used to delete cookbook files that match a pattern defined by a regular expression. The regular expression must be within quotes and not be surrounded by forward slashes (/). +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife cookbook bulk delete REGEX (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-p\fP, \fB\-\-purge\fP +Indicates that a cookbook (or cookbook version) will be removed entirely from the server. This action should be used carefully because only one copy of any single file is stored on the server. Consequently, purging a cookbook will disable any other cookbook that references one or more files from a cookbook that has been purged. +.UNINDENT +.sp +\fBExamples\fP +.sp +To bulk delete many cookbooks, use a regular expression to define the pattern: +.sp +.nf +.ft C +$ knife cookbook bulk delete "^[0\-9]{3}$" \-p +.ft P +.fi +.SH CREATE +.sp +The \fBcreate\fP argument is used to create a new cookbook directory on the local machine, including the following directories and files: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 cookbook/attributes -. -.IP "\(bu" 4 +.IP \(bu 2 +cookbook/CHANGELOG.md +.IP \(bu 2 cookbook/definitions -. -.IP "\(bu" 4 +.IP \(bu 2 cookbook/files/default -. -.IP "\(bu" 4 +.IP \(bu 2 cookbook/libraries -. -.IP "\(bu" 4 -cookbook/metadata\.rb -. -.IP "\(bu" 4 +.IP \(bu 2 +cookbook/metadata.rb +.IP \(bu 2 cookbook/providers -. -.IP "\(bu" 4 -cookbook/readme\.md -. -.IP "\(bu" 4 -cookbook/recipes/default\.rb -. -.IP "\(bu" 4 +.IP \(bu 2 +cookbook/README.md (or .rdoc) +.IP \(bu 2 +cookbook/recipes/default.rb +.IP \(bu 2 cookbook/resources -. -.IP "\(bu" 4 +.IP \(bu 2 cookbook/templates/default -. -.IP "" 0 -. -.P -supported readme formats are \'md\' (default), \'mkd\', \'txt\', \'rdoc\'\. 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\-m\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, email and readme_format settings can be filled in the \fBknife\.rb\fR, for example with default values: -. -.IP "" 4 -. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +After the cookbook is created, it can be uploaded to the server using the \fBknife upload\fP argument. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp .nf - -cookbook_copyright "your_company_name" -cookbook_license "none" -cookbook_email "your_email" -readme_format "md" -. +.ft C +$ knife cookbook create COOKBOOK_NAME (options) +.ft P .fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-C COPYRIGHT_HOLDER\fP, \fB\-\-copyright COPYRIGHT_HOLDER\fP +The name of the copyright holder. This option will place a copyright notice that contains the name of the copyright holder in each of the pre\-created files. If this option is not specified, a copyright name of "your_company_name" will be used instead; it can be easily modified later. +.TP +.B \fB\-I LICENSE\fP, \fB\-\-license LICENSE\fP +The type of license under which a cookbook is distributed: \fBapachev2\fP, \fBgplv2\fP, \fBgplv3\fP, \fBmit\fP, or \fBnone\fP (default). This option will place the appropriate license notice in the pre\-created files. Be aware of the licenses for files inside of a cookbook and be sure to follow any restrictions they describe. +.TP +.B \fB\-m EMAIL\fP, \fB\-\-email EMAIL\fP +The email address for the individual who maintains the cookbook. This option will place an email address in each of the pre\-created files. If this option is not specified, an email name of "your_email" will be used instead; it can be easily modified later. +.TP +.B \fB\-o PATH\fP, \fB\-\-cookbook\-path PATH\fP +The directory in which cookbook are created. This can be a colon\-separated path. +.TP +.B \fB\-r FORMAT\fP, \fB\-\-readme\-format FORMAT\fP +The document format of the readme file: \fBmd\fP (markdown) and \fBrdoc\fP (Ruby docs). +.UNINDENT +.sp +\fBExamples\fP +.sp +To create a cookbook named "my_cookbook" with copyright, email, license, and readme format options specified, enter: +.sp +.nf +.ft C +$ knife cookbook create my_cookbook \-C "My Name" \-m "my@email.com" \-I apachev2 \-r md +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +** Creating cookbook my_cookbook +** Creating README for cookbook: my_cookbook +** Creating metadata for cookbook: my_cookbook +.ft P +.fi +.SH DELETE +.sp +The \fBdelete\fP argument is used to delete a specified cookbook or cookbook version on the server (and not locally). +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife cookbook delete COOKBOOK_NAME [COOKBOOK_VERSION] (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-all\fP +Indicates that a cookbook and every version of that cookbook will be deleted. +.TP +.B \fBCOOKBOOK_VERSION\fP +The version of a cookbook to be deleted. 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\-p\fP, \fB\-\-purge\fP +Indicates that a cookbook (or cookbook version) will be removed entirely from the server. This action should be used carefully because only one copy of any single file is stored on the server. Consequently, purging a cookbook will disable any other cookbook that references one or more files from a cookbook that has been purged. +.UNINDENT +.sp +\fBExamples\fP +.sp +To delete version "0.8" from a cookbook named "smartmon", enter: +.sp +.nf +.ft C +$ knife cookbook delete smartmon 0.8 +.ft P +.fi +.sp +Type \fBY\fP to confirm a deletion. +.SH DOWNLOAD +.sp +The \fBdownload\fP argument is used to download a cookbook from the server to the current working directory. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife cookbook download COOKBOOK_NAME [COOKBOOK_VERSION] (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-d DOWNLOAD_DIRECTORY\fP, \fB\-\-dir DOWNLOAD_DIRECTORY\fP +The directory into which a cookbook will be downloaded. +.TP +.B \fB\-f\fP, \fB\-\-force\fP +Indicates that an existing directory will be overwritten. +.TP +.B \fB\-N\fP, \fB\-\-latest\fP +Indicates that the most recent version of a cookbook will be downloaded. +.UNINDENT +.sp +\fBExamples\fP +.sp +To download a cookbook named "smartmon", enter: +.sp +.nf +.ft C +$ knife cookbook download smartmon +.ft P +.fi +.SH LIST +.sp +The \fBlist\fP argument is used to view a list of cookbooks that are currently available on the server. The list will contain only the most recent version for each cookbook by default. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife cookbook list (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-all\fP +Indicates that all available versions of each cookbook will be returned. +.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: +.sp +.nf +.ft C +$ knife cookbook list +.ft P +.fi +.SH METADATA +.sp +The \fBmetadata\fP argument is used to generate the metadata for one or more cookbooks. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife cookbook metadata (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-all\fP +Indicates that metadata should be generated for all cookbooks, and not just for a specified cookbook. +.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 generate metadata for all cookbooks: +.sp +.nf +.ft C +$ knife cookbook metadata \-a +.ft P +.fi +.SH METADATA FROM FILE +.sp +The \fBmetadata from file\fP argument is used to load the metadata for a cookbook from a file. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife cookbook metadata from file FILE +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To view cookbook metadata from a JSON file: +.sp +.nf +.ft C +$ knife cookbook metadta from file /path/to/file +.ft P +.fi +.SH SHOW +.sp +The \fBshow\fP argument is used to view information about a cookbook, parts of a cookbook (attributes, definitions, files, libraries, providers, recipes, resources, and templates), or a file that is associated with a cookbook (including attributes such as checksum or specificity). +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife cookbook show COOKBOOK_NAME [COOKBOOK_VERSION] [PART...] [FILE_NAME] (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 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. +.TP +.B \fB\-f FQDN\fP, \fB\-\-fqdn FQDN\fP +The FQDN of the host. +.TP +.B \fBFILE_NAME\fP +The name of a file that is associated with a cookbook. +.TP +.B \fB\-p PLATFORM\fP, \fB\-\-platform PLATFORM\fP +The platform for which a cookbook is designed. +.TP +.B \fBPART\fP +The part of the cookbook to show: \fBattributes\fP, \fBdefinitions\fP, \fBfiles\fP, \fBlibraries\fP, \fBproviders\fP, \fBrecipes\fP, \fBresources\fP, or \fBtemplates\fP. More than one part can be specified. +.TP +.B \fB\-V PLATFORM_VERSION\fP, \fB\-\-platform\-version PLATFORM_VERSION\fP +The version of the platform. +.TP +.B \fB\-w\fP, \fB\-\-with\-uri\fP +Indicates that the corresponding URIs will be shown. +.UNINDENT +.sp +\fBExamples\fP +.sp +To get the list of available versions of a cookbook named "getting\-started", enter: +.sp +.nf +.ft C +$ knife cookbook show getting\-started +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +getting\-started 0.3.0 0.2.0 +.ft P +.fi +.sp +To show a list of data about a cookbook using the name of the cookbook and the version, enter: +.sp +.nf +.ft C +$ knife cookbook show getting\-started 0.3.0 +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +attributes: + checksum: fa0fc4abf3f6787aeb5c3c5c35de667c + name: default.rb + path: attributes/default.rb + specificity: default + url: https://somelongurlhere.com +chef_type: cookbook_version +cookbook_name: getting\-started +definitions: [] +files: [] +frozen?: false +json_class: Chef::CookbookVersion +libraries: [] +.ft P +.fi +.sp +To only view data about "templates", enter: +.sp +.nf +.ft C +$ knife cookbook show getting\-started 0.3.0 templates +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +checksum: a29d6f254577b830091f140c3a78b1fe +name: chef\-getting\-started.txt.erb +path: templates/default/chef\-getting\-started.txt.erb +specificity: default +url: https://someurlhere.com +.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 TEST +.sp +The \fBtest\fP argument is used to test a cookbook for syntax errors. This argument uses Ruby syntax checking to verify every file in a cookbook that ends in .rb and Embedded Ruby (ERB). +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife cookbook test COOKBOOK_NAME (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-all\fP +Indicates that all cookbooks will be tested. +.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 test a cookbook named "getting\-started", enter: +.sp +.nf +.ft C +$ knife cookbook test getting\-started +.ft P +.fi +.SH UPLOAD +.sp +The \fBupload\fP argument is used to upload one or more cookbooks (and any files that are associated with those cookbooks) from a local repository to the server. Only files that do not already exist on the server will be uploaded. +.IP Note +Use a chefignore file to prevent the upload of specific files and file types, such as temporary files or files placed in folders by version control systems. The chefignore file must be located in the root of the cookbook repository and must use rules similar to filename globbing (as defined by the Ruby \fBFile.fnmatch\fP syntax). +.RE +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife cookbook upload [COOKBOOK_NAME...] (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-all\fP +Indicates that all cookbooks will be uploaded. +.TP +.B \fB\-d\fP, \fB\-\-include\-dependencies\fP +Indicates that when a cookbook has a dependency on one (or more) cookbooks, those cookbooks will also be uploaded. +.TP +.B \fB\-\-force\fP +Indicates that a cookbook should be updated even if the \fB\-\-freeze\fP flag has been set. +.TP +.B \fB\-\-freeze\fP +Indicates that a cookbook cannot be modified; any changes to this cookbook must be included as a new version. Only the \fB\-\-force\fP option can override this setting. +.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 upload a cookbook named "getting\-started": +.sp +.nf +.ft C +$ knife cookbook upload getting\-started +.ft P +.fi +.sp +To upload a cookbook, and then prevent other users from being able to make changes to it, enter: +.sp +.nf +.ft C +$ knife cookbook upload redis \-\-freeze +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +Uploading redis... +Upload completed +.ft P +.fi +.sp +If a cookbook is frozen and the \fB\-\-force\fP option is not specified, Knife will return an error message similar to the following: +.sp +.nf +.ft C +Uploading redis... +ERROR: Version 0.1.6 of cookbook redis is frozen. Use \-\-force to override. +.ft P +.fi +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.IP "" 0 -. -.SH "METADATA" -\fBknife cookbook metadata cookbook\fR \fI(options)\fR -. -.TP -\fB\-a\fR, \fB\-\-all\fR -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 -. -.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\. -. -.SH "METADATA FROM FILE" -\fBknife cookbook metadata from file\fR \fI(options)\fR -. -.P -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 -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 -. -.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)\. -. -.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/distro/common/man/man1/knife-data-bag.1 b/distro/common/man/man1/knife-data-bag.1 index 2872837052..b5fae1742a 100644 --- a/distro/common/man/man1/knife-data-bag.1 +++ b/distro/common/man/man1/knife-data-bag.1 @@ -1,123 +1,486 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-DATA\-BAG" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\-data\-bag\fR \- Store arbitrary data on a Chef Server -. -.SH "SYNOPSIS" -\fBknife\fR \fBdata bag\fR \fIsub\-command\fR \fI(options)\fR -. -.SH "DESCRIPTION" -Data bags are stores of arbitrary JSON data\. Each data bag is a collection that may contain many items\. Data Bag Items are indexed by the Chef Server and can be searched via \fBknife\-search\fR(1)\. -. -.P -Data bags are available to all nodes configured by \fBchef\-client\fR(8), and are therefore a convenient mechanism to store global information, such as lists of administrative accounts that should be configured on all hosts\. -. -.SH "DATA BAG SUB\-COMMANDS" -. -.SH "CREATE" -\fBknife data bag create\fR \fIbag name\fR [item id] \fI(options)\fR -. +.TH "KNIFE-DATA-BAG" "1" "Chef 11.8.0" "" "knife data bag" +.SH NAME +knife-data-bag \- The man page for the knife data bag 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 +A data bag is a global variable that is stored as JSON data and is accessible from a server. A data bag is indexed for searching and can be loaded by a recipe or accessed during a search. The contents of a data bag can vary, but they often include sensitive information (such as database passwords). +.sp +The contents of a data bag can be encrypted using \fI\%shared secret encryption\fP. This allows a data bag to store confidential information (such as a database password) or to be managed in a source control system (without plain\-text data appearing in revision history). +.sp +The \fBknife data bag\fP subcommand is used to manage arbitrary stores of globally available JSON data. +.sp +This subcommand has the following syntax: +.sp +.nf +.ft C +$ knife data bag [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\-s\fR, \fB\-\-secret SECRET\fR -A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-\-secret\-file SECRET_FILE\fR -The path to a file containing the secret key to be used to encrypt the data bag item\. -. -.P -If \fIitem id\fR is given, creates a new, empty data bag item and opens it for editing in your editor\. The data bag will be created if it does not exist\. -. -.P -If \fIitem id\fR is not given, the data bag will be created\. -. -.SH "DELETE" -\fBknife data bag delete\fR \fIbag name\fR [item id] \fI(options)\fR -. -.P -Delete a data bag, or an item from a data bag\. -. -.SH "EDIT" -\fBknife data bag edit\fR \fIbag name\fR \fIitem id\fR \fI(options)\fR -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -\fB\-s\fR, \fB\-\-secret SECRET\fR -A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. -. +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. .TP -\fB\-\-secret\-file SECRET_FILE\fR -The path to a file containing the secret key to be used to encrypt the data bag item\. -. -.P -Edit an item in a data bag\. -. -.SH "FROM FILE" -\fBknife data bag from file\fR \fIbag name\fR \fIfile\fR \fI(options)\fR -. -.P -\fBknife data bag from file\fR \fIbag name\fR \fIfile1\fR \fIfile2\fR \fIfile3\fR \fI(options)\fR -. -.P -\fBknife data bag from file\fR \fIbag name\fR \fIfolder\fR \fI(options)\fR -. +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. .TP -\fB\-s\fR, \fB\-\-secret SECRET\fR -A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. -. +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. .TP -\fB\-\-secret\-file SECRET_FILE\fR -The path to a file containing the secret key to be used to encrypt the data bag item\. -. -.P -Load a data bag item from a JSON file\. If \fIfile\fR is a relative or absolute path to the file, that file will be used\. Otherwise, the \fIfile\fR parameter is treated as the base name of a data bag file in a Chef repository, and \fBknife\fR will search for the file in \fB\./data_bags/bag_name/file\fR\. For example \fBknife data bag from file users dan\.json\fR would attempt to load the file \fB\./data_bags/users/dan\.json\fR\. -. -.SH "LIST" -\fBknife data bag list\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\-w\fR, \fB\-\-with\-uri\fR -Show corresponding URIs -. -.P -Lists the data bags that exist on the Chef Server\. -. -.SH "SHOW" -\fBknife data bag show BAG [ITEM]\fR \fI(options)\fR -. +.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\-s\fR, \fB\-\-secret SECRET\fR -A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. -. +.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\-\-secret\-file SECRET_FILE\fR -The path to a file containing the secret key to be used to encrypt the data bag item\. -. -.P -Show a specific data bag or an item in a data bag\. The output will be formatted according to the \-\-format option\. -. -.SH "ENCRYPTION SUPPORT" -Data Bag Items may be encrypted to keep their contents secret\. This may be desireable when storing sensitive information such as database passwords, API keys, etc\. -. -.P -Data Bag Item encryption uses the AES\-256 CBC symmetric key algorithm\. -. -.P -\fBCAVEATS:\fR Keys are not encrypted; only values are encrypted\. The "id" of a Data Bag Item is not encrypted, since it is used by Chef Server to store the item in its database\. For example, given the following data bag item: {"id": "important_passwords", "secret_password": "opensesame"} The key "secret_password" will be visible to an evesdropper, but the value "opensesame" will be protected\. Both the key "id" and its value "important_passwords" will be visible to an evesdropper\. -. -.P -Chef Server does not provide a secure mechanism for distributing encryption keys\. -. -.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\. +.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 CREATE +.sp +The \fBcreate\fP argument is used to add a data bag to the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag create DATA_BAG_NAME [DATA_BAG_ITEM] (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fBDATA_BAG_ITEM\fP +The name of a specific item within a data bag. +.TP +.B \fB\-\-secret SECRET\fP +The encryption key that is used for values contained within a data bag. +.TP +.B \fB\-\-secret\-file FILE\fP +The path to the file that contains the encryption key. +.UNINDENT +.IP Note +For encrypted data bag items, use \fIeither\fP \fB\-\-secret\fP or \fB\-\-secret\-file\fP, not both. +.RE +.sp +\fBExamples\fP +.sp +To create a data bag named "admins", enter: +.sp +.nf +.ft C +$ knife data bag create admins +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +Created data_bag[admins] +.ft P +.fi +.SH DELETE +.sp +The \fBdelete\fP argument is used to delete a data bag or a data bag item from a server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag delete DATA_BAG_NAME [DATA_BAG_ITEM] (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fBDATA_BAG_ITEM\fP +The name of a specific item within a data bag. +.UNINDENT +.sp +\fBExamples\fP +.sp +To a data bag named "admins", enter: +.sp +.nf +.ft C +$ knife data bag delete admins +.ft P +.fi +.sp +To delete an item named "charlie", enter: +.sp +.nf +.ft C +$ knife data bag delete admins charlie +.ft P +.fi +.sp +Type \fBY\fP to confirm a deletion. +.SH EDIT +.sp +The \fBedit\fP argument is used to edit the data contained in a data bag. If encryption is being used, the data bag will be decrypted, the data will be made available in the $EDITOR, and then encrypted again before saving it to the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag edit DATA_BAG_NAME [DATA_BAG_ITEM] (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fBDATA_BAG_ITEM\fP +The name of a specific item within a data bag. +.TP +.B \fB\-\-secret SECRET\fP +The encryption key that is used for values contained within a data bag. +.TP +.B \fB\-\-secret\-file FILE\fP +The path to the file that contains the encryption key. +.UNINDENT +.IP Note +For encrypted data bag items, use \fIeither\fP \fB\-\-secret\fP or \fB\-\-secret\-file\fP, not both. +.RE +.sp +\fBExamples\fP +.sp +To edit the contents of a data bag, enter: +.sp +.nf +.ft C +$ knife data bag edit admins +.ft P +.fi +.sp +To edit an item named "charlie" that is contained in a data bag named "admins", enter: +.sp +.nf +.ft C +$ knife data bag edit admins charlie +.ft P +.fi +.sp +to open the $EDITOR. Once opened, you can update the data before saving it to the server. For example, by changing: +.sp +.nf +.ft C +{ + "id": "charlie" +} +.ft P +.fi +.sp +to: +.sp +.nf +.ft C +{ + "id": "charlie", + "uid": 1005, + "gid":"ops", + "shell":"/bin/zsh", + "comment":"Crazy Charlie" +} +.ft P +.fi +.SH FROM FILE +.sp +The \fBfrom file\fP argument is used to create a data bag on the server from a file. The path to the data bag file must specify one of the following: +.INDENT 0.0 +.IP \(bu 2 +the name of a data bag +.IP \(bu 2 +a relative or absolute path to a file +.UNINDENT +.sp +If the name of a data bag is specified, Knife will search for the data bag in \fB./data_bags/bag_name/file\fP. Once opened, the JSON file should be a hash that contains at least an ID key which represents the name of the data bag item. +.IP Warning +A chef\-client must be version 11.6 (or higher) when using the \fBknife data bag from file\fP argument with the Enterprise Chef or Open Source Chef version 11 servers. +.RE +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag from file DATA_BAG_NAME_or_PATH +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-all\fP +Indicates that all data bags found at the specified path will be uploaded. +.TP +.B \fB\-\-secret SECRET\fP +The encryption key that is used for values contained within a data bag. +.TP +.B \fB\-\-secret\-file FILE\fP +The path to the file that contains the encryption key. +.UNINDENT +.IP Note +For encrypted data bag items, use \fIeither\fP \fB\-\-secret\fP or \fB\-\-secret\-file\fP, not both. +.RE +.sp +\fBExamples\fP +.sp +To create a data bag on the server from a file: +.sp +.nf +.ft C +$ knife data bag from file "path to JSON file" +.ft P +.fi +.sp +To create a data bag named "devops_data" that contains encrypted data, enter: +.sp +.nf +.ft C +$ knife data bag from file devops_data \-\-secret\-file "path to decryption file" +.ft P +.fi +.SH LIST +.sp +The \fBlist\fP argument is used to view a list of data bags that are currently available on the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag 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 +For example, to view a list of data bags on the server, enter: +.sp +.nf +.ft C +$ knife data bag list +.ft P +.fi +.SH SHOW +.sp +The \fBshow\fP argument is used to view the contents of a data bag. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag show DATA_BAG_NAME (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fBDATA_BAG_ITEM\fP +The name of a specific item within a data bag. +.TP +.B \fB\-\-secret SECRET\fP +The encryption key that is used for values contained within a data bag. +.TP +.B \fB\-\-secret\-file FILE\fP +The path to the file that contains the encryption key. +.UNINDENT +.IP Note +For encrypted data bag items, use \fIeither\fP \fB\-\-secret\fP or \fB\-\-secret\-file\fP, not both. +.RE +.sp +\fBExamples\fP +.sp +To show the contents of a data bag, enter: +.sp +.nf +.ft C +$ knife data bag show admins +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +charlie +.ft P +.fi +.sp +To show the contents of a specific item within data bag, enter: +.sp +.nf +.ft C +$ knife data bag show admins charlie +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +comment: Crazy Charlie +gid: ops +id: charlie +shell: /bin/zsh +uid: 1005 +.ft P +.fi +.sp +To show the contents of a data bag named "passwords" with an item that contains encrypted data named "mysql", enter: +.sp +.nf +.ft C +$ knife data bag show passwords mysql +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +## sample: +{ + "id": "mysql", + "pass": "trywgFA6R70NO28PNhMpGhEvKBZuxouemnbnAUQsUyo=\en", + "user": "e/p+8WJYVHY9fHcEgAAReg==\en" +} +.ft P +.fi +.sp +To show the decrypted contents of the same data bag, enter: +.sp +.nf +.ft C +$ knife data bag show \-\-secret\-file /path/to/decryption/file passwords mysql +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +## sample: +{ + "id": "mysql", + "pass": "thesecret123", + "user": "fred" +} +.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 data bag show admins \-F json +.ft P +.fi +.sp +Other formats available include \fBtext\fP, \fByaml\fP, and \fBpp\fP. +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.SH "CHEF" -Knife is distributed with Chef\. http://wiki\.opscode\.com/display/chef/Home diff --git a/distro/common/man/man1/knife-delete.1 b/distro/common/man/man1/knife-delete.1 index 9b9bb51dce..7f1028fbb9 100644 --- a/distro/common/man/man1/knife-delete.1 +++ b/distro/common/man/man1/knife-delete.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-DELETE" "1" "Chef 11.8" "" "knife delete" +.TH "KNIFE-DELETE" "1" "Chef 11.8.0" "" "knife delete" .SH NAME knife-delete \- The man page for the knife delete subcommand. . @@ -128,7 +128,5 @@ The layout of the local chef\-repo. Possible values: \fBstatic\fP, \fBeverything .UNINDENT .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-deps.1 b/distro/common/man/man1/knife-deps.1 index 8879ed536c..2f8056ed26 100644 --- a/distro/common/man/man1/knife-deps.1 +++ b/distro/common/man/man1/knife-deps.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-DEPS" "1" "Chef 11.8" "" "knife deps" +.TH "KNIFE-DEPS" "1" "Chef 11.8.0" "" "knife deps" .SH NAME knife-deps \- The man page for the knife deps subcommand. . @@ -215,7 +215,5 @@ $ knife deps nodes/*.json | xargs knife upload .fi .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-diff.1 b/distro/common/man/man1/knife-diff.1 index cc83401863..f773820286 100644 --- a/distro/common/man/man1/knife-diff.1 +++ b/distro/common/man/man1/knife-diff.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-DIFF" "1" "Chef 11.8" "" "knife diff" +.TH "KNIFE-DIFF" "1" "Chef 11.8.0" "" "knife diff" .SH NAME knife-diff \- The man page for the knife diff subcommand. . @@ -208,7 +208,5 @@ node\-lb/Rakefile .fi .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-download.1 b/distro/common/man/man1/knife-download.1 index 71eafe15a0..5ab5e788fe 100644 --- a/distro/common/man/man1/knife-download.1 +++ b/distro/common/man/man1/knife-download.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-DOWNLOAD" "1" "Chef 11.8" "" "knife download" +.TH "KNIFE-DOWNLOAD" "1" "Chef 11.8.0" "" "knife download" .SH NAME knife-download \- The man page for the knife download subcommand. . @@ -216,7 +216,5 @@ $ knife download cookbooks/apache\e* roles/webserver.json .fi .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-edit.1 b/distro/common/man/man1/knife-edit.1 index e1a0a45424..fd443726c3 100644 --- a/distro/common/man/man1/knife-edit.1 +++ b/distro/common/man/man1/knife-edit.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-EDIT" "1" "Chef 11.8" "" "knife edit" +.TH "KNIFE-EDIT" "1" "Chef 11.8.0" "" "knife edit" .SH NAME knife-edit \- The man page for the knife edit subcommand. . @@ -122,7 +122,5 @@ The layout of the local chef\-repo. Possible values: \fBstatic\fP, \fBeverything .UNINDENT .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-environment.1 b/distro/common/man/man1/knife-environment.1 index fd02466b48..c70556a190 100644 --- a/distro/common/man/man1/knife-environment.1 +++ b/distro/common/man/man1/knife-environment.1 @@ -1,168 +1,324 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-ENVIRONMENT" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\-environment\fR \- Define cookbook policies for the environments in your infrastructure -. -.SH "SYNOPSIS" -\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 -. -.TP -\fB\-d\fR, \fB\-\-description DESCRIPTION\fR -The value of the description field\. -. -.P -Create a new environment object on the Chef Server\. The envrionment will be opened in the text editor for editing prior to creation if the \-n option is not present\. -. -.SH "DELETE" -\fBknife environment delete\fR \fIenvironment\fR \fI(options)\fR -. -.P -Destroy an environment on the Chef Server\. A prompt for confirmation will be displayed if the \-y options is not given\. -. -.SH "EDIT" -\fBknife environment edit\fR \fIenvironment\fR \fI(options)\fR -. -.P -Fetch \fIenvironment\fR and display it in the text editor for editing\. The environment will be saved to the Chef Server when the editing session exits\. -. -.SH "FROM FILE" -\fBknife environment from file\fR \fIfile\fR \fI(options)\fR -. -.P -Create or update an environment from the JSON or Ruby format \fIfile\fR\. See \fBformat\fR for the proper format of this file\. -. -.SH "LIST" -\fBknife environment list\fR \fI(options)\fR * \fB\-w\fR, \fB\-\-with\-uri\fR: Show the resource URI for each environment -. -.SH "SHOW" -\fBknife environment show\fR \fIenvironment\fR \fI(options)\fR -. -.SH "DESCRIPTION" -Environments provide a means to apply policies to hosts in your infrastructure based on business function\. For example, you may have a separate copy of your infrastructure called "dev" that runs the latest version of your application and should use the newest versions of your cookbooks when configuring systems, and a production instance of your infrastructure where you wish to update code and cookbooks in a more controlled fashion\. In Chef, this function is implemented with \fIenvironments\fR\. -. -.P -Environments contain two major components: a set of cookbook version constraints and environment attributes\. -. -.SH "SYNTAX" -A cookbook version constraint is comprised of a \fIcookbook name\fR and a \fIversion constraint\fR\. The \fIcookbook name\fR is the name of a cookbook in your system, and the \fIversion constraint\fR is a String describing the version(s) of that cookbook allowed in the environment\. Only one \fIversion constraint\fR is supported for a given \fIcookbook name\fR\. -. -.P -The exact syntax used to define a cookbook version constraint varies depending on whether you use the JSON format or the Ruby format\. In the JSON format, the cookbook version constraints for an environment are represented as a single JSON object, like this: -. -.IP "" 4 -. -.nf - -{"apache2": ">= 1\.5\.0"} -. -.fi -. -.IP "" 0 -. -.P -In the Ruby format, the cookbook version contraints for an environment are represented as a Ruby Hash, like this: -. -.IP "" 4 -. +.TH "KNIFE-ENVIRONMENT" "1" "Chef 11.8.0" "" "knife environment" +.SH NAME +knife-environment \- The man page for the knife environment 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 +An environment is a way to map an organization\(aqs real\-life workflow to what can be configured and managed when using server. Every organization begins with a single environment called the \fB_default\fP environment, which cannot be modified (or deleted). Additional environments can be created to reflect each organization\(aqs patterns and workflow. For example, creating \fBproduction\fP, \fBstaging\fP, \fBtesting\fP, and \fBdevelopment\fP environments. Generally, an environment is also associated with one (or more) cookbook versions. +.sp +The \fBknife environment\fP subcommand is used to manage environments within a single organization on the server. +.sp +This subcommand has the following syntax: +.sp .nf - -{"apache2" => ">= 1\.5\.0"} -. +.ft C +$ knife environment [ARGUMENT] (options) +.ft P .fi -. -.IP "" 0 -. -.P -A \fIversion number\fR is a String comprised of two or three digits separated by a dot (\.) character, or in other words, strings of the form "major\.minor" or "major\.minor\.patch"\. "1\.2" and "1\.2\.3" are examples of valid version numbers\. Version numbers containing more than three digits or alphabetic characters are not supported\. -. -.P -A \fIversion constraint\fR String is composed of an \fIoperator\fR and a \fIversion number\fR\. The following operators are available: -. +.SH COMMON OPTIONS +.sp +The following options can be run with all Knife sub\-commands and plug\-ins: +.INDENT 0.0 .TP -\fB= VERSION\fR -Equality\. Only the exact version specified may be used\. -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB> VERSION\fR -Greater than\. Only versions greater than \fBVERSION\fR may be used\. -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -\fB>= VERSION\fR -Greater than or equal to\. Only versions equal to VERSION or greater may be used\. -. +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. .TP -\fB< VERSION\fR -Less than\. Only versions less than VERSION may be used\. -. +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. .TP -\fB<= VERSION\fR -Less than or equal to\. Only versions lesser or equal to VERSION may be used\. -. +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. .TP -\fB~> VERSION\fR -Pessimistic greater than\. Depending on the number of components in the given VERSION, the constraint will be optimistic about future minor or patch revisions only\. For example, \fB~> 1\.1\fR will match any version less than \fB2\.0\fR and greater than or equal to \fB1\.1\.0\fR, whereas \fB~> 2\.0\.5\fR will match any version less than \fB2\.1\.0\fR and greater than or equal to \fB2\.0\.5\fR\. -. -.SH "FORMAT" -The JSON format of an envioronment is as follows: -. -.IP "" 4 -. +.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 +.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 +.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 +.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 CREATE +.sp +The \fBcreate\fP argument is used to add an environment object to the server. When this argument is run, Knife will open $EDITOR to enable editing of the \fBENVIRONMENT\fP description field (unless a description is specified as part of the command). When finished, Knife will add the environment to the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp .nf - -{ - "name": "dev", - "description": "The development environment", - "cookbook_versions": { - "couchdb": "= 11\.0\.0" - }, - "json_class": "Chef::Environment", - "chef_type": "environment", - "default_attributes": { - "apache2": { "listen_ports": [ "80", "443" ] } - }, - "override_attributes": { - "aws_s3_bucket": "production" - } -} -. +.ft C +$ knife environment create ENVIRONMENT_NAME \-d DESCRIPTION +.ft P .fi -. -.IP "" 0 -. -.P -The Ruby format of an environment is as follows: -. -.IP "" 4 -. +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-d DESCRIPTION\fP, \fB\-\-description DESCRIPTION\fP +The description of the environment. This value will populate the description field for the environment on the server. +.UNINDENT +.sp +\fBExamples\fP +.sp +To create an environment named "dev" with a description of "The development environment.": +.sp +.nf +.ft C +$ knife environment create dev \-d "The development environment." +.ft P +.fi +.SH DELETE +.sp +The \fBdelete\fP argument is used to delete an environment from a server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife environment delete ENVIRONMENT_NAME +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To delete an environment named "dev", enter: +.sp +.nf +.ft C +$ knife environment delete dev +.ft P +.fi +.sp +Type \fBY\fP to confirm a deletion. +.SH EDIT +.sp +The \fBedit\fP argument is used to edit the attributes of an environment. When this argument is run, Knife will open $EDITOR to enable editing of \fBENVIRONMENT\fP attributes. When finished, Knife will update the server with those changes. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife environment edit ENVIRONMENT_NAME +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To edit an environment named "devops", enter: +.sp +.nf +.ft C +$ knife environment edit devops +.ft P +.fi +.SH FROM FILE +.sp +The \fBfrom file\fP argument is used to add or update an environment using a JSON or Ruby DSL description. It must be run with the \fBcreate\fP or \fBedit\fP arguments. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife environment [create | edit] from file FILE (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-all\fP +Indicates that all environments found at the specified path will be uploaded. +.UNINDENT +.sp +\fBExamples\fP +.sp +To add an environment using data contained in a JSON file: +.sp +.nf +.ft C +$ knife environment create devops from file "path to JSON file" +.ft P +.fi +.sp +or: +.sp +.nf +.ft C +$ knife environment edit devops from file "path to JSON file" +.ft P +.fi +.SH LIST +.sp +The \fBlist\fP argument is used to list all of the environments that are currently available on the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife environment list \-w +.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 environments: +.sp +.nf +.ft C +$ knife environment list \-w +.ft P +.fi +.SH SHOW +.sp +The \fBshow\fP argument is used to display information about the specified environment. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife environment show ENVIRONMENT_NAME +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To view information about the "dev" environment enter: +.sp .nf +.ft C +$ knife environment show dev +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +% knife environment show dev +chef_type: environment +cookbook_versions: +default_attributes: +description: +json_class: Chef::Environment +name: dev +override_attributes: -name "dev" -description "The development environment" -cookbook_versions "couchdb" => "= 11\.0\.0" -default_attributes "apache2" => { "listen_ports" => [ "80", "443" ] } -override_attributes "aws_s3_bucket" => "production" -. +\e\e +\e\e +\e\e +\e\e +.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 AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.IP "" 0 -. -.SH "SEE ALSO" -\fBknife\-node(1)\fR \fBknife\-cookbook(1)\fR \fBknife\-role(1)\fR \fIhttp://wiki\.opscode\.com/display/chef/Environments\fR \fIhttp://wiki\.opscode\.com/display/chef/Version+Constraints\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/distro/common/man/man1/knife-exec.1 b/distro/common/man/man1/knife-exec.1 index ca9c455bb5..962ec4079e 100644 --- a/distro/common/man/man1/knife-exec.1 +++ b/distro/common/man/man1/knife-exec.1 @@ -1,43 +1,325 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 +.TH "KNIFE-EXEC" "1" "Chef 11.8.0" "" "knife exec" +.SH NAME +knife-exec \- The man page for the knife exec subcommand. . -.TH "KNIFE\-EXEC" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" +.nr rst2man-indent-level 0 . -.SH "NAME" -\fBknife\-exec\fR \- Run user scripts using the Chef API DSL -. -.SH "SYNOPSIS" -\fBknife\fR \fBexec\fR \fI(options)\fR +.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 \fBknife exec\fP subcommand uses the Knife configuration file to execute Ruby scripts in the context of a fully configured chef\-client. This subcommand is most often used to run scripts that will only access server one time (or otherwise very infrequently). Use this subcommand any time that an operation does not warrant full usage of the Knife subcommand library. +.sp +For Ruby scripts that will be run using the \fBexec\fP subcommand, note the following: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +The Ruby script must be located on the system from which Knife is run (and not be located on any of the systems that Knife will be managing). +.IP \(bu 2 +Shell commands will be run from a management workstation. For example, something like \fB%x[ls \-lash /opt/only\-on\-a\-node]\fP would give you the directory listing for the "opt/only\-on\-a\-node" directory or a "No such file or directory" error if the file does not already exist locally. +.IP \(bu 2 +When the chef\-shell DSL is available, the chef\-client DSL will not be (unless the management workstation is also a chef\-client). Without the chef\-client DSL, a bash block cannot be used to run bash commands. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fBCommon Options\fP +.sp +The following options can be run with all Knife sub\-commands and plug\-ins: +.INDENT 0.0 .TP -\fB\-E\fR, \fB\-\-exec CODE\fR -Provide a snippet of code to evaluate on the command line -. -.SH "DESCRIPTION" -\fBknife exec\fR runs arbitrary ruby scripts in a context similar to that of the chef\-shell(1) DSL\. See the chef\-shell documentation for a description of the commands available\. -. -.SH "EXAMPLES" -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -Make an API call against an arbitrary endpoint -knife exec \-E \'api\.get("nodes/fluke\.localdomain/cookbooks")\' => list of cookbooks for the node \fIfluke\.localdomain\fR -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -Remove the role \fIobsolete\fR from all nodes -knife exec \-E \'nodes\.transform(:all){|n| n\.run_list\.delete("role[obsolete]")}\' -. +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. .TP -Generate the expanded run list for hosts in the \fBwebserver\fR role -knife exec \-E \'nodes\.find(:roles => "webserver") {|n| n\.expand!; n[:recipes]}\' -. -.SH "SEE ALSO" -\fBchef\-shell(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 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\. +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. +.TP +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. +.TP +.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 +.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 +.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 +.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 +.sp +\fBAuthenticated API Requests\fP +.sp +The \fBknife exec\fP subcommand can be used to make authenticated API requests to the server using the following methods: +.TS +center; +|l|l|. +_ +T{ +Method +T} T{ +Description +T} +_ +T{ +\fBapi.delete\fP +T} T{ +Use to delete an object from the server. +T} +_ +T{ +\fBapi.get\fP +T} T{ +Use to get the details of an object on the server. +T} +_ +T{ +\fBapi.post\fP +T} T{ +Use to add an object to the server. +T} +_ +T{ +\fBapi.put\fP +T} T{ +Use to update an object on the server. +T} +_ +.TE +.sp +These methods are used with the \fB\-E\fP option, which executes that string locally on the workstation using chef\-shell. These methods have the following syntax: +.sp +.nf +.ft C +$ knife exec \-E \(aqapi.method(/endpoint)\(aq +.ft P +.fi +.sp +where: +.INDENT 0.0 +.IP \(bu 2 +\fBapi.method\fP is the corresponding authentication method \-\-\- \fBapi.delete\fP, \fBapi.get\fP, \fBapi.post\fP, or \fBapi.put\fP +.IP \(bu 2 +\fB/endpoint\fP is an endpoint in the Chef Server API +.UNINDENT +.sp +For example, to get the data for a node named "Example_Node": +.sp +.nf +.ft C +$ knife exec \-E \(aqputs api.get("/nodes/Example_Node")\(aq +.ft P +.fi +.sp +and to ensure that the output is visible in the console, add the \fBputs\fP in front of the API authorization request: +.sp +.nf +.ft C +$ knife exec \-E \(aqputs api.get("/nodes/Example_Node")\(aq +.ft P +.fi +.sp +where \fBputs\fP is the shorter version of the \fB$stdout.puts\fP predefined variable in Ruby. +.sp +The following example shows how to add a client named "IBM305RAMAC" and the \fB/clients\fP endpoint, and then return the private key for that user in the console: +.sp +.nf +.ft C +$ client_desc = { + "name" => "IBM305RAMAC", + "admin" => false + } + + new_client = api.post("/clients", client_desc) + puts new_client["private_key"] +.ft P +.fi +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife exec SCRIPT (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This subcommand has the following options: +.INDENT 0.0 +.TP +.B \fB\-E CODE\fP, \fB\-\-exec CODE\fP +A string of code that will be executed. +.TP +.B \fB\-p PATH:PATH\fP, \fB\-\-script\-path PATH:PATH\fP +A colon\-separated path at which Ruby scripts are located. +.UNINDENT +.sp +\fBExamples\fP +.sp +There are three ways to use \fBknife exec\fP to run Ruby script files. For example: +.sp +.nf +.ft C +$ knife exec /path/to/script_file +.ft P +.fi +.sp +Or: +.sp +.nf +.ft C +$ knife exec \-E \(aqRUBY CODE\(aq +.ft P +.fi +.sp +Or: +.sp +.nf +.ft C +$ knife exec +RUBY CODE +^D +.ft P +.fi +.sp +To check the status of Knife using a Ruby script named "status.rb" (which looks like): +.sp +.nf +.ft C +printf "%\-5s %\-12s %\-8s %s\en", "Check In", "Name", "Ruby", "Recipes" +nodes.all do |n| + checkin = Time.at(n[\(aqohai_time\(aq]).strftime("%F %R") + rubyver = n[\(aqlanguages\(aq][\(aqruby\(aq][\(aqversion\(aq] + recipes = n.run_list.expand(_default).recipes.join(", ") + printf "%\-20s %\-12s %\-8s %s\en", checkin, n.name, rubyver, recipes +end +.ft P +.fi +.sp +and is located in a directory named "scripts", enter: +.sp +.nf +.ft C +$ knife exec scripts/status.rb +.ft P +.fi +.sp +To show the available free memory for all nodes, enter: +.sp +.nf +.ft C +$ knife exec \-E \(aqnodes.all {|n| puts "#{n.name} has #{n.memory.total} free memory"}\(aq +.ft P +.fi +.sp +To list all of the available search indexes, enter: +.sp +.nf +.ft C +$ knife exec \-E \(aqputs api.get("search").keys\(aq +.ft P +.fi +.sp +To query a node for multiple attributes using a Ruby script named \fBsearch_attributes.rb\fP (which looks like): +.sp +.nf +.ft C +% cat scripts/search_attributes.rb +query = ARGV[2] +attributes = ARGV[3].split(",") +puts "Your query: #{query}" +puts "Your attributes: #{attributes.join(" ")}" +results = {} +search(:node, query) do |n| + results[n.name] = {} + attributes.each {|a| results[n.name][a] = n[a]} +end + +puts results +exit 0 +.ft P +.fi +.sp +enter: +.sp +.nf +.ft C +% knife exec scripts/search_attributes.rb "hostname:test_system" ipaddress,fqdn +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +Your query: hostname:test_system +Your attributes: ipaddress fqdn +{"test_system.example.com"=>{"ipaddress"=>"10.1.1.200", "fqdn"=>"test_system.example.com"}} +.ft P +.fi +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.SH "CHEF" -Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR diff --git a/distro/common/man/man1/knife-index-rebuild.1 b/distro/common/man/man1/knife-index-rebuild.1 index 2bacf68619..1dc7dc1703 100644 --- a/distro/common/man/man1/knife-index-rebuild.1 +++ b/distro/common/man/man1/knife-index-rebuild.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-INDEX-REBUILD" "1" "Chef 11.8" "" "knife index rebuild" +.TH "KNIFE-INDEX-REBUILD" "1" "Chef 11.8.0" "" "knife index rebuild" .SH NAME knife-index-rebuild \- The man page for the knife index rebuild subcommand. . @@ -111,7 +111,5 @@ $ knife index rebuild This command does not have any specific options. .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-index.1 b/distro/common/man/man1/knife-index.1 deleted file mode 100644 index be59f4a878..0000000000 --- a/distro/common/man/man1/knife-index.1 +++ /dev/null @@ -1,29 +0,0 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-INDEX" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\-index\fR \- Rebuild the search index on a Chef Server -. -.SH "SYNOPSIS" -\fBknife\fR \fBindex rebuild\fR \fI(options)\fR -. -.TP -\fB\-y\fR, \fB\-\-yes\fR -don\'t bother to ask if I\'m sure -. -.SH "DESCRIPTION" -Rebuilds all the search indexes on the server\. This is accomplished by deleting all objects from the search index, and then forwarding each item in the database to \fBchef\-expander\fR(8) via \fBrabbitmq\-server\fR(1)\. Depending on the number of objects in the database, it may take some time for all objects to be indexed and available for search\. -. -.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/distro/common/man/man1/knife-list.1 b/distro/common/man/man1/knife-list.1 index e4cfb6710d..0314abef33 100644 --- a/distro/common/man/man1/knife-list.1 +++ b/distro/common/man/man1/knife-list.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-LIST" "1" "Chef 11.8" "" "knife list" +.TH "KNIFE-LIST" "1" "Chef 11.8.0" "" "knife list" .SH NAME knife-list \- The man page for the knife list subcommand. . @@ -163,7 +163,5 @@ $ knife list \-R / .fi .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-node.1 b/distro/common/man/man1/knife-node.1 index 1a65c6391a..394cf54c87 100644 --- a/distro/common/man/man1/knife-node.1 +++ b/distro/common/man/man1/knife-node.1 @@ -1,134 +1,578 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-NODE" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\-node\fR \- Manage the hosts in your infrastructure -. -.SH "SYNOPSIS" -\fBknife\fR \fBnode\fR \fIsub\-command\fR \fI(options)\fR -. -.SH "DESCRIPTION" -Nodes are data structures that represent hosts configured with Chef\. Nodes have a \fBname\fR, a String that uniquely identifies the node, \fBattributes\fR, a nested Hash of properties that describe how the host should be configured, a \fBchef_environment\fR, a String representing the environment to which the node belongs, and a \fBrun_list\fR, an ordered list of \fBrecipes\fR or \fBroles\fR that chef\-client should apply when configuring a host\. -. -.P -When a host communicates with a Chef Server, it authenticates using its \fBnode_name\fR for identification and signs its reqests with a private key\. The Server validates the request by looking up a \fBclient\fR object with a name identical to the \fBnode_name\fR submitted with the request and verifes the signature using the public key for that \fBclient\fR object\. \fBNOTE\fR that the \fBclient\fR is a different object in the system\. It is associated with a node by virtue of having a matching name\. -. -.P -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 -. -.P -Deletes nodes for which the name matches the regular expression \fIregex\fR on the Chef Server\. The regular expression should be given in quotes, and should not be surrounded with forward slashes (as is typical of regular expression literals in scripting languages)\. -. -.SH "CREATE" -\fBknife node create\fR \fIname\fR \fI(options)\fR -. -.P -Create a new node\. Unless the \-\-disable\-editing option is given, an empty node object will be created and displayed in your text editor\. If the editor exits with a successful exit status, the node data will be posted to the Chef Server to create the node\. -. -.SH "DELETE" -\fBknife node delete\fR \fIname\fR \fI(options)\fR -. -.P -Deletes the node identified by \fIname\fR on the Chef Server\. -. -.SH "EDIT" -\fBknife node edit\fR \fIname\fR \fI(options)\fR -. +.TH "KNIFE-NODE" "1" "Chef 11.8.0" "" "knife node" +.SH NAME +knife-node \- The man page for the knife node 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 +A node is any physical, virtual, or cloud machine that is configured to be maintained by a chef\-client. +.sp +The \fBknife node\fP subcommand is used to manage the nodes that exist on a server. +.sp +This subcommand has the following syntax: +.sp +.nf +.ft C +$ knife node [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\-a\fR, \fB\-\-all\fR -Display all node data in the editor\. By default, default, override, and automatic attributes are not shown\. -. -.P -Edit the node identified by \fIname\fR\. Like \fBknife node create\fR, the node will be displayed in your text editor unless the \-n option is present\. -. -.SH "FROM FILE" -\fBknife node from file\fR \fIfile\fR \fI(options)\fR -. -.P -Create a node from a JSON format \fIfile\fR\. -. -.SH "LIST" -\fBknife node list\fR \fI(options)\fR -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-w\fR, \fB\-\-with\-uri\fR -Show corresponding URIs -. -.P -List all nodes\. -. -.SH "RUN_LIST ADD" -\fBknife node run_list add\fR \fIname\fR \fIrun list item\fR \fI(options)\fR -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -\fB\-a\fR, \fB\-\-after ITEM\fR -Place the ENTRY in the run list after ITEM -. -.P -Add the \fIrun list item\fR to the node\'s \fBrun_list\fR\. See Run list -. -.SH "RUN_LIST REMOVE" -\fBknife node run_list remove\fR \fInode name\fR \fIrun list item\fR \fI(options)\fR -. -.P -Remove the \fIrun list item\fR from the node\'s \fBrun_list\fR\. -. -.SH "SHOW" -\fBknife node show\fR \fInode name\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\-a\fR, \fB\-\-attribute [ATTR]\fR -Show only one attribute -. +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. .TP -\fB\-r\fR, \fB\-\-run\-list\fR -Show only the run list -. +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. .TP -\fB\-F\fR, \fB\-\-format FORMAT\fR -Display the node in a different format\. -. +.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\-m\fR, \fB\-\-medium\fR -Display more, but not all, of the node\'s data when using the default \fIsummary\fR format -. -.P -Displays the node identified by \fInode name\fR on stdout\. -. -.SH "RUN LIST ITEM FORMAT" -Run list items may be either roles or recipes\. When adding a role to a run list, the correct syntax is "role[ROLE_NAME]" -. -.P -When adding a recipe to a run list, there are several valid formats: -. +.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 -Fully Qualified Format -"recipe[COOKBOOK::RECIPE_NAME]", for example, "recipe[chef::client]" -. +.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 -Cookbook Recipe Format -For brevity, the recipe part of the fully qualified format may be omitted, and recipes specified as "COOKBOOK::RECIPE_NAME", e\.g\., "chef::client" -. +.B \fB\-h\fP, \fB\-\-help\fP +Shows help for the command. .TP -Default Recipe Format -When adding the default recipe of a cookbook to a run list, the recipe name may be omitted as well, e\.g\., "chef::default" may be written as just "chef" -. -.SH "SEE ALSO" -\fBknife\-client\fR(1) \fBknife\-search\fR(1) \fBknife\-role\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\. +.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 BULK DELETE +.sp +The \fBbulk delete\fP argument is used to delete one or more nodes that match a pattern defined by a regular expression. The regular expression must be within quotes and not be surrounded by forward slashes (/). +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife node bulk delete REGEX +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To bulk delete many nodes, use a regular expression to define the pattern: +.sp +.nf +.ft C +$ knife node bulk delete "^[0\-9]{3}$" +.ft P +.fi +.sp +Type \fBY\fP to confirm a deletion. +.SH CREATE +.sp +The \fBcreate\fP argument is used to add a node to the server. Node data is stored as JSON on the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife node create NODE_NAME +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To add a node, enter: +.sp +.nf +.ft C +$ knife node create node1 +.ft P +.fi +.sp +In the $EDITOR enter the node data in JSON: +.sp +.nf +.ft C +## sample: +{ + "normal": { + }, + "name": "foobar", + "override": { + }, + "default": { + }, + "json_class": "Chef::Node", + "automatic": { + }, + "run_list": [ + "recipe[zsh]", + "role[webserver]" + ], + "chef_type": "node" +} +.ft P +.fi +.sp +When finished, save it. +.SH DELETE +.sp +The \fBdelete\fP argument is used to delete a node from the server. +.IP Note +Deleting a node will not delete any corresponding API clients. +.RE +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife node delete NODE_NAME +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To delete a node called "dev", enter: +.sp +.nf +.ft C +$ knife node delete dev +.ft P +.fi +.SH EDIT +.sp +The \fBedit\fP argument is used to edit the details of a node on a server. Node data is stored as JSON on the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife node edit NODE_NAME (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-all\fP +Displays a node in the $EDITOR. By default, attributes that are default, override, or automatic are not shown. +.UNINDENT +.sp +\fBExamples\fP +.sp +To edit the data for a node named "node1", enter: +.sp +.nf +.ft C +$ knife node edit node1 \-a +.ft P +.fi +.sp +Update the role data in JSON: +.sp +.nf +.ft C +## sample: +{ + "normal": { + }, + "name": "node1", + "override": { + }, + "default": { + }, + "json_class": "Chef::Node", + "automatic": { + }, + "run_list": [ + "recipe[devops]", + "role[webserver]" + ], + "chef_type": "node" +} +.ft P +.fi +.sp +When finished, save it. +.SH FROM FILE +.sp +The \fBfrom file\fP argument is used to create a node using existing node data as a template. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife node from file FILE +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To add a node using data contained in a JSON file: +.sp +.nf +.ft C +$ knife node from file "path to JSON file" +.ft P +.fi +.SH LIST +.sp +The \fBlist\fP argument is used to view all of the nodes that exist on a server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife node list (options) +.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 verify the list of nodes that are registered with the server, enter: +.sp +.nf +.ft C +$ knife node list +.ft P +.fi +.sp +to return something similar to: +.sp +.nf +.ft C +i\-12345678 +rs\-123456 +.ft P +.fi +.SH RUN_LIST ADD +.sp +The \fBrun_list add\fP argument is used to add run list items (roles or recipes) to a node. A recipe must be in one of the following formats: fully qualified, cookbook, or default. Both roles and recipes must be in quotes, for example: \fB\(aqrole[ROLE_NAME]\(aq\fP or \fB\(aqrecipe[COOKBOOK::RECIPE_NAME]\(aq\fP. Use a comma to separate roles and recipes when adding more than one, like this: \fB\(aqrecipe[COOKBOOK::RECIPE_NAME],COOKBOOK::RECIPE_NAME,role[ROLE_NAME]\(aq\fP. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife node run_list add NODE_NAME RUN_LIST_ITEM (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a ITEM\fP, \fB\-\-after ITEM\fP +Use this to add the run list item after the specified run list item. +.UNINDENT +.sp +\fBExamples\fP +.sp +To add a role to a run list, enter: +.sp +.nf +.ft C +$ knife node run_list add node \(aqrole[ROLE_NAME]\(aq +.ft P +.fi +.sp +To add roles and recipes to a run list, enter: +.sp +.nf +.ft C +$ knife node run_list add node \(aqrecipe[COOKBOOK::RECIPE_NAME],recipe[COOKBOOK::RECIPE_NAME],role[ROLE_NAME]\(aq +.ft P +.fi +.sp +To add a recipe to a run list using the fully qualified format, enter: +.sp +.nf +.ft C +$ knife node run_list add node \(aqrecipe[COOKBOOK::RECIPE_NAME]\(aq +.ft P +.fi +.sp +To add a recipe to a run list using the cookbook format, enter: +.sp +.nf +.ft C +$ knife node run_list add node \(aqCOOKBOOK::RECIPE_NAME\(aq +.ft P +.fi +.sp +To add the default recipe of a cookbook to a run list, enter: +.sp +.nf +.ft C +$ knife node run_list add node \(aqCOOKBOOK\(aq +.ft P +.fi +.SH RUN_LIST REMOVE +.sp +The \fBrun_list remove\fP argument is used to remove run list items (roles or recipes) from a node. A recipe must be in one of the following formats: fully qualified, cookbook, or default. Both roles and recipes must be in quotes, for example: \fB\(aqrole[ROLE_NAME]\(aq\fP or \fB\(aqrecipe[COOKBOOK::RECIPE_NAME]\(aq\fP. Use a comma to separate roles and recipes when removing more than one, like this: \fB\(aqrecipe[COOKBOOK::RECIPE_NAME],COOKBOOK::RECIPE_NAME,role[ROLE_NAME]\(aq\fP. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife node run_list remove NODE_NAME RUN_LIST_ITEM +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To remove a role from a run list, enter: +.sp +.nf +.ft C +$ knife node run_list remove node \(aqrole[ROLE_NAME]\(aq +.ft P +.fi +.sp +To remove a recipe from a run list using the fully qualified format, enter: +.sp +.nf +.ft C +$ knife node run_list remove node \(aqrecipe[COOKBOOK::RECIPE_NAME]\(aq +.ft P +.fi +.SH SHOW +.sp +The \fBshow\fP argument is used to display information about a node. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife node show NODE_NAME (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a ATTR\fP, \fB\-\-attribute ATTR\fP +The attribute (or attributes) to show. +.TP +.B \fB\-l\fP, \fB\-\-long\fP +Display long output when searching nodes while using the default summary format. +.TP +.B \fB\-m\fP, \fB\-\-medium\fP +Display more, but not all, of a node\(aqs data when searching using the default summary format. +.TP +.B \fB\-r\fP, \fB\-\-run\-list\fP +Indicates that only the run\-list will be shown. +.UNINDENT +.sp +\fBExamples\fP +.sp +To view all data for a node named "build", enter: +.sp +.nf +.ft C +$ knife node show build +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +Node Name: build +Environment: _default +FQDN: +IP: +Run List: +Roles: +Recipes: +Platform: +.ft P +.fi +.sp +To show basic information about a node, truncated and nicely formatted: +.sp +.nf +.ft C +knife node show <node_name> +.ft P +.fi +.sp +To show all information about a node, nicely formatted: +.sp +.nf +.ft C +knife node show \-l <node_name> +.ft P +.fi +.sp +To list a single node attribute: +.sp +.nf +.ft C +knife node show <node_name> \-a <attribute_name> +.ft P +.fi +.sp +where \fB<attribute_name>\fP is something like kernel or platform. (This doesn\(aqt work for nested attributes like \fBnode[kernel][machine]\fP because \fBknife node show\fP doesn\(aqt understand nested attributes.) +.sp +To view the FQDN for a node named "i\-12345678", enter: +.sp +.nf +.ft C +$ knife node show i\-12345678 \-a fqdn +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +fqdn: ip\-10\-251\-75\-20.ec2.internal +.ft P +.fi +.sp +To view the run list for a node named "dev", enter: +.sp +.nf +.ft C +$ knife node show dev \-r +.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. +.sp +To view node information in raw JSON, use the \fB\-l\fP or \fB\-\-long\fP option: +.sp +.nf +.ft C +knife node show \-l \-F json <node_name> +.ft P +.fi +.sp +and/or: +.sp +.nf +.ft C +knife node show \-l \-\-format=json <node_name> +.ft P +.fi +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.SH "CHEF" -Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR diff --git a/distro/common/man/man1/knife-raw.1 b/distro/common/man/man1/knife-raw.1 index 5053006c0b..c35b010031 100644 --- a/distro/common/man/man1/knife-raw.1 +++ b/distro/common/man/man1/knife-raw.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-RAW" "1" "Chef 11.8" "" "knife raw" +.TH "KNIFE-RAW" "1" "Chef 11.8.0" "" "knife raw" .SH NAME knife-raw \- The man page for the knife raw subcommand. . @@ -166,7 +166,5 @@ to return something similar to: .fi .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-recipe-list.1 b/distro/common/man/man1/knife-recipe-list.1 index d8cca9edec..ab7bf6ec8c 100644 --- a/distro/common/man/man1/knife-recipe-list.1 +++ b/distro/common/man/man1/knife-recipe-list.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-RECIPE-LIST" "1" "Chef 11.8" "" "knife recipe list" +.TH "KNIFE-RECIPE-LIST" "1" "Chef 11.8.0" "" "knife recipe list" .SH NAME knife-recipe-list \- The man page for the knife recipe list subcommand. . @@ -129,7 +129,5 @@ couchdb::org_cleanu .fi .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-role.1 b/distro/common/man/man1/knife-role.1 index 654299f054..33c7b6bf8f 100644 --- a/distro/common/man/man1/knife-role.1 +++ b/distro/common/man/man1/knife-role.1 @@ -1,88 +1,374 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 +.TH "KNIFE-ROLE" "1" "Chef 11.8.0" "" "knife role" +.SH NAME +knife-role \- The man page for the knife role subcommand. . -.TH "KNIFE\-ROLE" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" +.nr rst2man-indent-level 0 . -.SH "NAME" -\fBknife\-role\fR \- Group common configuration settings -. -.SH "SYNOPSIS" -\fBknife\fR \fBrole\fR \fIsub\-command\fR \fI(options)\fR -. -.SH "ROLE SUB\-COMMANDS" -The following \fBrole\fR subcommands are available: -. -.SH "LIST" -\fBknife role list\fR \fI(options)\fR +.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 +A role is a way to define certain patterns and processes that exist across nodes in an organization as belonging to a single job function. Each role consists of zero (or more) attributes and a run list. Each node can have zero (or more) roles assigned to it. When a role is run against a node, the configuration details of that node are compared against the attributes of the role, and then the contents of that role\(aqs run list are applied to the node\(aqs configuration details. When a chef\-client runs, it merges its own attributes and run lists with those contained within each assigned role. +.sp +The \fBknife role\fP subcommand is used to manage the roles that are associated with one or more nodes on a server. +.sp +This subcommand has the following syntax: +.sp +.nf +.ft C +$ knife role [ARGUMENT] (options) +.ft P +.fi +.IP Note +Use the \fBknife node\fP subcommand (and the \fBrun_list add node\fP argument) to add a role to a node on the server. +.RE +.SH COMMON OPTIONS +.sp +The following options can be run with all Knife sub\-commands and plug\-ins: +.INDENT 0.0 .TP -\fB\-w\fR, \fB\-\-with\-uri\fR -Show corresponding URIs -. -.P -List roles\. -. -.SH "SHOW" -\fBknife role show ROLE\fR \fI(options)\fR -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-a\fR, \fB\-\-attribute ATTR\fR -Show only one attribute -. -.P -Show a specific role\. -. -.SH "CREATE" -\fBknife role create ROLE\fR \fI(options)\fR -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -\fB\-d\fR, \fB\-\-description\fR -The role description -. -.P -Create a new role\. -. -.SH "EDIT" -\fBknife role edit ROLE\fR \fI(options)\fR -. -.P -Edit a role\. -. -.SH "FROM FILE" -\fBknife role from file FILE\fR \fI(options)\fR -. -.P -Create or update a role from a role Ruby DSL (\fB\.rb\fR) or JSON file\. -. -.SH "DELETE" -\fBknife role delete ROLE\fR \fI(options)\fR -. -.P -Delete a role\. -. -.SH "BULK DELETE" -\fBknife role bulk delete REGEX\fR \fI(options)\fR -. -.P -Delete roles on the Chef Server based on a regular expression\. The regular expression (\fIREGEX\fR) should be in quotes, not in //\'s\. -. -.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 -\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 -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\. -. -.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 -. -.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\. +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. +.TP +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. +.TP +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. +.TP +.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 +.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 +.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 +.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 BULK DELETE +.sp +The \fBbulk delete\fP argument is used to delete one or more roles that match a pattern defined by a regular expression. The regular expression must be within quotes and not be surrounded by forward slashes (/). +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife role bulk delete REGEX +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To bulk delete roles using a regular expression: +.sp +.nf +.ft C +$ knife role bulk delete "^[0\-9]{3}$" +.ft P +.fi +.SH CREATE +.sp +The \fBcreate\fP argument is used to add a role to the server. To add a role to a node, you must use the \fBnode\fP sub\-command and the \fBrun\-list add\fP argument. Role data is saved as JSON on the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife role create ROLE_NAME (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-d DESCRIPTION\fP, \fB\-\-description DESCRIPTION\fP +The description of the role. This value will populate the description field for the role on the server. +.UNINDENT +.sp +\fBExamples\fP +.sp +To add a role named "role1", enter: +.sp +.nf +.ft C +$ knife role create role1 +.ft P +.fi +.sp +In the $EDITOR enter the role data in JSON: +.sp +.nf +.ft C +## sample: +{ + "name": "role1", + "default_attributes": { + }, + "json_class": "Chef::Role", + "run_list": [ + + ], + "description": "", + "chef_type": "role", + "override_attributes": { + } +} +.ft P +.fi +.sp +When finished, save it. +.SH DELETE +.sp +The \fBdelete\fP argument is used to delete a role from the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife role delete ROLE_NAME +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To delete a role: +.sp +.nf +.ft C +$ knife role delete devops +.ft P +.fi +.sp +Type \fBY\fP to confirm a deletion. +.SH EDIT +.sp +The \fBedit\fP argument is used to edit role details on the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife role edit ROLE_NAME +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To edit the data for a role named "role1", enter: +.sp +.nf +.ft C +$ knife role edit role1 +.ft P +.fi +.sp +Update the role data in JSON: +.sp +.nf +.ft C +## sample: +{ + "name": "role1", + "default_attributes": { + }, + "json_class": "Chef::Role", + "run_list": [ + + ], + "description": "This is the description for the role1 role.", + "chef_type": "role", + "override_attributes": { + } +} +.ft P +.fi +.sp +When finished, save it. +.SH FROM FILE +.sp +The \fBfrom file\fP argument is used to create a role using existing JSON data as a template. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife role from file FILE +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To view role details based on the values contained in a JSON file: +.sp +.nf +.ft C +$ knife role from file "path to JSON file" +.ft P +.fi +.SH LIST +.sp +The \fBlist\fP argument is used to view a list of roles that are currently available on the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife role 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 roles on the server and display the URI for each role returned, enter: +.sp +.nf +.ft C +$ knife role list \-w +.ft P +.fi +.SH SHOW +.sp +The \fBshow\fP argument is used to view the details of a role. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife role show ROLE_NAME +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a ATTR\fP, \fB\-\-attribute ATTR\fP +The attribute (or attributes) to show. +.UNINDENT +.sp +\fBExamples\fP +.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. +.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 AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.SH "CHEF" -Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR diff --git a/distro/common/man/man1/knife-search.1 b/distro/common/man/man1/knife-search.1 index c248d84b6c..e59be88bd9 100644 --- a/distro/common/man/man1/knife-search.1 +++ b/distro/common/man/man1/knife-search.1 @@ -1,280 +1,304 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-SEARCH" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\-search\fR \- Find objects on a Chef Server by query -. -.SH "SYNOPSIS" -\fBknife\fR \fBsearch INDEX QUERY\fR \fI(options)\fR -. +.TH "KNIFE-SEARCH" "1" "Chef 11.8.0" "" "knife search" +.SH NAME +knife-search \- The man page for the knife search 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 +Search indexes allow queries to be made for any type of data that is indexed by the server, including data bags (and data bag items), environments, nodes, and roles. A defined query syntax is used to support search patterns like exact, wildcard, range, and fuzzy. A search is a full\-text query that can be done from several locations, including from within a recipe, by using the \fBsearch\fP subcommand in Knife, by using the search functionality in the Management Console, or by using the \fB/search\fP or \fB/search/INDEX\fP endpoints in the Chef Server API. The search engine is based on Apache Solr and is run from the server. +.sp +The \fBknife search\fP subcommand is used run a search query for information that is indexed on a server. +.sp +\fBCommon Options\fP +.sp +The following options can be run with all Knife sub\-commands and plug\-ins: +.INDENT 0.0 .TP -\fB\-a\fR, \fB\-\-attribute ATTR\fR -Show only one attribute -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-i\fR, \fB\-\-id\-only\fR -Show only the ID of matching objects -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -\fB\-q\fR, \fB\-\-query QUERY\fR -The search query; useful to protect queries starting with \- -. +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. .TP -\fB\-R\fR, \fB\-\-rows INT\fR -The number of rows to return -. +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. .TP -\fB\-r\fR, \fB\-\-run\-list\fR -Show only the run list -. +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. .TP -\fB\-o\fR, \fB\-\-sort SORT\fR -The order to sort the results in -. +.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\-b\fR, \fB\-\-start ROW\fR -The row to start returning results at -. +.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\-m\fR, \fB\-\-medium\fR -Display medium sized output when searching nodes using the default summary format -. +.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\-l\fR, \fB\-\-long\fR -Display long output when searching nodes using the default summary format -. -.SH "DESCRIPTION" -Search is a feature of the Chef Server that allows you to use a full\-text search engine to query information about your infrastructure and applications\. You can utilize this service via search calls in a recipe or the knife search command\. The search syntax is based on Lucene\. -. -.SH "INDEXES" -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: -. -.IP "\(bu" 4 -\fInode\fR -. -.IP "\(bu" 4 -\fIrole\fR -. -.IP "\(bu" 4 -\fIenvironment\fR -. -.IP "\(bu" 4 -\fIclients\fR -. -.IP "\(bu" 4 -\fIdata bag\fR -. -.IP "" 0 -. -.P -Data bags are indexed by the data bag\'s name\. For example, to search a data bag named "admins": -. -.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 +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp .nf - -knife search admins "field:search_pattern" -. +.ft C +$ knife search INDEX SEARCH_QUERY +.ft P .fi -. -.IP "" 0 -. -.SH "QUERY SYNTAX" -Queries have the form \fBfield:search_pattern\fR where \fBfield\fR is a key in the JSON description of the relevant objects (nodes, roles, environments, or data bags)\. Both \fBfield\fR and \fBsearch_pattern\fR are case\-sensitive\. \fBsearch_pattern\fR can be an exact, wildcard, range, or fuzzy match (see below)\. The \fBfield\fR supports exact matching and limited wildcard matching\. -. -.P -Searches will return the relevant objects (nodes, roles, environments, or data bags) where the \fBsearch_pattern\fR matches the object\'s value of \fBfield\fR\. -. -.SS "FIELD NAMES" -Field names are the keys within the JSON description of the object being searched\. Nested Keys can be searched by placing an underscore ("_") between key names\. -. -.SS "WILDCARD MATCHING FOR FIELD NAMES" -The field name also has limited support for wildcard matching\. Both the "*" and "?" wildcards (see below) can be used within a field name; however, they cannot be the first character of the field name\. -. -.SS "EXACT MATCHES" -Without any search modifiers, a search returns those fields for which the \fBsearch_pattern\fR exactly matches the value of \fBfield\fR in the JSON description of the object\. -. -.SS "WILDCARD MATCHES" -Search support both single\- and multi\-character wildcard searches within a search pattern\. -. -.P -\'?\' matches exactly one character\. -. -.P -\'*\' matches zero or more characters\. -. -.SS "RANGE MATCHES" -Range searches allows one to match values between two given values\. To match values between X and Y, inclusively, use square brackets: -. -.IP "" 4 -. +.sp +where \fBINDEX\fP is one of \fBclient\fP, \fBenvironment\fP, \fBnode\fP, \fBrole\fP, or the name of a data bag and \fBSEARCH_QUERY\fP is the search query syntax for the query that will be executed. +.sp +\fBINDEX\fP is implied if omitted, and will default to \fBnode\fP. For example: +.sp .nf - -knife search INDEX \'field:[X TO Y] -. +.ft C +$ knife search \(aq*:*\(aq \-i +.ft P .fi -. -.IP "" 0 -. -.P -To match values between X and Y, exclusively, use curly brackets: -. -.IP "" 4 -. +.sp +will return something similar to: +.sp .nf +.ft C +8 items found -knife search INDEX \'field:{X TO Y}\' -. +centos\-62\-dev +opensuse\-1203 +ubuntu\-1304\-dev +ubuntu\-1304\-orgtest +ubuntu\-1204\-ohai\-test +ubuntu\-1304\-ifcfg\-test +ohai\-test +win2k8\-dev +.ft P .fi -. -.IP "" 0 -. -.P -Values are sorted in lexicographic order\. -. -.SS "FUZZY MATCHES" -Fuzzy searches allows one to match values based on the Levenshtein Distance algorithm\. To perform a fuzzy match, append a tilda (~) to the search term: -. -.IP "" 4 -. +.sp +and is the same search as: +.sp .nf - -knife search INDEX \'field:term~\' -. +.ft C +$ knife node search \(aq*:*" \-i +.ft P .fi -. -.IP "" 0 -. -.P -This search would return nodes whose \fBfield\fR was \'perm\' or \'germ\'\. -. -.SS "BOOLEAN OPERATORS" -The boolean operators NOT, AND, and OR are supported\. To find values of \fBfield\fR that are not X: -. -.IP "" 4 -. +.sp +If the \fBSEARCH_QUERY\fP does not contain a colon character (\fB:\fP), then the default query pattern is \fBtags:*#{@query}* OR roles:*#{@query}* OR fqdn:*#{@query}* OR addresses:*#{@query}*\fP, which means the following two search queries are effectively the same: +.sp .nf - -knife search INDEX \'field:(NOT X)\' -. +.ft C +$ knife search ubuntu +.ft P .fi -. -.IP "" 0 -. -.P -To find records where \fBfield1\fR is X and \fBfield2\fR is Y: -. -.IP "" 4 -. +.sp +or: +.sp .nf - -knife search INDEX \'field1:X AND field2:Y\' -. +.ft C +$ knife search node "tags:*ubuntu* OR roles:*ubuntu* OR fqdn:*ubuntu* (etc.)" +.ft P .fi -. -.IP "" 0 -. -.P -To find records where \fBfield\fR is X or Y: -. -.IP "" 4 -. +.sp +\fBOptions\fP +.sp +This sub\-command has the following options: +.INDENT 0.0 +.TP +.B \fB\-a ATTR\fP, \fB\-\-attribute ATTR\fP +The attribute (or attributes) to show. +.TP +.B \fB\-b ROW\fP, \fB\-\-start ROW\fP +The row at which return results will begin. +.TP +.B \fB\-i\fP, \fB\-\-id\-only\fP +Indicates that only matching object IDs will be shown. +.TP +.B \fBINDEX\fP +The name of the index to be queried: \fBclient\fP, \fBenvironment\fP, \fBnode\fP, \fBrole\fP, or \fBDATA_BAG_NAME\fP. Default index: \fBnode\fP. +.TP +.B \fB\-l\fP, \fB\-\-long\fP +Display long output when searching nodes while using the default summary format. +.TP +.B \fB\-m\fP, \fB\-\-medium\fP +Display more, but not all, of a node\(aqs data when searching using the default summary format. +.TP +.B \fB\-o SORT\fP, \fB\-\-sort SORT\fP +The order in which search results will be sorted. +.TP +.B \fB\-q SEARCH_QUERY\fP, \fB\-\-query SEARCH_QUERY\fP +Use to protect search queries that start with a hyphen (\-). A \fB\-q\fP query may be specified as an argument or an option, but not both. +.TP +.B \fB\-r\fP, \fB\-\-run\-list\fP +Indicates that only the run\-list will be shown. +.TP +.B \fB\-R INT\fP, \fB\-\-rows INT\fP +The number of rows to be returned. +.TP +.B \fBSEARCH_QUERY\fP +The search query used to identify a a list of items on a server. This option uses the same syntax as the \fBsearch\fP sub\-command. +.UNINDENT +.sp +\fBExamples\fP +.sp +To search for the IDs of all nodes running on the Amazon EC2 platform, enter: +.sp .nf - -knife search INDEX \'field:X OR field:Y\' -. +.ft C +$ knife search node \(aqec2:*\(aq \-i +.ft P .fi -. -.IP "" 0 -. -.SS "QUOTING AND SPECIAL CHARACTERS" -In order to avoid having special characters and escape sequences within your search term interpreted by either Ruby or the shell, enclose them in single quotes\. -. -.P -Search terms that include spaces should be enclosed in double\-quotes: -. -.IP "" 4 -. +.sp +to return something like: +.sp .nf +.ft C +4 items found -knife search INDEX \'field:"term with spaces"\' -. +ip\-0A7CA19F.ec2.internal + +ip\-0A58CF8E.ec2.internal + +ip\-0A58E134.ec2.internal + +ip\-0A7CFFD5.ec2.internal +.ft P .fi -. -.IP "" 0 -. -.P -The following characters must be escaped: -. -.IP "" 4 -. +.sp +To search for the instance type (flavor) of all nodes running on the Amazon EC2 platform, enter: +.sp .nf - -+ \- && || ! ( ) { } [ ] ^ " ~ * ? : \e -. +.ft C +$ knife search node \(aqec2:*\(aq \-a ec2.instance_type +.ft P .fi -. -.IP "" 0 -. -.SH "EXAMPLES" -Find the nodes with the fully\-qualified domain name (FQDN) www\.example\.com: -. -.IP "" 4 -. +.sp +to return something like: +.sp .nf +.ft C +4 items found -knife search node \'fqdn:www\.example\.com\' -. +ec2.instance_type: m1.large +id: ip\-0A7CA19F.ec2.internal + +ec2.instance_type: m1.large +id: ip\-0A58CF8E.ec2.internal + +ec2.instance_type: m1.large +id: ip\-0A58E134.ec2.internal + +ec2.instance_type: m1.large +id: ip\-0A7CFFD5.ec2.internal +.ft P .fi -. -.IP "" 0 -. -.P -Find the nodes running a version of Ubuntu: -. -.IP "" 4 -. +.sp +To search for all nodes running Ubuntu, enter: +.sp .nf - -knife search node \'platform:ubuntu*\' -. +.ft C +$ knife search node \(aqplatform:ubuntu\(aq +.ft P .fi -. -.IP "" 0 -. -.P -Find all nodes running CentOS in the production environment: -. -.IP "" 4 -. +.sp +To search for all nodes running CentOS in the production environment, enter: +.sp .nf - -knife search node \'chef_environment:production AND platform:centos\' -. +.ft C +$ knife search node \(aqchef_environment:production AND platform:centos\(aq +.ft P .fi +.sp +To find a nested attribute, use a pattern similar to the following: +.sp +.nf +.ft C +$ knife search node <query_to_run> \-a <main_attribute>.<nested_attribute> +.ft P +.fi +.sp +To build a search query to use more than one attribute, use an underscore ( _ ) to separate each attribute. For example, the following query will search for all nodes running a specific version of Ruby: +.sp +.nf +.ft C +$ knife search node "languages_ruby_version:1.9.3" +.ft P +.fi +.sp +To build a search query that can find a nested attribute: +.sp +.nf +.ft C +$ knife search node name:<node_name> \-a kernel.machine +.ft P +.fi +.sp +To test a search query that will be used in a \fBknife ssh\fP command: +.sp +.nf +.ft C +$ knife search node "role:web AND NOT name:web03" +.ft P +.fi +.sp +where the query in the previous example will search all servers that have the \fBweb\fP role, but not on the server named \fBweb03\fP. +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.IP "" 0 -. -.SH "KNOWN BUGS" -. -.IP "\(bu" 4 -Searches against the client index return no results in most cases\. (CHEF\-2477) -. -.IP "\(bu" 4 -Searches using the fuzzy match operator (~) produce an error\. (CHEF\-2478) -. -.IP "" 0 -. -.SH "SEE ALSO" -\fBknife\-ssh\fR(1) \fIhttp://wiki\.opscode\.com/display/chef/Attributes\fR Lucene Query Parser Syntax \fIhttp://lucene\.apache\.org/java/2_3_2/queryparsersyntax\.html\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/distro/common/man/man1/knife-show.1 b/distro/common/man/man1/knife-show.1 index da0aff8511..0612440672 100644 --- a/distro/common/man/man1/knife-show.1 +++ b/distro/common/man/man1/knife-show.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-SHOW" "1" "Chef 11.8" "" "knife show" +.TH "KNIFE-SHOW" "1" "Chef 11.8.0" "" "knife show" .SH NAME knife-show \- The man page for the knife show subcommand. . @@ -134,7 +134,5 @@ $ knife show roles/ environments/ .fi .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-ssh.1 b/distro/common/man/man1/knife-ssh.1 index 863dfcdcfc..41f47eecbd 100644 --- a/distro/common/man/man1/knife-ssh.1 +++ b/distro/common/man/man1/knife-ssh.1 @@ -1,79 +1,254 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-SSH" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\-ssh\fR \- Run a command or interactive session on multiple remote hosts -. -.SH "SYNOPSIS" -\fBknife\fR \fBssh QUERY COMMAND\fR \fI(options)\fR -. +.TH "KNIFE-SSH" "1" "Chef 11.8.0" "" "knife ssh" +.SH NAME +knife-ssh \- The man page for the knife ssh 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 \fBknife ssh\fP subcommand is used to invoke SSH commands (in parallel) on a subset of nodes within an organization, based on the results of a search query. +.sp +\fBCommon Options\fP +.sp +The following options can be run with all Knife sub\-commands and plug\-ins: +.INDENT 0.0 .TP -\fB\-a\fR, \fB\-\-attribute ATTR\fR -The attribute to use for opening the connection \- default is fqdn -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-C\fR, \fB\-\-concurrency NUM\fR -The number of concurrent connections -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -\fB\-m\fR, \fB\-\-manual\-list\fR -QUERY is a space separated list of servers -. +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. .TP -\fB\-P\fR, \fB\-\-ssh\-password PASSWORD\fR -The ssh password -. +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. .TP -\fB\-x\fR, \fB\-\-ssh\-user USERNAME\fR -The ssh username -. +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. .TP -\fB\-i\fR, \fB\-\-identity\-file IDENTITY_FILE\fR -The SSH identity file used for authentication -. +.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\-p\fR, \fB\-\-ssh\-port PORT\fR -The ssh port -. +.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\-\-[no\-]host\-key\-verify\fR -Verify host key, enabled by default\. -. -.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: -. +.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 -\fBinteractive\fR -A built\-in multiplexer\. \fBinteractive\fR supports running commands on a subset of the connected hosts in parallel -. +.B \fB\-h\fP, \fB\-\-help\fP +Shows help for the command. .TP -\fBscreen\fR(1) -Runs ssh interactively inside \fBscreen\fR\. ~/\.screenrc will be sourced if it exists\. -. +.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 -\fBtmux\fR(1) -Runs ssh interactively inside tmux\. -. +.B \fB\-\-no\-color\fP +Indicates that color will not be used in the output. .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\. +.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 +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife ssh SEARCH_QUERY SSH_COMMAND (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This subcommand has the following options: +.INDENT 0.0 +.TP +.B \fB\-a SSH_ATTR\fP, \fB\-\-attribute SSH_ATTR\fP +The attribute that is used when opening the SSH connection. The default attribute is the FQDN of the host. Other possible values include a public IP address, a private IP address, or a hostname. +.TP +.B \fB\-C NUM\fP, \fB\-\-concurrency NUM\fP +The number of allowed concurrent connections. +.TP +.B \fB\-G GATEWAY\fP, \fB\-\-ssh\-gateway GATEWAY\fP +The SSH tunnel or gateway that is used to run a bootstrap action on a machine that is not accessible from the workstation. +.TP +.B \fB\-i IDENTITY_FILE\fP, \fB\-\-identity\-file IDENTIFY_FILE\fP +The SSH identity file used for authentication. Key\-based authentication is recommended. +.TP +.B \fB\-m\fP, \fB\-\-manual\-list\fP +Indicates that a search query is a space\-separated list of servers. If there is more than one item in the list, put quotes around the entire list. For example: \fB\-\-manual\-list "server01 server 02 server 03"\fP +.TP +.B \fB\-\-[no\-]host\-key\-verify\fP +Use \fB\-\-no\-host\-key\-verify\fP to disable host key verification. Default setting: \fB\-\-host\-key\-verify\fP. +.TP +.B \fBOTHER\fP +The shell type. Possible values: \fBinteractive\fP, \fBscreen\fP, \fBtmux\fP, \fBmacterm\fP, or \fBcssh\fP. (\fBcsshx\fP is deprecated in favor of \fBcssh\fP.) +.TP +.B \fB\-p PORT\fP, \fB\-\-ssh\-port PORT\fP +The SSH port. +.TP +.B \fB\-P PASSWORD\fP, \fB\-\-ssh\-password PASSWORD\fP +The SSH password. This can be used to pass the password directly on the command line. If this option is not specified (and a password is required) Knife will prompt for the password. +.TP +.B \fBSEARCH_QUERY\fP +The search query used to return a list of servers to be accessed using SSH and the specified \fBSSH_COMMAND\fP. This option uses the same syntax as the search sub\-command. +.TP +.B \fBSSH_COMMAND\fP +The command that will be run against the results of a search query. +.TP +.B \fB\-x USER_NAME\fP, \fB\-\-ssh\-user USER_NAME\fP +The SSH user name. +.UNINDENT +.sp +\fBExamples\fP +.sp +To find the uptime of all of web servers running Ubuntu on the Amazon EC2 platform, enter: +.sp +.nf +.ft C +$ knife ssh "role:web" "uptime" \-x ubuntu \-a ec2.public_hostname +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +ec2\-174\-129\-127\-206.compute\-1.amazonaws.com 13:50:47 up 1 day, 23:26, 1 user, load average: 0.25, 0.18, 0.11 +ec2\-67\-202\-63\-102.compute\-1.amazonaws.com 13:50:47 up 1 day, 23:33, 1 user, load average: 0.12, 0.13, 0.10 +ec2\-184\-73\-9\-250.compute\-1.amazonaws.com 13:50:48 up 16:45, 1 user, load average: 0.30, 0.22, 0.13 +ec2\-75\-101\-240\-230.compute\-1.amazonaws.com 13:50:48 up 1 day, 22:59, 1 user, load average: 0.24, 0.17, 0.11 +ec2\-184\-73\-60\-141.compute\-1.amazonaws.com 13:50:48 up 1 day, 23:30, 1 user, load average: 0.32, 0.17, 0.15 +.ft P +.fi +.sp +To run the chef\-client on all nodes, enter: +.sp +.nf +.ft C +$ knife ssh \(aqname:*\(aq \(aqsudo chef\-client\(aq +.ft P +.fi +.sp +To force a chef\-client run on all of the web servers running Ubuntu on the Amazon EC2 platform, enter: +.sp +.nf +.ft C +$ knife ssh "role:web" "sudo chef\-client" \-x ubuntu \-a ec2.public_hostname +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +ec2\-67\-202\-63\-102.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:37 +0000] INFO: Starting Chef Run (Version 0.9.10) +ec2\-174\-129\-127\-206.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:37 +0000] INFO: Starting Chef Run (Version 0.9.10) +ec2\-184\-73\-9\-250.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:38 +0000] INFO: Starting Chef Run (Version 0.9.10) +ec2\-75\-101\-240\-230.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:38 +0000] INFO: Starting Chef Run (Version 0.9.10) +ec2\-184\-73\-60\-141.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:38 +0000] INFO: Starting Chef Run (Version 0.9.10) +ec2\-174\-129\-127\-206.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Chef Run complete in 1.419243 seconds +ec2\-174\-129\-127\-206.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: cleaning the checksum cache +ec2\-174\-129\-127\-206.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Running report handlers +ec2\-174\-129\-127\-206.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Report handlers complete +ec2\-67\-202\-63\-102.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Chef Run complete in 1.578265 seconds +ec2\-67\-202\-63\-102.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: cleaning the checksum cache +ec2\-67\-202\-63\-102.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Running report handlers +ec2\-67\-202\-63\-102.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:39 +0000] INFO: Report handlers complete +ec2\-184\-73\-9\-250.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Chef Run complete in 1.638884 seconds +ec2\-184\-73\-9\-250.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: cleaning the checksum cache +ec2\-184\-73\-9\-250.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Running report handlers +ec2\-184\-73\-9\-250.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Report handlers complete +ec2\-75\-101\-240\-230.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Chef Run complete in 1.540257 seconds +ec2\-75\-101\-240\-230.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: cleaning the checksum cache +ec2\-75\-101\-240\-230.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Running report handlers +ec2\-75\-101\-240\-230.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Report handlers complete +ec2\-184\-73\-60\-141.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Chef Run complete in 1.502489 seconds +ec2\-184\-73\-60\-141.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: cleaning the checksum cache +ec2\-184\-73\-60\-141.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Running report handlers +ec2\-184\-73\-60\-141.compute\-1.amazonaws.com [Fri, 22 Oct 2010 14:18:40 +0000] INFO: Report handlers complete +.ft P +.fi +.sp +To query for all nodes that have the "webserver" role and then use SSH to run the command "sudo chef\-client", enter: +.sp +.nf +.ft C +$ knife ssh "role:webserver" "sudo chef\-client" +.ft P +.fi +.sp +To upgrade all nodes, enter: +.sp +.nf +.ft C +$ knife ssh name:* "sudo aptitude upgrade \-y" +.ft P +.fi +.sp +To specify the shell type used on the nodes returned by a search query: +.sp +.nf +.ft C +$ knife ssh roles:opscode\-omnitruck macterm +.ft P +.fi +.sp +where \fBscreen\fP is one of the following values: \fBcssh\fP, \fBinteractive\fP, \fBmacterm\fP, \fBscreen\fP, or \fBtmux\fP. If the node does not have the shell type installed, Knife will return an error similar to the following: +.sp +.nf +.ft C +you need the rb\-appscript gem to use knife ssh macterm. +\(ga(sudo) gem install rb\-appscript\(ga to install +ERROR: LoadError: cannot load such file \-\- appscript +.ft P +.fi +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.SH "CHEF" -Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR diff --git a/distro/common/man/man1/knife-status.1 b/distro/common/man/man1/knife-status.1 index 9b040c22ca..0682fdca70 100644 --- a/distro/common/man/man1/knife-status.1 +++ b/distro/common/man/man1/knife-status.1 @@ -1,29 +1,207 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 +.TH "KNIFE-STATUS" "1" "Chef 11.8.0" "" "knife status" +.SH NAME +knife-status \- The man page for the knife status subcommand. . -.TH "KNIFE\-STATUS" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" +.nr rst2man-indent-level 0 . -.SH "NAME" -\fBknife\-status\fR \- Display status information for the nodes in your infrastructure -. -.SH "SYNOPSIS" -\fBknife\fR \fBstatus\fR \fI(options)\fR +.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 \fBknife status\fP subcommand is used to display a brief summary of the nodes on a server, including the time of the most recent successful chef\-client run. +.sp +\fBCommon Options\fP +.sp +The following options can be run with all Knife sub\-commands and plug\-ins: +.INDENT 0.0 .TP -\fB\-r\fR, \fB\-\-run\-list RUN_LIST\fR -Show the run list -. -.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\. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. +.TP +.B \fB\-\-color\fP +Indicates that colored output will be used. +.TP +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. +.TP +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. +.TP +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. +.TP +.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 +.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 +.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 +.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 +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife status (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This subcommand has the following options: +.INDENT 0.0 +.TP +.B \fBQUERY\fP +The search query used to identify a a list of items on a server. This option uses the same syntax as the \fBsearch\fP sub\-command. +.TP +.B \fB\-H\fP, \fB\-\-hide\-healthy\fP +Indicates that nodes on which a chef\-client run has occurred within the previous hour will be hidden. +.TP +.B \fB\-r RUN_LIST\fP, \fB\-\-run\-list RUN_LIST\fP +A comma\-separated list of roles and/or recipes to be applied. +.TP +.B \fB\-s\fP, \fB\-\-sort\-reverse\fP +Indicates that the list will be sorted by last run time, descending. +.UNINDENT +.sp +\fBExamples\fP +.sp +To include run lists in the status, enter: +.sp +.nf +.ft C +$ knife status \-\-run\-list +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +20 hours ago, dev\-vm.chisamore.com, ubuntu 10.04, dev\-vm.chisamore.com, 10.66.44.126, role[lb]. +3 hours ago, i\-225f954f, ubuntu 10.04, ec2\-67\-202\-63\-102.compute\-1.amazonaws.com, 67.202.63.102, role[web]. +3 hours ago, i\-a45298c9, ubuntu 10.04, ec2\-174\-129\-127\-206.compute\-1.amazonaws.com, 174.129.127.206, role[web]. +3 hours ago, i\-5272a43f, ubuntu 10.04, ec2\-184\-73\-9\-250.compute\-1.amazonaws.com, 184.73.9.250, role[web]. +3 hours ago, i\-226ca64f, ubuntu 10.04, ec2\-75\-101\-240\-230.compute\-1.amazonaws.com, 75.101.240.230, role[web]. +3 hours ago, i\-f65c969b, ubuntu 10.04, ec2\-184\-73\-60\-141.compute\-1.amazonaws.com, 184.73.60.141, role[web]. +.ft P +.fi +.sp +To show the status for nodes on which the chef\-client did not run successfully within the past hour, enter: +.sp +.nf +.ft C +$ knife status \-\-hide\-healthy +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +1 hour ago, i\-256f884f, ubuntu 12.04, ec2\-67\-202\-63\-102.compute\-1.amazonaws.com, 67.202.63.102, role[web]. +1 hour ago, i\-a47823c9, ubuntu 10.04, ec2\-174\-129\-127\-206.compute\-1.amazonaws.com, 184.129.143.111, role[lb]. +.ft P +.fi +.sp +To show the status of a subset of nodes that are returned by a specific query, enter: +.sp +.nf +.ft C +$ knife status "role:web" \-\-run\-list +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +3 hours ago, i\-225f954f, ubuntu 10.04, ec2\-67\-202\-63\-102.compute\-1.amazonaws.com, 67.202.63.102, role[web]. +3 hours ago, i\-a45298c9, ubuntu 10.04, ec2\-174\-129\-127\-206.compute\-1.amazonaws.com, 174.129.127.206, role[web]. +3 hours ago, i\-5272a43f, ubuntu 10.04, ec2\-184\-73\-9\-250.compute\-1.amazonaws.com, 184.73.9.250, role[web]. +3 hours ago, i\-226ca64f, ubuntu 10.04, ec2\-75\-101\-240\-230.compute\-1.amazonaws.com, 75.101.240.230, role[web]. +3 hours ago, i\-f65c969b, ubuntu 10.04, ec2\-184\-73\-60\-141.compute\-1.amazonaws.com, 184.73.60.141, role[web]. +.ft P +.fi +.sp +To view the status of all nodes in the organization, enter: +.sp +.nf +.ft C +$ knife status +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +20 hours ago, dev\-vm.chisamore.com, ubuntu 10.04, dev\-vm.chisamore.com, 10.66.44.126 +3 hours ago, i\-225f954f, ubuntu 10.04, ec2\-67\-202\-63\-102.compute\-1.amazonaws.com, 67.202.63.102 +3 hours ago, i\-a45298c9, ubuntu 10.04, ec2\-174\-129\-127\-206.compute\-1.amazonaws.com, 174.129.127.206 +3 hours ago, i\-5272a43f, ubuntu 10.04, ec2\-184\-73\-9\-250.compute\-1.amazonaws.com, 184.73.9.250 +3 hours ago, i\-226ca64f, ubuntu 10.04, ec2\-75\-101\-240\-230.compute\-1.amazonaws.com, 75.101.240.230 +3 hours ago, i\-f65c969b, ubuntu 10.04, ec2\-184\-73\-60\-141.compute\-1.amazonaws.com, 184.73.60.141 +.ft P +.fi +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.SH "CHEF" -Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR diff --git a/distro/common/man/man1/knife-tag.1 b/distro/common/man/man1/knife-tag.1 index 018f831e97..945912f35e 100644 --- a/distro/common/man/man1/knife-tag.1 +++ b/distro/common/man/man1/knife-tag.1 @@ -1,43 +1,180 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 +.TH "KNIFE-TAG" "1" "Chef 11.8.0" "" "knife tag" +.SH NAME +knife-tag \- The man page for the knife tag subcommand. . -.TH "KNIFE\-TAG" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" +.nr rst2man-indent-level 0 . -.SH "NAME" -\fBknife\-tag\fR \- Apply tags to nodes on a Chef Server +.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. . -.SH "SYNOPSIS" -\fBknife\fR \fBtag\fR \fIsubcommand\fR \fI(options)\fR +.sp +A tag is a custom description that is applied to a node. A tag, once applied, can be helpful when managing nodes using Knife or when building recipes by providing alternate methods of grouping similar types of information. +.sp +The \fBknife tag\fP subcommand is used to apply tags to nodes on a server. +.sp +This subcommand has the following syntax: +.sp +.nf +.ft C +$ knife tag [ARGUMENT] +.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 +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. +.TP +.B \fB\-\-color\fP +Indicates that colored output will be used. +.TP +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. +.TP +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. +.TP +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. +.TP +.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 +.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 +.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 +.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 CREATE +.sp +The \fBcreate\fP argument is used to add one or more tags to a node. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife tag create NODE_NAME [TAG...] +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To create tags named "seattle", "portland", and "vancouver", enter: +.sp +.nf +.ft C +$ knife tag create node seattle portland vancouver +.ft P +.fi +.SH DELETE +.sp +The \fBdelete\fP argument is used to delete one or more tags from a node. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife tag delete NODE_NAME [TAG...] +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.sp +\fBExamples\fP +.sp +To delete tags named "denver" and "phoenix", enter: +.sp +.nf +.ft C +$ knife tag delete node denver phoenix +.ft P +.fi +.sp +Type \fBY\fP to confirm a deletion. +.SH LIST +.sp +The \fBlist\fP argument is used to list all of the tags that have been applied to a node. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife tag list [NODE_NAME...] +.ft P +.fi +.sp +\fBOptions\fP +.sp +This command does not have any specific options. +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.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/distro/common/man/man1/knife-upload.1 b/distro/common/man/man1/knife-upload.1 index 91ebb198d5..f7498f861c 100644 --- a/distro/common/man/man1/knife-upload.1 +++ b/distro/common/man/man1/knife-upload.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-UPLOAD" "1" "Chef 11.8" "" "knife upload" +.TH "KNIFE-UPLOAD" "1" "Chef 11.8.0" "" "knife upload" .SH NAME knife-upload \- The man page for the knife upload subcommand. . @@ -235,7 +235,5 @@ $ knife upload \(gaknife deps nodes/*.json\(ga .fi .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-user.1 b/distro/common/man/man1/knife-user.1 index 7d6fada5ce..b8fe4583f0 100644 --- a/distro/common/man/man1/knife-user.1 +++ b/distro/common/man/man1/knife-user.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-USER" "1" "Chef 11.8" "" "knife user" +.TH "KNIFE-USER" "1" "Chef 11.8.0" "" "knife user" .SH NAME knife-user \- The man page for the knife user subcommand. . @@ -313,7 +313,5 @@ $ knife user show "Dennis Teck" \-F json Other formats available include \fBtext\fP, \fByaml\fP, and \fBpp\fP. .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife-xargs.1 b/distro/common/man/man1/knife-xargs.1 index 68710a19df..74f7bcaaab 100644 --- a/distro/common/man/man1/knife-xargs.1 +++ b/distro/common/man/man1/knife-xargs.1 @@ -1,4 +1,4 @@ -.TH "KNIFE-XARGS" "1" "Chef 11.8" "" "knife xargs" +.TH "KNIFE-XARGS" "1" "Chef 11.8.0" "" "knife xargs" .SH NAME knife-xargs \- The man page for the knife xargs subcommand. . @@ -162,7 +162,5 @@ $ knife deps nodes/*.json | xargs knife upload .fi .SH AUTHOR Opscode -.SH COPYRIGHT -This work is licensed under a Creative Commons Attribution 3.0 Unported License .\" Generated by docutils manpage writer. . diff --git a/distro/common/man/man1/knife.1 b/distro/common/man/man1/knife.1 index 4e157422d1..7e20d8a4c9 100644 --- a/distro/common/man/man1/knife.1 +++ b/distro/common/man/man1/knife.1 @@ -1,285 +1,228 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 +.TH "KNIFE" "1" "Chef 11.8.0" "" "knife" +.SH NAME +knife \- The man page for the knife command line tool. +. +.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 +Knife is a command\-line tool that provides an interface between a local chef\-repo and the server. Knife helps users to manage: +.INDENT 0.0 +.IP \(bu 2 +Nodes +.IP \(bu 2 +Cookbooks and recipes +.IP \(bu 2 +Roles +.IP \(bu 2 +Stores of JSON data (data bags), including encrypted data +.IP \(bu 2 +Environments +.IP \(bu 2 +Cloud resources, including provisioning +.IP \(bu 2 +The installation of the chef\-client on management workstations +.IP \(bu 2 +Searching of indexed data on the server +.UNINDENT +.sp +Knife subcommands: +.INDENT 0.0 +.IP \(bu 2 +knife bootstrap +.IP \(bu 2 +knife client +.IP \(bu 2 +knife configure +.IP \(bu 2 +knife cookbook +.IP \(bu 2 +knife cookbook site +.IP \(bu 2 +knife data bag +.IP \(bu 2 +knife delete +.IP \(bu 2 +knife deps +.IP \(bu 2 +knife diff +.IP \(bu 2 +knife download +.IP \(bu 2 +knife edit +.IP \(bu 2 +knife environment +.IP \(bu 2 +knife exec +.IP \(bu 2 +knife list +.IP \(bu 2 +knife node +.IP \(bu 2 +knife raw +.IP \(bu 2 +knife recipe list +.IP \(bu 2 +knife role +.IP \(bu 2 +knife search +.IP \(bu 2 +knife show +.IP \(bu 2 +knife ssh +.IP \(bu 2 +knife status +.IP \(bu 2 +knife tag +.IP \(bu 2 +knife upload +.IP \(bu 2 +knife user +.IP \(bu 2 +knife xargs +.UNINDENT +.SH WORKING WITH KNIFE +.sp +Knife runs from a management workstation and sits in\-between a server and an organization\(aqs infrastructure. Knife interacts with a server by using the same REST API that is used by a chef\-client. Role\-based authentication controls (RBAC) can be used to authorize changes when Knife is run with Hosted Chef or Private Chef. Knife is configured during workstation setup, but subsequent modifications can be made using the knife.rb configuration file. +.SS JSON Data Format +.sp +Most data is entered using a text editor in JSON format, unless the \fB\-\-disable\-editing\fP option is entered as part of a command. (Encrypted data bags use YAML, which is a superset of JSON.) JSON is a common, language\-independent data format that provides a simple text representation of arbitrary data structures. For more information about JSON, see \fI\%http://www.json.org/\fP or \fI\%http://en.wikipedia.org/wiki/JSON\fP. +.SS Set the Text Editor +.sp +Some Knife commands, such as \fBknife data bag edit\fP, require that information be edited as JSON data using a text editor. For example, the following command: +.sp +.nf +.ft C +$ knife data bag edit admins admin_name +.ft P +.fi +.sp +will open up the text editor with data similar to: +.sp +.nf +.ft C +{ + "id": "admin_name" +} +.ft P +.fi +.sp +Changes to that file can then be made: +.sp +.nf +.ft C +{ + "id": "Justin C." + "description": "I am passing the time by letting time pass over me ..." +} +.ft P +.fi +.sp +The type of text editor that is used by Knife can be configured by adding an entry to the knife.rb file or by setting an \fBEDITOR\fP environment variable. For example, to configure the text editor to always open with vim, add the following to the knife.rb file: +.sp +.nf +.ft C +knife[:editor] = "/usr/bin/vim" +.ft P +.fi +.sp +When a Microsoft Windows file path is enclosed in a double\-quoted string (" "), the same backslash character (\fB\e\fP) that is used to define the file path separator is also used in Ruby to define an escape character. The knife.rb file is a Ruby file; therefore, file path separators must be escaped. In addition, spaces in the file path must be replaced with \fB~1\fP so that the length of each section within the file path is not more than 8 characters. For example, if EditPad Pro is the text editor of choice and is located at the following path: +.sp +.nf +.ft C +C:\e\eProgram Files (x86)\eEditPad Pro\eEditPad.exe +.ft P +.fi +.sp +the setting in the knife.rb file would be similar to: +.sp +.nf +.ft C +knife[:editor] = "C:\e\eProgra~1\e\eEditPa~1\e\eEditPad.exe" +.ft P +.fi +.sp +One approach to working around the double\- vs. single\-quote issue is to put the single\-quotes outside of the double\-quotes. For example, for Notepad++: +.sp +.nf +.ft C +knife[:editor] = \(aq"C:\eProgram Files (x86)\eNotepad++\enotepad++.exe \-nosession \-multiInst"\(aq +.ft P +.fi +.sp +for Sublime Text: +.sp +.nf +.ft C +knife[:editor] = \(aq"C:\eProgram Files\eSublime Text 2\esublime_text.exe \-\-wait"\(aq +.ft P +.fi +.sp +for TextPad: +.sp +.nf +.ft C +knife[:editor] = \(aq"C:\eProgram Files (x86)\eTextPad 7\eTextPad.exe"\(aq +.ft P +.fi +.sp +and for vim: +.sp +.nf +.ft C +knife[:editor] = \(aq"C:\eProgram Files (x86)\evim\evim74\egvim.exe"\(aq +.ft P +.fi +.SS Using Quotes +.sp +Values can be entered with double quotes (" ") or single quotes (\(aq \(aq), but this should be done consistently. +.SS Sub\-commands +.sp +Knife comes with a collection of built in subcommands that work together to provide all of the functionality required to take specific actions against any object in an organization, including cookbooks, nodes, roles, data bags, environments, and users. A Knife plugin extends the functionality beyond built\-in subcommands. +.sp +Knife has the following subcommands: \fBbootstrap\fP, \fBclient\fP, \fBconfigure\fP, \fBcookbook\fP, \fBcookbook site\fP, \fBdata bag\fP, \fBdelete\fP, \fBdeps\fP, \fBdiff\fP, \fBdownload\fP, \fBedit\fP, \fBenvironment\fP, \fBexec\fP, \fBindex rebuild\fP, \fBlist\fP, \fBnode\fP, \fBrecipe list\fP, \fBrole\fP, \fBsearch\fP, \fBshow\fP, \fBssh\fP, \fBstatus\fP, \fBtag\fP, \fBupload\fP, \fBuser\fP, and \fBxargs\fP. +.IP Note +The following subcommands run only against the open source server: \fBindex rebuild\fP and \fBuser\fP. +.RE +.SS Syntax +.sp +All Knife subcommands have the following syntax: +.INDENT 0.0 +.INDENT 3.5 +knife subcommand [ARGUMENT] (options) +.UNINDENT +.UNINDENT +.sp +Each subcommand has its own set of arguments and options. +.IP Note +All syntax examples in this document show variables in ALL_CAPS. For example \fB\-u PORT_LIST\fP (where PORT_LIST is a comma\-separated list of local and public UDP ports) or \fB\-F FORMAT\fP (where FORMAT determines the output format, either \fBsummary\fP, \fBtext\fP, \fBjson\fP, \fByaml\fP, or \fBpp\fP). These variables often require specific values that are unique to each organization. +.RE +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.TH "KNIFE" "1" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\fR \- Chef Server API client utility -. -.SH "SYNOPSIS" -\fBknife\fR \fIsub\-command\fR [\fIargument\fR\.\.\.] \fI(options)\fR -. -.SH "DESCRIPTION" -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: -. -.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 -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 "OPTIONS" -. -.TP -\fB\-s\fR, \fB\-\-server\-url\fR URL -Chef Server URL, corresponds to \fBChef::Config\fR \fBchef_server_url\fR\. -. -.TP -\fB\-k\fR, \fB\-\-key\fR KEY -API Client Key, corresponds to \fBChef::Config\fR \fBclient_key\fR\. -. -.TP -\fB\-c\fR, \fB\-\-config\fR CONFIG -The configuration file to use -. -.TP -\fB\-E\fR, \fB\-\-environment ENVIRONMENT\fR -Set the Chef environment -. -.TP -\fB\-e\fR, \fB\-\-editor\fR EDITOR -Set the editor to use for interactive commands -. -.TP -\fB\-F\fR, \fB\-\-format\fR FORMAT -Which format to use for output\. See FORMATS for details\. -. -.TP -\fB\-d\fR, \fB\-\-disable\-editing\fR -Do not open EDITOR, just accept the data as is -. -.TP -\fB\-u\fR, \fB\-\-user\fR USER -API Client Username, corresponds to \fBChef::Config\fR \fBnode_name\fR\. -. -.TP -\fB\-p\fR, \fB\-\-print\-after\fR -Show the data after a destructive operation -. -.TP -\fB\-v\fR, \fB\-\-version\fR -Show chef version -. -.TP -\fB\-V\fR, \fB\-\-verbose\fR -More verbose output\. Use twice for max verbosity\. -. -.TP -\fB\-y\fR, \fB\-\-yes\fR -Say yes to all prompts for confirmation -. -.TP -\fB\-\-defaults\fR -Accept default values for all questions -. -.TP -\fB\-\-[no\-]color\fR -Use colored output\. Color enabled by default\. -. -.TP -\fB\-h\fR, \fB\-\-help\fR -Show the available options for a command\. -. -.SH "SUB\-COMMANDS" -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) -. -.IP "\(bu" 4 -list and show (read) -. -.IP "\(bu" 4 -edit (update) -. -.IP "\(bu" 4 -delete (destroy) -. -.IP "" 0 -. -.P -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\. -. -.P -If the config file exists, knife uses these settings for \fBGENERAL OPTIONS\fR defaults\. -. -.IP "\(bu" 4 -\fBnode_name\fR: User or client identity (i\.e\., \fIname\fR) to use for authenticating requests to the Chef Server\. -. -.IP "\(bu" 4 -\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 -\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 -\fBsyntax_check_cache_path\fR: Specifies the path to a directory where knife caches information about files that it has syntax checked\. -. -.IP "\(bu" 4 -\fBvalidation_client_name\fR: Specifies the name of the client used to validate new clients\. -. -.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\. -. -.IP "\(bu" 4 -\fBcookbook_copyright\fR, \fBcookbook_email\fR, \fBcookbook_license\fR, \fBreadme_format\fR Used by \fBknife cookbook create\fR sub\-command to specify the copyright holder, maintainer email, license and readme format (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\. Currently supported readme formats are "md", "mkd", "txt", and "rdoc"\. Any other value will result in an unformatted README\. -. -.IP "" 0 -. -.SH "FILES" -\fI~/\.chef/knife\.rb\fR -. -.P -Ruby DSL configuration file for knife\. See \fBCONFIGURATION\fR\. -. -.SH "FORMATS" -The amount of content displayed and the output format are modified by the \fB\-\-format\fR option\. If no alternate format is selected, the default is summary\. -. -.P -Valid formats are: -. -.TP -\fBsummary\fR -displays the node in a custom, summarized format (default) -. -.TP -\fBtext\fR -displays the node data in its entirety using the colorized tree display -. -.TP -\fBjson\fR -displays the node in JSON format -. -.TP -\fByaml\fR -displays the node in YAML format -. -.TP -\fBpp\fR -displays the node using Ruby\'s pretty printer\. -. -.P -For brevity, only the first character of the format is required, for example, \-Fj will produce JSON format output\. -. -.SH "CHEF WORKFLOW" -When working with Chef and Knife in the local repository, the recommended workflow outline looks like: -. -.IP "\(bu" 4 -Create repository\. A skeleton sample is provided at \fIhttp://github\.com/opscode/chef\-repo/\fR\. -. -.IP "\(bu" 4 -Configure knife, see \fBCONFIGURATION\fR\. -. -.IP "\(bu" 4 -Download cookbooks from the Opscode cookbooks site, see \fBCOOKBOOK SITE SUB\-COMMANDS\fR\. -. -.IP "\(bu" 4 -Or, create new cookbooks, see \fBcookbook create\fR sub\-command\. -. -.IP "\(bu" 4 -Commit changes to the version control system\. See your tool\'s documentation\. -. -.IP "\(bu" 4 -Upload cookbooks to the Chef Server, see \fBCOOKBOOK SUB\-COMMANDS\fR\. -. -.IP "\(bu" 4 -Launch instances in the Cloud, OR provision new hosts; see \fBCLOUD COMPUTING SUB\-COMMANDS\fR and \fBBOOTSTRAP SUB\-COMMANDS\fR\. -. -.IP "\(bu" 4 -Watch Chef configure systems! -. -.IP "" 0 -. -.P -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" -. -.SH "ENVIRONMENT" -. -.TP -\fBEDITOR\fR -The text editor to use for editing data\. The \-\-editor option takes precedence over this value, and the \-\-disable\-editing option supresses data editing entirely\. -. -.SH "SEE ALSO" -\fBchef\-client(8)\fR \fBchef\-server(8)\fR \fBchef\-shell(1)\fR -. -.P -\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 -Complete Chef documentation is available online: \fIhttp://wiki\.opscode\.com/display/chef/Home/\fR -. -.P -JSON is JavaScript Object Notation \fIhttp://json\.org/\fR -. -.P -SOLR is an open source search engine\. \fIhttp://lucene\.apache\.org/solr/\fR -. -.P -\fBgit(1)\fR is a version control system \fIhttp://git\-scm\.com/\fR -. -.P -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/distro/common/man/man1/ohai.1 b/distro/common/man/man1/ohai.1 new file mode 100644 index 0000000000..1a06bb74ff --- /dev/null +++ b/distro/common/man/man1/ohai.1 @@ -0,0 +1,85 @@ +.TH "OHAI" "1" "Ohai 6.20.0" "" "ohai" +.SH NAME +ohai \- The man page for the ohai command line tool. +. +.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 +Ohai is a tool that is used to detect attributes on a node, and then provide these attributes to the chef\-client at the start of every chef\-client run. Ohai is required by the chef\-client and must be present on a node. The types of attributes Ohai collects include: +.INDENT 0.0 +.IP \(bu 2 +Platform details +.IP \(bu 2 +Networking usage +.IP \(bu 2 +Memory usage +.IP \(bu 2 +Processor usage +.IP \(bu 2 +Kernel data +.IP \(bu 2 +Host names +.IP \(bu 2 +Fully qualified domain names +.IP \(bu 2 +Other configuration details +.UNINDENT +.sp +Attributes that are collected by Ohai are automatic attributes, in that these attributes are used by the chef\-client to ensure that these attributes remain unchanged after the chef\-client is done configuring the node. +.sp +ohai is the command\-line interface for Ohai, a tool that is used to detect attributes on a node, and then provide these attributes to the chef\-client at the start of every chef\-client run. +.SH OPTIONS +.sp +This command has the following syntax: +.sp +.nf +.ft C +ohai OPTION +.ft P +.fi +.sp +This tool has the following options: +.INDENT 0.0 +.TP +.B \fB\-d PATH\fP, \fB\-\-directory PATH\fP +The directory in which Ohai plugins are located. For example: \fB/etc/ohai/plugins\fP. +.TP +.B \fB\-f FILE_NAME\fP, \fB\-\-file FILE_NAME\fP +The file against which Ohai will run. +.TP +.B \fB\-l LEVEL\fP, \fB\-\-log_level LEVEL\fP +The level of logging that will be stored in a log file: \fBdebug\fP, \fBinfo\fP, \fBwarn\fP, \fBerror\fP, or \fBfatal\fP. +.TP +.B \fB\-h\fP, \fB\-\-help\fP +Shows help for the command. +.UNINDENT +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. +. diff --git a/distro/common/man/man8/chef-client.8 b/distro/common/man/man8/chef-client.8 index 68a3d1ede2..68a77c4ef6 100644 --- a/distro/common/man/man8/chef-client.8 +++ b/distro/common/man/man8/chef-client.8 @@ -1,104 +1,270 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 +.TH "CHEF-CLIENT" "8" "Chef 11.8.0" "" "chef-client" +.SH NAME +chef-client \- The man page for the chef-client command line tool. . -.TH "CHEF\-CLIENT" "8" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" +.nr rst2man-indent-level 0 . -.SH "NAME" -\fBchef\-client\fR \- Runs a client node connecting to a chef\-server\. -. -.SH "SYNOPSIS" -\fBchef\-client\fR \fI(options)\fR +.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 +A chef\-client is an agent that runs locally on every node that is registered with the server. When a chef\-client is run, it will perform all of the steps that are required to bring the node into the expected state, including: +.INDENT 0.0 +.IP \(bu 2 +Registering and authenticating the node with the server +.IP \(bu 2 +Building the node object +.IP \(bu 2 +Synchronizing cookbooks +.IP \(bu 2 +Compiling the resource collection by loading each of the required cookbooks, including recipes, attributes, and all other dependencies +.IP \(bu 2 +Taking the appropriate and required actions to configure the node +.IP \(bu 2 +Looking for exceptions and notifications, handling each as required +.UNINDENT +.sp +The chef\-client executable can be run as a command\-line tool. +.IP Note +A client.rb file is used to specify the configuration details for the chef\-client. This file is the default configuration file and is loaded every time the chef\-client executable is run. The chef\-client executable can be run as a daemon. On UNIX\- and Linux\-based machines, the configuration file is located at: /etc/chef/client.rb. On Microsoft Windows machines, the configuration file is located at C:chefclient.rb. +.RE +.SH OPTIONS +.sp +This command has the following syntax: +.sp +.nf +.ft C +chef\-client OPTION VALUE OPTION VALUE ... +.ft P +.fi +.sp +This command has the following options: +.INDENT 0.0 .TP -\fB\-S\fR, \fB\-\-server CHEFSERVERURL\fR -The chef server URL -. +.B \fB\-A\fP, \fB\-\-fatal\-windows\-admin\-check\fP +Indicates that a chef\-client run should fail if the chef\-client does not have administrator privileges in Microsoft Windows. .TP -\fB\-c\fR, \fB\-\-config CONFIG\fR -The configuration file to use -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-d\fR, \fB\-\-daemonize\fR -Daemonize the process -. +.B \fB\-d\fP, \fB\-\-daemonize\fP +Indicates that the executable will be run as a daemon. This option is only available on machines that run in UNIX or Linux environments. For machines that are running Microsoft Windows that require similar functionality, use the \fBchef\-client::service\fP recipe in the \fBchef\-client\fP cookbook: \fI\%http://community.opscode.com/cookbooks/chef-client\fP. This will install a chef\-client service under Microsoft Windows using the Windows Service Wrapper. .TP -\fB\-g\fR, \fB\-\-group GROUP\fR -Group to set privilege to -. +.B \fB\-E ENVIRONMENT_NAME\fP, \fB\-\-environment ENVIRONMENT_NAME\fP +The name of the environment. .TP -\fB\-i\fR, \fB\-\-interval SECONDS\fR -Run chef\-client periodically, in seconds -. +.B \fB\-\-[no\-]fork\fP +Indicates that a chef\-client run will be contained in a secondary process with dedicated RAM. When the chef\-client run is complete the RAM will be returned to the master process. This option helps ensure that a chef\-client will use a steady amount of RAM over time because the master process will not run recipes. This option will also help prevent memory leaks (such as those that can be introduced by the code contained within a poorly designed cookbook). Use \fB\-\-no\-fork\fP to disable running the chef\-client in fork node. Default value: \fB\-\-fork\fP. .TP -\fB\-j\fR, \fB\-\-json\-attributes JSON_ATTRIBS\fR -Load attributes from a JSON file or URL -. +.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\-E\fR, \fB\-\-environment ENVIRONMENT\fR -Set the Chef Environment on the node -. +.B \fB\-\-force\-formatter\fP +Indicates that formatter output will be used instead of logger output. .TP -\fB\-l\fR, \fB\-\-log_level LEVEL\fR -Set the log level (debug, info, warn, error, fatal) -. +.B \fB\-\-force\-logger\fP +Indicates that logger output will be used instead of formatter output. .TP -\fB\-L\fR, \fB\-\-logfile LOGLOCATION\fR -Set the log file location, defaults to STDOUT \- recommended for daemonizing -. +.B \fB\-g GROUP\fP, \fB\-\-group GROUP\fP +The name of the group that owns a process. This is required when starting any executable as a daemon. .TP -\fB\-N\fR, \fB\-\-node\-name NODE_NAME\fR -The node name for this client -. +.B \fB\-h\fP, \fB\-\-help\fP +Shows help for the command. .TP -\fB\-o\fR, \fB\-\-override\-runlist\fR -Replace current run list with specified items -. +.B \fB\-i SECONDS\fP, \fB\-\-interval SECONDS\fP +The frequency (in seconds) at which the chef\-client runs. This value is configured for the chef\-client application run time, rather than in \fBChef::Config\fP. Default value: \fB1800\fP. .TP -\fB\-K\fR, \fB\-\-validation_key KEY_FILE\fR -Set the validation key file location, used for registering new clients -. +.B \fB\-j PATH\fP, \fB\-\-json\-attributes PATH\fP +The path to a file that contains JSON data. Use this option to override attributes that are set from other locations, such as from within a cookbook or by a role. .TP -\fB\-k\fR, \fB\-\-client_key KEY_FILE\fR -Set the client key file location -. +.B \fB\-k KEY_FILE\fP, \fB\-\-client_key KEY_FILE\fP +The location of the file which contains the client key. Default value: \fB/etc/chef/client.pem\fP. .TP -\fB\-s\fR, \fB\-\-splay SECONDS\fR -The splay time for running at intervals, in seconds -. +.B \fB\-K KEY_FILE\fP, \fB\-\-validation_key KEY_FILE\fP +The location of the file which contains the key used when a chef\-client is registered with a server. A validation key is signed using the \fBvalidation_client_name\fP for authentication. Default value: \fB/etc/chef/validation.pem\fP. .TP -\fB\-u\fR, \fB\-\-user USER\fR -User to set privilege to -. +.B \fB\-l LEVEL\fP, \fB\-\-log_level LEVEL\fP +The level of logging that will be stored in a log file: \fBdebug\fP, \fBinfo\fP, \fBwarn\fP, \fBerror\fP, or \fBfatal\fP. .TP -\fB\-P\fR, \fB\-\-pid PIDFILE\fR -Set the PID file location, defaults to /tmp/chef\-client\.pid -. +.B \fB\-L LOGLOCATION\fP, \fB\-\-logfile c\fP +The location in which log file output files will be saved. If this location is set to something other than \fBSTDOUT\fP, standard output logging will still be performed (otherwise there would be no output other than to a file). This is recommended when starting any executable as a daemon. Default value: \fBSTDOUT\fP. .TP -\fB\-\-once\fR -Cancel any interval or splay options, run chef once and exit -. +.B \fB\-\-[no\-]color\fP +Indicates that color will not be used in the output. Default setting: \fB\-\-color\fP. .TP -\fB\-v\fR, \fB\-\-version\fR -Show chef version -. +.B \fB\-N NODE_NAME\fP, \fB\-\-node\-name NODE_NAME\fP +The name of the node. .TP -\fB\-h\fR, \fB\-\-help\fR -Show this message -. -.SH "DESCRIPTION" -The Chef Client is where almost all of the work in Chef is done\. It communicates with the Chef Server via REST, authenticates via Signed Header Authentication, and compiles and executes Cookbooks\. -. -.P -A Chef Client does work on behalf of a Node\. A single Chef Client can run recipes for multiple Nodes\. -. -.P -Clients are where all the action happens \- the Chef Server and Chef Expander are largely services that exist only to provide the Client with information\. -. -.SH "SEE ALSO" -Full documentation for Chef and chef\-client is located on the Chef wiki, http://wiki\.opscode\.com/display/chef/Home\. -. -.SH "AUTHOR" -Chef was written by Adam Jacob \fIadam@ospcode\.com\fR of Opscode (http://www\.opscode\.com), with contributions from the community\. This manual page was written by Joshua Timberman \fIjoshua@opscode\.com\fR with help2man\. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2\.0 License\. +.B \fB\-o RUN_LIST_ITEM\fP, \fB\-\-override\-runlist RUN_LIST_ITEM\fP +Replace the current run list with the specified items. +.TP +.B \fB\-\-once\fP +Indicates that the chef\-client is run once and that interval and splay options are cancelled. +.TP +.B \fB\-P PID_FILE\fP, \fB\-\-pid PID_FILE\fP +The location in which a process identification number (pid) is saved. An executable, when started as a daemon, will write the pid to the specified file. Default value: \fB/tmp/name\-of\-executable.pid\fP. +.TP +.B \fB\-R\fP, \fB\-\-enable\-reporting\fP +Indicates that data collection reporting is enabled during a chef\-client run. +.TP +.B \fB\-s SECONDS\fP, \fB\-\-splay SECONDS\fP +A number (in seconds) to add to the \fBinterval\fP that is used to determine the frequency of chef\-client runs. This number can help prevent server load when there are many clients running at the same time. +.TP +.B \fB\-S CHEF_SERVER_URL\fP, \fB\-\-server CHEF_SERVER_URL\fP +The URL for the server. +.TP +.B \fB\-u USER\fP, \fB\-\-user USER\fP +The user that owns a process. This is required when starting any executable as a daemon. +.TP +.B \fB\-v\fP, \fB\-\-version\fP +The version of the chef\-client. +.TP +.B \fB\-W\fP, \fB\-\-why\-run\fP +Indicates that the executable will be run in why\-run mode, which is a type of chef\-client run that does everything except modify the system. Use why\-run mode to understand why the chef\-client makes the decisions that it makes and to learn more about the current and proposed state of the system. +.UNINDENT +.SH RUN WITH ELEVATED PRIVILEGES +.sp +The chef\-client may need to be run with elevated privileges in order to get a recipe to converge correctly. On UNIX and UNIX\-like operating systems this can be done by running the command as root. On Microsoft Windows this can be done by running the command prompt as an administrator. +.SS Linux +.sp +On Linux, the following error sometimes occurs when the permissions used to run the chef\-client are incorrect: +.sp +.nf +.ft C +$ chef\-client +[Tue, 29 Nov 2011 19:46:17 \-0800] INFO: *** Chef 10.X.X *** +[Tue, 29 Nov 2011 19:46:18 \-0800] WARN: Failed to read the private key /etc/chef/client.pem: #<Errno::EACCES: Permission denied \- /etc/chef/client.pem> +.ft P +.fi +.sp +This can be resolved by running the command as root. There are a few ways this can be done: +.INDENT 0.0 +.IP \(bu 2 +Log in as root and then run the chef\-client +.IP \(bu 2 +Use \fBsu\fP to become the root user, and then run the chef\-client. For example: +.INDENT 2.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ su +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.sp +and then: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ chef\-client +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.IP \(bu 2 +Use the sudo utility +.INDENT 2.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ sudo chef\-client +.ft P +.fi +.UNINDENT +.UNINDENT +.IP \(bu 2 +Give a user access to read \fB/etc/chef\fP and also the files accessed by the chef\-client. This requires super user privileges and, as such, is not a recommended approach +.UNINDENT +.SS Windows +.sp +On Microsoft Windows, running without elevated privileges (when they are necessary) is an issue that fails silently. It will appear that the chef\-client completed its run successfully, but the changes will not have been made. When this occurs, do one of the following to run the chef\-client as the administrator: +.INDENT 0.0 +.IP \(bu 2 +Log in to the administrator account. (This is not the same as an account in the administrator\(aqs security group.) +.IP \(bu 2 +Run the chef\-client process from the administrator account while being logged into another account. Run the following command: +.INDENT 2.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ runas /user:Administrator "cmd /C chef\-client" +.ft P +.fi +.sp +This will prompt for the administrator account password. +.UNINDENT +.UNINDENT +.IP \(bu 2 +Open a command prompt by right\-clicking on the command prompt application, and then selecting \fBRun as administrator\fP. After the command window opens, the chef\-client can be run as the administrator +.UNINDENT +.SH EXAMPLES +.sp +\fBStart a Chef run when the chef\-client is running as a daemon\fP +.sp +A chef\-client that is running as a daemon can be woken up and started by sending the process a \fBSIGUSR1\fP. For example, to trigger a chef\-client run on a machine running Linux: +.sp +.nf +.ft C +$ sudo killall \-USR1 chef\-client +.ft P +.fi +.sp +\fBStart a Chef run manually\fP +.sp +.nf +.ft C +$ ps auxw|grep chef\-client +.ft P +.fi +.sp +to return something like: +.sp +.nf +.ft C +root 66066 0.9 0.0 2488880 264 s001 S+ 10:26AM 0:03.05 +/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/ruby /usr/bin/chef\-client \-i 3600 \-s 20 +.ft P +.fi +.sp +and then enter: +.sp +.nf +.ft C +$ sudo kill \-USR1 66066 +.ft P +.fi +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.P -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/distro/common/man/man8/chef-solo.8 b/distro/common/man/man8/chef-solo.8 index 24eaf3bcd6..b3ee9a0a5d 100644 --- a/distro/common/man/man8/chef-solo.8 +++ b/distro/common/man/man8/chef-solo.8 @@ -1,126 +1,158 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "CHEF\-SOLO" "8" "October 2013" "Chef 11.10.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBchef\-solo\fR \- Runs chef in solo mode against a specified cookbook location\. -. -.SH "SYNOPSIS" -\fBchef\-solo\fR \fI(options)\fR -. +.TH "CHEF-SOLO" "8" "Chef 11.8.0" "" "chef-solo" +.SH NAME +chef-solo \- The man page for the chef-solo command line tool. +. +.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 +chef\-solo is an open source version of the chef\-client that allows using cookbooks with nodes without requiring access to a server. chef\-solo runs locally and requires that a cookbook (and any of its dependencies) be on the same physical disk as the node. chef\-solo is a limited\-functionality version of the chef\-client and \fBdoes not support\fP the following: +.INDENT 0.0 +.IP \(bu 2 +Node data storage +.IP \(bu 2 +Search indexes +.IP \(bu 2 +Centralized distribution of cookbooks +.IP \(bu 2 +A centralized API that interacts with and integrates infrastructure components +.IP \(bu 2 +Authentication or authorization +.IP \(bu 2 +Persistent attributes +.UNINDENT +.sp +The chef\-solo executable can be run as a command\-line tool. +.SH OPTIONS +.sp +This command has the following syntax: +.sp +.nf +.ft C +chef\-solo OPTION VALUE OPTION VALUE ... +.ft P +.fi +.sp +This command has the following options: +.INDENT 0.0 .TP -\fB\-c\fR, \fB\-\-config CONFIG\fR -The configuration file to use -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-d\fR, \fB\-\-daemonize\fR -Daemonize the process -. +.B \fB\-d\fP, \fB\-\-daemonize\fP +Indicates that the executable will be run as a daemon. This option is only available on machines that run in UNIX or Linux environments. For machines that are running Microsoft Windows that require similar functionality, use the \fBchef\-client::service\fP recipe in the \fBchef\-client\fP cookbook: \fI\%http://community.opscode.com/cookbooks/chef-client\fP. This will install a chef\-client service under Microsoft Windows using the Windows Service Wrapper. .TP -\fB\-g\fR, \fB\-\-group GROUP\fR -Group to set privilege to -. +.B \fB\-f\fP, \fB\-\-fork\fP +Indicates that a chef\-client run will be contained in a secondary process with dedicated RAM. When the chef\-client run is complete the RAM will be returned to the master process. This option helps ensure that a chef\-client will use a steady amount of RAM over time because the master process will not run recipes. This option will also help prevent memory leaks (such as those that can be introduced by the code contained within a poorly designed cookbook). .TP -\fB\-i\fR, \fB\-\-interval SECONDS\fR -Run chef\-client periodically, in seconds -. +.B \fB\-F FORMATTER\fP, \fB\-\-format FORMATTER\fP +The output format. .TP -\fB\-j\fR, \fB\-\-json\-attributes JSON_ATTRIBS\fR -Load attributes from a JSON file or URL -. +.B \fB\-\-force\-formatter\fP +Indicates that formatter output will be used instead of logger output. .TP -\fB\-l\fR, \fB\-\-log_level LEVEL\fR -Set the log level (debug, info, warn, error, fatal) -. +.B \fB\-\-force\-logger\fP +Indicates that logger output will be used instead of formatter output. .TP -\fB\-L\fR, \fB\-\-logfile LOGLOCATION\fR -Set the log file location, defaults to STDOUT \- recommended for daemonizing -. +.B \fB\-g GROUP\fP, \fB\-\-group GROUP\fP +The name of the group that owns a process. This is required when starting any executable as a daemon. .TP -\fB\-N\fR, \fB\-\-node\-name NODE_NAME\fR -The node name for this client -. +.B \fB\-h\fP, \fB\-\-help\fP +Shows help for the command. .TP -\fB\-r\fR, \fB\-\-recipe\-url RECIPE_URL\fR -Pull down a remote gzipped tarball of recipes and untar it to the cookbook cache\. -. +.B \fB\-i SECONDS\fP, \fB\-\-interval SECONDS\fP +The frequency (in seconds) at which the chef\-client runs. This value is configured for the chef\-client application run time, rather than in \fBChef::Config\fP. .TP -\fB\-s\fR, \fB\-\-splay SECONDS\fR -The splay time for running at intervals, in seconds -. +.B \fB\-j PATH\fP, \fB\-\-json\-attributes PATH\fP +The path to a file that contains JSON data. Use this option to override attributes that are set from other locations, such as from within a cookbook or by a role. .TP -\fB\-u\fR, \fB\-\-user USER\fR -User to set privilege to -. +.B \fB\-l LEVEL\fP, \fB\-\-log_level LEVEL\fP +The level of logging that will be stored in a log file: \fBdebug\fP, \fBinfo\fP, \fBwarn\fP, \fBerror\fP, or \fBfatal\fP. .TP -\fB\-v\fR, \fB\-\-version\fR -Show chef version -. +.B \fB\-L LOGLOCATION\fP, \fB\-\-logfile c\fP +The location in which log file output files will be saved. If this location is set to something other than \fBSTDOUT\fP, standard output logging will still be performed (otherwise there would be no output other than to a file). This is recommended when starting any executable as a daemon. .TP -\fB\-h\fR, \fB\-\-help\fR -Show this message -. -.SH "DESCRIPTION" -Chef Solo allows you to run Chef Cookbooks in the absence of a Chef Server\. To do this, the complete cookbook needs to be present on disk\. -. -.P -By default Chef Solo will look in /etc/chef/solo\.rb for its configuration\. This configuration file has two required variables: file_cache_path and cookbook_path\. -. -.P -For example: file_cache_path "/var/chef\-solo" cookbook_path "/var/chef\-solo/cookbooks" -. -.P -For your own systems, you can change this to reflect any directory you like, but you\'ll need to specify absolute paths and the cookbook_path directory should be a subdirectory of the file_cache_path\. -. -.P -You can also specify cookbook_path as an array, passing multiple locations to search for cookbooks\. -. -.P -For example: file_cache_path "/var/chef\-solo" cookbook_path ["/var/chef\-solo/cookbooks", "/var/chef\-solo/site\-cookbooks"] -. -.P -Note that earlier entries are now overridden by later ones\. -. -.P -Since chef\-solo doesn\'t have any interaction with a Chef Server, you\'ll need to specify node\-specifc attributes in a JSON file\. This can be located on the target system itself, or it can be stored on a remote server such as S3, or a web server on your network\. -. -.P -Within the JSON file, you\'ll also specify the recipes that Chef should run in the "run_list"\. An example JSON file, which sets a resolv\.conf: -. -.IP "" 4 -. +.B \fB\-\-[no\-]color\fP +Use \fB\-\-no\-color\fP to disable colored output. Default setting: \fB\-\-color\fP. +.TP +.B \fB\-N NODE_NAME\fP, \fB\-\-node\-name NODE_NAME\fP +The name of the node. +.TP +.B \fB\-o RUN_LIST_ITEM\fP, \fB\-\-override\-runlist RUN_LIST_ITEM\fP +Replace the current run list with the specified items. +.TP +.B \fB\-r RECIPE_URL\fP, \fB\-\-recipe\-url RECIPE_URL\fP +The URL location from which a remote cookbook tar.gz will be downloaded. +.TP +.B \fB\-s SECONDS\fP, \fB\-\-splay SECONDS\fP +A number (in seconds) to add to the \fBinterval\fP that is used to determine the frequency of chef\-client runs. This number can help prevent server load when there are many clients running at the same time. +.TP +.B \fB\-u USER\fP, \fB\-\-user USER\fP +The user that owns a process. This is required when starting any executable as a daemon. +.TP +.B \fB\-v\fP, \fB\-\-version\fP +The version of the chef\-client. +.TP +.B \fB\-W\fP, \fB\-\-why\-run\fP +Indicates that the executable will be run in whyrun mode, which is a chef\-client run that does everything except modify the system. Use whyrun mode to understand why the chef\-client makes the decisions that it makes and to learn more about the current and proposed state of the system. +.UNINDENT +.SH EXAMPLES +.sp +\fBUse a URL\fP +.sp .nf - -{ - "resolver": { - "nameservers": [ "10\.0\.0\.1" ], - "search":"int\.example\.com" - }, - "run_list": [ "recipe[resolver]" ] -} -. +.ft C +$ chef\-solo \-c ~/solo.rb \-j ~/node.json \-r http://www.example.com/chef\-solo.tar.gz +.ft P .fi +.sp +where \fB\-r\fP uses the \fBremote_file\fP resource to retrieve the tar.gz archive into the \fBfile_cache_path\fP, and then extract it to \fBcookbooks_path\fP. +.sp +\fBUse a directory\fP +.sp +.nf +.ft C +$ chef\-solo \-c ~/solo.rb \-j ~/node.json +.ft P +.fi +.sp +where the \fB\-r URL\fP option is not used. chef\-solo will look in the solo.rb file to determine the directory in which cookbooks are located. +.sp +\fBUse a URL for cookbook and JSON data\fP +.sp +.nf +.ft C +$ chef\-solo \-c ~/solo.rb \-j http://www.example.com/node.json \-r http://www.example.com/chef\-solo.tar.gz +.ft P +.fi +.sp +where \fB\-r\fP corresponds to \fBrecipe_url\fP and \fB\-j\fP corresponds to \fBjson_attribs\fP, both of which are configuration options in solo.rb. +.SH AUTHOR +Opscode +.\" Generated by docutils manpage writer. . -.IP "" 0 -. -.P -Then you can run chef\-solo with \-j to specify the JSON file\. It will look for cookbooks in the cookbook_path configured in the configuration file, and apply attributes and use the run_list from the JSON file specified\. -. -.P -You can use \-c to specify the path to the configuration file (if you don\'t want chef\-solo to use the default)\. You can also specify \-r for a cookbook tarball\. -. -.P -For example: chef\-solo \-c ~/solo\.rb \-j ~/node\.json \-r http://www\.example\.com/chef\-solo\.tar\.gz -. -.P -In the above case, chef\-solo would extract the tarball to your specified cookbook_path, use ~/solo\.rb as the configuration file, and apply attributes and use the run_list from ~/node\.json\. -. -.SH "SEE ALSO" -Full documentation for Chef and chef\-solo is located on the Chef wiki, http://wiki\.opscode\.com/display/chef/Home\. -. -.SH "AUTHOR" -Chef was written by Adam Jacob \fIadam@ospcode\.com\fR of Opscode (http://www\.opscode\.com), with contributions from the community\. This manual page was written by Joshua Timberman \fIjoshua@opscode\.com\fR with help2man\. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2\.0 License\. -. -.P -On Debian systems, the complete text of the Apache 2\.0 License can be found in /usr/share/common\-licenses/Apache\-2\.0\. |