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

Checkpoint: do not assume a newly added supplementary-group membership shows up in an already-running login session. Start a new session, or use a deliberate group-refresh method for your system, before testing anything that depends on it.

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

Warning: --purge removes every user from the selected group's membership list in one go, which can immediately break access to shared files, devices or services for several accounts at once. Review the list and get the operational approval you need before running it:

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.