VMware ESXi and vSphere Cluster Management

Administer Linux Groups with gpasswd

Learn how to use gpasswd to add and remove group members, assign group administrators, set group member lists, change group passwords, and verify Linux group configuration.

gpasswd is a command-line utility for administering local Linux groups. It can manage group membership, designate group administrators, and change a group's password. Because these operations affect authorization, they usually require sudo or an administrative shell.

This lesson covers supplementary group membership and the local group database. It also explains how to verify the effective result when a system obtains identity data from sources such as LDAP through NSS.

Linux group concepts

A user is an account that can run processes and own files. A group is a named collection of accounts used to grant shared access to files, directories, applications, and other resources.

A user's primary group is the default group associated with the account. It is commonly used as the group owner of newly created files.
A supplementary group is an additional group membership beyond the primary group. Supplementary groups are commonly used to grant access to shared resources.
A normal group member receives access associated with the group and may be able to use the group's password, depending on the system's configuration.
A group administrator is a user authorized to manage membership and the password for one specific group. This is different from being a system-wide root administrator.

For example, adding john to project can give him access to files whose group ownership is project, provided the file permissions and directory permissions also allow that access.

What gpasswd manages

gpasswd operates on a named group. Its main administrative operations are:

Add one user to a group's supplementary member list.
Remove one user from a group's supplementary member list.
Set one or more designated group administrators.
Replace the group's supplementary member list with an explicit list.
Interactively set or change the group password.

Use an account-management command rather than manually editing /etc/group whenever possible. Administrative commands can apply the system's expected locking and database-handling behavior.

gpasswd options for group administration

Option	Purpose	Argument pattern	Example	Important behavior
`-a`	Add a user	`-a user group`	`gpasswd -a john project`	Adds the user without replacing other supplementary members.
`-d`	Delete a user	`-d user group`	`gpasswd -d john project`	Removes the named user from the group.
`-A`	Set group administrators	`-A admin_list group`	`gpasswd -A alice,bob project`	Uses a comma-separated list. The administrator list is defined by this operation.
`-M`	Set group members explicitly	`-M member_list group`	`gpasswd -M alice,john project`	Replaces the supplementary member list with the specified comma-separated list.
No option	Change the group password	`gpasswd group`	`gpasswd project`	Starts an interactive password change.

Add a user to a group

Use -a followed by the username and group name. The argument order is important: option, username, then group.

sudo gpasswd -a john project

This adds john to the project supplementary group. It does not change John's primary group. The change affects newly created login sessions; an existing shell may still have the old group credentials.

After the operation, verify the effective group record and the user's configured memberships:

getent group project
id john

Ask the user to start a new login session before testing access. Logging out and in again is the clearest approach. Some session-management tools can refresh credentials, but a new login avoids ambiguity.

Remove a user from a group

Use -d with the username and group name:

sudo gpasswd -d john project

This removes john from the group's supplementary member list. Access granted specifically through project may then be revoked after the user's active session is refreshed. It does not automatically remove access granted by another group, an ACL, the user's primary group, or other permission mechanism.

Before removing a member, check whether the account still needs access to the group's files, applications, or services. Verify the result:

getent group project

Assign group administrators

The -A option defines one or more administrators for a group. When more than one administrator is specified, separate usernames with commas and do not add spaces.

sudo gpasswd -A alice project
sudo gpasswd -A alice,bob project

Designated administrators can manage membership and the group password for that group, subject to the platform's implementation and authorization rules. They are not automatically system administrators and cannot manage every group.

Set group members explicitly with -M

The -M option sets the complete supplementary member list. Its value is a comma-separated list of usernames:

sudo gpasswd -M alice,john project

This is not an append operation. Members that are currently listed but omitted from the command can be removed. Review the current state first and provide the complete intended list.

The administrator list and the regular member list are separate concepts. Assigning alice as an administrator does not necessarily place her in the supplementary member list. If she should be both an administrator and a regular member, include her in both operations:

sudo gpasswd -A alice -M alice,john project
getent group project

Important: Treat -M as a replacement operation. Omitting an existing member can unintentionally revoke that user's group-based access.

Change a group password

Run gpasswd with only the group name to start an interactive password change:

sudo gpasswd project

The command prompts for the new password and normally asks for confirmation. Password data is stored in protected form rather than as readable plain text. A group password is separate from every individual user's password.

Group passwords are uncommon in modern administration. Explicit user membership, delegated administration, and carefully designed permissions are usually easier to audit. Use a group password only when you understand who can authenticate to the group and how that authentication fits the system's access model.

Inspect the group database

On systems using local files, /etc/group is the local group database. A typical entry has four colon-delimited fields:

project:x:2001:alice,john

Position	Field	Meaning	Example value
1	Group name	The name used to refer to the group.	`project`
2	Password field or placeholder	Often a placeholder such as `x`; protected group password data is commonly kept separately.	`x`
3	GID	The numeric group identifier used internally by Linux.	`2001`
4	Supplementary member list	A comma-separated list of users explicitly listed as supplementary members.	`alice,john`

The GID is the numeric group identifier. Linux permissions use numeric IDs internally even when commands display names.

Do not assume that /etc/group contains every effective group entry. Linux can obtain account and group data through NSS, or Name Service Switch. NSS determines whether lookups use local files, LDAP, another directory service, or additional configured sources. Use getent for an effective lookup:

getent group project

getent group GROUP queries configured name-service sources, while reading /etc/group directly only examines the local file.

Verify users and group membership

Command	What it checks	When to use it
`getent group GROUP`	Displays the effective group record and its listed supplementary members.	Confirm the group exists and inspect the result after a change.
`id USER`	Displays the user's UID, primary group, GID, and supplementary groups.	Check all group identities associated with an account.
`groups USER`	Displays group names associated with the user.	Quickly review group membership by name.

For example:

getent group project
id john
groups john

These commands help distinguish configured membership from active session membership. The group database can be updated while an already-running shell continues using the group list established at login. Run id inside the user's newly opened session when testing access.

Safe administration workflow

Confirm the target names: getent passwd USER checks the user, and getent group GROUP checks the group.
Review the existing group state before using a replacement operation such as -M.
Use sudo or an administrative shell where required.
Perform one change at a time.
Verify the database result with getent group GROUP.
Verify the account view with id USER or groups USER.
Have the user start a new login session before testing permissions.
Check resource ownership, permission bits, ACLs, and parent-directory traversal if access still fails.

Routine manual edits to /etc/group can create syntax errors, overwrite concurrent changes, or fail to update related protected group data. Prefer supported administration commands such as gpasswd.

Troubleshooting gpasswd changes

User or group does not exist

Check for spelling errors, missing accounts, and unavailable identity services:

getent passwd USER
getent group GROUP

Correct the name, create the required account or group through the appropriate administrative process, or resolve the configured identity-service problem.

The user was added but access still fails

First check whether the new membership is visible and whether the session is stale:

getent group GROUP
id USER
ls -ld PATH

Start a new login session. If the problem continues, inspect the resource's group ownership, group permission bits, ACLs, and permissions on parent directories. Membership alone does not guarantee access.

Members disappeared after using -M

This is expected when the command's list omitted existing members. Inspect the result and reapply -M with the complete intended list:

getent group GROUP
sudo gpasswd -M USER1,USER2,USER3 GROUP

Permission denied when running gpasswd

The caller may lack root privileges or may not be an administrator of the target group. Check the current identity and group record:

id
getent group GROUP

Use sudo when authorized, or ask a privileged administrator to perform the change.

/etc/group differs from getent output

The system may combine local files with LDAP or another NSS source. Compare the effective lookup with the local configuration:

getent group GROUP
grep '^group:' /etc/nsswitch.conf

Use getent for the effective result and account for the configured identity sources. A local file edit may not change directory-service membership.

Key exam notes

gpasswd -a USER GROUP adds a supplementary group membership; it does not change the user's primary group.
gpasswd -d USER GROUP removes a named supplementary membership.
gpasswd -A ADMIN1,ADMIN2 GROUP sets the group administrator list.
gpasswd -M USER1,USER2 GROUP replaces the supplementary member list rather than appending to it.
If an administrator should also be a regular member, include that username in the -M list.
gpasswd GROUP interactively changes the group password.
/etc/group uses the format group name, password field or placeholder, GID, and supplementary member list.
getent is generally safer than reading only /etc/group because it follows configured NSS sources.
A changed group membership may not appear in an existing shell until the user starts a new login session.

For a concise operational reference, see Administer Groups.