Safely Change a Linux Group with groupmod

You will finish with a controlled way to rename a local group, change its numeric GID or update its member list using groupmod. The examples target shadow-utils 4.13, installed here from Ubuntu's passwd package version 1:4.13+dfsg1-4ubuntu3.2.

Allow about fifteen minutes for a simple rename and longer for a GID change on a busy host. You need the group name, the intended new value, a root shell or a working sudo policy, and a maintenance plan if services use the group. These operations change account databases. Read the warning before changing a GID or membership.

1. Inspect the current group

Start with read-only checks. They do not need elevated privileges on a normal system:

$ getent group APP_GROUP
$ getent passwd | awk -F: '$4 == "OLD_GID" { print $1 }'
$ stat -c '%n %G %g' /path/to/a/file

Replace APP_GROUP, OLD_GID and /path/to/a/file with real values. The first command shows the group's current GID and supplementary members. The second finds users whose primary group is the old numeric ID. The third shows both the name and numeric ownership of one file. Repeat the file search for every filesystem that may contain data owned by the group.

Checkpoint: write down the current group line, GID, primary users and important paths. If the group does not exist, stop. groupmod reports that condition and cannot create a group; use groupadd only after checking that this is genuinely the intended operation.

2. Check the installed syntax

Ask the installed binary for its option list. This is a normal, unprivileged command:

$ command -v groupmod
/usr/sbin/groupmod
$ groupmod --help

The command shape is groupmod [options] GROUP. The options relevant here are --new-name, --gid, --users and, with that last option, --append. The installed help is the useful local contract if a distribution adds or removes an option. This host reports shadow-utils 4.13; do not copy syntax from an unrelated operating system without checking it.

3. Rename a group

Renaming changes the group name in the group database. It does not change the numeric GID, so existing file ownership remains associated with the same group ID:

$ sudo groupmod --new-name APP_GROUP_NEW APP_GROUP

This requires elevated privileges because it updates the system account files. The new name must not already be in use. Confirm the result and check a known file:

$ getent group APP_GROUP_NEW
$ getent group APP_GROUP
$ stat -c '%n %G %g' /path/to/a/file

The first lookup should show the renamed group, the second should produce no output, and the file's numeric GID should be unchanged. To undo the rename, use the old name as the destination and the new name as the source, provided no other group has taken the old name:

$ sudo groupmod --new-name APP_GROUP APP_GROUP_NEW

4. Change a GID with an ownership plan

Changing a GID is more disruptive than changing a name. Users whose primary group is the modified group are updated by groupmod, but files carrying the old numeric GID are not all found and rewritten for you. Services, ACLs, containers, backups and mounted filesystems can also retain the old number.

Choose a non-negative decimal GID that is not already assigned:

$ getent group | awk -F: '$3 == "NEW_GID" { print }'
$ getent group APP_GROUP

A blank first result means this lookup found no matching local or configured NSS group. It is not a guarantee that an LDAP, NIS or other directory will behave the same way during the change. Do not use --non-unique just to silence a collision. Duplicate GIDs make ownership ambiguous and should be an explicit, documented compatibility decision.

Back up the relevant account databases using your normal system backup process, stop or drain services that depend on the group, then run the change as root:

$ sudo groupmod --gid NEW_GID APP_GROUP

Verify the database and primary users:

$ getent group APP_GROUP
$ getent passwd | awk -F: '$4 == "NEW_GID" { print $1 }'

Now find and repair files that should follow the group. Limit the search to known local filesystems and review the result before changing anything:

$ sudo find /srv/app /var/lib/app -xdev -gid OLD_GID -print
$ sudo find /srv/app /var/lib/app -xdev -gid OLD_GID -exec chgrp -- APP_GROUP {} +

The second command is a state-changing command. Replace the directories with paths you have reviewed; do not run it against an entire mounted system by reflex. If the result is wrong, restore the files' group with chgrp OLD_GROUP path or restore from the backup, depending on the scope of the mistake. Restart services only after checking their configuration and a representative file.

5. Replace or append supplementary members

--users supplies the group's member list. Treat it as a replacement unless you also pass --append. This is an easy distraction trap: omitting a current member can remove their supplementary access immediately.

$ sudo groupmod --users alice,bob APP_GROUP

That command makes alice and bob the listed members. To retain the existing list and add users, use the append modifier:

$ sudo groupmod --append --users carol,dave APP_GROUP

Check the resulting entry:

$ getent group APP_GROUP

Membership changes affect new login sessions. A user with an existing shell may need to log out and in again, or start a new session, before the supplementary group appears in id. To recover an accidental replacement, rerun --users with the complete intended list from your recorded baseline.

6. Keep specialised options out of routine changes

--non-unique is only for allowing a duplicate GID with --gid. Use it only when an application or migration has a tested reason to represent two names with one numeric identity. It is not a repair for a failed availability check.

A group password passed with --password is exposed to users who can inspect the process list, so the manpage does not recommend that option. Do not put an encrypted password into a shell history or automation command merely because the option exists.

--root applies changes inside an absolute chroot directory. --prefix prepares files below a prefix without chrooting, and has limitations including no SELinux support and host PAM authentication. Use these only in a tested image-building or recovery workflow. They do not change the running host's group database.

7. Read failures by their exit status

Capture the status immediately when a script needs to distinguish failures:

if sudo groupmod --new-name APP_GROUP_NEW APP_GROUP; then
    printf '%s\n' 'group renamed'
else
    status=$?
    printf 'groupmod failed with status %s\n' "$status" >&2
    exit "$status"
fi

Status 0 means success. Status 4 indicates that the requested GID is already in use, 6 that the group was not found, and 9 that the new name is already in use. Status 2 or 3 points to command syntax or an invalid option argument. Status 10 means the group file could not be updated. Investigate the reported condition instead of repeating a privileged command blindly.