/ 
Footprintless-Plugin-Ldap-1.00
River stage zero No dependents
/ Footprintless::Plugin::Ldap::Ldap

NAME

Footprintless::Plugin::Ldap::Ldap; - The ldap client implementation

VERSION

version 1.00

SYNOPSIS

Standard way of getting an ldap client:

use Footprintless;
my $ldap = Footprintless->new()->ldap('proj.env');

# Export:
$ldap->with_connection(sub { $ldap->export_ldif('/tmp/export.ldif') });

# Import:
$ldap->with_connection(sub { $ldap->import_ldif('/tmp/export.ldif') });

# Search:
eval {
    $ldap->connect()->bind();
    my @foo_users = $ldap->search_for_list({filter => '(mail=*@foo.com)'});

    # do other things...
};
my $error = $@;
eval {$ldap->disconnect()};
die($error) if ($error);

DESCRIPTION

This module is a convenience wrapper around Net::LDAP that integrates with Footprintless and provides a bunch of useful LDAP manipulation functions.

ENTITIES

A simple LDAP entity:

ldap => {
    # An admin user with permission to manipulate entries
    bind_dn => 'uid=admin,ou=system',

    # Password for bind_dn
    # password can also be specified directly at the top level...
    bind_options => { password => 'secret' },

    # Base dn to use for all operations when not explicitly specified
    # by the operation options
    default_base => 'dc=foo,dc=com'

    # The hostname of the server
    hostname => 'public-ldap.foo.com',

    # The port (default 389 if secure == 0, 636 otherwise)
    port => 389,

    # O for LDAP (default), 1 for LDAPS
    secure => 0,

    # Optional ssh tunnel configuration, uses Footprintless::Tunnel
    tunnel_destination_hostname => 'internal-ldap.foo.com',
    tunnel_hostname => 'bastion-gateway.foo.com',
    tunnel_username => 'automationuser',
},

METHODS

add($entry)

Adds $entry.

add_or_update($entry)

Adds $entry if it does not exist, updates it otherwise.

base_dn(@rdns)

Returns a dn by combining all of the @rdns.

bind($dn, %options)

Binds to $dn. If %options are provided, they will be used in place to the configured connection options.

connect(%connect_options)

Connects to the server (does not perfom a bind). The %connect_options are passed through to the Net::LDAP or Net::LDAPS constructor.

canonical_dn($dn, %options)

Passes through to "canonical_dn" in Net::LDAP::Util.

delete($base, %options)

If %options are provided, the options filter and scope will be used together with $base to search for, and then delete entries. Otherwise, $base will be deleted.

disconnect()

Disconnects from the server.

exploded_dn($dn, %options)

Passes through to "ldap_explode_dn" in Net::LDAP::Util.

export_ldif($to, %options)

Exports the data to $to, which must be one of:

SCALARREF

A refrence to a scalar to hold the LDIF data.

string

The name of a file to write the LDIF data to.

The supported options are, base, scope, filter, and attrs. They are used to search for the entries to export.

import_ldif($from, %options)

Imports the data from $from, which must be one of:

GLOBREF

A reference to a file handle to read LDIF data from.

SCALARREF

A refrence to a scalar to holding the LDIF data.

string

An LDIF filename.

The supported options are:

each_entry

A sub that gets run on each entry instead of add_or_update.

is_connected()

Returns a truthy value if currently connected.

modify($dn, %options)

Modifies the entry at $dn according to %options. The %options are specified by modify in Net::Ldap

search($search_args, $each_entry_callback)

Searches for all entries matching $search_args and calls $each_entry_callback for each result.

search_for_containers($base)

Returns an ARRAY of dn's of all the containers under $base.

search_for_list($search_args, $entry_mapper)

Searches for all entries matching $search_args. If $entry_mapper is supplied it will be called for each entry. Otherwise, the entry itself will be used. All results will be aggregated into an ARRAY or ARRAYREF (depending on wantarray) and returned.

search_for_map($search_args, $entry_mapper)

Searches for all entries matching $search_args. If $entry_mapper is supplied it will be called for each entry and will be expected to return a tuple (ARRAY of length 2), representing a key value pair. Otherwise, the entry dn and the entry itself will be used as the key value pair. All results will be aggregated into a HASHREF and returned.

search_for_scalar($search_args, $entry_mapper)

Searches for a single entry matching $search_args. If $entry_mapper is supplied, it will be called with the entry, and the value returned will be returned. Otherwise, the entry itself will be returned.

to_string()

Prints out a string containing connection information useful for debugging.

unbind()

Unbinds the connection to the server.

update($entry)

Updates $entry on the server.

with_connection($sub)

Opens a connection, binds, calls $sub, and disconnects. If an error occurred the disconnect will be executed and the error will be re-died.

AUTHOR

Lucas Theisen <lucastheisen@pastdev.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Lucas Theisen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

SEE ALSO

Please see those modules/websites for more information related to this module.