How to install Hyper-G by use of the tar-files ============================================== Gerald Pani Helmut Leitner Version 0.90 November 22, 1995 1 Introduction ============== This document describes how to obtain and install the Hyper-G server software (binaries) by use of the Hyper-G distribution tar-files. 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 Hyper-G can be installed from tar-files we strongly recommend the use of the Hyper-G install script (hginstserver) if possible, especially for updating the server. Further information concerning Hyper-G server software update and a short introduction to Hyper-G server administration is contained in the HOWTO file (ftp://ftp.iicm.tu-graz.ac.at/pub/Hyper-G/Server/HOWTO). Should you experience problems connecting to ftp.iicm.tu-graz.ac.at, the /pub/Hyper-G directory is mirrored nightly to the following hosts: Australia ftp://ftp.cinemedia.com.au/pub/Hyper-G Austria ftp://ftp.tu-graz.ac.at/pub/Hyper-G Germany ftp://elib.zib-berlin.de/pub/InfoSystems/Hyper-G ftp://ftp.ask.uni-karlsruhe.de/pub/infosystems/Hyper-G Italy ftp://ftp.esrin.esa.it/pub/Hyper-G Spain ftp://ftp.etsimo.uniovi.es/pub/Hyper-G Sweden ftp://ftp.sunet.se/pub/Networked.Information.Retrieval/Hyper-G New Zealand ftp://ftp.cs.auckland.ac.nz/pub/HMU/Hyper-G UK ftp://unix.hensa.ac.uk/mirrors/Hyper-G USA ftp://ftp.ncsa.uiuc.edu/Hyper-G ftp://ftp.utdallas.edu/pub/Hyper-G If you have questions or comments about this document, please feel free to mail Gerald Pani (gpani@iicm.tu-graz.ac.at) or Helmut Leitner (hleitner@iicm.tu-graz.ac.at). 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 Hyper-G Server Software Tar-files =================================== To operate a Hyper-G server you must have one of the following machines and operating systems: - SUN Sparc (under SunOS 4.1.3 or Solaris 2.2 or above) - HP 700 series (under HPUX 9.01 or above) - DECstation (under Ultrix 4.2 or above) - SGI (under IRIX 3.0 or above) - DEC Alpha (under OSF/1) - IBM PC compatibles (under Linux) The following platform is likely to be supported in the near future: - IBM (under AIX) Now, for each supported architecture the software distribution consists of several compressed tar-archives; for instance, the tar-files for Silicon Graphics machines are: Hyper-G_Server_21.11.95.SGI.tar.gz Hyper-G_Server_beta_21.11.95.SGI.tar.gz Hyper-G_Tools_21.11.95.SGI.tar.gz Hyper-G_Tools_beta_21.11.95.SGI.tar.gz The tar-files contain: - Hyper-G_Server_...: core Hyper-G server software (database server, document cache server, fulltext server, ...) - Hyper-G_Server_beta_...: Beta-test versions of the programs listed above - Hyper-G_Tools_...: several tools necessary to operate and administer a Hyper-G server (administration tools, import- and export tools, the Hyper-G Terminal Client, ...) - Hyper-G_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 Hyper-G server installation you will need both a "Hyper-G_Server_..." and a "Hyper-G_Tools_..." tar-file!!! 3 Space requirements ==================== The Hyper-G 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 Hyper-G Server (core server software and tools) ================================================================ The Hyper-G 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): a) Create a new UNIX user the Hyper-G 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). b) Create a directory /usr/local/Hyper-G with owner hgsystem and 0755 mode. This is the system-wide place for Hyper-G 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 Hyper-G you can define the environment variable HYPERG_HOME in ~hgsystem/.cshrc: setenv HYPERG_HOME /usr/local/Hyper-G will then replaced by as the location where these links will be generated. If neither /usr/local/Hyper-G exists nor HYPERG_HOME is defined no links will be created at all. c) 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/perl-4.036.tar.gz or /pub/gnu/perl5.000.tar.gz d) Download the Hyper-G_Server_... and the Hyper-G_Tools_... tar-file for your requested server machine from ftp.iicm.tu-graz.ac.at 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: Hyper-G_Server_beta_21.11.95.SUN5.tar.gz Hyper-G_Tools_beta_21.11.95.SUN5.tar.gz e) 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 | tar xvpf - The tar-files will be expanded in the subdirectory "tartmp" of hgsystem's home directory. f) 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. DIRServer: 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). DBHost: Name of the machine where the low-level database engine runs on (hostname of your machine). HGHOST: Name of the machine where the Hyper-G server runs on (hostname of your machine). GOPHHOST: 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. HGServerString: String describing this server (e.g., "University of Somewhere, SomeCity, SomeState"). Please use a reasonable name since this is how your Hyper-G server will be known to the world. This name is displayed by various clients! The script will also create the directories HTF, HTML, bin, bin/scripts, bin/$CPU, contrib, server, 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/Hyper-G (if /usr/local/Hyper-G exists and write access is granted; if the environment variable HYPERG_HOME is defined the directory as specified by HYPERG_HOME is used instead of /usr/local/Hyper-G; see step b) 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. g) Let 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 Hyper-G 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 Hyper-G 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 Hyper-G server you may perform this by issueing the command dbstop However, in order to keep the Hyper-G server running all the time, you should add the following lines to your boot script (e.g., /etc/rc.local): # # Start Hyper-G Server # if [ -f /bin/scripts/dbstart ]; then echo 'Starting Hyper-G Server' >/dev/console su - hgsystem /usr/local/Hyper-G/bin/scripts/dbstart fi This starts the Hyper-G 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 Hyper-G server on the same system). In such cases you should edit the file ~hgsystem/.db.contr.rc and modify the numbers of or appropriately (e.g., for running the WWW gateway on port 8000 change the line 80 to 8000) and then stop and restart the Hyper-G server. If you don't want these gateways running at all just set the port number of that gateway to zero (e.g., 0). You may verify that the server is running by connecting to it using the terminal client (just start hgtv). You also may wish to install Harmony, the UNIX/X11 client for Hyper-G, 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 Hyper-G Server Tools ===================================== You may wish to install the Hyper-G Server Tools on other machines than your server machine, too (all the tools are client-server applications and can work with your Hyper-G server). The installation procedure is very similiar to the steps described in section 4, except that steps a) and b) and g) are not necessary. 7 Updating the Hyper-G server software ====================================== You have a choice between two different methods to update Hyper-G server software on your system: - automatic download, installation and update using the Hyper-G installation script "hginstserver" - update installation from a tar file Although Hyper-G can be updated from a tar file we strongly recommend the use of the Hyper-G 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 tu-graz.ac.at). For a description of hginstserver look at ftp://ftp.iicm.tu-graz.ac.at/pub/Hyper-G/Server/HOWTO This document describes the update procedure by use of the Hyper-G distribution tar-files. a) Download the Hyper-G_Server_... and/or the Hyper-G_Tools_... tar-file for your requested server machine from ftp.iicm.tu-graz.ac.at 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 Hyper-G tools for a SUN Sparc with the Solaris operating system installed you have to download the following tar-files: Hyper-G_Tools_beta_21.11.95.SUN5.tar.gz b) 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 | tar xvpf - The tar-files will be expanded in the subdirectory "tartmp" of hgsystem's home directory. c) Having unpacked the archives start the installation script executing the following command: tartmp/hginsttar When updating the Hyper-G 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 Hyper-G's design philosophy. In directory ftp://ftp.iicm.tu-graz.ac.at/pub/Hyper-G/papers you will find electronic versions of some of them. If you have never heard of Hyper-G before, we suggest you first look at files report388.ps* in that directory. We also suggest you to read ftp://ftp.iicm.tu-graz.ac.at/pub/Hyper-G/Server/HOWTO; this file contains a description of hginstserver installation method and gives a short introduction to Hyper-G server administration. This document does not describe Hyper-G clients. Information on Harmony, the UNIX/X11 client for Hyper-G, can be found in egmm94.ps* in the directory mentioned above. Documentation on Amadeus, the PC/MS-Windows client, is available in directory Hyper-G/Amadeus. Under Hyper-G/doc/HTF.ps you will find the description of HTF, the Hyper-G Text Format. This is a "must-read" before inserting text documents into a Hyper-G server. The protocol definition is contained in Hyper-G/doc/Protocol.ps, which is only of interest if you plan to write your own Hyper-G clients or tools that interface with the server directly. .