Document cvtsudoers CSV output format

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" "August 31, 2022" "Sudo @PACKAGE_VERSION@" "General Commands Manual"
+.TH "CVTSUDOERS" "1" "September 2, 2022" "Sudo @PACKAGE_VERSION@" "General Commands Manual"
 .nh
 .if n .ad l
 .SH "NAME"
@@ -143,12 +143,9 @@ The following formats are supported:
 CSV
 CSV (comma-separated value) files are often used by spreadsheets
 and report generators.
-For CSV output,
+See
-\fBcvtsudoers\fR
+\fICSV output format\fR
-double quotes strings that contain commas.
+for more details.
-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.
 .PD
 .TP 10n
 JSON
@@ -160,6 +157,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 +264,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
+\fRCmnd_Alias\fR,
+\fRHost_alias\fR,
+or
+\fRUser_Alias\fR
+may be specified as the
 \(lqcmnd\(rq,
 \(lqhost\(rq,
 or
@@ -622,7 +627,9 @@ and the netgroup
 Runas_Aliases
 A JSON object containing one or more
 \fIsudoers\fR
-Runas_Alias entries, where each named alias has as its value an array
+.TP 6n
+Runas_Alias
+entries, where each named alias has as its value an array
 containing one or more objects.
 Each object contains a
 \(lqname:value\(rq
@@ -669,7 +676,8 @@ and
 Host_Aliases
 A JSON object containing one or more
 \fIsudoers\fR
-Host_Alias entries where each named alias has as its value an array
+\fRHost_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
@@ -703,7 +711,8 @@ For example:
 Cmnd_Aliases
 A JSON object containing one or more
 \fIsudoers\fR
-Cmnd_Alias entries where each named alias has as its value an array
+\fRCmnd_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
@@ -961,6 +970,239 @@ converts to:
 .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
+\fRdefaults\fR,
+\fRdefaults_command\fR,
+\fRdefaults_host\fR,
+\fRdefaults_runas\fR,
+or
+\fRdefaults_user\fR.
+.TP 10n
+binding
+For
+\fRdefaults_command\fR,
+\fRdefaults_host\fR,
+\fRdefaults_runas\fR,
+and
+\fRdefaults_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
+\(lq=\(rq
+(assignment),
+\(lq+=\(rq
+(append),
+or
+\(lq-=\(rq
+(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
+\fRCmnd_Alias\fR
+\fRHost_Alias\fR,
+\fRRunas_Alias\fR,
+or
+\fRUser_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
+\fRCmnd_Alias\fR,
+\fRHost_Alias\fR,
+\fRRunas_Alias\fR,
+or
+\fRUser_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
+\fRUser_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
+\fRHost_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
+\fRRunas_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
+\fRRunas_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

docs/cvtsudoers.mdoc.in

@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd August 31, 2022
+.Dd September 2, 2022
 .Dt CVTSUDOERS 1
 .Os Sudo @PACKAGE_VERSION@
 .Sh NAME
@@ -125,12 +125,9 @@ The following formats are supported:
 .It CSV
 CSV (comma-separated value) files are often used by spreadsheets
 and report generators.
-For CSV output,
+See
-.Nm
+.Sx CSV output format
-double quotes strings that contain commas.
+for more details.
-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.
 .It JSON
 JSON (JavaScript Object Notation) files are usually easier for
 third-party applications to consume than the traditional
@@ -140,6 +137,9 @@ The various values have explicit types which removes much of the
 ambiguity of the
 .Em sudoers
 format.
+See
+.Sx JSON output format
+for more details.
 .It LDIF
 LDIF (LDAP Data Interchange Format) files can be imported into an LDAP
 server for use with
@@ -217,7 +217,12 @@ For example,
 .Sy user No = Ar operator
 or
 .Sy host No = Ar www .
-An upper-case Cmnd_Alias, Host_alias, or Host_Alias may be specified as the
+An upper-case
+.Li Cmnd_Alias ,
+.Li Host_alias ,
+or
+.Li User_Alias
+may be specified as the
 .Dq cmnd ,
 .Dq host ,
 or
@@ -542,7 +547,8 @@ and the netgroup
 .It Runas_Aliases
 A JSON object containing one or more
 .Em sudoers
-Runas_Alias entries, where each named alias has as its value an array
+.It Runas_Alias
+entries, where each named alias has as its value an array
 containing one or more objects.
 Each object contains a
 .Dq name:value
@@ -583,7 +589,8 @@ and
 .It Host_Aliases
 A JSON object containing one or more
 .Em sudoers
-Host_Alias entries where each named alias has as its value an array
+.Li Host_Alias
+entries where each named alias has as its value an array
 containing one or more objects.
 Each object contains a
 .Dq name:value
@@ -613,7 +620,8 @@ For example:
 .It Cmnd_Aliases
 A JSON object containing one or more
 .Em sudoers
-Cmnd_Alias entries where each named alias has as its value an array
+.Li Cmnd_Alias
+entries where each named alias has as its value an array
 containing one or more objects.
 Each object contains a
 .Dq name:value
@@ -853,6 +861,200 @@ converts to:
 ]
 .Ed
 .El
+.Ss CSV output format
+CSV (comma-separated value) files are often used by spreadsheets
+and report generators.
+For CSV output,
+.Nm
+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
+.Nm cvtsudoers Ns 's
+CSV output, each separated by a blank line:
+.Bl -tag -width 4n
+.It defaults
+This section includes any
+.Em Defaults
+settings in
+.Em sudoers .
+The
+.Em defaults
+section begins with the following heading:
+.Bd -literal -offset indent
+defaults_type,binding,name,operator,value
+.Ed
+.Pp
+The fields are as follows:
+.Bl -tag -width 8n
+.It defaults_type
+The type of
+.Em Defaults
+setting; one of
+.Li defaults ,
+.Li defaults_command ,
+.Li defaults_host ,
+.Li defaults_runas ,
+or
+.Li defaults_user .
+.It binding
+For
+.Li defaults_command ,
+.Li defaults_host ,
+.Li defaults_runas ,
+and
+.Li defaults_user
+this is the value that must match for the setting to be applied.
+.It name
+The name of the
+.Em Defaults
+setting.
+.It operator
+The operator determines how the value is applied to the setting.
+It may be either
+.Dq =
+(assignment),
+.Dq +=
+(append),
+or
+.Dq -=
+(remove).
+.It value
+The setting's value, usually a string or, for
+settings used in a boolean context,
+.Em true
+or
+.Em false .
+.El
+.It aliases
+This section includes any
+.Li Cmnd_Alias
+.Li Host_Alias ,
+.Li Runas_Alias ,
+or
+.Li User_Alias ,
+entries from
+.Em sudoers .
+The
+.Em aliases
+section begins with the following heading:
+.Bd -literal -offset indent
+alias_type,alias_name,members
+.Ed
+.Pp
+The fields are as follows:
+.Bl -tag -width 8n
+.It alias_type
+The type of alias; one of
+.Li Cmnd_Alias ,
+.Li Host_Alias ,
+.Li Runas_Alias ,
+or
+.Li User_Alias .
+.It alias_name
+The name of the alias; a string starting with an upper-case letter that
+consists of upper-case letters, digits, or underscores.
+.It members
+A comma-separated list of members belonging to the alias.
+Due to the use of commas,
+.Em members
+is surrounded by double quotes if it contains more than one member.
+.El
+.It rules
+This section includes the
+.Em sudoers
+rules that grant privileges.
+The
+.Em rules
+section begins with the following heading:
+.Bd -literal -offset indent
+rule,user,host,runusers,rungroups,options,command
+.Ed
+.Pp
+The fields are as follows:
+.Bl -tag -width 8n
+.It rule
+This field indicates a
+.Em sudoers
+.Em rule
+entry.
+.It user
+The user the rule applies to.
+This may also be a Unix group (preceded by a
+.Ql %
+character), a non-Unix group (preceded by
+.Ql %: )
+or a netgroup (preceded by a
+.Ql +
+character)
+or a
+.Li User_Alias .
+If set to the special value
+.Sy ALL ,
+it will match any user.
+.It host
+The host the rule applies to.
+This may also be a netgroup (preceded by a
+.Ql +
+character)
+or a
+.Li Host_Alias .
+If set to the special value
+.Sy ALL ,
+it will match any host.
+.It runusers
+An optional comma-separated list of users (or
+.Li Runas_Alias Ns No es )
+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
+.Sy ALL ,
+it will match any user.
+If empty, the root user is assumed.
+.It rungroups
+An optional comma-separated list of groups (or
+.Li Runas_Alias Ns No es )
+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
+.Sy ALL ,
+it will match any group.
+If empty, the
+.Em runuser Ns 's
+group is used.
+.It options
+An optional list of
+.Em Defaults
+settings to apply to the command.
+Any
+.Em Tag_Spec
+entries in
+.Em sudoers
+are converted to
+.Em options .
+.It commands
+A list of commands, with optional arguments, that the user is allowed to run.
+If set to the special value
+.Sy ALL ,
+it will match any command.
+.El
+.Pp
+For example, the following
+.Em sudoers
+entry:
+.Bd -literal
+millert ALL = (ALL : ALL) NOPASSWD: ALL, !/usr/bin/id
+.Ed
+.Pp
+converts to:
+.Bd -literal
+rule,millert,ALL,ALL,ALL,"!authenticate","ALL,!/usr/bin/id"
+.Ed -literal
+.El
 .Sh FILES
 .Bl -tag -width 24n
 .It Pa @sysconfdir@/cvtsudoers.conf