diff options
| author | Seth Chisamore <schisamo@opscode.com> | 2012-10-30 10:39:35 -0400 |
|---|---|---|
| committer | Seth Chisamore <schisamo@opscode.com> | 2012-10-30 10:39:35 -0400 |
| commit | 24dc69a9a97e82a6e4207de68d6dcc664178249b (patch) | |
| tree | 19bb289c9f88b4bbab066bc56b95d6d222fd5c35 /distro/common/markdown | |
| parent | 9348c1c9c80ee757354d624b7dc1b78ebc7605c4 (diff) | |
| download | chef-24dc69a9a97e82a6e4207de68d6dcc664178249b.tar.gz | |
[OC-3564] move core Chef to the repo root \o/ \m/
The opscode/chef repository now only contains the core Chef library code
used by chef-client, knife and chef-solo!
Diffstat (limited to 'distro/common/markdown')
25 files changed, 2651 insertions, 0 deletions
diff --git a/distro/common/markdown/README b/distro/common/markdown/README new file mode 100644 index 0000000000..0f35814baf --- /dev/null +++ b/distro/common/markdown/README @@ -0,0 +1,3 @@ +This directory contains markdown documentation that is used in other places. +For example, markdown (.mkd) documents that are generated as man pages +with ronn. diff --git a/distro/common/markdown/man1/chef-shell.mkd b/distro/common/markdown/man1/chef-shell.mkd new file mode 100644 index 0000000000..5525ef8ea9 --- /dev/null +++ b/distro/common/markdown/man1/chef-shell.mkd @@ -0,0 +1,195 @@ +chef-shell(1) -- Interactive Chef Console +========================================= + +## SYNOPSIS + +__chef-shell__ [_named configuration_] _(options)_ + + * `-S`, `--server CHEF_SERVER_URL`: + The chef server URL + * `-z`, `--client`: + chef-client mode + * `-c`, `--config CONFIG`: + The configuration file to use + * `-j`, `--json-attributes JSON_ATTRIBS`: + Load attributes from a JSON file or URL + * `-l`, `--log-level LOG_LEVEL`: + Set the logging level + * `-s`, `--solo`: + chef-solo session + * `-a`, `--standalone`: + standalone session + * `-v`, `--version`: + Show chef version + * `-h`, `--help`: + Show command options + +When no --config option is specified, chef-shell attempts to load a +default configuration file: + +* If a _named configuration_ is given, chef-shell will load ~/.chef/_named + configuration_/chef_shell.rb +* If no _named configuration_ is given chef-shell will load + ~/.chef/chef_shell.rb if it exists +* 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. +* The --config option takes precedence over implicit configuration + paths. + +## DESCRIPTION + +`chef-shell` is an irb(1) (interactive ruby) session customized for Chef. +`chef-shell` 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. + +## 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, +`recipe` and `attributes` modes are available. + +## PRIMARY MODE +The following commands are available in the primary +session: + + * `help`: + Prints a list of available commands + * `version`: + Prints the Chef version + * `recipe`: + Switches to `recipe` mode + * `attributes`: + Switches to `attributes` mode + * `run_chef`: + Initiates a chef run + * `reset`: + reinitializes chef-shell session + * `echo :on|:off`: + Turns irb's echo function on or off. Echo is _on_ by default. + * `tracing :on|:off`: + Turns irb's function tracing feature on or off. Tracing is extremely + verbose and expected to be of interest primarily to developers. + * `node`: + Returns the _node_ object for the current host. See knife-node(1) + for more information about nodes. + * `ohai`: + Prints the attributes of _node_ + +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 _object type_._operation_, where +_object type_ is in plural form. The following object types are +available: + + * `nodes` + * `roles` + * `data_bags` + * `clients` + * `cookbooks` + +For each _object type_ the following operations are available: + + * _object type_.all(_&block_): + Loads all items from the server. If the optional code _block_ is + given, each item will be passed to the block and the results + returned, similar to ruby's `Enumerable#map` method. + * _object type_.show(_object name_): + Aliased as _object type_.load + + Loads the singular item identified by _object name_. + * _object type_.search(_query_, _&block_): + Aliased as _object type_.find + + Runs a search against the server and returns the matching items. If + the optional code _block_ is given each item will be passed to the + block and the results returned. + + The _query_ 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. + * _object type_.transform(:all|_query_, _&block_): + Aliased as _object type_.bulk_edit + + Bulk edit objects by processing them with the (required) code _block_. + You can edit all objects of the given type by passing the Symbol + `:all` as the argument, or only a subset by passing a _query_ as the + argument. The _query_ is evaluated in the same way as with + __search__. + + The return value of the code _block_ is used to alter the behavior + of `transform`. If the value returned from the block is `nil` or + `false`, 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. + +## 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: + + * <http://wiki.opscode.com/display/chef/Resources> + * <http://wiki.opscode.com/display/chef/Recipes> + +Once you have defined resources in the recipe, you can trigger a +convergence run via `run_chef` + +## EXAMPLES + +* A "Hello World" interactive recipe + + 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"] + +* Search for _nodes_ by role, and print their IP addresses + + chef > nodes.find(:roles => 'monitoring-server') {|n| n[:ipaddress] } + => ["10.254.199.5"] + +* Remove the role _obsolete_ from every node in the system + + 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]] + + +## BUGS + +`chef-shell` often does not perfectly replicate the context in which +chef-client(8) configures a host, which may lead to discrepancies in +observed behavior. + +`chef-shell` has to duplicate much code from chef-client's internal +libraries and may become out of sync with the behavior of those +libraries. + +## SEE ALSO + + chef-client(8) knife(1) + <http://wiki.opscode.com/display/chef/Chef+Shell> + +## AUTHOR + + Chef was written by Adam Jacob <adam@opscode.com> with many + contributions from the community. chef-shell was written by Daniel + DeLeo. + +## DOCUMENTATION + + This manual page was written by Daniel DeLeo <dan@opscode.com>. + Permission is granted to copy, distribute and / or modify this + document under the terms of the Apache 2.0 License. + +## CHEF + + chef-shell is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> diff --git a/distro/common/markdown/man1/knife-bootstrap.mkd b/distro/common/markdown/man1/knife-bootstrap.mkd new file mode 100644 index 0000000000..c466fc7f7f --- /dev/null +++ b/distro/common/markdown/man1/knife-bootstrap.mkd @@ -0,0 +1,141 @@ +knife-bootstrap(1) -- Install Chef Client on a remote host +======================================== + +## SYNOPSIS + +__knife__ __bootstrap__ _(options)_ + + * `-i`, `--identity-file IDENTITY_FILE`: + The SSH identity file used for authentication + * `-N`, `--node-name NAME`: + The Chef node name for your new node + * `-P`, `--ssh-password PASSWORD`: + The ssh password + * `-x`, `--ssh-user USERNAME`: + The ssh username + * `-p`, `--ssh-port PORT`: + The ssh port + * `--bootstrap-version VERSION`: + The version of Chef to install + * `--bootstrap-proxy PROXY_URL`: + `The proxy server for the node being bootstrapped` + * `--prerelease`: + Install pre-release Chef gems + * `-r`, `--run-list RUN_LIST`: + Comma separated list of roles/recipes to apply + * `--template-file TEMPLATE`: + Full path to location of template to use + * `--sudo`: + Execute the bootstrap via sudo + * `-d`, `--distro DISTRO`: + Bootstrap a distro using a template + * `--[no-]host-key-verify`: + Enable host key verification, which is the default behavior. + * `--hint HINT_NAME[=HINT_FILE]`: + Provide the name of a hint (with option JSON file) to set for use by + Ohai plugins. + +## 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. + +The bootstrap sub-command supports supplying a template to perform the +bootstrap steps. If the distro is not specified (via `-d` or `--distro` +option), an Ubuntu 10.04 host bootstrapped with RubyGems is assumed. The +__DISTRO__ value corresponds to the base filename of the template, in +other words `DISTRO`.erb. A template file can be specified with the +`--template-file` option in which case the __DISTRO__ is not used. The +sub-command looks in the following locations for the template to use: + +* `bootstrap` directory in the installed Chef Knife library. +* `bootstrap` directory in the `$PWD/.chef`. +* `bootstrap` directory in the users `$HOME/.chef`. + +The default bootstrap templates are scripts that get copied to the +target node (FQDN). The following distros are supported: + +* centos5-gems +* fedora13-gems +* ubuntu10.04-gems +* ubuntu10.04-apt + +The gems installations will use RubyGems 1.3.6 and Chef installed as a +gem. The apt installation will use the Opscode APT repository. + +In addition to handling the software installation, these bootstrap +templates do the following: + + - Write the validation.pem per the local knife configuration. + - Write a default config file for Chef (`/etc/chef/client.rb`) using values from the `knife.rb`. + - Create a JSON attributes file containing the specified run list and run Chef. + +In the case of the RubyGems, the `client.rb` will be written from +scratch with a minimal set of values; see __EXAMPLES__. In the case of +APT Package installation, `client.rb` will have the +`validation_client_name` appended if it is not set to `chef-validator` +(default config value), and the `node_name` will be added if +`chef_node_name` option is specified. + +When this is complete, the bootstrapped node will have: + + - Latest Chef version installed from RubyGems or APT Packages from Opscode. This may be a later version than the local system. + - Be validated with the configured Chef Server. + - Have run Chef with its default run list if one is specfied. + +Additional custom bootstrap templates can be created and stored in +`.chef/bootstrap/DISTRO.erb`, replacing __DISTRO__ with the value passed +with the `-d` or `--distro` option. See __EXAMPLES__ for more +information. + +## EXAMPLES +Setting up a custom bootstrap is fairly straightforward. Create a +`.chef/bootstrap` directory in your Chef Repository or in +`$HOME/.chef/bootstrap`. Then create the ERB template file. + + mkdir ~/.chef/bootstrap + vi ~/.chef/bootstrap/debian5.0-apt.erb + +For example, to create a new bootstrap template that should be used when +setting up a new Debian node. Edit the template to run the commands, set +up the validation certificate and the client configuration file, and +finally to run chef-client on completion. The bootstrap template can be +called with: + + knife bootstrap mynode.example.com --template-file ~/.chef/bootstrap/debian5.0-apt.erb + +Or, + + knife bootstrap mynode.example.com --distro debian5.0-apt + +The `--distro` parameter will automatically look in the +`~/.chef/bootstrap` directory for a file named `debian5.0-apt.erb`. + +Templates provided by the Chef installation are located in +`BASEDIR/lib/chef/knife/bootstrap/*.erb`, where _BASEDIR_ is the +location where the package or Gem installed the Chef client libraries. + +## BUGS +`knife bootstrap` is not capable of bootstrapping multiple hosts in +parallel. + +The bootstrap script is passed as an argument to sh(1) on the remote +system, so sensitive information contained in the script will be visible +to other users via the process list using tools such as ps(1). + +## SEE ALSO + __knife-ssh__(1) + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> diff --git a/distro/common/markdown/man1/knife-client.mkd b/distro/common/markdown/man1/knife-client.mkd new file mode 100644 index 0000000000..e7b732ef71 --- /dev/null +++ b/distro/common/markdown/man1/knife-client.mkd @@ -0,0 +1,103 @@ +knife-client(1) -- Manage Chef API Clients +======================================== + +## SYNOPSIS + +__knife__ __client__ _sub-command_ _(options)_ + +## SUB-COMMANDS +Client subcommands follow a basic create, read, update, delete (CRUD) +pattern. The Following subcommands are available: + +## BULK DELETE +__knife client bulk delete__ _regex_ _(options)_ + +Delete clients where the client name matches the regular expression +_regex_ on the Chef Server. The regular expression should be given as a +quoted string, and not surrounded by forward slashes. + +## CREATE +__knife client create__ _client name_ _(options)_ + + * `-a`, `--admin `: + Create the client as an admin + * `-f`, `--file FILE`: + Write the key to a file + +Create a new client. This generates an RSA keypair. The private key will +be displayed on _STDOUT_ or written to the named file. The public half +will be stored on the Server. For _chef-client_ systems, the private key +should be copied to the system as `/etc/chef/client.pem`. + +Admin clients should be created for users that will use _knife_ to +access the API as an administrator. The private key will generally be +copied to `~/.chef/client\_name.pem` and referenced in the `knife.rb` +configuration file. + +## DELETE +__knife client delete__ _client name_ _(options)_ + +Deletes a registered client. + +## EDIT +__client edit__ _client name_ _(options)_ + +Edit a registered client. + +## LIST +__client list__ _(options)_ + + * `-w`, `--with-uri`: + Show corresponding URIs + +List all registered clients. + +## REREGISTER +__client reregister__ _client name_ _(options)_ + + * `-f`, `--file FILE`: + Write the key to a file + +Regenerate the RSA keypair for a client. The public half will be stored +on the server and the private key displayed on _STDOUT_ or written to +the named file. 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. + +## SHOW +__client show__ _client name_ _(options)_ + + * `-a`, `--attribute ATTR`: + Show only one attribute + +Show a client. Output format is determined by the --format option. + +## DESCRIPTION +Clients are identities used for communication with the Chef Server API, +roughly equivalent to user accounts on the Chef Server, except that +clients only communicate with the Chef Server API and are authenticated +via request signatures. + +In the typical case, there will be one client object on the server for +each node, and the corresponding client and node will have identical +names. + +In the Chef authorization model, there is one special client, the +"validator", which is authorized to create new non-administrative +clients but has minimal privileges otherwise. This identity is used as a +sort of "guest account" to create a client identity when initially +setting up a host for management with Chef. + +## SEE ALSO + __knife-node__(1) + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + diff --git a/distro/common/markdown/man1/knife-configure.mkd b/distro/common/markdown/man1/knife-configure.mkd new file mode 100644 index 0000000000..cc7dd1d96e --- /dev/null +++ b/distro/common/markdown/man1/knife-configure.mkd @@ -0,0 +1,70 @@ +knife-configure(1) -- Generate configuration files for knife or Chef Client +======================================== + +## SYNOPSIS + +__knife__ __configure__ [client] _(options)_ + +## DESCRIPTION +Generates a knife.rb configuration file interactively. When given the +--initial option, also creates a new administrative user. + +## CONFIGURE SUBCOMMANDS ## + +__knife configure__ _(options)_ + + * `-i`, `--initial`: + Create an initial API Client + * `-r`, `--repository REPO`: + The path to your chef-repo + +Create a configuration file for knife. This will prompt for values to +enter into the file. Default values are listed in square brackets if no +other entry is typed. See __knife__(1) for a description of +configuration options. + +__knife configure client__ _directory_ + +Read the _knife.rb_ config file and generate a config file suitable for +use in _/etc/chef/client.rb_ and copy the validation certificate into +the specified _directory_. + +## EXAMPLES + * On a freshly installed Chef Server, use _knife configure -i_ 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. + + 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 + + This creates a new administrator client named _username_, writes + a configuration file to _/home/username/.chef/knife.rb_, and the + private key to _/home/username/.chef/username.pem_. 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. + +## SEE ALSO + __knife__(1) __knife-client__(1) + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + diff --git a/distro/common/markdown/man1/knife-cookbook-site.mkd b/distro/common/markdown/man1/knife-cookbook-site.mkd new file mode 100644 index 0000000000..7c2b0fe31b --- /dev/null +++ b/distro/common/markdown/man1/knife-cookbook-site.mkd @@ -0,0 +1,123 @@ +knife-cookbook-site(1) -- Install and update open source cookbooks +======================================== + +## SYNOPSIS + +__knife__ __cookbook site__ _sub-command_ _(options)_ + +## COOKBOOK SITE SUB-COMMANDS +`knife cookbook site` provides the following subcommands: + +## INSTALL +__cookbook site install COOKBOOK [VERSION]__ _(options)_ + + * `-D`, `--skip-dependencies `: + Skip automatic installation of dependencies. + * `-o`, `--cookbook-path PATH`: + Install cookbooks to PATH + * `-B`, `--branch BRANCH`: + Default branch to work with [defaults to master] + +Uses git(1) version control in conjunction with the cookbook site to +install community contributed cookbooks to your local cookbook +repository. Running `knife cookbook site install` does the following: + +1. A new "pristine copy" branch is created in git for tracking the + upstream; +2. All existing cookbooks are removed from the branch; +3. The cookbook is downloaded from the cookbook site in tarball form; +4. The downloaded cookbook is untarred, and its contents commited via git; +5. The pristine copy branch is merged into the master branch. + +By installing cookbook with this process, you can locally modify the +upstream cookbook in your master branch 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. + +Unless _--skip-dependencies_ is specified, the process is applied recursively to all the +cookbooks _COOKBOOK_ depends on (via metadata _dependencies_). + +## DOWNLOAD +__knife cookbook site download COOKBOOK [VERSION]__ _(options)_ + + * `-f`, `--file FILE`: + The filename to write to + * `--force`: + Force download deprecated cookbook + +Downloads a specific cookbook from the Community site, optionally +specifying a certain version. + +## LIST +__knife cookbook site list__ _(options)_ + + * `-w`, `--with-uri`: + Show corresponding URIs + +Lists available cookbooks from the Community site. + +## SEARCH +__knife cookbook site search QUERY__ _(options)_ + +Searches for available cookbooks matching the specified query. + +## SHARE +__knife cookbook site share COOKBOOK CATEGORY__ _(options)_ + + * `-k`, `--key KEY`: + API Client Key + * `-u`, `--user USER`: + API Client Username + * `-o`, `--cookbook-path PATH:PATH`: + A colon-separated path to look for cookbooks in + +Uploads the specified cookbook using the given category to the Opscode +cookbooks site. Requires a login user and certificate for the Opscode +Cookbooks site. 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. + +## UNSHARE +__knife cookbook site unshare COOKBOOK__ + +Stops sharing the specified cookbook on the Opscode cookbooks site. + +## SHOW +__knife cookbook site show COOKBOOK [VERSION]__ _(options)_ + +Shows information from the site about a particular cookbook. + +## DESCRIPTION +The cookbook site, <http://community.opscode.com/>, is a cookbook +distribution service operated by Opscode. This service provides users +with a central location to publish cookbooks for sharing with other +community members. + +`knife cookbook site` commands provide an interface to the cookbook +site's HTTP API. For commands that read data from the API, no account is +required. In order to upload cookbooks using the `knife cookbook site +share` command, you must create an account on the cookbook site and +configure your credentials via command line option or in your knife +configuration file. + +## EXAMPLES +Uploading cookbooks to the Opscode cookbooks site: + + knife cookbook site share example Other -k ~/.chef/USERNAME.pem -u USERNAME + +## SEE ALSO + __knife-cookbook(1)__ + <http://community.opscode.com/cookbooks> + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + diff --git a/distro/common/markdown/man1/knife-cookbook.mkd b/distro/common/markdown/man1/knife-cookbook.mkd new file mode 100644 index 0000000000..4f714c52f6 --- /dev/null +++ b/distro/common/markdown/man1/knife-cookbook.mkd @@ -0,0 +1,263 @@ +knife-cookbook(1) -- upload and manage chef cookbooks +======================================== + +## SYNOPSIS + +__knife__ __cookbook__ _sub-command_ _(options)_ + +## SUB-COMMANDS +`knife cookbook` supports the following sub commands: + +## LIST +__knife cookbook list__ _(options)_ + + * `-a`, `--all`: + show all versions of a cookbook instead of just the most recent + * `-w`, `--with-uri`: + show corresponding uris + +Lists the cookbooks available on the Chef server. + +## SHOW +__knife cookbook show cookbook [version] [part] [filename]__ _(options)_ + + * `-f`, `--fqdn fqdn `: + the fqdn of the host to see the file for + * `-p`, `--platform platform `: + the platform to see the file for + * `-v`, `--platform-version version`: + the platform version to see the file for + * `-w`, `--with-uri`: + Show corresponding URIs + +show a particular part of a _cookbook_ for the specified _version_. _part_ can be one of: + + * _attributes_ + * _definitions_ + * _files_ + * _libraries_ + * _providers_ + * _recipes_ + * _resources_ + * _templates_ + +## UPLOAD +__knife cookbook upload [cookbooks...]__ _(options)_ + + * `-a`, `--all`: + upload all cookbooks, rather than just a single cookbook + * `-o`, `--cookbook-path path:path`: + a colon-separated path to look for cookbooks in + * `-d`, `--upload-dependencies`: + Uploads additional cookbooks that this cookbook lists in as + dependencies in its metadata. + * `-E`, `--environment ENVIRONMENT`: + An _ENVIRONMENT_ to apply the uploaded cookbooks to. Specifying this + option will cause knife to edit the _ENVIRONMENT_ to place a strict + version constraint on the cookbook version(s) uploaded. + * `--freeze`: + Sets the frozen flag on the uploaded cookbook(s) Any future attempt + to modify the cookbook without changing the version number will + return an error unless --force is specified. + * `--force`: + Overrides the frozen flag on a cookbook, allowing you to overwrite a + cookbook version that has previously been uploaded with the --freeze + option. + +Uploads one or more cookbooks from your local cookbook repository(ies) +to the Chef Server. Only files that don't yet exist on the server will +be uploaded. + +As the command parses the name args as 1..n cookbook names: + `knife cookbook upload COOKBOOK COOKBOOK ...` +works for one to many cookbooks. + +## DOWNLOAD +__knife cookbook download cookbook [version]__ _(options)_ + + * `-d`, `--dir download_directory`: + the directory to download the cookbook into + * `-f`, `--force`: + overwrite an existing directory with the download + * `-n`, `--latest`: + download the latest version of the cookbook + +download a cookbook from the chef server. if no version is specified and +only one version exists on the server, that version will be downloaded. +if no version is specified and multiple versions are available on the +server, you will be prompted for a version to download. + +## DELETE +__knife cookbook delete cookbook [version]__ _(options)_ + + * `-a`, `--all`: + delete all versions + * `-p`, `--purge`: + purge files from backing store. this will disable any cookbook that contains any of the same files as the cookbook being purged. + +delete the specified _version_ of the named _cookbook_. if no version is +specified, and only one version exists on the server, that version will +be deleted. if multiple versions are available on the server, you will +be prompted for a version to delete. + +## BULK DELETE +__knife cookbook bulk delete regex__ _(options)_ + + * `-p`, `--purge`: + purge files from backing store. this will disable any cookbook that + contains any of the same files as the cookbook being purged. + +delete cookbooks on the chef server based on a regular expression. the +regular expression (_regex_) should be in quotes, not in //'s. + +## COOKBOOK CREATE +__knife cookbook create cookbook__ _(options)_ + + * `-o`, `--cookbook-path path`: + the directory where the cookbook will be created + * `-r`, `--readme-format format`: + format of the readme file md, mkd, txt, rdoc + * `-c`, `--copyright copyright`: + name of copyright holder + * `-i`, `--license license`: + license for cookbook, apachev2 or none + * `-e`, `--email email`: + email address of cookbook maintainer + +this is a helper command that creates a new cookbook directory in the +`cookbook_path`. the following directories and files are created for the +named cookbook. + +* cookbook/attributes +* cookbook/definitions +* cookbook/files/default +* cookbook/libraries +* cookbook/metadata.rb +* cookbook/providers +* cookbook/readme.md +* cookbook/recipes/default.rb +* cookbook/resources +* cookbook/templates/default + +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. + +specify `-c` or `--copyright` with the name of the copyright holder as +your name or your company/organization name in a quoted string. if this +value is not specified an all-caps string `your_company_name` is used +which can be easily changed with find/replace. + +specify `-i` or `--license` with the license that the cookbook is +distributed under for sharing with other people or posting to the +opscode cookbooks site. be aware of the licenses of files you put inside +the cookbook and follow any restrictions they describe. when using +`none` (default) or `apachev2`, comment header text and metadata file +are pre-filled. the `none` license will be treated as +non-redistributable. + +specify `-e` or `--email` with the email address of the cookbook's +maintainer. if this value is not specified, an all-caps string +`your_email` is used which can easily be changed with find/replace. + +the cookbook copyright, license, email and readme_format settings can be filled in the +`knife.rb`, for example with default values: + + cookbook_copyright "your_company_name" + cookbook_license "none" + cookbook_email "your_email" + readme_format "md" + + +## METADATA +__knife cookbook metadata cookbook__ _(options)_ + + * `-a`, `--all`: + generate metadata for all cookbooks, rather than just a single cookbook + * `-o`, `--cookbook-path path:path`: + a colon-separated path to look for cookbooks in + +generate cookbook metadata for the named _cookbook_. the _path_ used here specifies where the cookbooks directory is located and corresponds to the `cookbook_path` configuration option. + +## METADATA FROM FILE +__knife cookbook metadata from file__ _(options)_ + +load the cookbook metadata from a specified file. + +## TEST +__knife cookbook test [cookbooks...]__ _(options)_ + + * `-a`, `--all`: + test all cookbooks, rather than just a single cookbook + * `-o`, `--cookbook-path path:path`: + a colon-separated path to look for cookbooks in + +test the specified cookbooks for syntax errors. this uses the built-in +ruby syntax checking option for files in the cookbook ending in `.rb`, +and the erb syntax check for files ending in `.erb` (templates). + +## RECIPE LIST +__knife recipe list [PATTERN]__ + +List available recipes from the server. Specify _PATTERN_ as a regular +expression to limit the results. + +## DESCRIPTION +Cookbooks are the fundamental unit of distribution in Chef. They +encapsulate all recipes of resources and assets used to configure a +particular aspect of the infrastructure. The following sub-commands can +be used to manipulate the cookbooks stored on the Chef Server. + +On disk, cookbooks are directories with a defined structure. The +following directories may appear within a cookbook: + + * COOKBOOK/attributes/: + Ruby files that define default parameters to be used in recipes + * COOKBOOK/definitions/: + Ruby files that contain _resource definitions_ + * COOKBOOK/files/SPECIFICITY: + Files of arbitrary type. These files may be downloaded by + chef-client(8) when configuring a host. + * COOKBOOK/libraries/: + Ruby files that contain library code needed for recipes + * COOKBOOK/providers/: + Ruby files that contain Lightweight Provider definitions + * COOKBOOK/recipes/: + Ruby files that use Chef's recipe DSL to describe the desired + configuration of a system + * COOKBOOK/resources/: + Ruby files that contain Lightweight Resource definitions + * COOKBOOK/templates/SPECIFICITY: + ERuby (ERb) template files. These are referenced by _recipes_ and + evaluated to dynamically generate configuration files. + +__SPECIFICITY__ is a feature of _files_ and _templates_ that allow you +to specify alternate files to be used on a specific OS platform or host. +The default specificity setting is _default_, that is files in +`COOKBOOK/files/default` will be used when a more specific copy is not +available. Further documentation for this feature is available on the +Chef wiki: <http://wiki.opscode.com/display/chef/File+Distribution#FileDistribution-FileSpecificity> + +Cookbooks also contain a metadata file that defines various properties +of the cookbook. The most important of these are the _version_ and the +_dependencies_. The _version_ is used in combination with environments +to select which copy of a given cookbook is distributed to a node. The +_dependencies_ are used by the server to determine which additional +cookbooks must be distributed to a given host when it requires a +cookbook. + +## SEE ALSO + __knife-environment(1)__ __knife-cookbook-site(1)__ + <http://wiki.opscode.com/display/chef/Cookbooks> + <http://wiki.opscode.com/display/chef/Metadata> + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> diff --git a/distro/common/markdown/man1/knife-data-bag.mkd b/distro/common/markdown/man1/knife-data-bag.mkd new file mode 100644 index 0000000000..67ec02158c --- /dev/null +++ b/distro/common/markdown/man1/knife-data-bag.mkd @@ -0,0 +1,121 @@ +knife-data-bag(1) -- Store arbitrary data on a Chef Server +======================================== + +## SYNOPSIS + +__knife__ __data bag__ _sub-command_ _(options)_ + +## 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 __knife-search__(1). + +Data bags are available to all nodes configured by __chef-client__(8), +and are therefore a convenient mechanism to store global information, +such as lists of administrative accounts that should be configured on +all hosts. + +## DATA BAG SUB-COMMANDS + +## CREATE +__knife data bag create__ _bag name_ [item id] _(options)_ + + * `-s`, `--secret SECRET`: + A secret key used to encrypt the data bag item. See __encryption support__ below. + * `--secret-file SECRET_FILE`: + The path to a file containing the secret key to be used to encrypt + the data bag item. + +If _item id_ 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. + +If _item id_ is not given, the data bag will be created. + +## DELETE +__knife data bag delete__ _bag name_ [item id] _(options)_ + +Delete a data bag, or an item from a data bag. + +## EDIT +__knife data bag edit__ _bag name_ _item id_ _(options)_ + + * `-s`, `--secret SECRET`: + A secret key used to encrypt the data bag item. See __encryption support__ below. + * `--secret-file SECRET_FILE`: + The path to a file containing the secret key to be used to encrypt + the data bag item. + +Edit an item in a data bag. + +## FROM FILE +__knife data bag from file__ _bag name_ _file_ _(options)_ + +__knife data bag from file__ _bag name_ _file1_ _file2_ _file3_ _(options)_ + +__knife data bag from file__ _bag name_ _folder_ _(options)_ + + * `-s`, `--secret SECRET`: + A secret key used to encrypt the data bag item. See __encryption support__ below. + * `--secret-file SECRET_FILE`: + The path to a file containing the secret key to be used to encrypt + the data bag item. + +Load a data bag item from a JSON file. If _file_ is a relative or +absolute path to the file, that file will be used. Otherwise, the _file_ +parameter is treated as the base name of a data bag file in a Chef +repository, and `knife` will search for the file in +`./data_bags/bag_name/file`. For example `knife data bag from file users +dan.json` would attempt to load the file `./data_bags/users/dan.json`. + +## LIST +__knife data bag list__ _(options)_ + + * `-w`, `--with-uri`: + Show corresponding URIs + +Lists the data bags that exist on the Chef Server. + +## SHOW +__knife data bag show BAG [ITEM]__ _(options)_ + + * `-s`, `--secret SECRET`: + A secret key used to encrypt the data bag item. See __encryption support__ below. + * `--secret-file SECRET_FILE`: + The path to a file containing the secret key to be used to encrypt + the data bag item. + +Show a specific data bag or an item in a data bag. The output will be +formatted according to the --format option. + +## 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. + +Data Bag Item encryption uses the AES-256 CBC symmetric key algorithm. + +__CAVEATS:__ 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. + +Chef Server does not provide a secure mechanism for distributing +encryption keys. + +## SEE ALSO + __knife-search__(1) + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. http://wiki.opscode.com/display/chef/Home + diff --git a/distro/common/markdown/man1/knife-environment.mkd b/distro/common/markdown/man1/knife-environment.mkd new file mode 100644 index 0000000000..2eebffbce6 --- /dev/null +++ b/distro/common/markdown/man1/knife-environment.mkd @@ -0,0 +1,151 @@ +knife-environment(1) -- Define cookbook policies for the environments in your infrastructure +======================================== + +## SYNOPSIS + +__knife__ __environment__ _sub-command_ _(options)_ + +## SUBCOMMANDS +Environment subcommands follow a basic create, read, update, delete +(CRUD) pattern. The following subcommands are available: + +## CREATE +__knife environment create__ _environment_ _(options)_ + + * `-d`, `--description DESCRIPTION`: + The value of the description field. + +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. + +## DELETE +__knife environment delete__ _environment_ _(options)_ + +Destroy an environment on the Chef Server. A prompt for confirmation +will be displayed if the -y options is not given. + +## EDIT +__knife environment edit__ _environment_ _(options)_ + +Fetch _environment_ and display it in the text editor for editing. The +environment will be saved to the Chef Server when the editing session +exits. + +## FROM FILE +__knife environment from file__ _file_ _(options)_ + +Create or update an environment from the JSON or Ruby format _file_. See +__format__ for the proper format of this file. + +## LIST +__knife environment list__ _(options)_ + * `-w`, `--with-uri`: + Show the resource URI for each environment + +## SHOW +__knife environment show__ _environment_ _(options)_ + +## 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 +_environments_. + +Environments contain two major components: a set of cookbook version +constraints and environment attributes. + +## SYNTAX +A cookbook version constraint is comprised of a _cookbook name_ and a +_version constraint_. The _cookbook name_ is the name of a cookbook in +your system, and the _version constraint_ is a String describing the +version(s) of that cookbook allowed in the environment. Only one +_version constraint_ is supported for a given _cookbook name_. + +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: + + {"apache2": ">= 1.5.0"} + +In the Ruby format, the cookbook version contraints for an environment +are represented as a Ruby Hash, like this: + + {"apache2" => ">= 1.5.0"} + +A _version number_ 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. + +A _version constraint_ String is composed of an _operator_ and a +_version number_. The following operators are available: + + * `= VERSION`: + Equality. Only the exact version specified may be used. + * `> VERSION`: + Greater than. Only versions greater than `VERSION` may be used. + * `>= VERSION`: + Greater than or equal to. Only versions equal to VERSION or greater + may be used. + * `< VERSION`: + Less than. Only versions less than VERSION may be used. + * `<= VERSION`: + Less than or equal to. Only versions lesser or equal to VERSION may + be used. + * `~> VERSION`: + 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, `~> 1.1` will match any + version less than `2.0` and greater than or equal to `1.1.0`, + whereas `~> 2.0.5` will match any version less than `2.1.0` and + greater than or equal to `2.0.5`. + +## FORMAT +The JSON format of an envioronment is as follows: + + { + "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" + } + } + +The Ruby format of an environment is as follows: + + 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" + + +## SEE ALSO + __knife-node(1)__ __knife-cookbook(1)__ __knife-role(1)__ + <http://wiki.opscode.com/display/chef/Environments> + <http://wiki.opscode.com/display/chef/Version+Constraints> + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Daniel DeLeo <dan@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> diff --git a/distro/common/markdown/man1/knife-exec.mkd b/distro/common/markdown/man1/knife-exec.mkd new file mode 100644 index 0000000000..d4aa87ca46 --- /dev/null +++ b/distro/common/markdown/man1/knife-exec.mkd @@ -0,0 +1,42 @@ +knife-exec(1) -- Run user scripts using the Chef API DSL +======================================== + +## SYNOPSIS + +__knife__ __exec__ _(options)_ + + * `-E`, `--exec CODE`: + Provide a snippet of code to evaluate on the command line + +## DESCRIPTION + +`knife exec` 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. + +## EXAMPLES + + * Make an API call against an arbitrary endpoint: + knife exec -E 'api.get("nodes/fluke.localdomain/cookbooks")' + => list of cookbooks for the node _fluke.localdomain_ + * Remove the role _obsolete_ from all nodes: + knife exec -E 'nodes.transform(:all){|n| n.run\_list.delete("role[obsolete]")}' + * Generate the expanded run list for hosts in the `webserver` role: + knife exec -E 'nodes.find(:roles => "webserver") {|n| n.expand!; n[:recipes]}' + +## SEE ALSO + + __chef-shell(1)__ + +## AUTHOR + + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> diff --git a/distro/common/markdown/man1/knife-index.mkd b/distro/common/markdown/man1/knife-index.mkd new file mode 100644 index 0000000000..812f3fe7dd --- /dev/null +++ b/distro/common/markdown/man1/knife-index.mkd @@ -0,0 +1,30 @@ +knife-index(1) -- Rebuild the search index on a Chef Server +======================================== + +## SYNOPSIS + +__knife__ __index rebuild__ _(options)_ + + * `-y`, `--yes`: + don't bother to ask if I'm sure + +## 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 __chef-expander__(8) via __rabbitmq-server__(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. + +## SEE ALSO + __knife-search__(1) + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + diff --git a/distro/common/markdown/man1/knife-node.mkd b/distro/common/markdown/man1/knife-node.mkd new file mode 100644 index 0000000000..72b7d0072f --- /dev/null +++ b/distro/common/markdown/man1/knife-node.mkd @@ -0,0 +1,130 @@ +knife-node(1) -- Manage the hosts in your infrastructure +======================================== + +## SYNOPSIS + +__knife__ __node__ _sub-command_ _(options)_ + +## DESCRIPTION +Nodes are data structures that represent hosts configured with Chef. +Nodes have a __name__, a String that uniquely identifies the node, +__attributes__, a nested Hash of properties that describe how the host +should be configured, a __chef\_environment__, a String representing the +environment to which the node belongs, and a __run\_list__, an ordered +list of __recipes__ or __roles__ that chef-client should apply when +configuring a host. + +When a host communicates with a Chef Server, it authenticates using its +__node\_name__ for identification and signs its reqests with a private +key. The Server validates the request by looking up a __client__ object +with a name identical to the __node\_name__ submitted with the request +and verifes the signature using the public key for that __client__ +object. __NOTE__ that the __client__ is a different object in the +system. It is associated with a node by virtue of having a matching +name. + +By default __chef-client__(8) will create a node using the FQDN of the +host for the node name, though this may be overridden by configuration +settings. + +## NODE SUB-COMMANDS +The following `node` subcommands are available: + +## BULK DELETE +__knife node bulk delete__ _regex_ _(options)_ + +Deletes nodes for which the name matches the regular expression _regex_ +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). + +## CREATE +__knife node create__ _name_ _(options)_ + +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. + +## DELETE +__knife node delete__ _name_ _(options)_ + +Deletes the node identified by _name_ on the Chef Server. + +## EDIT +__knife node edit__ _name_ _(options)_ + + * `-a`, `--all`: + Display all node data in the editor. By default, default, override, + and automatic attributes are not shown. + +Edit the node identified by _name_. Like __knife node create__, the node +will be displayed in your text editor unless the -n option is present. + +## FROM FILE +__knife node from file__ _file_ _(options)_ + +Create a node from a JSON format _file_. + +## LIST +__knife node list__ _(options)_ + + * `-w`, `--with-uri`: + Show corresponding URIs + +List all nodes. + +## RUN\_LIST ADD +__knife node run_list add__ _name_ _run list item_ _(options)_ + + * `-a`, `--after ITEM`: + Place the ENTRY in the run list after ITEM + +Add the _run list item_ to the node's `run_list`. See Run list + +## RUN\_LIST REMOVE +__knife node run_list remove__ _node name_ _run list item_ _(options)_ + +Remove the _run list item_ from the node's `run_list`. + +## SHOW +__knife node show__ _node name_ _(options)_ + + * `-a`, `--attribute [ATTR]`: + Show only one attribute + * `-r`, `--run-list `: + Show only the run list + * `-F`, `--format FORMAT`: + Display the node in a different format. + * `-m`, `--medium`: + Display more, but not all, of the node's data when using the default + _summary_ format + +Displays the node identified by _node name_ on stdout. + +## 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]" + +When adding a recipe to a run list, there are several valid formats: + + * Fully Qualified Format: + "recipe[COOKBOOK::RECIPE\_NAME]", for example, "recipe[chef::client]" + * 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" + * 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" + +## SEE ALSO + __knife-client__(1) __knife-search__(1) __knife-role__(1) + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + diff --git a/distro/common/markdown/man1/knife-role.mkd b/distro/common/markdown/man1/knife-role.mkd new file mode 100644 index 0000000000..7e0dac9bc5 --- /dev/null +++ b/distro/common/markdown/man1/knife-role.mkd @@ -0,0 +1,85 @@ +knife-role(1) -- Group common configuration settings +======================================== + +## SYNOPSIS + +__knife__ __role__ _sub-command_ _(options)_ + +## ROLE SUB-COMMANDS +The following `role` subcommands are available: + +## LIST +__knife role list__ _(options)_ + + * `-w`, `--with-uri`: + Show corresponding URIs + +List roles. + +## SHOW +__knife role show ROLE__ _(options)_ + + * `-a`, `--attribute ATTR`: + Show only one attribute + +Show a specific role. + +## CREATE +__knife role create ROLE__ _(options)_ + + * `-d`, `--description`: + The role description + +Create a new role. + +## EDIT +__knife role edit ROLE__ _(options)_ + +Edit a role. + +## FROM FILE +__knife role from file FILE__ _(options)_ + +Create or update a role from a role Ruby DSL (`.rb`) or JSON file. + +## DELETE +__knife role delete ROLE__ _(options)_ + +Delete a role. + +## BULK DELETE +__knife role bulk delete REGEX__ _(options)_ + +Delete roles on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s. + +## DESCRIPTION +Roles provide a mechanism to group repeated configuration settings. +Roles are data structures that contain __default\_attributes__, and +__override_attributes__, which are nested hashes of configuration +settings, and a __run_list__, which is an ordered list of recipes and +roles that should be applied to a host by chef-client. + +__default_attributes__ will be overridden if they conflict with a value +on a node that includes the role. Conversely, __override_attributes__ +will override any values set on nodes that apply them. + +When __chef-client__(8) configures a host, it will "expand" the +__run_list__ included in that host's node data. The expansion process +will recursively replace any roles in the run\_list with that role's +run\_list. + +## SEE ALSO + __knife-node(1)__ __knife-environment(1)__ + <http://wiki.opscode.com/display/chef/Roles> + <http://wiki.opscode.com/display/chef/Attributes> + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + diff --git a/distro/common/markdown/man1/knife-search.mkd b/distro/common/markdown/man1/knife-search.mkd new file mode 100644 index 0000000000..d6729be322 --- /dev/null +++ b/distro/common/markdown/man1/knife-search.mkd @@ -0,0 +1,180 @@ +knife-search(1) -- Find objects on a Chef Server by query +======================================== + +## SYNOPSIS + +__knife__ __search INDEX QUERY__ _(options)_ + + * `-a`, `--attribute ATTR`: + Show only one attribute + * `-i`, `--id-only`: + Show only the ID of matching objects + * `-q`, `--query QUERY`: + The search query; useful to protect queries starting with - + * `-R`, `--rows INT`: + The number of rows to return + * `-r`, `--run-list`: + Show only the run list + * `-o`, `--sort SORT`: + The order to sort the results in + * `-b`, `--start ROW`: + The row to start returning results at + * `-m`, `--medium`: + Display medium sized output when searching nodes using the default + summary format + * `-l`, `--long`: + Display long output when searching nodes using the default summary + format + +## 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. + + +## 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: + + * _node_ + * _role_ + * _environment_ + * _clients_ + * _data bag_ + +Data bags are indexed by the data bag's name. For example, to search a +data bag named "admins": + + knife search admins "field:search_pattern" + +## QUERY SYNTAX + +Queries have the form `field:search_pattern` where `field` is a key in +the JSON description of the relevant objects (nodes, roles, +environments, or data bags). Both `field` and `search_pattern` are +case-sensitive. `search_pattern` can be an exact, wildcard, +range, or fuzzy match (see below). The `field` supports exact +matching and limited wildcard matching. + +Searches will return the relevant objects (nodes, roles, environments, +or data bags) where the `search_pattern` matches the object's value of +`field`. + +### 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. + +### 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. + +### EXACT MATCHES +Without any search modifiers, a search returns those fields for which +the `search_pattern` exactly matches the value of `field` in the JSON +description of the object. + +### WILDCARD MATCHES + +Search support both single- and multi-character wildcard searches +within a search pattern. + +'?' matches exactly one character. + +'*' matches zero or more characters. + +### RANGE MATCHES +Range searches allows one to match values between two given values. To +match values between X and Y, inclusively, use square brackets: + + knife search INDEX 'field:[X TO Y] + +To match values between X and Y, exclusively, use curly brackets: + + knife search INDEX 'field:{X TO Y}' + +Values are sorted in lexicographic order. + +### 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: + + knife search INDEX 'field:term~' + +This search would return nodes whose `field` was 'perm' or 'germ'. + +### BOOLEAN OPERATORS + +The boolean operators NOT, AND, and OR are supported. To find values +of `field` that are not X: + + knife search INDEX 'field:(NOT X)' + +To find records where `field1` is X and `field2` is Y: + + knife search INDEX 'field1:X AND field2:Y' + +To find records where `field` is X or Y: + + knife search INDEX 'field:X OR field:Y' + +### 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. + +Search terms that include spaces should be enclosed in double-quotes: + + knife search INDEX 'field:"term with spaces"' + +The following characters must be escaped: + + + - && || ! ( ) { } [ ] ^ " ~ * ? : \ + +## EXAMPLES + +Find the nodes with the fully-qualified domain name (FQDN) +www.example.com: + + knife search node 'fqdn:www.example.com' + +Find the nodes running a version of Ubuntu: + + knife search node 'platform:ubuntu*' + +Find all nodes running CentOS in the production environment: + + knife search node 'chef_environment:production AND platform:centos' + +## KNOWN BUGS + + * Searches against the client index return no results in most cases. (CHEF-2477) + * Searches using the fuzzy match operator (~) produce an error. (CHEF-2478) + +## SEE ALSO + __knife-ssh__(1) + <http://wiki.opscode.com/display/chef/Attributes> + [Lucene Query Parser Syntax](http://lucene.apache.org/java/2_3_2/queryparsersyntax.html) + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + + diff --git a/distro/common/markdown/man1/knife-ssh.mkd b/distro/common/markdown/man1/knife-ssh.mkd new file mode 100644 index 0000000000..07fc5940ce --- /dev/null +++ b/distro/common/markdown/man1/knife-ssh.mkd @@ -0,0 +1,69 @@ +knife-ssh(1) -- Run a command or interactive session on multiple remote hosts +======================================== + +## SYNOPSIS + +__knife__ __ssh QUERY COMMAND__ _(options)_ + + * `-a`, `--attribute ATTR `: + The attribute to use for opening the connection - default is fqdn + * `-C`, `--concurrency NUM `: + The number of concurrent connections + * `-m`, `--manual-list `: + QUERY is a space separated list of servers + * `-P`, `--ssh-password PASSWORD`: + The ssh password + * `-x`, `--ssh-user USERNAME `: + The ssh username + * `-i`, `--identity-file IDENTITY_FILE`: + The SSH identity file used for authentication + * `-p`, `--ssh-port PORT`: + The ssh port + * `--[no-]host-key-verify`: + Verify host key, enabled by default. + +## DESCRIPTION + +The _ssh_ sub-command opens an ssh session to each of the nodes in the +search results of the _QUERY_. This sub-command requires that the +net-ssh-multi and highline Ruby libraries are installed. On Debian +systems, these are the libnet-ssh-multi-ruby and libhighline-ruby +packages. They can also be installed as RubyGems (net-ssh-multi and +highline, respectively). + +## TERMINAL MULTIPLEXING AND TERMINAL TAB SUPPORT +`knife ssh` integrates with several terminal multiplexer programs to +provide a more convenient means of managing multiple ssh sessions. When +the _COMMAND_ option matches one of these, `knife ssh` will create +multiple interactive ssh sessions running locally in the terminal +multiplexer instead of invoking the command on the remote host. + +The available multiplexers are: + + * `interactive`: + A built-in multiplexer. `interactive` supports running commands on a + subset of the connected hosts in parallel + * __screen__(1): + Runs ssh interactively inside `screen`. ~/.screenrc will be sourced + if it exists. + * __tmux__(1): + Runs ssh interactively inside tmux. + * `macterm` (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. + +## SEE ALSO + __knife-search__(1) + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + + diff --git a/distro/common/markdown/man1/knife-status.mkd b/distro/common/markdown/man1/knife-status.mkd new file mode 100644 index 0000000000..07f0ff305a --- /dev/null +++ b/distro/common/markdown/man1/knife-status.mkd @@ -0,0 +1,36 @@ +knife-status(1) -- Display status information for the nodes in your infrastructure +======================================== + +## SYNOPSIS + +__knife__ __status__ _(options)_ + + * `-r`, `--run-list RUN_LIST`: + Show the run list + +## DESCRIPTION + +The _status_ 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 `node.save`. 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 `-r` +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. + + +## SEE ALSO + __knife-search__(1) + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + + diff --git a/distro/common/markdown/man1/knife-tag.mkd b/distro/common/markdown/man1/knife-tag.mkd new file mode 100644 index 0000000000..6a1a2c4b56 --- /dev/null +++ b/distro/common/markdown/man1/knife-tag.mkd @@ -0,0 +1,39 @@ +knife-tag(1) -- Apply tags to nodes on a Chef Server +======================================== + +## SYNOPSIS + +__knife__ __tag__ _subcommand_ _(options)_ + +## TAG SUBCOMMANDS +The following `tag` subcommands are available: + +## CREATE +__knife tag create__ _node_ _tag_ [_..._] + +Adds one or more tags to _node_ + +## DELETE +__knife tag delete__ _node_ _tag_ [_..._] + +Removes one or more tags from _node_ + +## LIST +__knife tag list__ _node_ + +Lists the tags applied to _node_ + + +## SEE ALSO + __knife-node(1)__ + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community. + +## DOCUMENTATION + This manual page was written by Daniel DeLeo <dan@opscode.com>. + Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + diff --git a/distro/common/markdown/man1/knife.mkd b/distro/common/markdown/man1/knife.mkd new file mode 100644 index 0000000000..054e220cf9 --- /dev/null +++ b/distro/common/markdown/man1/knife.mkd @@ -0,0 +1,218 @@ +knife(1) -- Chef Server API client utility +======================================== + +## SYNOPSIS + +__knife__ _sub-command_ [_argument_...] _(options)_ + +## 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: + + * bootstrap + * client + * configure + * cookbook-site + * cookbook + * data-bag + * environment + * exec + * index + * node + * recipe + * role + * search + * ssh + * status + * tag + +If the knife manuals are in your `MANPATH`, you can access help for the +above topics using `man knife-TOPIC`; otherwise, you can view the +documentation using `knife help TOPIC`. + +## OPTIONS + * `-s`, `--server-url` URL: + Chef Server URL, corresponds to `Chef::Config` `chef_server_url`. + * `-k`, `--key` KEY: + API Client Key, corresponds to `Chef::Config` `client_key`. + * `-c`, `--config` CONFIG: + The configuration file to use + * `-E`, `--environment ENVIRONMENT`: + Set the Chef environment + * `-e`, `--editor` EDITOR: + Set the editor to use for interactive commands + * `-F`, `--format` FORMAT: + Which format to use for output. See FORMATS for details. + * `-d`, `--disable-editing`: + Do not open EDITOR, just accept the data as is + * `-u`, `--user` USER: + API Client Username, corresponds to `Chef::Config` `node_name`. + * `-p`, `--print-after`: + Show the data after a destructive operation + * `-v`, `--version`: + Show chef version + * `-V`, `--verbose`: + More verbose output. Use twice for max verbosity. + * `-y`, `--yes`: + Say yes to all prompts for confirmation + * `--defaults`: + Accept default values for all questions + * `--[no-]color`: + Use colored output. Color enabled by default. + * `-h`, `--help`: + Show the available options for a command. + +## SUB-COMMANDS + +Sub-commands that operate on the basic Chef data types are structured as +_NOUN verb NOUN (options)_. For all data types, the following commands +are available: + +* create (create) +* list and show (read) +* edit (update) +* delete (destroy) + +Knife also includes commands that take actions other than displaying or +modifying data on the Chef Server, such as __knife-ssh(1)__. + +## CONFIGURATION + +The knife configuration file is a Ruby DSL to set configuration +parameters for Knife's __GENERAL OPTIONS__. The default location for the +config file is `~/.chef/knife.rb`. If managing multiple Chef +repositories, per-repository config files can be created. The file must +be `.chef/knife.rb` in the current directory of the repository. + +If the config file exists, knife uses these settings for __GENERAL OPTIONS__ defaults. + + * `node_name`: + User or client identity (i.e., _name_) to use for authenticating + requests to the Chef Server. + * `client_key`: + Private key file to authenticate to the Chef server. Corresponds to the + `-k` or `--key` option. + * `chef_server_url`: + URL of the Chef server. Corresponds to the `-s` or `--server-url` + option. This is requested from the user when running this sub-command. + * `cache_type`: + The type of cache to use. Default is BasicFile. This can be any type of + Cache that moneta supports: BasicFile, Berkeley, Couch, DataMapper, + File, LMC, Memcache, Memory, MongoDB, Redis, Rufus, S3, SDBM, Tyrant, + Xattr, YAML. + * `cache_options`: + Specifies various options to use for caching. These options are + dependent on the `cache_type`. + * `validation_client_name`: + Specifies the name of the client used to validate new clients. + * `validation_key`: + Specifies the private key file to use when bootstrapping new hosts. + See knife-client(1) for more information about the validation + client. + * `cookbook_copyright`, `cookbook_email`, `cookbook_license`, `readme_format` + Used by `knife cookbook create` 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. + +## FILES + +_~/.chef/knife.rb_ + +Ruby DSL configuration file for knife. See __CONFIGURATION__. + +## FORMATS + +The amount of content displayed and the output format are +modified by the `--format` option. If no alternate format is selected, +the default is summary. + +Valid formats are: + + * `summary`: + displays the node in a custom, summarized format (default) + * `text`: + displays the node data in its entirety using the colorized tree display + * `json`: + displays the node in JSON format + * `yaml`: + displays the node in YAML format + * `pp`: + displays the node using Ruby's pretty printer. + +For brevity, only the first character of the format is required, for +example, -Fj will produce JSON format output. + +## CHEF WORKFLOW + +When working with Chef and Knife in the local repository, the recommended workflow outline looks like: + +* Create repository. A skeleton sample is provided at _http://github.com/opscode/chef-repo/_. +* Configure knife, see __CONFIGURATION__. +* Download cookbooks from the Opscode cookbooks site, see __COOKBOOK SITE SUB-COMMANDS__. +* Or, create new cookbooks, see `cookbook create` sub-command. +* Commit changes to the version control system. See your tool's documentation. +* Upload cookbooks to the Chef Server, see __COOKBOOK SUB-COMMANDS__. +* Launch instances in the Cloud, OR provision new hosts; see __CLOUD COMPUTING SUB-COMMANDS__ and __BOOTSTRAP SUB-COMMANDS__. +* Watch Chef configure systems! + +A note about git: Opscode and many folks in the Chef community use git, +but it is not required, except in the case of the `cookbook site vendor` +sub-command, as it uses git directly. Version control is strongly +recommended though, and git fits with a lot of the workflow paradigms. + + +## EXAMPLES + + +## ENVIRONMENT + * `EDITOR`: + 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. + +## SEE ALSO + __chef-client(8)__ __chef-server(8)__ __chef-shell(1)__ + + __knife-bootstrap(1)__ __knife-client(1)__ __knife-configure(1)__ + __knife-cookbook-site(1)__ __knife-cookbook(1)__ __knife-data-bag(1)__ + __knife-environment(1)__ __knife-exec(1)__ __knife-index(1)__ + __knife-node(1)__ __knife-recipe(1)__ __knife-role(1)__ + __knife-search(1)__ __knife-ssh(1)__ __knife-tag(1)__ + + Complete Chef documentation is available online: <http://wiki.opscode.com/display/chef/Home/> + + JSON is JavaScript Object Notation <http://json.org/> + + SOLR is an open source search engine. <http://lucene.apache.org/solr/> + + __git(1)__ is a version control system <http://git-scm.com/> + + This manual page was generated from Markdown with __ronn(1)__ <http://rtomayko.github.com/ronn/ronn.1.html> + +## AUTHOR + Chef was written by Adam Jacob <adam@opscode.com> of Opscode + (<http://www.opscode.com>), with contributions from the community. + +## DOCUMENTATION + This manual page was written by Joshua Timberman <joshua@opscode.com>. + +## LICENSE + Both Chef and this documentation are released under the terms of the + Apache 2.0 License. You may view the license online: <http://www.apache.org/licenses/LICENSE-2.0.html> + On some systems, the complete text of the Apache 2.0 License may be found in `/usr/share/common-licenses/Apache-2.0`. + +## CHEF + Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home> + diff --git a/distro/common/markdown/man8/chef-client.mkd b/distro/common/markdown/man8/chef-client.mkd new file mode 100644 index 0000000000..e37d283133 --- /dev/null +++ b/distro/common/markdown/man8/chef-client.mkd @@ -0,0 +1,74 @@ +chef-client(8) -- Runs a client node connecting to a chef-server. +======================================== + +## SYNOPSIS + +__chef-client__ _(options)_ + + * `-S`, `--server CHEFSERVERURL`: + The chef server URL + * `-c`, `--config CONFIG`: + The configuration file to use + * `-d`, `--daemonize`: + Daemonize the process + * `-g`, `--group GROUP`: + Group to set privilege to + * `-i`, `--interval SECONDS`: + Run chef-client periodically, in seconds + * `-j`, `--json-attributes JSON_ATTRIBS`: + Load attributes from a JSON file or URL + * `-E`, `--environment ENVIRONMENT`: + Set the Chef Environment on the node + * `-l`, `--log_level LEVEL`: + Set the log level (debug, info, warn, error, fatal) + * `-L`, `--logfile LOGLOCATION`: + Set the log file location, defaults to STDOUT - recommended for + daemonizing + * `-N`, `--node-name NODE_NAME`: + The node name for this client + * `-o`, `--override-runlist`: + Replace current run list with specified items + * `-K`, `--validation_key KEY_FILE`: + Set the validation key file location, used for registering new clients + * `-k`, `--client_key KEY_FILE`: + Set the client key file location + * `-s`, `--splay SECONDS`: + The splay time for running at intervals, in seconds + * `-u`, `--user USER`: + User to set privilege to + * `-P`, `--pid PIDFILE`: + Set the PID file location, defaults to /tmp/chef-client.pid + * `--once`: + Cancel any interval or splay options, run chef once and exit + * `-v`, `--version`: + Show chef version + * `-h`, `--help`: + Show this message + +## 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. + +A Chef Client does work on behalf of a Node. A single Chef Client can +run recipes for multiple Nodes. + +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. + +## SEE ALSO + +Full documentation for Chef and chef-client is located on the Chef +wiki, http://wiki.opscode.com/display/chef/Home. + +## AUTHOR + +Chef was written by Adam Jacob <adam@ospcode.com> of Opscode +(http://www.opscode.com), with contributions from the community. This +manual page was written by Joshua Timberman <joshua@opscode.com> with +help2man. Permission is granted to copy, distribute and / or modify +this document under the terms of the Apache 2.0 License. + +On Debian systems, the complete text of the Apache 2.0 License can be +found in /usr/share/common-licenses/Apache-2.0. diff --git a/distro/common/markdown/man8/chef-expander.mkd b/distro/common/markdown/man8/chef-expander.mkd new file mode 100644 index 0000000000..d72ee1df9f --- /dev/null +++ b/distro/common/markdown/man8/chef-expander.mkd @@ -0,0 +1,82 @@ +chef-expander(8) -- fetches messages from RabbitMQ, processes, and loads into chef-solr +======================================== + +## SYNOPSIS + +__chef-expander__ _(options)_ + + * `-c`, `--config CONFIG_FILE`: + a configuration file to use + * `-i`, `--index INDEX`: + the slot this node will occupy in the ring + * `-n`, `--node-count NUMBER`: + the number of nodes in the ring + * `-l`, `--log-level LOG_LEVEL`: + set the log level + * `-L`, `--logfile LOG_LOCATION`: + Logfile to use + * `-d`, `--daemonize`: + fork into the background + * `-P`, `--pid PIDFILE`: + PID file + * `-h`, `--help`: + show help message + * `-v`, `--version`: + show the version and exit + +## DESCRIPTION + +Chef Expander fetches messages from RabbitMQ, processes them into the +correct format to be loaded into Solr and loads them into Solr. + +__Running Chef Expander__ + +Chef Expander is designed for clustered operation, though small +installations will only need one worker process. To run Chef +Expander with one worker process, run chef-expander -n 1. +You will then have a master and worker process, which looks like +this in ps: + + your-shell> ps aux|grep expander + you 52110 0.1 0.7 2515476 62748 s003 S+ 3:49PM 0:00.80 chef-expander worker #1 (vnodes 0-1023) + you 52108 0.1 0.5 2492880 41696 s003 S+ 3:49PM 0:00.91 ruby bin/chef-expander -n 1 + +Workers are single threaded and therefore cannot use more than 100% +of a single CPU. If you find that your queues are getting backlogged, +increase the number of workers + +__Design__ + +Chef Expander uses 1024 queues (called vnodes in some places) to allow +you to scale the number of Chef Expander workers to meet the needs of +your infrastructure. When objects are saved in the API server, they are +added to queues based on their database IDs. These queues can be assigned +to different Chef Expander workers to distribute the load of processing +the index updates. + +__Chef Expander Operation and Troubleshooting__ + +Chef Expander includes chef-expanderctl, a management program that allows +you to get status information or change the logging verbosity (without +restarting). + +See __chef-expanderctl__(8) for details. + +## SEE ALSO + +__chef-expanderctl__(8) +__chef-solr__(8) + +Full documentation for Chef and chef-server is located on the Chef +wiki, http://wiki.opscode.com/display/chef/Home. + +## AUTHOR + +Chef was written by Adam Jacob <adam@ospcode.com> of Opscode +(http://www.opscode.com), with contributions from the community. This +manual page was created by Nuo Yan <nuo@opscode.com>. Permission is +granted to copy, distribute and / or modify this document under the +terms of the Apache 2.0 License. + +On Debian systems, the complete text of the Apache 2.0 License can be +found in /usr/share/common-licenses/Apache-2.0.
\ No newline at end of file diff --git a/distro/common/markdown/man8/chef-expanderctl.mkd b/distro/common/markdown/man8/chef-expanderctl.mkd new file mode 100644 index 0000000000..00b34e7734 --- /dev/null +++ b/distro/common/markdown/man8/chef-expanderctl.mkd @@ -0,0 +1,58 @@ +chef-expanderctl(8) -- management program for chef-expander +======================================== + +## SYNOPSIS + +__chef-expanderctl__ _COMMAND_ + +__Commands:__ + + * `help`: + Show help message + * `queue-depth`: + display the aggregate queue backlog + * `queue-status`: + show the backlog and consumer count for each vnode queue + * `node-status`: + show the status of the nodes in the cluster + * `log-level`: + sets the log level of all nodes in the cluster + +## DESCRIPTION + +Chef-expanderctl is a management program that allows +you to get status information or change the logging +verbosity (without restarting). chef-expanderctl has +the following commands: + +* __chef-expanderctl help__ +prints usage. +* __chef-expanderctl queue-depth__ +Shows the total number of messages in the queues. +* __chef-expanderctl queue-status__ +Show the number of messages in each queue. This is mainly of use when +debugging a Chef Expander cluster. +* __chef-expanderctl log-level LEVEL__ +Sets the log level on a running Chef Expander or cluster. +If you suspect that a worker process is stuck, as long as you are using +clustered operation, you can simply kill the worker process and it will +be restarted by the master process. + +## SEE ALSO + +__chef-expander-cluster__(8) +__chef-solr__(8) + +Full documentation for Chef and chef-server is located on the Chef +wiki, http://wiki.opscode.com/display/chef/Home. + +## AUTHOR + +Chef was written by Adam Jacob <adam@ospcode.com> of Opscode +(http://www.opscode.com), with contributions from the community. This +manual page was created by Nuo Yan <nuo@opscode.com>. Permission is +granted to copy, distribute and / or modify this document under the +terms of the Apache 2.0 License. + +On Debian systems, the complete text of the Apache 2.0 License can be +found in /usr/share/common-licenses/Apache-2.0.
\ No newline at end of file diff --git a/distro/common/markdown/man8/chef-server-webui.mkd b/distro/common/markdown/man8/chef-server-webui.mkd new file mode 100644 index 0000000000..977e1495e2 --- /dev/null +++ b/distro/common/markdown/man8/chef-server-webui.mkd @@ -0,0 +1,121 @@ +chef-server-webui(8) -- Start the Chef Server merb application slice providing Web User Interface (Management Console). +======================================== + +## SYNOPSIS + +__chef-server-webui__ _(options)_ + + * `-u`, `--user USER`: + This flag is for having chef-server-webui run as a user other than the + one currently logged in. Note: if you set this you must also provide a + --group option for it to take effect. + * `-G`, `--group GROUP`: + This flag is for having chef-server-webui run as a group other than the + one currently logged in. Note: if you set this you must also provide a + --user option for it to take effect. + * `-d`, `--daemonize`: + This will run a single chef-server-webui in the background. + * `-N`, `--no-daemonize`: + This will allow you to run a cluster in console mode. + * `-c`, `--cluster-nodes NUM_MERBS`: + Number of merb daemons to run for chef-server-webui. + * `-I`, `--init-file FILE`: + File to use for initialization on load, defaults to config/init.rb. + * `-p`, `--port PORTNUM`: + Port to run chef-server-webui on, defaults to 4040. Additional nodes (-c) + listen on incrementing port numbers. + * `-o`, `--socket-file FILE`: + Socket file to run chef-server-webui on, defaults to + [Merb.root]/log/merb.sock. This is for web servers, like thin, that use + sockets. Specify this *only* if you *must*. + * `-s`, `--socket SOCKNUM`: + Socket number to run chef-server-webui on, defaults to 0. + * `-n`, `--name NAME`: + Set the name of the application. This is used in the process title and + log file names. + * `-P`, `--pid PIDFILE`: + PID file, defaults to [Merb.root]/log/merb.main.pid for the master + process and[Merb.root]/log/merb.[port number].pid for worker processes. + For clusters, use %s to specify where in the file chef-server-webui + should place the port number. For instance: -P myapp.%s.pid. + * `-h`, `--host HOSTNAME`: + Host to bind to (default is 0.0.0.0). + * `-m`, `--merb-root PATH_TO_APP_ROOT`: + The path to the Merb.root for the app you want to run + (default is current working directory). + * `-a`, `--adapter ADAPTER`: + The rack adapter to use to run chef-server-webui (default is mongrel) + [mongrel, emongrel, thin, ebb, fastcgi, webrick]. + * `-R`, `--rackup FILE`: + Load an alternate Rack config file (default is config/rack.rb). + * `-i`, `--irb-console`: + This flag will start chef-server-webui in irb console mode. All your models + and other classes will be available for you in an irb session. + * `-S`, `--sandbox`: + This flag will enable a sandboxed irb console. If your ORM supports + transactions, all edits will be rolled back on exit. + * `-l`, `--log-level LEVEL`: + Log levels can be set to any of these options: + debug < info < warn < error < fatal (default is info). + * `-L`, `--log LOGFILE`: + A string representing the logfile to use. Defaults to + [Merb.root]/log/merb.[main].log for the master process and + [Merb.root]/log/merb[port number].logfor worker processes. + * `-e`, `--environment STRING`: + Environment to run Merb under [development, production, testing] + (default is development). + * `-r`, `--script-runner ['RUBY CODE'| FULL_SCRIPT_PATH]`: + Command-line option to run scripts and/or code in the chef-server-webui + app. + * `-K`, `-graceful PORT or all`: + Gracefully kill chef-server-webui proceses by port number. + Use chef-server -K all to gracefully kill all merbs. + * `-k`, `--kill PORT`: + Force kill one merb worker by port number. This will cause the worker + to be respawned. + * `--fast-deploy`: + Reload the code, but not yourinit.rb or gems. + * `-X`, `--mutex on/off`: + This flag is for turning the mutex lock on and off. + * `-D`, `--debugger`: + Run chef-server-webui using rDebug. + * `-V`, `--verbose`: + Print extra information. + * `-C`, `--console-trap`: + Enter an irb console on ^C. + * `-?`, `-H`, `--help`: + Show this help message. + +## DESCRIPTION + +The Chef Server WebUI (Management Console) is a Merb application slice. +The default listen port is 4040. + +The Management Console is Chef Server's web interface. Nodes, roles, +cookbooks, data bags, and API clients can be managed through the Management +Console. Search can also be done on the console. + +In order to start using the Management Console, you need to first create +a user or change the default password on the "admin" user. + +The default credentials are: + +- `Username`: admin +- `Password`: p@ssw0rd1 + +## SEE ALSO + +Full documentation for Chef and chef-server-webui (Management Console) +is located on the Chef wiki, http://wiki.opscode.com/display/chef/Home. + +## AUTHOR + +Chef was written by Adam Jacob <adam@ospcode.com> of Opscode +(http://www.opscode.com), with contributions from the community. This +manual page was written by Joshua Timberman <joshua@opscode.com> with +help2man for the Debian project (but may be used by others). Permission +is granted to copy, distribute and / or modify this document under the +terms of the Apache 2.0 License. + +On Debian systems, the complete text of the Apache 2.0 License can be +found in /usr/share/common-licenses/Apache-2.0. diff --git a/distro/common/markdown/man8/chef-server.mkd b/distro/common/markdown/man8/chef-server.mkd new file mode 100644 index 0000000000..1b0f35eb77 --- /dev/null +++ b/distro/common/markdown/man8/chef-server.mkd @@ -0,0 +1,121 @@ +chef-server(8) - Start the Chef Server merb application slice. +======================================== + +## SYNOPSIS + +__chef-server__ _(options)_ + + * `-u`, `--user USER`: + This flag is for having chef-server-webui run as a user other than the + one currently logged in. Note: if you set this you must also provide a + --group option for it to take effect. + * `-G`, `--group GROUP`: + This flag is for having chef-server-webui run as a group other than the + one currently logged in. Note: if you set this you must also provide a + --user option for it to take effect. + * `-d`, `--daemonize`: + This will run a single chef-server-webui in the background. + * `-N`, `--no-daemonize`: + This will allow you to run a cluster in console mode. + * `-c`, `--cluster-nodes NUM_MERBS`: + Number of merb daemons to run for chef-server-webui. + * `-I`, `--init-file FILE`: + File to use for initialization on load, defaults to config/init.rb. + * `-p`, `--port PORTNUM`: + Port to run chef-server-webui on, defaults to 4040. Additional nodes (-c) + listen on incrementing port numbers. + * `-o`, `--socket-file FILE`: + Socket file to run chef-server-webui on, defaults to + [Merb.root]/log/merb.sock. This is for web servers, like thin, that use + sockets. Specify this *only* if you *must*. + * `-s`, `--socket SOCKNUM`: + Socket number to run chef-server-webui on, defaults to 0. + * `-n`, `--name NAME`: + Set the name of the application. This is used in the process title and + log file names. + * `-P`, `--pid PIDFILE`: + PID file, defaults to [Merb.root]/log/merb.main.pid for the master + process and[Merb.root]/log/merb.[port number].pid for worker processes. + For clusters, use %s to specify where in the file chef-server-webui + should place the port number. For instance: -P myapp.%s.pid. + * `-h`, `--host HOSTNAME`: + Host to bind to (default is 0.0.0.0). + * `-m`, `--merb-root PATH_TO_APP_ROOT`: + The path to the Merb.root for the app you want to run + (default is current working directory). + * `-a`, `--adapter ADAPTER`: + The rack adapter to use to run chef-server-webui (default is mongrel) + [mongrel, emongrel, thin, ebb, fastcgi, webrick]. + * `-R`, `--rackup FILE`: + Load an alternate Rack config file (default is config/rack.rb). + * `-i`, `--irb-console`: + This flag will start chef-server-webui in irb console mode. All your models + and other classes will be available for you in an irb session. + * `-S`, `--sandbox`: + This flag will enable a sandboxed irb console. If your ORM supports + transactions, all edits will be rolled back on exit. + * `-l`, `--log-level LEVEL`: + Log levels can be set to any of these options: + debug < info < warn < error < fatal (default is info). + * `-L`, `--log LOGFILE`: + A string representing the logfile to use. Defaults to + [Merb.root]/log/merb.[main].log for the master process and + [Merb.root]/log/merb[port number].logfor worker processes. + * `-e`, `--environment STRING`: + Environment to run Merb under [development, production, testing] + (default is development). + * `-r`, `--script-runner ['RUBY CODE'| FULL_SCRIPT_PATH]`: + Command-line option to run scripts and/or code in the chef-server-webui + app. + * `-K`, `-graceful PORT or all`: + Gracefully kill chef-server-webui proceses by port number. + Use chef-server -K all to gracefully kill all merbs. + * `-k`, `--kill PORT`: + Force kill one merb worker by port number. This will cause the worker + to be respawned. + * `--fast-deploy`: + Reload the code, but not yourinit.rb or gems. + * `-X`, `--mutex on/off`: + This flag is for turning the mutex lock on and off. + * `-D`, `--debugger`: + Run chef-server-webui using rDebug. + * `-V`, `--verbose`: + Print extra information. + * `-C`, `--console-trap`: + Enter an irb console on ^C. + * `-?`, `-H`, `--help`: + Show this help message. + +## DESCRIPTION + +The Chef Server provides a central point for the distribution of Cookbooks, +management and authentication of Nodes, and the use of Search. It provides +a REST API. + +The API service is what clients use to interact with the server to manage +node configuration in Chef. By default, the service is started on port 4000 +as a Merb application slice running with the thin server adapter. + +The two methods of interaction with the API for humans are the command-line +tool Knife and the Management Console. The Chef Client library is used for +interacting with the API for client nodes. + +## SEE ALSO + +__chef-client__(8) +__chef-server-webui__(8) +__knife__(1) + +Full documentation for Chef and chef-server is located on the Chef +wiki, http://wiki.opscode.com/display/chef/Home. + +## AUTHOR + +Chef was written by Adam Jacob <adam@ospcode.com> of Opscode +(http://www.opscode.com), with contributions from the community. This +manual page was written by Joshua Timberman <joshua@opscode.com> with +help2man. Permission is granted to copy, distribute and / or modify +this document under the terms of the Apache 2.0 License. + +On Debian systems, the complete text of the Apache 2.0 License can be +found in /usr/share/common-licenses/Apache-2.0. diff --git a/distro/common/markdown/man8/chef-solo.mkd b/distro/common/markdown/man8/chef-solo.mkd new file mode 100644 index 0000000000..861a0faa2d --- /dev/null +++ b/distro/common/markdown/man8/chef-solo.mkd @@ -0,0 +1,107 @@ +chef-solo(8) -- Runs chef in solo mode against a specified cookbook location. +======================================== + +## SYNOPSIS + +__chef-solo__ _(options)_ + + * `-c`, `--config CONFIG`: + The configuration file to use + * `-d`, `--daemonize`: + Daemonize the process + * `-g`, `--group GROUP`: + Group to set privilege to + * `-i`, `--interval SECONDS`: + Run chef-client periodically, in seconds + * `-j`, `--json-attributes JSON_ATTRIBS`: + Load attributes from a JSON file or URL + * `-l`, `--log_level LEVEL`: + Set the log level (debug, info, warn, error, fatal) + * `-L`, `--logfile LOGLOCATION`: + Set the log file location, defaults to STDOUT - recommended for + daemonizing + * `-N`, `--node-name NODE_NAME`: + The node name for this client + * `-r`, `--recipe-url RECIPE_URL`: + Pull down a remote gzipped tarball of recipes and untar it to the + cookbook cache. + * `-s`, `--splay SECONDS`: + The splay time for running at intervals, in seconds + * `-u`, `--user USER`: + User to set privilege to + * `-v`, `--version`: + Show chef version + * `-h`, `--help`: + Show this message + +## 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. + +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. + +For example: + file_cache_path "/var/chef-solo" + cookbook_path "/var/chef-solo/cookbooks" + +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. + +You can also specify cookbook_path as an array, passing multiple locations +to search for cookbooks. + +For example: + file_cache_path "/var/chef-solo" + cookbook_path ["/var/chef-solo/cookbooks", "/var/chef-solo/site-cookbooks"] + +Note that earlier entries are now overridden by later ones. + +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. + +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: + + { + "resolver": { + "nameservers": [ "10.0.0.1" ], + "search":"int.example.com" + }, + "run_list": [ "recipe[resolver]" ] + } + +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. + +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. + +For example: + chef-solo -c ~/solo.rb -j ~/node.json -r http://www.example.com/chef-solo.tar.gz + +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. + +## SEE ALSO + +Full documentation for Chef and chef-solo is located on the Chef wiki, +http://wiki.opscode.com/display/chef/Home. + +## AUTHOR + +Chef was written by Adam Jacob <adam@ospcode.com> of Opscode +(http://www.opscode.com), with contributions from the community. This +manual page was written by Joshua Timberman <joshua@opscode.com> with +help2man. Permission is granted to copy, distribute and / or modify +this document under the terms of the Apache 2.0 License. + +On Debian systems, the complete text of the Apache 2.0 License can be +found in /usr/share/common-licenses/Apache-2.0. diff --git a/distro/common/markdown/man8/chef-solr.mkd b/distro/common/markdown/man8/chef-solr.mkd new file mode 100644 index 0000000000..02e7d6285e --- /dev/null +++ b/distro/common/markdown/man8/chef-solr.mkd @@ -0,0 +1,89 @@ +chef-solr(8) -- Runs as Chef's search server +======================================== + +## SYNOPSIS + +__chef-solr__ _(options)_ + + * `-c`, `--config CONFIG`: + The configuration file to use + * `-d`, `--daemonize`: + Daemonize the process + * `-g`, `--group GROUP`: + Group to set privilege to + * `-l`, `--log_level LEVEL`: + Set the log level (debug, info, warn, error, fatal) + * `-L`, `--logfile LOGLOCATION`: + Set the log file location, defaults to STDOUT - recommended for daemonizing + * `-P`, `--pid PIDFILE`: + Set the PID file location, defaults to /tmp/chef-solr.pid + * `-D`, `--solr-data-dir PATH`: + Where the Solr data lives + * `-x`, `--solor-heap-size SIZE`: + Set the size of the Java Heap + * `-H`, `--solr-home-dir PATH`: + Solr home directory + * `-j`, `--java-opts OPTS`: + Raw options passed to Java + * `-x`, `--solor-heap-size`: + Set the size of the Java Heap + * `-W`, `--solr-jetty-dir PATH`: + Where to place the Solr Jetty instance + * `-u`, `--user USER`: + User to set privilege to + * `-v`, `--version`: + Show chef-solr version + * `-h`, `--help`: + Show this message + +## DESCRIPTION + +Chef-solr provides search service for Chef. You need to have both +chef-solr and chef-expander-cluster running in order for search to work. + +__Installation__ + +Make sure you backed up your data if you are upgrading from a previous version. +Run chef-solr-installer to upgrade your Chef Solr installation. Answer "yes" +when prompted for confirmation. The process should look like this: + + yourshell> chef-solr-installer + Configuration setting solr_heap_size is unknown and will be ignored + + Chef Solr is already installed in /var/chef/solr + Do you want to overwrite the current install? All existing Solr data will be lost. [y/n] y + Removing the existing Chef Solr installation + rm -rf /var/chef/solr + rm -rf /var/chef/solr-jetty + rm -rf /var/chef/solr/data + Creating Solr Home Directory + mkdir -p /var/chef/solr + entering /var/chef/solr + tar zxvf /Users/ddeleo/opscode/chef/chef-solr/solr/solr-home.tar.gz + Creating Solr Data Directory + mkdir -p /var/chef/solr/data + Unpacking Solr Jetty + mkdir -p /var/chef/solr-jetty + entering /var/chef/solr-jetty + tar zxvf /Users/ddeleo/opscode/chef/chef-solr/solr/solr-jetty.tar.gz + + Successfully installed Chef Solr. + You can restore your search index using `knife index rebuild` + +## SEE ALSO + +__chef-expander-cluster__(8) + +Full documentation for Chef and chef-server is located on the Chef +wiki, http://wiki.opscode.com/display/chef/Home. + +## AUTHOR + +Chef was written by Adam Jacob <adam@ospcode.com> of Opscode +(http://www.opscode.com), with contributions from the community. This +manual page was written by Joshua Timberman <joshua@opscode.com> with +help2man. Permission is granted to copy, distribute and / or modify +this document under the terms of the Apache 2.0 License. + +On Debian systems, the complete text of the Apache 2.0 License can be +found in /usr/share/common-licenses/Apache-2.0. |