path: root/distro/common/man/man1/knife-cookbook.1

.\" Man page generated from reStructuredText.
.
.TH "KNIFE-COOKBOOK" "1" "Chef 11.16" "" "knife cookbook"
.SH NAME
knife-cookbook \- The man page for the knife cookbook subcommand.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
A cookbook is the fundamental unit of configuration and policy distribution. Each cookbook defines a scenario, such as everything needed to install and configure MySQL, and then it contains all of the components that are required to support that scenario, including:
.INDENT 0.0
.IP \(bu 2
Attribute values that are set on nodes
.IP \(bu 2
Definitions that allow the creation of reusable collections of resources
.IP \(bu 2
File distributions
.IP \(bu 2
Libraries that extend the chef\-client and/or provide helpers to Ruby code
.IP \(bu 2
Recipes that specify which resources to manage and the order in which those resources will be applied
.IP \(bu 2
Custom resources and providers
.IP \(bu 2
Templates
.IP \(bu 2
Versions
.IP \(bu 2
Metadata about recipes (including dependencies), version constraints, supported platforms, and so on
.UNINDENT
.sp
The \fBknife cookbook\fP subcommand is used to interact with cookbooks that are located on the Chef server or the local chef\-repo\&.
.SH COMMON OPTIONS
.sp
The following options may be used with any of the arguments available to the \fBknife cookbook\fP subcommand:
.INDENT 0.0
.TP
.B \fB\-\-chef\-zero\-port PORT\fP
The port on which chef\-zero will listen.
.TP
.B \fB\-c CONFIG_FILE\fP, \fB\-\-config CONFIG_FILE\fP
The configuration file to use.
.TP
.B \fB\-d\fP, \fB\-\-disable\-editing\fP
Use to prevent the $EDITOR from being opened and to accept data as\-is.
.TP
.B \fB\-\-defaults\fP
Use to have knife use the default value instead of asking a user to provide one.
.TP
.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP
The $EDITOR that is used for all interactive commands.
.TP
.B \fB\-E ENVIRONMENT\fP, \fB\-\-environment ENVIRONMENT\fP
The name of the environment. When this option is added to a command, the command will run only against the named environment.
.TP
.B \fB\-F FORMAT\fP, \fB\-\-format FORMAT\fP
The output format: \fBsummary\fP (default), \fBtext\fP, \fBjson\fP, \fByaml\fP, and \fBpp\fP\&.
.TP
.B \fB\-h\fP, \fB\-\-help\fP
Shows help for the command.
.TP
.B \fB\-k KEY\fP, \fB\-\-key KEY\fP
The private key that knife will use to sign requests made by the API client to the Chef server\&.
.TP
.B \fB\-\-[no\-]color\fP
Use to view colored output.
.TP
.B \fB\-\-print\-after\fP
Use to show data after a destructive operation.
.TP
.B \fB\-s URL\fP, \fB\-\-server\-url URL\fP
The URL for the Chef server\&.
.TP
.B \fB\-u USER\fP, \fB\-\-user USER\fP
The user name used by knife to sign requests made by the API client to the Chef server\&. Authentication will fail if the user name does not match the private key.
.TP
.B \fB\-V\fP, \fB\-\-verbose\fP
Set for more verbose outputs. Use \fB\-VV\fP for maximum verbosity.
.TP
.B \fB\-v\fP, \fB\-\-version\fP
The version of the chef\-client\&.
.TP
.B \fB\-y\fP, \fB\-\-yes\fP
Use to respond to all confirmation prompts with "Yes". knife will not ask for confirmation.
.TP
.B \fB\-z\fP, \fB\-\-local\-mode\fP
Use to run the chef\-client in local mode. This allows all commands that work against the Chef server to also work against the local chef\-repo\&.
.UNINDENT
.SH BULK DELETE
.sp
The \fBbulk delete\fP argument is used to delete cookbook files that match a pattern defined by a regular expression. The regular expression must be within quotes and not be surrounded by forward slashes (/).
.sp
\fBSyntax\fP
.sp
This argument has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook bulk delete REGEX (options)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This argument has the following options:
.INDENT 0.0
.TP
.B \fB\-p\fP, \fB\-\-purge\fP
Use to entirely remove a cookbook (or cookbook version) from the Chef server\&. This action should be used carefully because only one copy of any single file is stored on the Chef server\&. Consequently, purging a cookbook will disable any other cookbook that references one or more files from a cookbook that has been purged.
.UNINDENT
.sp
\fBExamples\fP
.sp
Use a regular expression to define the pattern used to bulk delete cookbooks:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook bulk delete "^[0\-9]{3}$" \-p
.ft P
.fi
.UNINDENT
.UNINDENT
.SH CREATE
.sp
The \fBcreate\fP argument is used to create a new cookbook directory on the local machine, including the following directories and files:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
cookbook/attributes
.IP \(bu 2
cookbook/CHANGELOG.md
.IP \(bu 2
cookbook/definitions
.IP \(bu 2
cookbook/files/default
.IP \(bu 2
cookbook/libraries
.IP \(bu 2
cookbook/metadata.rb
.IP \(bu 2
cookbook/providers
.IP \(bu 2
cookbook/README.md (or .rdoc)
.IP \(bu 2
cookbook/recipes/default.rb
.IP \(bu 2
cookbook/resources
.IP \(bu 2
cookbook/templates/default
.UNINDENT
.UNINDENT
.UNINDENT
.sp
After the cookbook is created, it can be uploaded to the Chef server using the \fBknife upload\fP argument.
.sp
\fBSyntax\fP
.sp
This argument has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook create COOKBOOK_NAME (options)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This argument has the following options:
.INDENT 0.0
.TP
.B \fB\-C COPYRIGHT_HOLDER\fP, \fB\-\-copyright COPYRIGHT_HOLDER\fP
The name of the copyright holder. This option will place a copyright notice that contains the name of the copyright holder in each of the pre\-created files. If this option is not specified, a copyright name of "your_company_name" will be used instead; it can be easily modified later.
.TP
.B \fB\-I LICENSE\fP, \fB\-\-license LICENSE\fP
The type of license under which a cookbook is distributed: \fBapachev2\fP, \fBgplv2\fP, \fBgplv3\fP, \fBmit\fP, or \fBnone\fP (default). This option will place the appropriate license notice in the pre\-created files: \fBApache v2.0\fP (for \fBapachev2\fP), \fBGPL v2\fP (for \fBgplv2\fP), \fBGPL v3\fP (for \fBgplv3\fP), \fBMIT\fP (for \fBmit\fP), or \fBlicense \(aqProprietary \- All Rights Reserved\fP (for \fBnone\fP). Be aware of the licenses for files inside of a cookbook and be sure to follow any restrictions they describe.
.TP
.B \fB\-m EMAIL\fP, \fB\-\-email EMAIL\fP
The email address for the individual who maintains the cookbook. This option will place an email address in each of the pre\-created files. If this option is not specified, an email name of "your_email" will be used instead; it can be easily modified later.
.TP
.B \fB\-o PATH\fP, \fB\-\-cookbook\-path PATH\fP
The directory in which cookbooks are created. This can be a colon\-separated path.
.TP
.B \fB\-r FORMAT\fP, \fB\-\-readme\-format FORMAT\fP
The document format of the readme file: \fBmd\fP (markdown) and \fBrdoc\fP (Ruby docs).
.UNINDENT
.sp
\fBExamples\fP
.sp
To create a cookbook named "my_cookbook" with copyright, email, license, and readme format options specified, enter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook create my_cookbook \-C "My Name" \-m "my@email.com" \-I apachev2 \-r md
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to return something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
** Creating cookbook my_cookbook
** Creating README for cookbook: my_cookbook
** Creating metadata for cookbook: my_cookbook
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DELETE
.sp
The \fBdelete\fP argument is used to delete a specified cookbook or cookbook version on the Chef server (and not locally).
.sp
\fBSyntax\fP
.sp
This argument has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook delete COOKBOOK_NAME [COOKBOOK_VERSION] (options)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This argument has the following options:
.INDENT 0.0
.TP
.B \fB\-a\fP, \fB\-\-all\fP
Use to delete all cookbooks (and cookbook versions).
.TP
.B \fBCOOKBOOK_VERSION\fP
The version of a cookbook to be deleted. If a cookbook has only one version, this option does not need to be specified. If a cookbook has more than one version and this option is not specified, knife will prompt for a version.
.TP
.B \fB\-p\fP, \fB\-\-purge\fP
Use to entirely remove a cookbook (or cookbook version) from the Chef server\&. This action should be used carefully because only one copy of any single file is stored on the Chef server\&. Consequently, purging a cookbook will disable any other cookbook that references one or more files from a cookbook that has been purged.
.UNINDENT
.sp
\fBExamples\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook delete cookbook_name version
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook delete smartmon 0.8
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Type \fBY\fP to confirm a deletion.
.SH DOWNLOAD
.sp
The \fBdownload\fP argument is used to download a cookbook from the Chef server to the current working directory.
.sp
\fBSyntax\fP
.sp
This argument has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook download COOKBOOK_NAME [COOKBOOK_VERSION] (options)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This argument has the following options:
.INDENT 0.0
.TP
.B \fB\-d DOWNLOAD_DIRECTORY\fP, \fB\-\-dir DOWNLOAD_DIRECTORY\fP
The directory in which cookbooks are located.
.TP
.B \fB\-f\fP, \fB\-\-force\fP
Use to overwrite an existing directory.
.TP
.B \fB\-N\fP, \fB\-\-latest\fP
Use to download the most recent version of a cookbook.
.UNINDENT
.sp
\fBExamples\fP
.sp
To download a cookbook named "smartmon", enter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook download smartmon
.ft P
.fi
.UNINDENT
.UNINDENT
.SH LIST
.sp
The \fBlist\fP argument is used to view a list of cookbooks that are currently available on the Chef server\&. The list will contain only the most recent version for each cookbook by default.
.sp
\fBSyntax\fP
.sp
This argument has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook list (options)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This argument has the following options:
.INDENT 0.0
.TP
.B \fB\-a\fP, \fB\-\-all\fP
Use to return all available versions for every cookbook.
.TP
.B \fB\-w\fP, \fB\-\-with\-uri\fP
Use to show the corresponding URIs.
.UNINDENT
.sp
\fBExamples\fP
.sp
To view a list of cookbooks:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook list
.ft P
.fi
.UNINDENT
.UNINDENT
.SH METADATA
.sp
The \fBmetadata\fP argument is used to generate the metadata for one or more cookbooks.
.sp
\fBSyntax\fP
.sp
This argument has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook metadata (options)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This argument has the following options:
.INDENT 0.0
.TP
.B \fB\-a\fP, \fB\-\-all\fP
Use to generate metadata for all cookbooks.
.TP
.B \fB\-o PATH:PATH\fP, \fB\-\-cookbook\-path PATH:PATH\fP
The directory in which cookbooks are created. This can be a colon\-separated path.
.UNINDENT
.sp
\fBExamples\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook metadata \-a
.ft P
.fi
.UNINDENT
.UNINDENT
.SH METADATA FROM FILE
.sp
The \fBmetadata from file\fP argument is used to load the metadata for a cookbook from a file.
.sp
\fBSyntax\fP
.sp
This argument has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook metadata from file FILE
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This command does not have any specific options.
.sp
\fBExamples\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook metadata from file /path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SHOW
.sp
The \fBshow\fP argument is used to view information about a cookbook, parts of a cookbook (attributes, definitions, files, libraries, providers, recipes, resources, and templates), or a file that is associated with a cookbook (including attributes such as checksum or specificity).
.sp
\fBSyntax\fP
.sp
This argument has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook show COOKBOOK_NAME [COOKBOOK_VERSION] [PART...] [FILE_NAME] (options)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This argument has the following options:
.INDENT 0.0
.TP
.B \fBCOOKBOOK_VERSION\fP
The version of a cookbook to be shown. If a cookbook has only one version, this option does not need to be specified. If a cookbook has more than one version and this option is not specified, a list of cookbook versions will be returned.
.TP
.B \fB\-f FQDN\fP, \fB\-\-fqdn FQDN\fP
The FQDN of the host.
.TP
.B \fBFILE_NAME\fP
The name of a file that is associated with a cookbook.
.TP
.B \fB\-p PLATFORM\fP, \fB\-\-platform PLATFORM\fP
The platform for which a cookbook is designed.
.TP
.B \fBPART\fP
The part of the cookbook to show: \fBattributes\fP, \fBdefinitions\fP, \fBfiles\fP, \fBlibraries\fP, \fBproviders\fP, \fBrecipes\fP, \fBresources\fP, or \fBtemplates\fP\&. More than one part can be specified.
.TP
.B \fB\-V PLATFORM_VERSION\fP, \fB\-\-platform\-version PLATFORM_VERSION\fP
The version of the platform.
.TP
.B \fB\-w\fP, \fB\-\-with\-uri\fP
Use to show the corresponding URIs.
.UNINDENT
.sp
\fBExamples\fP
.sp
To get the list of available versions of a cookbook named "getting\-started", enter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook show getting\-started
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to return something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
getting\-started   0.3.0  0.2.0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To show a list of data about a cookbook using the name of the cookbook and the version, enter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook show getting\-started 0.3.0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to return something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
attributes:
  checksum:     fa0fc4abf3f6787aeb5c3c5c35de667c
  name:         default.rb
  path:         attributes/default.rb
  specificity:  default
  url:          https://somelongurlhere.com
chef_type:      cookbook_version
cookbook_name:  getting\-started
definitions:    []
files:          []
frozen?:        false
json_class:     Chef::CookbookVersion
libraries:      []
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To only view data about "templates", enter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook show getting\-started 0.3.0 templates
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to return something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
checksum:     a29d6f254577b830091f140c3a78b1fe
name:         chef\-getting\-started.txt.erb
path:         templates/default/chef\-getting\-started.txt.erb
specificity:  default
url:          https://someurlhere.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To view information in JSON format, use the \fB\-F\fP common option as part of the command like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife role show devops \-F json
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Other formats available include \fBtext\fP, \fByaml\fP, and \fBpp\fP\&.
.SH TEST
.sp
The \fBtest\fP argument is used to test a cookbook for syntax errors. This argument uses Ruby syntax checking to verify every file in a cookbook that ends in .rb and Embedded Ruby (ERB)\&. This argument will respect \&.chefignore files when determining which cookbooks to test for syntax errors.
.sp
\fBSyntax\fP
.sp
This argument has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook test COOKBOOK_NAME (options)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This argument has the following options:
.INDENT 0.0
.TP
.B \fB\-a\fP, \fB\-\-all\fP
Use to test all cookbooks.
.TP
.B \fB\-o PATH:PATH\fP, \fB\-\-cookbook\-path PATH:PATH\fP
The directory in which cookbooks are created. This can be a colon\-separated path.
.UNINDENT
.sp
\fBExamples\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook test cookbook_name
.ft P
.fi
.UNINDENT
.UNINDENT
.SH UPLOAD
.sp
The \fBupload\fP argument is used to upload one or more cookbooks (and any files that are associated with those cookbooks) from a local repository to the Chef server\&. Only files that do not already exist on the Chef server will be uploaded.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Use a \&.chefignore file to prevent the upload of specific files and file types, such as temporary files or files placed in folders by version control systems. The \&.chefignore file must be located in the root of the cookbook repository and must use rules similar to filename globbing (as defined by the Ruby \fBFile.fnmatch\fP syntax).
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Empty directories are not uploaded to the Chef server\&. To upload an empty directory, create a "dot" file\-\-\-e.g. \fB\&.keep\fP\-\-\-in that directory to ensure that the directory itself is not empty.
.UNINDENT
.UNINDENT
.sp
\fBSyntax\fP
.sp
This argument has the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook upload [COOKBOOK_NAME...] (options)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBOptions\fP
.sp
This argument has the following options:
.INDENT 0.0
.TP
.B \fB\-a\fP, \fB\-\-all\fP
Use to upload all cookbooks.
.TP
.B \fB\-\-concurrency\fP
The number of allowed concurrent connections. Default: \fB10\fP\&.
.TP
.B \fB\-d\fP, \fB\-\-include\-dependencies\fP
Use to ensure that when a cookbook has a dependency on one (or more) cookbooks, those cookbooks will also be uploaded.
.TP
.B \fB\-E ENVIRONMENT\fP, \fB\-\-environment ENVIRONMENT\fP
Use to set the environment version dependency to the cookbook version being uploaded.
.TP
.B \fB\-\-force\fP
Use to update a cookbook even if the \fB\-\-freeze\fP flag has been set.
.TP
.B \fB\-\-freeze\fP
Use to require changes to a cookbook be included as a new version. Only the \fB\-\-force\fP option can override this setting.
.TP
.B \fB\-o PATH:PATH\fP, \fB\-\-cookbook\-path PATH:PATH\fP
The directory in which cookbooks are created. This can be a colon\-separated path.
.UNINDENT
.sp
\fBExamples\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook upload cookbook_name
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To upload a cookbook, and then prevent other users from being able to make changes to it, enter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knife cookbook upload redis \-\-freeze
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to return something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Uploading redis...
Upload completed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a cookbook is frozen and the \fB\-\-force\fP option is not specified, knife will return an error message similar to the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Uploading redis...
ERROR: Version 0.1.6 of cookbook redis is frozen. Use \-\-force to override.
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
Chef
.\" Generated by docutils manpage writer.
.