/ 
Config-LDAPClient-0.01
River stage zero No dependents
/ Config::LDAPClient

NAME

Config::LDAPClient - parse system configuration for LDAP client settings.

SYNOPSIS

use Config::LDAPClient;

my $conf = Config::LDAPClient->new();
$conf->parse(
    'pam', 'nss', 'libldap',
    { config => '/etc/custom-ldap.conf', parse => \&custom_ldap_parser },
);

print "hosts: ", join(" ", $conf->c_uri), "\n";

my $ldap = $conf->connect;
# Call Net::LDAP methods on $ldap.

sub custom_ldap_parser { ... }

DESCRIPTION

*** WARNING *** This is very much alpha software. Testing has been minimal, and the API is somewhat subject to change.

On many systems there is existing configuration for how to connect to an LDAP server, usually in order to perform authentication for the system itself. This module reads that configuration, parses it, and presents a common interface that can then be used to connect to the specified LDAP server.

For a list of configuration files supported see "Configuration Files".

Methods

All methods raise exceptions on errors. Currently these are simply string exceptions.

$class->new( ... )

This is the class's constructor. It takes a hashref, or a list of key-value pairs; these are treated as method names, and the methods are called with the associated values. This method is supplied by Moose.

$object->connect
$object->connect( new => \%args )

Attempts to connect to an LDAP database using Net::LDAP. Attributes should be set to appropriate values, which means "parse" probably should be called first.

The new argument, if specified, must be a hashref. It is dereferenced and passed to the Net::LDAP constructor. It is used to override any default options set by Config::LDAPClient, and any Net::LDAP defaults.

Currently the only default constructor argument specified by Config::LDAPClient is onerror, which is set to 'die'.

$object->parse( @names_or_specifications )

This is the workhorse of the module. The arguments to this method are a series of pre-defined names and/or hashrefs indicating what configuration files to read, and how to parse them.

Pre-defined names are listed in "Configuration Files".

If a hashref is specified, it must contain at least two keys, config and parse. config is a scalar or arrayref listing the configuration files to read; parse is the method or subroutine reference to call. An additional parameter, secret, may be provided; this is the name of the file that contains the bind password required to connect. Any problems opening this file are not fatal, and will be added to diag, but otherwise ignored.

The parse subroutine or method is expected to return two values: a hashref of the parsed values, to be passed to c_* methods, and a data structure representing the raw parsed configuration. The parse subroutine or method is called with three arguments: the Config::LDAPClient object, the configuration filename or names, and optionally the secret filename (if it's specified).

Names and specifications are listed in priority order, meaning the first file found takes precedence over subsequent files. All settings are merged, with the highest priority taking precedence.

$object->parse_file_pam($conf_filename, $secret_filename)

This parses the PAM LDAP configuration file format. The parsing, and subsequent handling of options, is based on a reading of the pam_ldap.conf(5) man page from libpam-ldap 184-4.2 installed on Debian Lenny.

This method conforms to the description of the parse argument described in the "parse" in "parse method" documentation.

$object->parse_file_nss($conf_filename, $secret_filename)

This parses the NSS LDAP configuration file format. It first callse "parse_file_pam", because the formats and most of the options are identical, then does specific handling. The handling of options ceomes from a reading of the libnss-ldap.conf(5) man page from libnss-ldap 261-2.1 installed on Debian Lenny.

This method conforms to the description of the parse argument described in the "parse" in "parse method" documentation.

$object->parse_file_libldap($conf_filename)

This parses the libldap configuration file format. The parsing and handling of options comes from a reading of the ldap.conf(5) man page from libldap-2.4-2 installed on Debian Lenny.

This method conforms to the description of the parse argument described in the "parse" in "parse method" documentation.

$object->diag
$object->add_diag($message)
$object->clear_diag

The diag method accesses an array of non-fatal errors encountered in a given "parse" run. add_diag adds an entry, and clear_diag clears the entire array.

$object->raw_configs
$object->raw_configs(\%configs)

Accessor for the raw configuration data parsed from files. The hash keys are the filenames, the values the configuration data returned from the parse.

$object->parsed
$object->parsed(\%parsed)

Accessor for the parsed and processed data. This is all of the original merged data, and should correspond directly to the values returned by the c_* accessors.

Configuration Accessors

$object->c_uri
$object->c_uri(\@uris)

Accessor for URIs to connect to. Corresponds to the HOST argument for the new method in Net::LDAP. Returns a list of URIs, not an arrayref.

$object->c_ldap_version
$object->c_ldap_version($number)

Accessor for the LDAP protocol version to be used. Corresponds to the version argument to the Net::LDAP constructor.

$object->c_bind_dn
$object->c_bind_dn($dn)

Accessor for the DN to bind to use on connect. Corresponds to the first argument to the bind method in Net::LDAP.

$object->c_bind_password
$object->c_bind_password($password)

Accessor for the bind password to use on connect. Corresponds to the password argument to the bind method in Net::LDAP.

$object->c_base
$object->c_base($base)

Accessor for the default base DN to use in searches.

$object->c_ssl_type
$object->c_ssl_type($type)

Accessor for the SSL access type; valid values are 'off', 'ssl', or 'tls'.

$object->c_ssl_verify
$object->c_ssl_verify($verify)

Accessor for the SSL verification requirement; valid values correspond to the verify argument to start_tls in Net::LDAP, namely 'none', 'optional', and 'require'.

$object->c_ssl_capath
$object->c_ssl_capath($path)

Accessor for the directory of CA certificates. Corresponds to the capath argument to start_tls in Net::LDAP.

$object->c_ssl_cafile
$object->c_ssl_cafile($filename)

Accessor for the CA certificates file. Corresponds to the cafile argument to start_tls in Net::LDAP.

$object->c_search_passwd
$object->c_search_passwd($object)
$object->c_search_group
$object->c_search_group($object)
$object->c_search_shadow
$object->c_search_shadow($object)

These apply specifically to NSS. They are accessors for base DNs to use for specific lookups. The object used is an Config::LDAPClient::Search object, or subclass thereof.

Configuration Files

This module comes with several pre-defined paths that it can attempt to parse. These names can be passed directly to "parse".

  • pam

    Attempts to parse /etc/pam_ldap.conf and /etc/pam_ldap.secret, using "parse_file_pam". The secret file is typically owned by root and mode 0600, so unless you run as root, you will get the binddn and bindpw values in "c_bind_dn" and "c_bind_password".

  • nss

    Attempts to parse /etc/libnss-ldap.conf and /etc/libnss-ldap.secret, using "parse_file_nss". The secret file is typically owned by root and mode 0600, so unless you run as root, you will get the binddn and bindpw values in "c_bind_dn" and "c_bind_password".

  • pam_nss

    Some systems merge their libnss-ldap and pam-ldap configuration files. This attempts to parse /etc/ldap.conf and /etc/ldap.secret. The secret file is typically owned by root and mode 0600, so unless you run as root, you will get the binddn and bindpw values in "c_bind_dn" and "c_bind_password".

  • libldap

    Attempts to parse /etc/ldap/ldap.conf using "parse_file_libldap".

  • libldap_home

    Attempts to parse $ENV{HOME}/.ldaprc and $ENV{HOME}/ldaprc.

BUGS

The test suite is non-existent.

Option handling is not comprehensive. Not all of the options available in pam_ldap.conf and libnss-ldap.conf are actually used, even though they have equivalents in Net::LDAP.

Currently this only supports common Linux setups (specifically Debian Lenny and Ubuntu Hardy Heron). Support for more systems is forthcoming.

In order to speed development time, this module uses Moose. This increases the dependency list by a few orders of magnitude, which you may or may not consider a bug.

All of the configuration options available are specified as toplevel methods, albeit with 'c_' prefixes. This could be considered a design bug, but it was the simplest way to involve Moose's type checking.

Aside from support and design, there are probably more than a few bugs lurking about. This module was written quickly over a weekend with very minimal testing, as the lack of a test suite can attest.

AUTHOR

Michael Fowler <mfowler@cpan.org>

COPYRIGHT & LICENSE

Copyright 2009 Michael Fowler

This program is free software; you can redistribute it and/or modify it under the terms of either:

  • the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

  • the Artistic License version 2.0.