Return to q-dish.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/q-dish.tex, revision 1.1

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter{The OSI Directory}
        !             4: \label{dir_model}
        !             5: 
        !             6: This Chapter is designed as a quick introduction to the model of X.500
        !             7: directories, to provide the reader with sufficient information to be able to
        !             8: understand the following Chapters.
        !             9: 
        !            10: \section {The Model}
        !            11: The OSI Directory is intended to support human user querying, allowing
        !            12: users to find, {\em inter alia}, telephone and address information of
        !            13: organisations and other users.  
        !            14: 
        !            15: It is also intended to support electronic
        !            16: communication such as message handling systems and file transfer.
        !            17: The Directory provides name to address mapping to support, for example, OSI
        !            18: presentation address look-ups. Message handling systems will be provided with 
        !            19: support for user-friendly naming, security and
        !            20: distribution lists.
        !            21: 
        !            22: \tagfigure[tp]{q-dit}{Example DIT}{qfig:dit}
        !            23: 
        !            24: In essence the Directory is a database with certain key characteristics.
        !            25: \begin{itemize}
        !            26: \item
        !            27: The Directory is intended to be very large and highly distributed. It is
        !            28: anticipated that the Directory will be distributed largely on an
        !            29: organisational basis.
        !            30: \item
        !            31: The Directory is hierarchically structured, the entries being arranged in
        !            32: the form of a tree called the Directory Information Tree (DIT).
        !            33: An example DIT is shown in Figure~\ref{qfig:dit}. 
        !            34: Entries near the root of the tree will usually represent
        !            35: objects such as countries (e.g., `GB') and organisations (e.g., `University 
        !            36: College London'), entries at or near the leaves
        !            37: of the tree will represent people (e.g., `Colin Robbins'), 
        !            38: equipment or application processes.
        !            39: 
        !            40: \item
        !            41: Read and search operations will dominate over modification operations.
        !            42: \item
        !            43: Temporary inconsistencies in the data are acceptable.  This greatly
        !            44: facilitates the replication of data in the Directory by obviating concerns
        !            45: about record locking and atomic operations.
        !            46: \end{itemize}
        !            47: 
        !            48: 
        !            49: \section{Information Representation}
        !            50: There are various structures needed to represent the data required in the
        !            51: directory database. These are described
        !            52: briefly below.
        !            53: 
        !            54: \subsection {Object Identifiers}
        !            55: An important part of the OSI world is the Object Identifier (OID).
        !            56: 
        !            57: An OID is a hierarchy of numbers used to uniquely describe various objects
        !            58: within the OSI world: for example, ``1.0.8571.1.1'' describes the FTAM
        !            59: protocol; ``0.9.2342.19200300.99.1'' 
        !            60: defines a QUIPU Attribute Type.
        !            61: The strings of numbers look ``horrible'' and can be difficult to remember.
        !            62: As such, QUIPU provides a mapping from OIDs to ``strings'', so that 
        !            63: easy to remember strings can be used in place of the numeric OIDs, for
        !            64: example ``iso ftam'' or ``quipuAttributeType''.
        !            65: 
        !            66: The mapping are defined in a set of oidtables which are discussed
        !            67: in Section~\ref{oidtables}. 
        !            68: 
        !            69: \subsection {Attributes}
        !            70: 
        !            71: \tagfigure[tp]{q-entry}{Structure of an Entry}{qfig:entry}
        !            72: 
        !            73: The directory holds information about various entities, such as a person or
        !            74: an organisation.  The information is held in an information object,
        !            75: typically referred to as an {\em entry}. 
        !            76: An entry consists of a set of one of more attributes
        !            77: (see Figure~\ref{qfig:entry}).
        !            78: 
        !            79: An attribute is represented by an attribute type, and set of attribute values.
        !            80: An attribute with a single value is represented as follows:-
        !            81: \begin{quote}  
        !            82: $<$Attribute Type$>$ ``='' $<$Attribute Value$>$
        !            83: \end{quote}
        !            84: The attribute type can either be a string (which must be in the attribute
        !            85: oidtable --- see Section~\ref{oidtables}) or the OID in a dotted decimal
        !            86: format.
        !            87: 
        !            88: Each attribute value is represented by a string, the format of the attribute value
        !            89: depends upon the
        !            90: syntax defined in the oidtables, but in general will be a string.
        !            91: 
        !            92: So
        !            93: \begin{quote}\begin{verbatim}  
        !            94: roomNumber = G24
        !            95: 2.5.4.20   = 453-5674
        !            96: commonName = Colin Robbins & Colin John Robbins
        !            97: photo      = {ASN} 0308207b4001488001fd...
        !            98: \end{verbatim}\end{quote}
        !            99: is an example of an entry, with 4 attributes. The ``commonName'' attribute
        !           100: is multi-valued, 
        !           101: with the two values separated by the ``\&'' symbol.
        !           102: Notice how the ``photo'' attribute does not have a specific string format,
        !           103: so a hexadecimal ``ASN.1'' representation is used.
        !           104: ``2.5.4.20'' is an Object Identifier represented in numeric form.
        !           105: 
        !           106: 
        !           107: \subsection {Names}
        !           108: \label{quipu_name}
        !           109: Within an entry, some attributes (generally one) have special importance,
        !           110: and are called {\em distinguished attributes}.  The collection of these
        !           111: attributes form the {\em Relative Distinguished Name}
        !           112: (RDN).\index{RDN}
        !           113: 
        !           114: An RDN is usually represented by a single valued attribute, thus
        !           115: \begin{quote}  \begin{verbatim}
        !           116: commonName = "Alan Turland"
        !           117: organization = "University College London"
        !           118: \end{verbatim}\end{quote}
        !           119: are valid RDNs. 
        !           120: 
        !           121: An RDN made up of multiple distinguished attributes uses the \verb+%+ symbol
        !           122: to separate the values, for
        !           123: example
        !           124: \begin{quote}  \begin{verbatim}
        !           125: userid = quipu % commonName = "Colin Robbins"
        !           126: \end{verbatim}\end{quote}
        !           127: 
        !           128: A {\em Distinguished Name} (DN) is the sequence of RDNs that uniquely define
        !           129: a node in the Directory Information Tree (DIT).
        !           130: These are represented as follows:-
        !           131: \begin{quote}
        !           132: RDN [ ``@'' RDN \ldots]
        !           133: \end{quote}
        !           134: So
        !           135: \begin{quote}\small\begin{verbatim}
        !           136: countryName = GB @ organization = University College London 
        !           137: \end{verbatim}\end{quote}
        !           138: is an example of a valid DN.
        !           139: 
        !           140: In some cases an RDN or DN is specified relative to a node other than the
        !           141: root in the DIT.
        !           142: To be unambiguous a DN may be rooted using a leading ``@'', for example
        !           143: \begin{quote}\small\begin{verbatim}
        !           144: @ countryName = GB @ organization = University College London 
        !           145: \end{verbatim}\end{quote}
        !           146: 
        !           147: 
        !           148: \section{Directory User Agent}
        !           149: The Directory User Agent (DUA) is the entity you as a user will connect to,
        !           150: it will help you formulate your queries, and then pass them to the
        !           151: Directory, and show you the results.
        !           152: 
        !           153: The X.500 standard defines only the protocol the DUA should use when taking
        !           154: to the Directory, and as such DUAs come in many varieties, but the basic
        !           155: concepts are the same.
        !           156: 
        !           157: A DUA talks to the directory using the Directory Access Protocol
        !           158: (DAP)\index{DAP}.
        !           159: 
        !           160: The following Chapters of this Part of the Manual describe five such
        !           161: interfaces: 
        !           162: \begin{describe}
        !           163: \item [dish:]  The DIrectory SHell\\
        !           164:                This interface give a user full access to the DAP, and
        !           165: as such may be complex for novice users.
        !           166: \item [sid:]   Steve's Interface to Dish\\
        !           167:                A set of scripts that make Dish usable for novice users.
        !           168: \item [fred:]  FRont End to Dish\\
        !           169:                Fred provides a White Pages User Interface, which hides most
        !           170: of the complexity of the OSI directory.
        !           171: \item [widget:] A curses based windowing interface,
        !           172: \item [sunint:] A suntools based windowing interface.
        !           173: \end{describe}
        !           174: 
        !           175: We should point out here that 
        !           176: Widget and Sunint are not considered fully developed interfaces,
        !           177: but are included to give would be DUA developers examples of how 
        !           178: the procedural interface discussed in Section~\ref{proc_model} can be used.
        !           179: 
        !           180: 
        !           181: \section{Directory System Agent}
        !           182: 
        !           183: \tagfigure[tp]{q-dsa}{DUA/DSA Interaction}{qfig:dsa}
        !           184: 
        !           185: The Directory System Agent (DSA) is the entity that generates the results to
        !           186: requests from a DUA.
        !           187: It may handle the request itself, ask another DSA (using the Directory System
        !           188: Protocol\index{DSP}), or advise the DUA to
        !           189: contact another DSA (see Figure~\ref{qfig:dsa}).
        !           190: This part of the directory is discussed more in Parts III and V of this
        !           191: manual.  Here we shall concentrate on the DUA.
        !           192: 
        !           193: 
        !           194: \chapter{DISH}
        !           195: \label{dish}
        !           196: 
        !           197: This Chapter describes DISH, a DIrectory SHell interface to the Directory.
        !           198: It provides an interface to the Directory in an similar manner
        !           199: to the way that \MH/ provides an interface to a message handling systems.
        !           200: As with \MH/, dish can either be invoked as a single process with the full
        !           201: repertoire of commands built in, or it can be invoked by individual shell
        !           202: commands.
        !           203: This latter style allows dish to be used with others tools to provide very
        !           204: flexible access to the directory.
        !           205: 
        !           206: Dish provides a very powerful interface onto the Directory and gives a user
        !           207: access to the full Directory Access Protocol(DAP).
        !           208: The price of such comprehensiveness is complexity.
        !           209: Dish has a large number of flags, and both the syntax and volume of typing
        !           210: required can seem forbidding to the novice user.
        !           211: One compromise solution is to use dish to build interfaces which are easier
        !           212: to use and more intuitive, for example SID (see Chapter~\ref{DUA:sid}).
        !           213: 
        !           214: To run DISH in interactive mode invoke \man dish(1c), then issue any of the
        !           215: commands described in Sections~\ref{dish_start} through \ref{sequences}.
        !           216: This mode of operation is especially useful for novice users.
        !           217: The process of connecting to the Directory -- binding --
        !           218: takes place automatically when the program is invoked, and an unbind
        !           219: is issued when you quit.  
        !           220: 
        !           221: The arguments to \man dish(1c) are the same as for bind (see 
        !           222: Section~\ref{dish_bind}), with the addition of a `-pipe' flag
        !           223: which is used to start dish in ``shell'' mode (see Section~\ref{dish_shell})
        !           224: (NOTE: ``dish -pipe \&'' has the same effect as the shell command ``bind'').
        !           225: 
        !           226: \section {Commands}
        !           227: 
        !           228: Each of the DISH commands described below has a large number of valid flags,
        !           229: the full names of the flags are given below, however the shortest unique
        !           230: name is sufficient to select the flag.
        !           231: Similarly, when dish is used interactively the shortest unique name is taken
        !           232: for the command name (e.g. ``l'' for ``list'').
        !           233: There is an exception in that ``sh'' is interpreted as ``showentry'', 
        !           234: ``shown'' must be typed for ``showname''.
        !           235: 
        !           236: The additional flag \tt -help \rm \ can be specified with 
        !           237: every command to get limited runtime help.
        !           238: 
        !           239: \subsection{Moveto}
        !           240: \label{dish_start}
        !           241: With nearly every command it is possible to supply the distinguished name of
        !           242: the object you want to reference.
        !           243: In the syntax this is represented by 
        !           244: \begin{verbatim}
        !           245:        <object>.  
        !           246: \end{verbatim}
        !           247: An initial `\tt @\rm ' in an object description specifies that the name
        !           248: is relative to the root of the Directory Information Tree (DIT), 
        !           249: otherwise the name is relative to the current
        !           250: position in the DIT.  
        !           251: The special name component `..' is used to mean `one
        !           252: position up' from the current position.  
        !           253: Some examples of valid names and their interpretation relative to
        !           254: how a distinguished name is built up are shown below by the following
        !           255: sequence of names:
        !           256: 
        !           257: \begin{description}
        !           258: 
        !           259: \item [\verb+"@c=GB@o=University College London@ou=Computer Science"+:]
        !           260: The specified object is \\
        !           261: ``c= GB @ o= University College London @ ou= Computer Science''.
        !           262: 
        !           263: \item [\verb+"cn=Colin Robbins"+:]
        !           264: describes the object
        !           265: cn=Colin Robbins relative to the current 
        !           266: position (``c= GB @ o= University College London @ ou= Computer Science @ cn= Colin Robbins''). 
        !           267: Spaces in a name will be seen as the start of a separate 
        !           268: argument by the shell, so the name must be quoted.
        !           269: 
        !           270: \item [\verb+"..@cn=Steve Titcombe"+:]
        !           271: describes the entry 
        !           272: cn=Steve Titcombe at the same level
        !           273: in the DIT as the current position (``c= GB @ o= University College London @
        !           274: ou= Computer Science @ cn= Steve Titcombe'').
        !           275: 
        !           276: \end{description}
        !           277: 
        !           278: Objects can also be expressed in the form of sequence numbers and nicknames.
        !           279: See sections \ref{sequences} and \ref{quipurc}.
        !           280: 
        !           281: When you specify an object, the current position in the DIT is not changed.
        !           282: To change the current position you should use
        !           283: \begin{verbatim}
        !           284: moveto [-[no]pwd] [-[no]check] 
        !           285:        [-sequence <name>] [-nosequence] <position>
        !           286: \end{verbatim}
        !           287: 
        !           288: The \tt -pwd \rm \ flag tells moveto to print the current position in the
        !           289: DIT.
        !           290: The current position can also be changed with the \tt -move\rm \ flag to 
        !           291: showentry and list (see Sections~\ref{dua:list} and ~\ref{dua:show}).
        !           292: 
        !           293: The \tt -nocheck \rm \ flag tells moveto NOT to check the entry exists,
        !           294: normally, moveto will invoke a `\verb"read"' to check the named entry exists.
        !           295: 
        !           296: 
        !           297: \subsection{Showentry}
        !           298: \label{dua:show}
        !           299: 
        !           300: \begin{verbatim}
        !           301: showentry [<object>] [-[no]cache] [-[no]name]
        !           302:           [-[no]move] [<any of the read arguments>]
        !           303: \end{verbatim}
        !           304: 
        !           305: Showentry will show the distinguished 
        !           306: name of the current entry (unless \tt -noname\rm \ is specified), 
        !           307: followed by each attribute
        !           308: specified in the read arguments. 
        !           309: If the `\tt -all\rm ' is given all attributes will be shown.
        !           310: If insufficient information resides in the local cache, a `\tt read\rm ' will
        !           311: be performed.
        !           312: 
        !           313: \tt -cache\rm \ is used the tell showentry to use cached information only ---
        !           314: do not issue a read operation. 
        !           315: This is used to see what the DUA has cached, and then get information when
        !           316: the local DSA is unavailable.
        !           317: 
        !           318: \tt -nocache\rm \ is used to enforce a directory read, this is used to update the cache
        !           319: directly.
        !           320: 
        !           321: \tt -move\rm \ is used to tell dish to change the current position in the DIT
        !           322: to the object specified. 
        !           323: 
        !           324: \subsubsection{read flags}
        !           325: 
        !           326: These flags are used by showentry(1), showname(1), search(1) and modify(1).
        !           327: 
        !           328: \begin{quote}\begin{verbatim}
        !           329: [-[no]types <attribute-type> *] [-[no]all] 
        !           330: [-[no]value] [-[no]show] 
        !           331: [-[no]key] [-edb]
        !           332: [-proc <syntax> <process>]
        !           333: [-sequence <name>] [-nosequence]
        !           334: \end{verbatim}\end{quote}
        !           335: 
        !           336: The \tt all\rm \ flag request that all attribute are read (default).
        !           337: 
        !           338: The \tt value\rm \ flag reads the attribute value, which is the default, 
        !           339: the inverse is to read the attribute types only.
        !           340: 
        !           341: The \tt novalue\rm \ flag says print the attribute types only.
        !           342: 
        !           343: The \tt show\rm \ flag displays the information read.
        !           344: 
        !           345: The \tt key\rm \ flag determines whether the key (attribute type) will 
        !           346: be shown along with the attribute value.
        !           347: 
        !           348: The \tt edb\rm \ flag requests that the data is displayed in ``EDB'' format,
        !           349: that is, a format which can be used in QUIPU data files.
        !           350: 
        !           351: The \tt type\rm \ flag requests that only the supplied attributes are 
        !           352: read from the DSA, the inverse of this \tt -notype \rm \ does not 
        !           353: prevent the attributes being read (as there is no
        !           354: easy mechanism to perform this within X.500), 
        !           355: but it does stop them being shown.
        !           356: 
        !           357: The \tt proc\rm \ flag is used to instruct the display routines to uses an
        !           358: external process to display the attribute.
        !           359: For example if you have a process that displays presentation elements
        !           360: representing ``OID's'' in a particular
        !           361: way, then you can use
        !           362: \begin{quote}\begin{verbatim}
        !           363: showentry -proc OID /usr/bin/oid_display_process
        !           364: \end{verbatim}\end{quote}
        !           365: then all OIDs will be displayed using ``/usr/bin/oid\_display\_process''.
        !           366: 
        !           367: The \tt sequence\rm \ flag is used to control sequences, sequences
        !           368:  are described in Section~\ref{sequences}.
        !           369: 
        !           370: \subsection{List}
        !           371: \label{dua:list}
        !           372: \begin{verbatim}
        !           373: list [<object>] [-nocache] [-noshow] [-[no]move]
        !           374: \end{verbatim}
        !           375: This function displays all the children below your current position.
        !           376: 
        !           377: \tt -nocache\rm \ tells list to re-read the directory - do not use cached information.
        !           378: 
        !           379: \tt -noshow\rm \ tells list not to display the names found, but 
        !           380: still construct sequences (see section \ref{sequences}).
        !           381: 
        !           382: \tt -move\rm \ is used to tell dish to change the current position in the DIT
        !           383: to the object specified. 
        !           384: 
        !           385: \subsection{Search}
        !           386: \label{search}
        !           387: 
        !           388: \begin{verbatim}
        !           389: search  [[-object] <object>] 
        !           390:         [-baseobject] [-singlelevel] [-subtree]
        !           391:         [[-filter] <filter>] 
        !           392:         [-[no]relative] [-[no]searchaliases]
        !           393:         [-[no]partial] [-hitone]
        !           394:         [<any of the read arguments>]
        !           395: \end{verbatim}
        !           396: 
        !           397: Search the DIT starting at the object specified, for entries that match a
        !           398: filter.
        !           399: When an entry is found to match the filter, its distinguished name is printed
        !           400: unless a `\tt-show\rm ' option is 
        !           401: specified, when the entry is displayed.
        !           402: 
        !           403: If no filter is specified the default filter (which matches any object in
        !           404: the DIT) is used.
        !           405: 
        !           406: If no flags are given, then the sole allowed parameter is taken to be the
        !           407: filter (NOT the base object as in ALL the other commands).
        !           408: The flags \tt -filter\rm \ and \tt -object \rm \ are supplied to allow the
        !           409: user to specify if both a filter and base object (NOTE only one need be
        !           410: flagged).
        !           411: For example, the following are all valid search commands
        !           412: \begin{quote}\begin{verbatim}
        !           413: search
        !           414: search <filter>
        !           415: search -filter <filter>
        !           416: search -object <object>
        !           417: search -filter <filter> -object <object>
        !           418: search <filter> -object <object>
        !           419: search -filter <filter> <object>
        !           420: \end{verbatim}\end{quote}
        !           421: Whereas 
        !           422: \begin{quote}\begin{verbatim}
        !           423: search <object>           (interpreted as a filter !)
        !           424: search <filter> <object>
        !           425: \end{verbatim}\end{quote}
        !           426: are not valid.
        !           427: 
        !           428: The flag `\tt -singlelevel\rm ' will search all the children
        !           429: from the current position. 
        !           430: The flag `\tt -subtree\rm ' searches all the 
        !           431: levels below the current position recursively.
        !           432: The default is
        !           433: `\tt -singlelevel\rm '.
        !           434: 
        !           435: For example:- 
        !           436: \begin{verbatim}
        !           437: search -object 
        !           438:    "@c=GB@o=University College London@ou=Computer Science"
        !           439:    -subtree -filter "cn=colin robbins" -type telephonenumber -show
        !           440: \end{verbatim}
        !           441: will search the subtree below `c=GB @ o=University College London @ ou=Computer Science' for
        !           442: an exact match of ``colin robbins'', and call showentry to 
        !           443: display the {\em telephonenumber} attribute.
        !           444: 
        !           445: The \tt -norelative\rm \ flag is used to tell \verb"showname" to print the full
        !           446: distinguished name of the results, otherwise the name relative to the current
        !           447: position is printed.
        !           448: 
        !           449: The \tt -[no]searchaliases\rm \ flag direct the search as to whether aliases
        !           450: encountered in the search should be dereferenced and searched.
        !           451: 
        !           452: The \tt -hitone\rm \ flag is used to tell Dish to consider it an error if
        !           453: the search returns more than one entry.  This is particularly useful when
        !           454: using Dish from shell scripts (see Section~\ref{dish_shell}).
        !           455: 
        !           456: From time to time, search will not be able to do the entire search, and will
        !           457: return partial results, the \tt -nopartial\rm \ directs dish not to print
        !           458: the partial result information.  To see the full set of partial results, both
        !           459: \tt -partial\rm \ and \tt -show\rm \ are needed, otherwise a summary is
        !           460: printed.
        !           461: 
        !           462: \subsubsection{More on Matching}
        !           463: 
        !           464: As well as an exact equality match, the 
        !           465: following types of match can be specified
        !           466: \begin{quote}\begin{verbatim}
        !           467: ~=     Approximately equals.
        !           468: >=     Greater than or equal.
        !           469: <=     Less than or equal.
        !           470: \end{verbatim}\end{quote}
        !           471: 
        !           472: When searching for an exact match (`=')
        !           473: the `\tt *\rm ' character is used as a wildcard, and a substring
        !           474: match takes place (unless only a `\tt *\rm ' is specified, when a {\em
        !           475: presence} match is used - hence any entry 
        !           476: containing that attribute will be matched). 
        !           477: 
        !           478: Filter items can be linked with {\em and} `\tt \&\rm ', or {\em or} 
        !           479: `\tt $|$\rm '.  Brackets `\tt( )\rm ' 
        !           480: should be used to enforce the boolean 
        !           481: ordering of the expressions, otherwise the evaluation is left to right.
        !           482: A {\em not} `\tt !\rm ' can be used to specify the boolean not operator.
        !           483: 
        !           484: If a filter does not have a type specified e.g., ``-filter steve'',
        !           485: then an approximate match for the specified common name is assumed
        !           486: (in this case ``-filter cn$\tilde{\ }$=steve'' is assumed).
        !           487: 
        !           488: A more complex example of a filter 
        !           489: that searches for anybody whose is a member of staff 
        !           490: or a student, who has a ``drink'' attribute,
        !           491: whose name approximately matches ``steve'', but whose surname is 
        !           492: not ``Kille'':-
        !           493: \begin{verbatim}
        !           494:       cn~=steve & (userClass = staff | userClass = student) &
        !           495:                   (! surname = Kille) & drink = *
        !           496: \end{verbatim}
        !           497: 
        !           498: A list of all the attributes is given in 
        !           499: Chapter~\ref{syntaxes}, together with a description of the type matching of
        !           500: matching allowed.
        !           501: 
        !           502: \subsection {Add Entry}
        !           503: \label{dish:add}
        !           504: 
        !           505: \begin{verbatim}
        !           506: add [<object>] [-draft <draft> [-noedit]] [-newdraft]
        !           507:     [-template <draft>] [-objectclass <objectclass>]
        !           508: \end{verbatim}
        !           509: 
        !           510: Add is used to add entries to the DIT.
        !           511: This invokes editentry
        !           512: on the draft entry.
        !           513: If there is not a draft entry specified a draft entry of the specified 
        !           514: objectclass (default --- thornperson \& quipuObject) is created.
        !           515: The default draft file is ``.dishdraft'' in your home directory, this can be
        !           516: altered with the -draft option.
        !           517: 
        !           518: When editing has finished the entry is added to the DIT
        !           519: (the \tt -noedit\rm \ flag following a \tt -draft\rm \ stops the editor
        !           520: being invoked).
        !           521: 
        !           522: \tt -newdraft\rm \ causes the current draft to be overwritten with a new
        !           523: template of the appropriate objectclass.
        !           524: 
        !           525: \tt -template\rm \ is used to specify a template that should be used during
        !           526: editing.
        !           527: 
        !           528: On successful completion of the add, the draft entry is renamed with a suffix of
        !           529: ``.old''.
        !           530: 
        !           531: \subsection{Editentry}
        !           532: 
        !           533: \begin{verbatim}
        !           534: editentry <draft>
        !           535: \end{verbatim}
        !           536: 
        !           537: editentry invokes an editor (as defined by the users
        !           538: \$EDITOR environment variable) on the current draft entry.
        !           539: In a future release it is hoped to have an editor that knows about the syntax
        !           540: of an entry, and thus ensures that the entry you have supplied is syntactically
        !           541: correct.
        !           542: 
        !           543: \subsection {Delete Entry}
        !           544: \begin{verbatim}
        !           545: delete [<object>]
        !           546: \end{verbatim}
        !           547: The specified entry is removed from the DIT.
        !           548: 
        !           549: \subsection {Modify Entry}
        !           550: \label{dish:modify}
        !           551: \begin{verbatim}
        !           552: modify [<object>] [-draft <draft> [-noedit]] [-newdraft] 
        !           553:        [<any of the showentry arguments>]
        !           554: \end{verbatim}
        !           555: Modify is used to modify existing entries in the DIT.  Initially showentry
        !           556: is used to get the current DIT entry, and place a copy of if in your
        !           557: .dishdraft file.  If the -draft option is specified the given file is used.
        !           558: After editing, any changes to the entry are sent to the directory
        !           559: (the \tt -noedit\rm \ flag following a \tt -draft\rm \ stops the editor
        !           560: being invoked).
        !           561: 
        !           562: The draft file is handled in the same way as with add, except, when a
        !           563: new draft is created, the current values of the attributes are read from the
        !           564: directory.
        !           565: 
        !           566: \subsection {ModifyRDN}
        !           567: \begin{verbatim}
        !           568: modifyrdn [<object>] -name <newrdn> [-[no]delete]
        !           569: \end{verbatim}
        !           570: This is used to modify the RDN of an entry.
        !           571: 
        !           572: The \tt -nodelete\rm \ flag is used to prevent the old RDN being removed as
        !           573: an attribute of the entry.
        !           574: 
        !           575: 
        !           576: \subsection{Showname}
        !           577: \label{showname}
        !           578: 
        !           579: \begin{verbatim}
        !           580: showname [<object>] [-compact] [-[no]cache] 
        !           581:          [<any of the read arguments>]
        !           582: \end{verbatim}
        !           583: 
        !           584: A name can be printed either in compact form, just showing the distinguished
        !           585: name, or by showing the distinguished attributes.
        !           586: 
        !           587: \subsection{Compare}
        !           588: \label{dua:compare}
        !           589: \begin{verbatim}
        !           590: compare [<object>] -attribute <attribute> [-[no]print]
        !           591: \end{verbatim}
        !           592: For example
        !           593: \begin{quote}\begin{verbatim}
        !           594: compare userclass=student
        !           595: \end{verbatim}\end{quote}
        !           596: This command has a return value of true or false (1 or 0).
        !           597: 
        !           598: If `\tt -print\rm ' is specified the strings ``TRUE'' or ``FALSE'' are printed.
        !           599: 
        !           600: \subsection {Squid}
        !           601: 
        !           602: \begin{verbatim}
        !           603: squid [-sequence [<sequence name>]] 
        !           604:       [-alias <alias>] [-version]
        !           605: \end{verbatim}
        !           606: 
        !           607: The command \pgm {squid} (Status QUIpu Dish) with no 
        !           608: parameters will inform you of the current status
        !           609: of you dish process for example:
        !           610: \begin{quote}\begin{verbatim}
        !           611: Connected to Armadillo at Internet=128.40.16.220+2005
        !           612: Current position: @c=GB@o=Nottingham University
        !           613: User name: @c=GB@o=University College London@
        !           614:            ou=Computer Science@cn=Colin Robbins
        !           615: Current sequence 'default'
        !           616: \end{verbatim}\end{quote}
        !           617: 
        !           618: \tt -sequence\rm \ makes squid print the specified sequence.
        !           619: Sequences are described in Section~\ref{sequences}.
        !           620: 
        !           621: \tt -alias\rm \ adds the given DN to the current sequence.
        !           622: 
        !           623: \tt -version\rm \ print the version number of the dish process and
        !           624: associated libraries.
        !           625: 
        !           626: \subsection {Bind}
        !           627: \label{dish_bind}
        !           628: 
        !           629: \begin{verbatim}
        !           630: bind [-noconnect] [[-user] [<username>]] 
        !           631:      [-password [<password>]] [-[no]refer] [-call <dsaname>] 
        !           632:      [-simple] [-protected] [-strong] [-noauthentication]
        !           633: \end{verbatim}
        !           634: 
        !           635: This is used to (re)connect to the directory.  This is not normally
        !           636: required, as each command will bind as necessary, but allows advanced users
        !           637: to contact specified DSA's.
        !           638: 
        !           639: \tt -noconnect\rm \ is used to start dish (and cache) without connection to a
        !           640: directory.
        !           641: 
        !           642: For an explanation of the `\tt -cache\rm ' flag see Section~\ref{dua_cache}
        !           643: 
        !           644: \tt -norefer\rm \ is used to tell Dish whether to automatically follow
        !           645: referrals issued by the DSA.
        !           646: 
        !           647: To connect to the directory you need to be authenticated.
        !           648: The are four flags to control the level of authentication required.
        !           649: \tt -noauthentication\rm \ will gain you ``public'' rights to the directory,
        !           650: thus you typically won't be able to modify data.
        !           651: \tt -simple\rm \ and \tt -protected \rm \ present a textual password to the
        !           652: directory which it the uses to authenticate you.
        !           653: Using \tt -simple\rm \ the password is sent across the network ``in the
        !           654: clear'', whereas \tt -protected \rm \ encrypts it, thus you are advised to
        !           655: used \tt -protected \rm \ if your directory supports it.
        !           656: 
        !           657: The \tt -strong \rm \ flag tells Dish to send strong authentication
        !           658: credentials to the directory. This is not fully implemented in this version
        !           659: of QUIPU.
        !           660: 
        !           661: To connect to the DSA using ``simple'' or ``protected'' authentication, 
        !           662: you must supply a
        !           663: distinguished name (\tt -user\rm ) and password (\tt -password\rm ).
        !           664: This however reveals you password to anybody who is looking at your 
        !           665: terminal, but is useful for issuing bind operations from
        !           666: a shell script. To prevent this you need to place the 
        !           667: password in your \unix/ protected ``.quipurc'' (see Section~\ref{quipurc}).
        !           668: Alternatively, if you do not supply a password, you will be prompted for one.
        !           669: 
        !           670: 
        !           671: \subsection {Unbind}
        !           672: 
        !           673: \begin{verbatim}
        !           674: unbind [-noquit]
        !           675: \end{verbatim}
        !           676: 
        !           677: This is used to break the connection to a DSA.
        !           678: If -noquit is specified, the dish process does not die (This is used to
        !           679: maintain the cache).
        !           680: 
        !           681: To be ``friendly''
        !           682: to other users, you should unbind 
        !           683: when you have finished using the directory --- put an \tt unbind\rm \ in
        !           684: you ``.logout'' file if you use \verb"dish" from the shell.
        !           685: 
        !           686: \section {Sequences}
        !           687: \label{sequences}
        !           688: 
        !           689: Results returned by {\em search} and {\em list} may be long, and for 
        !           690: this reason have a reference number printed beside them.
        !           691: The reference number can be used as the ``object'' in any of the calls to the 
        !           692: directory.  Thus
        !           693: \begin{quote}\begin{verbatim}
        !           694: showentry 6
        !           695: \end{verbatim}\end{quote}
        !           696: shows the entry labelled with the sequence number
        !           697: ``6'' by a previous {\em search} or {\em list}.
        !           698: 
        !           699: When you come into dish
        !           700: by default, the resultant numbers of list and search operations 
        !           701: are added to a sequence called ``default''.
        !           702: 
        !           703: To get a different sequence (hence renumber from 1 again), you can change
        !           704: this to ``mysequence'' with a 
        !           705: \begin{quote}\begin{verbatim}
        !           706: -sequence mysequence
        !           707: \end{verbatim}\end{quote}
        !           708: flag.
        !           709: 
        !           710: To completely remove the concept of sequences (so no numbers are printed by list
        !           711: or search) use ``\tt -nosequence\rm ''.
        !           712: 
        !           713: The special keyword ``\tt reset\rm '' is used to reset the current sequence,
        !           714: thus causing future operations to be renumbered from 1.
        !           715: This is different to setting a new sequence, as the old sequence values are
        !           716: removed.
        !           717: 
        !           718: Occasionally you will want to search an entry defined in one sequence,
        !           719: putting the results in another, for this purpose the special token
        !           720: ``result'' is recognised, thus
        !           721: \begin{quote}\begin{verbatim}
        !           722: search 4 -sequence xxx -sequence result yyy
        !           723: \end{verbatim}\end{quote}
        !           724: will search entry 4 as defined by sequence ``xxx'', but place the results in
        !           725: sequence ``yyy''.
        !           726: 
        !           727: \section {Service Controls}
        !           728: \label{dish_serv}
        !           729: 
        !           730: All the commands described in Sections~\ref{dua:show} 
        !           731: through \ref{dua:compare} 
        !           732: have additional flags to control the type of service provided.  The
        !           733: advice to a novice user is let these flags take their default values. 
        !           734: 
        !           735: The flags recognised are listed below:-
        !           736: 
        !           737: \begin{description}
        !           738: 
        !           739: \item [-(no)preferchain] Advise the DSA (not) to chain the operation if
        !           740: required.
        !           741: 
        !           742: \item [-(no)chaining] (Prohibit) Allow the use of chaining.
        !           743: 
        !           744: \item [-(dont)usecopy] (Prohibit) Allow the use of a cached or slave 
        !           745: copy of the data.  
        !           746: Note this refers to data cached in the DSA, there are separate flags
        !           747: (already described)
        !           748: for data cached in the DUA.
        !           749: 
        !           750: \item [-(dont)dereferencealias] (Do not) dereference aliases if found in
        !           751: the path of a query.
        !           752: 
        !           753: \item [-low] Flag the query as low priority.
        !           754: \item [-medium] Flag the query as medium (default) priority.
        !           755: \item [-high]  Flag the query as high priority.
        !           756: 
        !           757: \item [-timelimit $n$] Set the time limit to $n$ seconds.
        !           758: \item [-notimelimit] Do not specify a time limit.
        !           759: 
        !           760: \item [-sizelimit $n$] Set the size limit to $n$ entries.
        !           761: \item [-nosizelimit] Do not specify a size limit.
        !           762: 
        !           763: \item [-(no)localscope] (Do not) limit operation to local scope.
        !           764: 
        !           765: \item [-(no)refer] (Do not) automatically follow referrals issued by the DSA.
        !           766: 
        !           767: \item [-strong]        Ask the DSA to use strong authentication when sending the
        !           768: results.
        !           769: 
        !           770: \end{description}
        !           771: 
        !           772: 
        !           773: 
        !           774: \section {Tailoring}
        !           775: 
        !           776: There are two levels of tailoring that control the operation of the DISH DUA.
        !           777: First of all there is the system wide tailor file \file{dsaptailor}
        !           778: (found in the ISODE \verb"ETCDIR" directory, usually \file{/usr/etc/}), and
        !           779: then users private tailor file \file{.quipurc}.
        !           780: 
        !           781: The file \file{dsaptailor} is described in Section~\ref{dua:tailor}.
        !           782: 
        !           783: \subsection {.quipurc}
        !           784: \label{quipurc}\index{.quipurc}
        !           785: The file \file{.quipurc} is read by \verb"dish" on start up, and
        !           786: has the following format:-
        !           787: 
        !           788: \begin{verbatim}
        !           789: flag:  value
        !           790: \end{verbatim}
        !           791: 
        !           792: The following flags are currently recognised:-
        !           793: \begin{description}
        !           794: 
        !           795: \item [username] The name of the user to bind as.
        !           796: 
        !           797: \item [password] The password to use when binding.  For this reason care
        !           798: should be taken to ensure you .quipurc file is not publicly readable.
        !           799: 
        !           800: \item [cache\_time] How long to keep the dish process alive after unbinding
        !           801: (specified in minutes)
        !           802: 
        !           803: \item [connect\_time] How long to keep a connection open, it there is no
        !           804: activity (specified in minutes)
        !           805: 
        !           806: \item [service] A list of default service control flags 
        !           807: (as defined in Section~\ref{dish_serv}).
        !           808: 
        !           809: \item [sequence] Add the supplied DN parameter to the default sequence.
        !           810: 
        !           811: \item [dsap] This can be followed by one of the dsaptailor options
        !           812: described in the Section~\ref{dua:tailor}.\index{dsaptailor}
        !           813: 
        !           814: \item [isode] 
        !           815: This can be followed by one of the ISODE tailor options
        !           816: described in \volone/ of this Manual.
        !           817: 
        !           818: \item [notype] The argument is expected to be an attribute type.
        !           819: This attribute will not be displayed by showentry by default.
        !           820: 
        !           821: \item [type] The only valid argument for this entry is ``unknown'', and says 
        !           822: that unknown attributes should be shown, by default, they are not shown.
        !           823: 
        !           824: \item [certificate] Used for strong authentication.
        !           825: 
        !           826: \item [secret\_key] Used for strong authentication.
        !           827: 
        !           828: \item [$<$dish command$>$] A list of default flags 
        !           829: to be used when `command' is used.
        !           830: For example
        !           831: \begin{verbatim}
        !           832: showname: -compact
        !           833: \end{verbatim}
        !           834: says that ``showname'' should always be invoked with the 
        !           835: \tt -compact \rm \ flag set.
        !           836: 
        !           837: \item [$<$nickname$>$] A nickname entry, for example
        !           838: \begin{quote}\smaller\begin{verbatim}
        !           839: cjr: ``c= GB @ o= University College London @ ou= Computer Science @ CN= Colin Robbins''
        !           840: \end{verbatim}\end{quote}
        !           841: This can then be used in distinguished name arguments, for example
        !           842: \begin{quote}\begin{verbatim}
        !           843: showentry cjr
        !           844: \end{verbatim} \end{quote}
        !           845: will show the entry for `Colin Robbins'.
        !           846: 
        !           847: \end{description}
        !           848: 
        !           849: 
        !           850: \section {Remote Management of the DSA}\label{dua:mgmt}
        !           851: \begin{verbatim}
        !           852: dsacontrol [-[un]lock <entry>] [-dump <directory>] 
        !           853:            [-tailor <string>] [-abort] 
        !           854:            [-restart] [-info] [-refresh <entry>]
        !           855:            [-resync <entry>] -slave [<entry>]
        !           856: \end{verbatim}
        !           857: 
        !           858: If the \pgm{dish} program is bound to the DSA as the Directory manager
        !           859: (See Section~\ref{dish_bind} on binding),
        !           860: then it may be used to (primitively) manage the DSA.
        !           861: This feature is discussed in \cite{QUIPU.Design} and Section~\ref{dsa:mgmt}
        !           862: of this Manual.
        !           863: 
        !           864: \tt (un)lock\rm \ used to (un)lock subtrees of the DIT held locally. This
        !           865: (allows) prevents users to modify the DIT.
        !           866: 
        !           867: \tt dump\rm \ causes a copy of the local DIT to be dumped into the specified 
        !           868: directory.
        !           869: Note that when the DSA dumps its in-core database,
        !           870: it does so relative to the (possibly remote) \unix/ directory from which the
        !           871: DSA was started,
        !           872: not the directory that \man dish(1c) was invoked in!
        !           873: So it is best to specify path names in full to ensure the database is dumped
        !           874: where you expect it to be!
        !           875: 
        !           876: \tt tailor\rm \ is used to pass tailor command to a running DSA.  The format of
        !           877: ``string'' is the same as a line in the ``quiputailor'' file.
        !           878: For example:-
        !           879: \begin{quote}\begin{verbatim}
        !           880: dsacontrol -tailor "dsaplog level=all"
        !           881: \end{verbatim}\end{quote}
        !           882: will turn the DSA logging on full.
        !           883: 
        !           884: \tt refresh\rm \ tells the DSA to re-read sub-tree `entry' from disk.
        !           885: As with all `dsacontrol' commands, `entry' must be the full DN of the target
        !           886: entry, the dish concept of `current position' is not used.
        !           887: Also, if relating to a disk operation, the CASE of the DN must be correct
        !           888: as well.
        !           889: 
        !           890: \tt resync\rm \ tells the DSA to re-write the sub-tree `entry' to disk.
        !           891: 
        !           892: \tt slave\rm \ tell the DSA to update its SLAVE EDB files, see Section
        !           893: \ref{slave_update} for details.
        !           894: 
        !           895: \tt abort\rm \ tells the DSA to stop.
        !           896: \tt restart\rm \ tells the DSA to stop, then restart.
        !           897: 
        !           898: \tt info\rm \ asks the DSA to return some statistics about its database.
        !           899: 
        !           900: The error messages returned from a DSA are somewhat obscure.
        !           901: There are 3 things dish may report: 
        !           902: \verb+DONE+ --- the operation has been successfully completed; 
        !           903: \verb+Access rights insufficient+ --- you are not bound as the DSA manager;
        !           904: \verb+Unwilling to perform+ --- the DSA was unable to perform the task, this
        !           905: generally means the argument to dsacontrol was wrong.
        !           906: 
        !           907: \section {Caching in the DUA}
        !           908: \label {dua_cache}
        !           909: 
        !           910: All results returned from read and list operations are cached in memory
        !           911: in the DUAs.  The cache is then used if possible to answer queries.
        !           912: The cache is kept for ``cache\_time'' minutes as specified in the tailor
        !           913: files.
        !           914: 
        !           915: Disk caching has not been implemented yet,
        !           916: but it is intended to extend the in-core caching, 
        !           917: so that the cached data can be written to disk.  When the DUA's start up, the
        !           918: user will have the option to read this cache.
        !           919: Similar support for private data may be provided.
        !           920: 
        !           921: \section {Running DISH from the Shell}
        !           922: \label{dish_shell}
        !           923: 
        !           924: Each of the dish commands mentioned in this Chapter to
        !           925: \ref{dua:mgmt}
        !           926: can be applied directly to the shell, without having to first invoke
        !           927: \pgm{dish}.  This has the advantage that the result can be piped through
        !           928: programs like \pgm{more} thus giving the user flexibility in how
        !           929: they view the data.
        !           930: 
        !           931: Chapter~\ref{quipu:install} describes how to install this ``extra'' feature of
        !           932: dish.
        !           933: 
        !           934: \subsection {Dishinit}
        !           935: A program called \pgm{dishinit} 
        !           936: \label{dishinit}
        !           937: can be use to 
        !           938: bind to the directory as the manager, read certain information
        !           939: and create a 
        !           940: default \verb".quipurc"
        !           941: file for a specified user.
        !           942: This is a useful utility for new databases.
        !           943: If the \verb"dsaptailor" variable \verb"dishinit" is set to \verb"on",
        !           944: dishinit will be invoked by \verb"dish" whenever is can not find a 
        !           945: .quipurc file.
        !           946: 
        !           947: \verb"dishinit" needs three parameters to be set in order to bind as the 
        !           948: manager, and search the local subtree.
        !           949: These parameters are defined at the top of the dishinit script and are:-
        !           950: \begin{description}
        !           951: \item [manager] The DN of the manager of the local DSA
        !           952: \item [password] The managers password (the script should be protected 
        !           953: with \unix/ file protection).
        !           954: \item [position] The DN of the local sub-set of the DIT. This is where 
        !           955: the entries for users will be looked for
        !           956: \end{description}
        !           957: 
        !           958: \subsection{Example Scripts}
        !           959: Two example scripts have been supplied as part of ISODE, and can be found in
        !           960: the \file{others/quipu/uips/dish} directory.
        !           961: \begin{description}
        !           962: \item [dsaping] contacts all the DSAs at a given level in the DIT, and
        !           963: gathers some statistics.
        !           964: \item [dsalist] produces a list of all the (known) DSAs in the DIT.
        !           965: \end{description}
        !           966: 
        !           967: Each time a new shell is invoked and a dish command entered, a new DISH will
        !           968: be invoked.  This is sometimes not required.  To prevent this from happening
        !           969: an environment variable ``DISHPROC'' can be set, and should be the TCP
        !           970: address to use for communication, for example
        !           971: \begin{quote}\begin{verbatim}
        !           972: 127.0.0.1 12345
        !           973: \end{verbatim}\end{quote}
        !           974: where 127.0.0.1 is the IP address, and 12345 is the TCP port.
        !           975: The two example scripts show how the TCP port may be generated if required
        !           976: under \verb+sh+.
        !           977: For \verb+csh+ you might use
        !           978: \begin{verbatim}
        !           979: if (${?DISHPROC} == 0) then
        !           980:         setenv DISHPROC "127.0.0.1 `expr $$ + 10000`"
        !           981: endif
        !           982: \end{verbatim}
        !           983: 
        !           984: For people not running in the TCP environment this is not a problem, as
        !           985: ``named pipes'' are used, with the pipe name being bound to the terminal
        !           986: identifier, the section below identifies these files.
        !           987: 
        !           988: \subsection {Files}
        !           989: 
        !           990: When the multiple command version of dish is compile on a machine that does
        !           991: not support sockets, name pipes are used 
        !           992: to communicate with the
        !           993: a background process.
        !           994: 
        !           995: The file ``/tmp/dish$<$pid$>$'' is used by dish to write results to the calling
        !           996: processes, where the ``pid'' is the process id of the calling process.
        !           997: 
        !           998: The file ``/tmp/dish--$<$tty$>$--$<$uid$>$'' is used by calling process to send commands to
        !           999: dish, where ``tty'' is the users terminal number, and ``uid'' their user id.
        !          1000: 
        !          1001: \chapter {SID}
        !          1002: \index{sid}
        !          1003: \label{DUA:sid}
        !          1004: SID (Steve's Interface to Dish) is a Directory User Agent, designed to be
        !          1005: incredibly easy to use.
        !          1006: It is implemented as a simple set of scripts to the DISH DUA.
        !          1007: 
        !          1008: There are a lot of flags to DISH, this can make it awkward to use, and in
        !          1009: general shows too much directory specific information.
        !          1010: Fred has a centralised view of the world, and does not give
        !          1011: the advantages of a shell based interface.
        !          1012: 
        !          1013: SID is a simple approach of giving appropriate aliases to access DISH
        !          1014: commands.   It is targetted for searching for people and organisations.
        !          1015: It may be useful ``as is'' to others, and also give an indication as to how
        !          1016: DISH may be used.
        !          1017: 
        !          1018: 
        !          1019: \section {Quickstart}
        !          1020: 
        !          1021: 
        !          1022: \begin{description}
        !          1023: \item[WARNING] Before you start to try SID, you must have the variable
        !          1024: DISHPROC set in your environment.  The mechanism suggested in
        !          1025: Section~\ref{profile} is a good way to achieve this.  To experiment,
        !          1026: csh users can type the incantation:
        !          1027: \begin{verbatim}
        !          1028: % setenv DISHPROC "127.0.0.1 `expr $$ + 1000`"
        !          1029: \end{verbatim}
        !          1030: \end{description}
        !          1031: 
        !          1032: 
        !          1033: To find users within your Organisation is very easy.  
        !          1034: The default setup is optimised for
        !          1035: your particular Organisational Unit.  Simply use the command {\bf psearch}
        !          1036: with a single argument to identify the user looked for.  This will identify
        !          1037: all users with this key as a substring.  For example:
        !          1038: 
        !          1039: \begin{quote}\small\begin{verbatim}
        !          1040: % psearch steve
        !          1041: countryName=GB
        !          1042: organisation=University College London
        !          1043: department=Computer Science
        !          1044: 
        !          1045: 1   cn=Steve Kille
        !          1046: telephoneNumber    - +44-1-380-7294 (work)
        !          1047: telephoneNumber    - 01-350-2888 (home)
        !          1048: 2   cn=Stephen Titcombe
        !          1049: telephoneNumber    - +44-1-387-7050 x 3674/5 
        !          1050: telephoneNumber    - Term = 01-388-4741
        !          1051: 3   cn=Stephen Sackin
        !          1052: 4   cn=Steve Wilbur
        !          1053: telephoneNumber    - +44-1-380-7287
        !          1054: 5   cn=Stephen Usher
        !          1055: telephoneNumber    - +44-1-387-7050 x 3674/5 
        !          1056: 6   cn=Kevin Steptoe
        !          1057: 7   cn=Tomasz Stepniak
        !          1058: 8   cn=Stefan Penter
        !          1059: telephoneNumber    - +44-1-387-7050 x 3674/5 
        !          1060: 9   cn=Stephania Loizidou
        !          1061: 10  cn=Steve Hodges
        !          1062: telephoneNumber    - +44-1-387-7050 x 3674/5 
        !          1063: 11  cn=Steve Davey
        !          1064: telephoneNumber    - +44-1-387-7050 x 7280 or 7289
        !          1065: 12  cn=Steve Chan
        !          1066: telephoneNumber    - +44-1-387-7050 x 3674/5 
        !          1067: 13  cn=Steven Britton
        !          1068: telephoneNumber    - +44-1-387-7050 x 3715
        !          1069: 14  cn=Stephen Beckles
        !          1070: telephoneNumber    - +44-1-387-7050 x 3674/5 
        !          1071: 15  cn=Steven Bacall
        !          1072: telephoneNumber    - +44-1-387-7050 x 3674/5 
        !          1073: telephoneNumber    - dd 01-387-6978 (Campbell House)
        !          1074: \end{verbatim}\end{quote}
        !          1075: 
        !          1076: 
        !          1077: Each match will have an associated number.  To show a given entry, just use
        !          1078: the command {\bf showentry}, with the number identifying the entry as the
        !          1079: single argument.  For example to show entry 1 (Steve Kille):
        !          1080: 
        !          1081: \begin{quote}\smaller\begin{verbatim}
        !          1082: % showentry 1
        !          1083: c=GB@o=University College London@ou=Computer Science@cn=Steve Kille
        !          1084: Address            - 35 Elspeth Road
        !          1085:                      London
        !          1086:                      SW11 1DW
        !          1087: userClass - csresstaff
        !          1088: photo - (See X window, pid 598)
        !          1089: roomNumber         - G24
        !          1090: favouriteDrink     - Pinta - Brakspears
        !          1091: info               - Directory worker
        !          1092: rfc822Mailbox      - [email protected]
        !          1093: textEncodedORaddress - /Pn=Stephen.Kille/Ou=cs/O=ucl/ \
        !          1094:                      Prmd=uk.ac/admd=gold 400/c=gb/
        !          1095: userid             - steve
        !          1096: telephoneNumber    - +44-1-380-7294 (work)
        !          1097: telephoneNumber    - 01-350-2888 (home)
        !          1098: description        - New Description
        !          1099: surname            - Kille
        !          1100: name               - Steve E. Kille
        !          1101: name               - Stephen Kille
        !          1102: name               - Steve Kille
        !          1103: \end{verbatim}\end{quote}
        !          1104: 
        !          1105: If you are running X windows, a picture will be displayed if it is present.
        !          1106: 
        !          1107: If you wish to search all of your Organisation, simply give a second argument 
        !          1108: to {\bf
        !          1109: psearch}.  For example, to search UCL give `ucl' as shown:
        !          1110: 
        !          1111: \begin{quote}\small\begin{verbatim}
        !          1112: % psearch baker ucl
        !          1113: Searching for People matching "baker" under:
        !          1114: countryName=GB
        !          1115: organisation=University College London
        !          1116: 
        !          1117: 4   ou=French Lang and Lit@cn=F Baker
        !          1118: telephoneNumber  - 3077
        !          1119: 5   ou=Economics@cn=V Bashkar
        !          1120: telephoneNumber  - 2286
        !          1121: 6   ou=Biochemistry@cn=J Basra
        !          1122: telephoneNumber  - 2185
        !          1123: 7   ou=Bartlett School@cn=H Bowker
        !          1124: telephoneNumber  - 7453
        !          1125: 8   ou=Anatomy and Embryol@cn=D Becker
        !          1126: telephoneNumber  - 3293
        !          1127: 9   ou=Computer Science@cn=Malcolm Booker
        !          1128: telephoneNumber  - +44-1-387-7050 x 3645 
        !          1129: 10  ou=Computer Science@cn=Imtiaz Bashir
        !          1130: telephoneNumber  - +44-1-387-7050 x 7304 
        !          1131: 11  ou=Computer Science@cn=Benjamin Bacarisse
        !          1132: telephoneNumber  - +44-1-380-7212 (work)
        !          1133: telephoneNumber  - 01 987 2746 (home)
        !          1134: 12  ou=Surgery@cn=L Baker
        !          1135: telephoneNumber  - 82-5255
        !          1136: 13  ou=History Of Art@cn=B A Boucher
        !          1137: telephoneNumber  - 7210
        !          1138: 14  ou=Geological Sciences@cn=J R Baker
        !          1139: telephoneNumber  - 2382
        !          1140: 15  ou=Secretary's Office@cn=I H Baker
        !          1141: telephoneNumber  - 3000
        !          1142: \end{verbatim}\end{quote}
        !          1143: 
        !          1144: 
        !          1145: \section {Example Usage}
        !          1146: 
        !          1147: A typical sequence to find someone outside you organisation is now shown:
        !          1148: 
        !          1149: 
        !          1150: \begin{quote}\small\begin{verbatim}
        !          1151: % osearch nott
        !          1152: Searching in country "gb" for Organisations matching "nott"
        !          1153: 1   o=Nottingham University
        !          1154: telephoneNumber  - +44-0602-484848x2862
        !          1155: 2   o=NPL
        !          1156: 3   o=JNT
        !          1157: telephoneNumber  - +44-0235-445724
        !          1158: % psearch smith 1
        !          1159: Searching for People matching "smith" under:
        !          1160: countryName=GB
        !          1161: organisation=Nottingham University
        !          1162: 
        !          1163: 4   ou=Computer Science@cn=Hugh Smith
        !          1164: telephoneNumber  - extn 2862 (Departmental Secretary)
        !          1165: % showentry 4
        !          1166: c=GB@o=Nottingham University@ou=Computer Science@cn=Hugh Smith
        !          1167: photo            - (See X window, pid 1076)
        !          1168: telephoneNumber  - extn 2862 (Departmental Secretary)
        !          1169: description      - lecturer
        !          1170: surname          - Smith
        !          1171: name             - Hugh.Smith
        !          1172: name             - Hugh Smith
        !          1173: \end{verbatim}
        !          1174: \end{quote}
        !          1175: 
        !          1176: 
        !          1177: 
        !          1178: \section {Use of Nicknames}
        !          1179: 
        !          1180: It is convenient to have nicknames (privaet aliases) set up for commonly accessed parts of the
        !          1181: Directory Information Tree.  These can be set up in the QUIPU Profile (see
        !          1182: Section~\ref{profile}), which sets up the nickname ``us''.
        !          1183: Two nicknames used in the examples are:
        !          1184: 
        !          1185: \begin{description}
        !          1186: \item[ucl]  Country GB; Organsisation University College London.
        !          1187: \item[cs] Country GB; Organsisation University College London;
        !          1188: Organisational Unit Computer Science.
        !          1189: \end{description}
        !          1190: 
        !          1191: Aliases may be used as an alternative to sequence numbers.
        !          1192: 
        !          1193: \section {SID Commands}
        !          1194: 
        !          1195: The initial SID commands are:
        !          1196: 
        !          1197: \begin{description}
        !          1198: 
        !          1199: \item[osearch] (Organisation Search) Search for an organisation.  The first argument is the
        !          1200: organisation being searched for.  For example:
        !          1201: 
        !          1202: \begin{verbatim}
        !          1203: % osearch nott
        !          1204: \end{verbatim}
        !          1205: 
        !          1206: This searches for any organisations approximating to this string, or
        !          1207: containing it as a substring.
        !          1208: 
        !          1209: The second (optional) argument is the two letter country code (e.g., GB, US,
        !          1210: ES, etc.).  Use {\bf clist} to find these codes.  The default country is the
        !          1211: previous one searched.  Example:
        !          1212: 
        !          1213: \begin{verbatim}
        !          1214: % osearch nyser us
        !          1215: \end{verbatim}
        !          1216: 
        !          1217: \item[psearch] (Person Search) Search for a person.  The first argument is a key to identify
        !          1218: the person.  Approximate and substring matches are made.
        !          1219: There are two ways of using psearch.  
        !          1220: 
        !          1221: 
        !          1222: \begin{enumerate}
        !          1223: \item Search an identified organisation, using the second argument to
        !          1224: osearch.  Examples where the organisation is identified by a nickname:
        !          1225: 
        !          1226: \begin{verbatim}
        !          1227: % psearch kirstein ucl
        !          1228: \end{verbatim}
        !          1229: 
        !          1230: Example where the organisation is identified by a sequence number, returned
        !          1231: by a previous osearch command.
        !          1232: 
        !          1233: \begin{verbatim}
        !          1234: % psearch steve 29 
        !          1235: \end{verbatim}
        !          1236: 
        !          1237: 
        !          1238: \item Move explicitly to an organistion, and then use psearch with only one
        !          1239: argument.  This is useful when repeated searches will be made from one point.
        !          1240: Example:
        !          1241: 
        !          1242: \begin{verbatim}
        !          1243: % moveto  ucl
        !          1244: % psearch kirstein
        !          1245: \end{verbatim}
        !          1246: 
        !          1247: \end{enumerate}
        !          1248: 
        !          1249: 
        !          1250: 
        !          1251: \item[clist] (Country List) Used to give a list of countries, with friendly descriptions,
        !          1252: as well as the two letter code.
        !          1253: 
        !          1254: \item[ousearch] (Organisational Unit Search) Search for an OU.  Analogous to psearch.  This is
        !          1255: appropriate for use where organisations are large, and a full search takes
        !          1256: too long.
        !          1257: 
        !          1258: \item[dlist] (Directory List) This uses the search command to provide a listing of directory
        !          1259: information, without a clutter of wild South American animals.
        !          1260: 
        !          1261: \end{description}
        !          1262: 
        !          1263: \section {Standard DISH commands}
        !          1264: 
        !          1265: The following DISH commands are useful ``as is'' for normal users, and are
        !          1266: considered to be a part of SID.
        !          1267: 
        !          1268: \begin{description}
        !          1269: \item[showentry] Show an entry.  The sinle argument is typically the numeric
        !          1270: key returned by a search.  This will be used a lot, and it is likely to be
        !          1271: worthwhile setting up an alias.  The author uses ``ds'' (directory show).
        !          1272: Example, using a sequence number returned by a search.
        !          1273: 
        !          1274: \begin{verbatim}
        !          1275: % showentry 36
        !          1276: \end{verbatim}
        !          1277: 
        !          1278: 
        !          1279: \item[moveto] Move to a defined location.  Example of moving to a nickname
        !          1280: defined location:
        !          1281: 
        !          1282: \begin{verbatim}
        !          1283: % moveto ucl
        !          1284: \end{verbatim}
        !          1285: 
        !          1286: 
        !          1287: \item[modify] To modify your own entry, this command is used with the single
        !          1288: argument ``me''.  For example:
        !          1289: 
        !          1290: \begin{verbatim}
        !          1291: % modify me
        !          1292: \end{verbatim}
        !          1293: 
        !          1294: \end{description}
        !          1295: 
        !          1296: 
        !          1297: \section {QUIPU Profile}
        !          1298: \label {profile}
        !          1299: This is a suggested template for ``.quipurc'', note that this is very
        !          1300: similar to the default file installed by \pgm{dishinit} described in
        !          1301: Section~\ref{dishinit}.
        !          1302: 
        !          1303: 
        !          1304: \begin{quote}\smaller\begin{verbatim}
        !          1305: username:c=GB@o=University College London@ou=Computer Science@cn=Steve Kille
        !          1306: me:c=GB@o=University College London@ou=Computer Science@cn=Steve Kille
        !          1307: password:steve
        !          1308: 
        !          1309: position: @c=GB@o=University College London@ou=Computer Science
        !          1310: notype: acl
        !          1311: notype: treestructure
        !          1312: notype: masterdsa
        !          1313: notype: slavedsa
        !          1314: notype: objectclass
        !          1315: notype: lastmodifiedby
        !          1316: notype: lastmodifiedtime
        !          1317: notype: userpassword
        !          1318: cache_time: 30
        !          1319: connect_time: 2
        !          1320: 
        !          1321: us: c=us
        !          1322: moveto: -pwd
        !          1323: showentry: -name
        !          1324: 
        !          1325: \end{verbatim}\end{quote}
        !          1326: 
        !          1327: You must set the environment variable DISHPROC.  This can be done by the
        !          1328: following in the .login file (csh).
        !          1329: 
        !          1330: \begin{verbatim}
        !          1331: if (${?DISHPROC} == 0) then
        !          1332:         setenv DISHPROC "127.0.0.1 `expr $$ + 1000`"
        !          1333: endif
        !          1334: \end{verbatim}

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.