group
The group.* family of state modules.
| Module | Summary |
|---|---|
group.absent | Ensure a group does not exist on the system. |
group.present | Ensure a group exists with the specified attributes and membership. |
All states also accept the full set of requisite parameters and Salt-parity state attributes — see Dependencies & Requisites.
Parameter Types
StringList
A list of strings. Accepts a single string (a one-element list), a list of strings, or a mixed scalar list whose elements are rendered to strings. A nested list or map element is rejected rather than dropped.
group.absent
Ensure a group does not exist on the system.
Source: pkg/state/modules/group/group_absent.go
group.absent ensures the named group is removed. The group name defaults to the state ID.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | No | State ID | group name to remove; defaults to the state ID |
Effects
Check
Looks up the group and reports a change only when it exists; an already-absent group needs no change.
Apply
Re-verifies existence (a self-contained flow: a watch-forced Apply bypasses Check, and deleting a nonexistent group would fail), then deletes the group through the group provider. An already-absent group is a clean no-op. Reports the group in its details.
Revert
Cannot restore a deleted group (its GID and membership are not recorded), so Revert is an explicit no-op.
Examples
Remove a group
The group name defaults to the state ID.
oldgroup:
group.absent: []Remove a group after removing its users
require orders the user removals ahead of the group deletion.
decommission-team:
group.absent:
- name: oldteam
- require:
- "user.absent:alice"
- "user.absent:bob"Remove a group ad hoc
The bare positional argument is the group name.
zester '*' group.absent tempgroupSee Also
group.present
Ensure a group exists with the specified attributes and membership.
Source: pkg/state/modules/group/group_present.go
group.present ensures the named group exists and converges its numeric GID and membership. The group name defaults to the state ID. gid is a numeric group ID, compared and set only when non-zero. members declares an EXACT membership (extra members are removed, missing members added), while addusers and delusers adjust membership additively without disturbing other members. system selects a low-GID system group and is honored only at creation time.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | No | State ID | group name; defaults to the state ID |
gid | int | No | (none) | numeric group ID; only compared and set when non-zero (0 auto-assigns) |
system | bool | No | (none) | create a system group (low GID range); used only during creation; a boolean that also accepts the integers 1 (true) and 0 (false) |
members | StringList | No | (none) | exact membership list — extra members are removed and missing members are added |
addusers | StringList | No | (none) | users to add without affecting other existing members |
delusers | StringList | No | (none) | users to remove without affecting other existing members |
Effects
Check
Looks up the group. Reports a change when it does not exist; otherwise it compares, in order: gid (only when non-zero); the exact members list (when declared); every addusers entry (a listed user that is not a member is drift); and every delusers entry (a listed user that IS a member is drift).
Apply
Creates the group with the declared GID and system flag when it does not exist (adding members/addusers afterward and recording the creation for revert); a create that races another state at the same DAG level re-looks-up and falls through to the modify path. For an existing group it builds a modify set from only the drifted GID and membership (arming the revert memo), and a fully converged group is a clean no-op that leaves the memo unarmed. Reports the group and the action (created/modified) in its details.
Revert
Undoes only what this run's Apply recorded. A group Apply created is deleted; a group Apply modified is restored by diffing the current group against the memoized original and reverting only the still-drifted GID AND membership (so an added member is removed and a removed member restored). A fresh instance (a standalone revert) recorded nothing and is an explicit clean no-op.
Examples
Create a system group
The group name defaults to the state ID; system allocates a low GID.
docker:
group.present:
- system: trueGroup with an exact membership list
members declares exact membership — users not listed are removed.
webadmins:
group.present:
- gid: 3000
- members:
- alice
- bob
- charlieAdd and remove members without disturbing others
addusers/delusers adjust membership additively; require orders user creation first.
developers:
group.present:
- addusers:
- newdev
- delusers:
- formerdev
- require:
- "user.present:newdev"Create a group ad hoc
The bare positional argument is the group name; key=value pairs set attributes.
zester 'db*' group.present dbadmin gid=2000