SAUCER(1)

NAME
saucer - interactive X.500 Directory client program

SYNOPSIS
saucer [-h host] [-p portnumber] [-u X500UserName] [-c credentials] [-d debug-level]

DESCRIPTION
saucer is used to navigate and perform searches on an X.500 Directory via the Lightweight Directory Access Protocol (LDAP).

OPTIONS

-h hostname
    Used to specify the name or IP number of an LDAP host to which saucer should connect. If this flag is omitted, 127.0.0.1 is used.

-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 (389) is used.

-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: "cn=George Castanza, o=Vandelay Industries, c=US" Don't forget to put quotes around the name if it contains blanks.

-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 -u flag, an unauthenticated bind will be attempted. If neither flag is given, an anonymous bind will be attempted.

-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.

COMMANDS
saucer 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 "s" will be interpreted by saucer as the search command, and "sh" will be interpreted as the show command. The set command cannot be abbreviated since both "s" and "se" will be interpreted as the search 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 current location, which is set with the moveto command. All commands that accept a directory name have an optional -absolute flag which causes saucer to interpret the name as a complete X.500 name rather than one that is relative to the current location.

  help [command]
Provides brief online help giving the available commands and their syntax. If command is specified, the syntax for the command is shown. ``help'' by itself simply provides a list of the available commands.

  list [RDN/DN] [-absolute]
Displays the names of a directory node's subordinates. If an RDN/DN is given, it specifies the entry whose subordinates are to be listed. In its absence, the current location (see the moveto command) is used. The -absolute argument controls whether the RDN/DN is a complete directory name or is relative to the current location.

  moveto [RDN/DN] [-absolute]
Displays or modifies saucer's current location in the directory. Without arguments, the current location is displayed. If an RDN/DN is given, the current location is modified and the new value is displayed. The -absolute flag causes saucer to treat the entered RDN/DN as a complete directory name and to use it as the new current location. Without the -absolute flag, the name is assumed to be relative to the previous location. The special value ".." is recognized by saucer as a valid name and causes the current location to be moved one level up (towards the root) in the directory.

  quit
Unbinds from the directory and exits saucer.

  search <filter> [-object RDN/DN] [-absolute] [-scope <scope>]
Searches the directory for entries which match the <filter> expression. For more information on the syntax of the <filter> argument, see "RFC 1588 - A String Representation of LDAP Search Filters". If the -object argument is used, it specifies the base of the directory search. In its absence, the current location (see the moveto command) is used as the search base. The -absolute argument controls whether the RDN/DN given with the -object flag is a complete directory name or is relative to the current location. The -scope argument controls the depth of the search. It accepts one of the keywords base, onelevel, or subtree 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. Saucer defaults to a onelevel search depth at startup.

  set [-aliasderef <deref>] [-sizelimit N] [-timelimit seconds]
Displays or modifies settings which apply to all directory operations issued by saucer. Without arguments, the current settings are displayed. If options are given, the settings are changed and the new values are displayed. The -aliasderef <deref> argument controls how the directory handles alias entries that it encounters. The value of <deref> must be one of never, search, find, or always. A value of never tells the directory not to follow through any aliases it encounters. A value of find tells the directory to follow through an alias if it occurs as the base of a list, search, or show command. A value of search tells the directory to follow through an alias when performing a search 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 always combines the meanings of the find and search values, i.e., aliases are always dereferenced before being acted upon. The -sizelimit N argument sets the maximum number of entries that will be returned by directory for list and search commands to N. The directory server itself may impose a limit, in which case the lesser of the two limits is used. A value of 0 may be used to request as many entries as possible. The -timelimit seconds argument sets the maximum amount of time allowed for a list, search, or show 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 0 may be used to request no time limit.

  show [RDN/DN] [-absolute]
Displays the attributes of a directory entry. If an RDN/DN is given, it specifies the entry whose attributes are to be shown. In its absence, the current location (see the moveto command) is used. The -absolute argument controls whether the RDN/DN is a complete directory name or is relative to the current location. The attributes audio, jpegPhoto, personalSignature, and photo are known by saucer to be binary values and are therefore not displayed. Other attributes which have binary encodings will be displayed by saucer and will probably appear as garbage on the screen.

FILES
~/.saucerrc The saucer startup command file.

SEE ALSO
ldap(3), RFC 1485, RFC 1588

DIAGNOSTICS
saucer uses the ldap_perror() routine to print a message whenever an error is returned by the Directory server or the LDAP library.

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.

AUTHOR
Eric Rosenquist, Enterprise Solutions Limited.
Eric.Rosenquist@esltd.com