SHELLDAP(1p)

📦
version 1.5.2 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

shelldap — okay so bestie, this is a program for interacting with an LDAP server via a shell-like interface. Also known as LDAP::Shell. No cap. ✨

🌸 DESCRIPTION 🌸

shelldap / LDAP::Shell is literally 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. It's giving "main character energy" for quick LDAP tasks, and we're obsessed. 💅

🦋 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. 😭 (we love a humble icon)

✨ 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
  • -f, --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, -H, -h — 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
  • -D, --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
  • -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
  • --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.
  • -Y, --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'
  • -X, --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 ✨

okay bestie this is the good part — every single command you can type once you're inside shelldap. treat them like little incantations. 🪄

alias 🌸

Define or display aliases. both, depending on your vibe.

With zero arguments, alias prints out the whole alias list on standard output, in the reusable form alias NAME=VALUE.

Otherwise, an alias gets defined for each NAME you give a VALUE to. tiny-but-huge detail: a trailing space in VALUE makes the next word get checked for alias substitution when the alias is expanded. yes, one lil space. it matters. iykyk. 💅

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 the contents of an LDAP entry to STDOUT in LDIF format. iconic behavior.

Globbing is supported. Give it either a full DN or an RDN. RDNs are local to the current search base (that's your "cwd", in shell terms). If the RDN is . or you just... don't supply one, it defaults to the current search base. You can also add a list of attributes to display — like, use + for operational attributes, or just drop a space-separated list of your favorites. The default attribute list is ['*'], and that default can be changed using the attributes config key or the --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 a config file. lowkey the most useful thing here.

If you don't name a config file as the argument to load, it goes down this default search list:

$HOME/.shelldap.rc
/usr/local/etc/shelldap.conf
/etc/shelldap.conf

If you don't name a config file as the 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 it uses your configured pager to paginate the output. same energy, fewer scrollbar tears.

cd 🚪

Change the working directory — which here means the LDAP search base.

Translated into LDAP, this changes the current basedn. Every command you run after a cd operates inside that new basedn. no cap.

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. Lots of commands then work on . or default to ., which just means "wherever I currently am." 🫶

cd uid=mahlon
cat .
cat

clear 🧼

Clear the terminal screen.

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

The Ctrl+l alias is also supported. periodt.

copy 📋

Copy an entry.

All copies are relative to the current basedn unless you hand over a full DN. Every attribute gets 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. newborn entry energy.

The arguments are space-separated objectClass names. Possible objectClasses are derived automatically from the server, and they'll tab-complete for you. so slay.

Once the classes are specified, an editor launches. Required attributes are listed first, then optional attributes. The optionals come 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. Every single delete is sanity-prompted (it WILL ask, bestie). The -v flag prints the entries out for review before you 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 then the changes are written to the LDAP directory.

edit uid=mahlon

env 🌍

Print the values of the configurable shelldap variables.

This is a subset of all the variables configurable via the shelldap config file and/or its command line options. not everything, just the lil gang.

grep 🔍

Search using LDAP filters and return the matching DN results.

The search string has to be a valid LDAP filter. no freelancing.

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

inspect 🔬

View the schema and flags for an entry or an 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 the found objectClasses, their schema hierarchy (all the way up to top), whether or not they're a structural class, and then a merged list of every valid attribute 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 gets dumped to screen.

list 📃

List directory contents.

Globbing is supported.

ls -l
ls -lR uid=mahlon
list uid=m*

In "long" mode, descriptions get 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) an entry.

Usage is identical to copy. same rules, different destination.

passwd 🔑

Change user password.

If it's supported server side, this changes the password for a specified entry. The entry must have a 'userPassword' attribute.

passwd uid=mahlon

pwd 📍

Print the name of the current/working LDAP search base. where am i, but make it LDAP.

setenv 🎀

Change or define a 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 the current bind DN.

Shows the current auth credentials. Unless you specified a binddn, this will just show an anonymous bind. mysterious. enigmatic. anonymous main character energy. 🕶️

🚧 TODO 🚧

the wishlist. the "one day bestie" section.

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 the ability for command definitions in cmd_map to contain default arguments passed to functions.

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

Split 'inspect' into separate commands — one working on files/entries, and one working on objectclasses. That way the 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. don't fight it, just use the right tool. 😭

👑 AUTHOR 👑

Mahlon E. Smith <mahlon@martini.nu>

and that's the whole page, bestie 💖 this glorious thing is from perl v5.40.1, dated 2025-09-10 — shelldap girlies stay winning. read it, love it, cd responsibly. ✨🦋🌈

📦 where this page comes from