group
group manages one local group on the node: that it exists, its ID, the
accounts that have it as a supplementary group, or its removal. The group
module runs the node's native group tools.
Use user for an account, including its primary group and, from
the account's side, its supplementary groups. Configure each supplementary
membership through only a user task's supplementary_groups or a group
task's supplementary_members.
Inputs
name(string; required)system(boolean; optional): affects ID allocation on creation onlygid(integer; optional): used on creation, checked on an existing group; never renumberedsupplementary_members(list of strings; optional): accounts that have the group as a supplementary group; they must exist; needs supplementary_members_not_listed; accounts with the group as their primary group are not touchedsupplementary_members_not_listed(removeorkeep; optional): required with supplementary_members; remove makes supplementary_members the whole set, and supplementary_members: [] removes them all; keep adds the listed accounts and leaves other members alonestate(presentorabsent; defaultpresent): absent accepts only name and state
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangevalue.group_createdvalue.members_addedvalue.members_removed
What a dryrun reports
Supported; inspects only and lists the members that would be added or removed.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Create a group with a fixed ID
- group:
name: app
gid: 1200
gid takes an integer or a whole typed reference: a single {{ ... }}
expression that supplies an integer. It chooses the value for a new group and
checks the value of an existing group. Omit it to keep the node's native
allocation for a new group and the existing value of a current group.
Make a list of accounts the whole membership of a group
- group:
name: deploy
supplementary_members: [barbara, ci]
supplementary_members_not_listed: remove
supplementary_members lists the accounts that have the group as a
supplementary group. The listed accounts must exist.
supplementary_members_not_listed is required when you set
supplementary_members.
With supplementary_members_not_listed: remove, the list contains every
account that should have the group as a supplementary group. So deleting a
name from supplementary_members removes the account's supplementary
membership on the next run. With supplementary_members_not_listed: keep,
the task adds listed accounts and keeps unlisted supplementary members.
Remove a group
- group:
name: deploy
state: absent
How it works
systemaffects only which ID the node allocates when the group is created.- A
gidmismatch or a collision with another group fails before the group changes. MMX does not renumber groups. - An account whose primary group is the group named by
namekeeps the primary membership withsupplementary_members_not_listed: removeorsupplementary_members_not_listed: keep.supplementary_membersandsupplementary_members_not_listeddo not change the account's primary group membership.supplementary_members: []withsupplementary_members_not_listed: removeremoves every supplementary member. supplementary_members_not_listedfollows the rule for a task that owns a list.state: absentaccepts onlynameandstate. Thegrouptask removes the group with the node's native tools, without force. A missing group is unchanged.- A run and a dryrun list what changed, or would change, in the result's
value:group_created,members_added, andmembers_removed. A run that fails lists only what it changed before the failure, so a node task inon_failurecan read what happened. - Group changes do not request a service restart or reload.
Errors and what they mean
- An ID mismatch or collision. The task fails before the group changes.
account ci does not exist yet. A listed member does not exist. Create the account with ausertask before thegrouptask.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45.
The base suite covers this module (account_units.py, directory_resources.py) and runs on every tested distribution.
The suite account_units.py covers group members. The group fields of
this page are tested on Debian 12 and 13 and Ubuntu 24.04 and 26.04 (validation
record).
Why it works this way
- Membership names say supplementary. An account's primary group stays separate, so the task cannot silently remove its primary membership.
This page is docs/reference/modules/group.md in the MMX repository.