diff options
Diffstat (limited to 'docs/cvtsudoers.man.in')
| -rw-r--r-- | docs/cvtsudoers.man.in | 782 |
1 files changed, 767 insertions, 15 deletions
diff --git a/docs/cvtsudoers.man.in b/docs/cvtsudoers.man.in index 5e65be3bf..2b5ac6b78 100644 --- a/docs/cvtsudoers.man.in +++ b/docs/cvtsudoers.man.in @@ -16,7 +16,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.TH "CVTSUDOERS" "1" "February 16, 2022" "Sudo @PACKAGE_VERSION@" "General Commands Manual" +.TH "CVTSUDOERS" "1" "September 29, 2022" "Sudo @PACKAGE_VERSION@" "General Commands Manual" .nh .if n .ad l .SH "NAME" @@ -67,9 +67,8 @@ The options are as follows: The base DN (distinguished name) that will be used when performing LDAP queries. Typically this is of the form -\fRou=SUDOers,dc=my-domain,dc=com\fR -for the domain -\fRmy-domain.com\fR. +\(lqou=SUDOers,dc=my-domain,dc=com\(rq +for the domain my-domain.com. If this option is not specified, the value of the \fRSUDOERS_BASE\fR environment variable will be used instead. @@ -82,10 +81,10 @@ Defaults to .TP 12n \fB\-d\fR \fIdeftypes\fR, \fB\--defaults\fR=\fIdeftypes\fR Only convert -\fRDefaults\fR +\fIDefaults\fR entries of the specified types. One or more -\fRDefaults\fR +\fIDefaults\fR types may be specified, separated by a comma (\(oq\&,\(cq). The supported types are: @@ -122,7 +121,7 @@ for more information. If the \fB\-d\fR option is not specified, all -\fRDefaults\fR +\fIDefaults\fR entries will be converted. .RE .TP 12n @@ -143,12 +142,9 @@ The following formats are supported: CSV CSV (comma-separated value) files are often used by spreadsheets and report generators. -For CSV output, -\fBcvtsudoers\fR -double quotes strings that contain commas. -For each literal double quote character present inside the string, -two double quotes are output. -This method of quoting commas is compatible with most spreadsheet programs. +See +\fICSV output format\fR +for more details. .PD .TP 10n JSON @@ -160,6 +156,9 @@ The various values have explicit types which removes much of the ambiguity of the \fIsudoers\fR format. +See +\fIJSON output format\fR +for more details. .TP 10n LDIF LDIF (LDAP Data Interchange Format) files can be imported into an LDAP @@ -264,7 +263,12 @@ For example, \fBuser\fR = \fIoperator\fR or \fBhost\fR = \fIwww\fR. -An upper-case Cmnd_Alias, Host_alias, or Host_Alias may be specified as the +An upper-case +\fICmnd_Alias\fR, +\fIHost_alias\fR, +or +\fIUser_Alias\fR +may be specified as the \(lqcmnd\(rq, \(lqhost\(rq, or @@ -436,7 +440,7 @@ Per-user rules are merged and duplicates are removed. If a host name is specified with the input file, \fBcvtsudoers\fR will change rules that specify a host name of -\fRALL\fR +\fBALL\fR to the host name associated with the policy file being merged. The merging of rules is currently fairly simplistic but will be improved in a later release. @@ -522,6 +526,754 @@ command line option. .PP Options on the command line will override values from the configuration file. +.SS "JSON output format" +The +\fIsudoers\fR +JSON format may contain any of the following top-level objects: +.TP 6n +Defaults +An array of objects, each containing an +\fIOptions\fR +array and an optional +\fIBinding\fR +array. +.sp +The +\fIOptions\fR +array consists of one or more objects, each containing a +\(lqname:value\(rq +pair that corresponds to a +\fIsudoers\fR +\fIDefaults\fR +setting. +\fIOptions\fR +that operate on a list will also include an +\fIoperation\fR +entry in the object, with a value of +\(lqlist_assign\(rq +for +\(oq=\(cq, +\(lqlist_add\(rq +for +\(oq+=\(cq, +or +\(lqlist_remove\(rq +for +\(oq-=\(cq. +.sp +The optional +\fIBinding\fR +array consists of one or more objects, each containing a +\(lqname:value\(rq +pair and an optional +\fInegated\fR +entry, which will negate any comparison performed with the object. +If a +\fIBinding\fR +is present, the setting will only take effect if one of the specified +\fIcommand\fR, +\fIhostname\fR, +\fInetgroup\fR, +\fInetworkaddr\fR, +\fInonunixgid\fR, +\fInonunixgroup\fR, +\fIusergid\fR, +\fIusergroup\fR, +\fIuserid\fR, +\fIusername\fR, +or alias entries match. +.sp +For example, the following +\fIsudoers\fR +entry: +.nf +.sp +.RS 6n +Defaults@somehost set_home, env_keep += DISPLAY +.RE +.fi +.RS 6n +.sp +converts to: +.nf +.sp +.RS 6n +"Defaults": [ + { + "Binding": [ + { "hostname": "somehost" } + ], + "Options": [ + { "set_home": true }, + { + "operation": "list_add", + "env_keep": [ + "DISPLAY" + ] + } + ] + } +] +.RE +.fi +.RE +.TP 6n +User_Aliases +A JSON object containing one or more +\fIsudoers\fR +\fIUser_Alias\fR +entries where each named alias has as its value an array +containing one or more objects. +Each object contains a +\(lqname:value\(rq +pair and an optional +\fInegated\fR +entry, which will negate any comparison performed with the object. +The name may be one of +\fInetgroup\fR, +\fInonunixgid\fR, +\fInonunixgroup\fR, +\fIuseralias\fR, +\fIusergid\fR, +\fIusergroup\fR, +\fIuserid\fR, +or +\fIusername\fR. +.sp +For example, the following +\fIsudoers\fR +entry: +.nf +.sp +.RS 6n +User_Alias SYSADMIN = will, %wheel, +admin +.RE +.fi +.RS 6n +.sp +converts to: +.nf +.sp +.RS 6n +"User_Aliases": { + "SYSADMIN": [ + { "username": "will" }, + { "usergroup": "wheel" }, + { "netgroup": "admin" } + ] +} +.RE +.fi +.RE +.TP 6n +Runas_Aliases +A JSON object containing one or more +\fIsudoers\fR +\fIRunas_Alias\fR +entries, where each named alias has as its value an array +containing one or more objects. +Each object contains a +\(lqname:value\(rq +pair and an optional +\fInegated\fR +entry, which will negate any comparison performed with the object. +The name may be one of +\fInetgroup\fR, +\fInonunixgid\fR, +\fInonunixgroup\fR, +\fIrunasalias\fR, +\fIusergid\fR, +\fIusergroup\fR, +\fIuserid\fR, +or +\fIusername\fR. +.sp +For example, the following +\fIsudoers\fR +entry: +.nf +.sp +.RS 6n +Runas_Alias DB = oracle, sybase : OP = root, operator +.RE +.fi +.RS 6n +.sp +converts to: +.nf +.sp +.RS 6n +"Runas_Aliases": { + "DB": [ + { "username": "oracle" }, + { "username": "sybase" } + ], + "OP": [ + { "username": "root" }, + { "username": "operator" } + ] +} +.RE +.fi +.RE +.TP 6n +Host_Aliases +A JSON object containing one or more +\fIsudoers\fR +\fIHost_Alias\fR +entries where each named alias has as its value an array +containing one or more objects. +Each object contains a +\(lqname:value\(rq +pair and an optional +\fInegated\fR +entry, which will negate any comparison performed with the object. +The name may be one of +\fIhostalias\fR, +\fIhostname\fR, +\fInetgroup\fR, +or +\fInetworkaddr\fR. +.sp +For example, the following +\fIsudoers\fR +entries: +.nf +.sp +.RS 6n +Host_Alias DORMNET = 128.138.243.0, 128.138.204.0/24 +Host_Alias SERVERS = boulder, refuge +.RE +.fi +.RS 6n +.sp +convert to: +.nf +.sp +.RS 6n +"Host_Aliases": { + "DORMNET": [ + { "networkaddr": "128.138.243.0" }, + { "networkaddr": "128.138.204.0/24" } + ], + "SERVERS": [ + { "hostname": "boulder" }, + { "hostname": "refuge" } + ] +} +.RE +.fi +.RE +.TP 6n +Cmnd_Aliases +A JSON object containing one or more +\fIsudoers\fR +\fICmnd_Alias\fR +entries where each named alias has as its value an array +containing one or more objects. +Each object contains a +\(lqname:value\(rq +pair and an optional +\fInegated\fR +entry, which will negate any comparison performed with the object. +The name may be either another +\fIcmndalias\fR +or a +\fIcommand\fR. +For example, the following +\fIsudoers\fR +entries: +.nf +.sp +.RS 6n +Cmnd_Alias SHELLS = /bin/bash, /bin/csh, /bin/sh, /bin/zsh +Cmnd_Alias VIPW = /usr/bin/chpass, /usr/bin/chfn, /usr/bin/chsh, \e + /usr/bin/passwd, /usr/sbin/vigr, /usr/sbin/vipw +.RE +.fi +.RS 6n +.sp +convert to: +.nf +.sp +.RS 6n +"Cmnd_Aliases": { + "SHELLS": [ + { "command": "/bin/bash" }, + { "command": "/bin/csh" }, + { "command": "/bin/sh" }, + { "command": "/bin/zsh" } + ], + "VIPW": [ + { "command": "/usr/bin/chpass" }, + { "command": "/usr/bin/chfn" }, + { "command": "/usr/bin/chsh" }, + { "command": "/usr/bin/passwd" }, + { "command": "/usr/sbin/vigr" }, + { "command": "/usr/sbin/vipw" } + ] +} +.RE +.fi +.RE +.TP 6n +User_Specs +A JSON array containing one or more objects, each representing a +\fIsudoers\fR +User_Spec. +Each object in the +\fIUser_Specs\fR +array should contain a +\fIUser_List\fR +array, a +\fIHost_List\fR +array and a +\fICmnd_Specs\fR +array. +.sp +A +\fIUser_List\fR +consists of one or more objects. +Each object contains a +\(lqname:value\(rq +pair and an optional +\fInegated\fR +entry, which will negate any comparison performed with the object. +The name may be one of +\fInetgroup\fR, +\fInonunixgid\fR, +\fInonunixgroup\fR, +\fIuseralias\fR, +\fIusergid\fR, +\fIusergroup\fR, +\fIuserid\fR, +or +\fIusername\fR. +If +\fIusername\fR +is set to the special value +\fBALL\fR, +it will match any user. +.sp +A +\fIHost_List\fR +consists of one or more objects. +Each object contains a +\(lqname:value\(rq +pair and an optional +\fInegated\fR +entry, which will negate any comparison performed with the object. +The name may be one of +\fIhostalias\fR, +\fIhostname\fR, +\fInetgroup\fR, +or +\fInetworkaddr\fR. +If +\fIhostname\fR +is set to the special value +\fBALL\fR, +it will match any host. +.sp +The +\fICmnd_Specs\fR +array consists of one or more JSON objects describing a command that +may be run. +Each +\fICmnd_Specs\fR +is made up of a +\fICommands\fR +array, an optional +\fIrunasusers\fR +array, an optional +\fIrunasgroups\fR +array, and an optional +\fIOptions array.\fR +.sp +The +\fICommands\fR +array consists of one or more objects containing +\(lqname:value\(rq +pair elements. +The following names and values are supported: +.PP +.RS 6n +.PD 0 +.TP 10n +command +A string containing the command to run. +The special value +\fBALL\fR +it will match any command. +.PD +.TP 10n +negated +A boolean value that, if true, will negate any comparison performed +with the object. +.TP 10n +sha224 +A string containing the SHA224 digest of the +\fIcommand\fR. +.TP 10n +sha256 +A string containing the SHA256 digest of the +\fIcommand\fR. +.TP 10n +sha384 +A string containing the SHA384 digest of the +\fIcommand\fR. +.TP 10n +sha512 +A string containing the SHA512 digest of the +\fIcommand\fR. +.PP +The +\fIrunasusers\fR +array consists of objects describing users the command may be run as. +Each object contains a +\(lqname:value\(rq +pair and an optional +\fInegated\fR +entry, which will negate any comparison performed with the object. +The name may be one of +\fInetgroup\fR, +\fInonunixgid\fR, +\fInonunixgroup\fR, +\fIrunasalias\fR, +\fIusergid\fR, +\fIusergroup\fR, +\fIuserid\fR, +or +\fIusername\fR. +If +\fIusername\fR +is set to the special value +\fBALL\fR, +it will match any user. +If +\fIusername\fR +is set to the empty string +\(lq\(rq, +it will match the invoking user. +.sp +The +\fIrunasgroups\fR +array consists of objects describing groups the command may be run as. +Each object contains a +\(lqname:value\(rq +pair and an optional +\fInegated\fR +entry, which will negate any comparison performed with the object. +The name may be one of +\fIrunasalias\fR, +\fIusergid\fR, +or +\fIusergroup\fR. +If +\fIusergroup\fR +is set to the special value +\fBALL\fR, +it will match any group. +.sp +The +\fIOptions\fR +array is of the same format as the one in the +\fIDefaults\fR +object. +Any +\fITag_Spec\fR +entries in +\fIsudoers\fR +are converted to +\fIOptions\fR. +A user with +\(lqsudo ALL\(rq +privileges will automatically have the +\fIsetenv\fR +option enabled to match the implicit behavior provided by +\fIsudoers\fR. +.sp +For example, the following +\fIsudoers\fR +entry: +.nf +.sp +.RS 6n +millert ALL = (ALL : ALL) NOPASSWD: ALL, !/usr/bin/id +.RE +.fi +.sp +converts to: +.nf +.sp +.RS 6n +"User_Specs": [ + { + "User_List": [ + { "username": "millert" } + ], + "Host_List": [ + { "hostname": "ALL" } + ], + "Cmnd_Specs": [ + { + "runasusers": [ + { "username": "ALL" } + ], + "runasgroups": [ + { "usergroup": "ALL" } + ], + "Options": [ + { "authenticate": false }, + { "setenv": true } + ], + "Commands": [ + { "command": "ALL" }, + { + "command": "/usr/bin/id", + "negated": true + } + ] + } + ] + } +] +.RE +.fi +.RE +.SS "CSV output format" +CSV (comma-separated value) files are often used by spreadsheets +and report generators. +For CSV output, +\fBcvtsudoers\fR +double quotes strings that contain commas. +For each literal double quote character present inside the string, +two double quotes are output. +This method of quoting commas is compatible with most spreadsheet programs. +.PP +There are three possible sections in +\fBcvtsudoers\fR's +CSV output, each separated by a blank line: +.TP 6n +defaults +This section includes any +\fIDefaults\fR +settings in +\fIsudoers\fR. +The +\fIdefaults\fR +section begins with the following heading: +.nf +.sp +.RS 12n +defaults_type,binding,name,operator,value +.RE +.fi +.RS 6n +.sp +The fields are as follows: +.TP 10n +defaults_type +The type of +\fIDefaults\fR +setting; one of +\fIdefaults\fR, +\fIdefaults_command\fR, +\fIdefaults_host\fR, +\fIdefaults_runas\fR, +or +\fIdefaults_user\fR. +.TP 10n +binding +For +\fIdefaults_command\fR, +\fIdefaults_host\fR, +\fIdefaults_runas\fR, +and +\fIdefaults_user\fR +this is the value that must match for the setting to be applied. +.TP 10n +name +The name of the +\fIDefaults\fR +setting. +.TP 10n +operator +The operator determines how the value is applied to the setting. +It may be either +\(oq=\(cq +(assignment), +\(oq+=\(cq +(append), +or +\(oq-=\(cq +(remove). +.TP 10n +value +The setting's value, usually a string or, for +settings used in a boolean context, +\fItrue\fR +or +\fIfalse\fR. +.PD 0 +.PP +.RE +.PD +.TP 6n +aliases +This section includes any +\fICmnd_Alias\fR +\fIHost_Alias\fR, +\fIRunas_Alias\fR, +or +\fIUser_Alias\fR, +entries from +\fIsudoers\fR. +The +\fIaliases\fR +section begins with the following heading: +.nf +.sp +.RS 12n +alias_type,alias_name,members +.RE +.fi +.RS 6n +.sp +The fields are as follows: +.TP 10n +alias_type +The type of alias; one of +\fICmnd_Alias\fR, +\fIHost_Alias\fR, +\fIRunas_Alias\fR, +or +\fIUser_Alias\fR. +.TP 10n +alias_name +The name of the alias; a string starting with an upper-case letter that +consists of upper-case letters, digits, or underscores. +.TP 10n +members +A comma-separated list of members belonging to the alias. +Due to the use of commas, +\fImembers\fR +is surrounded by double quotes if it contains more than one member. +.PD 0 +.PP +.RE +.PD +.TP 6n +rules +.br +This section includes the +\fIsudoers\fR +rules that grant privileges. +The +\fIrules\fR +section begins with the following heading: +.nf +.sp +.RS 12n +rule,user,host,runusers,rungroups,options,command +.RE +.fi +.RS 6n +.sp +The fields are as follows: +.TP 10n +rule +This field indicates a +\fIsudoers\fR +\fIrule\fR +entry. +.TP 10n +user +The user the rule applies to. +This may also be a Unix group (preceded by a +\(oq%\(cq +character), a non-Unix group (preceded by +\(oq%:\(cq) +or a netgroup (preceded by a +\(oq+\(cq +character) +or a +\fIUser_Alias\fR. +If set to the special value +\fBALL\fR, +it will match any user. +.TP 10n +host +The host the rule applies to. +This may also be a netgroup (preceded by a +\(oq+\(cq +character) +or a +\fIHost_Alias\fR. +If set to the special value +\fBALL\fR, +it will match any host. +.TP 10n +runusers +An optional comma-separated list of users (or +\fIRunas_Alias\fRes) +the command may be run as. +If it contains more than one member, the value is surrounded by +double quotes. +If set to the special value +\fBALL\fR, +it will match any user. +If empty, the root user is assumed. +.TP 10n +rungroups +.br +An optional comma-separated list of groups (or +\fIRunas_Alias\fRes) +the command may be run as. +If it contains more than one member, the value is surrounded by +double quotes. +If set to the special value +\fBALL\fR, +it will match any group. +If empty, the +\fIrunuser\fR's +group is used. +.TP 10n +options +An optional list of +\fIDefaults\fR +settings to apply to the command. +Any +\fITag_Spec\fR +entries in +\fIsudoers\fR +are converted to +\fIoptions\fR. +.TP 10n +commands +A list of commands, with optional arguments, that the user is allowed to run. +If set to the special value +\fBALL\fR, +it will match any command. +.PP +For example, the following +\fIsudoers\fR +entry: +.nf +.sp +.RS 6n +millert ALL = (ALL : ALL) NOPASSWD: ALL, !/usr/bin/id +.RE +.fi +.sp +converts to: +.nf +.sp +.RS 6n +rule,millert,ALL,ALL,ALL,"!authenticate","ALL,!/usr/bin/id" +.RE +.fi +.RE .SH "FILES" .TP 26n \fI@sysconfdir@/cvtsudoers.conf\fR |