ansible-freeipa/README-group.md

Group module
============

Description
-----------

The group module allows to ensure presence and absence of groups and members of groups.

The group module is as compatible as possible to the Ansible upstream `ipa_group` module, but additionally offers to add users to a group and also to remove users from a group.


Notes
-----

* Ensuring presence (adding) of several groups with mixed types (`external`, `nonposix` and `posix`) requires a fix in FreeIPA. The module implements a workaround to automatically use `client` context if the fix is not present in the target node FreeIPA and if more than one group is provided to the task using the `groups` parameter. If `ipaapi_context` is forced to be `server`, the module will fail in this case.
* Using `externalmember` or `idoverrideuser` is only supported with `ipaapi_context: server`. With 'client' context, module execution will fail.


Features
--------
* Group management


Supported FreeIPA Versions
--------------------------

FreeIPA versions 4.4.0 and up are supported by the ipagroup module.

Some variables are only supported on newer versions of FreeIPA. Check `Variables` section for details.


Requirements
------------

**Controller**
* Ansible version: 2.14+

**Node**
* Supported FreeIPA version (see above)


Usage
=====

Example inventory file

```ini
[ipaserver]
ipaserver.test.local
```


Example playbook to add groups:

```yaml
---
- name: Playbook to handle groups
  hosts: ipaserver
  become: true

  tasks:
  # Create group ops with gid 1234
  - ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: ops
      gidnumber: 1234

  # Create group sysops
  - ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: sysops
      user:
      - pinky

  # Create group appops
  - ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: appops
```

These three `ipagroup` module calls can be combined into one with the `groups` variable:

```yaml
---
- name: Playbook to handle groups
  hosts: ipaserver

  tasks:
  - name: Ensure groups ops, sysops and appops are present
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      groups:
      - name: ops
        gidnumber: 1234
      - name: sysops
        user:
        - pinky
      - name: appops
```

You can also alternatively use a json file containing the groups, here `groups_present.json`:

```json
{
  "groups": [
    {
      "name": "group1",
      "description": "description group1"
    },
    {
      "name": "group2",
      "description": "description group2"
    }
  ]
}
```

And ensure the presence of the groups with this example playbook:

```yaml
---
- name: Tests
  hosts: ipaserver
  gather_facts: false

  tasks:
  - name: Include groups_present.json
    include_vars:
      file: groups_present.json

  - name: Groups present
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      groups: "{{ groups }}"
```

Example playbook to rename a group:

```yaml
---
- name: Playbook to rename a single group
  hosts: ipaserver
  become: false
  gather_facts: false

  tasks:
  - name: Rename group appops to webops
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: appops
      rename: webops
      state: renamed
```

Several groups can also be renamed with a single task, as in the example playbook:

```yaml
---
- name: Playbook to rename multiple groups
  hosts: ipaserver
  become: false
  gather_facts: false

  tasks:
  - name: Rename group1 to newgroup1 and group2 to newgroup2
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      groups:
      - name: group1
        rename: newgroup1
      - name: group2
        rename: newgroup2
      state: renamed
```

Example playbook to add users to a group:

```yaml
---
- name: Playbook to handle groups
  hosts: ipaserver
  become: true

  tasks:
  # Add user member brain to group sysops
  - ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: sysops
      action: member
      user:
      - brain
```
`action` controls if a the group or member will be handled. To add or remove members, set `action` to `member`.


Example playbook to add group members to a group:

```yaml
---
- name: Playbook to handle groups
  hosts: ipaserver
  become: true

  tasks:
  # Add group members sysops and appops to group ops
  - ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: ops
      group:
      - sysops
      - appops
```

Example playbook to add members from a trusted realm to an external group:

```yaml
---
- name: Playbook to handle groups.
  hosts: ipaserver

  tasks:
  - name: Create an external group and add members from a trust to it.
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: extgroup
      external: yes
      externalmember:
      - WINIPA\\Web Users
      - WINIPA\\Developers
```

Example playbook to add nonposix and external groups:

```yaml
---
- name: Playbook to add nonposix and external groups
  hosts: ipaserver

  tasks:
  - name: Add nonposix group sysops and external group appops
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      groups:
      - name: sysops
        nonposix: true
      - name: appops
        external: true
```

Example playbook to remove groups:

```yaml
---
- name: Playbook to handle groups
  hosts: ipaserver
  become: true

  tasks:
  # Remove groups sysops, appops and ops
  - ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: sysops,appops,ops
      state: absent
```

Example playbook to ensure groups are absent:

```yaml
---
- name: Playbook to handle groups
  hosts: ipaserver

  tasks:
  - name: Ensure groups ops and sysops are absent
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      groups:
      - name: ops
      - name: sysops
      state: absent
```


Example playbook to query a group and print the base fields:

```yaml
---
- name: Playbook to query groups
  hosts: ipaserver
  become: true

  tasks:
  - name: Query group ops
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: ops
      state: query
    register: result

  - name: Print group info
    debug:
      var: result.group
```


Example playbook to query specific fields of a group:

```yaml
---
- name: Playbook to query groups
  hosts: ipaserver
  become: true

  tasks:
  - name: Query description and members of group ops
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: ops
      query_param:
      - description
      - gid
      - user
      state: query
    register: result

  - name: Print group info
    debug:
      var: result.group
```


Example playbook to query all fields of a group:

```yaml
---
- name: Playbook to query groups
  hosts: ipaserver
  become: true

  tasks:
  - name: Query all fields of group ops
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      name: ops
      query_param: ALL
      state: query
    register: result

  - name: Print group info
    debug:
      var: result.group
```


Example playbook to query only the names of all groups:

```yaml
---
- name: Playbook to query groups
  hosts: ipaserver
  become: true

  tasks:
  - name: Query all group names
    ipagroup:
      ipaadmin_password: SomeADMINpassword
      query_param: PKEY_ONLY
      state: query
    register: result

  - name: Print group names
    debug:
      var: result.group.groups
```


Variables
=========

Variable | Description | Required
-------- | ----------- | --------
`ipaadmin_principal` | The admin principal is a string and defaults to `admin` | no
`ipaadmin_password` | The admin password is a string and is required if there is no admin ticket available on the node | no
`ipaapi_context` | The context in which the module will execute. Executing in a server context is preferred. If not provided context will be determined by the execution environment. Valid values are `server` and `client`. | no
`ipaapi_ldap_cache` | Use LDAP cache for IPA connection. The bool setting defaults to <br/>. (bool) | no
`name` \| `cn` | The list of group name strings. | no
`groups` | The list of group dicts. Each `groups` dict entry can contain group variables.<br>There is one required option in the `groups` dict:| no
&nbsp; | `name` - The group name string of the entry. | yes
`description` | The group description string. | no
`gid` \| `gidnumber` | The GID integer. | no
`posix` | Create a non-POSIX group or change a non-POSIX to a posix group. `nonposix`, `posix` and `external` are mutually exclusive. (bool) | no
`nonposix` | Create as a non-POSIX group. `nonposix`, `posix` and `external` are mutually exclusive. (bool) | no
`external` | Allow adding external non-IPA members from trusted domains. `nonposix`, `posix` and `external` are mutually exclusive. (bool) | no
`nomembers` | Suppress processing of membership attributes. (bool) | no
`user` | List of user name strings assigned to this group. | no
`group` | List of group name strings assigned to this group. | no
`service` | List of service name strings assigned to this group. Only usable with IPA versions 4.7 and up. | no
`membermanager_user` | List of member manager users assigned to this group. Only usable with IPA versions 4.8.4 and up. | no
`membermanager_group` | List of member manager groups assigned to this group. Only usable with IPA versions 4.8.4 and up. | no
`externalmember` \| `ipaexternalmember`  \| `external_member`| List of members of a trusted domain in DOM\\name or name@domain form. Requires "server" context. | no
`idoverrideuser` | List of user ID overrides to manage. Only usable with IPA versions 4.8.7 and up. Requires "server" context. | no
`rename` \| `new_name` | Rename the group object to the new name string. Only usable with `state: renamed`. | no
`action` | Work on group or member level. It can be one of `member` or `group` and defaults to `group`. | no
`query_param` | The fields to query with `state: query`. Can be `ALL`, `BASE`, `PKEY_ONLY` or a list of specific field names. Only usable with `state: query`. | no
`state` | The state to ensure. It can be one of `present`, `absent`, `renamed` or `query`, default: `present`. | yes


Authors
=======

- Thomas Woerner
- Rafael Jeffman