IInnssttaalllliinngg tthhee CCCCSSOO NNaammeesseerrvveerr
by
Steven Dorner
[email protected]
Computer and Communications Services Office
University of Illinois at Urbana
March 4, 1992
updated by
Paul Pomes
[email protected]
Computer and Communications Services Office
University of Illinois at Urbana
August 2, 1992
_I_n_t_r_o_d_u_c_t_i_o_n
This document covers the installation of the CCSO Nameserver.
Included are a description of the distribution, instructions on
configuring the software, and some suggestions for building a
database. Detailed descriptions of the various parts are left
for other documents.
The Nameserver requires a UNIX system with a reasonable amount of
Berkeley-ness. If you have a pure System V machine, you're in
for a lot of fun. It also requires a C compiler (ANSI C pre-
ferred), and perl.
_A _W_o_r_d _A_b_o_u_t _S_u_p_p_o_r_t
The word about support is, "no". This software is provided as-
is, and neither I nor the University of Illinois nor CSNet nor
even your mother takes any responsibility for anything bad that
happens because of it.
On the other hand, we do use the software extensively, and are
interested in bug reports and suggestions. As time permits, I
will answer email questions about the software, provided those
questions aren't answered in the supplied documentation, or
available through a quick perusal of the source code.
____________________
Converted to portable n/troff format using the -me macros from
funky Next WriteNow format (icch).
22 IInnssttaalllliinngg tthhee CCCCSSOO NNaammeesseerrvveerr
_T_h_e _D_i_s_t_r_i_b_u_t_i_o_n
This section describes the various pieces of the distribution.
Each piece is marked with one of several codes, which are listed
in _b_o_l_d. The codes and their meanings are:
vviittaall Things you must use/understand/modify to get the
Nameserver up and running.
iimmppoorrttaanntt Things you had better become familiar with, but can be
safely skipped or taken for granted during initial
installation.
ooppttiioonnaall Things you may or may not wish to use someday.
uuiiuucc Things we use at UIUC that may be of little or no use
to you, except as models.
Two general notes. First, _M_a_k_e_f_i_l_e in the various subdirectories
are generated from the _M_a_k_e_f_i_l_e._t_e_m_p_l files in those same direc-
tories, by _C_o_n_f_i_g_u_r_e. Second, the RCS subdirectories do contain
RCS files, but there are almost no useful log messages; the files
are used for checkpointing only.
README.NOW vviittaall Release notes, general instructions,
warnings, last-minute changes, etc.
Please read it before you go any
further. Then, please read this entire
document.
buildmisc uuiiuucc This directory contains the Makefile we
use to do database updates. While it's
certainly instructive, much of it is
UIUC-specific. Saying "touch s.tape.raw
f.tape.raw s.tape.all old.dir old.dov;
make -n" in this directory is a good way
to get an idea of what our update pro-
cess looks like.
configs vviittaall This directory contains configuration
files (perl fragments) for use in confi-
guring the software. These fragments
are divided into two major classes;
operating-system specific fragments and
setup-specific fragments. More about
these in the Configure section below.
configs/defaults vviittaall Defaults for the configuration process.
configs/{aix,convex,dynix,next,ultrix} iimmppoorrttaanntt
These are OS-specific configuration
files. Use these to get basic parame-
ters for the flavors of UNIX involved.
IInnssttaalllliinngg tthhee CCCCSSOO NNaammeesseerrvveerr 33
configs/{garcon,net-nav,ux2,uxa} uuiiuucc
These are specific configuration files
for our setups. They may be instruc-
tive, but you'll not be able to use any
of them directly.
Configure vviittaall This perl script configures the source
tree. _N._B., you _m_u_s_t read the _C_o_n_f_i_g_u_r_e
section below before trying to use _C_o_n_-
_f_i_g_u_r_e; it's not like the Configure that
comes with (eg) rn or perl.
olddoc ppttiioonnaall This directory contains older documents,
of varying relevance and utility, in a
variety of formats. This directory will
be removed when its contents have been
completely superseded.
help iimmppoorrttaanntt A directory which contains help files
for the server's use.
help/native iimmppoorrttaanntt A directory of help files related to the
server and its database, but not to any
particular client.
help/{macph,ph} iimmppoorrttaanntt
Directories for client-specific help.
include iimmppoorrttaanntt This directory contains include files
for the Nameserver.
lib iimmppoorrttaanntt Some library routines for common use.
Makefile iimmppoorrttaanntt This is the master Makefile for the
whole system, and is generated by _C_o_n_-
_f_i_g_u_r_e.
doc vviittaall This directory contains the most up-to-
date documents in n/troff format using
the -me macro package. The man pages,
_p_h._1 and _q_i._8, use the -man macros.
doc/install.me vviittaall You're reading it now.
ph iimmppoorrttaanntt The UNIX _p_h client lives here.
qi iimmppoorrttaanntt And here is the server.
util vviittaall This directory contains files that are
useful for building or manipulating
Nameserver data. You will probably have
to modify some of these programs for use
in building your own database. Which
44 IInnssttaalllliinngg tthhee CCCCSSOO NNaammeesseerrvveerr
ones depend on your situation.
util/age uuiiuucc We use this to get rid of people who
have been in the database for a year
after they've actually left UIUC.
util/aliasassign iimmppoorrttaanntt
This is a perl script that takes the
output of _a_l_i_a_s_p_r_e_p_a_r_e and assignes
unique aliases (and kerberos fields).
It produces a file in _m_a_k_e_d format (see
below).
util/aliasprepare iimmppoorrttaanntt
A perl script that takes input in _m_a_k_e_d
format, and produces input for _a_l_i_a_s_a_s_-
_s_i_g_n.
util/border.c iimmppoorrttaanntt This program reorders the bytes in a
Nameserver database. This allows data-
bases to be moved between machines with
VAX and 68000 byteorders.
util/build.c iimmppoorrttaanntt Build takes the ._i_d_x and ._i_o_v files and
generates from them the ._s_e_q and ._b_d_x
files.
util/credb.c iimmppoorrttaanntt Creates an empty database.
util/f.unblock uuiiuucc Perl script that takes a UIUC staff
dataset and puts it into _m_a_k_e_d format.
util/id.c uuiiuucc Functions for dealing with real id <->
fake id mapping.
util/maggie uuiiuucc A perl script to produce input for the
UIUC printed phone book.
util/maked.c iimmppoorrttaanntt This program turns _m_a_k_e_d format files
into ._d_i_r and ._d_o_v files.
util/makei.c iimmppoorrttaanntt _M_a_k_e_i generates the hash table (._i_d_x and
._i_o_v) from the ._d_i_r and ._d_o_v files.
util/mdump.c iimmppoorrttaanntt Dumps the database according to various
criteria and into various forms.
util/merge3 uuiiuucc We use this perl script to reconcile the
old database with new student and/or
staff information. Pray you never,
ever, have to get near it.
IInnssttaalllliinngg tthhee CCCCSSOO NNaammeesseerrvveerr 55
util/nsck.c iimmppoorrttaanntt Runs some consistency checks on the
database.
util/phify ooppttiioonnaall A script that turns _m_a_k_e_d format data
into something that looks like _p_h out-
put.
util/phoneaddr uuiiuucc Perl script that copies either office or
home phone and address into phone and
address fields. Uses _m_a_k_e_d format.
util/qierrs ooppttiioonnaall Perl script that sifts the output of _q_i,
looking for errors.
util/s.unblock uuiiuucc Perl script that takes a UIUC student
dataset and puts it into _m_a_k_e_d format.
util/ssndump.c uuiiuucc Dumps a dbm real id <-> fake id database
into ASCII form.
util/ssnid.c uuiiuucc Uses a dbm real id <-> fake id database
to map real id's to fake id's, and to
assign fake id's.
util/ssnload.c uuiiuucc Loads a dbm real id <-> fake id database
from ASCII form.
util/testqi.csh iimmppoorrttaanntt
A script that tests _q_i, at least
minimally.
whoi ooppttiioonnaall A "whois" server that actually uses _q_i.
xtra ooppttiioonnaall Stuff related to the Nameserver, but not
integrated into the distribution.
_C_o_n_f_i_g_u_r_e
_C_o_n_f_i_g_u_r_e is a perl script that gets the source ready for compi-
lation. This process includes setting up compilation and linking
options, choosing database locations, deciding where binaries go,
and determining which features to enable. It does this by build-
ing _M_a_k_e_f_i_l_e from the _M_a_k_e_f_i_l_e._t_e_m_p_l and building the _c_o_n_f._h and
_c_o_n_f._c source files. _C_o_n_f_i_g_u_r_e makes use of files in the _c_o_n_f_i_g_s
subdirectory. It reads _c_o_n_f_i_g_s/_d_e_f_a_u_l_t_s first, and then read in
turn each of its argument files. These files should contain perl
scripts.
The scripts supplied are separated into three categories. In the
first category is defaults, which is read first, and contains
global defaults. Insofar as possible, I suggest you leave
defaults alone; if you wish to alter the environment it creates,
do so by overriding the defaults with your own configuration
66 IInnssttaalllliinngg tthhee CCCCSSOO NNaammeesseerrvveerr
files.
The second category of scripts are OS-specific scripts. These
scripts set compiler options and defines for use with various
flavors of UNIX.
The third category are installation-specific scripts. These
scripts are used to define options for a particular databases.
Use of these scripts make it easy to run multiple _q_i databases on
a single host, with different features enabled on each database.
The scripts you write should primarily set perl variables. The
values of these variables will later be used when _C_o_n_f_i_g_u_r_e is
actually run. The variables you may set and what you may set
them to are described in the _d_e_f_a_u_l_t_s script. I will highlight a
few of the most important here. You should, of course, review
all the variables; just be doubly sure not to miss these.
o+ The @Features array can be used to enable optional features in
the code. If you want to run with encrypted passwords, this
array is the place to say so.
o+ $CC is your C compiler. This should be an ANSI C compiler; I
use gcc.
o+ $Owner and $Group own the nameserver binaries and database.
o+ If you have some extra libraries you need, put them in
$MoreLib.
o+ $ExecDir is where executables will be put.
o+ $DefineStrings{"Database"} is the name of your database, shorn
of suffices, but with the leading path component.
o+ $OtherDefines{"Drecsize"} and $OtherDefines{"Doversize"} must
be correct for your database, as must
$OtherDefines{"NIChars"}.
_T_h_e _F_i_e_l_d _C_o_n_f_i_g_u_r_a_t_i_o_n _F_i_l_e
The field configuration file is _q_i's key to interpreting your
database. In this file you associate names with field numbers,
and determine the properties of fields. The file should be named
the same as your database, but with a ._c_n_f extension (older ver-
sions of source and documents may refer to this as the _p_r_o_d._c_n_f
file). It consists of lines of the form:
3:name:256:Full name.:FS:Indexed:Lookup:Public:Default:
The first item is the field id (in this case, 3). This number
identifies the field in an entry, or in a _m_a_k_e_d format file. The
second item is the field name (in this case, "name"), which
should be used in commands, and will be printed in query
responses. The third item is the maximum length of the field (in
this case, 256 characters); maximum lengths should be less than
4096 characters. The fourth item is a brief description of the
field. The fifth item contains instructions for the _m_e_r_g_e_3 pro-
gram; if you don't use _m_e_r_g_e_3, put an "O" in this item. The
IInnssttaalllliinngg tthhee CCCCSSOO NNaammeesseerrvveerr 77
final items contain a list of field attributes. Only the first
character of the attributes are significant. The attributes and
their functions are:
I Indexed; the contents of this field will be put in the data-
base index. At least one Indexed field must be included in
every query.
L Lookup; users may use this field in queries.
P Public; the contents of this field may be displayed to any-
one (but see "F" below).
D Default; this field will be returned for queries that do not
specify which fields to return.
C Change; users may change the contents of this field.
F ForcePub; users may not suppress this field. Fields not
marked "F" may be hidden from view by putting something
(anything) in the F_SUPPRESS field.
N NoPeople; users may change this field, but only if their
F_TYPE field does not contain "person".
E Encrypt; this field may not cross the network, nohow, noway.
W Any (Wild); fields so marked may be searched collectively by
specifying an "any" field in a query.
There are other defined attributes, but they are not used at this
time.
You have a great deal of freedom in how you manage your field
configuration file. You may have as many fields as you like, and
give them whatever names, numbers, and attributes you like.
There is, however, a relatively small set of "core" field names
and numbers. If you change these field names or numbers, or omit
them from the database, you are likely to have to make changes to
the source to accommodate the change. These fields are:
2:email
3:name
4:type
5:id
6:alias
7:password
8:proxy
23:nickname
25:all
30:hero
43:suppress
88 IInnssttaalllliinngg tthhee CCCCSSOO NNaammeesseerrvveerr
Furthermore, there are some other fields that are used by some of
the utilities, or auxilliary programs like _p_h_q_u_e_r_y. If you
modify these names or numbers, some such programs may have diffi-
culty.
0:address
1:phone
9:department
10:title
11:curriculum
20:home_address
21:permanent_address
22:office_address
26:callsign
31:no_update
32:office_phone
33:home_phone
35:high_school
37:permanent_phone
42:left_uiuc (_o_n_l_y _t_h_e _n_u_m_b_e_r _i_s _i_m_p_o_r_t_a_n_t _f_o_r _t_h_i_s _o_n_e)
Our field configuration file is included in the _q_i distribution,
for reference.
This document is incomplete. Sorry.
