README.md 6.16 KB
Newer Older
1
# Freeipa Puppet module
2

3
#### Table of Contents
4

5 6 7 8
1. [Description](#description)
2. [Setup - The basics of getting started with Freeipa Puppet Module](#setup)
    * [What Freeipa Puppet module affects](#what-freeipa-pupppet-module-affects)
    * [Setup requirements](#setup-requirements)
9
    * [How does the module work](#how-does-the-module-work)
10 11
3. [Usage - Configuration options and additional functionality](#usage)
4. [Limitations - OS compatibility, etc.](#limitations)
12 13
5. [Development - Release Notes](#development)

14

15 16
## Description

17
This module will install and configure FreeIPA servers, replicas, and clients.
18 19 20 21 22

## Setup

### What Freeipa Pupppet module affects

23 24 25 26
The module should not affect a previous installation of FreeIPA, it should fail trying.

Below are all items that module can affect:

27
 * Modifiy /etc/hosts (if `$freeipa::manage_host_entry` true)
28

Fabien Combernous's avatar
Fabien Combernous committed
29
 * Install the following packages if not present: autofs, bind-dyndb-ldap, epel-release, sssd-common, sssdtools, ipa-client, ipa-server, ipa-server-dns, openldap-clients
30 31 32 33

Installation of Freeipa server will obviously install a ntp server, a DNS server, a LDAP Directory, a Kerberos server, apache, Certmonger and PKI Tomcat.

### Setup Requirements
34

35 36
This module requires :

37
  * `puppetlabs-stdlib`
38

39
  * `stahnma-epel`
40

41 42 43
Versions are given in `metadata.json` file.

### How does the module work.
44

45 46
Usually with a module, the desired state is described. If a value of parameter is changed, then during the next puppet run the node is modified to reach the desired state.
The version 3.x is a starting work to reach the target. But, the module is more an idempotent installer of FreeIPA.
47

48
So, to ensure that desired state described in code is applied on the node, puppet needs to login to kerberos. Puppet uses a fixed account `admin` to do this. It is possible to set the password of this account with parameter `freeipa::puppet_admin_password`. If `freeipa::enable_manage_admins` is true, the accounts of humans administrators are managed with hash `freeipa::humanadmins`. If you modify `freeipa::humanadmins`, next puppet run will take care to update the admins users on master node. The replication will to the job on replicas.
49 50

## Usage
51

52 53
### Example usage:

54
Creating an IPA master, with the WebUI proxied to `https://localhost:8440` and two admin accounts `jdupond` and `mgonzales`.
55
```puppet
56
class {'freeipa':
57
    ipa_role                    => 'master',
58 59
    domain                      => 'example.lan',
    ipa_server_fqdn             => 'ipa-server-1.example.lan',
60 61
    puppet_admin_password       => 'secret_abc,
    directory_services_password => 'secret_dir',
62
    install_ipa_server          => true,
63
    ip_address                  => '10.10.10.35',
64 65 66 67
    enable_ip_address           => true,
    enable_hostname             => true,
    manage_host_entry           => true,
    install_epel                => true,
68 69 70 71 72 73 74 75 76
    humanadmins                 => {
      jdupond => {
        ensure => 'present',
        password => 'secret123',
      },
      mgonzales => {
        ensure => 'present',
        password => 'secret456',
      },
77 78 79
      hzimmer => {
        ensure => 'absent',
      },
80
    },
81 82 83 84 85
}
```

Adding a replica:
```puppet
86
class {'freeipa':
87
    ipa_role             => 'replica',
88 89
    domain               => 'example.lan',
    ipa_server_fqdn      => 'ipa-server-2.example.lan',
90 91
    domain_join_password => 'vagrant123',
    install_ipa_server   => true,
92
    ip_address           => '10.10.10.36',
93 94 95 96
    enable_ip_address    => true,
    enable_hostname      => true,
    manage_host_entry    => true,
    install_epel         => true,
97
    ipa_master_fqdn      => 'ipa-server-1.example.lan',
98 99 100 101 102
}
```

Adding a client:
```puppet
103
class {'freeipa':
104
ipa_role             => 'client',
105
domain               => 'example.lan',
106 107
domain_join_password => 'vagrant123',
install_epel         => true,
108
ipa_master_fqdn      => 'ipa-server-1.example.lan',
109 110 111
}
```

112 113 114
### REFERENCE

A full description can be found in `REFERENCE.md`.
115 116 117

## Limitations

118
This module will not work well if managed passwords contain `'` or `\`. They must be banned.
119

120 121
Acceptance tests are done :

122
 * with last available versions of Puppet 5 and Puppet 6 from puppetlabs packages AIO (facter 3 is shiped).
123

Fabien Combernous's avatar
Fabien Combernous committed
124
 * with CentOS 7 for FreeIPA master and replica nodes. IPA masters and replicas works only on Centos >= 7.5.
125

Fabien Combernous's avatar
Fabien Combernous committed
126
 * with CentOS 7 and Ubuntu 16.06 for FreeIPA clients .
127

Fabien Combernous's avatar
Fabien Combernous committed
128
Puppet4 is EOL since 2019-01-01. Even if puppet 4.10 should work, it is not tested.
Fabien Combernous's avatar
Fabien Combernous committed
129

130 131 132 133 134 135 136 137 138
## Development

Home at URL https://gitlab.adullact.net/adullact/puppet-freeipa

Issues and MR are welcome. `CONTRIBUTING.md` gives some guidance about contributing process. 
If you follow these contributing guidelines your patch will likely make it into a release a little more quickly.

### Release Notes

139
Details in `CHANGELOG.md`. Key points :
140

141
 * release 1.6.1 : the fist release under `adullact` name space. nothing special.
142

143 144 145
 * releases 2.x : use code ready for Puppet 4.10 and 5.x, uses pdk as guidance, enable acceptance tests, rename classes from `easy_ipa` to `freeipa`.

 * releases 3.x : use public and private classes, enable Puppet 6 tests, drop Puppet 4 tests, refactor module to permit management of administrator accounts.
146 147

### Contributors
148 149

Original work from Harvard University Information Technology, mainly written by Rob Ruma (https://github.com/huit/puppet-ipa)
150

151
then forked by John Puskar (https://github.com/jpuskar/puppet-freeipa)
152

Fabien Combernous's avatar
Fabien Combernous committed
153
then forked by ADULLACT (https://gitlab.adullact.net/adullact/puppet-freeipa) written by :
154 155 156
  * ADULLACT with Fabien Combernous
  * PHOSPHORE.si with Scott Barthelemy and Bertrand RETIF

157
### License
158

159 160 161 162
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
163

164 165 166 167
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
168

169 170
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
171