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, 113 insertions, 478 deletions
diff --git a/distro/common/man/man1/knife-data-bag.1 b/distro/common/man/man1/knife-data-bag.1 index df44979710..2872837052 100644 --- a/distro/common/man/man1/knife-data-bag.1 +++ b/distro/common/man/man1/knife-data-bag.1 @@ -1,488 +1,123 @@ -.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 -.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP -The configuration file to use. -.TP -.B \fB\-\-color\fP -Indicates that colored output will be used. -.TP -.B \fB\-d\fP, \fB\-\-disable\-editing\fP -Indicates that $EDITOR will not be opened; data will be accepted as\-is. -.TP -.B \fB\-\-defaults\fP -Indicates that Knife will 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 FILE_NAME\fP, \fB\-\-file FILE_NAME\fP -Indicates that the private key will be saved to a specified file name. -.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 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. +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 +. +.TH "KNIFE\-DATA\-BAG" "1" "October 2013" "Chef 11.10.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 +. .TP -.B \fB\-\-secret SECRET\fP -The encryption key that is used for values contained within a data bag. +\fB\-s\fR, \fB\-\-secret SECRET\fR +A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. +. .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 +\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 +. .TP -.B \fB\-a\fP, \fB\-\-all\fP -Indicates that all data bags found at the specified path will be uploaded. +\fB\-s\fR, \fB\-\-secret SECRET\fR +A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. +. .TP -.B \fB\-\-secret SECRET\fP -The encryption key that is used for values contained within a data bag. +\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 +. .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 +\fB\-s\fR, \fB\-\-secret SECRET\fR +A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. +. .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 +\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 +. .TP -.B \fBDATA_BAG_ITEM\fP -The name of a specific item within a data bag. +\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 +. .TP -.B \fB\-\-secret SECRET\fP -The encryption key that is used for values contained within a data bag. +\fB\-s\fR, \fB\-\-secret SECRET\fR +A secret key used to encrypt the data bag item\. See \fBencryption support\fR below\. +. .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. +\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\. . +.SH "CHEF" +Knife is distributed with Chef\. http://wiki\.opscode\.com/display/chef/Home |