DESCRIPTIONShelldap /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.
shelldap --server example.net [--help]
- 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.
OPTIONSAll 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.)
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
Optional. Use an alternate configuration file, instead of the
--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.)
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
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
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
- Force password prompting. Useful to temporarily override cached credentials.
A space separated list of SASL mechanisms. Requires the Authen::SASL
--sasl "PLAIN CRAM-MD5 GSSAPI"
- Enables TLS over what would normally be an insecure connection. Requires server side support.
Specify CA Certificate to trust.
The TLS client certificate.
The TLS client key. Not specifying a key will connect via TLS without
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.
- Set the maximum time an LDAP operation can take before it is cancelled.
- Print extra operational info out, and backtrace on fatal error.
- Display the version number.
Display an LDIF dump of an entry. Globbing is supported. Specify
either the full dn, or an rdn. For most commands, rdns are local to the
current search base. ('cwd', as translated to shell speak.) You may additionally
add a list of attributes to display. Use '+' for server side attributes.
cat uid=mahlon cat ou=* cat uid=mahlon,ou=People,dc=example,o=company cat uid=mahlon + userPassword
- Like cat, but uses the configured pager to display output.
Change directory. Translated to LDAP, this changes the current basedn.
All commands after a 'cd' operate within the new basedn.
cd change to 'home' basedn cd ~ change to the binddn, or basedn if anonymously bound 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 actually limit what can be a container object, you can actually cd into any entry. Many commands then work on '.', meaning ``wherever I currently am.''
cd uid=mahlon cat .
- Clear the screen.
Copy an entry to a different dn path. All copies are relative to the
current basedn, unless a full dn is specified. All attributes are
copied, 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
aliased to: cp
Create an entry from scratch. 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
aliased to: touch
Remove an entry from the directory. 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
aliased to: rm
Edit an entry in an external editor. After the editor exits, the
resulting LDIF is sanity checked, and changes are written to the LDAP
aliased to: vi
Show values for various runtime variables.
Search for arbitrary 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=*)) aliased to: search
View schema information about a given entry, or a list of arbitrary
objectClasses, along with the most common flags for the objectClass
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 entries for the current basedn. Globbing is supported.
aliased to: ls
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
Creates a new 'organizationalUnit' entry.
mkdir containername mkdir ou=whatever
Move an entry to a different dn path. Usage is identical to copy.
aliased to: mv
If supported server side, change the password for a specified entry.
The entry must have a 'userPassword' attribute.
- Print the 'working directory' - aka, the current ldap basedn.
Modify various runtime variables normally set from the command line.
setenv debug 1 export debug=1
Show current auth credentials. Unless you specified a binddn, this
will just show an anonymous bind.
aliased to: id
TODOReferral 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.
BUGS / LIMITATIONSThere is no support for editing binary data. If you need to edit base64 stuff, just feed it to the regular ldapmodify/ldapadd/etc tools.
AUTHORMahlon E. Smith <[email protected]>