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
75       binddn
76           The full dn of a user to authenticate as.  If not specified,
77           defaults to an anonymous bind.  You will be prompted for a
78           password.
79
80               --binddn cn=Manager,dc=your,o=company
81               -D cn=Manager,dc=your,o=company
82
83       basedn
84           The directory 'root' of your LDAP server.  If omitted, shelldap
85           will try and ask the server for a sane default.
86
87               --basedn dc=your,o=company
88               -b dc=your,o=company
89
90       paginate
91           Integer.  If enabled, shelldap will attempt to use server side
92           pagination to build listings.  Note: if you're using this to avoid
93           sizelimit errors, you'll likely need server configuration to raise
94           the limits for paginated results.
95
96                   --paginate 100
97
98       promptpass
99           Force password prompting.  Useful to temporarily override cached
100           credentials.
101
102       sasl
103           A space separated list of SASL mechanisms.  Requires the
104           Authen::SASL module.
105
106               --sasl "PLAIN CRAM-MD5 GSSAPI"
107
108       tls Enables TLS over what would normally be an insecure connection.
109           Requires server side support.
110
111       tls_cacert
112           Specify CA Certificate to trust.
113
114               --tls_cacert /etc/ssl/certs/cacert.pem
115
116       tls_cert
117           The TLS client certificate.
118
119               --tls_cert ~/.ssl/client.cert.pem
120
121       tls_key
122           The TLS client key.  Not specifying a key will connect via TLS
123           without key verification.
124
125               --tls_key ~/.ssl/private/client.key.pem
126
127       cacheage
128           Set the time to cache directory lookups in seconds.
129
130           By default, directory lookups are cached for 300 seconds, to speed
131           autocomplete up when changing between different basedns.
132
133           Modifications to the directory automatically reset the cache.
134           Directory listings are not cached.  (This is just used for
135           autocomplete.)  Set it to 0 to disable caching completely.
136
137       timeout
138           Set the maximum time an LDAP operation can take before it is
139           cancelled.
140
141       debug
142           Print extra operational info out, and backtrace on fatal error.
143
144       version
145           Display the version number.
146

SHELL COMMANDS

148        cat
149           Display an LDIF dump of an entry.  Globbing is supported.  Specify
150           either the full dn, or an rdn.  For most commands, rdns are local
151           to the current search base. ('cwd', as translated to shell speak.)
152           You may additionally add a list of attributes to display.  Use '+'
153           for server side attributes.
154
155               cat uid=mahlon
156               cat ou=*
157               cat uid=mahlon,ou=People,dc=example,o=company
158               cat uid=mahlon + userPassword
159
160        less
161           Like cat, but uses the configured pager to display output.
162
163         cd
164           Change directory.  Translated to LDAP, this changes the current
165           basedn.  All commands after a 'cd' operate within the new basedn.
166
167               cd                  change to 'home' basedn
168               cd ~                change to the binddn, or basedn if anonymously bound
169               cd -                change to previous node
170               cd ou=People        change to explicit path below current node
171               cd ..               change to parent node
172               cd ../../ou=Groups  change to node ou=Groups, which is a sibling
173                                   to the current node's grandparent
174
175           Since LDAP doesn't actually limit what can be a container object,
176           you can actually cd into any entry. Many commands then work on '.',
177           meaning "wherever I currently am."
178
179               cd uid=mahlon
180               cat .
181
182       clear
183           Clear the screen.
184
185       copy
186           Copy an entry to a different dn path.  All copies are relative to
187           the current basedn, unless a full dn is specified.  All attributes
188           are copied, then an LDAP moddn() is performed.
189
190               copy uid=mahlon uid=bob
191               copy uid=mahlon ou=Others,dc=example,o=company
192               copy uid=mahlon,ou=People,dc=example,o=company uid=mahlon,ou=Others,dc=example,o=company
193
194           aliased to: cp
195
196       create
197           Create an entry from scratch.  Arguments are space separated
198           objectClass names.  Possible objectClasses are derived
199           automatically from the server, and will tab-complete.
200
201           After the classes are specified, an editor will launch.  Required
202           attributes are listed first, then optional attributes.  Optionals
203           are commented out.  After the editor exits, the resulting LDIF is
204           validated and added to the LDAP directory.
205
206               create top person organizationalPerson inetOrgPerson posixAccount
207
208           aliased to: touch
209
210       delete
211           Remove an entry from the directory.  Globbing is supported.  All
212           deletes are sanity-prompted.  The -v flag prints the entries out
213           for review before delete.
214
215               delete uid=mahlon
216               delete uid=ma*
217               rm -v uid=mahlon,ou=People,dc=example,o=company l=office
218
219           aliased to: rm
220
221       edit
222           Edit an entry in an external editor.  After the editor exits, the
223           resulting LDIF is sanity checked, and changes are written to the
224           LDAP directory.
225
226               edit uid=mahlon
227
228           aliased to: vi
229
230       env
231            Show values for various runtime variables.
232
233       grep
234           Search for arbitrary LDAP filters, and return matching dn results.
235           The search string must be a valid LDAP filter.
236
237               grep uid=mahlon
238               grep uid=mahlon ou=People
239               grep -r (&(uid=mahlon)(objectClass=*))
240
241            aliased to: search
242
243       inspect
244           View schema information about a given entry, or a list of arbitrary
245           objectClasses, along with the most common flags for the objectClass
246           attributes.
247
248               inspect uid=mahlon
249               inspect posixAccount organizationalUnit
250               inspect _schema
251
252           The output is a list of found objectClasses, their schema hierarchy
253           (up to 'top'), whether or not they are a structural class, and then
254           a merged list of all valid attributes for the given objectClasses.
255           Attributes are marked as either required or optional, and whether
256           they allow multiple values or not.
257
258           If you ask for the special "_schema" object, the raw server schema
259           is dumped to screen.
260
261       list
262           List entries for the current basedn.  Globbing is supported.
263
264           aliased to: ls
265
266               ls -l
267               ls -lR uid=mahlon
268               list uid=m*
269
270           In 'long' mode, descriptions are listed as well, if they exist.
271           There are some default 'long listing' mappings for common
272           objectClass types.  You can additionally specify your own mappings
273           in your .shelldap.rc, like so:
274
275               ...
276               descmaps:
277                   objectClass: attributename
278                   posixAccount: gecos
279                   posixGroup: gidNumber
280                   ipHost: ipHostNumber
281
282       mkdir
283           Creates a new 'organizationalUnit' entry.
284
285               mkdir containername
286               mkdir ou=whatever
287
288       move
289           Move an entry to a different dn path.  Usage is identical to copy.
290
291           aliased to: mv
292
293       passwd
294           If supported server side, change the password for a specified
295           entry.  The entry must have a 'userPassword' attribute.
296
297               passwd uid=mahlon
298
299        pwd
300           Print the 'working directory' - aka, the current ldap basedn.
301
302       setenv
303           Modify various runtime variables normally set from the command
304           line.
305
306               setenv debug 1
307               export debug=1
308
309       whoami
310           Show current auth credentials.  Unless you specified a binddn, this
311           will just show an anonymous bind.
312
313           aliased to: id
314

TODO

316       Referral support.  Currently, if you try to write to a replicant slave,
317       you'll just get a referral.  It would be nice if shelldap automatically
318       tried to follow it.
319
320       For now, it only makes sense to connect to a master if you plan on
321       doing any writes.
322

BUGS / LIMITATIONS

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

AUTHOR

328       Mahlon E. Smith <mahlon@martini.nu>
329
330
331
332perl v5.28.1                      2019-02-02                       SHELLDAP(1)
Impressum