%
% Copyright (c) 1996 Bunyip Information Systems Inc.
% All rights reserved
%
% Archie 3.5
% August 1996
%
% install.tex
%

\chapter{Installing the basic Archie system}
\label{chap:install}

This section will guide you through the process of installing the Archie
software on your system. With an understanding of the overall Archie system
architecture, as presented in chapter~\ref{chap:overview}, we will then proceed
to the configuration of the system.


\section{Archie system space requirements}


Choosing a location for the Archie system on your file system depends
on the databases that you intend to maintain. We estimate that a complete
{\bf anonftp} catalog (covering about 1200 archive sites) requires
between 600 and 1000 megabytes. In the case of a {\bf webindex} catalog,
the space requirements are as much as possible!  

To help decide on the location of the Archie system, let's take a look
at the directory structure that will be created once the distribution
is unpacked.

\begin{center}
\begin{tabbing}
Directory/file pathname\hspace*{5mm}\= Purpose \\
\\
archie/ \> Archie system home directory \\
archie/cgi \> CGI related directories \\
archie/cgi/bin \> CGI binaries \\
archie/cgi/html \> HTML files \\
archie/contrib/ \> public domain and third-party software \\
archie/config/ \> installation configuration \\
archie/bin/ \> system binaries and shell scripts \\
archie/db/ \> Archie database home directory \\
archie/db/anonftp\_db/ \> anonymous FTP catalog files \\
archie/db/webindex\_db/ \> WWW catalog files \\
archie/db/host\_db/ \> host database files \\
archie/db/locks/ \> directory for lock files \\
archie/db/tmp/ \> temporary or ``holding'' directory for data files \\
archie/doc/ \> system documentation \\
archie/etc/ \> system configuration files \\
archie/help/ \> Archie client help directories and files \\
archie/logs/ \> system log files \\
archie/logs/archie.log \> main Archie system log file \\
archie/logs/email.log \> log file for email client (if installed) \\
archie/manpages/ \> Archie system manual pages \\
archie/pfs/ \> Archie/Prospero system home \\
archie/pfs/bin/ \> Archie/Prospero binaries \\
archie/pfs/pfs.log \> Prospero log file  \\
\end{tabbing}
\end{center}

The directories \Path{db/tmp}, \Path{db/anonftp\_db} and
\Path{db/webindex\_db} will likely use the most space. Previous versions of
the Archie system required that those directories be part of the same disk
partition. The current version removes that restriction. \new The only
limitation still present, in this version, is the requirement that
\Path{db/tmp}  and 
\Path{etc} still be in the same partition. The catalog directories may reside in
separate partitions.



%
% Archie user codes 
%

\section{Archie user codes}


Two user codes need to be created to enable Archie system operation and
maintenance. The first, called {\it archie}, is used for non-administrative
access to the Archie system (e.g., for accepting user queries to the Archie
databases). The second, called {\it archuser}, is for system maintenance by
the Archie system administrator. The password file entries for these two users
should specify, in the home directory field, the full path to the root of the
Archie system. The password file entries for these two codes also should meet
the following requirements:


\begin{itemize}

\item
both codes must have the same UID (User ID) number

\item
NEITHER code should have any special privileges, such as belonging to the
wheel or staff groups

\item
the archie user code must appear {\it before} the archuser code in the password
file

\item
the archuser code should have whatever shell you normally use (e.g.
/bin/csh or /bin/ksh)

\item
the archie user's shell field should be set to /bin/false for the time
being. This will be changed if a telnet client is installed
(See ``Setting up the anonftp catalog clients'' on page~\ref{chap:clients}.)

\item
the password field for archie should be set to asterisk (`*') for now. This
will be changed if you install the Archie telnet client
(See ``Setting up the anonftp catalog clients'' on page~\ref{chap:clients}.)

\item
The password field for the archuser code should be set to one of your choosing

\item
The \Path{/etc/group} file must be modified to create a group named ``archie''
for the Archie user codes. For example:

\texttt{archie:*:1000:archie,archuser}

\item both codes must have the same GID (Group ID) number in the password
file, and this must be the number, set above, for the archie group.

\end{itemize}

Thus, an example of the entries in the \Path{/etc/passwd} file is:

\texttt{archie:*:23:1000:archie client code:/usr/local/archie:/bin/false}

\texttt{archuser:ufUn9Ap.:23:1000:archie admin code:/usr/local/archie:/usr/bin/csh}


If you are using the Network Information System (NIS) you should only need to
add the above entries to the /etc/passwd file for the local Archie host, not
for the entire NIS system.

\alertbox{The naming convention of \archie \ or \Path{\Archie}
is used here to specify the home directory of the Archie system.}





%
%
%

\section{Unbundling the distribution}

This new version of Archie contains not only a new set of binaries and a new
catalog, but certain elements, internal to the system, also have been modified.
If you already have an existing Archie installation, the catalogs will
have to be rebuilt. \new Fortunately, you can convert the existing host\_db database
to the new format.

\alertbox{If you are upgrading your software from version 3.3 and want to
save the host database, you will need to make a backup copy of the directory
\Path{\archie/db/host\_db}. Be sure to read section~\ref{ndbm} before
proceeding with this.


Once you have installed all the software, restore the host database
then run the program \Path{convert\_hostdb}, as follows:

\comm{convert\_hostdb}

The new host database will then be converted and will contain only
those sites for which you are responsible (i.e. that you retrieve).
}
\new 


First start by FTPing the distribution from ftp.bunyip.com. In the directory
archie-\version \ you will find the files that need to be retrieved.

\begin{itemize}
\item archie-\version-install.tar 
\item archie-\version-arch-version.tgz 
\item archie-\version-arch-version-A.tgz 
\item archie-\version-arch-version-B.tgz
\end{itemize}

where ``arch-version'' is one of: `sunos-4.1.4', `sunos-5.4', or `aix-3.2'.

Untar `archie-\version-install.tar' with the command:

\comm{tar xvpf archie-\version-install.tar}

There you will find three scripts that will be used to install the binaries,
`unwrap', `untar', and `unrotate'.  The single command, `unwrap' should take
care of installing the binaries and other files.


To install the server software, as superuser, type:

\comm{./unwrap}

and follow the instructions. As indicated by the script, you need to
set the correct permissions. If you want to install the Archie man pages
in a system-wide area, read the next section. As superuser type:

\comm{cd \archie/config}

\comm{make}



This will change the permissions of the files in the Archie system to the
appropriate values, as well as install the manual pages into the directory
specified above.

In addition, a symbolic link will be created from the root directory pointing
to the Prospero tree. Typing

\comm{ls -al /pfs}

will show you the link and the directory to which it points. It will look
similar to:

\param{lrwxrwxrwx 1 root 33 Mar 2 23:28 /pfs -$>$ /usr/local/archie/pfs}



It is suggested that the installation and configuration be performed as the
user archuser except for those changes that must be made as the superuser.



%
% Man pages 
%

\section{Manual Pages}

The on-line manual pages are, by default, configured to be installed in the
Archie man directories \Path{\archie/man}.
However, you may opt to install the man pages in a different location,
as described below.

First
\Path{cd \archie/config} and edit the file
\Path{Makefile}. Modify the line:

\path{MAN=../man}

to be the name of the directory where you would like the Archie system
manual pages placed, if it is different from the existing location.

Change the line:

\path{MANEXT=n}

to reflect the manual page name extension for that directory.

For example, if you wanted to store the Archie manual pages with the system
man pages, you could change the appropriate lines, as follows:

\path{MAN=/usr/man/mann}

\path{MANEXT=n}



If the manual pages are placed anywhere other than your system's default manual
directories, you may have to change your UNIX environment variable MANPATH to
reflect the changes. Otherwise, the \Path{man} command will not find the Archie
manual pages.



\section{ndbm and Berkeley DB files}
\label{ndbm}
\new

In the previous versions of Archie, ndbm files were used to maintain certain
information on hosts etc. It, now, uses Berkeley DB library to construct and
maintain those databases.  These files have extension \Path{.db}.

%
% Congratulations
%

\section{Done !}

You have now finished the initial installation of the Archie system. The next
section  will describe how to configure the system. You may want, first,
to reread the overview section~\ref{chap:overview} to understand the different
aspects of Archie.






