CVTSUDOERS(1)

📦 version 1.9.17p2, in ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so this is the manual page for cvtsudoers, and its whole job is to convert between sudoers file formats 🦋

✨ SYNOPSIS ✨

cvtsudoers [-ehMpV] [-b dn] [-c conf_file] [-d deftypes]
           [-f output_format] [-i input_format] [-I increment]
           [-l log_file] [-m filter] [-o output_file] [-O start_point]
           [-P padding] [-s sections] [input_file ...]

🌸 DESCRIPTION 🌸

bestie, cvtsudoers takes one or more security policies as input, either in sudoers or LDIF format, and spits out a single policy in whatever format you ask for 💅 The default input is sudoers and the default output is LDIF. It only works on a policy file that is syntactically correct, so clean up your act first 🙈

If you don't give it an input_file, or you give it -, it reads the policy from standard input. You can also prefix input files with a host name and a colon (:) to make the rules specific to that host when you merge a bunch of files together ✨ By default the result goes to standard output.

Here are the options 🎀

  • -b dn, --base=dn — this is the base DN (distinguished name) used for LDAP queries. It usually looks like “ou=SUDOers,dc=my-domain,dc=com” for the domain my-domain.com 🧚 If you skip this flag, it grabs the SUDOERS_BASE environment variable instead. It only matters when you're converting to LDIF.
  • -c conf_file, --config=conf_file — point it at a configuration file. If you don't, it defaults to /etc/cvtsudoers.conf 💜
  • -d deftypes, --defaults=deftypes — only convert the Defaults entries of the types you name. You can list more than one, separated by a comma (,). The types are:
    • all — every Defaults entry, no exceptions 👑
    • global — global Defaults entries that get applied no matter the user, runas, host, or command 🌈
    • user — per-user Defaults entries 🍓
    • runas — per-runas user Defaults entries 🦋
    • host — per-host Defaults entries ✨
    • command — per-command Defaults entries 💅

For more on this, check the Defaults section in sudoers(5). And if you don't use -d at all, every Defaults entry gets converted 💖

  • -e, --expand-aliases — expands the aliases in input_file. Fyi, aliases are kept as they are by default when the output format is JSON or sudoers 🫶
  • -f output_format, --output-format=output_format — pick your output format. It's not picky about capitals 💅 The formats you can choose from are:
    • CSV — CSV (comma-separated value) files are the spreadsheet and report generator favourite 📊 Check out “CSV output format” for the deets.
    • JSON — JSON (JavaScript Object Notation) files are usually way easier for third-party apps to read than the old-school sudoers format. The values have explicit types, so there's way less guessing going on than with sudoers 🧠 See “JSON output format” for more.
    • LDIF — LDIF (LDAP Data Interchange Format) files can be imported into an LDAP server and used with sudoers.ldap(5) 🌸
⚠️ heads up, converting to LDIF has some limitations, babe: - Command, host, runas, and user-specific Defaults lines can't be translated, because the sudoers LDAP schema doesn't have an equivalent for them 💀 - Command, host, runas, and user aliases aren't supported by the sudoers LDAP schema, so they get expanded during the conversion 🙈
  • sudoers — the traditional sudoers format 📜 A brand new sudoers file gets rebuilt from the parsed input. Comments are NOT preserved, and any data from include files gets output inline.
  • --group-file=file — when -M is also specified, group queries use file instead of the system group database 🫧
  • -h, --help — shows a short help message on standard output and then exits 🎀

Okay so picking up where we left off, bestie 💅 Per-user rules get merged and duplicates get yeeted 🗑️✨

  • Per-user rules are merged and duplicates are removed. If a host name is specified with the input file, cvtsudoers will change rules that specify a host name of 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. 🌸

It's also possible to merge policy files with differing formats. Mix and match, no cap 🦋

✨ The cvtsudoers.conf file ✨

Okay so you can ALSO set options in the form keyword = value inside a config file. By default that's /etc/cvtsudoers.conf 📄💖 These are the keywords it recognizes, so let's go:

  • defaults = deftypes — same as the -d command line option 🎀
  • expand_aliases = yes | no — same as the -e command line option ✨
  • group_file = file — same as the --group-file command line option 👥
  • input_format = ldif | sudoers — same as the -i command line option 📥
  • match = filter — same as the -m command line option 🔍
  • match_local = yes | no — same as the -M command line option 🏠
  • order_increment = increment — same as the -I command line option 🔢
  • order_start = start_point — same as the -O command line option 🚀
  • output_format = csv | json | ldif | sudoers — same as the -f command line option 📤
  • padding = padding — same as the -P command line option 🧸
  • passwd_file = file — same as the --passwd-file command line option 🗂️
  • prune_matches = yes | no — same as the -p command line option ✂️
  • sudoers_base = dn — same as the -b command line option 🌳
  • suppress = sections — same as the -s command line option 🙈
Heads up: options on the command line will override values from the configuration file. The command line always wins, periodt 👑

✨ JSON output format ✨

Okay the sudoers JSON format can contain any of the following top-level objects, and each one is its own little vibe 🧚

Defaults

An array of objects, each containing an Options array and an optional Binding array. 💅

The Options array is made of one or more objects, each holding a “name:value” pair that matches a sudoers Defaults setting. Options that work on a list also get an operation entry, with a value of “list_assign” for =, “list_add” for +=, or “list_remove” for -=. 📝

The optional Binding array is one or more objects, each with a “name:value” pair and an optional negated entry. That negated entry negates any comparison done with the object. If a Binding is there, the setting only takes effect if one of these matches: command, hostname, netgroup, networkaddr, nonunixgid, nonunixgroup, usergid, usergroup, userid, username, or alias 🔐

Here's an example, because examples make everything click ✨ This sudoers entry:

Defaults@somehost set_home, env_keep += DISPLAY

converts to:

"Defaults": [
    {
        "Binding": [
            { "hostname": "somehost" }
        ],
        "Options": [
            { "set_home": true },
            {
                "operation": "list_add",
                "env_keep": [
                    "DISPLAY"
                ]
            }
        ]
    }
]

User_Aliases

A JSON object with one or more sudoers User_Alias entries. Each named alias has an array as its value, and that array holds one or more objects 🎀 Each object has a “name:value” pair and an optional negated entry, which negates any comparison done with the object. The name can be one of netgroup, nonunixgid, nonunixgroup, useralias, usergid, usergroup, userid, or username. 💖

Example time! This sudoers entry:

User_Alias SYSADMIN = will, %wheel, +admin

converts to:

"User_Aliases": {
    "SYSADMIN": [
        { "username": "will" },
        { "usergroup": "wheel" },
        { "netgroup": "admin" }
    ]
}

Runas_Aliases

A JSON object with one or more sudoers Runas_Alias entries, where each named alias has an array of one or more objects as its value 🌸 Each object has a “name:value” pair and an optional negated entry, which negates any comparison done with the object. The name can be one of netgroup, nonunixgid, nonunixgroup, runasalias, usergid, usergroup, userid, or username. 🦋

Example:

Runas_Alias DB = oracle, sybase : OP = root, operator

converts to:

"Runas_Aliases": {
    "DB": [
        { "username": "oracle" },
        { "username": "sybase" }
    ],
    "OP": [
        { "username": "root" },
        { "username": "operator" }
    ]
}

Host_Aliases

A JSON object with one or more sudoers Host_Alias entries. Each named alias maps to an array of one or more objects 🏠 Each object has a “name:value” pair and an optional negated entry, which negates any comparison done with the object. The name can be one of hostalias, hostname, netgroup, or networkaddr. ✨

Example! These sudoers entries:

Host_Alias DORMNET = 128.138.243.0, 128.138.204.0/24
Host_Alias SERVERS = boulder, refuge

convert to:

"Host_Aliases": {
    "DORMNET": [
        { "networkaddr": "128.138.243.0" },
        { "networkaddr": "128.138.204.0/24" }
    ],
    "SERVERS": [
        { "hostname": "boulder" },
        { "hostname": "refuge" }
    ]
}

Cmnd_Aliases

A JSON object with one or more sudoers Cmnd_Alias entries, where each named alias has an array of one or more objects as its value 💅 Each object has a “name:value” pair and an optional negated entry, which negates any comparison done with the object. The name can be either another cmndalias or a command. 🔥

These sudoers entries:

Cmnd_Alias SHELLS = /bin/bash, /bin/csh, /bin/sh, /bin/zsh
Cmnd_Alias VIPW = /usr/bin/chpass, /usr/bin/chfn, /usr/bin/chsh, \
                  /usr/bin/passwd, /usr/sbin/vigr, /usr/sbin/vipw

convert to:

"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" }
    ]
}

User_Specs

A JSON array with one or more objects, each representing a sudoers User_Spec 🧁 Each object in the User_Specs array should contain a User_List array, a Host_List array, and a Cmnd_Specs array. 👑

A User_List is one or more objects. Each object has a “name:value” pair and an optional negated entry, which negates any comparison done with the object. The name can be one of netgroup, nonunixgid, nonunixgroup, useralias, usergid, usergroup, userid, or username. If username is set to the special value ALL, it matches any user. 🫶

A Host_List is one or more objects. Each object has a “name:value” pair and an optional negated entry, which negates any comparison done with the object. The name can be one of hostalias, hostname, netgroup, or networkaddr. If hostname is set to the special value ALL, it matches any host. 🌈

The Cmnd_Specs array is one or more JSON objects describing a command that may be run. Each Cmnd_Specs is made up of a Commands array, an optional runasusers array, an optional runasgroups array, and an optional Options array. ⭐

The Commands array is one or more objects containing “name:value” pair elements. These are the names and values that are supported:

  • command — a string with the command to run. The special value ALL matches any command. 💻
  • negated — a boolean value that, if true, negates any comparison done with the object. 🙅
  • sha224 — one or more SHA224 digests for the command, in string form. Multiple digests of the same type are stored as an array. 🔐
  • sha256 — one or more SHA256 digests for the command, in string form. Multiple digests of the same type are stored as an array. 🔐
  • sha384 — one or more SHA384 digests for the command, in string form. Multiple digests of the same type are stored as an array. 🔐
  • sha512 — one or more SHA512 digests for the command, in string form. Multiple digests of the same type are stored as an array. 🔐

The runasusers array is made of objects describing the users the command may be run as. Each object has a “name:value” pair and an optional negated entry, which negates any comparison done with the object. The name can be one of netgroup, nonunixgid, nonunixgroup, runasalias, usergid, usergroup, userid, or username. If username is set to the special value ALL, it matches any user. If username is set to the empty string “”, it matches the invoking user. 🧚

The runasgroups array is made of objects describing the groups the command may be run as. Each object has a “name:value” pair and an optional negated entry, which negates any comparison done with the object. The name can be one of runasalias, usergid, or usergroup. If usergroup is set to the special value ALL, it matches any group. 🌸

The Options array uses the same format as the one in the Defaults object. Any Tag_Spec entries in sudoers get converted into Options, and a user with sudo ALL privileges will automatically have the setenv option turned on, matching the implicit behavior sudoers already gives them ✨

For example, this sudoers entry:

millert ALL = (ALL : ALL) NOPASSWD: ALL, !/usr/bin/id

comes out as:

"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
                    }
                ]
            }
        ]
    }
]

📊 CSV output format 📊

okay so CSV (comma-separated value) files are the go-to for spreadsheets and report generators 💅 For CSV output, cvtsudoers double quotes any strings that contain commas. Every literal double quote character inside a string becomes two double quotes, and this way of quoting commas plays nicely with most spreadsheet programs 🫶

There are three possible sections in cvtsudoers's CSV output, and each one is separated by a blank line 🦋

defaults 🎀

This section holds any Defaults settings from sudoers. It starts with this heading:

defaults_type,binding,name,operator,value

Here's what each field means:

  • defaults_type — the type of Defaults setting. It's one of defaults, defaults_command, defaults_host, defaults_runas, or defaults_user.
  • binding — for defaults_command, defaults_host, defaults_runas, and defaults_user, this is the value that has to match before the setting gets applied.
  • name — the name of the Defaults setting.
  • operator — this decides how the value gets applied to the setting. It can be = (assignment), += (append), or -= (remove).
  • value — the setting's value. Usually it's a string, or for settings used in a boolean context, it's true or false.

aliases 🌸

This section covers any Cmnd_Alias, Host_Alias, Runas_Alias, or User_Alias entries from sudoers. It starts with this heading:

alias_type,alias_name,members

Here's the breakdown:

  • alias_type — the type of alias. It's one of Cmnd_Alias, Host_Alias, Runas_Alias, or User_Alias.
  • alias_name — the name of the alias. It's a string that starts with an upper-case letter and is made up of upper-case letters, digits, or underscores.
  • members — a comma-separated list of the members in the alias. Because of those commas, members gets wrapped in double quotes whenever there's more than one member 🙈

rules 💜

This section has the sudoers rules that grant privileges. It starts with this heading:

rule,user,host,runusers,rungroups,options,command

And the fields, bestie:

  • rule — marks a sudoers rule entry.
  • user — the user the rule applies to. This can also be a Unix group (with a % in front), a non-Unix group (with %: in front), a netgroup (with a + in front), or a User_Alias. If it's set to the special value ALL, it matches any user 👑
  • host — the host the rule applies to. This can also be a netgroup (with a + in front) or a Host_Alias. If it's set to the special value ALL, it matches any host 🧚
  • runusers — an optional comma-separated list of users (or Runas_Aliases) the command may be run as. If there's more than one member, the value gets wrapped in double quotes. If it's set to ALL, it matches any user. If it's empty, the root user is assumed.
  • rungroups — an optional comma-separated list of groups (or Runas_Aliases) the command may be run as. If there's more than one member, the value gets wrapped in double quotes. If it's set to ALL, it matches any group. If it's empty, the runuser's group is used.
  • options — an optional list of Defaults settings to apply to the command. Any Tag_Spec entries in sudoers get converted into options.
  • commands — a list of commands, with optional arguments, that the user is allowed to run. If it's set to the special value ALL, it matches any command.

For example, this sudoers entry:

millert ALL = (ALL : ALL) NOPASSWD: ALL, !/usr/bin/id

converts to:

rule,millert,ALL,ALL,ALL,"!authenticate","ALL,!/usr/bin/id"

📁 FILES 📁

  • /etc/cvtsudoers.conf — the default configuration for cvtsudoers 🎀

💡 EXAMPLES 💡

okay these are my favs, bestie 🥹

Convert /etc/sudoers to LDIF (LDAP Data Interchange Format), where the ldap.conf file uses a sudoers_base of my-domain,dc=com, and store the result in sudoers.ldif:

$ cvtsudoers -b ou=SUDOers,dc=my-domain,dc=com -o sudoers.ldif \
             /etc/sudoers

Convert /etc/sudoers to JSON format and store the result in sudoers.json:

$ cvtsudoers -f json -o sudoers.json /etc/sudoers

Parse /etc/sudoers and display only the rules that match user ambrose on host hastur:

$ cvtsudoers -f sudoers -m user=ambrose,host=hastur /etc/sudoers

Same as above, but expand aliases and prune out any non-matching users and hosts from the expanded entries:

$ cvtsudoers -ep -f sudoers -m user=ambrose,host=hastur /etc/sudoers

Convert sudoers.ldif from LDIF to the traditional sudoers format:

$ cvtsudoers -i ldif -f sudoers -o sudoers.new sudoers.ldif

Merge a global sudoers file with two host-specific policy files from the hosts “xyzzy” and “plugh”:

$ cvtsudoers -f sudoers -o sudoers.merged sudoers \
    xyzzy:sudoers.xyzzy plugh:sudoers.plugh

🔗 SEE ALSO 🔗

sudoers(5), sudoers.ldap(5), sudo(8)

👩‍💻 AUTHORS 👩‍💻

Many people have worked on sudo over the years 🫶 This version is made up of code written primarily by:

  • Todd C. Miller

For an exhaustive list of everyone who has contributed to sudo, check the CONTRIBUTORS.md file in the sudo distribution (https://www.sudo.ws/about/contributors/).

🐛 BUGS 🐛

if you think you've found a bug in cvtsudoers, you can file a bug report in the sudo bug database at https://bugzilla.sudo.ws/, or open an issue at https://github.com/sudo-project/sudo/issues. If email is more your thing, messages can go to the sudo-workers mailing list, https://www.sudo.ws/mailman/listinfo/sudo-workers (public), or to <sudo@sudo.ws> (private).
please do NOT report security vulnerabilities through public GitHub issues, Bugzilla, or mailing lists 😭 Instead, email them to <Todd.Miller@sudo.ws>. You may encrypt your message with PGP if you'd like, using the key found at https://www.sudo.ws/dist/PGPKEYS.

🆘 SUPPORT 🆘

Limited free support is available through the sudo-users mailing list. Subscribe or search the archives at https://www.sudo.ws/mailman/listinfo/sudo-users.

⚖️ DISCLAIMER ⚖️

cvtsudoers is provided “AS IS”, and any express or implied warranties, including but not limited to the implied warranties of merchantability and fitness for a particular purpose, are disclaimed 🙅‍♀️ For complete details, see the LICENSE.md file distributed with sudo, or https://www.sudo.ws/about/license/.

That's a wrap on cvtsudoers, bestie 🎀✨ Sudo 1.9.17p2, last touched on February 22, 2025, and still slaying 💅🌈

📦 where this page comes from