Tested with Travis CI
- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with openldap
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
This module manages OpenLDAP.
This module can install LDAP libraries, client utilities and more importantly
install and configure the slapd
ḋaemon to provide directory services.
- The package(s) providing LDAP support.
- Managing the global and any per-user LDAP client configuration.
- Installing client utilities.
- Installing and configuring the
slapd
daemon. - The service controlling the
slapd
daemon.
include ::openldap
Parameters within openldap
:
The name of the package to install that provides the LDAP libraries.
The base configuration directory, usually /etc/openldap
or /etc/ldap
.
The global configuration file, normally ${conf_dir}/ldap.conf
.
See the base
parameter in openldap::configuration
.
See the uri
parameter in openldap::configuration
.
See the deref
parameter in openldap::configuration
.
See the network_timeout
parameter in openldap::configuration
.
See the referrals
parameter in openldap::configuration
.
See the sizelimit
parameter in openldap::configuration
.
See the timelimit
parameter in openldap::configuration
.
See the timeout
parameter in openldap::configuration
.
See the sasl_secprops
parameter in openldap::configuration
.
See the sasl_nocanon
parameter in openldap::configuration
.
See the gssapi_sign
parameter in openldap::configuration
.
See the gssapi_encrypt
parameter in openldap::configuration
.
See the gssapi_allow_remote_principal
parameter in openldap::configuration
.
See the tls_cacert
parameter in openldap::configuration
.
See the tls_cacertdir
parameter in openldap::configuration
.
See the tls_cipher_suite
parameter in openldap::configuration
.
See the tls_protocol_min
parameter in openldap::configuration
.
See the tls_randfile
parameter in openldap::configuration
.
See the tls_reqcert
parameter in openldap::configuration
.
See the tls_crlcheck
parameter in openldap::configuration
.
See the tls_crlfile
parameter in openldap::configuration
.
Parameters within openldap::client
:
The name of the package to install that provides the LDAP client utilities.
Parameters within openldap::server
:
The Root Distinguished Name used to administer the database.
The password for the Root Distinguished Name.
The suffix for the main database.
An array of ACLs to apply to the database, in the same form as the olcAccess
attribute.
Do not include an ACL for the DN used by replication, one is added
automatically when the syncprov
parameter is used.
Setting this to true
will enable the accesslog
overlay in conjunction
with the syncprov
overlay to enable delta replication.
It will create a separate database with the suffix cn=log
and use the value
of the replica_dn
parameter much like the syncprov
setting to allow it to
be accessed by consumers.
Specify the size of the in-memory entry cache maintained by the bdb
or
hdb
backends for the database used by the accesslog
overlay. See the
olcDbCacheSize
attribute.
Specify the frequency for checkpointing the transaction log of the database
used by the accesslog
overlay. This is specified in the same form as the
olcDbCheckpoint
attribute.
An array of lines in the same form as the olcDbConfig
attribute to tune the
database used by the accesslog
overlay. This results in creating a
DB_CONFIG
file for the database if the backend is either bdb
or hdb
.
Specify the size of the in-memory DN cache maintained by the bdb
or
hdb
backends for the database used by the accesslog
overlay. See the
olcDbDNcacheSize
attribute.
Specify the size of the in-memory index cache maintained by the bdb
or
hdb
backends for the database used by the accesslog
overlay. See the
olcDbIDLcacheSize
attribute.
Where slapd
writes out its command-line arguments.
Setting this to true
will enable the auditlog
overlay.
The LDIF file where the auditlog
overlay writes any changes.
Maps to the olcAuthzPolicy
attribute, accepts one of none
, from
, to
,
any
, or all
.
An array of database backends that are built as modules and therefore require loading before use.
Setting this to true
enables the chain
overlay which transparently
forwards writes to a slave/consumer on behalf of the client to the
master/producer indicated by the configured update referral URI.
Maps to the olcDbIDAssertBind
attribute on the LDAP database used by the
chain overlay.
Maps to the olcDbRebindAsUser
attribute on the LDAP database used by the
chain overlay.
Maps to the olcChainReturnError
attribute on the chain overlay.
Maps to the olcDbStartTLS
attribute on the LDAP database used by the chain
overlay. See the tls
entry in the slapd-ldap
man page for more information
on usage and accepted values.
Specify the size of the in-memory entry cache maintained by the bdb
or
hdb
backends for the main database. See the olcDbCacheSize
attribute.
Specify the frequency for checkpointing the transaction log of the main
database. This is specified in the same form as the olcDbCheckpoint
attribute.
An array of lines in the same form as the olcDbConfig
attribute to tune the
main database. This results in creating a DB_CONFIG
file for the database
if the backend is either bdb
or hdb
.
The base directory used for database storage. Rather than store one database at the top level, this module creates a sub-directory per-database. Any unmanaged files in the top-level directory will be purged.
Specify the size of the in-memory index cache maintained by the bdb
or
hdb
backends for the main database. See the olcDbDNcacheSize
attribute.
Specify the size of the in-memory index cache maintained by the bdb
or
hdb
backends for the main database. See the olcDbIDLcacheSize
attribute.
The chosen database backend, usually one of hdb
, bdb
, or mdb
.
The group that runs the slapd
process.
An array of index definitions in the same form as the olcDbIndex
attribute.
Do not include an index for the attributes applicable to the syncprov
overlay. They are added automatically.
Any array of address(:port)
values that will be wrapped with ldap://
&
/
to form a list of interfaces to listen on for regular LDAP (optionally
with STARTTLS) connections, traditionally on TCP port 389. For IPv6 values,
the address portion should be wrapped with []
's, i.e. [address](:port)
.
Any array of address(:port)
values that will be wrapped with ldaps://
&
/
to form a list of interfaces to listen on for LDAP over SSL connections,
traditionally on TCP port 636. For IPv6 values, the address portion should
be wrapped with []
's, i.e. [address](:port)
.
An array of limits in the same form as the olcLimits
attribute.
Do not include a limit for the DN used by replication, one is added
automatically when the syncprov
parameter is used.
Security strength factor assigned to ldapi
connections. This defaults to 256
which is a safeguard to prevent locking the Puppet agent out as it uses this
connection to manipulate the configuration.
Set the logging level. Maps to the olcLogLevel
attribute.
The extension module files have, normally .la
.
The name of the package to install that provides the LDAP slapd
daemon.
Where slapd
writes out its PID.
Setting this to true
will enable the ppolicy
overlay on the main database
allowing the enforcement of password strength/complexity as well as account
lockout. You will need to ensure the ppolicy
schema is loaded before you
try and create or load any policies.
A Distinguished Name of the default password policy object to use if a user
does not have a pwdPolicySubEntry
attribute. This must exist under the
main suffix.
If this server is a consumer/slave this setting controls whether password
policy operational attributes are written locally or forwarded to the
producer/master, (which means they can come back via replication). This
requires enabling the chain
overlay.
Setting this to true
forces cleartext passwords to be hashed when updated
via Add or Modify operations. This is not necessary if the Password Modify
extended operation is normally used.
Setting this to true
makes a bind to a locked account return an
AccountLocked
error instead of InvalidCredentials
.
The Distinguished Name used by consumer/slave servers to connect to this server in order to replicate content.
The base directory used to store the schemas shipped with OpenLDAP. This is
used as a default by the
openldap::server::schema
defined type.
Specify minimum security strength factors in the same form as the
olcSecurity
attribute.
Specify the maximum number of entries to return from a search operation. Maps
to the olcSizeLimit
attribute set on the frontend
database.
Setting this to true
will enable the smbk5pwd
overlay. In order to add this
overlay to the database, the schema files for any enabled backends also need to
be loaded. Both Red Hat and Debian/Ubuntu enable the Samba backend by default
which requires the Samba schema. Debian/Ubuntu additionally enable the Kerberos
backend which requires the Heimdal KDC/HDB schema and also slapd
will need to
be able to access the KDC master key (m-key
) file.
By default, all backends compiled into the overlay are enabled. Pass in an
array of backends to enable only some of them. This affects which schemas
need to be loaded and any additional setup steps. This maps to the
olcSmbK5PwdEnable
attribute.
Maps to the olcSmbK5PwdMustChange
attribute controlling how long until Samba
passwords expire after a password change.
Maps to the olcTLSCACertificateFile
attribute.
Maps to the olcTLSCertificateFile
attribute.
Maps to the olcTLSCACertificatePath
attribute.
Maps to the olcTLSCipherSuite
attribute.
Maps to the olcTLSDHParamFile
attribute.
Maps to the olcTLSCertificateKeyFile
attribute.
Maps to the olcTLSProtocolMin
attribute.
Setting this to true
will enable the syncprov
overlay on the main database
allowing consumer/slave servers to replicate the content.
An additional index entryCSN,entryUUID eq
will be appended to those passed
by the indices
parameter.
The value of the replica_dn
parameter is also used to prepend the ACL to * by dn.exact="${replica_dn}" read by * break
to those passed by the access
parameter to allow the consumers to read all of the data. The limit
dn.exact="${replica_dn}" time.soft=unlimited time.hard=unlimited size.soft=unlimited size.hard=unlimited
is also prepended to any limits passed
with the limits
parameter.
Maps to the olcSpCheckpoint
attribute.
Maps to the olcSpSessionlog
attribute.
An array of olcSyncrepl
attribute values used to establish a replication
relationship between this server and a producer.
Specify the maximum number of seconds slapd
will spend answering a search
request. Maps to the olcTimeLimit
attribute set on the frontend
database.
Setting this to true
will enable the unique
overlay on the main database
allowing the enforcement of attribute value uniqueness.
Maps to the olcUniqueURI
attribute. Values are validated with the
validate_openldap_unique_uri
function.
A referral URI to return for referring writes from a read-only replica server to the original producer/master server.
The user that runs the slapd
process.
Parameters within openldap::configuration
:
Path to the file
resource.
Same as a file
resource, i.e. present
, absent
or file
.
Same as a file
resource.
Same as a file
resource.
Same as a file
resource.
Maps to the BASE
ldap.conf
option.
Maps to the URI
ldap.conf
option.
Maps to the BINDDN
ldap.conf
option.
Maps to the DEREF
ldap.conf
option.
Maps to the NETWORK_TIMEOUT
ldap.conf
option.
Maps to the REFERRALS
ldap.conf
option.
Maps to the SIZELIMIT
ldap.conf
option.
Maps to the TIMELIMIT
ldap.conf
option.
Maps to the TIMEOUT
ldap.conf
option.
Maps to the SASL_MECH
ldap.conf
option.
Maps to the SASL_REALM
ldap.conf
option.
Maps to the SASL_AUTHCID
ldap.conf
option.
Maps to the SASL_AUTHZID
ldap.conf
option.
Maps to the SASL_SECPROPS
ldap.conf
option.
Maps to the SASL_NOCANON
ldap.conf
option.
Maps to the GSSAPI_SIGN
ldap.conf
option.
Maps to the GSSAPI_ENCRYPT
ldap.conf
option.
Maps to the GSSAPI_ALLOW_REMOTE_PRINCIPAL
ldap.conf
option.
Maps to the TLS_CACERT
ldap.conf
option.
Maps to the TLS_CACERTDIR
ldap.conf
option.
Maps to the TLS_CERT
ldap.conf
option.
Maps to the TLS_KEY
ldap.conf
option.
Maps to the TLS_CIPHER_SUITE
ldap.conf
option.
Maps to the TLS_PROTOCOL_MIN
ldap.conf
option.
Maps to the TLS_RANDFILE
ldap.conf
option.
Maps to the TLS_REQCERT
ldap.conf
option.
Maps to the TLS_CRLCHECK
ldap.conf
option.
Maps to the TLS_CRLFILE
ldap.conf
option.
Parameters within openldap::server::schema
:
The Common Name of the schema, i.e. core
, inetorgperson
, etc.
Position of schema in the list. This maps to the DN of the schema object, i.e.
cn={${position}}${name},cn=schema
.
This module always loads the core
schema at position 0 so this should be
from 1 onwards with no gaps.
Hash of additional attributes, defaults to {}
.
LDIF file containing the schema, if not set will default to
${schema_dir}/${name}.ldif
which handles any schema shipped with OpenLDAP.
See the openldap
type.
Defaults to false
, see the openldap
type.
openldap { 'cn=schema,cn=config':
ensure => present,
attributes => {
'cn' => 'schema',
'objectClass' => 'olcSchemaConfig',
},
}
This type autorequires parent objects, (Openldap['cn=config'] -> Openldap['cn=schema,cn=config']
), as well as siblings if they use the OpenLDAP
positional syntax, (Openldap['olcDatabase={0}config,cn=config'] -> Openldap['olcDatabase={1}monitor,cn=config']
). Other relationships should
be explicitly declared if certain objects are required to exist before others.
Parameters within openldap
:
Standard ensurable parameter. Be aware that quite a lot of OpenLDAP configuration settings are additive and that the server will be "unwilling to perform" deletion. For example dynamic modules can be loaded, but cannot be unloaded again.
Hash of object attributes 'name' => 'value'
. In the case of multiple values,
use an array of values 'name' => ['value1', 'value2']
.
If a file resource exists in the catalogue for any value of a known set of
attributes, (olcDbDirectory
, olcTLSCertificateFile
, etc.), then it will be
autorequired.
Controls purging of unknown attributes and/or values. Defaults to true
to
purge anything not explicitly declared but can also be set to false
so that
only missing attributes are added, or partial
which purges any unknown
attribute values for explcitly declared attributes, but will leave alone any
attributes not declared.
Path to LDIF file containing the object definition which is used only if the
object does not exist yet, (This is a shortcut for loading huge schema files
without duplicating the whole schema object in the catalogue). A puppet:///
URL can also be used for the location of the LDIF file.
If a file resource exists in the catalogue for this value it will be autorequired.
The name of the service controlling the slapd
daemon. In order to affect
change the daemon needs to be running first. The service resource will be
autorequired.
Canonicalise and unique an array of index directives.
openldap_unique_indices(['entryCSN,entryUUID eq', 'ou,cn eq,pres,sub', 'entryCSN eq', 'entryUUID eq'])
Prefix an array of values with positional {x}
notation.
openldap_values(['foo', 'bar'])
Validate an array of LDAP URI values suitable for configuring the unique
overlay.
validate_openldap_unique_uri('dc=example,dc=com', ['ldap:///?uidNumber?sub'])
validate_openldap_unique_uri('dc=example,dc=com', ['ldap:///ou=people,dc=example,dc=com?uidNumber?sub'])
Install the LDAP libraries and create a global ldap.conf
mimicking the stock
RHEL/CentOS install as well as a per-user .ldaprc
for any subsequently
created users. Also install the client utilities:
class { '::openldap':
tls_cacertdir => '/etc/openldap/certs'
}
::openldap::configuration { '/etc/skel/.ldaprc':
ensure => file,
owner => 0,
group => 0,
mode => '0640',
base => 'dc=example,dc=com',
uri => ['ldap://ldap.example.com/'],
}
::Openldap::Configuration['/etc/skel/.ldaprc'] -> User <||>
include ::openldap::client
Create a standalone directory server listening on the standard LDAP TCP port 389 that disallows anonymous reads and allows users to update their own object:
include ::openldap
include ::openldap::client
class { '::openldap::server':
root_dn => 'cn=Manager,dc=example,dc=com',
root_password => '{SSHA}7dSAJPGe4YKKEvUPuGJIeSL/03GV2IMY',
suffix => 'dc=example,dc=com',
access => [
'to attrs=userPassword by self =xw by anonymous auth',
'to * by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth" manage by self write by users read',
],
indices => [
'objectClass eq,pres',
'ou,cn,mail,surname,givenname eq,pres,sub',
],
ldap_interfaces => [$ipaddress],
}
::openldap::server::schema { 'cosine':
position => 1,
}
::openldap::server::schema { 'inetorgperson':
position => 2,
}
::openldap::server::schema { 'nis':
position => 3,
}
Extend the above example to become a producer/master server for a number of consumer/slave servers:
include ::openldap
include ::openldap::client
class { '::openldap::server':
root_dn => 'cn=Manager,dc=example,dc=com',
root_password => '{SSHA}7dSAJPGe4YKKEvUPuGJIeSL/03GV2IMY',
suffix => 'dc=example,dc=com',
access => [
'to attrs=userPassword by self =xw by anonymous auth',
'to * by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth" manage by self write by users read',
],
indices => [
'objectClass eq,pres',
'ou,cn,mail,surname,givenname eq,pres,sub',
],
ldap_interfaces => [$ipaddress],
replica_dn => 'cn=replicator,dc=example,dc=com',
syncprov => true,
}
::openldap::server::schema { 'cosine':
position => 1,
}
::openldap::server::schema { 'inetorgperson':
position => 2,
}
::openldap::server::schema { 'nis':
position => 3,
}
Extend this further to also enable delta replication:
include ::openldap
include ::openldap::client
class { '::openldap::server':
root_dn => 'cn=Manager,dc=example,dc=com',
root_password => '{SSHA}7dSAJPGe4YKKEvUPuGJIeSL/03GV2IMY',
suffix => 'dc=example,dc=com',
access => [
'to attrs=userPassword by self =xw by anonymous auth',
'to * by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth" manage by self write by users read',
],
accesslog => true,
indices => [
'objectClass eq,pres',
'ou,cn,mail,surname,givenname eq,pres,sub',
],
ldap_interfaces => [$ipaddress],
replica_dn => 'cn=replicator,dc=example,dc=com',
syncprov => true,
}
::openldap::server::schema { 'cosine':
position => 1,
}
::openldap::server::schema { 'inetorgperson':
position => 2,
}
::openldap::server::schema { 'nis':
position => 3,
}
Create a server acting as a consumer of another server using delta replication and pass back a referral to clients on attempting to write:
include ::openldap
include ::openldap::client
class { '::openldap::server':
root_dn => 'cn=Manager,dc=example,dc=com',
root_password => '{SSHA}7dSAJPGe4YKKEvUPuGJIeSL/03GV2IMY',
suffix => 'dc=example,dc=com',
access => [
'to attrs=userPassword by self =xw by anonymous auth',
'to * by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth" manage by self write by users read',
],
indices => [
'objectClass eq,pres',
'ou,cn,mail,surname,givenname eq,pres,sub',
],
ldap_interfaces => [$ipaddress],
syncrepl => [
'rid=001 provider=ldap://ldap.example.com/ searchbase="dc=example,dc=com" bindmethod=simple binddn="cn=replicator,dc=example,dc=com" credentials=secret logbase="cn=log" logfilter="(&(objectClass=auditWriteObject)(reqResult=0))" schemachecking=on type=refreshAndPersist retry="60 +" syncdata=accesslog',
],
update_ref => 'ldap://ldap.example.com/',
}
::openldap::server::schema { 'cosine':
position => 1,
}
::openldap::server::schema { 'inetorgperson':
position => 2,
}
::openldap::server::schema { 'nis':
position => 3,
}
Extend the standalone example with support for synchronising passwords between POSIX and Samba:
include ::openldap
include ::openldap::client
class { '::openldap::server':
root_dn => 'cn=Manager,dc=example,dc=com',
root_password => '{SSHA}7dSAJPGe4YKKEvUPuGJIeSL/03GV2IMY',
suffix => 'dc=example,dc=com',
access => [
'to attrs=userPassword by self =xw by anonymous auth',
'to attrs=sambaLMPassword,sambaNTPassword by self =w',
'to * by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth" manage by self write by users read',
],
indices => [
'objectClass eq,pres',
'ou,cn,mail,surname,givenname eq,pres,sub',
],
ldap_interfaces => [$ipaddress],
smbk5pwd => true,
smbk5pwd_backends => ['samba'],
}
::openldap::server::schema { 'cosine':
position => 1,
}
::openldap::server::schema { 'inetorgperson':
position => 2,
}
::openldap::server::schema { 'nis':
position => 3,
}
package { 'samba':
ensure => present,
}
::openldap::server::schema { 'samba':
ldif => '/usr/share/doc/samba-4.1.12/LDAP/samba.ldif',
position => 4,
require => Package['samba'],
}
openldap
: Main class for installing base LDAP library.openldap::client
: Main class for installing LDAP client utilities.openldap::server
: Main class for installing and managingslapd
daemon.
openldap::config
: Handles base LDAP library configuration.openldap::install
: Handles base LDAP library installation.openldap::params
: Different configuration data for different systems.openldap::client::install
: Handles LDAP client utility installation.openldap::server::config
: Handlesslapd
configuration.openldap::server::install
: Handlesslapd
installation.openldap::server::service
: Handles starting theslapd
daemon.
openldap::configuration
: Handles creating global or per-user LDAP client configuration.openldap::server::schema
: Installs and enables LDAP schemas inslapd
.
openldap
: Manages a configuration object in theslapd
OLC (cn=config
) DIT.
openldap_unique_indices
: Canonicalises and uniques a set of indices.openldap_values
: Adds a positional{x}
prefix to an array of values.validate_openldap_unique_uri
: Validates an array of URI values suitable for configuring theunique
overlay.
Rather than expose overlays, modules, databases, etc. as defined or native types and leave the user to build their own configuration this module takes the decision to hide most of this complexity and build what most people probably want out of OpenLDAP; a single database, possibly replicated. This is largely due to a number of behaviours and idiosyncrasies of OpenLDAP; the order of overlays matters for example.
As alluded to by the openldap
native type, a lot of
attributes or objects are additive and can't be deleted without manually
editing the configuration. This module will always try and issue the necessary
LDIF commands however the server will be "unwilling to perform" them. This
means that if you try to convert from say a replicating producer back to a
standalone server you will probably get errors from trying to remove the
various replication objects. However things should always build from scratch
cleanly.
This module has been built on and tested against Puppet 3.0 and higher.
The module has been tested on:
- RedHat/CentOS Enterprise Linux 6/7
- Ubuntu 12.04/14.04
- Debian 6/7
It should also probably work on:
- Fedora 19/20 (need vagrant boxes for tests)
Testing on other platforms has been light and cannot be guaranteed.
Please log issues or pull requests at github.