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


\Chapter{Managing the Host Information Files}
\label{chap:hostmanage}


The curses(3X) based program, host\_manage, allows the Archie administrator to
examine and/or change the contents of the Host Information files. These
activities include the addition and deletion of Data Hosts, as well as
providing information about specific catalogs that are updated from the Data
Host sites. Invoked as:

\comm{host\_manage [<site name>]}

it will display the information about the given \Param{<site name>}, or the
first entry in the Host Information File (alphabetically sorted) if no
\Param{<site name>} is given. The screen display is illustrated below.

\begin{center}
\begin{verbatim}
Primary hostname: blizzard.cc.mcgill.ca
Preferred hostname: www.mcgill.ca
Databases: webindex 
Operating System: Unknown                     Prospero Host: No 
Primary IP address: 132.206.27.11             Timezone: -5:00 


Database: webindex


Source: archie.bunyip.com                      Generated by: insert
Retrieve time: 19:02:34 31 Mar 1996 EST        Number of records: 136
Parse time: 17:06:00 25 Apr 1996 EST
Update time: 05:47:23 26 Apr 1996 EST          Fail count: 0


Msg:


Port: 80                                       Path:

Current status: Active
Force Update: No
Action: Update
\end{verbatim}
\end{center}



The commands for editing the information are based on the standard emacs key
bindings. These will be configurable in a future release of the system.

The configuration file associated with the host\_manage program is
\archie/etc/hm\_db.cf. It describes how the various catalog-specific
information is to be displayed on the screen. Currently, the default file
handles anonftp and webidnex catalog entries. This file need not change
unless you add new catalogs.

Many of the fields displayed by the program are informational only and may not
be modified directly by the Archie administrator. Others may be modified, but
have a restricted range of values (such as the Operating System value). In all
cases, the information given by the Archie administrator is verified against
the existing information file, as well as the Domain Name System. Any errors
that are encountered will be indicated.



Only the major functions of the program are described in detail below. For
full details on how to configure and use host\_manage, please see the manual
page entry.



\alertbox{There is a known problem with the host\_manage program in its interaction with
certain terminal types, particularly xterms. This can be fixed by removing the
``me'' attribute in the distributed /etc/termcap entry for the affected
terminals. For example, in the xterm entry remove the string:

\param{:me=\symbol{92}E[m:}


So far, to our knowledge, this fixes the problem on all terminal types.}


\section{Adding individual Data Hosts}
\label{sec:addhost}

The easiest way to add an individual Data Host to the Host Information Files
is to use the host\_manage program. Adding a site to the database is a
straightforward operation.



\alertbox{Quite often, someone will request that you add a site, and will
specify the name as something like ftp.xxx.yy.zz. This name is probably not
the primary hostname, but rather an alias for the primary hostname. The
host\_manage program requires that the host be stored under the primary
hostname, with an optional preferred hostname.}



Use the various DNS tools, such as host, nslookup, or nstest to determine the primary
name before proceeding. In general, we recommend that you check all names
before starting.

Using host\_manage, do the following:

\begin{itemize}
\item Hit the \Param{<TAB>} key, to bring up the Host Database Modification Menu.

\item select item ``Add a site to the host database''.

\item The message Add site will appear at the bottom of the screen and a blank
template will be displayed.

\item Fill in the various fields:

\begin{itemize}
\item Primary hostname must contain the primary (``canonical'') name of the
host. 

\item Preferred hostname can be the alternate name of the host, typically an
alias of the primary name. Leave this blank if none is desired.

\item Operating System. This field is used by the parser. Currently only three
values are possible. Hitting the spacebar cycles through these. If
the site is not a VMS site, select Unix BSD.

\item Prospero Host. Leave this as ``No''. This is reserved for future releases.

\item Timezone. An optional field specifying the offset, from GMT, of the host being
entered.

\item Database. The name of the catalog that you are entering for this host.
This would normally be anonftp or webindex. Note that you can only add one
database at a time.

\item Access commands. Leave blank for the moment.

\item Current Status. This field holds three values:

\begin{itemize}
\item Disabled. This host is not polled.

\item Active. This host is actively being polled.

\item Inactive. The host is not in the database at the moment.

\item Not Supported. The host is currently unsupported for one reason or
another (e.g. because of an incompatible operating system).

\item You will probably want to enter the host as ``Active''. Again just hit the
space bar to cycle through the possible values.
\end{itemize}

\end{itemize}

\item When you are satisfied with your entries, type \Param{<Cntl-U>}. The
system will ask you if you want to update the site, and then if you want to update
the database. Answer ``y'' to both questions.

\item The site has now been added and will be indexed during the next Update 
Cycle.
\end{itemize}

\section{Deleting a Data Host}
\label{sec:delhost}

Before a site can be removed from the Host Database of the Archie system, all
catalogs tracked on that host must be scheduled for deletion.

Using host\_manage, do the following:

\begin{itemize}
\item Find the site you want to delete by filling in the Primary Database field
then, typing the \Param{<return>} key.

\item Hit the \Param{<TAB>} key to bring up the Host Database Modification
Menu, then select the number corresponding to the entry ``Delete an Archie
database from current site''.

\item You will be asked if you want to delete the current database. Answer ``y''.

\item The system should then report the message ``Database \Param{<x>}
scheduled for deletion'', where \Param{<x>} is the current catalog selected
and displayed on the line ``Database:''. The ``Current status'' line for that
catalog will now display ``Marked for deletion by Archie administrator''.

\item Repeat the procedure for all the catalogs for which this site is being
polled. You can see this list by consulting the ``Databases'' field.

\item Once you've marked all the catalogs for deletion, you will have to wait
until the next Update Cycle runs, when all catalog entries for that site will
be purged.

\item As each catalog is removed from the system, the ``Current status'' line
will display ``Deleted''.

\item Only once this is done can you remove the site, from the Host Databases,
using the ``Delete a site from the host database''. The site will then be
physically removed from the Host Databases.

\end{itemize}


Often a site will offer multiple services, such as anonymous FTP and webindex.
It is possible to add multiple catalogs for the same site with
the following steps: \new

\begin{itemize}
\item Go to that site by typing in its name in the primary\_name field.
\item Hit \Param{<TAB>} and select \Param{``3. Add an archie catalog to current
site''}.
\item Fill in the information and update with \Param{<Cntl-U>}.
\end{itemize}


\section{Forcing an early update}

If, for whatever reason, you would like a particular site to be inspected
before it normally would be scheduled, use the Force Update function of the
Host Modification Menu in host\_manage.

This will cause the particular Data Host/catalog pair to be retrieved and
processed during the next Update Cycle, if it conforms to the domain and
catalog restrictions of that Retrieval Phase. That is, this feature only
overrides the time of the update, not the type.

\section{And now the catalogs...}

Now that we know how to look at the information stored in the Host Databases
we can start to look at configuring individual catalogs.



