Provided by: chef_12.3.0-3ubuntu1_all bug

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
       Chef server or the local chef-repo.

COMMON OPTIONS

       The following options may be used with  any  of  the  arguments  available  to  the  knife
       cookbook subcommand:

       --chef-zero-port PORT
              The port on which chef-zero will listen.

       -c CONFIG_FILE, --config CONFIG_FILE
              The configuration file to use.

       -d, --disable-editing
              Use to prevent the $EDITOR from being opened and to accept data as-is.

       --defaults
              Use to have knife 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 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
              Chef server.

       --[no-]color
              Use to view colored output.

       --print-after
              Use to show data after a destructive operation.

       -s URL, --server-url URL
              The URL for the Chef server.

       -u USER, --user USER
              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.

       -V, --verbose
              Set for more verbose outputs. Use -VV for maximum verbosity.

       -v, --version
              The version of the chef-client.

       -y, --yes
              Use to respond to all confirmation prompts with  "Yes".  knife  will  not  ask  for
              confirmation.

       -z, --local-mode
              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.

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
              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.

       Examples

       Use a regular expression to define the pattern used to bulk delete cookbooks:

          $ 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  Chef  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: Apache v2.0 (for apachev2), GPL v2 (for gplv2), GPL v3  (for
              gplv3), MIT (for mit), or license 'Proprietary - All Rights Reserved (for none). 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 cookbooks 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 Chef
       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
              Use to delete all cookbooks (and cookbook versions).

       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
              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.

       Examples

          $ knife cookbook delete cookbook_name version

       For example:

          $ knife cookbook delete smartmon 0.8

       Type Y to confirm a deletion.

DOWNLOAD

       The  download  argument is used to download a cookbook from the Chef 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 in which cookbooks are located.

       -f, --force
              Use to overwrite an existing directory.

       -N, --latest
              Use to download the most recent version of a cookbook.

       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
       Chef  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
              Use to return all available versions for every cookbook.

       -w, --with-uri
              Use to show the corresponding URIs.

       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
              Use to generate metadata for all cookbooks.

       -o PATH:PATH, --cookbook-path PATH:PATH
              The directory in which cookbooks are created. This can be a colon-separated path.

       Examples

          $ 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

          $ knife cookbook metadata 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
              Use to show the corresponding URIs.

       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). This argument will respect .chefignore files when determining  which  cookbooks  to
       test for syntax errors.

       Syntax

       This argument has the following syntax:

          $ knife cookbook test COOKBOOK_NAME (options)

       Options

       This argument has the following options:

       -a, --all
              Use to test all cookbooks.

       -o PATH:PATH, --cookbook-path PATH:PATH
              The directory in which cookbooks are created. This can be a colon-separated path.

       Examples

          $ knife cookbook test cookbook_name

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 Chef  server.  Only  files
       that do not already exist on the Chef 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).

       NOTE:
          Empty directories are not uploaded to the Chef server. To upload  an  empty  directory,
          create  a  "dot"  file---e.g.  .keep---in  that  directory to ensure that the directory
          itself is not empty.

       Syntax

       This argument has the following syntax:

          $ knife cookbook upload [COOKBOOK_NAME...] (options)

       Options

       This argument has the following options:

       -a, --all
              Use to upload all cookbooks.

       --concurrency
              The number of allowed concurrent connections. Default: 10.

       -d, --include-dependencies
              Use to ensure that when a cookbook has a dependency on  one  (or  more)  cookbooks,
              those cookbooks will also be uploaded.

       -E ENVIRONMENT, --environment ENVIRONMENT
              Use  to  set  the  environment  version  dependency  to  the cookbook version being
              uploaded.

       --force
              Use to update a cookbook even if the --freeze flag has been set.

       --freeze
              Use to require changes to a cookbook 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 cookbooks are created. This can be a colon-separated path.

       Examples

          $ knife cookbook upload cookbook_name

       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

       Chef

                                            Chef 12.0                           KNIFE-COOKBOOK(1)