The CSO Nameserver
Guide to Installation
December 22, 1988

by Steven Dorner
Computing Services Office
University of Illinois at Urbana-Champaign

Introduction
	This document provides instructions, general and specific, for installing the programs that make up CSO Nameserver.  To decide if you want to install the CSO Nameserver at all, I suggest you read The CSO Nameserver, A Description.  For detailed information on the inner workings of the Nameserver, you should read The CSO Nameserver, A ProgrammerUs Guide.  If you follow the procedures in this document, you will end up with the right programs in the right places; you will not yet have a functioning system.  You must first come up with data, and form that data into a valid Nameserver database.  For an example procedure to build a Nameserver database, Rebuilding a Nameserver Database, In 24 Easy Steps should be perused.  Your procedure is likely to differ from ours, since you will undoubtedly have your data in a form unlike our own.
	Do read all of this document before beginning your installation.

Prerequisites
	The system you choose to run the server portion of the Nameserver should meet the following requirements:
	1.	BSD UNIX or equivalent.  The server portion of the Nameserver has been run on a 4.3bsd system and an Ultrix 2.2 system.  4.3bsd is the preferred system.
	2.	The 4.3bsd syslog facility.  If you are not using a 4.3bsd system, you will either have to port the 4.3 syslog to your system (we have done this for ourselves in order to run the Nameserver on an Ultrix VAX), or change the calls to syslog within the Nameserver.
	3.	Disk space.  We use about 40 megabytes to hold our database (60,000 persons).  The Nameserver could be tuned to be somewhat less wasteful of space, if you care to do so.  In any case, you will need at least twice the disk space the database will eventually occupy in order to conveniently create the database.
	4.	Processor.  The running database causes minimal system load.  Building a database takes quite a few cycles, however; five hours on a fast super-mini the last time we built our database.  Fortunately, this need only be done when mass quantities of entries are to be added.
	The client software can be run without modification on bsd UNIX systems, HP-UX, or VAX/VMS.

Overview
	The CSO Nameserver is a relatively straightforward program to install.  There are four major pieces; the server program itself (qi), the client program (ph), database utilities (a set of programs used to build, dump, and otherwise manipulate the database), and statistics programs (that help make sense of the voluminous logs produced by the Nameserver).
	The basic plan for installation is:
	1.	Create a userid for the Nameserver, and become that user.
	2.	Untar the files.
	3.	Edit the configure script.
	4.	Run the configure script.
	5.	Make any binary directories you mentioned in the configure script.
	6.	Do a make install (as super-user).
	7.	Create a database.
	8.	Put an ns entry in /etc/services.
	9.	Teach /etc/syslog.conf about qi, and kick syslogd.
	10.	Teach /etc/inetd.conf about qi, and kick inetd.
	11.	Install the client software on any other system(s) you wish.
	The rest of this document will deal with each step in detail.

Creating A Userid For The Nameserver
	If you have a 4.3bsd system, you should create a userid for use by the Nameserver.  This userid should have sole access to the Nameserver database and the utility and server programs.  If you have a 4.2 bsd system, it is sufficient that the super-user have access to the database and related files (although it will do no harm to have a Nameserver userid that owns the Nameserver files).  The distinction is made because the 4.3bsd inetd networking daemon allows a userid to be specified for the programs it runs; the 4.2bsd inetd runs its programs as the super-user.
	If you create a Nameserver userid, you should become that userid for most of the installation process.

Untar The Files
	The Nameserver is normally distributed as a compressed tar archive.  The command:
uncompress -c <ph.tar.Z | tar xvf -
will uncompress and extract the files from ph.tar.Z, which can then be removed.  The following directories and files will appear in your current working directory:
Makefile
	The top-level makefile for the Nameserver.  This makefile mostly runs make in the various subdirectories.
configure
	This script is used to configure the Nameserver to run on your system.  This is done by editting the various Makefiles and installing proper definitions in them.  The configure script edits only some variable lines at the top of each Makefile, and qi/conf.c; it does not touch any other source code or the bodies of the Makefiles.
lintlint
	This file contains sed commands to delete unwanted complaints from lint output.
doc
	This directory contains various documents pertaining to the Nameserver.
include
	The NameserverUs #include files go here.
lib
	A few ubiquitous library functions.
ph
	The client program.
qi
	The server program.
stats
	Programs for dealing with the Nameserver log.
util
	Miscellaneous other goodies.  Thes programs build and dump the Nameserver database, as well as do other nifty little things.

See Appendix A for an explanation of each file in the subdirectories.

The configure Script
	The configure script will aid you in localizing the Nameserver for your site.  It does this in two ways; it edits the various Makefiles, inserting proper values for variables defining such things as C compiler flags, special #defines, etc.; it also edits qi/conf.c, a C source file that gives the locations of various important files (such as the Nameserver database).
	The configure script consists of three parts; the prologue, which you should edit; the code to change Makefiles; and the code to edit conf.c.  The prologue itself is in two parts; the first part, that sets variables for Makefiles; and the second part, that sets file names for qi/conf.c.
	In editing the prologue, bear in mind that the c-shell (csh) is going to be executing configure; be sure to protect things from the shell.  Also bear in mind that sed is going to be run;  you may have to experiment with the placement of quotes and escapes to get the results you want.  Never fear, however; you canUt break anything with configure that canUt be easily repaired with configure.
	Here are the variables in the prologue of config, along with example settings,  explanations of what they mean, and what you can do with them:
set mainbin=/usr/local/bin
	This is a directory where ph will be placed.  It should be in the search path of users.
set utilbin=/nameserv/bin
	This is a directory where the other binaries will be placed.  Woe is the system that lets the casual user execute these.
set otherlib=
	If there is a library that shoudl be appended to loader runs, put it here.  We use it to see that qi gets the 4.3 version of syslog(3) on our Ultrix system.
set otherlint=
	If you give this a value, you can help lint when dealing with the library you gave for otherlib.  This assumes you have a built a lint library for otherlib.
set cc=/bin/cc
	Your favorite C compiler.
set lint="/usr/bin/lint -u"
	How you care to invoke lint.
set ci='ci -q -l -m"No help here."'
	This will be invoked when you do a Rmake rcsS in any directory.  It will be given a list of files that probably need to have their revisions controlled.
set defs=(LOG_QILOG=LOG_LOCAL0)
	You can #define anything you want here.  If you give more than one word, put the words in parentheses, per shell syntax.  You should define LOG_QILOG to be the proper syslog facility number.
set depend=-M
	This should be the flag that cc should be given to generate a dependency list.  On most UNIX systems it is R-MS.  Ultrix requires R-EmS (donUt look at me...).
set host='\"garcon.cso.uiuc.edu\"'
	The host that the server program (qi) runs on.  This is used only by the client, ph.  (Note the RtrickyS use of quotes and escapes; the end result is a constant string in ph.c.)
set fallbackaddr=0x80ae053a
	The address of the aforementioned host, in case it canUt be found in host table or domain system.
set nsservice='\"ns\"'
	The name of the UNIX service that is the CSO Nameserver.
set fallbackport=105
	The port number to use if the aforementioned service is not found in /etc/services.
set admin='\"dorner@garcon.cso.uiuc.edu\"'
	The CSO Nameserver adminstrator.
set passw='\"nameserv@uxg.cso.uiuc.edu\"'
	The person who gives out CSO Nameserver passwords.
set lockfile=/nameserv/db/LockFile
	The lock file for the main database.  This file must exist for qi to run.
set tempfile=/tmp/qiXXXXXX
	Template for mktemp(3).
set fieldconfig=/nameserv/db/prod.cnf
	The file that describes the tagged fields used by the database.
set database=/nameserv/db/prod
	The prefix for the main database files.  The six suffices are .dir, .dov, .idx, .iov, .seq and .bdx.
set idlock=/nameserv/db/Id.Lock
	The lock file for the id database.  This file need only be present when the ssnid program is run.
set idfile=/nameserv/db/IdDB
	The prefix for the id database files.  The two suffices are .pag and .dir.  This database need only be present when the ssnid program is run.
	Running configure will install these definitions in the various Makefiles and qi/conf.c.  While it is running, configure will write on the standard output the name of the directory it is working on.  If there are any errors running configure, simply edit configure to fix the error, and run it again; it is not desctructive, nor is there any cleanup that has to be done after a partial run.  You may wish to set the echo flag (x) in the first line of configure to help you find errors.

Running Make
	Before discussing the actual installation of the Nameserver, let me digress into a discussion of the top-level (and the subdirectory) Makefiles.  They provide several standardized targets, in addition to the targets particular to each directory.  For the most part, running make at the top level will simply make the specified target in all the subdirectories; exceptions are noted below.  The standard targets are:
all
	Everything that needs to be compiled and loaded.  This is always the first target in the Makefile, so that a simple RmakeS has the same effect as a Rmake allS.  Note that this does not install the programs in their proper directories; it only compiles and loads them.
install
	Installs the programs in their proper binary directories.  This target has RallS as a dependency, so it will compile if necessary.
clean
	This removes everything but the source.  Object files, binary libraries, backup copies of Makefiles, compiled (but not installed) programs, etc.  Do a Rmake cleanS to save some disk space when you do not plan to be doing development on the Nameserver for a while.
depend
	This will add #include file dependencies to the Makefiles.
rcs
	This performs a checkin of all files that look like they have been changed since the last recorded checkin was done.
lint
	Runs lint on all the programs, and leaves the output in the file LINT in the subdirectories.  The Nameserver is not well-liked by lint, but I do make sure that there are no serious errors in it.  LintUs complaints about the Nameserver are just nits that do no real harm.  If you care to cast every occurrence of NULL to the proper pointer type, you may be my guest...  In the top-level directory, running make lint will first run lint in all the subdirectories, then cat the LINT files together and run them through the sed script lintlint, which removes a lot of lintUs unnecessary messages, and leaves the result in the file LINT in the top level directory.
tape
	First cleans the directory, then makes a tar archive out of the Nameserver.  This target is present in the top-lev el Makefile only.
print
	Prints the Nameserver source.  Be sure you have the Makefile variable PRINTER set to a program that knows how to print its standard input.  Top-level Makefile only.
	Running Rmake installS will compile, load, and copy into the binary directories all the programs that make up the Nameserver.  It does not create the directories, however; be sure you have done so before you run make install.

Create A Database
	This is the step for which I can give you the least help.  Read the document Rebuilding a Nameserver Database In 24 Easy Steps to see how I do it here at the University of Illinois.  You will probably be able to modify the procedures and programs used in our process to fit your own data and data formats.

Put An ns Entry In /etc/services
	The CSO Nameserver uses the same service name and port number (RnsS and 105) as the CSNET Name Server.  The /etc/services entry should be:
	ns              105/tcp         ns              # CSO  nameserver
This /etc/services entry should be present on the server machine as well as on any machine that will run the client program, ph.

Teach /etc/syslog.conf About qi
	As part of editing configure, you should have arrived at a choice for the syslog facility to be used for the Nameserver.  Enter the facility and a log file for it in your /etc/syslogd.conf:
	local0.warning;local0.info;local0.debug                 /nameserv/log
The Nameserver uses the INFO level for most messages; it uses WARN for errors that need prompt attention.
	You should now send an HUP signal to syslogd to make it reread its configuration file.
Teach /etc/inetd.conf About qi
	The server program, qi, is written to read from and write to standard input.  It relies on the network daemon inetd to listen for, make, and pass connections to it.  Therefore, you must enter the Nameserver in inetdUs configuration table, /etc/inetd.conf.  On a 4.3bsd system, you would have:
	shell   stream  tcp     nowait  nameserv  /nameserv/bin/qi  qi -d
On a 4.2bsd system, you should say:
	ns      stream  tcp     nowait  /nameserv/bin/qi        qi -d
Since there is a bug in some versions of 4.3bsd inetd, be sure to put the Nameserver entry before the first internal service in /etc/inetd.conf on a 4.3bsd system.		You should now send an HUP signal to inetd to make it reread its configuration file.

Install the Client
	The ph subdirectory may be copied to whatever machine you wish; a make install (and the proper entry in /etc/services) will suffice to make it run on the target system.  Note that ph requires no privilege at all, so no special userid is needed on a system that will run the client only.

Appendix AQNameserver Files

Figure 1. Directory Organization

doc:
Installation.macbin
	This WriteNow for the Macintosh document.
Introduction.macbin
	A WriteNow for the Macintosh document that provides a tutorial introduction to the client program, ph.
Description.wn.Bin
	A WriteNow for the Macintosh document that gives an overview of the CSO Nameserver.
Installation.wn.Bin
	A WriteNow for the Macintosh document which explains the Nameserver distribution and how to install the Nameserver.
Introduction.wn.Bin
	A WriteNow for the Macintosh document providing a tutorial for end users. 
Programmer.wn.Bin
	A WriteNow for the Macintosh document giving further guidance to the benighted Nameserver programmer.
Protocol.wn.Bin
	A WriteNow for the Macintosh document describing the protocol used by the CSO Nameserver.
Rebuild.wn.Bin
	A WriteNow for the Macintosh document describing how we rebuild our Nameserver database each semester.
Why.wn.Bin
	A WriteNow for the Macintosh document that explains the design process we used for our Nameserver.
Description.rtf
Installation.rtf
Introduction.rtf
Programmer.rtf
Protocol.rtf
Rebuild.rtf
Why.rtf
	These documents are Rich Text Format versions of their namesakes.
ph.1
	The ph manual page, ready for the man macros.
qi.8
	The qi manual page, ready for the man macros.

include:
Makefile
	This Makefile doesnUt shake the earth, since itUs in an include file directory, but it does know how to use rcs...
RCS
	RCSUed versions of the include files live here.
bintree.h
	Include file for programs using metacharacter-ful searches, or building the index required for such things.
commands.h
	Include file used by qi for definitions required when writing functions which implement Nameserver protocol commands.
db.h
	Include file for dealing with the Nameserver database and index.
field.h
	Include file for handling tagged fields.
ll.h
	Include file for linked lists (used only by a statistics program).
options.h
	Nameserver options defined.
qi.h
	General definitions for the server portion of the Nameserver.
replies.h
	Nameserver reply codes.

lib:
Makefile
	Need I say more?
RCS
	This directory has an obvious function.
anyof.c
	Contains a function that decides if any of the characters from one string appear in another string.
pmatch.c
	Contains functions that do globbing-style pattern matching.
str.c
	Various interesting and boring string functions.
strbuild.c
	Functions for building unlimited-length strings.
util.c
	Miscellaneous useful stuff.

ph:
Makefile
RCS
cryptit.c
	En,decrypting code.
ph.c
	The definitive Nameserver client.
replies.h
	Nameserver reply codes, reprised for the benefit of systems other than the server system.

qi:
Makefile
RCS
add.c
	The Nameserver RaddS command is implemented here.
auth.c
	User authorization functions.
bintree.c
	Functions to deal with the tree index to the Nameserver databaseUs hash table index.
change.c
	Functions implementing the Nameserver RchangeS command.
commands.c
	The top level of the Nameserver command interpreter, and miscellaneous trivial commands.
conf.c
	The locations of database and other files.
cryptit.c
	En,decrypting code.
dbd.c
	Functions that handle the database proper.
dbi.c
	Functions that handle the hash table index to the database.
dbm.c
	This file contains functions that deal with the database in toto; index and data.
field.c
	If you want to deal with tagged fields, come here first.
language.l
	Parser for the Nameserver protocol.  Lex this.
lock.c
	Controls advisory locks on the database.
lookup.c
	Give the functions in this file a list of index entries, and theyUll give you the entries that are implied.
phoneme.c
	Some phonetic code that isnUt too impressive for the NameserverUs purposes, and is currently unused.
qi.c
	The serverUs main lives here, along with other minor details.
query.c
	This file implements the Nameserver query command, including validation and post-index matching.
rules.c
	More defunct phonetic code.
set.c
	If you want to set an option, youUll wind up in this file.
version.c
	Check this in if you want the NameserverUs version number to change.

stats:
Makefile
RCS
follow.c
	This program reads the Nameserver log, and RfollowsS any Nameserver session that matches the given pattern.
hour.awk
	Awk script that figures out when people use the Nameserver, from the Nameserver log.
ll.c
	Linked list handling functions (used by follow.c).
phstats
	Performs reductions on the Nameserver log, and gives statistics on what hosts use the Nameserver, how many times they use it, when the Nameserver is used, and what the command mix is.
qicmds.awk
	Awk script that tallies commands from the Nameserver log.
qiuse.awk
	Awk script that preprocesses the Nameserver log for qiuse.
qiuse.c
	Program that figures out the names of hosts that use the Nameserver.

util:
Makefile
RCS
alias.awk
	Awk script that assigns Nameserver alia to those who have none.
aliasprepare.c
	Prepares a Nameserver database dump for alias.awk.
border.c
	Reverses byte order in a Nameserver database; used to move a database from a normal machine to a VAX.
build.c
	Builds the bintree index to the Nameserver database.
credb.c
	Creates a new, empty, Nameserver database.
emailp
	Processes the output qi produces when given a massaged /etc/passwd file.
f.pb.c
	Program that interprets the University of Illinois staff data tape.
id.c
	Functions that deal with the dbm(3) database of University IdUs.
maked.c
	Program that makes a .dir file (Nameserver database) out of an ascii data file.
makei.c
	Functions for the initial creation of the Nameserver hash table index.
maket.c
	Functions that aid build in making the bintree index to the hash table.
mdump.c
	Program that dumps the Nameserver database in ascii form onto standard output.
s.pb.c
	Program that deals with the University of Illinois student data tape.
ssnid.c
	Program that uses id.c to assign random idUs to Nameserver entries.
stastu.c
	Program that merges the staff and student ascii data files.
tmerge.c
	Program that merges a database dump with new data.