git.sur5r.net Git - openldap/blob - contrib/saucer/saucer.1

   1 .TH SAUCER 1 "December 3 1994" "U-M LDAP LDVERSION"
   2 .UC 6
   3 .SH NAME
   4 saucer \- interactive X.500 Directory client program
   5 .SH SYNOPSIS
   6 \fBsaucer\fR [-h \fIhost\fR] [-p \fIportnumber\fR] [-u \fIX500UserName\fR]
   7 [-c \fIcredentials\fR] [-d \fIdebug-level\fR]
   8 .SH DESCRIPTION
   9 \fIsaucer\fR is used to navigate and perform searches on an X.500
  10 Directory via the Lightweight Directory Access Protocol (LDAP).
  11 .SH OPTIONS
  12 .TP 5
  13 .B \-h hostname
  14 Used to specify the name or IP number of an LDAP host to which saucer
  15 should connect.  If this flag is omitted, \fI127.0.0.1\fR is used.
  16 .TP 5
  17 .B \-p portnumber
  18 Used to specify the TCP port number of the LDAP daemon on the server
  19 host.  If this flag is omitted, the LDAP default port number
  20 (\fI389\fR) is used.
  21 .TP 5
  22 .B \-u X500UserName
  23 Specifies the X.500 name to be used when binding to the directory
  24 server.  It must be in the form specified by RFC 1485, for example:
  25
  26 \fB"cn=George Castanza, o=Vandelay Industries, c=US"\fR
  27
  28 Don't forget to put quotes around the name if it contains blanks.
  29 .TP 5
  30 .B \-c credentials
  31 Specifies the credentials, i.e. the password, to be used when binding
  32 to the directory server.  If this flag is omitted but a name is given
  33 with the \fB-u\fR flag, an unauthenticated bind will be attempted.  If
  34 neither flag is given, an anonymous bind will be attempted.
  35 .TP 5
  36 .B \-d debug-level
  37 Sets the LDAP debug mask to the numeric value specified.  This flag is
  38 only used if saucer was compiled with the LDAP_DEBUG flag.
  39 .SH COMMANDS
  40 \fIsaucer\fR commands consist of a keyword followed by zero or more
  41 arguments.  Commands and arguments can be shortened to any number of
  42 characters; the entered text is matched against the available keywords
  43 in ascending alphabetical order.  For example, entering the command
  44 \fB"s"\fR will be interpreted by \fIsaucer\fR as the \fBsearch\fR
  45 command, and \fB"sh"\fR will be interpreted as the \fBshow\fR command.
  46 The \fBset\fR command cannot be abbreviated since both \fB"s"\fR and
  47 \fB"se"\fR will be interpreted as the \fBsearch\fR command.
  48
  49 Arguments to commands are separated by whitespace (blanks or tabs), so
  50 any values that contain whitespace (such as X.500 names) need to be
  51 enclosed in single or double quotes.
  52
  53 Arguments can be entered in any order.  If the same argument appears
  54 more than once in a command, the last value is used and the others are
  55 ignored.
  56
  57 Directory names are by default assumed to be relative to the
  58 \fIcurrent location\fR, which is set with the \fBmoveto\fR command.
  59 All commands that accept a directory name have an optional
  60 \fI-absolute\fR flag which causes \fIsaucer\fR to interpret the name
  61 as a complete X.500 name rather than one that is relative to the
  62 current location.
  63 .SS "help [command]"
  64 Provides brief online help giving the available commands and their syntax.
  65
  66 If \fIcommand\fR is specified, the syntax for the command is shown.
  67 ``help'' by itself simply provides a list of the available commands.
  68 .SS "list [RDN/DN] [-absolute]"
  69 Displays the names of a directory node's subordinates.
  70
  71 If an \fIRDN/DN\fR is given, it specifies the entry whose subordinates
  72 are to be listed.  In its absence, the current location (see the
  73 \fBmoveto\fR command) is used.  The \fI-absolute\fR argument controls
  74 whether the \fIRDN/DN\fR is a complete directory name or is relative
  75 to the current location.
  76 .SS "moveto [RDN/DN] [-absolute]"
  77 Displays or modifies \fIsaucer\fR's \fIcurrent location\fR in the
  78 directory.  Without arguments, the current location is displayed.
  79 If an \fIRDN/DN\fR is given, the current location is modified
  80 and the new value is displayed.
  81
  82 The \fI-absolute\fR flag causes \fIsaucer\fR to treat the entered
  83 \fIRDN/DN\fR as a complete directory name and to use it as the
  84 new current location.  Without the \fI-absolute\fR flag, the
  85 name is assumed to be relative to the previous location.
  86
  87 The special value \fB".."\fR is recognized by \fIsaucer\fR as a
  88 valid name and causes the current location to be moved one level
  89 up (towards the root) in the directory.
  90 .SS quit
  91 Unbinds from the directory and exits \fIsaucer\fR.
  92 .SS "search <filter> [-object RDN/DN] [-absolute] [-scope <scope>]"
  93 Searches the directory for entries which match the \fI<filter>\fR
  94 expression.  For more information on the syntax of the \fI<filter>\fR
  95 argument, see "RFC 1588 - A String Representation of LDAP Search
  96 Filters".
  97
  98 If the \fI-object\fR argument is used, it specifies the base of the
  99 directory search.  In its absence, the current location (see the
 100 \fBmoveto\fR command) is used as the search base.  The \fI-absolute\fR
 101 argument controls whether the \fIRDN/DN\fR given with the
 102 \fI-object\fR flag is a complete directory name or is relative to the
 103 current location.
 104
 105 The \fI-scope\fR argument controls the depth of the search.  It
 106 accepts one of the keywords \fIbase\fR, \fIonelevel\fR, or
 107 \fIsubtree\fR to search within the base object, its immediate
 108 children, or all of its subordinates respectively.  The search depth
 109 is preserved across commands, so subsequent searches will use the
 110 previously entered depth setting if a new one is not given.
 111 \fISaucer\fR defaults to a \fIonelevel\fR search depth at startup.
 112 .SS "set [-aliasderef <deref>] [-sizelimit N] [-timelimit seconds]"
 113 Displays or modifies settings which apply to all directory operations
 114 issued by \fIsaucer\fR.  Without arguments, the current settings are
 115 displayed.  If options are given, the settings are changed and the new
 116 values are displayed.
 117
 118 The \fI-aliasderef <deref>\fR argument controls how the directory
 119 handles alias entries that it encounters.  The value of \fI<deref>\fR
 120 must be one of \fInever\fR, \fIsearch\fR, \fIfind\fR, or \fIalways\fR.
 121
 122 A value of \fInever\fR tells the directory not to follow through any
 123 aliases it encounters.
 124
 125 A value of \fIfind\fR tells the directory to follow through an alias
 126 if it occurs as the base of a \fBlist\fR, \fBsearch\fR, or \fBshow\fR
 127 command.
 128
 129 A value of \fIsearch\fR tells the directory to follow through an alias
 130 when performing a \fBsearch\fR command.  In other words, when
 131 performing a search, the attributes of the entry an alias points to
 132 will be tested against the filter expression rather than the alias
 133 itself.
 134
 135 A value of \fIalways\fR combines the meanings of the \fIfind\fR and
 136 \fIsearch\fR values, i.e., aliases are always dereferenced before
 137 being acted upon.
 138
 139 The \fI-sizelimit N\fR argument sets the maximum number of entries
 140 that will be returned by directory for \fBlist\fR and \fBsearch\fR
 141 commands to \fIN\fR.  The directory server itself may impose a limit,
 142 in which case the lesser of the two limits is used.  A value of
 143 \fI0\fR may be used to request as many entries as possible.
 144
 145 The \fI-timelimit seconds\fR argument sets the maximum amount of time
 146 allowed for a \fBlist\fR, \fBsearch\fR, or \fBshow\fR command.  Note
 147 that this value is simply passed to the directory server, so the
 148 enforcement of the time limit is up to the server.  A value of \fI0\fR
 149 may be used to request no time limit.
 150 .SS "show [RDN/DN] [-absolute]"
 151 Displays the attributes of a directory entry.
 152
 153 If an \fIRDN/DN\fR is given, it specifies the entry whose attributes
 154 are to be shown.  In its absence, the current location (see the
 155 \fBmoveto\fR command) is used.  The \fI-absolute\fR argument controls
 156 whether the \fIRDN/DN\fR is a complete directory name or is relative
 157 to the current location.
 158
 159 The attributes \fIaudio\fR, \fIjpegPhoto\fR, \fIpersonalSignature\fR,
 160 and \fIphoto\fR are known by \fIsaucer\fR to be binary values and are
 161 therefore not displayed.  Other attributes which have binary encodings
 162 will be displayed by \fIsaucer\fR and will probably appear as garbage
 163 on the screen.
 164 .SH FILES
 165 ~/.saucerrc    The saucer startup command file.
 166 .SH "SEE ALSO"
 167 ldap(3), RFC 1485, RFC 1588
 168 .SH DIAGNOSTICS
 169 \fIsaucer\fR uses the ldap_perror() routine to print a message
 170 whenever an error is returned by the Directory server or the LDAP
 171 library.
 172 .SH "TO DO"
 173 The new LDAP 3.1 ldap_XXX2text() routines should be used instead of
 174 the code built into saucer.
 175
 176 The ability to read the X500UserName and credentials from the
 177 ~/.saucerrc file should be added.  There should also be a way to have
 178 saucer prompt the user for their password.
 179
 180 Attribute types which are binary are hard-coded into saucer.  Ideally
 181 saucer should also try to detect which ones aren't displayable at
 182 runtime.
 183 .SH AUTHOR
 184 Eric Rosenquist, Enterprise Solutions Limited.
 185 .br
 186 Eric.Rosenquist@esltd.com