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

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.

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

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.

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

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

    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

    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

    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

    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

    promptpass
        Force password prompting. Useful to temporarily override cached
        credentials.

    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'

    sasluser
        SASL authorization identity, if one is explicitly required by your
        backend mechanism.

            --sasluser mahlon
            -X mahlon

    tls Enables TLS over what would normally be an insecure connection.
        Requires server side support.

    tls_cacert
        Specify CA Certificate to trust.

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

    tls_cert
        The TLS client certificate.

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

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

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

    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.

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

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

    version
        Display the version number.

SHELL COMMANDS
  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 '

  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

  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

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

  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

  clear
    Clear the terminal screen.

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

    Ctrl+l alias is also supported.

  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

  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

  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

  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

  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.

  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=*))

  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.

  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

  mkdir
    Create a new 'organizationalUnit' LDAP entry.

      mkdir containername
      mkdir ou=whatever

  move
    Move (rename) entry.

    Usage is identical to copy.

  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

  pwd
    Print name of current/working LDAP search base.

  setenv
    Change or define shelldap variable.

        setenv debug 1
        export debug=1

  unalias
    Remove each NAME from the list of defined aliases.

        alias ll=ls -al
        alias
        unalias ll
        unalias ll ls
        alias

  unsetenv
    Remove each NAME from the list of defined shelldap variables.

        unset debug
        unset configfile
        unset myvar1 myvar2 myvar3

  whoami
    Print current bind DN.

    Show current auth credentials. Unless you specified a binddn, this will
    just show an anonymous bind.

TODO
    Referral support. Currently, if you try to write to a replicant slave,
    you'll just get a referral. It would be nice if shelldap automatically
    tried to follow it.

    For now, it only makes sense to connect to a master if you plan on doing
    any writes.

    Add ability for command definitions in cmd_map to contain default
    arguments passed to functions.

    Then add ability to define custom commands/aliases in config file.

    Split 'inspect' into separate commands, one working on files/entries,
    and one working on objectclasses. This way, autocompleter for both
    commands will be reasonable, unlike now.

BUGS / LIMITATIONS
    There is no support for editing binary data. If you need to edit base64
    stuff, just feed it to the regular ldapmodify/ldapadd/etc tools.

AUTHOR
    Mahlon E. Smith <mahlon@martini.nu>

