.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 ""<STANDARD INPUT>" 1"
.TH "<STANDARD INPUT>" 1 "2008-01-13" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Shelldap / LDAP::Shell
.PP
A program for interacting with an LDAP server via a shell\-like
interface.
.PP
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.
.SH "SYNPOSIS"
.IX Header "SYNPOSIS"
.Vb 1
\& shelldap --server example.net --basedn dc=your,o=company [--tls] [--binddn ...] [--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.
.Ve
.PP
.Vb 1
\& - Custom 'description maps' for entry listings.  (See the 'list' command.)
.Ve
.PP
.Vb 1
\& - History and autocomplete via readline, if installed.
.Ve
.PP
.Vb 2
\& - Automatic reconnection attempts if the connection is lost with the
\&   LDAP server.
.Ve
.PP
.Vb 2
\& - 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 5
\&    server: ldap.example.net
\&    binddn: cn=Manager,dc=your,o=company
\&    bindpass: xxxxxxxxx
\&    basedn: dc=your,o=company
\&    tls: yes
.Ve
.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 1
\&    --server 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 1
\&    --binddn cn=Manager,dc=your,o=company
.Ve
.IP "\fBbasedn\fR" 4
.IX Item "basedn"
Required.  The directory 'root' of your \s-1LDAP\s0 server.
.Sp
.Vb 1
\&    --basedn dc=your,o=company
.Ve
.IP "\fB tls\fR" 4
.IX Item " tls"
Enables \s-1TLS\s0 over what would normally be an insecure connection.
Requires server side support.
.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.
.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.)
.Sp
.Vb 3
\&    cat uid=mahlon
\&    cat ou=*
\&    cat uid=mahlon,ou=People,dc=example,o=company
.Ve
.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 5
\&    cd                cd to 'home' basedn
\&    cd ~              same thing
\&    cd -              cd to previous directory
\&    cd ou=People      cd to explicit path
\&    cd ..             cd to parent node
.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 \fImoddn()\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.
.Sp
.Vb 2
\&    delete uid=mahlon
\&    delete uid=ma*
.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 "\fB env\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=*))
.Ve
.Sp
.Vb 1
\& aliased to: search
.Ve
.IP "\fBlist\fR" 4
.IX Item "list"
List entries for the current basedn.  Globbing is supported.
.Sp
aliased to: ls
.Sp
.Vb 4
\&    ls -l
\&    ls -lR uid=mahlon
\&    list uid=m*
\&    list verbose
.Ve
.Sp
In 'verbose' mode, descriptions are listed as well, if they exist.
There are also some 'sane' long listings for common objectClass types.
You can actually specify your own in your .shelldap.rc, like so:
.Sp
.Vb 7
\&    ...
\&    descmaps:
\&        objectClass: attributename
\&        posixAccount: gecos
\&        posixGroup: gidNumber
\&        ipHost: ipHostNumber
\&        puppetClient: puppetclass
.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.
.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.
.PP
\&\*(L"cd ../ou=SomewhereElse\*(R" doesn't work, but \*(L"cd ../../\*(R" does.  This is
weird, as both should probably work.
.SH "BUGS / LIMITATIONS"
.IX Header "BUGS / LIMITATIONS"
There is currently no attribute multiline support \- attribute values
that span over one line will be ignored if modified.  (Thankfully, they
are generally rare.)
.PP
There is no support for editing binary data.  This is actually related
to the lack of multiline support \- if you just base64 encode data and
paste it in, it will be ignored for the same reasons.
.SH "AUTHOR"
.IX Header "AUTHOR"
Mahlon E. Smith <mahlon@martini.nu>