1SHELLDAP(1)           User Contributed Perl Documentation          SHELLDAP(1)
2
3
4

NAME

6       Shelldap - A program for interacting with an LDAP server via a
7       shell-like interface
8

DESCRIPTION

10       Shelldap /LDAP::Shell is a program for interacting with an LDAP server
11       via a shell-like interface.
12
13       This is not meant to be an exhaustive LDAP editing and browsing
14       interface, but rather an intuitive shell for performing basic LDAP
15       tasks quickly and with minimal effort.
16

SYNPOSIS

18        shelldap --server example.net [--help]
19

FEATURES

21        - Upon successful authenticated binding, credential information is
22          auto-cached to ~/.shelldap.rc -- future loads require no command line
23          flags.
24
25        - Custom 'description maps' for entry listings.  (See the 'list' command.)
26
27        - History and autocomplete via readline, if installed.
28
29        - Automatic reconnection attempts if the connection is lost with the
30          LDAP server.
31
32        - Basic schema introspection for quick reference.
33
34        - It feels like a semi-crippled shell, making LDAP browsing and editing
35          at least halfway pleasurable.
36

OPTIONS

38       All command line options follow getopts long conventions.
39
40           shelldap --server example.net --basedn dc=your,o=company
41
42       You may also optionally create a ~/.shelldap.rc file with command line
43       defaults.  This file should be valid YAML.  (This file is generated
44       automatically on a successful bind auth.)
45
46       Example:
47
48           server: ldap.example.net
49           binddn: cn=Manager,dc=your,o=company
50           bindpass: xxxxxxxxx
51           basedn: dc=your,o=company
52           tls: yes
53           tls_cacert: /etc/ssl/certs/cacert.pem
54           tls_cert:   ~/.ssl/client.cert.pem
55           tls_key:    ~/.ssl/private/client.key.pem
56
57       configfile
58           Optional.  Use an alternate configuration file, instead of the
59           default ~/.shelldap.rc.
60
61               --configfile /tmp/alternate-config.yml
62               -f /tmp/alternate-config.yml
63
64           This config file overrides values found in the default config, so
65           you can easily have separate config files for connecting to your
66           cn=monitor or cn=log overlays (for example.)
67
68       server
69           Required. The LDAP server to connect to.  This can be a hostname,
70           IP address, or a URI.
71
72               --server ldaps://ldap.example.net
73               -H ldaps://ldap.example.net
74               -h hostname_or_IP
75
76       binddn
77           The full dn of a user to authenticate as.  If not specified,
78           defaults to an anonymous bind.  You will be prompted for a
79           password.
80
81               --binddn cn=Manager,dc=your,o=company
82               -D cn=Manager,dc=your,o=company
83
84       basedn
85           The directory 'root' of your LDAP server.  If omitted, shelldap
86           will try and ask the server for a sane default.
87
88               --basedn dc=your,o=company
89               -b dc=your,o=company
90
91       paginate
92           Integer.  If enabled, shelldap will attempt to use server side
93           pagination to build listings.  Note: if you're using this to avoid
94           sizelimit errors, you'll likely need server configuration to raise
95           the limits for paginated results.
96
97             --paginate 100
98
99       promptpass
100           Force password prompting.  Useful to temporarily override cached
101           credentials.
102
103       sasl
104           A space separated list of SASL mechanisms.  Requires the
105           Authen::SASL module.
106
107               --sasl 'PLAIN DIGEST-MD5 EXTERNAL GSSAPI'
108               -Y 'PLAIN DIGEST-MD5 EXTERNAL GSSAPI'
109
110       sasluser
111           SASL authorization identity, if one is explicitly required by your
112           backend mechanism.
113
114               --sasluser mahlon
115               -X mahlon
116
117       tls Enables TLS over what would normally be an insecure connection.
118           Requires server side support.
119
120       tls_cacert
121           Specify CA Certificate to trust.
122
123               --tls_cacert /etc/ssl/certs/cacert.pem
124
125       tls_cert
126           The TLS client certificate.
127
128               --tls_cert ~/.ssl/client.cert.pem
129
130       tls_key
131           The TLS client key.  Not specifying a key will connect via TLS
132           without key verification.
133
134               --tls_key ~/.ssl/private/client.key.pem
135
136       cacheage
137           Set the time to cache directory lookups in seconds.
138
139           By default, directory lookups are cached for 300 seconds, to speed
140           autocomplete up when changing between different basedns.
141
142           Modifications to the directory automatically reset the cache.
143           Directory listings are not cached.  (This is just used for
144           autocomplete.)  Set it to 0 to disable caching completely.
145
146       timeout
147           Set the maximum time an LDAP operation can take before it is
148           cancelled.
149
150       debug
151           Print extra operational info out, and backtrace on fatal error.
152
153       version
154           Display the version number.
155

SHELL COMMANDS

157   alias
158       Define or display aliases.
159
160       Without arguments, `alias' prints the list of aliases in the reusable
161       form `alias NAME=VALUE' on standard output.
162
163       Otherwise, an alias is defined for each NAME whose VALUE is given.  A
164       trailing space in VALUE causes the next word to be checked for alias
165       substitution when the alias is expanded.
166
167           alias
168           alias ll=ls -al
169           alias ll
170           alias show=cat
171           alias cmd1=command 'arg with spaces'
172           alias cmd2='command '
173           alias cmd2=command 'with_arg '
174
175   cat
176       Print contents of LDAP entry to STDOUT in LDIF format.
177
178       Globbing is supported. Specify either full DN, or a RDN.  RDNs are
179       local to the current search base ('cwd' in shell terms). If RDN is '.'
180       or missing, it defaults to the current search base.  You may
181       additionally add a list of attributes to display (e.g. use '+' for
182       operational attributes or provide a specific space-separated list).
183       Default list of attributes is ['*'] and this default list can be
184       changed using 'attributes' config key or --attributes cmdline option.
185
186           cat uid=mahlon
187           cat ou=*
188           cat uid=mahlon,ou=People,dc=example,o=company
189           cat uid=mahlon + userPassword
190
191   configfile
192       Load or save config file.
193
194       If no config file is specified as argument to 'load', the default
195       search list is:
196
197           $HOME/.shelldap.rc
198           /usr/local/etc/shelldap.conf
199           /etc/shelldap.conf
200
201       If no config file is specified as argument to 'save', the default path
202       is $HOME/.shelldap.rc.
203
204           configfile load
205           configfile load /path/to/config
206           configfile save
207           configfile save /path/to/config
208
209   less
210       Like 'cat', but use configured pager to paginate output.
211
212   cd
213       Change the working directory (LDAP search base).
214
215       Translated to LDAP, this changes the current basedn.  All commands
216       after a 'cd' operate within the new basedn.
217
218           cd                  change to 'home' (binddn if any, or basedn)
219           cd ~                change to 'home' (binddn if any, or basedn)
220           cd -                change to previous node
221           cd ou=People        change to explicit path below current node
222           cd ..               change to parent node
223           cd ../../ou=Groups  change to node ou=Groups, which is a sibling
224                               to the current node's grandparent
225
226       Since LDAP doesn't limit what can be a container object, you can 'cd'
227       into any entry. Many commands then work on '.' or default to '.',
228       meaning "wherever I currently am."
229
230           cd uid=mahlon
231           cat .
232           cat
233
234   clear
235       Clear the terminal screen.
236
237       Clears screen similar to 'clear' or Ctrl+l on the shell command line.
238
239       Ctrl+l alias is also supported.
240
241   copy
242       Copy an entry.
243
244       All copies are relative to the current basedn unless a full DN is
245       specified.  All attributes are copied and then an LDAP moddn() is
246       performed.
247
248           copy uid=mahlon uid=bob
249           copy uid=mahlon ou=Others,dc=example,o=company
250           copy uid=mahlon,ou=People,dc=example,o=company uid=mahlon,ou=Others,dc=example,o=company
251
252   create
253       Create an entry.
254
255       Arguments are space separated objectClass names.  Possible
256       objectClasses are derived automatically from the server, and will tab-
257       complete.
258
259       After the classes are specified, an editor will launch.  Required
260       attributes are listed first, then optional attributes.  Optionals are
261       commented out.  After the editor exits, the resulting LDIF is validated
262       and added to the LDAP directory.
263
264           create top person organizationalPerson inetOrgPerson posixAccount
265
266   delete
267       Remove an entry.
268
269       Globbing is supported.  All deletes are sanity-prompted.  The -v flag
270       prints the entries out for review before delete.
271
272           delete uid=mahlon
273           delete uid=ma*
274           rm -v uid=mahlon,ou=People,dc=example,o=company l=office
275
276   edit
277       Edit an entry in an external editor.
278
279       After the editor exits, the resulting LDIF is sanity checked, and
280       changes are written to the LDAP directory.
281
282           edit uid=mahlon
283
284   env
285       Print values of configurable shelldap variables.
286
287       This is a subset of all variables configurable via shelldap config file
288       and/or its command line options.
289
290   grep
291       Search using LDAP filters and return matching DN results.
292
293       The search string must be a valid LDAP filter.
294
295           grep uid=mahlon
296           grep uid=mahlon ou=People
297           grep -r (&(uid=mahlon)(objectClass=*))
298
299   inspect
300       View schema and flags for an entry or objectClass.
301
302       It also includes the most common flags for the objectClass attributes.
303
304           inspect uid=mahlon
305           inspect posixAccount organizationalUnit
306           inspect _schema
307
308       The output is a list of found objectClasses, their schema hierarchy (up
309       to 'top'), whether or not they are a structural class, and then a
310       merged list of all valid attributes for the given objectClasses.
311       Attributes are marked as either required or optional, and whether they
312       allow multiple values or not.
313
314       If you ask for the special "_schema" object, the raw server schema is
315       dumped to screen.
316
317   list
318       List directory contents.
319
320       Globbing is supported.
321
322           ls -l
323           ls -lR uid=mahlon
324           list uid=m*
325
326       In 'long' mode, descriptions are listed as well, if they exist.  There
327       are some default 'long listing' mappings for common objectClass types.
328       You can additionally specify your own mappings in your .shelldap.rc,
329       like so:
330
331           ...
332           descmaps:
333               objectClass: attributename
334               posixAccount: gecos
335               posixGroup: gidNumber
336               ipHost: ipHostNumber
337
338   mkdir
339       Create a new 'organizationalUnit' LDAP entry.
340
341         mkdir containername
342         mkdir ou=whatever
343
344   move
345       Move (rename) entry.
346
347       Usage is identical to copy.
348
349   passwd
350       Change user password.
351
352       If supported server side, change the password for a specified entry.
353       The entry must have a 'userPassword' attribute.
354
355           passwd uid=mahlon
356
357   pwd
358       Print name of current/working LDAP search base.
359
360   setenv
361       Change or define shelldap variable.
362
363           setenv debug 1
364           export debug=1
365
366   unalias
367       Remove each NAME from the list of defined aliases.
368
369           alias ll=ls -al
370           alias
371           unalias ll
372           unalias ll ls
373           alias
374
375   unsetenv
376       Remove each NAME from the list of defined shelldap variables.
377
378           unset debug
379           unset configfile
380           unset myvar1 myvar2 myvar3
381
382   whoami
383       Print current bind DN.
384
385       Show current auth credentials.  Unless you specified a binddn, this
386       will just show an anonymous bind.
387

TODO

389       Referral support.  Currently, if you try to write to a replicant slave,
390       you'll just get a referral.  It would be nice if shelldap automatically
391       tried to follow it.
392
393       For now, it only makes sense to connect to a master if you plan on
394       doing any writes.
395
396       Add ability for command definitions in cmd_map to contain default
397       arguments passed to functions.
398
399       Then add ability to define custom commands/aliases in config file.
400
401       Split 'inspect' into separate commands, one working on files/entries,
402       and one working on objectclasses. This way, autocompleter for both
403       commands will be reasonable, unlike now.
404

BUGS / LIMITATIONS

406       There is no support for editing binary data.  If you need to edit
407       base64 stuff, just feed it to the regular ldapmodify/ldapadd/etc tools.
408

AUTHOR

410       Mahlon E. Smith <mahlon@martini.nu>
411
412
413
414perl v5.36.0                      2023-01-21                       SHELLDAP(1)
Impressum