Portable DUAs
How to set up programs that access the X.500 directory
Tignor, T., "Portable DUAs", RFC 1373, DOI 10.17487/RFC1373, October 1992, <https://www.rfc-editor.org/info/rfc1373>.
@misc{rfc1373,
series = {Request for Comments},
number = 1373,
howpublished = {RFC 1373},
publisher = {RFC Editor},
doi = {10.17487/RFC1373},
url = {https://www.rfc-editor.org/info/rfc1373},
author = {T. Tignor},
title = {{Portable DUAs}},
pagetotal = 12,
year = 1992,
month = oct,
} RFC text
Contents
Network Working Group T. Tignor
Request for Comments: 1373 ISI
October 1992
PORTABLE DUAs
Status of this Memo
This memo provides information for the Internet community. It does
not specify an Internet standard. Distribution of this memo is
unlimited.
INTRODUCTION
This document comes in two parts. The first part is for regular
people who wish to set up their own DUAs (Directory User Interfaces)
to access the Directory. It includes some brief notes on the
operation of the DUAs and instructions for their creation and
installation. The instructions are given in an easy-to-follow, step-
by-step format. It is fully expected that the user will be able to
perform the necessary operations as he reads through the instructions
for the first time and have a working DUA when he finishes. The
second part is for ISODE-maintainers wishing to provide portable DUAs
to users. This part gives instructions in a similar but longer,
step-by-step format. It is fully expected that the maintainer will be
able to perform the necessary operations as he reads through the
instructions for the first time and have a working DUA
package/supporting service when he finishes.
The document currently has four sub-parts for each larger part. The
sub-parts detail the following DUAs: WHOIS, "de," dixie's "ud" and
ISODE's "doog." It is intended that additional sub-parts will be
added to the document as new, portable DUA packages are designed.
Where pertinent, the document assumes ISODE 8.0 is being used.
1. Instructions for DUA-Users
WHOIS
A WHOIS interface to X.500 may be available on any ISODE-resident
machine which also runs a DSA (Directory System Agent.) Check with
your local, ISODE-maintainer. If the service is available, users can
access the Directory with the following command:
whois -h <hostname> <name in UFN format>
<hostname> indicates the name of the host machine offering the WHOIS
interface, surrounded by quotes. <name in UFN format> refers to a
special, user-friendly syntax developed by Steve Hardcastle-Kille.
UFN format is a comma-separated list of DN component values.
(Attribute types are omitted.) The criteria for identifying DN
components in UFN is often less stringent than normal. For example:
@c=US@st=California@o=Information Sciences
Institute@ou=HPCC@cn=Tom Tignor
could be uniquely specified in UFN syntax as
tignor,isi,ca,us
So to find this entry through WHOIS, one would type:
whois -h "gum.isi.edu" tignor,isi,ca,us
See Steve Hardcastle-Kille's Work in Progress, "User Friendly Naming"
for details.
De
Use of the "de" DUA is fully explained by the program's help section.
New users should type "?" at the first prompt after installing and
running the de executable.
The de executable can be created and installed by the following
simple steps:
If you do not have a file called ".unknown_tailor" in your home
directory, create it now. This file should contain the following
single line:
etcpath: <fullpathname>/isode/etc/
where <fullpathname> is the full path name of your $HOME
directory.
If you do not have a directory $HOME/isode/bin, where "$HOME" is
your home directory, create it now.
ftp the compressed tar file "de-portable.tar.Z" from your local,
ISODE-resident machine and put it in your isode directory. If
you cannot find this file locally, it is available by anonymous
ftp from "gum.isi.edu" in the "x500" directory.
cd $HOME/isode
uncompress < de-portable.tar.Z | tar xf -
If your name is listed in the Directory, edit the de/detailor
file and add a line reading:
username: <yourDN>
where <yourDN> indicates your Distinguished Name in the
Directory.
cp de/detailor de/etc/detailor
Edit the CONFIG.make variables BINDIR, ETCDIR and SBINDIR to
refer to your isode/bin, isode/etc and isode/etc directories,
respectively. (The isode/etc directory was created by the
previous command.)
ranlib libdsap.a
ranlib libisode.a
cd de
./make all
./make inst-all
There is one error you may encounter during this procedure, following
the "./make all" command:
"Redeclaration of sprintf." in general.h
If this error occurs, the following sub-procedure will fix the
problem:
Invoke your editor for the file ../h/general.h
Search for the string "sprintf".
Cut the line with the "#endif" string which follows the line
reading:
char *sprintf ();
Paste the line under the line which reads "#endif". This second
#endif line is exactly three lines below the current line.
Save the file and quit the editor.
Type "./make all" again. It should now compile smoothly. Finish up by
typing "./make inst-all".
Dixie/Ud
The "ud" DUA is designed for users doing most of their X.500 queries
in one branch of the DIT (Directory Information Tree.) The DUA
operates from a predefined "base," a position in the DIT one or more
branches above the entries to be queried. The base is usually an
organization name, such as:
@c=US@st=California@o=Information Sciences Institute
Ud starts with a preset base. (See below.) But this base can be
changed with the "cb" command. "cb" takes the full DN of the new base
as an argument. For example:
cb @c=GB@o=University College London
With a preset base, searching is easy. The user finds entries below
the base with the "find" command. "find" takes the last component of
the DN of the entry as its sole argument. The criteria for the
argument is very loose. The partial matching performed by ud should
return the desired data or a clarification request if the name is at
all close to the real thing.
For example, with a base "@c=US@st=California@o=Information Sciences
Institute", the RDN
ou=HPCC@cn=Tom Tignor
could be found by entering
find tignor
at the ud prompt.
Other commands in ud are briefly described by the program's help
section. Interested users should type "?" at the first prompt, after
installing and running the executable.
"Ud" comes with the "dixie" package, a mini-environment designed
specifically to support lightweight Directory access. Using ud
requires that a dixie server is running along with a DSA on your
local, ISODE-resident machine. Before retrieving the dixie package,
check with your local DSA manager to see that the dixie server is up
and running.
Once you're sure that everything is set up at the DSA-manager's end,
the ud executable can be created and installed by the following
simple steps:
If you do not have a directory $HOME/isode/bin, where "$HOME" is
your home directory, create it now.
ftp (anonymously) the compressed tar file "dixie-<version
#>.tar.Z", where <version #> is the number of the latest
release, from "terminator.cc.umich.edu" and put it in your isode
directory. The file is available in the "x500" directory on
terminator.
cd $HOME/isode
uncompress < dixie-<version #>.tar.Z | tar xf -
This creates the dixie environment. As a user interested in ud only,
there are a number of things in the package that will be taking up
space to no purpose. The following sequence of commands will get rid
of them.
cd dixie-<version #>
rm -r dos
rm -r macintosh
rm -r server
rm -r vms
cd ..
That done, we continue to bring ud to life.
cd dixie-<version #>
Edit the file "ud/ud.h". There are two constants for which you
will need to supply new values: DEFAULT_BASE and DEFAULT_SERVER.
DEFAULT_BASE identifies ud's "base" upon startup, as described
above. It takes a quoted DN as a value, e.g.,
"@c=US@st=California@o=Information Sciences Institute".
DEFAULT_SERVER identifies the machine which hosts the dixie
server, i.e. your local, ISODE-resident machine. This constant
takes a quoted string as a value, e.g., "gum.isi.edu".
Edit the file "Makefile". Set the value of the BINDIR variable
to "<mypath>/isode/bin", where <mypath> is the full pathname of
the user's home directory.
make depend-ud
make ud-only
make inst-ud
Doog
The "doog" DUA retrieves information on entries supplied by the user
in UFN format. UFN format refers to a special, user-friendly syntax
developed by Steve Hardcastle-Kille. UFN format is a comma-separated
list of DN component values. (Attribute types are omitted.) The
criteria for identifying DN components in UFN is often less stringent
than normal. For example:
@c=US@st=California@o=Information Sciences
Institute@ou=HPCC@cn=Tom Tignor
could be specified in UFN syntax (and doog) as
tignor,isi,ca,us
See Steve Hardcastle-Kille's Work in Progress, "User Friendly Naming"
for details.
Other commands in doog are briefly described by the program's help
section. Interested users should type "?" at the first prompt, after
installing and running the executable.
The doog executable can be created and installed by the following
simple steps:
If you do not have a file called ".unknown_tailor" in your home
directory, create it now. This file should contain the following
single line:
etcpath: <fullpathname>/isode/etc/
where <fullpathname> is the full path name of your $HOME
directory.
If you do not have a directory $HOME/isode/bin, where "$HOME" is
your home directory, create it now.
ftp the compressed tar file "doog-portable.tar.Z" from your
local, ISODE-resident machine and put it in your isode
directory. If you cannot find this file locally, it is available
by anonymous ftp from "gum.isi.edu" in the "x500" directory.
cd $HOME/isode
uncompress < doog-isode-8.0.tar.Z | tar xf -
Edit the CONFIG.make variables BINDIR, ETCDIR and SBINDIR to
refer to your isode/bin, isode/etc and isode/etc directories,
respectively. (The isode/etc directory was created by the
previous command.)
ranlib libdsap.a
ranlib libisode.a
cd doog
./make all
./make inst-all
2. Instructions for ISODE-Maintainers
WHOIS
"WHOIS" is a simple program already available at most UNIX
workstations and hosts. It is normally used to access the database of
users at NIC.DDN.MIL. The instructions below explain how to use WHOIS
to access data in the White Pages Pilot X.500 database. These
instructions are taken nearly word for word from the "PSI White Pages
Pilot Project Administrator's Guide," section 2.8.3.
Choose a machine in your local environment which is running the pilot
project software. This machine will offer the white pages service via
a network port offering an emulation of the WHOIS service.
On this machine, modify the /etc/services file so that it contains an
entry like this:
whitepages 17005/tcp
Next, edit the file /etc/servers so that it has an entry like this:
whitepages tcp $(SBINDIR)in.whitepages
Because most user interfaces to WHOIS, e.g., whois(1c), do not allow
the user to specify a special port, you should probably also add this
line as well:
whois tcp$(SBINDIR)in.whitepages
If you already have a line for whois in the servers file, then you
are already running a WHOIS service, and you should NOT add a second
whois line. This machine is not a good choice for running the white
pages via WHOIS emulation.
Note that on newer systems derived from Berkeley UNIX, /etc/servers
is called /etc/inetd.conf.
The whitepages Command
On those systems which are to access the white pages via the network
and not locally (i.e., those systems which are not running the pilot
project software), you should determine how the user invokes the
WHOIS service via the network. For UNIX systems, you should provide a
shell script like this:
: run this script through /bin/sh
exec /usr/ucb/whois -h wp.psi.net "$*"
where the name of a host running the pilot project software is
substituted for whitepages, e.g., wp.psi.net. This host must have the
files /etc/services and /etc/servers edited as described above.
De
The compressed tar file for "de" can be created by the following
sequence of commands. (Note: In the instructions which follow,
<toplevel> indicates the top level of the ISODE distribution.)
cd <toplevel>/others/quipu/uips
Edit the de/detailor file to set the following options:
dsa_address: (the address of your DSA)
default_country: (your country)
default_org: (your organization)
cp de/make temp1
Edit the de/make file so that the last line reads as follows:
exec $M TOPDIR=../ -f ../CONFIG.make -f Makefile ${1+"$@"}
tar -cf de-portable.tar de/*
mv temp1 de/make
mv de-portable.tar <aboveETCDIR>
(Here, <aboveETCDIR> is the directory immediately above
ETCDIR.)
cd <aboveETCDIR>
tar -rf de-portable.tar etc/dsaptailor etc/isomacros
etc/oidtable.at etc/oidtable.oc etc/oidtable.gen
mv de-portable.tar <toplevel>
cd <toplevel>
cp config/CONFIG.make .
tar -rf de-portable.tar h/* h/quipu/* util/* CONFIG.make
libdsap.a libisode.a
rm CONFIG.make
compress de-portable.tar
The compressed tar file for de will appear in the top level directory
of the ISODE distribution as "de-portable.tar.Z".
Dixie/Ud
The latest version of the dixie distribution is available by
anonymous ftp at "terminator.cc.umich.edu" in the "x500" directory.
The file is named "dixie-<version #>.tar.Z", where <version #> is the
number of the latest release.
In order for anyone to use dixie clients, there must be a running
dixie server which they can connect to. To set up the dixie server,
the DSA manager should take the dixie package and explode/uncompress
it in the top level directory of the ISODE distribution. This is done
with the following command:
uncompress < dixie-<version #>.tar.Z | tar xf -
where <version #> is the version number of your dixie package. This
will create a "dixie-<version #>" directory. The dixie server, dixie
library and any DUAs included with the package will be in this
directory branch. Software to support dixie on machines other than
UNIX is included as well. This software is stored in the directories
"dos", "macintosh" and "vms". UNIX users should feel free to delete
these directories and all their contents. Commands of the form:
rm -r <dirname>
where <dirname> is the directory name, should accomplish this task.
In the top level of the dixie distribution is a file called
"Makefile". The file holds several variables which should be
configured to match those of your ISODE environment.
BINDIR ISODEINCLUDEDIR
ETCDIR LIBDIR
INCLUDEDIR ISODELIBS
INSTLIBDIR
In the "server" directory below the top level of the dixie
distribution is another "Makefile" file. Configure the ISODELIBS
variable in this file, as well.
After setting these variables, cd to the top level of the dixie
distribution and type the following commands:
make depend-server
make server-only
make inst-server
This will create and install the dixie server in your ETCDIR. cd to
the ETCDIR and type "dixie" to start the server.
Doog
The compressed tar file for "doog" can be created by the following
sequence of commands. (Note: In the instructions which follow,
<toplevel> indicates the top level of the ISODE distribution.)
cd <toplevel>/others/quipu/uips
cp doog/make temp1
Edit the doog/make file so that the last line reads as follows:
exec $M TOPDIR=../ -f ../CONFIG.make -f Makefile ${1+"$@"}
cp doog/query/make temp2
Edit the doog/query/make file so that the last line reads as
follows:
exec $M TOPDIR=../../ -f ../../CONFIG.make -f Makefile
${1+"$@"}
tar -cf doog-portable.tar doog/*
mv temp1 doog/make
mv temp2 doog/query/make
mv doog-portable.tar ../../..
cd ../../..
cp config/CONFIG.make .
tar -rf doog-portable.tar h/* h/quipu/* util/* CONFIG.make
libdsap.a libisode.a
rm CONFIG.make
mv doog-portable.tar <aboveETCDIR>
(Here, <aboveETCDIR> is the directory immediately above
ETCDIR.)
cd <aboveETCDIR>
tar -rf doog-portable.tar etc/dsaptailor etc/isomacros
etc/oidtable.at etc/oidtable.gen etc/oidtable.oc
compress doog-portable.tar
The compressed tar file for doog will appear in the directory
immediately above ETCDIR as "doog-portable.tar.Z".
Security Considerations
Security issues are not discussed in this memo.
Author's Address
Tom Tignor
University of Southern California
Information Sciences Institute
4676 Admiralty Way
Marina del Rey, CA 90292
Phone: (310) 822-1511
EMail: tpt2@isi.edu
AI ELI5
On this page
§1What This Document Does
RFC 1373 is a practical guide in two parts. The first helps regular users install and run Directory User Agents (DUAs)—programs that let you search the X.500 directory. The second helps system maintainers prepare these DUAs as portable packages for distribution.
The document covers four different DUA implementations: WHOIS, de, dixie/ud, and doog. Each one offers a different way to access the directory, from a simple command-line tool to a full interactive interface. The instructions assume you are running ISODE 8.0, the standard X.500 implementation software at the time.
This is a how-to manual. It has two sets of instructions: one for people who want to use a directory lookup tool, and one for people who want to package it up for others to use.
§2User Installation for Four DUAs
WHOIS is the simplest option. It uses a command-line interface to query a remote X.500 server. Users run whois -h hostname search-term where the search term follows UFN (User Friendly Naming) format: a comma-separated list of directory components like tignor,isi,ca,us.
De is a text-based interactive DUA. Installation requires creating configuration files, fetching a compressed archive, and running a compiler. Users may encounter a redeclaration error in general.h during compilation, which the RFC provides a workaround to fix.
Dixie/Ud is designed for users who search mostly within a single branch of the directory tree. It uses a preset base position (like an organization name), letting users search below that point without typing the full path. The dixie server must be running on the local ISODE machine.
Doog retrieves directory entries using UFN format. Like de, it requires downloading a tar archive, compilation, and configuration. Users interact with it at a command prompt.
Each tool has its own way of working. WHOIS is quick and simple. De and doog need you to compile and configure them. Ud is best if you mostly search in one department or organization.
§3System Maintainer Packaging
Maintainers who run a DSA (Directory System Agent) can create portable packages of these DUAs for their users. The process differs for each tool.
For WHOIS, the maintainer configures the /etc/services and /etc/servers files (or /etc/inetd.conf on newer systems) to run a WHOIS emulation service. Users on machines without the DSA software can use a shell script that redirects them to the maintainer's WHOIS server.
For de and doog, the maintainer extracts the source from the ISODE distribution, configures files like detailor or the CONFIG.make variables, then compresses the result into a portable tar archive for distribution. These archives must include the required libraries and configuration files.
For dixie/ud, the maintainer downloads the latest dixie package, configures the Makefile variables to match the ISODE environment, and builds the server. The server then runs continuously to serve clients. Users download the dixie package separately and configure it to point to the maintainer's server.
If you run the directory server, you can package the lookup tools for others to use. Some need server changes, others just need you to distribute a package they can compile.
§4Directory Concepts and UFN Format
The X.500 directory uses Distinguished Names (DNs) to identify entries. A DN is a path through the directory tree, written as components like @c=US@st=California@o=ISI. The @ symbol separates components, and the two-letter codes identify attribute types (c for country, st for state, o for organization).
User Friendly Naming (UFN) simplifies this. Instead of writing the full DN with attribute types, you write just the values as a comma-separated list: tignor,isi,ca,us instead of cn=Tom Tignor,ou=HPCC,o=ISI,st=California,c=US. DUAs that support UFN make the directory much easier for non-experts to use.
A Directory Information Tree (DIT) is the hierarchical structure of the directory, with the root at the top and organizations, departments, and people organized below. A DUA's base is a preset position in this tree where searches begin—usually an organization name.
The directory is like a phone book, but organized in a tree. UFN format lets you write names the simple way: just list the parts separated by commas, like you would say a person's name.