Read and Safely Check Linux's /etc/gshadow File

A ticket asks who can grant a shared group's permissions, and the answer lives in /etc/gshadow, not /etc/group. You will identify what the file controls, inspect it without printing group password hashes, and run a read-only consistency check. Allow about ten minutes. The examples use shadow-utils 4.13, as provided by the installed Ubuntu passwd package version 1:4.13+dfsg1-4ubuntu3.2.

Checkpoint: stop after step 3 if you only needed to understand the file. Steps 4 and 5 check or change group administration, and step 5 requires particular care.

1. Confirm the local tools

The file is normally maintained by account-management commands, not by hand. Check which commands are available before relying on an example:

$ command -v gpasswd grpck newgrp getent
/usr/bin/gpasswd
/usr/sbin/grpck
/usr/bin/newgrp
/usr/bin/getent

Paths can differ on another distribution. The important result is that the commands exist. This guide describes the installed shadow-utils 4.13 behaviour; another release or an LDAP or NIS deployment may use different administration paths.

2. Understand the four fields

Each non-comment line in /etc/gshadow has four colon-separated fields:

  1. Group name: the name of an existing group.
  2. Password: a crypt(3)-style value, an empty field, or a value such as ! or * that is not a valid password result.
  3. Administrators: comma-separated users who can change the group's password or membership, and who also have member access.
  4. Members: comma-separated users who can use the group without entering its password.

A blank password field means only listed members can gain the group through newgrp. A password beginning with ! is locked; the characters after the exclamation mark preserve the value that was there before locking. The gshadow password takes precedence over a password in /etc/group.

Do not treat the second field as an ordinary text password. It is sensitive authentication material, and /etc/gshadow must not be readable by regular users if group-password security is to be maintained.

3. Check protection without dumping secrets

Inspect ownership and mode with stat. This reads metadata only and does not reveal any gshadow field:

$ stat -c '%a %U %G %n' /etc/gshadow
640 root shadow /etc/gshadow

The exact mode and group are distribution policy, so do not blindly replace the output with these values. The practical check is that an ordinary account cannot read the file. Test that directly without printing its contents:

$ test -r /etc/gshadow && echo 'readable by this account' || echo 'not readable by this account'
not readable by this account

Warning: if the test says your account can read the file, treat that as a security finding. Do not paste the file into a ticket or chat. Preserve the current metadata for your system administrator to review, then repair ownership and permissions through your distribution's account-management policy. Avoid guessing a group name or mode on a production host.

4. Check the paired group databases read-only

/etc/group and /etc/gshadow describe the same groups from different security perspectives. Use grpck in read-only mode so it can report problems without accepting repair prompts:

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

No output and status 0 indicate that this check found no error. The command checks field counts, unique and valid names, member and administrator lists, and matching entries between the two files. Status 2 means one or more group entries are bad; status 3 means the files could not be opened. The other non-zero statuses cover command syntax, locking and update failures.

sudo is shown because grpck normally needs to read both protected files; if your account already has suitable access, omit it. The --read-only option is the safety boundary: without it, grpck can prompt about deleting malformed entries.

5. Change membership through gpasswd

Warning: do not edit /etc/gshadow with a text editor. For a real group, use gpasswd so the paired files and lock handling are managed together. Replace the placeholders only after checking the group and user names:

$ getent group PROJECT_GROUP
PROJECT_GROUP:x:2001:alice
$ sudo gpasswd --add USER_NAME PROJECT_GROUP
Adding user USER_NAME to group PROJECT_GROUP

The exact confirmation text can vary. Verify the membership through the normal group database view:

$ getent group PROJECT_GROUP
PROJECT_GROUP:x:2001:alice,USER_NAME

Removing a user is the inverse operation:

$ sudo gpasswd --delete USER_NAME PROJECT_GROUP
Removing user USER_NAME from group PROJECT_GROUP

These commands change access immediately for future sessions and can affect running work after its credentials are refreshed. They require elevated privileges unless you are an authorised group administrator. Before changing a production group, record the original membership and obtain the service owner's approval.

Recovery: if you removed the wrong user, run gpasswd --add with the original user name. If you are unsure what changed, stop and compare a trusted membership record rather than editing either file manually.

6. Treat group passwords as a last resort

A group password lets a non-member request the group's permissions with newgrp. The installed gpasswd manual calls group passwords an inherent security problem because more than one person may know the password. Prefer explicit membership where possible.

If an existing policy requires a group password, administer it through gpasswd PROJECT_GROUP, which prompts for a new value. Do not put the password in a shell command, script, terminal transcript or article. To remove the group password later, the documented command is:

$ sudo gpasswd --remove-password PROJECT_GROUP

That leaves the password field empty, so only group members can use newgrp for the group. gpasswd --restrict instead sets the field to ! and restricts access to members with a password. These are security-sensitive changes: check the resulting policy with your administrator and do not test them against a group used by a running service.

Common traps

Done means