IInnssttaalllliinngg tthhee CCCCSSOO NNaammeesseerrvveerr by Steven Dorner s-dorner@uiuc.edu Computer and Communications Services Office University of Illinois at Urbana March 4, 1992 updated by Paul Pomes paul-pomes@uiuc.edu 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.