mirror of
https://github.com/freeipa/ansible-freeipa.git
synced 2026-07-31 20:04:45 +00:00
Move role documentation into the specific role locations as README.md
This will result in a better role documentation on galaxy.
This commit is contained in:
Thomas Woerner
174
roles/ipaclient/README.md
Normal file
174
roles/ipaclient/README.md
Normal file
@@ -0,0 +1,174 @@
|
||||
ipaclient role
|
||||
==============
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
This role allows to join hosts as clients to an IPA domain. This can be done in differnt ways using auto-discovery of the servers, domain and other settings or by specifying them.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Example inventory file with fixed principal using auto-discovery with DNS records:
|
||||
|
||||
```ini
|
||||
[ipaclients]
|
||||
ipaclient1.example.com
|
||||
ipaclient2.example.com
|
||||
|
||||
[ipaclients:vars]
|
||||
ipaadmin_principal=admin
|
||||
```
|
||||
|
||||
Example playbook to setup the IPA client(s) using principal from inventory file and password from an [Ansible Vault](http://docs.ansible.com/ansible/latest/playbooks_vault.html) file:
|
||||
|
||||
```yaml
|
||||
- name: Playbook to configure IPA clients with username/password
|
||||
hosts: ipaclients
|
||||
become: true
|
||||
vars_files:
|
||||
- playbook_sensitive_data.yml
|
||||
|
||||
roles:
|
||||
- role: ipaclient
|
||||
state: present
|
||||
```
|
||||
|
||||
Example playbook to unconfigure the IPA client(s) using principal and password from inventory file:
|
||||
|
||||
```yaml
|
||||
- name: Playbook to unconfigure IPA clients
|
||||
hosts: ipaclients
|
||||
become: true
|
||||
|
||||
roles:
|
||||
- role: ipaclient
|
||||
state: absent
|
||||
```
|
||||
|
||||
Example inventory file with fixed servers, principal, password and domain:
|
||||
|
||||
```ini
|
||||
[ipaclients]
|
||||
ipaclient1.example.com
|
||||
ipaclient2.example.com
|
||||
|
||||
[ipaservers]
|
||||
ipaserver.example.com
|
||||
|
||||
[ipaclients:vars]
|
||||
ipaclient_domain=example.com
|
||||
ipaadmin_principal=admin
|
||||
ipaadmin_password=MySecretPassword123
|
||||
```
|
||||
|
||||
Example playbook to setup the IPA client(s) using principal and password from inventory file:
|
||||
|
||||
```yaml
|
||||
- name: Playbook to configure IPA clients with username/password
|
||||
hosts: ipaclients
|
||||
become: true
|
||||
|
||||
roles:
|
||||
- role: ipaclient
|
||||
state: present
|
||||
```
|
||||
|
||||
Variables
|
||||
---------
|
||||
|
||||
### `ipaclients`
|
||||
|
||||
The mandatory `ipaclients` group is a list of the names of the IPA clients in FQDN form. All these clients will be installed or configured using the playbook.
|
||||
|
||||
### `ipaclient_domain`
|
||||
|
||||
The optional `ipaclient_domain` variable sets the DNS domain that will be used for client installation. Usually the DNS domain is a lower-cased name of the Kerberos realm.
|
||||
|
||||
If `ipaclient_domain` is not set, then it will be generated from the domain part of the first entry from the `ipaservers` FQDN group if the group is defined and contains at least one entry. If `ipaservers` is not defined, then the domain will be tried to gather using DNS autodiscovery. `ipaclient_domain` needs to be set if the primary DNS domain is different from domain part of the server FQDN.
|
||||
|
||||
### `ipaclient_realm`
|
||||
|
||||
The optional `ipaclient_realm` sets the Kerberos realm that will be used for client installation. Usually the Kerberos realm is an upper-cased name of the DNS domain.
|
||||
|
||||
If `ipaclient_realm` is not set, then it will be generated from `ipaclient_domain` if this is set. If both are not set, then this
|
||||
|
||||
|
||||
### `ipaclient_keytab`
|
||||
|
||||
The optional `ipaclient_keytab` contains the path of a backup host keytab from a previous enrollment.
|
||||
|
||||
### `ipaclient_force_join`
|
||||
|
||||
The `ipaclient_force_join` bool value defines if an already enrolled host can join again. `ipaclient_force_join` defaults to `no`.
|
||||
|
||||
### `ipaclient_use_otp`
|
||||
|
||||
The `ipaclient_use_otp` bool value defines if a one-time password will be generated to join a new or existing host. `ipaclient_use_otp` defaults to `no`.
|
||||
|
||||
The enforcement on an existing host is not done if there is a working krb5.keytab on the host. If the generation of an otp is enforced for an existing host entry, then the host gets diabled and the containing keytab gets removed.
|
||||
|
||||
### `ipaclient_allow_repair`
|
||||
|
||||
The `ipaclient_allow_repair` bool value defines if an already joined or partly set-up client can be repaired. `ipaclient_allow_repair` defaults to `no`.
|
||||
|
||||
Contrary to `ipaclient_force_join=yes` the host entry will not be changed on the server.
|
||||
|
||||
### `ipaclient_kinit_attempts`
|
||||
|
||||
The optional `ipaclient_kinit_attempts` defines the number of tries to repeat the request for a failed host Kerberos ticket. `ipaclient_kinit_attempts` defaults to 3.
|
||||
|
||||
### `ipaclient_no_ntp`
|
||||
|
||||
The `ipaclient_no_ntp` bool value defines if NTP will not be configured and enabled. `ipaclient_no_ntp` defaults to `no`.
|
||||
|
||||
### `ipaclient_mkhomedir`
|
||||
|
||||
The `ipaclient_mkhomedir` bool value defines if PAM will be configured to create a users home directory if it does not exist. `ipaclient_mkhomedir` defaults to `no`.
|
||||
|
||||
Server Variables
|
||||
----------------
|
||||
|
||||
### `ipaservers`
|
||||
|
||||
The optional `ipaservers` group is a list of the IPA server full qualified host names. In a topology with a chain of servers and replicas, it is important to use the right server or replica as the server for the client. If there is a need to overwrite the setting for a client in the `ipaclients` group, please use the list `ipaclient_servers` explained below.
|
||||
|
||||
If no `ipaservers` group is defined than the installation preparation step will try to use DNS autodiscovery to identify the the IPA server using DNS txt records.
|
||||
|
||||
### `ipaadmin_keytab`
|
||||
|
||||
The `ipaadmin_keytab` variable enables the use of an admin keytab as an alternativce authentication method. The variable needs to contain the local path to the keytab file. If `ipaadmin_keytab` is used, then `ipaadmin_password` does not need to be set.
|
||||
|
||||
### `ipaadmin_principal`
|
||||
|
||||
The optional `ipaadmin_principal` variable only needs to be set if the name of the Kerberos admin principal is not "admin". If `ipaadmin_principal` is not set it will be set internally to "admin".
|
||||
|
||||
### `ipaadmin_password`
|
||||
|
||||
The `ipaadmin_password` variable contains the Kerberos password of the Kerberos admin principal. If `ipaadmin_keytab` is used, then `ipaadmin_password` does not need to be set.
|
||||
|
||||
|
||||
Topology Variables
|
||||
------------------
|
||||
|
||||
These variables can be used to define or change how clients are arranged within a cluster for example.
|
||||
|
||||
### `ipaclient_no_dns_lookup`
|
||||
|
||||
The `ipaclient_no_dns_lookup` bool value defines if the `ipaservers` group will be used as servers for the clients automatically. If enabled this deactivates DNS lookup in Kerberos in client installations. `ipaclient_no_dns_lookup` defauults to `no`.
|
||||
|
||||
### `ipaclient_servers`
|
||||
|
||||
The optional `ipaclient_servers` varaible can be used to manually override list of servers on a per client basis. The list of servers is normally taken from from `ipaservers` group.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
freeipa-client v4.4 or later
|
||||
|
||||
Authors
|
||||
-------
|
||||
|
||||
Florence Blanc-Renaud
|
||||
|
||||
Thomas Woerner
|
||||
135
roles/ipareplica/README.md
Normal file
135
roles/ipareplica/README.md
Normal file
@@ -0,0 +1,135 @@
|
||||
ipareplica role
|
||||
==============
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
This role allows to configure a new IPA server that is a replica of the server. Once it has been created it is an exact copy of the original IPA server and is an equal master.
|
||||
Changes made to any master are automatically replicated to other masters.
|
||||
|
||||
This can be done in differnt ways using auto-discovery of the servers, domain and other settings or by specifying them.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Example inventory file with fixed principal using auto-discovery with DNS records:
|
||||
|
||||
[ipareplicas]
|
||||
ipareplica1.example.com
|
||||
ipareplica2.example.com
|
||||
|
||||
[ipareplicas:vars]
|
||||
ipaadmin_principal=admin
|
||||
|
||||
Example playbook to setup the IPA client(s) using principal from inventory file and password from an [Ansible Vault](http://docs.ansible.com/ansible/latest/playbooks_vault.html) file:
|
||||
|
||||
- name: Playbook to configure IPA replicas
|
||||
hosts: ipareplicas
|
||||
become: true
|
||||
vars_files:
|
||||
- playbook_sensitive_data.yml
|
||||
|
||||
roles:
|
||||
- role: ipareplica
|
||||
state: present
|
||||
|
||||
Example playbook to unconfigure the IPA client(s) using principal and password from inventory file:
|
||||
|
||||
- name: Playbook to unconfigure IPA replicas
|
||||
hosts: ipareplicas
|
||||
become: true
|
||||
|
||||
roles:
|
||||
- role: ipareplica
|
||||
state: absent
|
||||
|
||||
Example inventory file with fixed server, principal, password and domain:
|
||||
|
||||
[ipaserver]
|
||||
ipaserver.example.com
|
||||
|
||||
[ipareplicas]
|
||||
ipareplica1.example.com
|
||||
ipareplica2.example.com
|
||||
|
||||
[ipareplicas:vars]
|
||||
ipaclient_domain=example.com
|
||||
ipaadmin_principal=admin
|
||||
ipaadmin_password=MySecretPassword123
|
||||
ipadm_password=MySecretPassword456
|
||||
|
||||
Example playbook to setup the IPA client(s) using principal and password from inventory file:
|
||||
|
||||
- name: Playbook to configure IPA replicas with username/password
|
||||
hosts: ipareplicas
|
||||
become: true
|
||||
|
||||
roles:
|
||||
- role: ipareplica
|
||||
state: present
|
||||
|
||||
Variables
|
||||
---------
|
||||
|
||||
**ipaserver** - Group with IPA server hostname.
|
||||
(list of strings, optional)
|
||||
|
||||
**ipaclients** - Group of IPA client hostnames.
|
||||
(list of strings)
|
||||
|
||||
**ipaadmin_keytab** - The path to the admin keytab used for alternative authentication.
|
||||
(string, optional)
|
||||
|
||||
**ipaadmin_principal** - The authorized kerberos principal used to join the IPA realm.
|
||||
(string, optional)
|
||||
|
||||
**ipaadmin_password** - The password for the kerberos principal.
|
||||
(string, optional)
|
||||
|
||||
**ipaclient_domain** - The primary DNS domain of an existing IPA deployment.
|
||||
(string, optional)
|
||||
|
||||
**ipaclient_realm** - The Kerberos realm of an existing IPA deployment.
|
||||
(string, optional)
|
||||
|
||||
**ipaclient_keytab** - The path to a backed-up host keytab from previous enrollment.
|
||||
(string, optional)
|
||||
|
||||
**ipaclient_force_join** - Set force_join to yes to join the host even if it is already enrolled.
|
||||
(bool, optional)
|
||||
|
||||
**ipaclient_use_otp** - Enforce the generation of a one time password to configure new and existing hosts. The enforcement on an existing host is not done if there is a working krb5.keytab on the host. If the generation of an otp is enforced for an existing host entry, then the host gets diabled and the containing keytab gets removed.
|
||||
(bool, optional)
|
||||
|
||||
**ipaclient_allow_repair** - Allow repair of already joined hosts. Contrary to ipaclient_force_join the host entry will not be changed on the server.
|
||||
(bool, optional)
|
||||
|
||||
**ipaclient_kinit_attempts** - Repeat the request for host Kerberos ticket X times if it fails.
|
||||
(int, optional)
|
||||
|
||||
**ipaclient_no_ntp** - Set to yes to not configure and enable NTP
|
||||
(bool, optional)
|
||||
|
||||
**ipaclient_mkhomedir** - Set to yes to configure PAM to create a users home directory if it does not exist.
|
||||
(string, optional)
|
||||
|
||||
Cluster Specific Variables
|
||||
--------------------------
|
||||
|
||||
**ipaclient_no_dns_lookup** - Set to 'yes' to use groups.ipaserver in cluster environments as servers for the clients. This deactivates DNS lookup in krb5.
|
||||
(bool, optional, default: 'no')
|
||||
|
||||
**ipareplica_servers** - Manually override list of servers for example in a cluster environment on a per client basis. The list of servers is normally taken from from groups.ipaserver in cluster environments.
|
||||
(list of strings, optional)
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
freeipa-server v4.6 or later
|
||||
|
||||
Authors
|
||||
-------
|
||||
|
||||
Florence Blanc-Renaud
|
||||
|
||||
Thomas Woerner
|
||||
170
roles/ipaserver/README.md
Normal file
170
roles/ipaserver/README.md
Normal file
@@ -0,0 +1,170 @@
|
||||
ipaserver role
|
||||
==============
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
This role allows to configure and IPA server.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Example inventory file with fixed domain and realm, setting up of the DNS server and using forwarders from /etc/resolv.conf:
|
||||
|
||||
[ipaserver]
|
||||
ipaserver2.example.com
|
||||
|
||||
[ipaserver:vars]
|
||||
ipaserver_domain=example.com
|
||||
ipaserver_realm=EXAMPLE.COM
|
||||
ipaserver_setup_dns=yes
|
||||
ipaserver_auto_forwarders=yes
|
||||
|
||||
Example playbook to setup the IPA server using admin and dirman passwords from an [Ansible Vault](http://docs.ansible.com/ansible/latest/playbooks_vault.html) file:
|
||||
|
||||
- name: Playbook to configure IPA server
|
||||
hosts: ipaserver
|
||||
become: true
|
||||
vars_files:
|
||||
- playbook_sensitive_data.yml
|
||||
|
||||
roles:
|
||||
- role: ipaserver
|
||||
state: present
|
||||
|
||||
Example playbook to unconfigure the IPA client(s) using principal and password from inventory file:
|
||||
|
||||
- name: Playbook to unconfigure IPA server
|
||||
hosts: ipaserver
|
||||
become: true
|
||||
|
||||
roles:
|
||||
- role: ipaserver
|
||||
state: absent
|
||||
|
||||
Example inventory file with fixed domain, realm, admin and dirman passwords:
|
||||
|
||||
[ipaserver]
|
||||
ipaserver.example.com
|
||||
|
||||
[ipaserver:vars]
|
||||
ipaserver_domain=example.com
|
||||
ipaserver_realm=EXAMPLE.COM
|
||||
ipaadmin_password=MySecretPassword123
|
||||
ipadm_password=MySecretPassword234
|
||||
|
||||
Example playbook to setup the IPA server using admin and dirman passwords from inventory file:
|
||||
|
||||
- name: Playbook to configure IPA server
|
||||
hosts: ipaserver
|
||||
become: true
|
||||
|
||||
roles:
|
||||
- role: ipaserver
|
||||
state: present
|
||||
|
||||
Variables
|
||||
---------
|
||||
|
||||
**ipaserver** - Group with the IPA server hostname
|
||||
(list of strings)
|
||||
|
||||
**ipaadmin_password** - The password for the IPA admin user.
|
||||
(string, optional)
|
||||
|
||||
**ipadm_password** - The password for the Directory Manager.
|
||||
(string, optional)
|
||||
|
||||
**ipaserver_domain** - The primary DNS domain of an existing IPA deployment.
|
||||
(string)
|
||||
|
||||
**ipaserver_realm** - The Kerberos realm of an existing IPA deployment.
|
||||
(string)
|
||||
|
||||
**ipaserver_idstart** - The starting user and group id number (default random).
|
||||
(integer, optional)
|
||||
|
||||
**ipaserver_idmax** - The maximum user and group id number (default: idstart+199999).
|
||||
(integer, optional)
|
||||
|
||||
**ipaserver_no_hbac_allow** - Do not install allow_all HBAC rule.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_no_ui_redirect** - Do not automatically redirect to the Web UI.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_dirsrv_config_file** - The path to LDIF file that will be used to modify configuration of dse.ldif during installation.
|
||||
(string, optional)
|
||||
|
||||
**ipaserver_setup_kra** - Install and configure a KRA on this server.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_setup_dns** - Configure an integrated DNS server, create DNS zone specified by domain
|
||||
(string, optional)
|
||||
|
||||
**ipaserver_forwarders** - Add DNS forwarders to the DNS configuration.
|
||||
(list of strings, optional)
|
||||
|
||||
**ipaserver_no_forwarders** - Do not add any DNS forwarders. Root DNS servers will be used instead.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_auto_forwarders** - Add DNS forwarders configured in /etc/resolv.conf to the list of forwarders used by IPA DNS.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_forward_policy** - DNS forwarding policy for global forwarders specified using other options. first|only
|
||||
(choice, optional)
|
||||
|
||||
**ipaserver_reverse_zones** - The reverse DNS zones to use.
|
||||
(list of strings, optional)
|
||||
|
||||
**ipaserver_no_reverse** - Do not create reverse DNS zone.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_auto_reverse** - Try to resolve reverse records and reverse zones for server IP addresses.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_zonemgr** - The e-mail address of the DNS zone manager. Defaults to hostmaster@DOMAIN.
|
||||
(string, optional)
|
||||
|
||||
**ipaserver_no_host_dns** - Do not use DNS for hostname lookup during installation.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_no_dnssec_validation** - Disable DNSSEC validation on this server.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_allow_zone_overlap** - Allow creation of (reverse) zone even if the zone is already resolvable.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_setup_adtrust** - Configure AD Trust capability.
|
||||
(bool, optional)
|
||||
|
||||
**ipaserver_netbios_name** - The NetBIOS name for the IPA domain.
|
||||
(string, optional)
|
||||
|
||||
**ipaserver_rid_base** - First RID value of the local domain.
|
||||
(integer, optional)
|
||||
|
||||
**ipaserver_secondary_rid_base** - Start value of the secondary RID range.
|
||||
(integer, optional)
|
||||
|
||||
**ipaserver_enable_compat** - Enables support for trusted domains users for old clients through Schema Compatibility plugin.
|
||||
(bool, optional)
|
||||
|
||||
**ipaclient_force_join** - Set force_join to yes to join the host even if it is already enrolled.
|
||||
(bool, optional)
|
||||
|
||||
**ipaclient_no_ntp** - Set to no to not configure and enable NTP
|
||||
(bool, optional)
|
||||
|
||||
**ipaclient_mkhomedir** - Set to yes to configure PAM to create a users home directory if it does not exist.
|
||||
(string, optional)
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
freeipa-server v4.5 or later
|
||||
|
||||
Authors
|
||||
-------
|
||||
|
||||
Thomas Woerner
|
||||
Reference in New Issue
Block a user