Safely Edit Linux Account Files with vipw and vigr

One stray colon in /etc/passwd can lock every account out or hand one out for free, which is why vipw exists instead of a plain text editor.

vipw edits /etc/passwd; vigr edits /etc/group. Their -s forms edit the protected files behind them, /etc/shadow and /etc/gshadow. Allow about 15 minutes, including a backup and a verification check. This guide covers the installed Ubuntu package passwd 1:4.13+dfsg1-4ubuntu3.2, whose local manuals identify the bundled implementation as shadow-utils 4.13.

• You need: root privileges for the edit, a known-good editor, and a maintenance window if the change could affect logins or group access.

Warning: these files control authentication and authorisation. A malformed line, an accidental deletion, or an incorrect shadow value can lock out users or grant access. Do not edit them on a remote host unless you have a working root console or another recovery path.

1. Choose and test the editor

vipw and vigr pick an editor in this order: VISUAL, then EDITOR, then vi. Set one explicitly for a one-off change so an unexpected default does not become a distraction:

$ command -v nano
/usr/bin/nano
$ VISUAL=nano
$ printf '%s\n' "$VISUAL"
nano

• Check the first command prints a path you recognise. If it prints nothing, pick an installed editor before continuing.
• Avoid anything that silently reformats or saves through an unusual workflow. That includes editors with autosave or auto-indent surprises.

Checkpoint: the editor choice is known, and you can exit it without saving. If you are unsure how to cancel, open a harmless temporary file first.

2. Make a recoverable backup

Back up the exact files you may touch. This is an ordinary read followed by a write to a root-owned directory, so use elevated privileges for both:

$ sudo install -m 600 /etc/passwd /root/passwd.vipw.before
$ sudo install -m 600 /etc/group /root/group.vigr.before
$ sudo install -m 600 /etc/shadow /root/shadow.vipw.before
$ sudo install -m 600 /etc/gshadow /root/gshadow.vigr.before

Check the snapshots exist and are non-empty:

$ sudo ls -l /root/passwd.vipw.before /root/group.vigr.before /root/shadow.vipw.before /root/gshadow.vigr.before

Keep these files protected: they contain password hashes and account metadata. Delete them only once you have confirmed the change and no rollback is needed.

3. Edit the normal account database

For a user account entry:

$ sudo env VISUAL=nano vipw

For a group entry:

$ sudo env VISUAL=nano vigr

• Edit only the intended line. Preserve the existing colon-separated layout and leave unrelated records alone.
• Do not paste a line from an untrusted source. And do not remove an account merely because it looks unused.
• If the editor asks whether to save, stop. Inspect the file again rather than guessing.

The commands take the appropriate locks while editing, which reduces the chance of two account-management operations writing over one another, but it does not make an incorrect edit safe. Close the editor normally to save, or exit without saving to abandon the change.

Checkpoint: run a read-only lookup immediately afterwards:

$ getent passwd ACCOUNT_NAME
ACCOUNT_NAME:x:1001:1001:Example User:/home/ACCOUNT_NAME:/bin/bash
$ getent group GROUP_NAME
GROUP_NAME:x:1002:ACCOUNT_NAME

Replace the uppercase placeholders with real names; the exact numeric IDs and shell will differ. A blank result means the name is not being returned by the configured account sources. It does not by itself prove a local file is malformed, because getent can also consult network sources.

4. Edit protected password or group data only when required

The -s option selects the shadow database. With vipw, for /etc/shadow:

$ sudo env VISUAL=nano vipw -s

With vigr, for /etc/gshadow:

$ sudo env VISUAL=nano vigr -s

This is a security-sensitive operation. Do not replace a password field with a value copied from a chat message or a web page. Prefer a dedicated account command when one exists, such as passwd ACCOUNT_NAME for changing a password. Manual shadow editing is for cases where you understand the field and its intended effect.

After saving, confirm the target record is readable without displaying the whole file:

$ sudo getent shadow ACCOUNT_NAME
ACCOUNT_NAME:!:...

The value shown after the first colon is sensitive. Do not paste it into a ticket or shell transcript. If your change affects group administration, use getent gshadow GROUP_NAME with the same care.

5. Roll back a bad change

Warning: do not restore backups over live files while account services are actively changing them. Stop the relevant maintenance activity first, and make sure no administrator is editing the same database. Then restore only the affected file, retaining its restrictive ownership and mode:

$ sudo install -o root -g root -m 644 /root/passwd.vipw.before /etc/passwd
$ sudo install -o root -g root -m 644 /root/group.vigr.before /etc/group
$ sudo install -o root -g shadow -m 640 /root/shadow.vipw.before /etc/shadow
$ sudo install -o root -g shadow -m 640 /root/gshadow.vigr.before /etc/gshadow

Those modes match a common Debian or Ubuntu installation, but check the live file with stat before restoring if this host uses a different policy:

$ sudo stat -c '%U %G %a %n' /etc/passwd /etc/group /etc/shadow /etc/gshadow

If the change caused login or service failures, use the host console or your provider's recovery environment. Avoid repeatedly editing the files until you know which record caused the problem.

6. Use the installed help when a mode is unclear

The local program accepts -g, -p, -q, -R and -s, along with their long forms. -R applies the operation inside an absolute chroot directory; do not point it at a live system directory unless that is the specific task.

$ vipw --help
Usage: vipw [options]

Options:
  -g, --group                   edit group database
  -h, --help                    display this help message and exit
  -p, --passwd                  edit passwd database
  -q, --quiet                   quiet mode
  -R, --root CHROOT_DIR         directory to chroot into
  -s, --shadow                  edit shadow or gshadow database

The same option set is available through vigr --help, so there is no need to guess at a flag. The local program does not provide a useful --version option, so the package query above is the reliable version check on this machine.

Done means

• Selected the correct command and database.
• A protected backup exists for every file changed.
• The editor choice was explicit and the edit was saved deliberately.
• getent can read the affected account or group.
• No password hash or shadow record was exposed in logs, tickets or chat.
• You know where the rollback copy is and can reach a recovery console if needed.