puppet-ds_389

Table of Contents

1. Overview
2. Requirements
3. Usage
   • Basic usage
   • Instances
   • Initialize suffix
   • SSL
   • Plugins
   • Backups
   • Replication overview
   • Replication consumer
   • Replication hub
   • Replication supplier
   • Initializing replication
   • Schema extensions
   • Modifying existing LDIF data
   • Adding new LDIF data
   • Adding baseline LDIF data
   • Recreate SSL certs
4. Reference
5. Limitations
   • Supported versions
   • Migrating from spacepants module
6. Development
   • Contributing
   • Fork
7. License

Overview

This module installs and manages the 389 Directory Server. It will create and bootstrap 389 DS instances, configure SSL, replication, schema extensions and even load LDIF data.

SSL is enabled by default using self-signed certificates, but existing SSL certificates may also be used and will automatically be imported into the 389 DS instance.

Replication is supported for consumers, hubs, and suppliers (both master and multi-master), and there is a Puppet task to reinitialize replication.

Requirements

This module requires 389-ds version 1.4 or later. Older versions are incompatible.

Usage

Basic usage

include ds_389

At a bare minimum, the module ensures that the 389 DS base package and NSS tools are installed and sets appropiate resource limits.

Instances

The primary resource for configuring a 389 DS service is the ds_389::instance define:

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  server_id    => $facts['networking']['hostname'],
}

In this example an instance is created with the server ID set to the hostname of the node. For a node with a hostname of foo, this would create an instance at /etc/dirsrv/slapd-foo that listens on the default ports of 389 and 636 (for SSL).

Initialize suffix

When creating new instances, it is possible to initialize the specified suffix by using the $create_suffix parameter. The new instance will create a generic root node entry for the suffix in the database. This is most useful when bootstrapping a new LDAP.

SSL

When existing SSL certificates should be used, they could be passed to the instance with the $ssl parameter. This parameter expects a hash with paths (either local file paths on the node or a puppet:/// path) for the PEM files for the certificate, key, and CA bundle. It also requires the certificate nickname for the cert and every CA in the bundle. (pk12util sets the nickname for the certificate to the friendly name of the cert in the pkcs12 bundle, and the nickname for each ca cert to "${the common name(cn) of the ca cert subject} - ${the organization(o) of the cert issuer}".)

To require StartTLS for non-SSL connections, the $minssf parameter should be used to specify the minimum required encryption.

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  server_id    => $facts['networking']['hostname'],
  minssf       => 128,
  ssl          => {
    'cert_path'      => 'puppet:///path/to/ssl_cert.pem',
    'key_path'       => 'puppet:///path/to/ssl_key.pem',
    'ca_bundle_path' => 'puppet:///path/to/ssl_ca.pem',
    'ca_cert_names'  => [
      'Certificate nickname for the first CA cert goes here',
      'Certificate nickname for another CA cert goes here',
    ],
    'cert_name'      => 'Certificate nickname goes here',
  },
}

Plugins

In order to enable or disable some of the 386 DS plugins, the plugin name and a simple string should be added to the $plugins parameter:

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  server_id    => $facts['networking']['hostname'],
  plugins      => {
    'memberof'      => 'enabled',
    'posix-winsync' => 'disabled',
  },
}

When additional plugin options need to be configured, a hash should be used instead:

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  server_id    => $facts['networking']['hostname'],
  plugins      => {
    'memberof'      => {
      ensure  => 'enabled',
      options => [
        'set --groupattr uniqueMember',
        'set --allbackends on',
        'set --skipnested off',
      ],
    },
    'posix-winsync' => 'disabled',
  },
}

To use the defined type directly, the server id of the instance as well as the root dn and password must be provided:

ds_389::plugin { 'memberof':
  ensure       => 'enabled',
  options      => [
    'set --groupattr uniqueMember',
    'set --allbackends on',
    'set --skipnested off',
  ],
  server_id    => 'example',
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
}

Backups

To perform online backups of a directory, the $backup_enable parameter should be used:

ds_389::instance { 'example':
  backup_enable => true,
  root_dn       => 'cn=Directory Manager',
  root_dn_pass  => 'supersecret',
  suffix        => 'dc=example,dc=com',
  cert_db_pass  => 'secret',
  server_id     => $facts['networking']['hostname'],
}

This will enable a backup job with default parameters that is scheduled to run every night. If the backup was successful, an empty file /tmp/389ds_backup_success is created and the modification time is updated. This will make it easy to monitor the status of the directory backup (by checking for the existence of the file and it's modification time).

To use the defined type directly, the server id of the instance as well as the root dn and password must be provided:

ds_389::backup { 'Perform hourly backups of the directory':
  ensure       => 'present',
  server_id    => 'example',
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  backup_dir   => '/path/to/ds-backups',
  rotate       => 10,
  time         => ['0', '*', '*'],
  success_file => '/tmp/hourly_backup_success',
}

Replication overview

To set up replication, the $replication parameter should be used to add the replication config. At a minimum, it expects a hash with the replication bind dn, replication bind dn password, and replication role (either 'consumer', 'hub', or 'supplier').

Replication consumer

Example config for a consumer role:

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  server_id    => $facts['networking']['hostname'],
  replication  => {
    'replication_pass' => 'secret',
    'role'             => 'consumer',
  },
}

This would ensure that the replica bind dn and credentials are present in the instance.

Replication hub

For a hub, any consumers for the hub should be passed as an array of server IDs:

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  server_id    => $facts['networking']['hostname'],
  replication  => {
    'replication_pass' => 'secret',
    'role'             => 'hub',
    'consumers'        => [
      'consumer1',
      'consumer2',
    ],
  },
}

The replication agreement will then be created and added to the instance.

Replication supplier

For a supplier, consumers need to be passed as an array, and also any hubs or other suppliers (if running in multi-master) that should be present in the instance. The replica ID for the supplier must also be provided.

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  server_id    => $facts['networking']['hostname'],
  replication  => {
    'replication_pass' => 'secret',
    'role'             => 'hub',
    'suppliers'        => [
      'supplier1',
      'supplier2',
    ],
    'hubs'             => [
      'hub1',
      'hub2',
    ],
    'consumers'        => [
      'consumer1',
      'consumer2',
    ],
  },
}

Initializing replication

Once replication has been configured on all of the desired nodes, replication can be initialized for consumers, hubs, and/or other suppliers by passing the appropriate "init_" parameters:

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  server_id    => $facts['networking']['hostname'],
  replication  => {
    'replication_pass' => 'secret',
    'role'             => 'hub',
    'suppliers'        => [
      'supplier1',
      'supplier2',
    ],
    'hubs'             => [
      'hub1',
      'hub2',
    ],
    'consumers'        => [
      'consumer1',
      'consumer2',
    ],
    'init_suppliers'   => true,
    'init_hubs'        => true,
    'init_consumers'   => true,
  },
}

Replication can also be initialize (or reinitialize) with the Puppet task.

Schema extensions

If a schema extension needs to be added, the $schema_extensions parameter should be used. This parameter expects a hash with the desired ldif filename as the key, and a source reference (either via puppet:/// or an absolute path on the node):

ds_389::instance { 'example':
  root_dn           => 'cn=Directory Manager',
  root_dn_pass      => 'supersecret',
  suffix            => 'dc=example,dc=com',
  cert_db_pass      => 'secret',
  schema_extensions => {
    '99example_schema' => 'puppet:///path/to/example_schema.ldif',
  },
}

Note that schema filenames are typically prefixed with a number that indicates the desired schema load order.

Modifying existing LDIF data

If the default ldif data (typically configs) needs to be modified, the $modify_ldifs parameter should be used. This parameter expects a hash with the desired ldif filename as the key, and a source reference (either via puppet:/// or an absolute path on the node):

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  modify_ldifs => {
    'example_ldif_modify' => 'puppet:///path/to/example_modify.ldif',
  },
}

The ldif file is then created and passed to ldapmodify to load it into the instance.

To use the defined type directly, by calling their define directly, but the server id of the instance as well as the root dn and password must be provided:

ds_389::modify { 'example_ldif_modify':
  server_id    => 'example',
  source       => 'puppet:///path/to/example_modify.ldif',
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
}

Adding new LDIF data

If new ldif data (typically configs) needs to be added, the $add_ldifs parameter should be used. This parameter expects a hash with the desired ldif filename as the key, and a source reference (either via puppet:/// or an absolute path on the node):

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  add_ldifs    => {
    'example_ldif_add' => 'puppet:///path/to/example_add.ldif',
  },
}

This works similar to the modify_ldifs parameter, but it utilizes ldapadd instead of ldapmodify.

To use the defined type directly, the server id of the instance as well as the root dn and password must be provided:

ds_389::add { 'example_ldif_add':
  server_id    => 'example',
  source       => 'puppet:///path/to/example_add.ldif',
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
}

Adding baseline LDIF data

To load baseline ldif data that runs after any other ldif configuration changes, the $base_load_ldifs parameter should be used:

ds_389::instance { 'example':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecret',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  base_load_ldifs    => {
    'example_ldif_baseline' => 'puppet:///path/to/example_baseline.ldif',
  },
}

Note that while it's possible declare these via the ds_389::add defined type, Puppet's resource load ordering may potentially result in it attempting to add the ldif before a configuration change that it requires.

Recreate SSL certs

Currently some manual steps are required to regenerate the SSL certificates. A new Bolt task would be nice, PRs are welcome. :)

A backup should be created before attempting this procedure.

The following shell commands need to be run as root to remove the existing certificates:

export LDAP_INSTANCE="my-instance-name"

test -d /etc/dirsrv/slapd-${LDAP_INSTANCE} || exit 1

systemctl stop dirsrv@${LDAP_INSTANCE}

dd if=/dev/random count=1024 | sha256sum | awk '{print $1}' > /tmp/noisefile-${LDAP_INSTANCE}
cut -d: -f2 /etc/dirsrv/slapd-${LDAP_INSTANCE}/pin.txt > /tmp/passfile-${LDAP_INSTANCE}

rm -f /etc/dirsrv/slapd-${LDAP_INSTANCE}/${LDAP_INSTANCE}CA.cnf \
  /etc/dirsrv/slapd-${LDAP_INSTANCE}/${LDAP_INSTANCE}CA-Key.pem \
  /etc/dirsrv/slapd-${LDAP_INSTANCE}/${LDAP_INSTANCE}CA.p12 \
  /etc/dirsrv/slapd-${LDAP_INSTANCE}/${LDAP_INSTANCE}CA.pem \
  /etc/dirsrv/slapd-${LDAP_INSTANCE}/${LDAP_INSTANCE}Cert-Key.pem \
  /etc/dirsrv/slapd-${LDAP_INSTANCE}/${LDAP_INSTANCE}Cert.pem \
  /etc/dirsrv/slapd-${LDAP_INSTANCE}/ssl_config.done \
  /etc/dirsrv/slapd-${LDAP_INSTANCE}/ssl.done \
  /etc/dirsrv/slapd-${LDAP_INSTANCE}/ssl_enable.done \
  /etc/dirsrv/slapd-${LDAP_INSTANCE}/ssl.ldif

certutil -D -n "${LDAP_INSTANCE}Cert" -d /etc/dirsrv/slapd-${LDAP_INSTANCE}
certutil -D -n "${LDAP_INSTANCE}CA" -d /etc/dirsrv/slapd-${LDAP_INSTANCE}

Next the file /etc/dirsrv/slapd-${LDAP_INSTANCE}/dse.ldif needs to be modified and the following entries including their attributes must be removed:

  cn=AES,cn=encrypted attribute keys,cn=database_name,cn=ldbm database,cn=plugins,cn=config
  cn=3DES,cn=encrypted attribute keys,cn=database_name,cn=ldbm database,cn=plugins,cn=config

Afterwards Puppet should be used to regenerate both the CA and the server certificates.

Reference

Classes and parameters are documented in REFERENCE.md.

Limitations

Supported versions

This module requires 389-ds version 1.4 or later. When using an older version of 389-ds, consider using spacepants/puppet-ds_389 instead. It is no longer under active development, but it may still be useful to migrate to an up-to-date version of 389-ds.

In newer versions of 389-ds the "master" role was renamed to "supplier" in an backwards-incompatible way. The $supplier_role_name parameter can be used to change the role name accordingly.

Migrating from spacepants module

Version 2.x of this module contains migration tasks for users of spacepants/puppet-ds_389. They will ensure that the SSL status as well as the replication status of suppliers, hubs and consumers is preserved. However, it is strongly recommended to setup a test environment or at least run Puppet Agent with --noop when migrating to this module.

Development

Contributing

Please use the GitHub issues functionality to report any bugs or requests for new features. Feel free to fork and submit pull requests for potential contributions.

Contributions must pass all existing tests, new features should provide additional unit/acceptance tests.

License

Copyright 2020-2022 Frank Wall

Copyright 2019 Paul Bailey

Reference

Table of Contents

Classes

Public Classes

• ds_389: Manages and configures the 389 Directory Server

Private Classes

• ds_389::install: Install packages, setup user/group and runtime environment for 389 DS.

Defined types

• ds_389::add: Adds an ldif file to a 389 ds instance.
• ds_389::backup: Setup backup jobs for a 389 ds instance.
• ds_389::instance: Manages a 389 ds instance.
• ds_389::modify: Adds an ldif modify file to a 389 ds instance.
• ds_389::plugin: Manages a plugin for a 389 ds instance.
• ds_389::replication: Sets up replication for a 389 ds instance.
• ds_389::schema: Adds a schema extension ldif file to a 389 ds instance.
• ds_389::service: Manages the service for a 389 ds instance.
• ds_389::ssl: Manages SSL for a 389 ds instance.

Tasks

• reinit_consumer: Allows you to reinitialize replication for a consumer

Classes

ds_389

Manages and configures the 389 Directory Server

Examples

include ds_389

Parameters

The following parameters are available in the ds_389 class.

cacert_rehash

Data type: String

The command that is used to rehash CA certificates.

cacerts_path

Data type: Stdlib::Absolutepath

Target directory the 389 ds certs should be exported to. Default: '/etc/openldap/cacerts'

dnf_module_name

Data type: Optional[String]

The name of the DNF module that should be enabled on RHEL. Optional.

Default value: undef

dnf_module_version

Data type: Optional[String]

The version of the DNF module that should be enabled on RHEL. Optional.

Default value: undef

group

Data type: String

Group account 389 ds user should belong to. Default: 'dirsrv'

home_dir

Data type: Stdlib::Absolutepath

Home directory for the 389 ds user account. Default: '/usr/share/dirsrv'

instances

Data type: Hash

A hash of ds_389::instance resources. Optional.

limits_config_dir

Data type: Stdlib::Absolutepath

Target directory for resource limit configuration.

nsstools_package_name

Data type: String

Name of the NSS tools package.

package_ensure

Data type: String

389 ds package state. Default 'installed'

package_name

Data type: Variant[String,Array]

Name of the 389 ds package to install. Default: '389-ds-base'

path

Data type: String

Specifies the content of the PATH environment variable when running commands. Should usually NOT be altered.

service_type

Data type: String

The service manager that should be used.

ssl_dir

Data type: Stdlib::Absolutepath

Target directory for generated SSL certificates.

ssl_version_min_support

Data type: Boolean

Obsolete parameter, only kept for compatibility with spacepants/puppet-ds_389. Will be removed in a later version.

supplier_role_name

Data type: String

In 389-ds the name of the supplier replication role was renamed from 'master' to 'supplier' in a backwards-incompatible fashion (issue #4656).

user

Data type: String

User account 389 ds should run as. Default: 'dirsrv'

user_shell

Data type: String

Shell for the user account. Usually a pseudo-shell to prevent console access.

Defined types

ds_389::add

Adds an ldif file to a 389 ds instance.

Examples

Adding an ldif file with required params.

ds_389::add { 'add_example_1':
  server_id    => 'foo',
  source       => 'puppet:///path/to/file.ldif',
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecure',
}

Adding an ldif file when using a template.

ds_389::add { 'add_example_2':
  server_id    => 'foo',
  content      => epp('profiles/template.ldif.epp'),
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecure',
}

Adding an ldif file when using all params.

ds_389::add { 'add_example_3':
  server_id    => 'foo',
  source       => '/path/to/file.ldif',
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecure',
  server_host  => 'foo.example.com',
  server_port  => 1389,
  user         => 'custom_user',
  group        => 'custom_group',
}

Parameters

The following parameters are available in the ds_389::add defined type.

content

Data type: Optional[String]

The content value to use for the ldif file. Required, unless providing the source.

Default value: undef

group

Data type: String

The group of the created ldif file. Default: $ds_389::group

Default value: $ds_389::group

protocol

Data type: Enum['ldap','ldaps']

The protocol to use when calling ldapadd. Default: 'ldap'

Default value: 'ldap'

root_dn_pass

Data type: Variant[String,Sensitive[String]]

The password to use when calling ldapadd. Required.

root_dn

Data type: String

The bind DN to use when calling ldapadd. Required.

server_host

Data type: String

The host to use when calling ldapadd. Default: $facts['networking']['fqdn']

Default value: $facts['networking']['fqdn']

server_id

Data type: String

The 389 ds instance name. Required.

server_port

Data type: Integer

The port to use when calling ldapadd. Default: 389

Default value: 389

source

Data type: Optional[String]

The source path to use for the ldif file. Required, unless providing the content.

Default value: undef

starttls

Data type: Boolean

Whether to use StartTLS when calling ldapadd. Default: false

Default value: false

user

Data type: String

The owner of the created ldif file. Default: $ds_389::user

Default value: $ds_389::user

ds_389::backup

Setup backup jobs for a 389 ds instance.

Examples

ds_389::backup { 'daily backup':
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecure',
  server_id    => 'instancename',
}

Parameters

The following parameters are available in the ds_389::backup defined type.

backup_dir

Data type: Optional[Stdlib::Absolutepath]

The directory where the backup files will be stored. The directory must be read- and writable for the 389-ds user. Default: /var/lib/dirsrv/slapd-instance/bak

Default value: undef

ensure

Data type: String

This parameter controls whether the backup job should be created (present) or removed (absent).

Default value: 'present'

environment

Data type: Array

Any environment settings associated with the backup cron job. Note that the PATH variable is automatically added to the environment.

Default value: []

protocol

Data type: Enum['ldap','ldaps']

The protocol to use when performing the backup.

Default value: 'ldaps'

root_dn_pass

Data type: Variant[String,Sensitive[String]]

The password to use when performing the backup. Required.

root_dn

Data type: String

The bind DN to use when performing the backup. Required.

rotate

Data type: Integer

The maximum backup age in days. Older backups will be removed.

Default value: 30

time

Data type: Array

An array containing the cron schedule in this order: minute, hour, weekday.

Default value: ['15', '23', '*']

server_host

Data type: String

The host to use when performing the backup. Default: $facts['networking']['fqdn']

Default value: $facts['networking']['fqdn']

server_id

Data type: String

The 389 ds instance name. Required.

server_port

Data type: Integer

The port to use when performing the backup. Default: 636

Default value: 636

success_file

Data type: Stdlib::Absolutepath

Specify a path where upon successful backup a file should be created for checking purposes.

Default value: '/tmp/389ds_backup_success'

ds_389::instance

Manages a 389 ds instance.

Examples

A basic instance with required params.

ds_389::instance { 'foo':
  root_dn      => 'cn=Directory Manager',
  suffix       => 'dc=example,dc=com',
  cert_db_pass => 'secret',
  root_dn_pass => 'supersecure',
  server_id    => 'specdirectory',
}

Parameters

The following parameters are available in the ds_389::instance defined type.

add_ldifs

Data type: Optional[Hash]

A hash of ldif add files. See add.pp. Optional.

Default value: undef

backup_enable

Data type: Boolean

Whether to enable a periodic backup job for this instance.

Default value: false

backup_notls

Data type: Boolean

Whether to disable TLS connection for the backup job.

Default value: false

base_load_ldifs

Data type: Optional[Hash]

A hash of ldif add files to load after all other config files have been added. Optional.

Default value: undef

cert_db_pass

Data type: Variant[String,Sensitive[String]]

The certificate db password to ensure. Required.

create_suffix

Data type: Boolean

Set this parameter to True to create a generic root node entry for the suffix in the database.

Default value: true

group

Data type: String

The group for the instance. Default: $ds_389::group

Default value: $ds_389::group

minssf

Data type: Integer

The minimum security strength for connections. Default: 0

Default value: 0

modify_ldifs

Data type: Optional[Hash]

A hash of ldif modify files. See modify.pp. Optional.

Default value: undef

plugins

Data type: Optional[Hash]

A hash of plugins to enable or disable. See plugin.pp. Optional.

Default value: undef

replication

Data type: Optional[Hash]

A replication config hash. See replication.pp. Optional.

Default value: undef

root_dn_pass

Data type: Variant[String,Sensitive[String]]

The root dn password to ensure. Required.

root_dn

Data type: String

The root dn to ensure. Required.

schema_extensions

Data type: Optional[Hash]

A hash of schemas to ensure. See schema.pp. Optional.

Default value: undef

server_host

Data type: String

The fqdn for the instance. Default: $facts['networking']['fqdn']

Default value: $facts['networking']['fqdn']

server_id

Data type: String

The server identifier for the instance. Default: $facts['networking']['hostname']

Default value: $facts['networking']['hostname']

server_port

Data type: Integer

The port to use for non-SSL traffic. Default: 389

Default value: 389

server_ssl_port

Data type: Integer

The port to use for SSL traffic. Default: 636

Default value: 636

ssl

Data type: Optional[Hash]

An ssl config hash. See ssl.pp. Optional.

Default value: undef

ssl_version_min

Data type: Optional[String]

The minimum TLS version the instance should support. Optional.

Default value: undef

subject_alt_names

Data type: Optional[Array]

An array of subject alt names, if using self-signed certificates. Optional.

Default value: undef

suffix

Data type: String

The LDAP suffix to use. Required.

user

Data type: String

The user for the instance. Default: $ds_389::user

Default value: $ds_389::user

ds_389::modify

Adds an ldif modify file to a 389 ds instance.

Examples

Adding an ldif modify file with required params.

ds_389::modify { 'modify_example_1':
  server_id    => 'foo',
  source       => 'puppet:///path/to/file.ldif',
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecure',
}

Adding an ldif modify file with required params.

ds_389::modify { 'modify_example_2':
  server_id    => 'foo',
  content      => epp('profiles/template.ldif.epp'),
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecure',
}

Adding an ldif modify file when using all params.

ds_389::modify { 'modify_example_3':
  server_id    => 'foo',
  source       => '/path/to/file.ldif',
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecure',
  server_host  => 'foo.example.com',
  server_port  => 1389,
  user         => 'custom_user',
  group        => 'custom_group',
}

Parameters

The following parameters are available in the ds_389::modify defined type.

content

Data type: Optional[String]

The content value to use for the ldif file. Required, unless providing the source.

Default value: undef

group

Data type: String

The group of the created ldif file. Default: $ds_389::group

Default value: $ds_389::group

protocol

Data type: Enum['ldap','ldaps']

The protocol to use when calling ldapmodify. Default: 'ldap'

Default value: 'ldap'

root_dn_pass

Data type: Variant[String,Sensitive[String]]

The password to use when calling ldapmodify. Required.

root_dn

Data type: String

The bind DN to use when calling ldapmodify. Required.

server_host

Data type: String

The host to use when calling ldapmodify. Default: $facts['networking']['fqdn']

Default value: $facts['networking']['fqdn']

server_id

Data type: String

The 389 ds instance name. Required.

server_port

Data type: Integer

The port to use when calling ldapmodify. Default: 389

Default value: 389

source

Data type: Optional[String]

The source path to use for the ldif file. Required, unless providing the content.

Default value: undef

starttls

Data type: Boolean

Whether to use StartTLS when calling ldapmodify. Default: false

Default value: false

user

Data type: String

The owner of the created ldif file. Default: $ds_389::user

Default value: $ds_389::user

ds_389::plugin

Manages a plugin for a 389 ds instance.

Examples

Enable a plugin with required params.

ds_389::plugin { 'memberof':
  server_id    => 'foo',
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecure',
}

Disable a plugin when using all params.

ds_389::plugin { 'memberof':
  ensure       => 'disabled',
  server_id    => 'foo',
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecure',
  server_host  => 'foo.example.com',
  server_port  => 1389,
}

Parameters

The following parameters are available in the ds_389::plugin defined type.

ensure

Data type: Enum['enabled','disabled']

The desired state of the plugin. Default: 'enabled'

Default value: 'enabled'

options

Data type: Array

An array containing additional plugin options. See man 8 dsconf for a complete list. Note that several options can only be applied once, further attempts will fail. Optional.

Default value: []

protocol

Data type: Enum['ldap','ldaps']

The protocol to use when calling ldapadd. Default: 'ldap'

Default value: 'ldap'

root_dn_pass

Data type: Variant[String,Sensitive[String]]

The password to use when calling ldapadd. Required.

root_dn

Data type: String

The bind DN to use when calling ldapadd. Required.

server_host

Data type: String

The host to use when calling ldapadd. Default: $facts['networking']['fqdn']

Default value: $facts['networking']['fqdn']

server_id

Data type: String

The 389 ds instance name. Required.

server_port

Data type: Integer

The port to use when calling ldapadd. Default: 389

Default value: 389

ds_389::replication

Sets up replication for a 389 ds instance.

Examples

A basic consumer with required params.

ds_389::replication { 'consumer1':
  bind_dn          => 'cn=Replication Manager,cn=config',
  replication_pass => 'supersecret',
  root_dn          => 'cn=Directory Manager',
  root_dn_pass     => 'supersecure',
  role             => 'consumer',
  suffix           => 'dc=example,dc=com',
}

A basic hub with 2 consumers.

ds_389::replication { 'hub1':
  bind_dn          => 'cn=Replication Manager,cn=config',
  replication_pass => 'supersecret',
  root_dn          => 'cn=Directory Manager',
  root_dn_pass     => 'supersecure',
  role             => 'hub',
  suffix           => 'dc=example,dc=com',
  consumers        => [
    'consumer1',
    'consumer2',
  ],
}

A basic supplier in multi-master mode with 2 other suppliers and initializing replication.

ds_389::replication { 'supplier1':
  bind_dn          => 'cn=Replication Manager,cn=config',
  replication_pass => 'supersecret',
  root_dn          => 'cn=Directory Manager',
  root_dn_pass     => 'supersecure',
  role             => 'supplier',
  suffix           => 'dc=example,dc=com',
  init_suppliers   => true,
  suppliers        => [
    'supplier1',
    'supplier2',
  ],
}

Parameters

The following parameters are available in the ds_389::replication defined type.

bind_dn

Data type: Optional[String]

The bind dn of the replication user. Required.

Default value: undef

consumers

Data type: Optional[Array]

An array of consumer names to ensure. Optional.

Default value: undef

excluded_attributes

Data type: Optional[Array]

An array of attributes to exclude from replication. Optional.

Default value: undef

group

Data type: String

The group of the created ldif file. Default: $ds_389::group

Default value: $ds_389::group

hubs

Data type: Optional[Array]

An array of hub names to ensure. Optional.

Default value: undef

id

Data type: Optional[Integer]

The replica id. Optional unless declaring a supplier.

Default value: undef

init_consumers

Data type: Boolean

Whether to initialize replication for consumers. Default: false

Default value: false

init_hubs

Data type: Boolean

Whether to initialize replication for hubs. Default: false

Default value: false

init_suppliers

Data type: Boolean

Whether to initialize replication for suppliers. Default: false

Default value: false

protocol

Data type: Enum['ldap','ldaps']

The protocol to use when calling ldapmodify. Default: 'ldap'

Default value: 'ldap'

purge_delay

Data type: Integer

Time in seconds state information stored in replica entries is retained. Default: 604800

Default value: 604800

replica_port

Data type: Integer

The port to use for replication. Default: 389

Default value: 389

replica_transport

Data type: Enum['LDAP','SSL','TLS']

The transport type to use for replication. Default: 'LDAP'

Default value: 'LDAP'

replication_pass

Data type: Variant[String,Sensitive[String]]

The password of the replication user. Required.

replication_user

Data type: String

The user account to use for replication.

Default value: 'Replication Manager'

role

Data type: Enum['supplier','hub','consumer']

Replication role. Either 'supplier', 'hub', or 'consumer'. Required.

root_dn_pass

Data type: Variant[String,Sensitive[String]]

The root dn password for configuring replication. Required.

root_dn

Data type: String

The root dn for configuring replication. Required.

server_host

Data type: String

The host to use when calling ldapmodify. Default: $fqdn

Default value: $facts['networking']['fqdn']

server_port

Data type: Integer

The port to use when calling ldapmodify. Default: 389

Default value: 389

starttls

Data type: Boolean

Whether to use StartTLS when calling ldapmodify. Default: false

Default value: false

suffix

Data type: String

The LDAP suffix to use. Required.

supplier_role_name

Data type: String

In 389-ds the name of the supplier replication role was renamed from 'master' to 'supplier' in a backwards-incompatible fashion (issue #4656).

Default value: $ds_389::supplier_role_name

suppliers

Data type: Optional[Array]

An array of supplier names to ensure. Optional.

Default value: undef

user

Data type: String

The owner of the created ldif file. Default: $ds_389::user

Default value: $ds_389::user

ds_389::schema

Adds a schema extension ldif file to a 389 ds instance.

Examples

Adding a schema extension with required params.

ds_389::schema { '50example':
  server_id => 'foo',
  source    => 'puppet:///path/to/file.ldif',
}

Parameters

The following parameters are available in the ds_389::schema defined type.

group

Data type: String

The group of the created ldif file. Default: $ds_389::group

Default value: $ds_389::group

server_id

Data type: String

The 389 ds instance name. Required.

source

Data type: String

The source path to use for the ldif file. Required.

user

Data type: String

The owner of the created ldif file. Default: $ds_389::user

Default value: $ds_389::user

ds_389::service

Manages the service for a 389 ds instance.

Parameters

The following parameters are available in the ds_389::service defined type.

service_enable

Data type: Boolean

Whether the service should be enabled. Default: true

Default value: true

service_ensure

Data type: String

The state the service should be in. Default: 'running'

Default value: 'running'

ds_389::ssl

Manages SSL for a 389 ds instance.

Examples

ds_389::ssl { 'foo':
  cert_name    => 'fooCert'
  root_dn      => 'cn=Directory Manager',
  root_dn_pass => 'supersecure',
}

Parameters

The following parameters are available in the ds_389::ssl defined type.

cert_name

Data type: String

The nickname of the SSL cert to use. Required.

group

Data type: String

The group of the created ldif file. Default: $ds_389::group

Default value: $ds_389::group

minssf

Data type: Integer

The minimum security strength for connections. Default: 0

Default value: 0

root_dn_pass

Data type: Variant[String,Sensitive[String]]

The password to use when calling ldapmodify. Required.

root_dn

Data type: String

The bind DN to use when calling ldapmodify. Required.

server_host

Data type: String

The host to use when calling ldapmodify. Default: $facts['networking']['fqdn']

Default value: $facts['networking']['fqdn']

server_port

Data type: Integer

The port to use when calling ldapmodify. Default: 389

Default value: 389

server_ssl_port

Data type: Integer

The port to use for SSL traffic. Default: 636

Default value: 636

ssl_version_min

Data type: String

The minimum TLS version to allow. Default: 'TLS1.1'

Default value: 'TLS1.1'

user

Data type: String

The owner of the created ldif file. Default: $ds_389::user

Default value: $ds_389::user

Tasks

reinit_consumer

Allows you to reinitialize replication for a consumer

Supports noop? false

Parameters

instance_name

Data type: String[1]

Directory Server instance name

replica_name

Data type: String[1]

Replica name to initialize

suffix

Data type: String[1]

LDAP suffix to use

server_host

Data type: String[1]

Host to connect to

server_port

Data type: Integer

SSL port to connect to

protocol

Data type: String[1]

Connection protocol

starttls

Data type: Boolean

Connect with StartTLS

root_dn

Data type: String[1]

The root dn to bind as

root_dn_pass

Data type: String[1]

The root dn password

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

[3.0.0] - 2022-10-08

This new major release breaks compatibility with spacepants/ds_389. Users should first migrate to version 2.x of this module when coming from spacepants/ds_389.

Added

• Add new parameter $supplier_role_name (set to either 'master' or 'supplier')

Changed

• Use the 'path' parameter for 'ssl_pkey' and 'x509_cert' resources (#2)

Fixed

• Fix compatibility with recent versions of 389-ds (through $supplier_role_name)
• Do not ignore failures when running ldapadd (#4)
• Revive acceptance tests

Removed

• Remove migration path for spacepants/ds_389

2.7.0 - 2022-10-05

Added

• Add documentation for all parameters

Changed

• Replace dependency camptocamp/openssl with puppet/openssl
• Migrate tests to GitHub Actions

Fixed

• Fix unit tests

Removed

• Drop Ubuntu 18.04 support

2.6.0 - 2022-09-21

Changed

• Update os versions and Puppet version
• Update PDK from 1.8.0 to 2.5.0

Fixed

• Fix puppet-lint offenses
• Fix unit tests

2.5.0 - 2021-01-20

Added

• Add parameter $backup_notls to defined type ds_389::instance

Changed

• Allow Puppet 7

2.4.0 - 2020-11-30

Added

• Add parameter $environment to defined type ds_389::backup

Changed

• Add PATH environment variable to default backup cron job

Fixed

• Fix "command not found" error in backup cron job due to missing PATH variable

2.3.0 - 2020-11-18

Added

• Add defined type to manage backup jobs: ds_389::backup

Fixed

• Protect passwords by not displaying a diff when the password file changes

2.2.0 - 2020-11-16

This release fixes a major bug when using self-signed certificates. In previous releases the internal CA certificate was created without the required extensions. As a result, using LDAPS could lead to various SSL errors. Note that only new CA certificates will benefit from this bugfix. The README contains instructions to purge the existing SSL certificates.

Added

• Add new dependency: camptocamp/openssl

Changed

• Use camptocamp/openssl to generate CA certificates

Fixed

• Fix broken CA certificates by including the required CA extensions
• Fix missing newline in cert bundle

2.1.0 - 2020-11-07

Added

• Add new parameter $options to provide additional plugin configuration

Fixed

• Fix resource ordering: skip plugins on error

2.0.0 - 2020-11-01

This is the first release after forking the module. It aims to be compatible with spacepants/ds_389, but please read the migration notes in the README.

Added

• Add new parameter $create_suffix
• Add ability to manage 389-ds plugins
• Add migration path for users of spacepants/puppet-ds_389
• Add acceptance test for multi-master replication

Changed

• Drop legacy tool usage (setup-ds.pl)
• Migrate params.pp to Hiera module data
• Convert erb templates to epp
• Refactor SSL setup/config to use new tools wherever possible
• Refactor support for nsds5replicatedattributelist ($excluded_attributes)
• Refactor support for nsDS5ReplicaPurgeDelay ($purge_delay)
• Use modern facts instead of $::fqdn, $::hostname, etc.
• Update to PDK 1.18.1
• Limit OS support to versions that include 389-ds 1.4
• Update unit tests
• Update acceptance tests

Fixed

• Fix resource ordering: a service restart could break the initialization of the replication

1.1.7 - 2018-03-13

This release fixes an issue when setting the file descriptor limit on Debian systems.

Changed

• Fix limits config dir on Debian.

1.1.6 - 2018-01-29

Summary

This release fixes a replication issue for consumers and hubs.

Changed

• Set the replica id for consumers and hubs.

1.1.5 - 2018-01-19

This release adds some additional fixes for replication.

Changed

• Fixed a bug where the nsDS5ReplicaRoot wasn't being set correctly in the replication agreement.
• Cleaned up replication attributes.
• Made the replication agreement cn more explicit.

1.1.4 - 2018-01-18

Fixed a bug with replication logic.

Changed

• Check for fqdn when setting replication.

1.1.3 - 2018-01-18

This release adds additional support for StartTLS. ldapadd and ldapmodify actions now connect via the URI, and can connect with StartTLS via the starttls param. nsDS5ReplicaTransportInfo can be set to 'TLS' as well.

Changed

• ldapadd / ldapmodify commands now connect via URI.
• ldapadd / ldapmodify commands now can connect with StartTLS.

1.1.2 - 2018-01-12

This release adds the ability to customize nsDS5ReplicaTransportInfo for replication. It defaults to 'LDAP', but can be set to 'SSL' via the replica_transport param.

Changed

• Parameterize replication transport.
• ldapadd / ldapmodify commands now default to port 389 instead of 636.

1.1.1 - 2018-01-05

This release adds the ability to specify the minssf setting that controls StartTLS for non-SSL connections.

Changed

• Parameterize nsslapd-minssf.
• Default nsslapd-minssf value changed to package default.
• ldif files are passed to ldapmodify directly instead of piping from stdout.

1.1.0 - 2017-12-18

This release adds the ability to manage the content of both ds_389::add and ds_389::modify ldif files. This allows for better secret management and the use of template(), inline_template(), or inline_epp() when declaring these defined types.

Changed

• Expose the content of an ldif file to allow for template-based management.
• Clean up references to the replication manager.
• The bind_dn_pass param for replication has been replaced with replication_pass.
• Added replication_user which defaults to 'Replication Manager'.
• bind_dn is now optional, and allows the bind DN for replication to be overriden if needed.

1.0.0 - 2017-10-27

• Initial release.