SHELLDAP(1p)						User Contributed Perl Documentation					      SHELLDAP(1p)

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.

	- 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

       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

       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

	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

	cat
	   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

	 cd
	   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
	   Clear the screen.

       copy
	   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
	   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

       delete
	   Remove an entry from the directory.	Globbing is supported.	All deletes are sanity-prompted.

	       delete uid=mahlon
	       delete uid=ma*

	   aliased to: rm

       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

	   aliased to: vi

	env
	    Show values for various runtime variables.

       grep
	   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

       list
	   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

       mkdir
	   Creates a new 'organizationalUnit' entry.

	       mkdir containername
	       mkdir ou=whatever

       move
	   Move an entry to a different dn path.  Usage is identical to copy.

	   aliased to: mv

       passwd
	   If supported server side, change the password for a specified entry.  The entry must have a 'userPassword' attribute.

	       passwd uid=mahlon

	pwd
	   Print the 'working directory' - aka, the current ldap basedn.

       setenv
	   Modify various runtime variables normally set from the command line.

	       setenv debug 1
	       export debug=1

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

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.12.4							    2011-11-12							      SHELLDAP(1p)