⟦87e60326d⟧

TextFile

% run this through LaTeX with the appropriate wrapper

\f

\chapter{DISH}
\label{dish}

This Part of the Manual describes the QUIPU X500 Directory User Agent (DUA) interfaces
--- Dish, Widget and Sunint.

Widget and Sunint are not fully developed interfaces,
but are included to give would be DUA developers examples of how 
the procedural interface discussed in Section~\ref{proc_model} can be used.


\section {DISH Users Guide}

To run DISH in interactive mode invoke \man dish(1c), then issue any of the
commands described in Sections~\ref{dish_start} through \ref{sequences}.
This mode of operation is especially useful for novice users.
The process of connecting to the Directory -- binding --
takes place automatically when the program is invoked, and an unbind
is issued when you quit.  

The arguments to \man dish(1c) are the same as for bind (see 
Section~\ref{dish_bind}), with the addition of a `-pipe' flag
which is used to start dish in ``shell'' mode (see Section~\ref{dish_shell})
(NOTE: ``dish -pipe \&'' has the same effect as the shell command ``bind'').

\subsection {Flags}
Each of the DISH commands described below has a large number of valid flags,
the full names of the flags are given below, however the shortest unique
name is sufficient to select the flag.
Similarly, when dish is used interactively the shortest unique name is taken
for the command name (e.g. ``l'' for ``list'').
(``sh'' is interpreted as ``showentry'', ``shown'' must be typed for
``showname'')

\subsection {Help}
The additional flag \tt -help \rm \ can be specified with 
every command to get limited runtime help.

\subsection{Moving around the DIT}
\label{dish_start}
With nearly every command it is possible to supply the distinguished name of
the object you want to reference.
In the syntax this is represented by 
\begin{verbatim}
	<object>.  
\end{verbatim}
An initial `\tt @\rm ' in an object description specifies that the name
is relative to the root of the Directory Information Tree (DIT), 
otherwise the name is relative to the current
position in the DIT.  
The special name component `..' is used to mean `one
position up' from the current position.  
Some examples of valid names and their interpretation relative to
how a distinguished name is built up are shown below:

\begin{description}

\item [``\verb"@c=GB@o=University College London@ou=Computer Science"''] 
The specified object is 
\begin{quote}
c= GB @ o= University College London @ ou= Computer Science
\end{quote}

\item [``\verb"cn=Colin Robbins"''] describes the object
cn=Colin Robbins relative to the current 
position (``c= GB @ o= University College London @ ou= Computer Science @ cn= Colin Robbins''). 
Spaces in a name will be seen as the start of a separate 
argument by the shell, so the name must be quoted.

\item [``\verb"..@cn=Steve Titcombe"''] describes the entry 
cn=Steve Titcombe at the same level
in the DIT as the current position (``c= GB @ o= University College London @
ou= Computer Science @ cn= Steve Titcombe'').
\end{description}

Objects can also be expressed in the form of sequence numbers and nicknames.
See sections \ref{sequences} and \ref{quipurc}.

When you specify an object, the current position in the DIT is not changed.
To change the current position you should use
\begin{verbatim}
moveto [-pwd] <object> [-[no]check]
\end{verbatim}
``object'' will then become the current position.
The \tt -pwd \rm \ flag tells moveto to print the current position in the
DIT.
The current position can also be changed with the \tt -move\rm \ flag to 
showentry and list (see Sections~\ref{dua:list} and ~\ref{dua:show}).

The \tt -nocheck \rm \ flag tells moveto NOT to check the entry exists,
normally, moveto will invoke a `\verb"read"' to check the named entry exists.


Now the commands\ldots

\subsection{Showentry}
\label{dua:show}

\begin{verbatim}
showentry [<object>] [-[no]cache] [-[no]name]
	[-[no]move] [<any of the read arguments>]
\end{verbatim}

Showentry will call `\tt showname -compact\rm ' (see Section~\ref{showname}) to print the distinguished
name of the current entry (unless \tt -noname\rm \ is specified), 
then each attribute
specified in the read arguments. 
If the `\tt -all\rm ' is given all attributes will be shown.
If insufficient information resides in the local cache, a `\tt read\rm ' will
be performed.

\tt -cache\rm \ is used the tell showentry to use cached information only ---
do not issue a read operation. 
This is used to see what the DUA has cached, and then get information when
the local DSA is unavailable.

\tt -nocache\rm \ is used to enforce a directory read, this is used to update the cache
directly.

\tt -move\rm \ is used to tell dish to change the current position in the DIT
to the object specified. 

\subsubsection{read flags}

These flags are used by showentry(1), showname(1), search(1) and modify(1).

\begin{verbatim}
[-[no]type <attribute-type> *] [-[no]all] 
[-[no]value] [-[no]show] [-[no]key] [-edb]
\end{verbatim}

The \tt all\rm \ flag request that all attribute are read (default).

The \tt value\rm \ flag reads the attribute value, which is the default, 
the inverse is to read the attribute types only.

The \tt novalue\rm \ flag say print the attribute types only.

The \tt show\rm \ flag displays the information read.

The \tt key\rm \ flag determines whether the key (attribute type) will 
be shown along with the attribute value.

The \tt edb\rm \ flag requests that the data is displayed in "edb" format,
that is, a format which can be used in QUIPU data files.

The \tt type\rm \ flag request that only the supplied attributes are 
read from the DSA, the inverse of this \tt -notype \rm \ does not 
prevent the attributes being read (as thee is no
easy mechanism to perform this within X.500), 
but it does stop them being shown.

\subsection{List}
\label{dua:list}
\begin{verbatim}
list [<object>] [-nocache] [-noshow]
	[-[no]move]
\end{verbatim}
This function displays all the children below your current position.

\tt -nocache\rm \ tells list to re-read the directory - do not use cached information.

\tt -noshow\rm \ tells list not to display the names found, but 
still construct sequences (see section \ref{sequences}).

\tt -move\rm \ is used to tell dish to change the current position in the DIT
to the object specified. 

\subsection{Search}
\label{search}

\begin{verbatim}
search [[-filter] <filter>] [[-object] [<object>]] 
	[-baseobject] [-singlelevel] [-subtree]
	[-nameonly] [<any of the read arguments>]
	[-[no]relative]
\end{verbatim}

Search the DIT starting at the object specified, for entries that match a
filter.
When an entry is found to match the filter, its distinguished name is printed
unless a `\tt-show\rm ' option is 
specified, when the entry is displayed.

If no filter is specified the default filter (which matches any object in
the DIT) is used.

If no flags are given, then the sole allowed parameter is taken to be the
filter (NOT the base object as in ALL the other commands).
The flags \tt -filter\rm \ and \tt -object \rm \ are supplied to allow the
user to specify if both a filter and base object (NOTE only one need be
flagged).
For example, the following are all valid search commands
\begin{verbatim}
search
search <filter>
search -filter <filter>
search -object <object>
search -filter <filter> -object <object>
search <filter> -object <object>
search -filter <filter> <object>
\end{verbatim}
Whereas 
\begin{verbatim}
search <object>     (interpreted as a filter !)
search <filter> <object>
\end{verbatim}
are not valid.

The flag `\tt -singlelevel\rm ' will search all the children
from the current position. 
The flag `\tt -subtree\rm ' searches all the 
levels below the current position recursively.
The default is
`\tt -singlelevel\rm '.

For example:- 
\begin{verbatim}
search -object 
@c=GB@o=University College London@ou=Computer Science 
-subtree -filter "cn=colin robbins" -type telephonenumber
\end{verbatim}
will search the subtree below `c=GB @ o=University College London @ ou=Computer Science' for
an exact match of ``colin robbins'', and call showentry to 
display the {\em telephonenumber} attribute.

The \tt -norelative\rm \ flag is used to tell \verb"showname" to print the full
distinguished name of the results, otherwise the name relative to the current
position is printed.

As well as an exact equality match, the 
following types of match can be specified
\begin{verbatim}
~=		Approximately equals.
>=		Greater than or equal.
<=		Less than or equal.
\end{verbatim}

When searching for an exact match (`=')
the `\tt *\rm ' character is used as a wildcard, and a substring
match takes place (unless only a `\tt *\rm ' is specified, when a {\em
presence} match is used - hence any entry 
containing that attribute will be matched). 

Filter items can be linked with {\em and} --- `\tt \&\rm ', or {\em or} 
--- `\tt $|$\rm '.  Brackets `\tt( )\rm ' 
should be used to enforce the boolean 
ordering of the expressions, otherwise the evaluation is left to right.
A {\em not} `\tt !\rm ' can be used to specify the boolean not operator.

If a filter does not have a type specified e.g., ``-filter steve'',
then an approximate match for the specified common name is assumed
(in this case ``-filter cn$\tilde{\ }$=steve'' is assumed).

A more complex example of a filter 
that searches for anybody whose is a member of staff 
or a student, who has a ``drink'' attribute,
whose name approximately matches ``steve'', but whose surname is 
not ``Kille'':-
\begin{verbatim}
cn~=steve & (userClass = staff | userClass = student) &
( ! surname = Kille) & drink = *
\end{verbatim}

A list of all the attributes that can be searched for is given in 
Appendix~\ref{attr_match}.

NOTE: `$>$=' actually sends a LESS THAN OR EQUAL query to the directory.  In
this way the results you get back are what a typical user might instinctively
expect --- read the standard !!!



\subsection {Add Entry}
\label{dish:add}

\begin{verbatim}
add [<object>] [-draft <draft> [-noedit]] [-newdraft]
	[-objectclass <objectclass>]
\end{verbatim}

Add is used to add entries to the DIT.
This invokes editentry
on the draft entry.
If there is not a draft entry specified a draft entry of the specified 
objectclass (default --- thornperson \& quipuObject) is created.
The default draft file is ``.dishdraft'' in your home directory, this can be
altered with the -draft option.

When editing has finished the entry is added to the DIT
(the \tt -noedit\rm \ flag following a \tt -draft\rm \ stops the editor
being invoked).

\tt -newdraft\rm \ causes the current draft to be overwritten with a new
template of the appropriate objectclass.

On completion of the add, the draft entry is renamed with a suffix of
``.old''.

\subsection{Editentry}

\begin{verbatim}
editentry <draft>
\end{verbatim}

editentry invokes an editor (as defined by the users
\$EDITOR environment variable) on the current draft entry.
In a future release it is hoped to have an editor that knows about the syntax
of an entry, and thus ensures that the entry you have supplied is syntactically
correct.

\subsection {Delete Entry}
\begin{verbatim}
delete [<object>]
\end{verbatim}
The specified entry is removed from the DIT.

\subsection {Modify Entry}
\label{dish:modify}
\begin{verbatim}
modify [<object>] [-draft <draft> [-noedit]] [-newdraft] 
	[<any of the showentry arguments>]
\end{verbatim}
Modify is used to modify existing entries in the DIT.  Initially showentry
is used to get the current DIT entry, and place a copy of if in your
.dishdraft file.  If the -draft option is specified the given file is used.
After editing, any changes to the entry are sent to the directory
(the \tt -noedit\rm \ flag following a \tt -draft\rm \ stops the editor
being invoked).

The draft file is handled in the same way as with add, except, when a
new draft is created, the current values of the attributes are read from the
directory.

\subsection {Modify RDN}
\begin{verbatim}
modifyrdn [<object>] -attribute <newrdn>
\end{verbatim}
This is used to modify the RDN of an entry.  


\subsection{Showname}
\label{showname}

\begin{verbatim}
showname [<object>] [-compact] [-[no]cache] 
	[<any of the read arguments>]
\end{verbatim}

A name can be printed either in compact form, just showing the distinguished
name, or by showing the distingushed attributes.

\subsection{Compare}
\label{dua:compare}
\begin{verbatim}
compare [<object>] -attribute <attribute> [-[no]print]
\end{verbatim}
For example
\begin{quote}\begin{verbatim}
compare userclass=student
\end{verbatim}\end{quote}
This command has a return value of true or false (1 or 0).

If `\tt -print\rm ' is specified the strings ``TRUE'' or ``FALSE'' are printed.

\subsection {Service Controls}
\label{dish_serv}

All the commands described in Sections~\ref{dua:show} 
through \ref{dua:compare} 
have additional flags to control the type of service provided.  The
advice to a novice user is let these flags take their default values. 

The flags recognised are listed below:-

\begin{description}

\item [-(no)preferchain] (Do not) use chaining if the local DSA can't
answer the query.

\item [-(no)chaining] (Prohibit) Allow the use of chaining.

\item [-(dont)usecopy] (Prohibit) Allow the use of a cached or slave 
copy of the data.  
Note this refers to data cached in the DSA, there are separate flags
(already described)
for data cached in the DUA.

\item [-(dont)dereferencealias] (Do not) dereference aliases if found in
the path of a query.

\item [-low] Flag the query as low priority.
\item [-medium] Flag the query as medium (default) priority.
\item [-high]  Flag the query as high priority.

\item [-timelimit $n$] Set the time limit to $n$ seconds.
\item [-notimelimit] Do not specify a time limit.

\item [-sizelimit $n$] Set the size limit to $n$ entries.
\item [-nosizelimit] Do not specify a size limit.

\item [-(no)localscope] (Do not) limit operation to local scope.

\end{description}



\subsection {Squid}

\begin{verbatim}
squid [-sequence [<sequence name>]]
\end{verbatim}

The command \pgm {squid} (Status QUIpu Dish) with no 
parameters will inform you of the current status
of you dish process.

\tt -sequence\rm \ make squid print the specified sequence.
Sequences are described in Section~\ref{sequences}.

\subsection {Bind}
\label{dish_bind}

\begin{verbatim}
bind [-noconnect] [-user [<username>]] 
[-password [<password>]] [-call <dsaname>] 
[-quipurc] [-cache <file>]
\end{verbatim}

This is used to (re)connect to the directory.  This is not normally
required, as each command will bind as necessary, but allows advanced users
to contact specified DSA's.

\tt -noconnect\rm \ is used to start dish (and cache) without connection to a
directory.

\tt -quipurc\rm \ causes you .quipurc file to be re-read, it is normally only
read when you issue your first dish command of the session.

For an explanation of the `\tt -cache\rm ' flag see Section~\ref{dua_cache}

To connect to the DSA as a specific entity, you must supply the
distinguished name (\tt -user\rm ) and password (\tt -password\rm ).
This however reveals you password to anybody who is looking at your 
terminal, but is useful for issuning bind operations from
a shell script. To prevent this you need to place the 
password in your \unix/ protected ``quipurc'' (see Section~\ref{quipurc}).
Alternatively, if you do not supply a password, you will be prompted for one.

Passwords can be found by examining the DSAs textual
database as the \unix/ super-user.  If an entry does not have a password,
attempts to bind as that entry will always fail.

\subsection {Unbind}

\begin{verbatim}
unbind [-noquit] [-cache <file>]
\end{verbatim}

This is used to break the connection to a DSA.
If -noquit is specified, the dish process does not die (This is used to
maintain the cache).

To be ``friendly''
to other users, you should unbind 
when you have finished using the directory --- put an \tt unbind\rm \ in
you ``.logout'' file if you use \verb"dish" from the shell.

For and explanation of the `\tt -cache\rm ' flag see Section~\ref{dua_cache}.

\subsection {Sequences}
\label{sequences}

Results returned by {\em search} and {\em list} may be long, and for 
this reason have a reference number printed beside them.
The reference number can be used as the ``object'' in any of the calls to the 
directory.  Thus
\begin{verbatim}
showentry 6
\end{verbatim}
shows the entry labeled with the sequence number
``6'' by a previous {\em search} or {\em list}.

When you come into dish
by default, the resultant numbers of list and search operations 
are added to a sequence called ``default''.

To get a different sequence (hence renumber from 1 again), you can change
this to ``mysequence'' with a 
\begin{verbatim}
-sequence mysequence
\end{verbatim}
flag.

To completely remove the concept of sequences (so no numbers are printed by list
or search) use ``\tt -nosequence\rm\ ''.



\f

\section {Tailoring}

There are two levels of tailoring that control the operation of the DISH DUA.
First of all there is the system wide tailor file \file{/usr/etc/dsaptailor}, and
then users private tailor file \file{.quipurc}.

\file{/usr/etc/dsaptailor} is described in Section~\ref{dua:tailor}.

\subsection {.quipurc}
\label{quipurc}\index{.quipurc}
The file \file{.quipurc} is read by \verb"dish" on start up, and
has the following format:-

\begin{verbatim}
flag:	value
\end{verbatim}

The following flags are currently recognised:-
\begin{description}

\item [username] The name of the user to bind as.

\item [password] The password to use when binding.  For this reason care
should be taken to ensure you .quipurc file is not publicly readable.

\item [cache\_time] How long to keep the dish process alive after unbinding
(specified in minutes)

\item [connect\_time] How long to keep a connection open, it there is no
activity (specified in minutes)

\item [service] A list of default service control flags 
(as defined in Section~\ref{dish_serv}).

\item [dsap] This can be followed by one of the dsaptailor options
described in the Section~\ref{dua:tailor}.\index{dsaptailor}

\item [isode] 
This can be followed by one of the ISODE tailor options
described in \volone/ of this Manual.

\item [notype] The argument is expected to be an attribute type.
This attribute will not be displayed by showentry by default.

\item [type] The only valid argument for this entry is ``unknown'', and says 
that unknown attributes should be shown, by default, they are not shown.

\item [$<$dish command$>$] A list of default flags 
to be used when `command' is used.
For example
\begin{verbatim}
showname: -compact
\end{verbatim}
says that ``showname'' should always be invoked with the 
\tt -compact \rm \ flag set.

\item [$<$nickname$>$] A nickname entry, for example
\begin{quote}
cjr: ``c= GB @ o= University College London @ ou= Computer Science @ CN= Colin Robbins''
\end{quote}
This can then be used in distinguished name arguments, for example
\begin{verbatim}
showentry cjr
\end{verbatim} 
will show the entry for `Colin Robbins'.

\end{description}


\f

\section {Remote Management of the DSA}\label{dua:mgmt}
\begin{verbatim}
dsacontrol [-[un]lock <entry>] [-dump <directory>] 
	[-tailor <string>]  [-abort] [-slave]
	[-refresh <entry>] [-resync <entry>]
\end{verbatim}

If the \pgm{dish} program is bound to the DSA as the Directory manager
(See Section~\ref{dish_bind} on binding),
then it may be used to (primitively) manage the DSA.
This process is discussed in \cite{QUIPU.Design} and Section~\ref{dsa:mgmt}
of this Manual.

\tt (un)lock\rm \ used to (un)lock subtrees of the DIT held locally. This
(allow) prevent users to modify the DIT.

\tt dump\rm \ causes a copy of the local DIT to be dumped into the specified 
directory.
Note that when the DSA dumps its in-core database,
it does so relative to the (possibly remote) \unix/ directory from which the
DSA was started,
not the directory that \man dish(1c) was invoked in!
So it is best to specify path names in full to ensure the database is dumped
where you expect it to be!

\tt tailor\rm \ is used to pass tailor command to a running DSA.  The format of
``string'' is the same as a line in the ``quiputailor'' file.
For example:-
\begin{verbatim}
dsacontrol -tailor "dsaplog level=all"
\end{verbatim}
will turn the DSA logging on full.

\tt refresh\rm \ tells the DSA to re-read sub-tree `entry' from disk.

\tt resync\rm \ tells the DSA to re-write the sub-tree `entry' to disk.

\tt slave\rm \ tell the DSA to update its SLAVE EDB files, see Section
\ref{slave_update} for details.

\section {Caching in the DUA}
\label {dua_cache}

All results returned from read and list operations are cached in memory
in the DUAs.  The cache is then used if possible to answer queries.
The cache is kept throughout the life of the DUA process, there is
no mechanism (in the current version of the software) to ``timeout''
the cached data.

Disk caching has not been implemented yet,
but it is intended to extend the in-core caching, 
so that the cached data can be written to disk.  When the DUA's start up, the
user will have the option to read this cache.
Similar support for private data may be provided.

\section {Running DISH from the Shell}
\label{dish_shell}

Each of the dish commands mentioned in Sections \ref{dish_start} to
\ref{dua:mgmt}
can be applied directly to the shell, without having to first invoke
\pgm{dish}.  This has the advantage that the result can be piped through
programs like \pgm{more} thus giving the user flexibiltiy in how
they view the data.

Chapter~\ref{quipu:install} describes how to install this ``extra'' feature of
dish.

\subsection {Dishinit}
As an example of how this \verb"dish" can be used from a shell, there is 
an example script called \pgm{dishinit}.
\label{dishinit}
This binds to the directory as the manager, reads certain information, which is 
then used to create a 
default \verb".quipurc"
file for a specified user.
This is a useful utility for new databases.
If the \verb"dsaptailor" variable \verb"dishinit" is set to \verb"on",
dishinit will be invoked by \verb"dish" whenever is can not find a 
.quipurc file.

\verb"dishinit" needs three parameters to be set inorder to bind as the 
manager, and search the local subtree.
These parameters are defined at the top of the dishinit script and are:-
\begin{description}
\item [manager] The DN of the manager of the local DSA
\item [password] The managers password (the script should be protected 
with \unix/ file protection).
\item [position] The DN of the local sub-set of the DIT. This is where 
the entries for users will be looked for
\end{description}


\subsection {Files}

DISH uses various temporary files when invoked from the shell.
These are then ``named pipes'' which DISH uses to communicate with the
various commands. 

The file ``/tmp/dish$<$pid$>$'' is used by dish to write results to the calling
processes, where the ``pid'' is the process id of the calling process.

The file ``/tmp/dish--$<$tty$>$--$<$uid$>$'' is used by calling process to send commands to
dish, where ``tty'' is the users terminal number, and ``uid'' their user id.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦87e60326d⟧ TextFile

Derivation

TextFile
