timorunge.freeipa_client

freeipa_client

This role installs and sets up the FreeIPA Client based on your requirements.

When used with freeipa (Github), you can successfully run freeipa_client with the latest FreeIPA version on Debian 9.4 and Ubuntu versions 18.04 and newer (check the example section).

Requirements

This role needs Ansible 2.5.0 or a newer version.

You can easily install a stable version using pip:

pip install ansible==2.7.9

All platform requirements are specified in the metadata file.

To set up this role properly, you need to be able to communicate through the required ports to a FreeIPA Server (Github Repo).

Install

ansible-galaxy install timorunge.freeipa_client

Role Variables

You must set the following variables for this role to work (no customization needed). These variables do not have default values:

# Main DNS domain of the IPA deployment
# Type: Str
freeipa_client_domain: example.com
# The hostname of this machine (FQDN)
# Type: Str
freeipa_client_fqdn: srv-1-eu-central-1.example.com
# Password to join the IPA realm
# Type: Str
freeipa_client_password: Passw0rd
# Principal to use to join the IPA realm
# Type: Str
freeipa_client_principal: admin
# Kerberos realm name of the IPA deployment
# Type: Str
freeipa_client_realm: EXAMPLE.COM
# FQDN of IPA server
# Type: Str
freeipa_client_server: ipa.example.com

You can adjust the following variables for this role. (For all variables, see defaults/main.yml)

# Base command for FreeIPA installation
# Type: Str
freeipa_client_install_base_command: ipa-client-install --unattended

# Default FreeIPA installation options
# Type: List
freeipa_client_install_options:
  - "--domain={{ freeipa_client_domain }}"
  - "--server={{ freeipa_client_server }}"
  - "--realm={{ freeipa_client_realm }}"
  - "--principal={{ freeipa_client_principal }}"
  - "--password={{ freeipa_client_password }}"
  - "--mkhomedir"
  - "--hostname={{ freeipa_client_fqdn }}"
  - "--force-join"

Examples

To keep this document brief, the install options are simplified. You can find more install options in this document or in the online man page for ipa-client-install.

1) Install the FreeIPA client with default settings

- hosts: freeipa-clients
  vars:
    freeipa_client_domain: example.com
    freeipa_client_server: ipa.example.com
    freeipa_client_realm: EXAMPLE.COM
    freeipa_client_principal: admin
    freeipa_client_password: Passw0rd
    freeipa_client_fqdn: srv-1-eu-central-1.example.com
  roles:
    - timorunge.freeipa_client

2) Install the FreeIPA client with custom install options

- hosts: freeipa-clients
  vars:
    freeipa_client_domain: example.com
    freeipa_client_server: ipa.example.com
    freeipa_client_realm: EXAMPLE.COM
    freeipa_client_principal: admin
    freeipa_client_password: Passw0rd
    freeipa_client_fqdn: srv-1-eu-central-1.example.com
    freeipa_client_install_options:
      - "--no-ntp"
      - "--ssh-trust-dns"
      - "--ip-address=172.20.1.2"
      - "--ip-address=172.20.2.2"
  roles:
    - timorunge.freeipa_client

3) Install the FreeIPA client and add multiple IPA servers

- hosts: freeipa-clients
  vars:
    freeipa_client_domain: example.com
    freeipa_client_server:
      - ipa-eu-central-1.example.com
      - ipa-eu-west-1.example.com
      - ipa-eu-west-2.example.com
      - ipa-eu-west-3.example.com
      - ipa.example.com
    freeipa_client_realm: EXAMPLE.COM
    freeipa_client_principal: admin
    freeipa_client_password: Passw0rd
    freeipa_client_fqdn: srv-1-eu-central-1.example.com
    freeipa_client_install_options:
      - "--server={{ freeipa_client_server | join(' --server=') }}"
  roles:
    - timorunge.freeipa_client

FreeIPA client install options

Here are the install options for ipa-client-install (4.6.4).

Usage: ipa-client-install [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -U, --unattended      unattended installation (no prompts)
  --uninstall           remove an existing installation. Can run with --unattended option

  Basic options:
    -p PRINCIPAL, --principal=PRINCIPAL
                        principal to use to join the IPA realm
    --ca-cert-file=FILE
                        load the CA certificate from a file
    --ip-address=IP_ADDRESS
                        Specify an IP address to add to DNS. This can be used multiple times
    --all-ip-addresses  Add all routable IP addresses configured on any interface to DNS
    --domain=DOMAIN_NAME
                        primary DNS domain of the IPA deployment
    --server=SERVER     FQDN of IPA server
    --realm=REALM_NAME  Kerberos realm name of the IPA deployment
    --hostname=HOST_NAME
                        The hostname of this machine (FQDN). If specified, it will persist after a reboot.

  Client options:
    -w PASSWORD, --password=PASSWORD
                        password to join the IPA realm
    -W                  Prompt for a password to join the IPA realm
    --noac              do not change the NSSwitch.conf and PAM configuration
    -f, --force         force settings of LDAP/Kerberos config
    --mkhomedir         create home directories for users on first login
    --force-join        Force client enrollment even if already enrolled
    --no-ntp            do not configure NTP

  SSSD options:
    --fixed-primary     Use a specific server as the primary IPA server
    --permit            allow all access by default

  Logging and output options:
    -v, --verbose       output debugging information
    -q, --quiet         show only errors
    --log-file=FILE     log output to a specified file

Testing

Tests are done using Docker and docker_test_runner. They perform linting and syntax checks.

For more detail, check the docker_test_runner configuration and the Docker entrypoint.

# To test locally:
curl https://raw.githubusercontent.com/timorunge/docker-test-runner/master/install.sh | sh
./docker_test_runner.py -f tests/docker_test_runner.yml