group¶

group makes sure a local group exists, with the gid you give, or that it does not exist. It reads the group with getent group and changes it with groupadd, groupmod and groupdel only when something differs. Members are set on the user side, with the user resource's groups:.

New in 0.2.0

Minimal example¶

examples/resources/group/minimal.rb

group "app"

Options¶

Option	Type	Default	Description
`gid`	Integer	unmanaged	Numeric group ID. Changing it on an existing group runs `groupmod -g`; files keep their old gid.
`system`	`true` or `false`	`false`	Create a system group (`groupadd -r`), with a gid from the system range. Only used when the group is created.
`state`	`:present` or `:absent`	`:present`	`:absent` deletes the group with `groupdel`.
`notifies`	`[:action, "type[name]"]`, optionally with `:immediately`, or a list of them	none	Actions to run on other resources when this one changes. See Notifications.
`subscribes`	`[:action, "type[name]"]`, optionally with `:immediately`, or a list of them	none	Actions to run on this resource when another one changes.
`tags`	Symbol, String, or an Array of them	none	Tags for running part of a recipe with `--tags` and `--skip-tags`. See Tags.

On Alpine without the shadow package, sadame uses BusyBox's addgroup and delgroup instead. BusyBox cannot change a gid; declare package "shadow" first if you need to.

Scenarios¶

examples/resources/group/recipe.rb

# The same gid on every server, so files on shared storage or in backups
# keep their group.
group "app", gid: 1500

# A system group: its gid comes from the system range, for service accounts.
group "metrics", system: true

# A group that must not exist. Nothing happens when it is already gone.
group "oldteam", state: :absent

Groups on a new server¶

$ sudo sadame plan examples/resources/group
sadame 0.5.1 plan on local (Debian GNU/Linux 12 (bookworm))

+ group[app]
    state: absent -> present
    gid: 1500

+ group[metrics]
    state: absent -> present

Plan: 2 to create, 0 to update, 0 to remove, 0 to run, 1 unchanged.

$ sudo sadame apply examples/resources/group
sadame 0.5.1 apply on local (Debian GNU/Linux 12 (bookworm))

changed    group[app]
           state: absent -> present
           gid: 1500
changed    group[metrics]
           state: absent -> present
unchanged  group[oldteam]

Summary
  changed      2  group[app]
                  group[metrics]
  unchanged    1
  failed       0
  skipped      0
  notified     0

Finished in 0.19s.

$ getent group app metrics
app:x:1500:
metrics:x:999:

group[oldteam] is unchanged because it does not exist, which is what state: :absent asks for.

A group and its members¶

Declare the group before the users that join it; the user resource needs its groups to exist:

group "app", gid: 1500
user "deploy", groups: ["app"]

Common mistakes¶

A group that a user is still in. groupdel refuses to delete a group that is some user's primary group. Remove or change the user first.
A gid that is taken. groupadd -g and groupmod -g fail when another group already has that gid; the error names it.
Expecting a gid change to fix file ownership. Files store the number, so after a change they show the old gid. Fix them with chown or a directory resource's group:.