diff options
Diffstat (limited to 'docs/cvtsudoers.mdoc.in')
| -rw-r--r-- | docs/cvtsudoers.mdoc.in | 688 |
1 files changed, 671 insertions, 17 deletions
diff --git a/docs/cvtsudoers.mdoc.in b/docs/cvtsudoers.mdoc.in index 7aa06868f..6d73a0987 100644 --- a/docs/cvtsudoers.mdoc.in +++ b/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 February 16, 2022 +.Dd September 29, 2022 .Dt CVTSUDOERS 1 .Os Sudo @PACKAGE_VERSION@ .Sh NAME @@ -65,9 +65,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 -.Li ou=SUDOers,dc=my-domain,dc=com -for the domain -.Li my-domain.com . +.Dq ou=SUDOers,dc=my-domain,dc=com +for the domain my-domain.com. If this option is not specified, the value of the .Ev SUDOERS_BASE environment variable will be used instead. @@ -78,10 +77,10 @@ Defaults to .Pa @sysconfdir@/cvtsudoers.conf . .It Fl d Ar deftypes , Fl -defaults Ns = Ns Ar deftypes Only convert -.Li Defaults +.Em Defaults entries of the specified types. One or more -.Li Defaults +.Em Defaults types may be specified, separated by a comma .Pq Ql \&, . The supported types are: @@ -110,7 +109,7 @@ for more information. If the .Fl d option is not specified, all -.Li Defaults +.Em Defaults entries will be converted. .It Fl e , Fl -expand-aliases Expand aliases in @@ -125,12 +124,9 @@ The following formats are supported: .It CSV 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. +See +.Sx CSV output format +for more details. .It JSON JSON (JavaScript Object Notation) files are usually easier for third-party applications to consume than the traditional @@ -140,6 +136,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 +216,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 +.Em Cmnd_Alias , +.Em Host_alias , +or +.Em User_Alias +may be specified as the .Dq cmnd , .Dq host , or @@ -360,9 +364,9 @@ subsequent aliases of the same name are renamed with a numeric suffix separated with a underscore .Pq Ql _ . For example, if there are two different aliases named -.Li SERVERS , +.Dv SERVERS , the first will be left as-is and the second will be renamed -.Li SERVERS_1 . +.Dv SERVERS_1 . References to the renamed alias are also updated in the policy file. Duplicate aliases (those with identical contents) are pruned. .It @@ -379,7 +383,7 @@ Per-user rules are merged and duplicates are removed. If a host name is specified with the input file, .Nm will change rules that specify a host name of -.Li ALL +.Sy ALL 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. @@ -454,6 +458,656 @@ command line option. .Pp Options on the command line will override values from the configuration file. +.Ss JSON output format +The +.Em sudoers +JSON format may contain any of the following top-level objects: +.Bl -tag -width 4n +.It Defaults +An array of objects, each containing an +.Em Options +array and an optional +.Em Binding +array. +.Pp +The +.Em Options +array consists of one or more objects, each containing a +.Dq name:value +pair that corresponds to a +.Em sudoers +.Em Defaults +setting. +.Em Options +that operate on a list will also include an +.Em operation +entry in the object, with a value of +.Dq list_assign +for +.Ql = , +.Dq list_add +for +.Ql += , +or +.Dq list_remove +for +.Ql -= . +.Pp +The optional +.Em Binding +array consists of one or more objects, each containing a +.Dq name:value +pair and an optional +.Em negated +entry, which will negate any comparison performed with the object. +If a +.Em Binding +is present, the setting will only take effect if one of the specified +.Em command , +.Em hostname , +.Em netgroup , +.Em networkaddr , +.Em nonunixgid , +.Em nonunixgroup , +.Em usergid , +.Em usergroup , +.Em userid , +.Em username , +or alias entries match. +.Pp +For example, the following +.Em sudoers +entry: +.Bd -literal +Defaults@somehost set_home, env_keep += DISPLAY +.Ed +.Pp +converts to: +.Bd -literal +"Defaults": [ + { + "Binding": [ + { "hostname": "somehost" } + ], + "Options": [ + { "set_home": true }, + { + "operation": "list_add", + "env_keep": [ + "DISPLAY" + ] + } + ] + } +] +.Ed +.It User_Aliases +A JSON object containing one or more +.Em sudoers +.Em User_Alias +entries where each named alias has as its value an array +containing one or more objects. +Each object contains a +.Dq name:value +pair and an optional +.Em negated +entry, which will negate any comparison performed with the object. +The name may be one of +.Em netgroup , +.Em nonunixgid , +.Em nonunixgroup , +.Em useralias , +.Em usergid , +.Em usergroup , +.Em userid , +or +.Em username . +.Pp +For example, the following +.Em sudoers +entry: +.Bd -literal +User_Alias SYSADMIN = will, %wheel, +admin +.Ed +.Pp +converts to: +.Bd -literal +"User_Aliases": { + "SYSADMIN": [ + { "username": "will" }, + { "usergroup": "wheel" }, + { "netgroup": "admin" } + ] +} +.Ed +.It Runas_Aliases +A JSON object containing one or more +.Em sudoers +.Em 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 +pair and an optional +.Em negated +entry, which will negate any comparison performed with the object. +The name may be one of +.Em netgroup , +.Em nonunixgid , +.Em nonunixgroup , +.Em runasalias , +.Em usergid , +.Em usergroup , +.Em userid , +or +.Em username . +.Pp +For example, the following +.Em sudoers +entry: +.Bd -literal +Runas_Alias DB = oracle, sybase : OP = root, operator +.Ed +.Pp +converts to: +.Bd -literal +"Runas_Aliases": { + "DB": [ + { "username": "oracle" }, + { "username": "sybase" } + ], + "OP": [ + { "username": "root" }, + { "username": "operator" } + ] +} +.Ed +.It Host_Aliases +A JSON object containing one or more +.Em sudoers +.Em 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 +pair and an optional +.Em negated +entry, which will negate any comparison performed with the object. +The name may be one of +.Em hostalias , +.Em hostname , +.Em netgroup , +or +.Em networkaddr . +.Pp +For example, the following +.Em sudoers +entries: +.Bd -literal +Host_Alias DORMNET = 128.138.243.0, 128.138.204.0/24 +Host_Alias SERVERS = boulder, refuge +.Ed +.Pp +convert to: +.Bd -literal +"Host_Aliases": { + "DORMNET": [ + { "networkaddr": "128.138.243.0" }, + { "networkaddr": "128.138.204.0/24" } + ], + "SERVERS": [ + { "hostname": "boulder" }, + { "hostname": "refuge" } + ] +} +.Ed +.It Cmnd_Aliases +A JSON object containing one or more +.Em sudoers +.Em 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 +pair and an optional +.Em negated +entry, which will negate any comparison performed with the object. +The name may be either another +.Em cmndalias +or a +.Em command . +For example, the following +.Em sudoers +entries: +.Bd -literal +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 +.Ed +.Pp +convert to: +.Bd -literal +"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" } + ] +} +.Ed +.It User_Specs +A JSON array containing one or more objects, each representing a +.Em sudoers +User_Spec. +Each object in the +.Em User_Specs +array should contain a +.Em User_List +array, a +.Em Host_List +array and a +.Em Cmnd_Specs +array. +.Pp +A +.Em User_List +consists of one or more objects. +Each object contains a +.Dq name:value +pair and an optional +.Em negated +entry, which will negate any comparison performed with the object. +The name may be one of +.Em netgroup , +.Em nonunixgid , +.Em nonunixgroup , +.Em useralias , +.Em usergid , +.Em usergroup , +.Em userid , +or +.Em username . +If +.Em username +is set to the special value +.Sy ALL , +it will match any user. +.Pp +A +.Em Host_List +consists of one or more objects. +Each object contains a +.Dq name:value +pair and an optional +.Em negated +entry, which will negate any comparison performed with the object. +The name may be one of +.Em hostalias , +.Em hostname , +.Em netgroup , +or +.Em networkaddr . +If +.Em hostname +is set to the special value +.Sy ALL , +it will match any host. +.Pp +The +.Em Cmnd_Specs +array consists of one or more JSON objects describing a command that +may be run. +Each +.Em Cmnd_Specs +is made up of a +.Em Commands +array, an optional +.Em runasusers +array, an optional +.Em runasgroups +array, and an optional +.Em Options array. +.Pp +The +.Em Commands +array consists of one or more objects containing +.Dq name:value +pair elements. +The following names and values are supported: +.Bl -tag -width 8n +.It command +A string containing the command to run. +The special value +.Sy ALL +it will match any command. +.It negated +A boolean value that, if true, will negate any comparison performed +with the object. +.It sha224 +A string containing the SHA224 digest of the +.Em command . +.It sha256 +A string containing the SHA256 digest of the +.Em command . +.It sha384 +A string containing the SHA384 digest of the +.Em command . +.It sha512 +A string containing the SHA512 digest of the +.Em command . +.El +.Pp +The +.Em runasusers +array consists of objects describing users the command may be run as. +Each object contains a +.Dq name:value +pair and an optional +.Em negated +entry, which will negate any comparison performed with the object. +The name may be one of +.Em netgroup , +.Em nonunixgid , +.Em nonunixgroup , +.Em runasalias , +.Em usergid , +.Em usergroup , +.Em userid , +or +.Em username . +If +.Em username +is set to the special value +.Sy ALL , +it will match any user. +If +.Em username +is set to the empty string +.Dq "" , +it will match the invoking user. +.Pp +The +.Em runasgroups +array consists of objects describing groups the command may be run as. +Each object contains a +.Dq name:value +pair and an optional +.Em negated +entry, which will negate any comparison performed with the object. +The name may be one of +.Em runasalias , +.Em usergid , +or +.Em usergroup . +If +.Em usergroup +is set to the special value +.Sy ALL , +it will match any group. +.Pp +The +.Em Options +array is of the same format as the one in the +.Em Defaults +object. +Any +.Em Tag_Spec +entries in +.Em sudoers +are converted to +.Em Options . +A user with +.Dq sudo ALL +privileges will automatically have the +.Em setenv +option enabled to match the implicit behavior provided by +.Em sudoers . +.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 +"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 + } + ] + } + ] + } +] +.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 +.Em defaults , +.Em defaults_command , +.Em defaults_host , +.Em defaults_runas , +or +.Em defaults_user . +.It binding +For +.Em defaults_command , +.Em defaults_host , +.Em defaults_runas , +and +.Em 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 +.Ql = +(assignment), +.Ql += +(append), +or +.Ql -= +(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 +.Em Cmnd_Alias +.Em Host_Alias , +.Em Runas_Alias , +or +.Em 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 +.Em Cmnd_Alias , +.Em Host_Alias , +.Em Runas_Alias , +or +.Em 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 +.Em 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 +.Em 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 +.Em 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 +.Em 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 +.El .Sh FILES .Bl -tag -width 24n .It Pa @sysconfdir@/cvtsudoers.conf |