#!/usr/bin/env perl

# vim: set nosta noet ts=4 sw=4:

#

# Copyright (c) 2006-2019, Mahlon E. Smith <mahlon@martini.nu>

# All rights reserved.

# Redistribution and use in source and binary forms, with or without

# modification, are permitted provided that the following conditions are met:

#

#     * Redistributions of source code must retain the above copyright

#       notice, this list of conditions and the following disclaimer.

#

#     * Redistributions in binary form must reproduce the above copyright

#       notice, this list of conditions and the following disclaimer in the

#       documentation and/or other materials provided with the distribution.

#

#     * Neither the name of Mahlon E. Smith nor the names of his

#       contributors may be used to endorse or promote products derived

#       from this software without specific prior written permission.

#

# THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY

# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

# DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY

# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES

# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;

# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=head1 NAME

Shelldap - A program for interacting with an LDAP server via a shell-like interface

=head1 DESCRIPTION

Shelldap /LDAP::Shell is a program for interacting with an LDAP server via a shell-like

interface.

This is not meant to be an exhaustive LDAP editing and browsing

interface, but rather an intuitive shell for performing basic LDAP

tasks quickly and with minimal effort.

=head1 SYNPOSIS

 shelldap --server example.net [--help]

=head1 FEATURES

 - Upon successful authenticated binding, credential information is

   auto-cached to ~/.shelldap.rc -- future loads require no command line

   flags.

 - Custom 'description maps' for entry listings.  (See the 'list' command.)

 - History and autocomplete via readline, if installed.

 - Automatic reconnection attempts if the connection is lost with the

   LDAP server.

 - Basic schema introspection for quick reference.

 - It feels like a semi-crippled shell, making LDAP browsing and editing

   at least halfway pleasurable.

=head1 OPTIONS

All command line options follow getopts long conventions.

    shelldap --server example.net --basedn dc=your,o=company

You may also optionally create a ~/.shelldap.rc file with command line

defaults.  This file should be valid YAML.  (This file is generated

automatically on a successful bind auth.)

Example:

    server: ldap.example.net

    binddn: cn=Manager,dc=your,o=company

    bindpass: xxxxxxxxx

    basedn: dc=your,o=company

    tls: yes

    tls_cacert: /etc/ssl/certs/cacert.pem

    tls_cert:   ~/.ssl/client.cert.pem 

    tls_key:    ~/.ssl/private/client.key.pem

=over 4

=item B<configfile>

Optional.  Use an alternate configuration file, instead of the

default ~/.shelldap.rc.

    --configfile /tmp/alternate-config.yml

    -f /tmp/alternate-config.yml

This config file overrides values found in the default config, so

you can easily have separate config files for connecting to your

cn=monitor or cn=log overlays (for example.)

=back

=over 4

=item B<server>

Required. The LDAP server to connect to.  This can be a hostname, IP

address, or a URI.

    --server ldaps://ldap.example.net

    -H ldaps://ldap.example.net

    -h hostname_or_IP

=back

=over 4

=item B<binddn>

The full dn of a user to authenticate as.  If not specified, defaults to

an anonymous bind.  You will be prompted for a password.

    --binddn cn=Manager,dc=your,o=company

    -D cn=Manager,dc=your,o=company

=back

=over 4

=item B<basedn>

The directory 'root' of your LDAP server.  If omitted, shelldap will

try and ask the server for a sane default.

    --basedn dc=your,o=company

    -b dc=your,o=company

=back

=over 4

=item B<paginate>

Integer.  If enabled, shelldap will attempt to use server side

pagination to build listings.  Note: if you're using this to avoid

sizelimit errors, you'll likely need server configuration to raise the

limits for paginated results.

  --paginate 100

=back

=over 4

=item B<promptpass>

Force password prompting.  Useful to temporarily override cached

credentials.

=back

=over 4

=item B<sasl>

A space separated list of SASL mechanisms.  Requires the Authen::SASL

module.

    --sasl 'PLAIN DIGEST-MD5 EXTERNAL GSSAPI'

    -Y 'PLAIN DIGEST-MD5 EXTERNAL GSSAPI'

=back

=over 4

=item B<sasluser>

SASL authorization identity, if one is explicitly required by your

backend mechanism.

    --sasluser mahlon

    -X mahlon

=back

=over 4

=item B<tls>

Enables TLS over what would normally be an insecure connection.

Requires server side support.

=item B<tls_cacert>

Specify CA Certificate to trust.

    --tls_cacert /etc/ssl/certs/cacert.pem

=item B<tls_cert>

The TLS client certificate.

    --tls_cert ~/.ssl/client.cert.pem

=item B<tls_key>

The TLS client key.  Not specifying a key will connect via TLS without

key verification.

    --tls_key ~/.ssl/private/client.key.pem

=back

=over 4

=item B<cacheage>

Set the time to cache directory lookups in seconds.

By default, directory lookups are cached for 300 seconds, to speed

autocomplete up when changing between different basedns.

Modifications to the directory automatically reset the cache.  Directory

listings are not cached.  (This is just used for autocomplete.)  Set it

to 0 to disable caching completely.

=back

=over 4

=item B<timeout>

Set the maximum time an LDAP operation can take before it is cancelled.

=back

=over 4

=item B<debug>

Print extra operational info out, and backtrace on fatal error.

=back

=over 4

=item B<version>

Display the version number.

=back

=head1 SHELL COMMANDS

=head2 alias

Define or display aliases.

Without arguments, `alias' prints the list of aliases in the reusable

form `alias NAME=VALUE' on standard output.

Otherwise, an alias is defined for each NAME whose VALUE is given.

A trailing space in VALUE causes the next word to be checked for

alias substitution when the alias is expanded.

    alias

    alias ll=ls -al

    alias ll

    alias show=cat

    alias cmd1=command 'arg with spaces'

    alias cmd2='command '

    alias cmd2=command 'with_arg '

=head2 cat

Print contents of LDAP entry to STDOUT in LDIF format.

Globbing is supported. Specify either full DN, or a RDN.

RDNs are local to the current search base ('cwd' in shell terms). If RDN is '.' or missing,

it defaults to the current search base.

You may additionally add a list of attributes to display (e.g. use '+' for operational

attributes or provide a specific space-separated list). Default list of attributes is ['*']

and this default list can be changed using 'attributes' config key or --attributes cmdline

option.

    cat uid=mahlon

    cat ou=*

    cat uid=mahlon,ou=People,dc=example,o=company

    cat uid=mahlon + userPassword

=head2 configfile

Load or save config file.

If no config file is specified as argument to 'load', the default search list is:

    $HOME/.shelldap.rc

    /usr/local/etc/shelldap.conf

    /etc/shelldap.conf

If no config file is specified as argument to 'save', the default path is

$HOME/.shelldap.rc.

    configfile load

    configfile load /path/to/config

    configfile save

    configfile save /path/to/config

=head2 less

Like 'cat', but use configured pager to paginate output.

=head2 cd

Change the working directory (LDAP search base).

Translated to LDAP, this changes the current basedn.

All commands after a 'cd' operate within the new basedn.

    cd                  change to 'home' (binddn if any, or basedn)

    cd ~                change to 'home' (binddn if any, or basedn)

    cd -                change to previous node

    cd ou=People        change to explicit path below current node

    cd ..               change to parent node

    cd ../../ou=Groups  change to node ou=Groups, which is a sibling

                        to the current node's grandparent

Since LDAP doesn't limit what can be a container object, you can 'cd' into

any entry. Many commands then work on '.' or default to '.', meaning

"wherever I currently am."

    cd uid=mahlon

    cat .

    cat

=head2 clear

Clear the terminal screen.

Clears screen similar to 'clear' or Ctrl+l on the shell command line.

Ctrl+l alias is also supported.

=head2 copy

Copy an entry.

All copies are relative to the

current basedn unless a full DN is specified.  All attributes are

copied and then an LDAP moddn() is performed.

    copy uid=mahlon uid=bob

    copy uid=mahlon ou=Others,dc=example,o=company

    copy uid=mahlon,ou=People,dc=example,o=company uid=mahlon,ou=Others,dc=example,o=company

=head2 create

Create an entry.

Arguments are space separated objectClass

names.  Possible objectClasses are derived automatically from the

server, and will tab-complete.

After the classes are specified, an editor will launch.  Required

attributes are listed first, then optional attributes.  Optionals are

commented out.  After the editor exits, the resulting LDIF is validated

and added to the LDAP directory.

    create top person organizationalPerson inetOrgPerson posixAccount

=head2 delete

Remove an entry.

Globbing is supported.

All deletes are sanity-prompted.  The -v flag prints the entries out

for review before delete.

    delete uid=mahlon

    delete uid=ma*

    rm -v uid=mahlon,ou=People,dc=example,o=company l=office

=head2 edit

Edit an entry in an external editor.

After the editor exits, the

resulting LDIF is sanity checked, and changes are written to the LDAP

directory.

    edit uid=mahlon

=head2 env

Print values of configurable shelldap variables.

This is a subset of all variables configurable via shelldap config

file and/or its command line options.

=head2 grep

Search using LDAP filters and return matching DN results.

The search string must be a valid LDAP filter.

    grep uid=mahlon

    grep uid=mahlon ou=People

    grep -r (&(uid=mahlon)(objectClass=*))

=head2 inspect

View schema and flags for an entry or objectClass.

It also includes the most common flags for the objectClass

attributes.

    inspect uid=mahlon

    inspect posixAccount organizationalUnit

    inspect _schema

The output is a list of found objectClasses, their schema hierarchy

(up to 'top'), whether or not they are a structural class, and then

a merged list of all valid attributes for the given objectClasses.

Attributes are marked as either required or optional, and whether

they allow multiple values or not.

If you ask for the special "_schema" object, the raw server schema

is dumped to screen.

=head2 list

List directory contents.

Globbing is supported.

    ls -l

    ls -lR uid=mahlon

    list uid=m*

In 'long' mode, descriptions are listed as well, if they exist.

There are some default 'long listing' mappings for common objectClass

types.  You can additionally specify your own mappings in your

.shelldap.rc, like so:

    ...

    descmaps:

        objectClass: attributename

        posixAccount: gecos

        posixGroup: gidNumber

        ipHost: ipHostNumber

=head2 mkdir

Create a new 'organizationalUnit' LDAP entry.

  mkdir containername

  mkdir ou=whatever

=head2 move

Move (rename) entry.

Usage is identical to B<copy>.

=head2 passwd

Change user password.

If supported server side, change the password for a specified entry.

The entry must have a 'userPassword' attribute.

    passwd uid=mahlon

=head2 pwd

Print name of current/working LDAP search base.

=head2 setenv

Change or define shelldap variable.

    setenv debug 1

    export debug=1

=head2 unalias

Remove each NAME from the list of defined aliases.

    alias ll=ls -al

    alias

    unalias ll

    unalias ll ls

    alias

=head2 unsetenv

Remove each NAME from the list of defined shelldap variables.

    unset debug

    unset configfile

    unset myvar1 myvar2 myvar3