> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://rivet.chrisboulton.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://rivet.chrisboulton.com/_mcp/server.

# Group

> Manage local group existence and GIDs; order account removal deliberately.

`group` manages local Linux groups. Names default to the label, must start with an ASCII letter or underscore, can contain letters, digits, underscores, and hyphens, and are at most 32 bytes. GIDs are integers from 0 to 4294967294.

```hcl
group "app" {
  system = true
}
```

## Parameters

| Parameter | Default     | Behavior                                                                                    |
| --------- | ----------- | ------------------------------------------------------------------------------------------- |
| `name`    | label       | Local group name.                                                                           |
| `ensure`  | `"present"` | `"present"` or `"absent"`.                                                                  |
| `gid`     | unmanaged   | Explicit GID allocation or change; occupied IDs fail. Files retain their numeric ownership. |
| `system`  | `false`     | Creation-time ID allocation policy only.                                                    |

Group passwords and duplicate names or IDs aren't supported. Only local groups are managed; a name or ID that comes from a directory service such as LDAP is refused. Deleting a group or changing its GID fails, listing the affected users, while any local user still has it as their primary group.

A present user's primary or supplementary group creates an ordering edge when the group is managed in the same catalog, including literal names and explicit GIDs. References such as `group.app.name` retain dependency provenance. Present users cannot request a managed absent group. Omitted allocated IDs cannot be read at compile time; reference the name when the host allocates an ID.

When removing a user and its group, order them yourself; Rivet doesn't reverse dependencies for absent resources:

```hcl
user "app" {
  ensure = "absent"
  meta { before = [group.app] }
}

group "app" {
  ensure = "absent"
}
```

Changes use the shadow-utils commands, which lock the account files, with a 60-second timeout. Each change is journalled first and verified afterwards; an interrupted change is converged again on the next run.

Capability: `group.shadow.v1`. See [user](/resources/user) for the corresponding primary-group and home constraints.