Safely reconcile Debian system accounts with update-passwd

You will compare a running Debian system's /etc/passwd, /etc/shadow and /etc/group with the account masters shipped by base-passwd, inspect any proposed changes, and apply them with a recoverable backup. The installed command here is update-passwd from base-passwd version 3.6.3build1.

Allow about fifteen minutes for a normal check, longer if the command proposes account changes. You need a shell and elevated privileges for the real check because /etc/shadow is normally unreadable to ordinary users. This command changes security-sensitive account databases, so schedule an approved maintenance window and keep an existing root session available.

1. Confirm the command and its input files

Start with read-only checks. These commands do not need sudo unless your system has unusual permissions:

$ command -v update-passwd
/usr/sbin/update-passwd
$ dpkg-query -W -f='${Package} ${Version}\n' base-passwd
base-passwd 3.6.3build1
$ update-passwd --version
update-passwd 3.6.3build1

The installed defaults are the two master copies /usr/share/base-passwd/passwd.master and /usr/share/base-passwd/group.master, compared with /etc/passwd, /etc/shadow and /etc/group. The tool considers the global system range, UID and GID 0 through 99. It is not a general account synchroniser for ordinary users.

Checkpoint: make sure the package version and paths are the ones you intend to use. Do not substitute a hand-edited file as a master unless you have a documented reason and have reviewed every entry.

2. Run a sanity check as root

The --sanity-check option checks the inputs without making changes. Run it with sudo so that the shadow database can be opened:

$ sudo update-passwd --sanity-check --verbose
# output depends on the state of this host
$ printf 'exit status: %s\n' "$?"
exit status: 0

On this machine, running the same command without elevated privileges fails while opening /etc/shadow. That is an access problem, not evidence that the account files are inconsistent. If your command returns a non-zero status, read the diagnostic before trying a different option.

--verbose prints more detail. A second --verbose requests additional detail, so use --verbose --verbose when the first report is not enough.

3. Preview proposed changes

Once the sanity check has succeeded, use --dry-run for the operational preview:

$ sudo update-passwd --dry-run --verbose
# proposed changes, if any, are printed here
$ printf 'exit status: %s\n' "$?"
exit status: 0

Dry-run means that the program reports what it would do and then leaves the account files alone. Review every proposed addition, removal, UID or GID change, home-directory change, shell change and GECOS change. A change to a low-numbered service account can prevent a daemon from starting or can make files appear to belong to a different numeric identity.

Do not treat an empty report as a failure. It normally means that the installed master copies require no update in the global system range.

4. Apply the update only after review

$ sudo update-passwd --verbose
# review any interactive questions and the final report

The program locks the account database during its work. Keep the normal locking behaviour. The --no-locking option exists for debugging but the manual explicitly warns against using it unless you are certain it is necessary. Do not add it to a routine repair command.

If DEBIAN_HAS_FRONTEND is set and you did not use --dry-run, update-passwd can use debconf to ask about proposed changes. Each proposed change may produce its own prompt. Read the exact question rather than accepting a long sequence mechanically.

5. Check the result and backups

The command leaves an .org copy of a previous file when it modifies that file. Inspect the current files and any backups without printing password hashes:

$ sudo stat -c '%A %U:%G %s %n' /etc/passwd /etc/shadow /etc/group
$ sudo find /etc -maxdepth 1 -type f -name '*.org' -printf '%f\n'
$ getent passwd root
root:x:0:0:root:/root:/bin/bash
$ getent group root
root:x:0:

The exact getent output depends on local account data. Check the key service accounts you expected to remain present, and confirm that the services relying on them are healthy. Do not use cat /etc/shadow as a verification step: it exposes password hashes unnecessarily.

Keep the .org files until the result has been checked. They are recovery material, not a permanent substitute for a tested account-backup procedure.

6. Recover carefully if an account change breaks something

There is no undo flag. If a service or login is broken, stop making further account changes and preserve diagnostics. Compare the affected current file with its matching .org copy:

$ sudo diff -u /etc/passwd.org /etc/passwd
$ sudo diff -u /etc/group.org /etc/group
# inspect /etc/shadow.org only when it exists and access is authorised
$ sudo diff -u /etc/shadow.org /etc/shadow

Restore a file only after confirming that it is the file you need and that no later legitimate account change would be lost. A restoration replaces the current database and is itself a security-sensitive change:

$ sudo cp --preserve=all /etc/passwd.org /etc/passwd
$ sudo cp --preserve=all /etc/group.org /etc/group
# restore /etc/shadow.org in the same way only after reviewing it
$ sudo pwck -r
$ sudo grpck -r

The pwck and grpck checks are separate local tools; if they are unavailable, stop and use your distribution's normal account-recovery procedure. Restoring only one related file can leave the databases mismatched, so involve the person responsible for the host before restoring a partial set.

7. Know the boundary of the check

The installed manual records a limitation: update-passwd does not verify that every passwd entry has a matching shadow entry, or that passwords are absent from both files. A successful run therefore does not prove that the shadow database is complete or correctly separated.

It also does not manage ordinary user accounts, rotate passwords, repair arbitrary ownership, or enable a disabled login service. Keep those tasks separate. If the command reports a difference that you cannot explain, leave the files unchanged, save the verbose dry-run output, and investigate the package master files and local policy before applying it.