1. About the Search Engine
2. Testing for a Server
2.1 Information
about Servers
3. Running the Install Script
3.1 What the
Install Script Does
4. Troubleshooting
5. Glossary
For Hot Mix 17, we have included for your convenience a search engine that will permit you to quickly look up on the CD information about a specific vendor, a specific type of product, a specific area of interest, or whatever combination you may need to look for. For instance, the search engine gives you a fast and easy way to find demo software (simply search on "demo AND software"). Important Note: this search engine will not work on PCs or Macs.
The particular search engine being used is the SWISH Search Engine, used with permission from its creator, Kevin Hughes. SWISH stands for "Simple Web Indexing System for Humans". It works on many different flavors of UNIX platform, including BSD, Solaris, and IRIX. Please note that Macintosh and PC users will be unable to use the Hot Mix version of SWISH, since the Hot Mix CD has some specialized setup steps it needs to go through that are configured for IRIX systems.
The SWISH Search Engine uses a program to look up information about all the files on the Hot Mix 17 CD. Everything on the CD has already been indexed for you, and the search engine already knows where to look to find that information. However, the search engine uses a CGI script, and this requires an extra step to make the search engine work from the Hot Mix CD. We've tried to simplify this process for you by including with the CD a shell script that attempts to install the neccessary files in their correct places.
SWISH requires that you have a Web server running on your system in order to execute the cgi program that looks up information. A quick way to see if you have a server running is to execute the following command:
ps -ef | grep httpd
You should see some text returned that looks similair to this:
anybody 672 1 0 Jul 02 ? 0:00 ./ns-httpd -d
/usr/ns-home/https-myCPU/config
anybody 709 673 0 Jul 02 ? 0:01 ./ns-httpd -d
/usr/ns-home/https-myCPU/config
anybody 703 673 0 Jul 02 ? 0:01 ./ns-httpd -d
/usr/ns-home/https-myCPU/config
This indicates that you have a server running on your system. If you
don't see anything returned at all, or if you only see a single entry
that looks like this:
anybody 6295 6277 1 11:04:54 pts/4 0:00 grep httpd
you don't have a server running. Instead, the command that looks for processes that include "httpd" in them found the command that searches for "httpd" instead!
If you don't find a server that's running on your system, it's highly recommended that you discuss the situation with your systems administrator or Webmaster before attempting to start one up or install a server. While all systems since OS 5.3 are shipped from the factory with a server installed and running at startup, if your server has been turned off it was probably for a specific reason.
There are two types of servers that ship by default on SGI systems, depending on your operating system release and the bundle you purchased your system with.
If you are running a plain 5.3 system, you have the NCSA Web server installed, all configuration files live in /var/www/server, and your document root is /var/www/htdocs.
If you are running a 5.3 WebForce system, the Netscape Communications server is installed, all configuration files live in /usr/ns-home, and your document root is /var/www/htdocs.
If you are running a 6.2 WebForce system, the Netscape Fasttrack server is installed, all configuration files live in /usr/ns-home, and your document root is /var/www/htdocs.
If you are running a plain 6.2 system, the NCSA Web server is installed, with configuration files in /var/www/server and a document root in /var/www/htdocs.
For 6.3 systems and higher, the Netscape Fasttrack server is installed, all configuration files live in /usr/ns-home, and your document root is /var/www/htdocs.
If you have not customized your Web server and are running it exactly as it came out of the box, the installation script will look at your disk and install the search engine pieces in appropriate locations for them to work. You can still install the search engine if you've customized your Web server by loading a different server or changing your document root, provided that you know some specific information. If you don't have this information, or if you have trouble at any point with the installation, show this document to your Webmaster or systems administrator and they can help you run the installation script.
Now you're ready to run the setup script. This script will open a shell window which will then begin running the installation script. The first item the script asks is if you want to proceed with automatic installation. If you have a system that is running the server as it was installed from the factory, you can answer "yes" or "y" to this question, and the script will attempt to figure out what kind of server you have. The "swshsrch.cgi" program will be placed in /var/www/cgi-bin, and a "hm17search.html" file will be placed in /usr/tmp. The script will then check for a running server, and exit. If the script has trouble writing to a directory, it will ask you to log in as root to finish the installation.
If you answer "no" or "n" to the query to proceed with automatic installation, the script will then ask if you want to proceed with custom installation. By answering "yes" or "y" to this query, you will be able to tell the script where your document root and cgi-bin directories are. This part of the installation script requires that you already know where your document root is, and where your primary cgi-bin directory is. The script will then install "hm17search.html" into /usr/tmp, and "swshsrch.cgi" into the primary cgi-bin directory. If the script has trouble writing to a directory, it will ask you to log in as root to finish the installation.
If you answer "no" or "n" to both the automatic install and custom install questions, the script will simply exit without doing anything at all. At any point you can exit the script without causing any problems; the only ramification is that the search engine may not be completely installed and may not run correctly. Also, if you mistype the answer to a question, at any time you can choose to re-run the installation process.
When you initially started the Hot Mix executable, a file called "hm17search.html" was copied to your /usr/tmp directory. This script correctly sets links based on how your CDROM was mounted so that it can point to the install script (HM17_SGI/html/docopy.sh), and to this document (HM17_SGI/html/searchinfo.html). It gets the path information about /CDROM from an environment variable that is passed to it from the Hot Mix 17 executable.
When you run the install script, what should happen is that the script should take swshsrch.cgi from HM17_SGI/html/cgi-bin, and copy it to a place on your disk that cgi can be run from. On a default server, this typically means /var/www/cgi-bin; if you've modified your server, the installation script expects that your cgi-bin area is in your document root. Those people who have put cgi-bin somewhere else may find that the install seems to run ok, but the engine does not run. Should this be the case, you can modify your server to have a cgi-bin directory under your document root, and copy swshsrch.cgi to that location. Make sure that /usr/tmp/hm17search.html points to the new location.
After swshsrch.cgi is copied down, it is modified so that it points to the location on the CD where the SWISH executable and index lives (HM17_SGI/html/swish.11). Note that there are two indexes, index.swish and indexiso.swish. If the CD mounts on your system as /CDROM/iso9660, it uses an index that takes that path into account. The other index has files listed with the top level directory as /CDROM.
Once swshsrch.cgi is copied to your disk, the hm17search.html file in your /usr/tmp directory is modified so that the link will find where swshsrch.cgi is on your disk.
I don't have a running server. What should I do?
By default, systems that ship from the factory have servers installed on them that begin running when you boot your system. If for some reason you don't have a running server, it's very important to check with your systems administrator or Webmaster to find out why the server isn't running. One reason may be that the flags neccessary to let the server know it should run were turned off; you can run the command "/etc/chkconfig" and look at the status flags for outbox, ns_enterprise, ns_fasttrack, ns_httpd and ns_communications and see if those flags are set to on, or off. You systems administrator or Webmaster may have chosen to remove the NCSA or Netscape server, in which case you won't find any of those flags at all. Again, if that software has been removed, it was for a specific reason, and you'll want to talk to your systems administrator or Webmaster about it.
I don't think I have server software installed.
By default, all systems from 5.3 OS release and up were shipped from the factory with a running server. If you think that software is missing, you can use the "versions" command, and look for Outbox, or any of the Netscape server products. If "versions" does not show that software as being installed, you will want to consult with your systems administrator or Webmaster and ask why it was removed from the system. If they wish to reinstall it, the software lives on the CDs that shipped with your system.
I have a running server, but the search engine still doesn't run.
Several things may have happened here...the quickest way to find out what went wrong is to check the server logs. If you're running a Netscape server, you can look at the bottom of /usr/ns-home/yourservername/logs/errors. If you're running the NCSA server, the error log lives in /var/www/server/logs/error_log.
One thing that may have gone wrong is that cgi was turned on as a filetype and doesn't include swshsrch.cgi's location...or the cgi-bin directory where swshsrch.cgi was installed is not recognized as a valid cgi-bin directory. This is usually indicated by an error that looks like this:
trying to GET /var/www/cgi-bin/swshsrch.cgi, send-cgi reports: cannot find CGI program /var/www/cgi-bin/swshsrch.cgi (No such file or directory)
You can either configure your server to recognize the location of swshsrch.cgi as a valid directory for cgi-bin programs by including it as another cgi-bin directory, or including it in the list of places where cgi is turned on as a filetype; or you can simply re-run the installation program and install swshsrch.cgi into the correct directory. For assistance with this, please see your Webmaster or systems administrator.
Another thing that may have gone wrong is that you may have mistyped one of the directories during custom installation. For instance, when you are asked to choose your primary cgi-bin directory, if that directory doesn't exist under your document root, or if you typed in the full path (e.g. /var/www/cgi-bin rather than cgi-bin), or if you included the leading ./, the hm17search.html file will be looking in the wrong location for swshsrch.cgi. This is usually indicated by an error in the error log that looks like this:
trying to GET /var/www/cgi-bin/swshsrch.cgi, send-cgi reports: cannot find CGI program /var/www/var/www/cgi-bin/swshsrch.cgi (No such file or directory)
In this instance, the user typed in the entire document root AND cgi-bin path, which causes an extra instance of /var/www to occur in hm17search.html, thereby breaking the link. To fix this, you can either re-install the search engine, or you can hand-edit the file /usr/tmp/hm17search.html and point it to the correct URL where swshsrch.cgi lives.
I've tried everything and simply can't get the search engine to run.
Your best bet is to find someone at your site who understands Bourne shell scripts, URLs and cgi-bin programs, and ask them to take a look at /usr/tmp/hm17search.html and try to figure out what went wrong. You can consult the section above on What the Install Script Does as a guide. The basic flow is to make sure that hm17search.html can find and run swshsrch.cgi, and that swshsrch.cgi can find and run "swish" on the CDROM with the index.swish file on the CDROM.
document root: This refers to the directory on your system from which your Web pages are served. By default, this is set to /var/www/htdocs when your system ships from the factory. Some people move their document root onto another disk entirely when they receive their system.
cgi program: A program that uses the Common Gateway Interface language and which runs on your local server. These programs commonly output Web pages, and require a running server in order to function.
web server: This is a program that runs on your system and is configured to serve Web documents and run cgi programs. The difference between a server and a client is that a client can only access someone else's server and not serve pages itself.
swshsrch.cgi: This is the cgi program from the SWISH search engine that looks on the Hot Mix 17 CDROM for the swish executable and the index.swish file that contains the list of information. It is updated by the installation script to reflect the current path to find swish and index.swish on the CD.
hm17search.html: This is the search page from which you can execute searches. It is placed in your /usr/tmp directory by the installation program, and is updated by the installation script to reflect the path to this document, the path to the installation program, and the path to find swshsrch.cgi.