Safely Validate and Edit sudoers with visudo

Edit /etc/sudoers with a plain text editor and one bad line can lock out every admin on the box; visudo exists to stop that happening.

By the end of this guide, you can check the complete sudo policy, edit it with the right safeguards, and confirm a change was accepted. The commands match sudo 1.9.15p5, with sudoers grammar version 50, installed on this system.

• Allow about 10 minutes for a small, reviewed change.
• You need: an account that can run sudo, a root shell, or equivalent administrative access.

Warning: editing /etc/sudoers is security-sensitive. A mistake can remove administrative access or grant more access than intended. Keep an already-open root session available until the new policy has been checked.

1. Confirm the installed tool

Run this as an ordinary user. It does not change any file and prints the installed visudo and grammar versions:

visudo --version

Expected output includes:

visudo version 1.9.15p5
visudo grammar version 50

2. Check the current policy first

Ask visudo to parse the main file and every file it includes. This is the safest first action because check-only mode does not open an editor or install changes. It also checks ownership and permissions when you use the default path:

sudo visudo --check

A successful check exits with status 0 and normally reports the file parsed successfully. Verify the status explicitly when using it in a script:

sudo visudo --check && echo "sudoers check passed"

Run the command again after any edit. Checking only a new include file is not enough, because sudo evaluates the policy as a whole.

3. Edit the policy through visudo

Use visudo with elevated privileges. It locks the policy against simultaneous edits, writes a temporary copy, checks the result, and installs it only after parsing succeeds:

sudo visudo

The default file is /etc/sudoers. Do not edit it with a general text editor and copy it back afterwards: that bypasses the locking, validation and ownership safeguards that make this workflow recoverable.

Add the smallest rule that meets the requirement. This example grants user alice permission to restart one named service without a password:

alice ALL=(root) NOPASSWD: /usr/bin/systemctl restart example.service

Replace both the account and command with values you have verified on this host. A command path, arguments, and wildcard can change the security boundary, so do not copy this rule unchanged into production.

4. Handle the editor safely

visudo chooses an editor from the SUDO_EDITOR, VISUAL, and EDITOR environment variables when the sudoers policy permits it, then falls back to its configured editor list. Check which editor you are about to use before starting an elevated edit:

printf 'SUDO_EDITOR=%s\nVISUAL=%s\nEDITOR=%s\n' "$SUDO_EDITOR" "$VISUAL" "$EDITOR"

• Use an editor you know how to save and exit. An editor with shell escapes can provide a root shell during a visudo session.
• Pick something simple and trusted for privileged editing. That beats accepting an arbitrary environment value.
• Review the env_editor sudoers setting. It is enabled by default in this sudo version, so check it is part of your privilege design.

5. Respond to a syntax error

If visudo finds a syntax error, it prints the affected line and asks What now?. The edit has not been installed at this point.

• Enter e to return to the editor, usually positioned at the reported line.
• Enter x to leave without saving the faulty change.
• Enter Q to save despite the error. Avoid this: sudo will see the same syntax error and may stop applying the policy.

If you are unsure, choose x, record what you changed, and start again after checking the syntax and the referenced names. This is the recovery path that leaves the installed policy untouched.

6. Check an alternate policy file

For a planned change or a test copy, specify the file explicitly. The file must contain the complete policy context needed for parsing, including any relevant include directives:

sudo visudo --check --file=/path/to/test-sudoers

Use an absolute placeholder path such as /path/to/test-sudoers only after replacing it with a real file. In check-only mode, visudo reads - as the policy from standard input, which is useful for a controlled generated candidate:

cat /path/to/test-sudoers | sudo visudo --check --file=-

Do not treat a successful parse as proof that a rule is appropriate. Parsing confirms grammar, not that the permission is least-privilege or that the command behaves as intended.

7. Confirm the result

After saving an edit, run the full check again from a separate command prompt:

sudo visudo --check
sudo -l -U alice

The first command must succeed. The second displays the privileges for the account you changed, so inspect that the intended command appears and that unrelated privileges did not appear. If the check fails, do not close your existing administrative session: re-enter sudo visudo, remove or correct the last change, and check again.

Warnings about undefined or cyclic aliases are normally warnings, but strict mode treats them as errors. Use strict checking when reviewing aliases or CI candidates:

sudo visudo --check --strict

Tip: files inside an @includedir or #includedir are subject to filename rules. Backup names ending in ~ or .bak, and names containing a dot, are ignored. A rule saved in such a file will not be active, even if its contents look correct.

Common failure messages

• /etc/sudoers: Permission denied. Run visudo with the required privilege.
• sudoers file busy, try again later. Another visudo process holds the lock. Wait for the legitimate edit to finish; do not delete the temporary file blindly.
• An owner or permission error in check mode. Restore the expected ownership and mode through your normal privileged administration process, then repeat the check.
• A rule appears absent. Inspect the include filename, then check the complete policy rather than only the fragment.

Done means

• visudo --version identified the local sudo version.
• sudo visudo --check completed successfully after the edit.
• The intended privilege appeared in sudo -l -U USER.
• You kept a working administrative session until verification finished.
• You did not accept a syntax error with Q unless you fully understood the recovery consequences.