Provided by: chef_11.8.2-2_all
NAME
knife-cookbook - The man page for the knife cookbook subcommand. A cookbook is the fundamental unit of configuration and policy distribution. Each cookbook defines a scenario, such as everything needed to install and configure MySQL, and then it contains all of the components that are required to support that scenario, including: • Attribute values that are set on nodes • Definitions that allow the creation of reusable collections of resources • File distributions • Libraries that extend the chef-client and/or provide helpers to Ruby code • Recipes that specify which resources to manage and the order in which those resources will be applied • Custom resources and providers • Templates • Versions • Metadata about recipes (including dependencies), version constraints, supported platforms, and so on The knife cookbook subcommand is used to interact with cookbooks that are located on the server or the local chef-repo. This subcommand has the following syntax: $ knife cookbook [ARGUMENT] (options)
COMMON OPTIONS
The following options can be run with all Knife sub-commands and plug-ins: -c CONFIG, --config CONFIG The configuration file to use. --color Indicates that colored output will be used. -d, --disable-editing Indicates that $EDITOR will not be opened; data will be accepted as-is. --defaults Indicates that Knife will use the default value, instead of asking a user to provide one. -e EDITOR, --editor EDITOR The $EDITOR that is used for all interactive commands. -E ENVIRONMENT, --environment ENVIRONMENT The name of the environment. When this option is added to a command, the command will run only against the named environment. -f FILE_NAME, --file FILE_NAME Indicates that the private key will be saved to a specified file name. -F FORMAT, --format FORMAT The output format: summary (default), text, json, yaml, and pp. -h, --help Shows help for the command. -k KEY, --key KEY The private key that Knife will use to sign requests made by the API client to the server. --no-color Indicates that color will not be used in the output. -p PASSWORD, --password PASSWORD The user password. --print-after Indicates that data will be shown after a destructive operation. -s URL, --server-url URL The URL for the server. -u USER, --user USER The user name used by Knife to sign requests made by the API client to the server. Authentication will fail if the user name does not match the private key. -v, --version The version of the chef-client. -V, --verbose Set for more verbose outputs. Use -VV for maximum verbosity. -y, --yes Indicates that the response to all confirmation prompts will be "Yes" (and that Knife will not ask for confirmation).
BULK DELETE
The bulk delete argument is used to delete cookbook files that match a pattern defined by a regular expression. The regular expression must be within quotes and not be surrounded by forward slashes (/). Syntax This argument has the following syntax: $ knife cookbook bulk delete REGEX (options) Options This argument has the following options: -p, --purge Indicates that a cookbook (or cookbook version) will be removed entirely from the server. This action should be used carefully because only one copy of any single file is stored on the server. Consequently, purging a cookbook will disable any other cookbook that references one or more files from a cookbook that has been purged. Examples To bulk delete many cookbooks, use a regular expression to define the pattern: $ knife cookbook bulk delete "^[0-9]{3}$" -p
CREATE
The create argument is used to create a new cookbook directory on the local machine, including the following directories and files: • cookbook/attributes • cookbook/CHANGELOG.md • cookbook/definitions • cookbook/files/default • cookbook/libraries • cookbook/metadata.rb • cookbook/providers • cookbook/README.md (or .rdoc) • cookbook/recipes/default.rb • cookbook/resources • cookbook/templates/default After the cookbook is created, it can be uploaded to the server using the knife upload argument. Syntax This argument has the following syntax: $ knife cookbook create COOKBOOK_NAME (options) Options This argument has the following options: -C COPYRIGHT_HOLDER, --copyright COPYRIGHT_HOLDER The name of the copyright holder. This option will place a copyright notice that contains the name of the copyright holder in each of the pre-created files. If this option is not specified, a copyright name of "your_company_name" will be used instead; it can be easily modified later. -I LICENSE, --license LICENSE The type of license under which a cookbook is distributed: apachev2, gplv2, gplv3, mit, or none (default). This option will place the appropriate license notice in the pre-created files. Be aware of the licenses for files inside of a cookbook and be sure to follow any restrictions they describe. -m EMAIL, --email EMAIL The email address for the individual who maintains the cookbook. This option will place an email address in each of the pre-created files. If this option is not specified, an email name of "your_email" will be used instead; it can be easily modified later. -o PATH, --cookbook-path PATH The directory in which cookbook are created. This can be a colon-separated path. -r FORMAT, --readme-format FORMAT The document format of the readme file: md (markdown) and rdoc (Ruby docs). Examples To create a cookbook named "my_cookbook" with copyright, email, license, and readme format options specified, enter: $ knife cookbook create my_cookbook -C "My Name" -m "my@email.com" -I apachev2 -r md to return something like: ** Creating cookbook my_cookbook ** Creating README for cookbook: my_cookbook ** Creating metadata for cookbook: my_cookbook
DELETE
The delete argument is used to delete a specified cookbook or cookbook version on the server (and not locally). Syntax This argument has the following syntax: $ knife cookbook delete COOKBOOK_NAME [COOKBOOK_VERSION] (options) Options This argument has the following options: -a, --all Indicates that a cookbook and every version of that cookbook will be deleted. COOKBOOK_VERSION The version of a cookbook to be deleted. If a cookbook has only one version, this option does not need to be specified. If a cookbook has more than one version and this option is not specified, Knife will prompt for a version. -p, --purge Indicates that a cookbook (or cookbook version) will be removed entirely from the server. This action should be used carefully because only one copy of any single file is stored on the server. Consequently, purging a cookbook will disable any other cookbook that references one or more files from a cookbook that has been purged. Examples To delete version "0.8" from a cookbook named "smartmon", enter: $ knife cookbook delete smartmon 0.8 Type Y to confirm a deletion.
DOWNLOAD
The download argument is used to download a cookbook from the server to the current working directory. Syntax This argument has the following syntax: $ knife cookbook download COOKBOOK_NAME [COOKBOOK_VERSION] (options) Options This argument has the following options: -d DOWNLOAD_DIRECTORY, --dir DOWNLOAD_DIRECTORY The directory into which a cookbook will be downloaded. -f, --force Indicates that an existing directory will be overwritten. -N, --latest Indicates that the most recent version of a cookbook will be downloaded. Examples To download a cookbook named "smartmon", enter: $ knife cookbook download smartmon
LIST
The list argument is used to view a list of cookbooks that are currently available on the server. The list will contain only the most recent version for each cookbook by default. Syntax This argument has the following syntax: $ knife cookbook list (options) Options This argument has the following options: -a, --all Indicates that all available versions of each cookbook will be returned. -w, --with-uri Indicates that the corresponding URIs will be shown. Examples To view a list of cookbooks: $ knife cookbook list
METADATA
The metadata argument is used to generate the metadata for one or more cookbooks. Syntax This argument has the following syntax: $ knife cookbook metadata (options) Options This argument has the following options: -a, --all Indicates that metadata should be generated for all cookbooks, and not just for a specified cookbook. -o PATH:PATH, --cookbook-path PATH:PATH The directory in which cookbook are created. This can be a colon-separated path. Examples To generate metadata for all cookbooks: $ knife cookbook metadata -a
METADATA FROM FILE
The metadata from file argument is used to load the metadata for a cookbook from a file. Syntax This argument has the following syntax: $ knife cookbook metadata from file FILE Options This command does not have any specific options. Examples To view cookbook metadata from a JSON file: $ knife cookbook metadta from file /path/to/file
SHOW
The show argument is used to view information about a cookbook, parts of a cookbook (attributes, definitions, files, libraries, providers, recipes, resources, and templates), or a file that is associated with a cookbook (including attributes such as checksum or specificity). Syntax This argument has the following syntax: $ knife cookbook show COOKBOOK_NAME [COOKBOOK_VERSION] [PART...] [FILE_NAME] (options) Options This argument has the following options: COOKBOOK_VERSION The version of a cookbook to be shown. If a cookbook has only one version, this option does not need to be specified. If a cookbook has more than one version and this option is not specified, a list of cookbook versions will be returned. -f FQDN, --fqdn FQDN The FQDN of the host. FILE_NAME The name of a file that is associated with a cookbook. -p PLATFORM, --platform PLATFORM The platform for which a cookbook is designed. PART The part of the cookbook to show: attributes, definitions, files, libraries, providers, recipes, resources, or templates. More than one part can be specified. -V PLATFORM_VERSION, --platform-version PLATFORM_VERSION The version of the platform. -w, --with-uri Indicates that the corresponding URIs will be shown. Examples To get the list of available versions of a cookbook named "getting-started", enter: $ knife cookbook show getting-started to return something like: getting-started 0.3.0 0.2.0 To show a list of data about a cookbook using the name of the cookbook and the version, enter: $ knife cookbook show getting-started 0.3.0 to return something like: attributes: checksum: fa0fc4abf3f6787aeb5c3c5c35de667c name: default.rb path: attributes/default.rb specificity: default url: https://somelongurlhere.com chef_type: cookbook_version cookbook_name: getting-started definitions: [] files: [] frozen?: false json_class: Chef::CookbookVersion libraries: [] To only view data about "templates", enter: $ knife cookbook show getting-started 0.3.0 templates to return something like: checksum: a29d6f254577b830091f140c3a78b1fe name: chef-getting-started.txt.erb path: templates/default/chef-getting-started.txt.erb specificity: default url: https://someurlhere.com To view information in JSON format, use the -F common option as part of the command like this: $ knife role show devops -F json Other formats available include text, yaml, and pp.
TEST
The test argument is used to test a cookbook for syntax errors. This argument uses Ruby syntax checking to verify every file in a cookbook that ends in .rb and Embedded Ruby (ERB). Syntax This argument has the following syntax: $ knife cookbook test COOKBOOK_NAME (options) Options This argument has the following options: -a, --all Indicates that all cookbooks will be tested. -o PATH:PATH, --cookbook-path PATH:PATH The directory in which cookbook are created. This can be a colon-separated path. Examples To test a cookbook named "getting-started", enter: $ knife cookbook test getting-started
UPLOAD
The upload argument is used to upload one or more cookbooks (and any files that are associated with those cookbooks) from a local repository to the server. Only files that do not already exist on the server will be uploaded. Note Use a chefignore file to prevent the upload of specific files and file types, such as temporary files or files placed in folders by version control systems. The chefignore file must be located in the root of the cookbook repository and must use rules similar to filename globbing (as defined by the Ruby File.fnmatch syntax). Syntax This argument has the following syntax: $ knife cookbook upload [COOKBOOK_NAME...] (options) Options This argument has the following options: -a, --all Indicates that all cookbooks will be uploaded. -d, --include-dependencies Indicates that when a cookbook has a dependency on one (or more) cookbooks, those cookbooks will also be uploaded. --force Indicates that a cookbook should be updated even if the --freeze flag has been set. --freeze Indicates that a cookbook cannot be modified; any changes to this cookbook must be included as a new version. Only the --force option can override this setting. -o PATH:PATH, --cookbook-path PATH:PATH The directory in which cookbook are created. This can be a colon-separated path. Examples To upload a cookbook named "getting-started": $ knife cookbook upload getting-started To upload a cookbook, and then prevent other users from being able to make changes to it, enter: $ knife cookbook upload redis --freeze to return something like: Uploading redis... Upload completed If a cookbook is frozen and the --force option is not specified, Knife will return an error message similar to the following: Uploading redis... ERROR: Version 0.1.6 of cookbook redis is frozen. Use --force to override.
AUTHOR
Opscode Chef 11.8.0 KNIFE-COOKBOOK(1)