Linux online course

Administer Linux Groups with gpasswd

Learn how to use gpasswd to add and remove Linux group members, assign group administrators, manage group passwords, and verify group configuration safely.

Linux groups organize users into named collections. File ownership, device access, and other permissions can refer to a group instead of listing individual users. For example, a project directory can be owned by the project group so that every authorized project member can access it.

Every user normally has a primary group, the default group associated with the account. A user can also have one or more supplementary groups, which provide additional access. The gpasswd command is commonly used to administer supplementary membership, group administrators, and group passwords for an existing local group. It does not create a group; create groups separately with an approved group-management command such as groupadd.

What gpasswd Does

gpasswd administers an existing group. Its general command pattern is:

gpasswd [options] group

Most membership and group-security changes require root privileges or appropriate administrative authorization. A typical administrative command therefore begins with sudo:

sudo gpasswd -a USER GROUP

Before changing anything, confirm that the account and group exist. The group must already have been created.

getent passwd USER
getent group GROUP

Common gpasswd Operations

Option — Purpose — Syntax pattern — Important behavior

-a user group — Add a user — gpasswd -a user group — Appends the user to the supplementary member list.

-d user group — Remove a user — gpasswd -d user group — Removes the user from the supplementary member list; it does not normally change the primary group.

-A admin-list group — Set administrators — gpasswd -A user1,user2 group — Replaces the administrator list with the comma-separated names supplied.

-M member-list group — Set regular members — gpasswd -M user1,user2 group — Replaces the complete supplementary-member list rather than appending to it.

gpasswd group — Set or change the group password — The command prompts interactively for the password.

Add a User to a Group

Use -a with a username and an existing group. The option means “add,” and it is the safer choice for adding one user because it does not replace other members.

sudo gpasswd -a john project

This adds john as a supplementary member of project. On many Linux systems, successful execution prints a confirmation similar to:

Adding user john to group project

john must be a valid user, and project must already exist. The user's current login session usually does not automatically acquire the new supplementary group. Have the user log out and start a new login session, or otherwise start a new session using the system's approved procedure.

Remove a User from a Group

Use -d to delete a user from an existing group's supplementary-member list:

sudo gpasswd -d john project

Removing this entry does not necessarily alter john's primary group. If project is the user's primary group, change the primary group separately with an appropriate account-management command rather than assuming gpasswd -d performs that change.

Verify the resulting configuration with:

getent group project
id john
groups john

Assign Group Administrators

A group administrator is a user designated to administer a particular group's members and group password. Use -A followed by a comma-separated administrator list:

sudo gpasswd -A maria project

To assign multiple administrators, separate their usernames with commas and do not insert spaces:

sudo gpasswd -A maria,lee project

This operation sets the administrator list. Existing administrators should be included in the new list if they are meant to remain administrators.

Administrative status and ordinary membership are separate settings. A group administrator can manage membership and the group password without necessarily appearing in the normal member list. Conversely, an ordinary member can use group-owned resources when permissions allow, but does not automatically gain authority to administer the group.

Capability — Group administrator — Regular group member

Use group-owned resources when permissions permit — Yes, if also a member or otherwise granted access — Yes, when listed or otherwise granted access.

Add or remove members — Yes, for the group they administer — No, merely being a member is insufficient.

Change the group password — Yes, for the group they administer — No, unless the user has separate administrative authority.

Must appear in the normal member list — No — Yes, to be a listed regular member.

Set the Group Member List

Use -M to explicitly replace the regular supplementary-member list:

sudo gpasswd -M john,maria,lee project

After this command, the listed users are the group's regular supplementary members. Existing members not included in the comma-separated list are removed. Therefore, -M is a replacement operation, not an append operation.

Review the current list before using -M, and provide the complete intended list:

getent group project
sudo gpasswd -M john,maria,lee project

If an administrator should also have ordinary group membership, include that user in both lists. For example:

sudo gpasswd -A maria -M john,maria project

Here, maria is a group administrator and is also listed as a regular member. The two lists remain logically independent.

Manage a Group Password

Run gpasswd with only the group name to set or change its group password interactively:

sudo gpasswd project

The command prompts for the password instead of putting it directly in the command line, which helps prevent the value from appearing in shell history. A group password can permit a user to join a group through newgrp when that workflow is supported and appropriate:

newgrp project

newgrp starts a shell with a changed current group and may request the group password. A group password does not permanently add the user to the group's member list, and it does not automatically change file permissions.

Group passwords are less common in modern administration than explicitly managing membership with administrators, account-management tools, or sudo. Use them only when they fit the system's security policy. Passwords are stored as protected hashes in group-security data, not as readable text.

Inspect Group Configuration

On systems using local group files, /etc/group contains records with four colon-separated fields:

File — Field — Meaning — Example value

/etc/group — group name — The name used in commands and permission checks — project

/etc/group — password placeholder — A placeholder such as x; protected password data is normally elsewhere — x

/etc/group — GID — The numeric group identifier — 1005

/etc/group — member list — Comma-separated supplementary members — john,maria

/etc/gshadow — administrator list — Protected list of group administrators — maria,lee

/etc/gshadow — protected password field — Protected group-password hash or related marker — A non-readable hash value

A local record can be inspected with:

grep '^project:' /etc/group

However, prefer getent for normal verification:

getent group project

getent asks the system's configured name-service sources for the group. This is useful when group data may come from local files, LDAP, Active Directory integration, or another directory service rather than only from /etc/group.

Use id to see a user's numeric identity, primary group, and supplementary groups:

id john

Use groups for a shorter group-oriented view:

groups john

/etc/gshadow is protected because it contains group password hashes and administrator information. Do not expose or casually copy its contents.

Safe Administration Practices

• Verify both names before making a change with getent passwd USER and getent group GROUP.
• Use supported management commands instead of manually editing /etc/group or /etc/gshadow. Manual edits can introduce malformed records, conflicting changes, or incorrect permissions.
• Treat -M as destructive to the current listed-member set. Include every intended member.
• Remember that a newly added supplementary group normally becomes effective after a new login session.
• Test the actual permission with the affected account. Membership alone does not guarantee access if file mode bits, ACLs, or mandatory access-control policy deny it.
• Keep group administrators and regular members conceptually separate, and add an administrator to the regular list only when that person also needs ordinary group access.

Troubleshooting

User or group does not exist

If gpasswd reports that an account or group does not exist, check spelling and name-service resolution:

getent passwd USER
getent group GROUP

The account or group may not have been created, or a required directory service may be unavailable. Use the exact names returned by the configured identity source and follow the approved process for creating missing objects.

New membership does not grant access

First check whether the user's session has refreshed:

id USER
getent group GROUP

Have the user log out and start a new session if the membership is not present in the effective identity. Then inspect the resource:

ls -l /path/to/resource

Also consider ACLs and mandatory access controls. Correct group membership cannot override a separate policy that denies access.

Members disappeared after using -M

This is expected when omitted members were not included in the replacement list. Inspect the current record and reissue -M with the complete intended list:

getent group project
sudo gpasswd -M john,maria,lee project

A group administrator cannot perform the expected action

Check that the user was included in the administrator list with -A. Administrative status is distinct from ordinary membership, and the command may also depend on the system's authorization and identity configuration. If the person needs resource access as well as administrative capability, include the person in the regular member list and refresh the session.

Group password behavior is unexpected

A group password is not the same as permanent membership. It is relevant to workflows using newgrp; it does not automatically alter a user's account groups or file permissions. Use gpasswd -a or -M when the goal is managed, persistent membership.

Practical Administration Sequence

1. Confirm the user and group with getent.
2. Choose an append, remove, administrator, replacement, or password operation.
3. Run the command with sudo or an equivalent authorized identity.
4. Verify the resolved record with getent group GROUP.
5. Verify the user's effective groups with id USER or groups USER.
6. Start a new user session when required, then test access to the protected resource.

Exam-Relevant Notes

• gpasswd administers an existing group; it does not create one.
• -a adds a user without replacing other members.
• -d removes a supplementary-group entry and normally does not change the primary group.
• -A sets the comma-separated group administrator list.
• -M replaces the complete comma-separated regular-member list.
• Group administrator status and regular membership are separate settings.
• getent is preferable to assuming that local files are the only source of group information.
• New supplementary-group membership normally requires a new login session to become effective.

For broader Linux administration topics, see Linux administration and command-line lessons.