group¶

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin

Added in version 0.0.2.

You need further requirements to be able to use this module, see the Requirements section for details.

Synopsis¶

Manage presence of groups on a host.
For Windows targets, use the M(ansible.windows.win_group) module instead.

Requirements¶

The following Python packages are needed on the host that executes this module:

Parameters¶

Parameter	Defaults / Choices	Comments
force bool		Whether to delete a group even if it is the primary group of a user. Only applicable on platforms which implement a C(--force) flag on the group deletion command. Version Added: 2.15
gid int		Optional I(GID) to set for the group.
gid_max int		Sets the GID_MAX value for group creation. Overwrites /etc/login.defs default value. Currently supported on Linux. Does nothing when used with other platforms. Requires O(local) is omitted or V(False). Version Added: 2.18
gid_min int		Sets the GID_MIN value for group creation. Overwrites /etc/login.defs default value. Currently supported on Linux. Does nothing when used with other platforms. Requires O(local) is omitted or V(False). Version Added: 2.18
local bool		Forces the use of "local" command alternatives on platforms that implement it. This is useful in environments that use centralized authentication when you want to manipulate the local groups. (for example, it uses C(lgroupadd) instead of C(groupadd)). This requires that these commands exist on the targeted host, otherwise it will be a fatal error. Version Added: 2.6
name str required		Name of the group to manage.
non_unique bool		This option allows to change the group ID to a non-unique value. Requires O(gid). Not supported on macOS or BusyBox distributions. Version Added: 2.8
state str	Default: present Choices: absent, present	Whether the group should be present or not on the remote host.
system bool		If V(yes), indicates that the group created is a system group.

Examples¶

- name: Ensure group "somegroup" exists
  ansible.builtin.group:
    name: somegroup
    state: present

- name: Ensure group "docker" exists with correct gid
  ansible.builtin.group:
    name: docker
    state: present
    gid: 1750

Return Values¶

Key	Data Type	Description	Returned
gid	int	Group ID of the group.	When O(state) is C(present)
name	str	Group name.	always
state	str	Whether the group is present or not.	always
system	bool	Whether the group is a system group or not.	When O(state) is C(present)

Authors¶

Stephen Fromm (@sfromm)