openldap/contrib/saucer/saucer.1

.TH SAUCER 1 "March 1999" "OpenLDAP"
.UC 6
.SH NAME
saucer \- interactive X.500 Directory client program
.SH SYNOPSIS
\fBsaucer\fR [-h \fIhost\fR] [-p \fIportnumber\fR] [-u \fIX500UserName\fR]
[-c \fIcredentials\fR] [-d \fIdebug-level\fR]
.SH DESCRIPTION
\fIsaucer\fR is used to navigate and perform searches on an X.500
Directory via the Lightweight Directory Access Protocol (LDAP).
.SH OPTIONS
.TP 5
.B \-h hostname
Used to specify the name or IP number of an LDAP host to which saucer
should connect.  If this flag is omitted, \fI127.0.0.1\fR is used.
.TP 5
.B \-p portnumber
Used to specify the TCP port number of the LDAP daemon on the server
host.  If this flag is omitted, the LDAP default port number
(\fI389\fR) is used.
.TP 5
.B \-u X500UserName
Specifies the X.500 name to be used when binding to the directory
server.  It must be in the form specified by RFC 1485, for example:

\fB"cn=George Castanza, o=Vandelay Industries, c=US"\fR

Don't forget to put quotes around the name if it contains blanks.
.TP 5
.B \-c credentials
Specifies the credentials, i.e. the password, to be used when binding
to the directory server.  If this flag is omitted but a name is given
with the \fB-u\fR flag, an unauthenticated bind will be attempted.  If
neither flag is given, an anonymous bind will be attempted.
.TP 5
.B \-d debug-level
Sets the LDAP debug mask to the numeric value specified.  This flag is
only used if saucer was compiled with the LDAP_DEBUG flag.
.SH COMMANDS
\fIsaucer\fR commands consist of a keyword followed by zero or more
arguments.  Commands and arguments can be shortened to any number of
characters; the entered text is matched against the available keywords
in ascending alphabetical order.  For example, entering the command
\fB"s"\fR will be interpreted by \fIsaucer\fR as the \fBsearch\fR
command, and \fB"sh"\fR will be interpreted as the \fBshow\fR command.
The \fBset\fR command cannot be abbreviated since both \fB"s"\fR and
\fB"se"\fR will be interpreted as the \fBsearch\fR command.

Arguments to commands are separated by whitespace (blanks or tabs), so
any values that contain whitespace (such as X.500 names) need to be
enclosed in single or double quotes.

Arguments can be entered in any order.  If the same argument appears
more than once in a command, the last value is used and the others are
ignored.

Directory names are by default assumed to be relative to the
\fIcurrent location\fR, which is set with the \fBmoveto\fR command.
All commands that accept a directory name have an optional
\fI-absolute\fR flag which causes \fIsaucer\fR to interpret the name
as a complete X.500 name rather than one that is relative to the
current location.
.SS "help [command]"
Provides brief online help giving the available commands and their syntax.

If \fIcommand\fR is specified, the syntax for the command is shown.
``help'' by itself simply provides a list of the available commands.
.SS "list [RDN/DN] [-absolute]"
Displays the names of a directory node's subordinates.

If an \fIRDN/DN\fR is given, it specifies the entry whose subordinates
are to be listed.  In its absence, the current location (see the
\fBmoveto\fR command) is used.  The \fI-absolute\fR argument controls
whether the \fIRDN/DN\fR is a complete directory name or is relative
to the current location.
.SS "moveto [RDN/DN] [-absolute]"
Displays or modifies \fIsaucer\fR's \fIcurrent location\fR in the
directory.  Without arguments, the current location is displayed.
If an \fIRDN/DN\fR is given, the current location is modified
and the new value is displayed.

The \fI-absolute\fR flag causes \fIsaucer\fR to treat the entered
\fIRDN/DN\fR as a complete directory name and to use it as the
new current location.  Without the \fI-absolute\fR flag, the
name is assumed to be relative to the previous location.

The special value \fB".."\fR is recognized by \fIsaucer\fR as a
valid name and causes the current location to be moved one level
up (towards the root) in the directory.
.SS quit
Unbinds from the directory and exits \fIsaucer\fR.
.SS "search <filter> [-object RDN/DN] [-absolute] [-scope <scope>]"
Searches the directory for entries which match the \fI<filter>\fR
expression.  For more information on the syntax of the \fI<filter>\fR
argument, see "RFC 1588 - A String Representation of LDAP Search
Filters".

If the \fI-object\fR argument is used, it specifies the base of the
directory search.  In its absence, the current location (see the
\fBmoveto\fR command) is used as the search base.  The \fI-absolute\fR
argument controls whether the \fIRDN/DN\fR given with the
\fI-object\fR flag is a complete directory name or is relative to the
current location.

The \fI-scope\fR argument controls the depth of the search.  It
accepts one of the keywords \fIbase\fR, \fIonelevel\fR, or
\fIsubtree\fR to search within the base object, its immediate
children, or all of its subordinates respectively.  The search depth
is preserved across commands, so subsequent searches will use the
previously entered depth setting if a new one is not given.
\fISaucer\fR defaults to a \fIonelevel\fR search depth at startup.
.SS "set [-aliasderef <deref>] [-sizelimit N] [-timelimit seconds]"
Displays or modifies settings which apply to all directory operations
issued by \fIsaucer\fR.  Without arguments, the current settings are
displayed.  If options are given, the settings are changed and the new
values are displayed.

The \fI-aliasderef <deref>\fR argument controls how the directory
handles alias entries that it encounters.  The value of \fI<deref>\fR
must be one of \fInever\fR, \fIsearch\fR, \fIfind\fR, or \fIalways\fR.

A value of \fInever\fR tells the directory not to follow through any
aliases it encounters.

A value of \fIfind\fR tells the directory to follow through an alias
if it occurs as the base of a \fBlist\fR, \fBsearch\fR, or \fBshow\fR
command.

A value of \fIsearch\fR tells the directory to follow through an alias
when performing a \fBsearch\fR command.  In other words, when
performing a search, the attributes of the entry an alias points to
will be tested against the filter expression rather than the alias
itself.

A value of \fIalways\fR combines the meanings of the \fIfind\fR and
\fIsearch\fR values, i.e., aliases are always dereferenced before
being acted upon.

The \fI-sizelimit N\fR argument sets the maximum number of entries
that will be returned by directory for \fBlist\fR and \fBsearch\fR
commands to \fIN\fR.  The directory server itself may impose a limit,
in which case the lesser of the two limits is used.  A value of
\fI0\fR may be used to request as many entries as possible.

The \fI-timelimit seconds\fR argument sets the maximum amount of time
allowed for a \fBlist\fR, \fBsearch\fR, or \fBshow\fR command.  Note
that this value is simply passed to the directory server, so the
enforcement of the time limit is up to the server.  A value of \fI0\fR
may be used to request no time limit.
.SS "show [RDN/DN] [-absolute]"
Displays the attributes of a directory entry.

If an \fIRDN/DN\fR is given, it specifies the entry whose attributes
are to be shown.  In its absence, the current location (see the
\fBmoveto\fR command) is used.  The \fI-absolute\fR argument controls
whether the \fIRDN/DN\fR is a complete directory name or is relative
to the current location.

The attributes \fIaudio\fR, \fIjpegPhoto\fR, \fIpersonalSignature\fR,
and \fIphoto\fR are known by \fIsaucer\fR to be binary values and are
therefore not displayed.  Other attributes which have binary encodings
will be displayed by \fIsaucer\fR and will probably appear as garbage
on the screen.
.SH FILES
~/.saucerrc    The saucer startup command file.
.SH "SEE ALSO"
ldap(3), RFC 1485, RFC 1588
.SH DIAGNOSTICS
\fIsaucer\fR uses the ldap_perror() routine to print a message
whenever an error is returned by the Directory server or the LDAP
library.
.SH "TO DO"
The new LDAP 3.1 ldap_XXX2text() routines should be used instead of
the code built into saucer.

The ability to read the X500UserName and credentials from the
~/.saucerrc file should be added.  There should also be a way to have
saucer prompt the user for their password.

Attribute types which are binary are hard-coded into saucer.  Ideally
saucer should also try to detect which ones aren't displayable at
runtime.
.SH AUTHOR
Eric Rosenquist, Enterprise Solutions Limited.
.br
Eric.Rosenquist@esltd.com