Chapter 16. Managing IdM servers by using Ansible

You can use Red Hat Ansible Engine to manage the servers in your Identity Management (IdM) topology. You can use the server module in the ansible-freeipa package to check the presence or absence of a server in the IdM topology. You can also hide any replica or make a replica visible.

The section contains the following topics:

16.1. Checking that an IdM server is present by using Ansible

You can use the ipaserver ansible-freeipa module in an Ansible playbook to verify that an Identity Management (IdM) server exists.

Note

The ipaserver Ansible module does not install the IdM server.

Prerequisites

  • You know the IdM admin password.

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

  • The target node, that is the node on which the ansible-freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

    • The SSH connection from the control node to the IdM server defined in the inventory file is working correctly.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/

  2. Copy the server-present.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/server/ directory: 

    $ cp /usr/share/doc/ansible-freeipa/playbooks/server/server-present.yml server-present-copy.yml
  3. Open the server-present-copy.yml file for editing.

  4. Adapt the file by setting the following variables in the ipaserver task section and save the file:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to the FQDN of the server. The FQDN of the example server is server123.idm.example.com. 
    ---
- name: Server present example
  hosts: ipaserver
  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure server server123.idm.example.com is present
    ipaserver:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: server123.idm.example.com

  5. Run the Ansible playbook and specify the playbook file and the inventory file: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory server-present-copy.yml

Additional resources

16.2. Ensuring that an IdM server is absent from an IdM topology by using Ansible

Use an Ansible playbook to ensure an Identity Management (IdM) server does not exist in an IdM topology, even as a host.

In contrast to the ansible-freeipa ipaserver role, the ipaserver module used in this playbook does not uninstall IdM services from the server.

Prerequisites

  • You know the IdM admin password.

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

  • The target node, that is the node on which the ansible-freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

    • The SSH connection from the control node to the IdM server defined in the inventory file is working correctly.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/

  2. Copy the server-absent.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/server/ directory: 

    $ cp /usr/share/doc/ansible-freeipa/playbooks/server/server-absent.yml server-absent-copy.yml
  3. Open the server-absent-copy.yml file for editing.

  4. Adapt the file by setting the following variables in the ipaserver task section and save the file:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to the FQDN of the server. The FQDN of the example server is server123.idm.example.com.
    • Ensure that the state variable is set to absent. 
    ---
- name: Server absent example
  hosts: ipaserver
  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure server server123.idm.example.com is absent
    ipaserver:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: server123.idm.example.com
      state: absent

  5. Run the Ansible playbook and specify the playbook file and the inventory file: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory server-absent-copy.yml
  6. Make sure all name server (NS) DNS records pointing to server123.idm.example.com are deleted from your DNS zones. This applies regardless of whether you use integrated DNS managed by IdM or external DNS.

Additional resources

  • See Uninstalling an IdM server.
  • See the README-server.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See the sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/server directory.

16.3. Ensuring the absence of an IdM server despite hosting a last IdM server role

You can use Ansible to ensure that an Identity Management (IdM) server is absent even if the last IdM service instance is running on the server. A certificate authority (CA), key recovery authority (KRA), or DNS server are all examples of IdM services.

Warning

If you remove the last server that serves as a CA, KRA, or DNS server, you disrupt IdM functionality seriously. You can manually check which services are running on which IdM servers with the ipa service-find command. The principal name of a CA server is dogtag/server_name/REALM_NAME.

In contrast to the ansible-freeipa ipaserver role, the ipaserver module used in this playbook does not uninstall IdM services from the server.

Prerequisites

  • You know the IdM admin password.

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

  • The target node, that is the node on which the ansible-freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

    • The SSH connection from the control node to the IdM server defined in the inventory file is working correctly.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/

  2. Copy the server-absent-ignore-last-of-role.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/server/ directory: 

    $ cp /usr/share/doc/ansible-freeipa/playbooks/server/server-absent-ignore-last-of-role.yml server-absent-ignore-last-of-role-copy.yml
  3. Open the server-absent-ignore-last-of-role-copy.yml file for editing.

  4. Adapt the file by setting the following variables in the ipaserver task section and save the file:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to the FQDN of the server. The FQDN of the example server is server123.idm.example.com.
    • Ensure that the ignore_last_of_role variable is set to yes.
    • Set the state variable to absent. 
    ---
- name: Server absent with last of role skip example
  hosts: ipaserver
  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure server “server123.idm.example.com” is absent with last of role skip
    ipaserver:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: server123.idm.example.com
      ignore_last_of_role: yes
      state: absent

  5. Run the Ansible playbook and specify the playbook file and the inventory file: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory server-absent-ignore-last-of-role-copy.yml
  6. Make sure all name server (NS) DNS records that point to server123.idm.example.com are deleted from your DNS zones. This applies regardless of whether you use integrated DNS managed by IdM or external DNS.

Additional resources

  • See Uninstalling an IdM server.
  • See the README-server.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/server directory.

16.4. Ensuring that an IdM server is absent but not necessarily disconnected from other IdM servers

If you are removing an Identity Management (IdM) server from the topology, you can keep its replication agreements intact with an Ansible playbook. The playbook also ensures that the IdM server does not exist in IdM, even as a host.

Important

Ignoring a server’s replication agreements when removing it is only recommended when the other servers are dysfunctional servers that you are planning to remove anyway. Removing a server that serves as a central point in the topology can split your topology into two disconnected clusters.

You can remove a dysfunctional server from the topology with the ipa server-del command.

Note

If you remove the last server that serves as a certificate authority (CA), key recovery authority (KRA), or DNS server, you seriously disrupt the Identity Management (IdM) functionality. To prevent this problem, the playbook makes sure these services are running on another server in the domain before it uninstalls a server that serves as a CA, KRA, or DNS server.

In contrast to the ansible-freeipa ipaserver role, the ipaserver module used in this playbook does not uninstall IdM services from the server.

Prerequisites

  • You know the IdM admin password.

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

  • The target node, that is the node on which the ansible-freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

    • The SSH connection from the control node to the IdM server defined in the inventory file is working correctly.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/

  2. Copy the server-absent-ignore_topology_disconnect.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/server/ directory: 

    $ cp /usr/share/doc/ansible-freeipa/playbooks/server/server-absent-ignore_topology_disconnect.yml server-absent-ignore_topology_disconnect-copy.yml
  3. Open the server-absent-ignore_topology_disconnect-copy.yml file for editing.

  4. Adapt the file by setting the following variables in the ipaserver task section and save the file:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to the FQDN of the server. The FQDN of the example server is server123.idm.example.com.
    • Ensure that the ignore_topology_disconnect variable is set to yes.
    • Ensure that the state variable is set to absent. 
    ---
- name: Server absent with ignoring topology disconnects example
  hosts: ipaserver
  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure server “server123.idm.example.com” with ignoring topology disconnects
    ipaserver:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: server123.idm.example.com
      ignore_topology_disconnect: yes
      state: absent

  5. Run the Ansible playbook and specify the playbook file and the inventory file: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory server-absent-ignore_topology_disconnect-copy.yml
  6. [Optional] Make sure all name server (NS) DNS records pointing to server123.idm.example.com are deleted from your DNS zones. This applies regardless of whether you use integrated DNS managed by IdM or external DNS.

Additional resources

  • See Uninstalling an IdM server.
  • See the README-server.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See sample playbooks in the /usr/share/doc/ansible-freeipa/playbooks/server directory.

16.5. Ensuring that an existing IdM server is hidden using an Ansible playbook

Use the ipaserver ansible-freeipa module in an Ansible playbook to ensure that an existing Identity Management (IdM) server is hidden. Note that this playbook does not install the IdM server.

Prerequisites

  • You know the IdM admin password.

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

  • The target node, that is the node on which the ansible-freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

    • The SSH connection from the control node to the IdM server defined in the inventory file is working correctly.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/

  2. Copy the server-hidden.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/server/ directory: 

    $ cp /usr/share/doc/ansible-freeipa/playbooks/server/server-hidden.yml server-hidden-copy.yml
  3. Open the server-hidden-copy.yml file for editing.

  4. Adapt the file by setting the following variables in the ipaserver task section and save the file:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to the FQDN of the server. The FQDN of the example server is server123.idm.example.com.
    • Ensure that the hidden variable is set to True. 
    ---
- name: Server hidden example
  hosts: ipaserver
  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure server server123.idm.example.com is hidden
    ipaserver:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: server123.idm.example.com
      hidden: True

  5. Run the Ansible playbook and specify the playbook file and the inventory file: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory server-hidden-copy.yml

Additional resources

16.6. Ensuring that an existing IdM server is visible by using an Ansible playbook

Use the ipaserver ansible-freeipa module in an Ansible playbook to ensure that an existing Identity Management (IdM) server is visible. Note that this playbook does not install the IdM server.

Prerequisites

  • You know the IdM admin password.

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

  • The target node, that is the node on which the ansible-freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

    • The SSH connection from the control node to the IdM server defined in the inventory file is working correctly.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/

  2. Copy the server-not-hidden.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/server/ directory: 

    $ cp /usr/share/doc/ansible-freeipa/playbooks/server/server-not-hidden.yml server-not-hidden-copy.yml
  3. Open the server-not-hidden-copy.yml file for editing.

  4. Adapt the file by setting the following variables in the ipaserver task section and save the file:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to the FQDN of the server. The FQDN of the example server is server123.idm.example.com.
    • Ensure that the hidden variable is set to no. 
    ---
- name: Server not hidden example
  hosts: ipaserver
  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure server server123.idm.example.com is not hidden
    ipaserver:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: server123.idm.example.com
      hidden: no

  5. Run the Ansible playbook and specify the playbook file and the inventory file: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory server-not-hidden-copy.yml

Additional resources

16.7. Ensuring that an existing IdM server has an IdM DNS location assigned

Use the ipaserver ansible-freeipa module in an Ansible playbook to ensure that an existing Identity Management (IdM) server is assigned a specific IdM DNS location.

Note that the ipaserver Ansible module does not install the IdM server.

Prerequisites

  • You know the IdM admin password.
  • The IdM DNS location exists. The example location is germany.
  • You have root access to the server. The example server is server123.idm.example.com.

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

  • The target node, that is the node on which the ansible-freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

    • The SSH connection from the control node to the IdM server defined in the inventory file is working correctly.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/

  2. Copy the server-location.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/server/ directory: 

    $ cp /usr/share/doc/ansible-freeipa/playbooks/server/server-location.yml server-location-copy.yml
  3. Open the server-location-copy.yml file for editing.

  4. Adapt the file by setting the following variables in the ipaserver task section and save the file:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to server123.idm.example.com.
    • Set the location variable to germany.

    This is the modified Ansible playbook file for the current example: 

    ---
- name: Server enabled example
  hosts: ipaserver
  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure server server123.idm.example.com with location “germany” is present
    ipaserver:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: server123.idm.example.com
      location: germany

  5. Run the Ansible playbook and specify the playbook file and the inventory file: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory server-location-copy.yml

  6. Connect to server123.idm.example.com as root using SSH: 

    ssh root@server123.idm.example.com

  7. Restart the named-pkcs11 service on the server for the updates to take effect immediately: 

    [root@server123.idm.example.com ~]# systemctl restart named-pkcs11

Additional resources

16.8. Ensuring that an existing IdM server has no IdM DNS location assigned

Use the ipaserver ansible-freeipa module in an Ansible playbook to ensure that an existing Identity Management (IdM) server has no IdM DNS location assigned to it. Do not assign a DNS location to servers that change geographical location frequently. Note that the playbook does not install the IdM server.

Prerequisites

  • You know the IdM admin password.
  • You have root access to the server. The example server is server123.idm.example.com.

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password.

  • The target node, that is the node on which the ansible-freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

    • The SSH connection from the control node to the IdM server defined in the inventory file is working correctly.

Procedure

  1. Navigate to your ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/

  2. Copy the server-no-location.yml Ansible playbook file located in the /usr/share/doc/ansible-freeipa/playbooks/server/ directory: 

    $ cp /usr/share/doc/ansible-freeipa/playbooks/server/server-no-location.yml server-no-location-copy.yml
  3. Open the server-no-location-copy.yml file for editing.

  4. Adapt the file by setting the following variables in the ipaserver task section and save the file:

    • Set the ipaadmin_password variable to the password of the IdM admin.
    • Set the name variable to server123.idm.example.com.
    • Ensure that the location variable is set to ””. 
    ---
- name: Server no location example
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure server server123.idm.example.com is present with no location
    ipaserver:
      ipaadmin_password: "{{ ipaadmin_password }}"
      name: server123.idm.example.com
      location: “”

  5. Run the Ansible playbook and specify the playbook file and the inventory file: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory server-no-location-copy.yml

  6. Connect to server123.idm.example.com as root using SSH: 

    ssh root@server123.idm.example.com

  7. Restart the named-pkcs11 service on the server for the updates to take effect immediately: 

    [root@server123.idm.example.com ~]# systemctl restart named-pkcs11

Additional resources