Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SHELLDAP(1)	      User Contributed Perl Documentation	   SHELLDAP(1)

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.32.0			  2019-10-13			   SHELLDAP(1)

NAME | DESCRIPTION | SYNPOSIS | FEATURES | OPTIONS | SHELL COMMANDS | TODO | BUGS / LIMITATIONS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=shelldap&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help