1SHELLDAP(1) User Contributed Perl Documentation SHELLDAP(1)
2
6 Shelldap - A program for interacting with an LDAP server via a
7 shell-like interface
8
10 Shelldap /LDAP::Shell is a program for interacting with an LDAP server
11 via a shell-like interface.
12 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
18 shelldap --server example.net [--help]
19
21 - Upon successful authenticated binding, credential information is
22 auto-cached to ~/.shelldap.rc -- future loads require no command line
23 flags.
24 - Custom 'description maps' for entry listings. (See the 'list' command.)
26 - History and autocomplete via readline, if installed.
28 - Automatic reconnection attempts if the connection is lost with the
30 LDAP server.
31 - Basic schema introspection for quick reference.
33 - It feels like a semi-crippled shell, making LDAP browsing and editing
35 at least halfway pleasurable.
36
38 All command line options follow getopts long conventions.
39 shelldap --server example.net --basedn dc=your,o=company
41 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 Example:
47 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 configfile
58 Optional. Use an alternate configuration file, instead of the
59 default ~/.shelldap.rc.
60 --configfile /tmp/alternate-config.yml
62 -f /tmp/alternate-config.yml
63 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 server
69 Required. The LDAP server to connect to. This can be a hostname,
70 IP address, or a URI.
71 --server ldaps://ldap.example.net
73 -H ldaps://ldap.example.net
74 -h hostname_or_IP
75 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 --binddn cn=Manager,dc=your,o=company
82 -D cn=Manager,dc=your,o=company
83 basedn
85 The directory 'root' of your LDAP server. If omitted, shelldap
86 will try and ask the server for a sane default.
87 --basedn dc=your,o=company
89 -b dc=your,o=company
90 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 --paginate 100
98 promptpass
100 Force password prompting. Useful to temporarily override cached
101 credentials.
102 sasl
104 A space separated list of SASL mechanisms. Requires the
105 Authen::SASL module.
106 --sasl 'PLAIN DIGEST-MD5 EXTERNAL GSSAPI'
108 -Y 'PLAIN DIGEST-MD5 EXTERNAL GSSAPI'
109 sasluser
111 SASL authorization identity, if one is explicitly required by your
112 backend mechanism.
113 --sasluser mahlon
115 -X mahlon
116 tls Enables TLS over what would normally be an insecure connection.
118 Requires server side support.
119 tls_cacert
121 Specify CA Certificate to trust.
122 --tls_cacert /etc/ssl/certs/cacert.pem
124 tls_cert
126 The TLS client certificate.
127 --tls_cert ~/.ssl/client.cert.pem
129 tls_key
131 The TLS client key. Not specifying a key will connect via TLS
132 without key verification.
133 --tls_key ~/.ssl/private/client.key.pem
135 cacheage
137 Set the time to cache directory lookups in seconds.
138 By default, directory lookups are cached for 300 seconds, to speed
140 autocomplete up when changing between different basedns.
141 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 timeout
147 Set the maximum time an LDAP operation can take before it is
148 cancelled.
149 debug
151 Print extra operational info out, and backtrace on fatal error.
152 version
154 Display the version number.
155
157 alias
158 Define or display aliases.
159 Without arguments, `alias' prints the list of aliases in the reusable
161 form `alias NAME=VALUE' on standard output.
162 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 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 cat
176 Print contents of LDAP entry to STDOUT in LDIF format.
177 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 cat uid=mahlon
187 cat ou=*
188 cat uid=mahlon,ou=People,dc=example,o=company
189 cat uid=mahlon + userPassword
190 configfile
192 Load or save config file.
193 If no config file is specified as argument to 'load', the default
195 search list is:
196 $HOME/.shelldap.rc
198 /usr/local/etc/shelldap.conf
199 /etc/shelldap.conf
200 If no config file is specified as argument to 'save', the default path
202 is $HOME/.shelldap.rc.
203 configfile load
205 configfile load /path/to/config
206 configfile save
207 configfile save /path/to/config
208 less
210 Like 'cat', but use configured pager to paginate output.
211 cd
213 Change the working directory (LDAP search base).
214 Translated to LDAP, this changes the current basedn. All commands
216 after a 'cd' operate within the new basedn.
217 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 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 cd uid=mahlon
231 cat .
232 cat
233 clear
235 Clear the terminal screen.
236 Clears screen similar to 'clear' or Ctrl+l on the shell command line.
238 Ctrl+l alias is also supported.
240 copy
242 Copy an entry.
243 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 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 create
253 Create an entry.
254 Arguments are space separated objectClass names. Possible
256 objectClasses are derived automatically from the server, and will tab-
257 complete.
258 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 create top person organizationalPerson inetOrgPerson posixAccount
265 delete
267 Remove an entry.
268 Globbing is supported. All deletes are sanity-prompted. The -v flag
270 prints the entries out for review before delete.
271 delete uid=mahlon
273 delete uid=ma*
274 rm -v uid=mahlon,ou=People,dc=example,o=company l=office
275 edit
277 Edit an entry in an external editor.
278 After the editor exits, the resulting LDIF is sanity checked, and
280 changes are written to the LDAP directory.
281 edit uid=mahlon
283 env
285 Print values of configurable shelldap variables.
286 This is a subset of all variables configurable via shelldap config file
288 and/or its command line options.
289 grep
291 Search using LDAP filters and return matching DN results.
292 The search string must be a valid LDAP filter.
294 grep uid=mahlon
296 grep uid=mahlon ou=People
297 grep -r (&(uid=mahlon)(objectClass=*))
298 inspect
300 View schema and flags for an entry or objectClass.
301 It also includes the most common flags for the objectClass attributes.
303 inspect uid=mahlon
305 inspect posixAccount organizationalUnit
306 inspect _schema
307 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 If you ask for the special "_schema" object, the raw server schema is
315 dumped to screen.
316 list
318 List directory contents.
319 Globbing is supported.
321 ls -l
323 ls -lR uid=mahlon
324 list uid=m*
325 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 ...
332 descmaps:
333 objectClass: attributename
334 posixAccount: gecos
335 posixGroup: gidNumber
336 ipHost: ipHostNumber
337 mkdir
339 Create a new 'organizationalUnit' LDAP entry.
340 mkdir containername
342 mkdir ou=whatever
343 move
345 Move (rename) entry.
346 Usage is identical to copy.
348 passwd
350 Change user password.
351 If supported server side, change the password for a specified entry.
353 The entry must have a 'userPassword' attribute.
354 passwd uid=mahlon
356 pwd
358 Print name of current/working LDAP search base.
359 setenv
361 Change or define shelldap variable.
362 setenv debug 1
364 export debug=1
365 unalias
367 Remove each NAME from the list of defined aliases.
368 alias ll=ls -al
370 alias
371 unalias ll
372 unalias ll ls
373 alias
374 unsetenv
376 Remove each NAME from the list of defined shelldap variables.
377 unset debug
379 unset configfile
380 unset myvar1 myvar2 myvar3
381 whoami
383 Print current bind DN.
384 Show current auth credentials. Unless you specified a binddn, this
386 will just show an anonymous bind.
387
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 For now, it only makes sense to connect to a master if you plan on
394 doing any writes.
395 Add ability for command definitions in cmd_map to contain default
397 arguments passed to functions.
398 Then add ability to define custom commands/aliases in config file.
400 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
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
410 Mahlon E. Smith <mahlon@martini.nu>
411perl v5.36.0 2023-01-21 SHELLDAP(1)