GROUPMOD(8)

💖 GROUPMOD 💖

okay bestie, so groupmod is a System Management Command and it's literally the glow-up artist for your groups. let's get into it 🎀

---

✨ NAME ✨

groupmod — modify a group definition on the system 👑

---

🦋 SYNOPSIS 🦋

groupmod [options] GROUP

---

🌸 DESCRIPTION 🌸

So basically, groupmod modifies the definition of the GROUP you hand it, by editing the appropriate entry in the group database. that's it, that's the whole vibe. it's giving "makeover montage but for /etc/group" 💅

---

✨ OPTIONS ✨

these are the options that apply to the groupmod command, no cap:

• -a, --append — if you're specifying group members with -U, this appends them to the existing member list instead of just replacing the whole thing. very "add to cart, don't empty the cart" energy 🛒
• -g, --gid GID — the group ID of the given GROUP gets changed to GID.

okay so important stuff here, bestie:

• GID must be a non-negative decimal integer. and it must be unique, unless you use the -o option.
• users who use this group as their primary group will be updated so they keep it as their primary group. 🫶
• any files that have the old group ID and need to keep belonging to GROUP have to have their group ID changed manually — groupmod is not doing that for you, sorry. 😭
• no checks will be performed with regard to the GID_MIN, GID_MAX, SYS_GID_MIN, or SYS_GID_MAX from /etc/login.defs.

• -h, --help — display the help message and exit. the classic "what does anything do" button 🙈
• -n, --new-name NEW_GROUP — the name of the group changes from GROUP to NEW_GROUP. rebranding era ✨
• -o, --non-unique — when used with the -g option, this allows you to change the group GID to a non-unique value. living dangerously, love that for you 💀
• -p, --password PASSWORD — the encrypted password, as returned by crypt(3).

note: this option is not recommended, because the password (or encrypted password) will be visible to users listing the processes. lowkey a privacy nightmare fr fr. 😬

you should make sure the password respects the system's password policy.

• -R, --root CHROOT_DIR — apply changes in the CHROOT_DIR directory and use the configuration files from the CHROOT_DIR directory. only absolute paths are supported. no SELINUX support.
• -P, --prefix PREFIX_DIR — apply changes in the PREFIX_DIR directory and use the configuration files from the PREFIX_DIR directory. this option does not chroot, and it's intended for preparing a cross-compilation target. some limitations to know about: NIS and LDAP users/groups are not verified. PAM authentication is using the host files. no SELINUX support.
• -U, --users — a comma-separated list of usernames to add as members of the group. bestie lineup 🧚

the default behavior (if the -g and -U options are not specified) is defined by the USERGROUPS_ENAB variable in /etc/login.defs.

---

🌈 CONFIGURATION 🌈

these configuration variables in /etc/login.defs change how this tool behaves:

MAX_MEMBERS_PER_GROUP (number)

Maximum members per group entry. when the maximum is reached, a new group entry (line) is started in /etc/group — with the same name, same password, and same GID. it's giving "split the group chat when it gets too full" 💬

the default value is 0, meaning there are no limits in the number of members in a group.

this feature (split group) lets you limit the length of lines in the group file. it's useful for making sure lines for NIS groups are not larger than 1024 characters.

if you need to enforce such a limit, you can use 25.

note: split groups may not be supported by all tools (even in the Shadow toolsuite). you should not use this variable unless you really need it. fr, be careful. 😭

---

🍓 FILES 🍓

• /etc/group — group account information.
• /etc/gshadow — secure group account information.
• /etc/login.defs — shadow password suite configuration.
• /etc/passwd — user account information.

---

👑 EXIT VALUES 👑

the groupmod command exits with these values, so you can tell what went down:

• 0 — E_SUCCESS: success 🎉
• 2 — E_USAGE: invalid command syntax
• 3 — E_BAD_ARG: invalid argument to option
• 4 — E_GID_IN_USE: group id already in use
• 6 — E_NOTFOUND: specified group doesn't exist
• 9 — E_NAME_IN_USE: group name already in use
• 10 — E_GRP_UPDATE: can't update group file
• 11 — E_CLEANUP_SERVICE: can't setup cleanup service
• 12 — E_PAM_USERNAME: can't determine your username for use with pam
• 13 — E_PAM_ERROR: pam returned an error, see syslog facility id groupmod for the PAM error message

---

💜 SEE ALSO 💜

chfn(1), chsh(1), passwd(1), gpasswd(8), groupadd(8), groupdel(8), login.defs(5), useradd(8), userdel(8), usermod(8).

---

and that's the whole page bestie, we ate and left no crumbs 🫶 this one's from shadow-utils 4.20.0, dated 07/30/2026 — go forth and modify those groups, main character 💅✨