lnemsick-simp / pupmod-simp-ds389

389 DS SIMP Puppet Module

Table of Contents

• Description
• This is a SIMP module
• Setup
  • Beginning with ds389
    • Enabling the default instance
• Usage
  • Creating additional instances
  • Deleting instances
  • Enabling the remote admin interface
  • Running the 389DS management console GUI
• Reference
• Limitations
• Development
  • Unit tests
  • Acceptance tests

Description

This module manages the 389 Directory Server (389DS), an enterprise-class open source LDAP server for Linux. Options are provided to both create a default LDAP instance and to bootstrap it with SIMP's traditional LDAP hierarchy.

The module is named ds389 because Puppet modules cannot start with a digit.

This is a SIMP module

This module is a component of the System Integrity Management Platform

If you find any issues, please submit them via JIRA.

Please read our Contribution Guide.

This module should be used within the SIMP ecosystem and will be of limited independent use when included on its own.

Setup

Beginning with ds389

To set up a 389DS server, simply include ds389. This will create a server with no active instances and can be fully managed by hand.

Usage

Creating instances

389DS can host any number of LDAP instances but you need to ensure that all port numbers are unique! If port numbers overlap, then issues will arise when managing the services.

You must specify a base_dn and a root_dn for each instance, since these are what define both the root of the directory (base_dn) and the administrative user of the directory (root_dn). These can overlap between instances but it is recommended that you keep them unique.

---
ds389::instances:
  test:
    base_dn: 'dc=test,dc=domain'
    root_dn: 'cn=Test Admin'
    listen_address: '0.0.0.0'
    port: 380
  test2:
    base_dn: 'dc=some other,dc=space'
    root_dn: 'cn=Directory Manager'
    listen_address: '0.0.0.0'
    port: 381

To access data on these instances, you need to direct your command to the appropriate port.

For example, to access the test instance:

ldapsearch -x \
  -y "/usr/share/puppet_ds389_config/test_ds_pw.txt" \
  -D "cn=Directory Manager" \
  -h `hostname -f` \
  -p 380 \
  -b "dc=test,dc=domain"

Deleting instances

LDAP instances are NOT automatically purged when they cease being managed by Puppet. This is a safety precaution, to protect users who may have set up instances using some other method, like the management console GUI. Automatic purging could result in the catastrophic loss of such valid yet unmanaged LDAP instances.

If you wish to remove an instance, you can either do it directly in Puppet:

ds389::instance { 'test2':
  ensure => 'absent'
}

Or you can do it in Hiera:

---
ds389::instances:
  test:
    listen_address: '0.0.0.0'
    port: 380
  test2:
    ensure: absent

Just remember that Puppet will attempt to remove this instance every time it runs! This means that if you create an instance by hand with the name test2 then Puppet will remove it at the next run.

Reference

See REFERENCE.md for module API documentation.

For more details about 389DS, please see the vendor documentation.

Configuration item details can be found in the cn=config documentation.

Limitations

This is still a work in progress and breaking changes may occur until 1.0.0

Development

Please read our Contribution Guide.

Unit tests

Unit tests, written in rspec-puppet can be run by calling:

bundle exec rake spec

Acceptance tests

To run the system tests, you need Vagrant installed. Then, run:

bundle exec rake beaker:suites

Some environment variables may be useful:

BEAKER_debug=true
BEAKER_provision=no
BEAKER_destroy=no
BEAKER_use_fixtures_dir_for_modules=yes

• BEAKER_debug: show the commands being run on the STU and their output.
• BEAKER_destroy=no: prevent the machine destruction after the tests finish so you can inspect the state.
• BEAKER_provision=no: prevent the machine from being recreated. This can save a lot of time while you're writing the tests.
• BEAKER_use_fixtures_dir_for_modules=yes: cause all module dependencies to be loaded from the spec/fixtures/modules directory, based on the contents of .fixtures.yml. The contents of this directory are usually populated by bundle exec rake spec_prep. This can be used to run acceptance tests to run on isolated networks.