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

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>

perl v5.40.0                                       2025-01-05                                       SHELLDAP(1p)