diff options
Diffstat (limited to 'distro/common/man/man1/knife-data-bag.1')
| -rw-r--r-- | distro/common/man/man1/knife-data-bag.1 | 591 |
1 files changed, 478 insertions, 113 deletions
diff --git a/distro/common/man/man1/knife-data-bag.1 b/distro/common/man/man1/knife-data-bag.1 index 5aca0bf317..df44979710 100644 --- a/distro/common/man/man1/knife-data-bag.1 +++ b/distro/common/man/man1/knife-data-bag.1 @@ -1,123 +1,488 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "KNIFE\-DATA\-BAG" "1" "July 2013" "Chef 11.8.0.alpha.0" "Chef Manual" -. -.SH "NAME" -\fBknife\-data\-bag\fR \- Store arbitrary data on a Chef Server -. -.SH "SYNOPSIS" -\fBknife\fR \fBdata bag\fR \fIsub\-command\fR \fI(options)\fR -. -.SH "DESCRIPTION" -Data bags are stores of arbitrary JSON data\. Each data bag is a collection that may contain many items\. Data Bag Items are indexed by the Chef Server and can be searched via \fBknife\-search\fR(1)\. -. -.P -Data bags are available to all nodes configured by \fBchef\-client\fR(8), and are therefore a convenient mechanism to store global information, such as lists of administrative accounts that should be configured on all hosts\. -. -.SH "DATA BAG SUB\-COMMANDS" -. -.SH "CREATE" -\fBknife data bag create\fR \fIbag name\fR [item id] \fI(options)\fR -. +.TH "KNIFE-DATA-BAG" "1" "Chef 11.8" "" "knife data bag" +.SH NAME +knife-data-bag \- The man page for the knife data bag subcommand. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.\" Man page generated from reStructuredText. +. +.sp +A data bag is a global variable that is stored as JSON data and is accessible from a server. A data bag is indexed for searching and can be loaded by a recipe or accessed during a search. The contents of a data bag can vary, but they often include sensitive information (such as database passwords). +.sp +The contents of a data bag can be encrypted using \fI\%shared secret encryption\fP. This allows a data bag to store confidential information (such as a database password) or to be managed in a source control system (without plain\-text data appearing in revision history). +.sp +The \fBknife data bag\fP subcommand is used to manage arbitrary stores of globally available JSON data. +.sp +This subcommand has the following syntax: +.sp +.nf +.ft C +$ knife data bag [ARGUMENT] (options) +.ft P +.fi +.SH COMMON OPTIONS +.sp +The following options can be run with all Knife sub\-commands and plug\-ins: +.INDENT 0.0 .TP -\fB\-s\fR, \fB\-\-secret SECRET\fR -A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. -. +.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP +The configuration file to use. .TP -\fB\-\-secret\-file SECRET_FILE\fR -The path to a file containing the secret key to be used to encrypt the data bag item\. -. -.P -If \fIitem id\fR is given, creates a new, empty data bag item and opens it for editing in your editor\. The data bag will be created if it does not exist\. -. -.P -If \fIitem id\fR is not given, the data bag will be created\. -. -.SH "DELETE" -\fBknife data bag delete\fR \fIbag name\fR [item id] \fI(options)\fR -. -.P -Delete a data bag, or an item from a data bag\. -. -.SH "EDIT" -\fBknife data bag edit\fR \fIbag name\fR \fIitem id\fR \fI(options)\fR -. +.B \fB\-\-color\fP +Indicates that colored output will be used. .TP -\fB\-s\fR, \fB\-\-secret SECRET\fR -A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. -. +.B \fB\-d\fP, \fB\-\-disable\-editing\fP +Indicates that $EDITOR will not be opened; data will be accepted as\-is. .TP -\fB\-\-secret\-file SECRET_FILE\fR -The path to a file containing the secret key to be used to encrypt the data bag item\. -. -.P -Edit an item in a data bag\. -. -.SH "FROM FILE" -\fBknife data bag from file\fR \fIbag name\fR \fIfile\fR \fI(options)\fR -. -.P -\fBknife data bag from file\fR \fIbag name\fR \fIfile1\fR \fIfile2\fR \fIfile3\fR \fI(options)\fR -. -.P -\fBknife data bag from file\fR \fIbag name\fR \fIfolder\fR \fI(options)\fR -. +.B \fB\-\-defaults\fP +Indicates that Knife will use the default value, instead of asking a user to provide one. .TP -\fB\-s\fR, \fB\-\-secret SECRET\fR -A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. -. +.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP +The $EDITOR that is used for all interactive commands. .TP -\fB\-\-secret\-file SECRET_FILE\fR -The path to a file containing the secret key to be used to encrypt the data bag item\. -. -.P -Load a data bag item from a JSON file\. If \fIfile\fR is a relative or absolute path to the file, that file will be used\. Otherwise, the \fIfile\fR parameter is treated as the base name of a data bag file in a Chef repository, and \fBknife\fR will search for the file in \fB\./data_bags/bag_name/file\fR\. For example \fBknife data bag from file users dan\.json\fR would attempt to load the file \fB\./data_bags/users/dan\.json\fR\. -. -.SH "LIST" -\fBknife data bag list\fR \fI(options)\fR -. +.B \fB\-E ENVIRONMENT\fP, \fB\-\-environment ENVIRONMENT\fP +The name of the environment. When this option is added to a command, the command will run only against the named environment. .TP -\fB\-w\fR, \fB\-\-with\-uri\fR -Show corresponding URIs -. -.P -Lists the data bags that exist on the Chef Server\. -. -.SH "SHOW" -\fBknife data bag show BAG [ITEM]\fR \fI(options)\fR -. +.B \fB\-f FILE_NAME\fP, \fB\-\-file FILE_NAME\fP +Indicates that the private key will be saved to a specified file name. .TP -\fB\-s\fR, \fB\-\-secret SECRET\fR -A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. -. +.B \fB\-F FORMAT\fP, \fB\-\-format FORMAT\fP +The output format: \fBsummary\fP (default), \fBtext\fP, \fBjson\fP, \fByaml\fP, and \fBpp\fP. .TP -\fB\-\-secret\-file SECRET_FILE\fR -The path to a file containing the secret key to be used to encrypt the data bag item\. -. -.P -Show a specific data bag or an item in a data bag\. The output will be formatted according to the \-\-format option\. -. -.SH "ENCRYPTION SUPPORT" -Data Bag Items may be encrypted to keep their contents secret\. This may be desireable when storing sensitive information such as database passwords, API keys, etc\. -. -.P -Data Bag Item encryption uses the AES\-256 CBC symmetric key algorithm\. -. -.P -\fBCAVEATS:\fR Keys are not encrypted; only values are encrypted\. The "id" of a Data Bag Item is not encrypted, since it is used by Chef Server to store the item in its database\. For example, given the following data bag item: {"id": "important_passwords", "secret_password": "opensesame"} The key "secret_password" will be visible to an evesdropper, but the value "opensesame" will be protected\. Both the key "id" and its value "important_passwords" will be visible to an evesdropper\. -. -.P -Chef Server does not provide a secure mechanism for distributing encryption keys\. -. -.SH "SEE ALSO" -\fBknife\-search\fR(1) -. -.SH "AUTHOR" -Chef was written by Adam Jacob \fIadam@opscode\.com\fR with many contributions from the community\. -. -.SH "DOCUMENTATION" -This manual page was written by Joshua Timberman \fIjoshua@opscode\.com\fR\. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2\.0 License\. +.B \fB\-h\fP, \fB\-\-help\fP +Shows help for the command. +.TP +.B \fB\-k KEY\fP, \fB\-\-key KEY\fP +The private key that Knife will use to sign requests made by the API client to the server. +.TP +.B \fB\-\-no\-color\fP +Indicates that color will not be used in the output. +.TP +.B \fB\-p PASSWORD\fP, \fB\-\-password PASSWORD\fP +The user password. +.TP +.B \fB\-\-print\-after\fP +Indicates that data will be shown after a destructive operation. +.TP +.B \fB\-s URL\fP, \fB\-\-server\-url URL\fP +The URL for the server. +.TP +.B \fB\-u USER\fP, \fB\-\-user USER\fP +The user name used by Knife to sign requests made by the API client to the server. Authentication will fail if the user name does not match the private key. +.TP +.B \fB\-v\fP, \fB\-\-version\fP +The version of the chef\-client. +.TP +.B \fB\-V\fP, \fB\-\-verbose\fP +Set for more verbose outputs. Use \fB\-VV\fP for maximum verbosity. +.TP +.B \fB\-y\fP, \fB\-\-yes\fP +Indicates that the response to all confirmation prompts will be "Yes" (and that Knife will not ask for confirmation). +.UNINDENT +.SH CREATE +.sp +The \fBcreate\fP argument is used to add a data bag to the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag create DATA_BAG_NAME [DATA_BAG_ITEM] (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fBDATA_BAG_ITEM\fP +The name of a specific item within a data bag. +.TP +.B \fB\-\-secret SECRET\fP +The encryption key that is used for values contained within a data bag. +.TP +.B \fB\-\-secret\-file FILE\fP +The path to the file that contains the encryption key. +.UNINDENT +.IP Note +For encrypted data bag items, use \fIeither\fP \fB\-\-secret\fP or \fB\-\-secret\-file\fP, not both. +.RE +.sp +\fBExamples\fP +.sp +To create a data bag named "admins", enter: +.sp +.nf +.ft C +$ knife data bag create admins +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +Created data_bag[admins] +.ft P +.fi +.SH DELETE +.sp +The \fBdelete\fP argument is used to delete a data bag or a data bag item from a server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag delete DATA_BAG_NAME [DATA_BAG_ITEM] (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fBDATA_BAG_ITEM\fP +The name of a specific item within a data bag. +.UNINDENT +.sp +\fBExamples\fP +.sp +To a data bag named "admins", enter: +.sp +.nf +.ft C +$ knife data bag delete admins +.ft P +.fi +.sp +To delete an item named "charlie", enter: +.sp +.nf +.ft C +$ knife data bag delete admins charlie +.ft P +.fi +.sp +Type \fBY\fP to confirm a deletion. +.SH EDIT +.sp +The \fBedit\fP argument is used to edit the data contained in a data bag. If encryption is being used, the data bag will be decrypted, the data will be made available in the $EDITOR, and then encrypted again before saving it to the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag edit DATA_BAG_NAME [DATA_BAG_ITEM] (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fBDATA_BAG_ITEM\fP +The name of a specific item within a data bag. +.TP +.B \fB\-\-secret SECRET\fP +The encryption key that is used for values contained within a data bag. +.TP +.B \fB\-\-secret\-file FILE\fP +The path to the file that contains the encryption key. +.UNINDENT +.IP Note +For encrypted data bag items, use \fIeither\fP \fB\-\-secret\fP or \fB\-\-secret\-file\fP, not both. +.RE +.sp +\fBExamples\fP +.sp +To edit the contents of a data bag, enter: +.sp +.nf +.ft C +$ knife data bag edit admins +.ft P +.fi +.sp +To edit an item named "charlie" that is contained in a data bag named "admins", enter: +.sp +.nf +.ft C +$ knife data bag edit admins charlie +.ft P +.fi +.sp +to open the $EDITOR. Once opened, you can update the data before saving it to the server. For example, by changing: +.sp +.nf +.ft C +{ + "id": "charlie" +} +.ft P +.fi +.sp +to: +.sp +.nf +.ft C +{ + "id": "charlie", + "uid": 1005, + "gid":"ops", + "shell":"/bin/zsh", + "comment":"Crazy Charlie" +} +.ft P +.fi +.SH FROM FILE +.sp +The \fBfrom file\fP argument is used to create a data bag on the server from a file. The path to the data bag file must specify one of the following: +.INDENT 0.0 +.IP \(bu 2 +the name of a data bag +.IP \(bu 2 +a relative or absolute path to a file +.UNINDENT +.sp +If the name of a data bag is specified, Knife will search for the data bag in \fB./data_bags/bag_name/file\fP. Once opened, the JSON file should be a hash that contains at least an ID key which represents the name of the data bag item. +.IP Warning +A chef\-client must be version 11.6 (or higher) when using the \fBknife data bag from file\fP argument with the Enterprise Chef or Open Source Chef version 11 servers. +.RE +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag from file DATA_BAG_NAME_or_PATH +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-a\fP, \fB\-\-all\fP +Indicates that all data bags found at the specified path will be uploaded. +.TP +.B \fB\-\-secret SECRET\fP +The encryption key that is used for values contained within a data bag. +.TP +.B \fB\-\-secret\-file FILE\fP +The path to the file that contains the encryption key. +.UNINDENT +.IP Note +For encrypted data bag items, use \fIeither\fP \fB\-\-secret\fP or \fB\-\-secret\-file\fP, not both. +.RE +.sp +\fBExamples\fP +.sp +To create a data bag on the server from a file: +.sp +.nf +.ft C +$ knife data bag from file "path to JSON file" +.ft P +.fi +.sp +To create a data bag named "devops_data" that contains encrypted data, enter: +.sp +.nf +.ft C +$ knife data bag from file devops_data \-\-secret\-file "path to decryption file" +.ft P +.fi +.SH LIST +.sp +The \fBlist\fP argument is used to view a list of data bags that are currently available on the server. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag list +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fB\-w\fP, \fB\-\-with\-uri\fP +Indicates that the corresponding URIs will be shown. +.UNINDENT +.sp +\fBExamples\fP +.sp +For example, to view a list of data bags on the server, enter: +.sp +.nf +.ft C +$ knife data bag list +.ft P +.fi +.SH SHOW +.sp +The \fBshow\fP argument is used to view the contents of a data bag. +.sp +\fBSyntax\fP +.sp +This argument has the following syntax: +.sp +.nf +.ft C +$ knife data bag show DATA_BAG_NAME (options) +.ft P +.fi +.sp +\fBOptions\fP +.sp +This argument has the following options: +.INDENT 0.0 +.TP +.B \fBDATA_BAG_ITEM\fP +The name of a specific item within a data bag. +.TP +.B \fB\-\-secret SECRET\fP +The encryption key that is used for values contained within a data bag. +.TP +.B \fB\-\-secret\-file FILE\fP +The path to the file that contains the encryption key. +.UNINDENT +.IP Note +For encrypted data bag items, use \fIeither\fP \fB\-\-secret\fP or \fB\-\-secret\-file\fP, not both. +.RE +.sp +\fBExamples\fP +.sp +To show the contents of a data bag, enter: +.sp +.nf +.ft C +$ knife data bag show admins +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +charlie +.ft P +.fi +.sp +To show the contents of a specific item within data bag, enter: +.sp +.nf +.ft C +$ knife data bag show admins charlie +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +comment: Crazy Charlie +gid: ops +id: charlie +shell: /bin/zsh +uid: 1005 +.ft P +.fi +.sp +To show the contents of a data bag named "passwords" with an item that contains encrypted data named "mysql", enter: +.sp +.nf +.ft C +$ knife data bag show passwords mysql +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +## sample: +{ + "id": "mysql", + "pass": "trywgFA6R70NO28PNhMpGhEvKBZuxouemnbnAUQsUyo=\en", + "user": "e/p+8WJYVHY9fHcEgAAReg==\en" +} +.ft P +.fi +.sp +To show the decrypted contents of the same data bag, enter: +.sp +.nf +.ft C +$ knife data bag show \-\-secret\-file /path/to/decryption/file passwords mysql +.ft P +.fi +.sp +to return: +.sp +.nf +.ft C +## sample: +{ + "id": "mysql", + "pass": "thesecret123", + "user": "fred" +} +.ft P +.fi +.sp +To view information in JSON format, use the \fB\-F\fP common option as part of the command like this: +.sp +.nf +.ft C +$ knife data bag show admins \-F json +.ft P +.fi +.sp +Other formats available include \fBtext\fP, \fByaml\fP, and \fBpp\fP. +.SH AUTHOR +Opscode +.SH COPYRIGHT +This work is licensed under a Creative Commons Attribution 3.0 Unported License +.\" Generated by docutils manpage writer. . -.SH "CHEF" -Knife is distributed with Chef\. http://wiki\.opscode\.com/display/chef/Home |