Rename, Renumber or Fix a Linux Group with groupmod

A renamed group can break every file permission built on the old name, and groupmod is what makes that rename deliberate. It also renumbers a GID and rewrites a member list. 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, longer for a GID change on a busy host. You need:

• The group's current name and GID. Read with getent group.
• The new name or GID. Checked for collisions before you use it.
• A root shell or a working sudo policy. These operations edit account databases.
• A maintenance plan. For any service that already uses the group.

Read the warning in step 4 before you touch a GID or a member list.

1. Inspect the current group

Start with read-only checks. None of these 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, then read the three outputs:

• The first command shows the group's current GID and supplementary members.
• The second command finds users whose primary group is the old numeric ID.
• The third command shows the name and numeric ownership of one file. Repeat it for every filesystem that may hold data owned by the group.

2. Check the installed syntax

Ask the installed binary for its own 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 that matter here are --new-name, --gid, --users and, with that last one, --append. This host reports shadow-utils 4.13, so treat the installed help as the real contract and do not copy syntax from an unrelated operating system without checking it first.

3. Rename a group without touching its GID

Renaming only changes the name in the group database. The numeric GID does not move, so existing file ownership stays tied to the same GID:

$ sudo groupmod --new-name APP_GROUP_NEW APP_GROUP

This needs elevated privileges because it edits the system account files, and 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 renamed group should now resolve with getent.
• The old name should produce no output.
• The file's numeric GID should be unchanged.

To undo the rename, swap source and destination, provided no other group has since taken the old name:

$ sudo groupmod --new-name APP_GROUP APP_GROUP_NEW

4. Change a GID and plan for the ownership it leaves behind

Changing a GID is far more disruptive than a rename. groupmod updates users whose primary group is the modified group, but it does not find and rewrite every file that still carries the old numeric GID. Services, ACLs, containers, backups and mounted filesystems can all 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 only means this lookup found no matching local or configured NSS group. It is not a guarantee that an LDAP, NIS or other directory will agree during the change. Do not use --non-unique just to silence a collision: duplicate GIDs make ownership ambiguous and should be an explicit, documented decision, not a shortcut.

Back up the relevant account databases through your normal 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 {} +

5. Replace or append supplementary members

--users supplies the group's whole member list. Treat it as a replacement unless you also pass --append: leaving out a current member removes their supplementary access immediately, and that is an easy trap.

$ sudo groupmod --users alice,bob APP_GROUP

That makes alice and bob the only listed members. To keep the existing list and add more, 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, not ones already running. A user with an existing shell may need to log out and back in, or start a fresh session, before the supplementary group shows up 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 only allows a duplicate GID alongside --gid. Use it when an application or migration has a tested reason to represent two names with one numeric identity, not as a repair for a failed availability check.
• --password exposes a group password to anyone who can inspect the process list, so the manpage does not recommend it. Do not put an encrypted password into shell history or an automation command merely because the option exists.
• --root applies changes inside an absolute chroot directory.
• --prefix prepares files below a prefix without chrooting, with limitations including no SELinux support and host PAM authentication. Use these two only in a tested image-building or recovery workflow; they do not touch the running host's group database.

7. Read failures by their exit status

Capture the status immediately when a script needs to tell failures apart:

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 means the requested GID is already in use.
• Status 6 means the group was not found.
• Status 9 means the new name is already in use.
• Status 2 or 3 points to a command syntax problem 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.