chef 12.10.24 → 12.11.18

data/distro/common/man/man1/knife-role.1

@@ -1,426 +1,426 @@
-.\" Man page generated from reStructuredText.
-.
-.TH "KNIFE-ROLE" "1" "Chef 12.0" "" "knife role"
-.SH NAME
-knife-role \- The man page for the knife role 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 role is a way to define certain patterns and processes that exist across nodes in an organization as belonging to a single job function. Each role consists of zero (or more) attributes and a run\-list. Each node can have zero (or more) roles assigned to it. When a role is run against a node, the configuration details of that node are compared against the attributes of the role, and then the contents of that role\(aqs run\-list are applied to the node\(aqs configuration details. When a chef\-client runs, it merges its own attributes and run\-lists with those contained within each assigned role.
-.sp
-The \fBknife role\fP subcommand is used to manage the roles that are associated with one or more nodes on a Chef server\&.
-.SH COMMON OPTIONS
-.sp
-The following options may be used with any of the arguments available to the \fBknife role\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 one or more roles 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 role bulk delete REGEX
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBOptions\fP
-.sp
-This command does not have any specific options.
-.sp
-\fBExamples\fP
-.sp
-Use a regular expression to define the pattern used to bulk delete roles:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role bulk delete "^[0\-9]{3}$"
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SH CREATE
-.sp
-The \fBcreate\fP argument is used to add a role to the Chef server\&. Role data is saved as JSON on the Chef server\&.
-.sp
-\fBSyntax\fP
-.sp
-This argument has the following syntax:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role create ROLE_NAME (options)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBOptions\fP
-.sp
-This argument has the following options:
-.INDENT 0.0
-.TP
-.B \fB\-d DESCRIPTION\fP, \fB\-\-description DESCRIPTION\fP
-The description of the role. This value will populate the description field for the role on the Chef server\&.
-.UNINDENT
-.sp
-\fBExamples\fP
-.sp
-To add a role named \fBrole1\fP, enter:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role create role1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-In the $EDITOR enter the role data in JSON:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-## sample:
-{
-   "name": "role1",
-   "default_attributes": {
-   },
-   "json_class": "Chef::Role",
-   "run_list": [\(aqrecipe[cookbook_name::recipe_name],
-                 role[role_name]\(aq
-   ],
-   "description": "",
-   "chef_type": "role",
-   "override_attributes": {
-   }
-}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-When finished, save it.
-.SH DELETE
-.sp
-The \fBdelete\fP argument is used to delete a role from the Chef server\&.
-.sp
-\fBSyntax\fP
-.sp
-This argument has the following syntax:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role delete ROLE_NAME
-.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 role delete devops
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Type \fBY\fP to confirm a deletion.
-.SH EDIT
-.sp
-The \fBedit\fP argument is used to edit role details on the Chef server\&.
-.sp
-\fBSyntax\fP
-.sp
-This argument has the following syntax:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role edit ROLE_NAME
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBOptions\fP
-.sp
-This command does not have any specific options.
-.sp
-\fBExamples\fP
-.sp
-To edit the data for a role named \fBrole1\fP, enter:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role edit role1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Update the role data in JSON:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-## sample:
-{
-   "name": "role1",
-   "default_attributes": {
-   },
-   "json_class": "Chef::Role",
-   "run_list": [\(aqrecipe[cookbook_name::recipe_name],
-                 role[role_name]\(aq
-   ],
-   "description": "This is the description for the role1 role.",
-   "chef_type": "role",
-   "override_attributes": {
-   }
-}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-When finished, save it.
-.SH FROM FILE
-.sp
-The \fBfrom file\fP argument is used to create a role using existing JSON data as a template.
-.sp
-\fBSyntax\fP
-.sp
-This argument has the following syntax:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role from file FILE
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBOptions\fP
-.sp
-This command does not have any specific options.
-.sp
-\fBExamples\fP
-.sp
-To view role details based on the values contained in a JSON file:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role from file "path to JSON file"
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SH LIST
-.sp
-The \fBlist\fP argument is used to view a list of roles that are currently available on the Chef server\&.
-.sp
-\fBSyntax\fP
-.sp
-This argument has the following syntax:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role list
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBOptions\fP
-.sp
-This argument has the following options:
-.INDENT 0.0
-.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 roles on the Chef server and display the URI for each role returned, enter:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role list \-w
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SH SHOW
-.sp
-The \fBshow\fP argument is used to view the details of a role.
-.sp
-\fBSyntax\fP
-.sp
-This argument has the following syntax:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ knife role show ROLE_NAME
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBOptions\fP
-.sp
-This argument has the following options:
-.INDENT 0.0
-.TP
-.B \fB\-a ATTR\fP, \fB\-\-attribute ATTR\fP
-The attribute (or attributes) to show.
-.UNINDENT
-.sp
-\fBExamples\fP
-.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\&.
-.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 AUTHOR
-Chef
-.\" Generated by docutils manpage writer.
-.
+.\" Man page generated from reStructuredText.
+.
+.TH "KNIFE-ROLE" "1" "Chef 12.0" "" "knife role"
+.SH NAME
+knife-role \- The man page for the knife role 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 role is a way to define certain patterns and processes that exist across nodes in an organization as belonging to a single job function. Each role consists of zero (or more) attributes and a run\-list. Each node can have zero (or more) roles assigned to it. When a role is run against a node, the configuration details of that node are compared against the attributes of the role, and then the contents of that role\(aqs run\-list are applied to the node\(aqs configuration details. When a chef\-client runs, it merges its own attributes and run\-lists with those contained within each assigned role.
+.sp
+The \fBknife role\fP subcommand is used to manage the roles that are associated with one or more nodes on a Chef server\&.
+.SH COMMON OPTIONS
+.sp
+The following options may be used with any of the arguments available to the \fBknife role\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 one or more roles 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 role bulk delete REGEX
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBOptions\fP
+.sp
+This command does not have any specific options.
+.sp
+\fBExamples\fP
+.sp
+Use a regular expression to define the pattern used to bulk delete roles:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role bulk delete "^[0\-9]{3}$"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH CREATE
+.sp
+The \fBcreate\fP argument is used to add a role to the Chef server\&. Role data is saved as JSON on the Chef server\&.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role create ROLE_NAME (options)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-d DESCRIPTION\fP, \fB\-\-description DESCRIPTION\fP
+The description of the role. This value will populate the description field for the role on the Chef server\&.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To add a role named \fBrole1\fP, enter:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role create role1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the $EDITOR enter the role data in JSON:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+## sample:
+{
+   "name": "role1",
+   "default_attributes": {
+   },
+   "json_class": "Chef::Role",
+   "run_list": [\(aqrecipe[cookbook_name::recipe_name],
+                 role[role_name]\(aq
+   ],
+   "description": "",
+   "chef_type": "role",
+   "override_attributes": {
+   }
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When finished, save it.
+.SH DELETE
+.sp
+The \fBdelete\fP argument is used to delete a role from the Chef server\&.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role delete ROLE_NAME
+.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 role delete devops
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Type \fBY\fP to confirm a deletion.
+.SH EDIT
+.sp
+The \fBedit\fP argument is used to edit role details on the Chef server\&.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role edit ROLE_NAME
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBOptions\fP
+.sp
+This command does not have any specific options.
+.sp
+\fBExamples\fP
+.sp
+To edit the data for a role named \fBrole1\fP, enter:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role edit role1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Update the role data in JSON:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+## sample:
+{
+   "name": "role1",
+   "default_attributes": {
+   },
+   "json_class": "Chef::Role",
+   "run_list": [\(aqrecipe[cookbook_name::recipe_name],
+                 role[role_name]\(aq
+   ],
+   "description": "This is the description for the role1 role.",
+   "chef_type": "role",
+   "override_attributes": {
+   }
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When finished, save it.
+.SH FROM FILE
+.sp
+The \fBfrom file\fP argument is used to create a role using existing JSON data as a template.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role from file FILE
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBOptions\fP
+.sp
+This command does not have any specific options.
+.sp
+\fBExamples\fP
+.sp
+To view role details based on the values contained in a JSON file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role from file "path to JSON file"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH LIST
+.sp
+The \fBlist\fP argument is used to view a list of roles that are currently available on the Chef server\&.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role list
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.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 roles on the Chef server and display the URI for each role returned, enter:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role list \-w
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SHOW
+.sp
+The \fBshow\fP argument is used to view the details of a role.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ knife role show ROLE_NAME
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-a ATTR\fP, \fB\-\-attribute ATTR\fP
+The attribute (or attributes) to show.
+.UNINDENT
+.sp
+\fBExamples\fP
+.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\&.
+.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 AUTHOR
+Chef
+.\" Generated by docutils manpage writer.
+.