/ home / ansible / ansible.builtin / v2.16.5 / module / group

ansible.builtin.group (v2.16.5) — module

Add or remove groups

| "added in version" 0.0.2 of ansible.builtin"

Authors: Stephen Fromm (@sfromm)

Install Ansible via `pip`

Install with pip install ansible-core==2.16.5

Description

Manage presence of groups on a host.

For Windows targets, use the M(ansible.windows.win_group) module instead.

Requirements

groupadd
groupdel
groupmod

Usage examples

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

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

Inputs

    
gid:
    description:
    - Optional I(GID) to set for the group.
    type: int

name:
    description:
    - Name of the group to manage.
    required: true
    type: str

force:
    default: false
    description:
    - Whether to delete a group even if it is the primary group of a user.
    - Only applicable on platforms which implement a --force flag on the group deletion
      command.
    type: bool
    version_added: '2.15'
    version_added_collection: ansible.builtin

local:
    default: false
    description:
    - 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.
    type: bool
    version_added: '2.6'
    version_added_collection: ansible.builtin

state:
    choices:
    - absent
    - present
    default: present
    description:
    - Whether the group should be present or not on the remote host.
    type: str

system:
    default: false
    description:
    - If V(yes), indicates that the group created is a system group.
    type: bool

non_unique:
    default: false
    description:
    - This option allows to change the group ID to a non-unique value. Requires O(gid).
    - Not supported on macOS or BusyBox distributions.
    type: bool
    version_added: '2.8'
    version_added_collection: ansible.builtin

Outputs

gid:
  description: Group ID of the group.
  returned: When O(state) is C(present)
  sample: 1001
  type: int
name:
  description: Group name.
  returned: always
  sample: users
  type: str
state:
  description: Whether the group is present or not.
  returned: always
  sample: absent
  type: str
system:
  description: Whether the group is a system group or not.
  returned: When O(state) is C(present)
  sample: false
  type: bool

Install Ansible via pip