How to install HyperWave by use of the tar-files

Gerald Pani, Helmut Leitner Version 1.00 June 27, 1996

1 Introduction

This document describes how to obtain and install the HyperWave server software (binaries) by use of the HyperWave distribution tar-files.

Note: To get the full functionality of the HyperWave Server you have to register your server.

We provide this special installation variant for people that cannot use our installation script; for instance, the server machine may be behind a firewall and only FTP to the outside world is allowed. Although HyperWave can be installed from tar-files we strongly recommend the use of the HyperWave install script (hginstserver) if possible, especially for updating the server. Further information concerning HyperWave server software update and a short introduction to HyperWave server administration is contained in Download HyperWave Software.

Should you experience problems connecting to ftp.iicm.edu, the /pub/Hyper-G directory is mirrored nightly to the following hosts.

If you have questions or comments about this document, please feel free to mail hgsupport@iicm.edu. We welcome any suggestions, criticism, or postcards. If you find a mistake within this document, please let us know so we can correct it in the next version.

Thanks.

2 HyperWave Server Software Tar-file

To operate a HyperWave server you must have one of the following machines and operating systems:

SUN Sparc (under SunOS 4.1.3 or Solaris 2.4 or above)
HP 700 series (under HPUX 9.05 or above)
DECstation (under Ultrix 4.4 or above)
SGI (under IRIX 5.3 or above)
DEC Alpha (under OSF/1 3.2)
IBM PC compatibles (under Linux 1.2.13-a.out)
IBM PC compatibles (under Linux 2.0.x-ELF)
IBM PC compatibles (under FreeBSD 2.1.0-RELEASE)
IBM (under AIX 4.1)

Now, for each supported architecture the software distribution consists of several compressed tar-archives; for instance, the tar-files for Silicon Graphics machines are:

HyperWave_Server_21.11.95.IRIX-5.3.tar.gz
HyperWave_Server_beta_21.11.95.IRIX-5.3.tar.gz
HyperWave_Tools_21.11.95.IRIX-5.3.tar.gz
HyperWave_Tools_beta_21.11.95.IRIX-5.3.tar.gz

The tar-files contain:

HyperWave_Server_...: core HyperWave server software (database server, document cache server, fulltext server, ...)
HyperWave_Server_beta_...: Beta-test versions of the programs listed above
HyperWave_Tools_...: several tools necessary to operate and administer a HyperWave server (administration tools, import- and export tools, the Hyper-G Terminal Client, ...)
HyperWave_Tools_beta_...: Beta-test versions of the tools mentioned above

The "date" in the tar-file names correspond to the creation date of the tar-files.

IMPORTANT:For a complete HyperWave server installation you will need both a "HyperWave_Server_..." and a "HyperWave_Tools_..." tar-file!!!

3 Space requirements

The HyperWave server software itself consumes about 50 MB (depending on your platform). In addition, you will need enough space for the documents you are planning to serve. Double the space for text documents (required for the full text index), and add an extra 500 bytes overhead per document. For example, if you are going to serve 50,000 text documents of 1K each, plus 1000 images of 100K each, this sums up to 50,000 * 1K * 2 + 1,000 * 100K + 51,000 * 0.5K = 225.5 MB. Allow more if you have lots of links between documents. In addition, you will need some free space for logfiles, temporary files, etc. Your mileage may vary!

4 Installing the HyperWave Server (core server software and tools)

The HyperWave Server is distributed in binary form, and is available for the platforms mentioned above. In order to install the software, you need to have root (super-user) privileges. However, once it is installed, the server could and should run as an ordinary UNIX user. First you may perform the following steps (you need root privileges to do this):

Create a new UNIX user the HyperWave server software will run as (say, hgsystem) and optionally a user group (say, hyperg). Put the home directory of this user on a file system with enough room (see "Space Requirements" above) and give it a standard C-shell (/bin/csh) or an enhanced version of the C-shell (/bin/tcsh).
Create a directory /usr/local/HyperWave with owner hgsystem and 0755 mode. This is the system-wide place for HyperWave configuration files, documentation, etc. You don't need much room on the file system of this directory, as symbolic links to the actual places (in the home-directory of hgsystem) will be generated. If you prefer another system-wide "entry point" to HyperWave you can define the environment variable HYPERWAVE_HOME in ~hgsystem/.cshrc:
```
setenv HYPERWAVE_HOME <directory>
```
/usr/local/HyperWave will then replaced by directory as the location where these links will be generated. If neither /usr/local/HyperWave exists nor HYPERWAVE_HOME is defined no links will be created at all.
Install Perl (a popular script language) on the machine (your system administrator should have done this anyway). The Perl interpreter must either be in the standard place (/usr/local/bin/perl), or its actual location must be in the path variable. If you don't have Perl yet, it can be downloaded by anonymous ftp from prep.ai.mit.edu (and many other sites) in /pub/gnu/perl5.000.tar.gz
Download the HyperWave_Server_... and the HyperWave_Tools_... tar-file for your requested server machine from ftp.iicm.edu or from one of the mirror sites (please use a ftp-site most suitable to your "internet location"). For example: If you want to install the beta version for a SUN Sparc with the Solaris operating system installed you have to download the following tar-files: HyperWave_Server_06.09.96.Solaris-2.4.tar.gz HyperWave_Tools_06.09.96.Solaris-2.4.tar.gz
After having downloaded the tar-files, make sure you are identified as user hgsystem and your current working directory is hgsystem's home directory (~hgsystem). Since the archives are in compressed form, untar each of them by executing the command:
```
gzip -dc <archive file name> | tar xvpf -
```
The tar-files will be expanded in the subdirectory "tartmp" of hgsystem's home directory.
Having unpacked the archives start the installation script executing the following command:
```
tartmp/hginsttar
```
The first time the script is run it will ask you a series of questions and create a file .hgrc in ~hgsystem (user hgsystem's home directory) and modify .cshrc so that .hgrc is included at the end of .cshrc. In .hgrc a number of environment variables are defined (you may edit this file after the installation has completed), including:
CPU

Your Platform (SUN4, SUN5, PMAX, HPUX9, SGI, etc.)

PATH
```
~hgsystem/bin/scripts ~hgsystem/bin/$CPU
```
is prepended to the existing path
DIRdbs

The directory where the low-level database server puts its files (default ~hgsystem/server)

DIRfts

The directory where the full-text server puts its files (default ~hgsystem/ftserver)

DIRdcs

The directory where the document cache server puts its files (default ~hgsystem/dcserver)

DIRhgs

The directory where the HyperWave server puts its files (default ~hgsystem/hgserver)

DBHost

Name of the machine where the low-level database engine runs on (hostname of your machine)

HGHOST

Name of the machine where the HyperWave server runs on (hostname of your machine)

OFFHOSTNAME

Fully qualified domain name of your server machine, i.e., the name you want your machine to be known from the outside. This is used by gopher and WWW gateways when they are sending out gopher menus and URLs
The script will also create the directories HTML, bin, bin/scripts, bin/$CPU, contrib, hgserver, dbserver, ftserver, dcserver, sgml, samples, doc, and man under ~hgsystem, with appropriate access permissions. It will also create symbolic links to these directories from /usr/local/HyperWave (if /usr/local/HyperWave exists and write access is granted; if the environment variable HYPERWAVE_HOME is defined the directory as specified by HYPERWAVE_HOME is used instead of /usr/local/HyperWave; see step 2 above).
After the previous steps (that are only necessary when installing for the first time) the binaries, scripts and configuration files for your platform are installed in the correct directories. The directory ~hgsystem/tartmp is not used anymore and can be removed to save diskspace.
Have the system administrator compile ~hgsystem/samples/hgbindport.c and put it to ~hgsystem/bin/$CPU/hgbindport owned by root and with the setuid bit set (mode 04755). This little program is used to obtain the privileged port numbers 418 (Hyper-G), 70 (Gopher) and 80 (WWW), and pass the openfile descriptors to another program that does not have root privileges. The program is delivered in source form so that the system administrator can check that it does not do nasty things as root. hgbindport opens a (system) port as file descriptor 3, changes its user id to hgsystem (the user who has invoked this command), and then exec's the appropriate program (e.g., gophgate). gophgate recognizes the open file descriptor and uses it automatically, instead of opening a port of its own. The effect of this is that (after the installation of hgbindport) you don't need root privileges to start the gopher and WWW gateways, and the HyperWave server. It therefore makes the system more secure (people don't have to trust the gateways etc.; they are started as ordinary user).

5 Starting the Server

Once you have done this, you are all set to start your HyperWave server. You may do so at any time by issueing the command dbstart (located in ~hgsystem/bin/scripts) as user hgsystem. If you want to stop the HyperWave server you may perform this by issueing the command dbstop. However, in order to keep the HyperWave server running all the time, you should add the following lines to your boot script (e.g., /etc/rc.local):

# Start HyperWave Server
if [ -f <home_of_hgsystem>/bin/scripts/dbstart];
  then echo 'Starting HyperWave Server' >/dev/console su -
  hgsystem <home_of_hgsystem>/bin/scripts/dbstart
fi

This starts the HyperWave server control script (that fires off the individual server components) as user hgsystem. You may want to change the default port numbers of the Gopher gateway (port 70) or the WWW gateway (port 80) to other port numbers (e.g. if you would like to run both the WWW server and the HyperWave server on the same system). In such cases you should edit the file ~hgsystem/.db.contr.rc (see dbserver.control) and then stop and restart the HyperWave server. You may verify that the server is running by connecting to it using any command line tool, e.g., hginfo -oid 2. You also may wish to install Harmony, the UNIX/X11 client for HyperWave, if you have not done this already. Look under the Hyper-G/Harmony ftp directory to find out how to install Harmony on your machine.

6 Installing the HyperWave Server Tools

You may wish to install the HyperWave Server Tools on other machines than your server machine, too (all the tools are client-server applications and can work with your HyperWave server). The installation procedure is very similiar to the steps described in section 4, except that steps 1) and 2) and 7) are not necessary.

7 Updating the HyperWave server software

You have a choice between two different methods to update HyperWave server software on your system:

automatic download, installation and update using the HyperWave installation script hginstserver
update installation from a tar file

Although HyperWave can be updated from a tar file we strongly recommend the use of the HyperWave install script if possible. We provide the "tar-file" installation variant for people that cannot use our installation script (server machine may be behind a firewall, slow network connection to iicm.edu).

For a description of hginstserver look at hginstserver.1

This document describes the update procedure by use of the HyperWave distribution tar-files.

Download the HyperWave_Server_... and/or the HyperWave_Tools_... tar-file for your requested server machine from ftp.iicm.edu or from one of the mirror sites (please use a ftp-site most suitable to your "internet location").
For example: If you want to update the beta version of the HyperWave tools for a SUN Sparc with the Solaris operating system installed you have to download the following tar-files: HyperWave_Tools_....tar.gz
After having downloaded the tar-file(s), make sure you are identified as user "hgsystem" and your current working directory is hgsystem's home directory (~hgsystem). Since the archives are in compressed form, untar each of them by executing the command:
```
gzip -dc <archive filename> | tar xvpf - 
```
The tar-files will be expanded in the subdirectory "tartmp" of hgsystem's home directory.
Having unpacked the archives start the installation script executing the following command: tartmp/hginsttar. When updating the HyperWave software the only parts of the server/tools that are installed are those that need to be replaced. The changes come in effect the next time you restart the server. hginsttar also takes parameters controlling the way the updates are installed: -h prints online help information. -confirm confirm installation of updated files. In this case the script will ask for confirmation for all files that need updating. Answers to these questions can be "y" (yes) or "n" (no) or "c" (only get changelog for this file but do not install). -changelog create a changelog file named hginsttar.log showing all changes of the updated version compared to the previously installed version. -nochanges do not update the installation; this is only useful with option -changelog.

8 Further Documentation

A number of research papers are available that go into details of HyperWave's design philosophy. In directory papers you will find electronic versions of some of them. If you have never heard of HyperWave before, we suggest you first look at files report388.ps* in that directory. We also suggest you to read the documentation on the HyperWave Server Manager to install, uptdate and manage the HyperWaver Server using a graphical user interface.

This document does not describe HyperWave clients. Information on Harmony, the UNIX/X11 client for HyperWave, can be found in Download HyperWave Software. Documentation on Amadeus, the PC/MS-Windows client, is also available there. The protocol definition is contained in Hyper-G Client/Server Protocol (HG-CSP), which is only of interest if you plan to write your own HyperWave clients or tools that interface with the server directly.