Puppet port389 Module

Table of Contents

1. Overview
2. Description
3. Usage
   • Example
   • Classes
   • Types
   • Functions
4. Limitations
   • Tested Platforms
5. Versioning
6. Support
7. See Also

Overview

Manages the port 389 Directory Server

Description

This is a module for the management of the 389 Directory Server aka 389 DS aka port 389 aka Fedora Directory Server aka Red Hat Directory Server. It aims to cover most common initial provisioning needs but replication is not yet support.

Usage

As the typical installation of 389 DS is done with the setup-ds-admin.pl script, this module attemps to provide an API that's highly analogus to the keys in the .inf that may optionally be passed to the configuration script for so called unattneded installs.

##Example

# java is needed if you want to use the 389-console, otherwise - no needed for installation
include java

# augeasproviders must be in a working state to enable server tuning
include augeas

class { 'port389':
  enable_tuning              => true,
  admin_domain               => 'example.org',
  config_directory_admin_pwd => 'password',
  server_admin_pwd           => 'password',
  root_dn_pwd                => 'password',
  enable_ssl                 => true,
  enable_server_admin_ssl    => false,
  ssl_cert                   => '/tmp/example.org.pem',
  ssl_key                    => '/tmp/example.org.key',
  ssl_ca_certs               => {
    'AlphaSSL CA'        => '/tmp/alphassl_intermediate.pem',
    'GlobalSign Root CA' => '/tmp/globalsign_root.pem',
  },
  require                    => Class['augeas'],
}

port389::instance { 'ldap1':
  schema_file => '/tmp/mycustomschema.ldif',
}

##Classes

# defaults
class { 'port389':
  ensure                     => 'present',
  package_ensure             => 'httpd',
  package_name               => [
    '389-admin',
    '389-admin-console',
    '389-admin-console-doc',
    '389-adminutil',
    '389-adminutil-devel',
    '389-console',
    '389-ds',
    '389-ds-base',
    '389-ds-base-devel',
    '389-ds-base-libs',
    '389-ds-console',
    '389-ds-console-doc',
  ],
  enable_tuning              => false,
  user                       => 'nobody',
  group                      => 'nobody',
  admin_domain               => $::domain,
  config_directory_admin_id  => 'admin',
  config_directory_admin_pwd => 'password',
  config_directory_ldap_url  => "ldap://${::fqdn}:389/o=NetscapeRoot",
  full_machine_name          => $::fqdn,
  server_admin_port          => '9830',
  server_admin_id            => 'admin',
  server_admin_pwd           => 'password',
  server_ipaddress           => '0.0.0.0',
  root_dn                    => 'cn=Directory Manager',
  root_dn_pwd                => 'password',
  server_port                => '389',
  setup_dir                  => '/var/lib/dirsrv/setup',
  enable_ssl                 => false,
  enable_server_admin_ssl    => false,
  ssl_server_port            => '636',
  ssl_cert                   => undef,
  ssl_key                    => undef,
  ssl_ca_certs               => {},
}

• ensure

  String defaults to present

  Must be one of present, absent, latest, purged. Provides typical package ensurable semantics with the exception of the purge value which will attempt to delete all 389 associated data and configuration from your system.

• package_ensure

  String|Array defaults to httpd

  A list of packages to ensure the existance of with the ensure_packages() function from stdlib. This is neeeded because the 389 admin server packages from EL do not have a dependency on apache.

• package_name

  Array defaults to [ '389-admin', ... ]

  The list of packages to manage as providing 389 ds.

• enable_tuning

  Bool defaults to false

  Enables/disable automatically tuning the system per the Red Hat Directory Server 9.0 Performance Tuning Guide section on Optimizing System Performance.

• user

  String defaults to nobody

  The role user account that owns the DS files and the slapd daemons are run as.

• group

  String defaults to nobody

  The role group.

The following parameters directly control values in the .inf file passed to setup-ds-admin.pl to create directory service instances. CamelCase .inf keys are represented as lowercase parameters names with _s between words. Eg. AdminDomain is transliterated to the admin_domain parameter.

See the Red Hat Directory Server 9.0 Installation Guide's section on Silent Setup for a listing of all .inf file keys.

 * `admin_domain`
 * `config_directory_admin_id`
 * `config_directory_admin_pwd`
 * `config_directory_ldap_url`
 * `full_machine_name`
 * `server_admin_port`
 * `server_admin_id`
 * `server_admin_pwd`
 * `server_ipaddress`
 * `root_dn`
 * `root_dn_pwd`
 * `server_port`

• setup_dir

  String/aboslute path defaults to /var/lib/dirsrv/setup

  The path used by the module for it's internal state files.

• enable_ssl

  Bool defaults to false

  Enables/disables setup of SSL/TLS connections to the directory server.

  If set, these paramters are manadatory:

   * `ssl_server_port`
   * `ssl_cert`
   * `ssl_key`
   * `ssl_ca_certs`
  

• enable_server_admin_ssl

  Bool defaults to false

  XXX This feature appears to be broken, either in terms of the setup done by this module or in the current release of 389 DS server itselfs and/or the interaction with it's dependency.

  Enables/disables the usage of SSL/TLS connections between the admin server and the directory instances.

  If set, these paramters are manadatory:

   * `enable_ssl`
   * `ssl_server_port`
   * `ssl_cert`
   * `ssl_key`
   * `ssl_ca_certs`
  

The following parameters are ignored unless enable_ssl or enable_server_admin_ssl is true.

• ssl_server_port

  String defaults to 636

  Sets the port used for LDAPS connections.

• ssl_cert

  String/aboslute path defaults to undef

  Path to the .pem format certificate to use for SSL/TLS connections.

• ssl_key

  String/aboslute path defaults to undef

  Path to the .pem format key to use for SSL/TLS connections.

• ssl_ca_certs

  Hash defaults to {}

  Nickname / absolute path pairs to any chained certificate authority (CA) certs that may be needed.

  {
    'AlphaSSL CA'        => '/tmp/alphassl_intermediate.pem',
    'GlobalSign Root CA' => '/tmp/globalsign_root.pem',
  }
  

##Types

#defaults
port389::instance { <title>:
  $admin_domain               = $::port389::admin_domain,
  $config_directory_admin_id  = $::port389::config_directory_admin_id,
  $config_directory_admin_pwd = $::port389::config_directory_admin_pwd,
  $config_directory_ldap_url  = $::port389::config_directory_ldap_url,
  $root_dn                    = $::port389::root_dn,
  $root_dn_pwd                = $::port389::root_dn_pwd,
  $server_port                = $::port389::server_port,
  $schema_file                = undef,
  $suffix                     = port389_domain2dn($::port389::admin_domain),
  $enable_ssl                 = $::port389::enable_ssl,
  $ssl_server_port            = $::port389::ssl_server_port,
  $ssl_cert                   = $::port389::ssl_cert,
  $ssl_key                    = $::port389::ssl_key,
  $ssl_ca_certs               = $::port389::ssl_ca_certs,
}

The following parameters directly control values in the .inf file passed to setup-ds-admin.pl to create directory service instances. CamelCase .inf keys are represented as lowercase parameters names with _s between words. Eg.

See the Red Hat Directory Server 9.0 Installation Guide's section on Silent Setup for a listing of all .inf file keys.

 * `admin_domain`
 * `config_directory_admin_id`
 * `config_directory_admin_pwd`
 * `config_directory_ldap_url`
 * `root_dn`
 * `root_dn_pwd`
 * `server_port`
 * `schema_file`
 * `suffix`

• schema_file

  String|Array defaults to 'undef'

  Note that this paramter may except an array of absolute paths to schema files to be used when creating a new ldap instance.

• enable_ssl

  Bool defaults to false

  Enables/disables setup of SSL/TLS connections to the directory server.

  If set, these paramters are manadatory:

   * `ssl_server_port`
   * `ssl_cert`
   * `ssl_key`
   * `ssl_ca_certs`
  

• ssl_server_port

  String defaults to 636

  Sets the port used for LDAPS connections.

• ssl_cert

  String/aboslute path defaults to undef

  Path to the .pem format certificate to use for SSL/TLS connections.

• ssl_key

  String/aboslute path defaults to undef

  Path to the .pem format key to use for SSL/TLS connections.

• ssl_ca_certs

  Hash defaults to {}

  Nickname / absolute path pairs to any chained certificate authority (CA) certs that may be needed.

  {
    'AlphaSSL CA'        => '/tmp/alphassl_intermediate.pem',
    'GlobalSign Root CA' => '/tmp/globalsign_root.pem',
  }
  

Functions

###port389_domain2dn

Converts a DNS style domain string into a string suitable for use as a LDAP DN by constructing 'dc=' elements for each domain component.

Example:

foo.example.org

Would become:

dc=foo,dc=example,dc=org

Limitations

Tested Platforms

Versioning

This module is versioned according to the Semantic Versioning 2.0.0 specification.

Support

Please log tickets and issues at github

See Also

[Current]

• 435a443 - (Joshua Hoblitt) Update README.md
• c305f77 - (Joshua Hoblitt) Update README.md
• 49b24b6 - (Joshua Hoblitt) add additional details to README
• 85d55f5 - (Joshua Hoblitt) manage dirsrv (non-instance) service

The dirsrv service defaults to being disabled so no 389 instances will automatically start on boot.

• ae69463 - (Joshua Hoblitt) convert whitespace in net.ipv4.ip_local_port_range to a tab

To match the output from sysctl to avoid:

Notice: /Stage[main]/Port389::Tune/Sysctl[net.ipv4.ip_local_port_range]/value:
changed live value from '1024   65000' to '1024 65000'

• 46d5fd7 - (Joshua Hoblitt) disable system tuning by default
• 94bffa9 - (Joshua Hoblitt) fill in README
• 376d79e - (Joshua Hoblitt) add dep on jhoblitt/nsstools >= 1.0.2
• 05cd337 - (Joshua Hoblitt) modify redhat_instance provider tests to work with 2.7.x

The init service provider in older puppet releases didn't auto-magically exclude service sysv init script names. The redhat_instance service provider isn't intended to be general purposes so testing for the service name blacklisting can be safely removed.

• ba78c67 - (Joshua Hoblitt) update rspec to work with ruby 1.8.7
• 799be3f - (Joshua Hoblitt) replace usage of port389_nsstools_add_cert() with nsstools_add_cert()
• f2c31d2 - (Joshua Hoblitt) remove port389_nsstools_add_cert() function

Exported and renamed to nsstools_add_cert() in:

https://github.com/jhoblitt/puppet-nsstools/commit/58cf67dadade00a7ebe19a31d5d01e72d4fa5570

• 93e211f - (Joshua Hoblitt) adapt to nssdb -> nstools rename + API changes
• 91aac90 - (Joshua Hoblitt) resolve or suppress lint warnings
• 22f7644 - (Joshua Hoblitt) remove rspec-system boilerplate
• fe451e5 - (Joshua Hoblitt) add rspec coverage of admin server ssl setup

XXX need to test admin service resource but it's not obvious if this should be tested under the port389 class or the port389::instance type.

• b94efdc - (Joshua Hoblitt) change default password(s) to 'password'

To match the example password used in the documentation.

• 3fd51c6 - (Joshua Hoblitt) simplify instance ssl setup and tidy file ownership/permissions
• e143e1b - (Joshua Hoblitt) update admin server ssl support

This should be almost a complete implementation now but it's not in a working state as sslv2/sslv3 handshakes to port 9830 are hanging.

• 3b4e9de - (Joshua Hoblitt) change Modulefile dep on mcanevet/openldap to camptocamp/openldap

It appears that this module maybe be in the process of being renamed:

https://github.com/mcanevet/puppet-openldap/issues/17

• 6357541 - (Joshua Hoblitt) add admin server ssl support
• 36d5e18 - (Joshua Hoblitt) add all instance ssl params to port389 base class

To allow them to all be set globally.

• a9ddc1a - (Joshua Hoblitt) validate private class/type params
• fd6113d - (Joshua Hoblitt) facter nssdb setup into it's own type

Split the nssdb setup out of the port389::instance::ssl type into it's own port389::certs type.

• ff24ac3 - (Joshua Hoblitt) add .bundle to .gitignore
• e8ea305 - (Joshua Hoblitt) add service resource management
• 6112159 - (Joshua Hoblitt) update Gemfile rspec-puppet to point to upstream git

The patch needed to properly test the port389_nssd_add_cert() function has been merged:

https://github.com/rodjek/rspec-puppet/pull/155 https://github.com/rodjek/rspec-puppet/commit/03e94422fb9bbdd950d5a0bec6ead5d76e06616b

• 5f97fe9 - (Joshua Hoblitt) add redhat_instance service type provider

This provider is a subclass of the core redhat service provider. It is of limited use and is intended for service scripts that support managing multiple service instances via additional arguments to the init script.

This is needed to function with 389's sysvinit script. It appears that this type of kluedge will not be nessicary for the systemd service files.

• b5f5e99 - (Joshua Hoblitt) add initial per instance ssl configuration

These params have been addded to the port389::instance define

• ssl_server_port

• ssl_cert

• ssl_key

• ssl_ca_certs

• dbb1c5e - (Joshua Hoblitt) add work around for broken package yum provider on RedHat

As of puppet 3.4.2, the yum provider for the package type does not handle 'purged' correctly and shows activity on every run.

• bb7c059 - (Joshua Hoblitt) add warning() when an instance is defined but base class is set to absent
• 546cba1 - (Joshua Hoblitt) add ensure param to port389 class

Controls package installation state via these values:

• {present, latest, absent, purge }

On el6.x, the purg statee will manually rm -f all [known] 389 related files as this is not handled by the 389 rpms.

• c58e434 - (Joshua Hoblitt) add schema_file param to port389::instance define

This param controls SchemaFile entrie(s) in the setup.inf file.

• 1361895 - (Joshua Hoblitt) remove datacat module from .fixtures.yml (unused)
• 7df13c2 - (Joshua Hoblitt) add initial implementation port389::instance define

The rspec coverage of this define is unfortunately light as is both has many parameters and required many to be added to the port389 class.

• 7369ad4 - (Joshua Hoblitt) add port389_domain2dn function

Converts a DNS style domain string into a string suitable for use as a LDAP DN by constructing 'dc=' elements for each domain component.

Example:

foo.example.org

Would become:

dc=foo,dc=example,dc=org

• c2ff177 - (Joshua Hoblitt) convert .fixtures.yml to use all https URLs

Travis CI is choking on ssh+git style repo URLs

• a547d03 - (Joshua Hoblitt) add port389::tune class

This class sets recommending 389/RedHat Directory Server tuning limits.d and sysctl values.

• e984464 - (Joshua Hoblitt) add basic port389::install class
• 2374d20 - (Joshua Hoblitt) Merge puppet-module_skel
• 80d1393 - (Joshua Hoblitt) first commit