Service module

==============

Description

-----------

The service module allows to ensure presence and absence of services.

Features

--------

* Service management

Supported FreeIPA Versions

--------------------------

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

Option `skip_host_check` requires FreeIPA version 4.7.0 or later.

Requirements

------------

**Controller**

* Ansible version: 2.8+

**Node**

* Supported FReeIPA version (see above)

Usage

=====

Example inventory file

```ini

[ipaserver]

ipaserver.test.local

```

Example playbook to make sure service is present:

```yaml

---

- name: Playbook to manage IPA service.

  hosts: ipaserver

  become: true

  gather_facts: false

  tasks:

  # Ensure service is present

  - ipaservice:

      ipaadmin_password: SomeADMINpassword

      name: HTTP/www.example.com

      certificate:

        - MIIC/zCCAeegAwIBAgIUMNHIbn+hhrOVew/2WbkteisV29QwDQYJKoZIhvcNAQELBQAw

        DzENMAsGA1UEAwwEdGVzdDAeFw0yMDAyMDQxNDQxMDhaFw0zMDAyMDExNDQxMDhaMA8xDT

        ALBgNVBAMMBHRlc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC+XVVGFYpH

        VkcDfVnNInE1Y/pFciegdzqTjMwUWlRL4Zt3u96GhaMLRbtk+OfEkzLUAhWBOwEraELJzM

        LJOMvjYF3C+TiGO7dStFLikZmccuSsSIXjnzIPwBXa8KvgRVRyGLoVvGbLJvmjfMXp0nIT

        oTx/i74KF9S++WEes9H5ErJ99CDhLKFgq0amnvsgparYXhypHaRLnikn0vQINt55YoEd1s

        4KrvEcD2VdZkIMPbLRu2zFvMprF3cjQQG4LT9ggfEXNIPZ1nQWAnAsu7OJEkNF+E4Mkmpc

        xj9aGUVt5bsq1D+Tzj3GsidSX0nSNcZ2JltXRnL/5v63g5cZyE+nAgMBAAGjUzBRMB0GA1

        UdDgQWBBRV0j7JYukuH/r/t9+QeNlRLXDlEDAfBgNVHSMEGDAWgBRV0j7JYukuH/r/t9+Q

        eNlRLXDlEDAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQCgVy1+1kNwHs

        5y1Zp0WjMWGCJC6/zw7FDG4OW5r2GJiCXZYdJ0UonY9ZtoVLJPrp2/DAv1m5DtnDhBYqic

        uPgLzEkOS1KdTi20Otm/J4yxLLrZC5W4x0XOeSVPXOJuQWfwQ5pPvKkn6WxYUYkGwIt1OH

        2nSMngkbami3CbSmKZOCpgQIiSlQeDJ8oGjWFMLDymYSHoVOIXHwNoooyEiaio3693l6no

        obyGv49zyCVLVR1DC7i6RJ186ql0av+D4vPoiF5mX7+sKC2E8xEj9uKQ5GTWRh59VnRBVC

        /SiMJ/H78tJnBAvoBwXxSEvj8Z3Kjm/BQqZfv4IBsA5yqV7MVq

      pac_type: PAD

      auth_ind: otp

      requires_pre_auth: false

      ok_as_delegate: false

      ok_to_auth_as_delegate: false

      skip-host-check: true

      force: true

```

Example playbook to make sure service is absent:

```yaml

---

- name: Playbook to manage IPA service.

  hosts: ipaserver

  become: true

  gather_facts: false

  tasks:

  # Ensure service is present

  - ipaservice:

      ipaadmin_password: SomeADMINpassword

      name: HTTP/www.example.com

      state: absent

```

Example playbook to make sure service is disabled:

```yaml

---

- name: Playbook to manage IPA service.

  hosts: ipaserver

  become: true

  gather_facts: false

  tasks:

  # Ensure service is present

  - ipaservice:

      ipaadmin_password: SomeADMINpassword

      name: HTTP/www.example.com

      state: disabled

```

Example playbook to add a service even if the host object does not exist, but only if it does have a DNS entry:

```yaml

---

- name: Playbook to manage IPA service.

  hosts: ipaserver

  become: true

  gather_facts: false

  tasks:

  # Ensure service is present

  - ipaservice:

      ipaadmin_password: SomeADMINpassword

      name: HTTP/www.example.com

      skip_host_check: true

      force: false

```

Example playbook to add a service if it does have a DNS entry, but host object exits:

```yaml

---

- name: Playbook to manage IPA service.

  hosts: ipaserver

  become: true

  gather_facts: false

  tasks:

  # Ensure service is present

  - ipaservice:

      ipaadmin_password: SomeADMINpassword

      name: HTTP/www.example.com

      skip_host_check: false

      force: true

```

Example playbook to ensure service has a certificate:

```yaml

---

- name: Playbook to manage IPA service.

  hosts: ipaserver

  become: true

  gather_facts: false

  tasks:

  # Ensure service member certificate is present.

  - ipaservice:

      ipaadmin_password: SomeADMINpassword

      name: HTTP/www.example.com

      certificate:

        - MIIC/zCCAeegAwIBAgIUMNHIbn+hhrOVew/2WbkteisV29QwDQYJKoZIhvcNAQELBQAw

        DzENMAsGA1UEAwwEdGVzdDAeFw0yMDAyMDQxNDQxMDhaFw0zMDAyMDExNDQxMDhaMA8xDT

        ALBgNVBAMMBHRlc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC+XVVGFYpH

        VkcDfVnNInE1Y/pFciegdzqTjMwUWlRL4Zt3u96GhaMLRbtk+OfEkzLUAhWBOwEraELJzM

        LJOMvjYF3C+TiGO7dStFLikZmccuSsSIXjnzIPwBXa8KvgRVRyGLoVvGbLJvmjfMXp0nIT

        oTx/i74KF9S++WEes9H5ErJ99CDhLKFgq0amnvsgparYXhypHaRLnikn0vQINt55YoEd1s

        4KrvEcD2VdZkIMPbLRu2zFvMprF3cjQQG4LT9ggfEXNIPZ1nQWAnAsu7OJEkNF+E4Mkmpc

        xj9aGUVt5bsq1D+Tzj3GsidSX0nSNcZ2JltXRnL/5v63g5cZyE+nAgMBAAGjUzBRMB0GA1

        UdDgQWBBRV0j7JYukuH/r/t9+QeNlRLXDlEDAfBgNVHSMEGDAWgBRV0j7JYukuH/r/t9+Q

        eNlRLXDlEDAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQCgVy1+1kNwHs

        5y1Zp0WjMWGCJC6/zw7FDG4OW5r2GJiCXZYdJ0UonY9ZtoVLJPrp2/DAv1m5DtnDhBYqic

        uPgLzEkOS1KdTi20Otm/J4yxLLrZC5W4x0XOeSVPXOJuQWfwQ5pPvKkn6WxYUYkGwIt1OH

        2nSMngkbami3CbSmKZOCpgQIiSlQeDJ8oGjWFMLDymYSHoVOIXHwNoooyEiaio3693l6no

        obyGv49zyCVLVR1DC7i6RJ186ql0av+D4vPoiF5mX7+sKC2E8xEj9uKQ5GTWRh59VnRBVC

        /SiMJ/H78tJnBAvoBwXxSEvj8Z3Kjm/BQqZfv4IBsA5yqV7MVq

      action: member

      state: present

```

Example playbook to add a principal to the service:

```yaml

---

- name: Playbook to manage IPA service.

  hosts: ipaserver

  become: true

  gather_facts: false

  tasks:

    # Principal host/principal.example.com present in service.

    - ipaservice:

        ipaadmin_password: SomeADMINpassword

        name: HTTP/www.example.com

        principal: host/principal.example.com

        action: member

```

Example playbook to enable a host to manage service:

```yaml

---

- name: Playbook to manage IPA service.

  hosts: ipaserver

  become: true

  gather_facts: false

  tasks:

    # Ensure host can manage service, again.

    - ipaservice:

        ipaadmin_password: SomeADMINpassword

        name: HTTP/www.example.com

        host: host1.example.com

        action: member

```

Example playbook to allow users, groups, hosts or hostgroups to create a keytab of this service:

```yaml

---

- name: Playbook to manage IPA service.

  hosts: ipaserver

  become: true

  gather_facts: false

  tasks:

    # Allow users, groups, hosts or host groups to create a keytab of this service.

    - ipaservice:

        ipaadmin_password: SomeADMINpassword

        name: HTTP/www.example.com

        allow_create_keytab_user:

        - user01

        - user02

        allow_create_keytab_group:

        - group01

        - group02

        allow_create_keytab_host:

        - host1.example.com

        - host2.example.com

        allow_create_keytab_hostgroup:

        - hostgroup01

        - hostgroup02

        action: member

```

Example playbook to allow users, groups, hosts or hostgroups to retrieve a keytab of this service:

```yaml

---

- name: Playbook to manage IPA service.

  hosts: ipaserver

  become: true

  gather_facts: false

  tasks:

    # Allow users, groups, hosts or host groups to retrieve a keytab of this service.

    - ipaservice:

        ipaadmin_password: SomeADMINpassword

        name: HTTP/www.example.com

        allow_retrieve_keytab_user:

        - user01

        - user02

        allow_retrieve_keytab_group:

        - group01

        - group02

        allow_retrieve_keytab_host:

        - "{{ host1_fqdn }}"

        - "{{ host2_fqdn }}"

        allow_retrieve_keytab_hostgroup:

        - hostgroup01

        - hostgroup02

        action: member

```

Variables

---------

ipaservice

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

`name` \| `service` | The list of service name strings. | yes

`certificate` \| `usercertificate` | Base-64 encoded service certificate. | no

`pac_type` \| `ipakrbauthzdata` | Supported PAC type. It can be one of `MS-PAC`, `PAD`, or `NONE`. | no

`auth_ind` \| `krbprincipalauthind` | Defines a whitelist for Authentication Indicators. It can be any of `otp`, `radius`, `pkinit`, or `hardened`. | no

`requires_pre_auth` \| `ipakrbrequirespreauth` | Pre-authentication is required for the service. Default to true. (bool) | no

`ok_as_delegate` \|  `ipakrbokasdelegate` | Client credentials may be delegated to the service. Default to false. (bool) | no

`ok_to_auth_as_delegate` \|  `ipakrboktoauthasdelegate` | The service is allowed to authenticate on behalf of a client. Default to false. (bool) | no

`skip_host_check` | Force service to be created even when host object does not exist to manage it. Default to false. (bool)| no

`force` | Force principal name even if host not in DNS. Default to false. (bool) | no

`host` \| `managedby_host`| Hosts that can manage the service. | no

`principal` \| `krbprincipalname` | List of principal aliases for the service. | no

`allow_create_keytab_user` \| `ipaallowedtoperform_write_keys_user` | Users allowed to create a keytab of this host. | no

`allow_create_keytab_group` \| `ipaallowedtoperform_write_keys_group`| Groups allowed to create a keytab of this host. | no

`allow_create_keytab_host` \| `ipaallowedtoperform_write_keys_host`| Hosts allowed to create a keytab of this host. | no

`allow_create_keytab_hostgroup` \| `ipaallowedtoperform_write_keys_group`| Host groups allowed to create a keytab of this host. | no

`allow_retrieve_keytab_user` \| `ipaallowedtoperform_read_keys_user` | Users allowed to retrieve a keytab of this host. | no

`allow_retrieve_keytab_group` \| `ipaallowedtoperform_read_keys_group` | Groups allowed to retrieve a keytab of this host. | no

`allow_retrieve_keytab_host` \| `ipaallowedtoperform_read_keys_host` | Hosts allowed to retrieve a keytab from of host. | no

`allow_retrieve_keytab_hostgroup` \| `ipaallowedtoperform_read_keys_hostgroup` | Host groups allowed to retrieve a keytab of this host. | no

`continue` | Continuous mode: don't stop on errors. Valid only if `state` is `absent`. Default: `no` (bool) | no

`action` | Work on service or member level. It can be on of `member` or `service` and defaults to `service`. | no

`state` | The state to ensure. It can be one of `present`, `absent`, or `disabled`, default: `present`. | no

Authors

=======

Rafael Jeffman