Audit /etc/group and /etc/gshadow with grpck

A corrupted line in the group database can lock people out or quietly widen access, and grpck is the read-only way to find it before it finds you. The examples use grpck from shadow-utils 4.13, installed here through Ubuntu package passwd version 1:4.13+dfsg1-4ubuntu3.2.

Allow about ten minutes. You need a shell and access to the host whose account files you are checking. The first checks do not need elevated privileges, although permissions and the presence of /etc/gshadow vary between systems. Keep a maintenance window and a recovery plan ready if you intend to let grpck remove anything.

1. Check the installed command

Confirm the binary and its option spelling before using it. This is an ordinary read-only step:

$ command -v grpck
/usr/sbin/grpck
$ dpkg-query -W -f='${Package} ${Version}\n' passwd
passwd 1:4.13+dfsg1-4ubuntu3.2
$ grpck --help
Usage: grpck [options] [group [gshadow]]

The command normally checks /etc/group and /etc/gshadow. You can supply two alternate paths after the options, but do not confuse that with a chroot: --root is the option that takes an absolute directory and makes the command use files below it.

Checkpoint: the command should resolve to the expected system binary, and the package version should be recorded if you are comparing results across hosts.

2. Run the first check without changing files

Use --read-only, or its short form -r. It displays warnings and answers every proposed change with no:

$ grpck --read-only

A clean run exits with status 0 and normally produces no output. Always capture the status immediately if a script or monitoring check will use it:

grpck --read-only
status=$?
printf 'grpck exit status: %s\n' "$status"
exit "$status"

On this host, the same command reports grpck: cannot open /etc/gshadow and returns status 3. That is a file-access or file-presence failure, not proof that the group entries are valid. Check the file directly before changing anything:

$ ls -l /etc/group /etc/gshadow
ls: cannot access '/etc/gshadow': No such file or directory

Do not create an empty /etc/gshadow just to make the diagnostic disappear. Whether that file should exist is a packaging and account-management decision for the host, not a workaround you make up on the spot.

3. Read warnings as diagnostics, not a licence to delete

grpck checks field counts, unique group names, group IDs, member and administrator lists, and matching entries between /etc/group and /etc/gshadow. Not every finding carries the same risk:

Wrong field count. Fatal for that entry. The command can offer to delete the whole line, and refusing the prompt skips later checks for that line too.
Duplicated group name. Also offered for deletion, but the remaining checks continue regardless.
Everything else. A warning. The manual recommends correcting ordinary group data with groupmod rather than editing a damaged line by hand.

Warning: do not answer a deletion prompt with yes until you have copied the affected files and confirmed the line is genuinely corrupt. A group entry can control access to files, devices and services, and removing it can lock users out or alter a service's effective permissions.

4. Save a copy before investigating a damaged host

Before an interactive run that may change files, make a root-owned backup in a protected location. This needs elevated privileges because the account databases are sensitive:

$ sudo install -m 600 /etc/group /root/group.grpck-$(date +%Y%m%d-%H%M%S)
$ sudo install -m 600 /etc/gshadow /root/gshadow.grpck-$(date +%Y%m%d-%H%M%S)

The timestamp is a placeholder generated by the shell, so note the exact names printed or list them afterwards. If either file is absent, stop and decide whether that absence is expected for the distribution and account stack.

There is no universal one-command undo for a deletion made by grpck. Recovery means restoring the correct backup with the correct owner, group and mode, then checking the account-management service that owns those files. Do not blindly copy a backup over live files while users or provisioning tools are modifying them.

5. Check an image or alternate files read-only

For a mounted image or a prepared root directory, use --root with an absolute path. The command can apply changes in that directory, so keep --read-only in place while you inspect it:

$ sudo grpck --read-only --root /srv/target-root

For explicitly selected files, provide the group file and then the shadow file:

$ grpck --read-only /tmp/group.check /tmp/gshadow.check

Use real paths only after checking their contents and permissions. Never point the command at a production file copied from a different host unless you understand the group IDs, names and member accounts in that file.

6. Interpret the exit status

Use the numeric status to decide what to investigate next:

Status	Meaning	Next action
0	Success	Record the clean check.
1	Invalid command syntax	Review the options and paths.
2	One or more bad group entries	Read the diagnostic and inspect backups before repair.
3	Cannot open group files	Check presence, permissions and the selected root or paths.
4	Cannot lock group files	Check for another account-management operation; do not remove lock files casually.
5	Cannot update group files	Stop and investigate the filesystem and permissions.

A status of 2 means the command found bad entries; it does not mean every warning should be fixed by deletion. Statuses 3 through 5 mean the check or update could not complete at all, so treat them as operational failures in automation.

7. Leave sorting and warning suppression for deliberate cases

--sort rewrites the group files in GID order. It is not a harmless display option, so do not include it in a health check. If ordering is genuinely required, back up the files, make the change in a maintenance window, and verify the result afterwards.

--silence-warnings suppresses more controversial warnings, including inconsistencies between member lists in the two databases. That shortens noisy output, but it also hides information: use it only when the omitted warning is understood and another check covers it. Note that --read-only and --sort cannot be combined.

Done means

Recorded the versions. The installed grpck and passwd versions.
Ran the read-only check. grpck --read-only against the intended files.
Interpreted the exit status. Including missing-file failures.
Backed up sensitive files. Before considering an interactive repair.
Avoided the risky options. No --sort, and no deletion prompts accepted without evidence and a recovery path.