.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "SHELLDAP 1p" .TH SHELLDAP 1p "2019-10-17" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Shelldap \- A program for interacting with an LDAP server via a shell\-like interface .SH "DESCRIPTION" .IX Header "DESCRIPTION" Shelldap /LDAP::Shell is a program for interacting with an \s-1LDAP\s0 server via a shell-like interface. .PP This is not meant to be an exhaustive \s-1LDAP\s0 editing and browsing interface, but rather an intuitive shell for performing basic \s-1LDAP\s0 tasks quickly and with minimal effort. .SH "SYNPOSIS" .IX Header "SYNPOSIS" .Vb 1 \& shelldap \-\-server example.net [\-\-help] .Ve .SH "FEATURES" .IX Header "FEATURES" .Vb 3 \& \- Upon successful authenticated binding, credential information is \& auto\-cached to ~/.shelldap.rc \-\- future loads require no command line \& flags. \& \& \- Custom \*(Aqdescription maps\*(Aq for entry listings. (See the \*(Aqlist\*(Aq 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. .Ve .SH "OPTIONS" .IX Header "OPTIONS" All command line options follow getopts long conventions. .PP .Vb 1 \& shelldap \-\-server example.net \-\-basedn dc=your,o=company .Ve .PP You may also optionally create a ~/.shelldap.rc file with command line defaults. This file should be valid \s-1YAML.\s0 (This file is generated automatically on a successful bind auth.) .PP Example: .PP .Vb 8 \& 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 .Ve .IP "\fBconfigfile\fR" 4 .IX Item "configfile" Optional. Use an alternate configuration file, instead of the default ~/.shelldap.rc. .Sp .Vb 2 \& \-\-configfile /tmp/alternate\-config.yml \& \-f /tmp/alternate\-config.yml .Ve .Sp 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.) .IP "\fBserver\fR" 4 .IX Item "server" Required. The \s-1LDAP\s0 server to connect to. This can be a hostname, \s-1IP\s0 address, or a \s-1URI.\s0 .Sp .Vb 2 \& \-\-server ldaps://ldap.example.net \& \-H ldaps://ldap.example.net .Ve .IP "\fBbinddn\fR" 4 .IX Item "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. .Sp .Vb 2 \& \-\-binddn cn=Manager,dc=your,o=company \& \-D cn=Manager,dc=your,o=company .Ve .IP "\fBbasedn\fR" 4 .IX Item "basedn" The directory 'root' of your \s-1LDAP\s0 server. If omitted, shelldap will try and ask the server for a sane default. .Sp .Vb 2 \& \-\-basedn dc=your,o=company \& \-b dc=your,o=company .Ve .IP "\fBpaginate\fR" 4 .IX Item "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. .Sp .Vb 1 \& \-\-paginate 100 .Ve .IP "\fBpromptpass\fR" 4 .IX Item "promptpass" Force password prompting. Useful to temporarily override cached credentials. .IP "\fBsasl\fR" 4 .IX Item "sasl" A space separated list of \s-1SASL\s0 mechanisms. Requires the Authen::SASL module. .Sp .Vb 2 \& \-\-sasl \*(AqPLAIN DIGEST\-MD5 EXTERNAL GSSAPI\*(Aq \& \-Y \*(AqPLAIN DIGEST\-MD5 EXTERNAL GSSAPI\*(Aq .Ve .IP "\fBsasluser\fR" 4 .IX Item "sasluser" \&\s-1SASL\s0 authorization identity, if one is explicitly required by your backend mechanism. .Sp .Vb 2 \& \-\-sasluser mahlon \& \-X mahlon .Ve .IP "\fBtls\fR" 4 .IX Item "tls" Enables \s-1TLS\s0 over what would normally be an insecure connection. Requires server side support. .IP "\fBtls_cacert\fR" 4 .IX Item "tls_cacert" Specify \s-1CA\s0 Certificate to trust. .Sp .Vb 1 \& \-\-tls_cacert /etc/ssl/certs/cacert.pem .Ve .IP "\fBtls_cert\fR" 4 .IX Item "tls_cert" The \s-1TLS\s0 client certificate. .Sp .Vb 1 \& \-\-tls_cert ~/.ssl/client.cert.pem .Ve .IP "\fBtls_key\fR" 4 .IX Item "tls_key" The \s-1TLS\s0 client key. Not specifying a key will connect via \s-1TLS\s0 without key verification. .Sp .Vb 1 \& \-\-tls_key ~/.ssl/private/client.key.pem .Ve .IP "\fBcacheage\fR" 4 .IX Item "cacheage" Set the time to cache directory lookups in seconds. .Sp By default, directory lookups are cached for 300 seconds, to speed autocomplete up when changing between different basedns. .Sp 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. .IP "\fBtimeout\fR" 4 .IX Item "timeout" Set the maximum time an \s-1LDAP\s0 operation can take before it is cancelled. .IP "\fBdebug\fR" 4 .IX Item "debug" Print extra operational info out, and backtrace on fatal error. .IP "\fBversion\fR" 4 .IX Item "version" Display the version number. .SH "SHELL COMMANDS" .IX Header "SHELL COMMANDS" .IP "\fB cat\fR" 4 .IX Item " cat" Display an \s-1LDIF\s0 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. .Sp .Vb 4 \& cat uid=mahlon \& cat ou=* \& cat uid=mahlon,ou=People,dc=example,o=company \& cat uid=mahlon + userPassword .Ve .IP "\fB less\fR" 4 .IX Item " less" Like cat, but uses the configured pager to display output. .IP "\fB cd\fR" 4 .IX Item " cd" Change directory. Translated to \s-1LDAP,\s0 this changes the current basedn. All commands after a 'cd' operate within the new basedn. .Sp .Vb 7 \& cd change to \*(Aqhome\*(Aq 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\*(Aqs grandparent .Ve .Sp Since \s-1LDAP\s0 doesn't actually limit what can be a container object, you can actually cd into any entry. Many commands then work on '.', meaning \&\*(L"wherever I currently am.\*(R" .Sp .Vb 2 \& cd uid=mahlon \& cat . .Ve .IP "\fBclear\fR" 4 .IX Item "clear" Clear the screen. .IP "\fBcopy\fR" 4 .IX Item "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 \s-1LDAP\s0 \fBmoddn()\fR is performed. .Sp .Vb 3 \& 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 .Ve .Sp aliased to: cp .IP "\fBcreate\fR" 4 .IX Item "create" Create an entry from scratch. Arguments are space separated objectClass names. Possible objectClasses are derived automatically from the server, and will tab-complete. .Sp 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 \s-1LDIF\s0 is validated and added to the \s-1LDAP\s0 directory. .Sp .Vb 1 \& create top person organizationalPerson inetOrgPerson posixAccount .Ve .Sp aliased to: touch .IP "\fBdelete\fR" 4 .IX Item "delete" Remove an entry from the directory. Globbing is supported. All deletes are sanity-prompted. The \-v flag prints the entries out for review before delete. .Sp .Vb 3 \& delete uid=mahlon \& delete uid=ma* \& rm \-v uid=mahlon,ou=People,dc=example,o=company l=office .Ve .Sp aliased to: rm .IP "\fBedit\fR" 4 .IX Item "edit" Edit an entry in an external editor. After the editor exits, the resulting \s-1LDIF\s0 is sanity checked, and changes are written to the \s-1LDAP\s0 directory. .Sp .Vb 1 \& edit uid=mahlon .Ve .Sp aliased to: vi .IP "\fBenv\fR" 4 .IX Item "env" .Vb 1 \& Show values for various runtime variables. .Ve .IP "\fBgrep\fR" 4 .IX Item "grep" Search for arbitrary \s-1LDAP\s0 filters, and return matching dn results. The search string must be a valid \s-1LDAP\s0 filter. .Sp .Vb 3 \& grep uid=mahlon \& grep uid=mahlon ou=People \& grep \-r (&(uid=mahlon)(objectClass=*)) \& \& aliased to: search .Ve .IP "\fBinspect\fR" 4 .IX Item "inspect" View schema information about a given entry, or a list of arbitrary objectClasses, along with the most common flags for the objectClass attributes. .Sp .Vb 3 \& inspect uid=mahlon \& inspect posixAccount organizationalUnit \& inspect _schema .Ve .Sp 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. .Sp If you ask for the special \*(L"_schema\*(R" object, the raw server schema is dumped to screen. .IP "\fBlist\fR" 4 .IX Item "list" List entries for the current basedn. Globbing is supported. .Sp aliased to: ls .Sp .Vb 3 \& ls \-l \& ls \-lR uid=mahlon \& list uid=m* .Ve .Sp 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: .Sp .Vb 6 \& ... \& descmaps: \& objectClass: attributename \& posixAccount: gecos \& posixGroup: gidNumber \& ipHost: ipHostNumber .Ve .IP "\fBmkdir\fR" 4 .IX Item "mkdir" Creates a new 'organizationalUnit' entry. .Sp .Vb 2 \& mkdir containername \& mkdir ou=whatever .Ve .IP "\fBmove\fR" 4 .IX Item "move" Move an entry to a different dn path. Usage is identical to \fBcopy\fR. .Sp aliased to: mv .IP "\fBpasswd\fR" 4 .IX Item "passwd" If supported server side, change the password for a specified entry. The entry must have a 'userPassword' attribute. .Sp .Vb 1 \& passwd uid=mahlon .Ve .IP "\fB pwd\fR" 4 .IX Item " pwd" Print the 'working directory' \- aka, the current ldap basedn. .IP "\fBsetenv\fR" 4 .IX Item "setenv" Modify various runtime variables normally set from the command line. .Sp .Vb 2 \& setenv debug 1 \& export debug=1 .Ve .IP "\fBwhoami\fR" 4 .IX Item "whoami" Show current auth credentials. Unless you specified a binddn, this will just show an anonymous bind. .Sp aliased to: id .SH "TODO" .IX Header "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. .PP For now, it only makes sense to connect to a master if you plan on doing any writes. .SH "BUGS / LIMITATIONS" .IX Header "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. .SH "AUTHOR" .IX Header "AUTHOR" Mahlon E. Smith