Footprintless::Plugin::Ldap::Ldap;

- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- ENTITIES
- METHODS
  - add($entry)
  - add_or_update($entry)
  - base_dn(@rdns)
  - bind($dn, %options)
  - connect(%connect_options)
  - canonical_dn($dn, %options)
  - delete($base, %options)
  - disconnect()
  - exploded_dn($dn, %options)
  - export_ldif($to, %options)
  - import_ldif($from, %options)
  - is_connected()
  - modify($dn, %options)
  - search($search_args, $each_entry_callback)
  - search_for_containers($base)
  - search_for_list($search_args, $entry_mapper)
  - search_for_map($search_args, $entry_mapper)
  - search_for_scalar($search_args, $entry_mapper)
  - to_string()
  - unbind()
  - update($entry)
  - with_connection($sub)
- AUTHOR
- COPYRIGHT AND LICENSE
- SEE ALSO

# 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.

- Footprintless::Plugin::Ldap