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

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