Manage Primary-Group Membership Safely with groupmems

groupmems is the odd one out among the group tools: it lets a user manage their own primary group without touching sudo. By the end of this guide you will be able to inspect a groupmems-managed group, add or remove a named account, and recognise when the command needs root privileges instead. The local command is from shadow-utils 4.13, packaged here as passwd 1:4.13+dfsg1-4ubuntu3.2.

Allow about five minutes for a routine membership change. You need a shell account, the groupmems command from the passwd package, and a group whose membership you are authorised to change. Have sudo available for administrator-only work.

groupmems is designed for one particular arrangement: a user administers the membership list of their own primary group, such as alice managing group alice. The superuser can select another group with -g, but that is easy to miss: -g is not a general option for ordinary users.

1. Check the installed command

Confirm which command will run and check its installed help:

command -v groupmems
groupmems --help

Expect /usr/sbin/groupmems and actions named --add, --delete, --list and --purge. This build has no --version option, so use the package query instead when you need a version number:

dpkg-query -W -f='${Package} ${Version}\n' passwd

2. List the current membership

List the members of your own primary group:

groupmems --list

The output is a membership list, usually one username per line. Where the secure group database is not readable, the command fails instead of giving you a trustworthy answer: this installation reports groupmems: cannot open /etc/gshadow when run as an unprivileged user. Treat that as a permission or configuration problem, never as proof the group is empty.

Check the account and group relationship separately:

id
getent group <GROUP_NAME>

Replace <GROUP_NAME> with a real group name, without the angle brackets. id shows your primary group; getent shows the group database view, including its member field.

3. Add one member

Adding a member changes /etc/group and may create or update an entry in /etc/gshadow. Confirm the username first, then run:

getent passwd <USER_NAME>
sudo groupmems --group <GROUP_NAME> --add <USER_NAME>

Use --group only as root. If you are managing your own primary group through the intended set-up, leave it out:

groupmems --add <USER_NAME>

Verify with the same database lookup:

getent group <GROUP_NAME>
sudo groupmems --group <GROUP_NAME> --list

4. Remove one member

Removal is also a state change, but it is reversible if you know the previous username and group. Save the current membership output first if you are working on a shared or production machine, then remove only the intended account:

sudo groupmems --group <GROUP_NAME> --delete <USER_NAME>
sudo groupmems --group <GROUP_NAME> --list

To undo that removal, add the same account back:

sudo groupmems --group <GROUP_NAME> --add <USER_NAME>

Removing a user from a group does not delete the account, its home directory or its files; it changes group membership only. Existing processes may keep their old supplementary groups until they exit, so verify from a fresh session when access control is the whole point of the change.

5. Use purge with caution

sudo groupmems --group <GROUP_NAME> --list
sudo groupmems --group <GROUP_NAME> --purge
sudo groupmems --group <GROUP_NAME> --list

There is no separate restore operation in groupmems. Recovery means re-adding the accounts from a saved list, one at a time:

sudo groupmems --group <GROUP_NAME> --add <USER_NAME>

Do not paste a bulk loop until the saved list has actually been reviewed. A typo in the group name or username turns a straightforward recovery into a second incident.

6. Diagnose the usual failures

• Permission denied or an administrator-only error: use sudo for a group selected with --group. Ordinary users are meant to administer only their own primary group.
• cannot open /etc/gshadow: stop and ask the system administrator to check that /etc/gshadow exists and is readable by the command's configured execution path. Do not hand-create a replacement while troubleshooting.
• The member list looks unchanged: run getent group <GROUP_NAME>, then test from a new login session; an existing process can keep old supplementary-group credentials.
• A username is rejected: verify it with getent passwd <USER_NAME>. Never substitute a display name or numeric ID unless your local account database explicitly uses that name.

7. Manage a chrooted account database

--root applies the operation inside a chroot directory and reads configuration files from there, changing only the target account database and not the host's default files. It accepts absolute paths only:

sudo groupmems --root /srv/<CHROOT_NAME> --group <GROUP_NAME> --list

Check the directory really is the intended root, and that its etc/group and etc/gshadow files exist, before changing anything. A relative path is invalid, and a mistaken absolute path can modify a different system image from the one you meant to administer.

Done means

• Version confirmed: you checked the installed passwd and shadow-utils version.
• Group identified: you found the target group and checked its current membership.
• Privilege used correctly: root was used only for selecting another group's list or operating on a chroot.
• Result verified: the final membership was checked with groupmems --list or getent group.
• Recovery covered: if you removed or purged members, you kept enough information to restore them with --add.