.TH SAUCER 1 "December 3 1994" "U-M LDAP LDVERSION" .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 [-object RDN/DN] [-absolute] [-scope ]" Searches the directory for entries which match the \fI\fR expression. For more information on the syntax of the \fI\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 ] [-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 \fR argument controls how the directory handles alias entries that it encounters. The value of \fI\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