OnSearch Installation

1. Introduction
2. System Requirements
3. Automatic Installation
4. Manual Installation
5. Appendices
   1. Perl Configuration
   2. Apache Installation
      1. Apache 1.3
      2. Apache 2.0
   3. Configuring Apache
      1. Apache 1.3
         1. Load Modules
         2. Enable Handlers
         3. Add Permissions
         4. Create Password and Group Files
         5. Restart the Server
      2. Apache 2.0
   4. Acknowledgements

  $ su            # Log in as the system administrator.
  Password:
  # perl install  # Follow the prompts.

The section, "Automatic Installation," describes each step of the automatic installation process in detail.

System Requirements

1. You must be able to log in as the superuser ("root") or set permissions using Web server's user ID.

2. The file systems where OnSearch is installed (/usr/local and the Apache DocumentRoot directory) need to be writable; e.g. they are not mounted read-only locally or via a network. If the system does not have a /usr/local file system, the installation process will create one.

3. The system must have sufficient disk space for the indexes. They can add significantly to a Web site's storage.

4. An Apache Web server, version 1.3 or later. If you don't have Apache, you can find it at http://www.apache.org.

   The Web server must have:

   1. Handlers to Run Common Gateway Interface scripts outside ScriptAlias directories.
   2. Handlers to execute CGI scripts using Server Side Include shtml files.
   3. The ability to write to the document directories.
   4. Unique user and group IDs for the Web server in order to index from within OnSearch.

   The section, Apache Configuration, describes how to add these features.

   If these requirements present security problems, you can limit OnSearch to only a portion of the Web site, or create a symlink to OnSearch's directories. The Apache document manual/misc/security_tips.xml discusses these issues.

5. Perl, version 5.6.1 or later. OnSearch can work with earlier versions, but its HTML filtering relies on the Unicode support of later versions. See Perl Configuration.

   If you need to install or upgrade Perl, you can find it at: http://www.perl.org/.

   The Perl interpreter, or a symlink to the interpreter, must be /usr/bin/perl.

   Note: OnSearch does not yet use the Perl I/O abstraction layer. One symptom of I/O layer incompatibility is excessive memory usage. To determine if Perl was built with the abstraction layer, and how to cope with it, see Perl Configuration.

6. A C compiler. The C part of OnSearch was built with the GNU C compiler, GCC 2.95. Other ANSI C compilers should also be able to build the binary programs with minimal effort. The GCC Web site is http://www.gnu.org, but most operating systems offer GCC as an optional free software package.

7. Web browser(s) that can handle cookies and CSS 2 style sheets; e.g., Mozilla and Netscape, versions 5 and later, and recent versions of Internet Explorer. Although OnSearch is compatible with earlier browsers and text mode programs like lynx, the pages are much more readable when viewed with recent browsers.

8. To index and search documents other than text files, OnSearch's plugins rely on helper applications. The Postscript plugin uses GNU Ghostscript to translate Postscript to text. The PDF plugin uses the pdftotext utility. The gzip plugin requires the gzip utility. You can find ghostscript at http://mirror.cs.wisc.edu/pub/mirrors/ghost. Pdftotext is part of the xpdf distribution which is downloadable from http://www.foolabs.com/xpdf. The main gzip site is http://www.gnu.org. Many operating systems also provide ghostscript, xpdf, and gzip packages.

The examples here show an Apache server installed as described in, Apache Installation, and, Configuring Apache. The host name, directories, and user and group names may be different.

1. Log in as the superuser and start the install script.

   $ su
   Password:
   # perl install
   

2. The install script will search for the Web server and its configuration If the system has more than one Web server the install script will ask which to use. This step can take several minutes.

   OnSearch installation.  If this program can't determine the site
   configuration, read INSTALL.html.
   
   NOTE: If you've already installed OnSearch, make a backup copy.
   Press [Ctrl-C] to exit now if necessary.
   
   The Web server is /usr/local/apache2/bin/httpd.  Is this correct (y/n)?
   y
   The Web server's configuration file is /usr/local/apache2/conf/httpd.conf.  
   Is this correct (y/n)?
   y
   Configuring for /usr/local/apache2/bin/httpd and /usr/local/apache2/conf/httpd.conf.
   

3. The install script finds the settings it needs from the Web server's configuration. If you're not certain that the settings are correct, determine that the settings in httpd.conf are also correct.

   Note: The install script will also warn you if the Web server is not configured to handle CGI scripts and Server Side Includes. You must make the necessary changes to httpd.conf before using OnSearch.

   The following values were found:
   The Web site's name is owl.local.net.
   The Web site's document directory is /usr/local/apache2/htdocs.
   The Web server's version is 2.0.54.
   The Web server's directory is /usr/local/apache2.
   The Web server's process owner is apache. 
   The Web server's port is 8090.
   

4. The install script then verifies the directory where it should install OnSearch. Refer to Manual Installation if you want to install OnSearch elsewhere.

   I'm going to install OnSearch in /usr/local/apache2/htdocs/onsearch.  Is this okay (y/n)?
   y
   

5. The install script installs the OnSearch program, documentation, and libraries, and verifies the location of the top-level document directory.

   OnSearch will use /usr/local/apache2/htdocs as its top-level document directory.  
   Is this okay (y/n)?
   y
   

6. The install script then checks for Perl and the GNU C Compiler. They must be present or the script will not continue.
7. The installation script then creates the necessary directories, configures and builds the program files, and sets the application's file and directory permissions.

   Creating directories.
   Copying files.
   Building indexing daemon.
   Setting permissions.
   

8. Then the install script asks if you want add directory wrappers for the OnSearch directories. They are necessary to set the correct permissions for OnSearch and enable passwords for the, "Admin," page.

   Note: The installation's administrator user name is, "onsearch," password, "onsearch." You should change them to your own user name and password by editing /usr/local/etc/onpasswd and /usr/local/etc/ongroup. Refer to the manual page for Apache's htpasswd program for instructions to set the password.

   I'm going to add OnSearch's configuration to /usr/local/apache2/conf/httpd.conf.
   I'll copy the original httpd.conf file to httpd.conf.onsearch-save.
   
   You can skip this step, and then configure the Web server
   manually, using the template in doc/conf.tmpl.
   Should I continue (y/n)?
   y
   
   I'm going to add password authentication information to your Web
   server configuration and then try to restart the server.
   
   With authentication enabled, users must enter a user name and password
   to perform administrative tasks.  For passwords to work the Web server
   must include mod_auth in its configuration.
   
   During the process, the installation will copy your old 
   /usr/local/apache2/conf/httpd.conf to /usr/local/apache2/conf/httpd.conf.onsearch-save, 
   so you can restore your previous configuration if necessary.
   
   You can skip this step, but then you will not have password protection
   for administrative tasks.
   
   Should I continue (y/n)?
   y
   

   
   .
   .
   .
   
   Done. If the installation was correct, you should be able to browse to
   
   http://owl.local.net:8090/onsearch/index.shtml
   
   The OnSearch User Guide, 
   
   http://owl.local.net/onsearch/doc/userguide.html
   
   describes how to index files and start using OnSearch.
   
   

9. You should now be able to browse the URL given by the install script (which uses your Web server's name instead of the server given in the example above). If the Web server's configuration is correct, you should see OnSearch's main Web page. If you encounter an error, refer to Manual Installation and Configuring Apache.

Refer to the OnSearch User Guide, which you can open from the, "About," page for instructions on how to configure OnSearch and index documents.

Manual Installation

Refer to the OnSearch User Guide, which you can open from the, "About," page, for information about configuring OnSearch and indexing documents.

Appendices

Following the instructions in README.configure, build and install Apache with support for the standard modules and Dynamic Shared Object support, and install the server in /usr/local/apache:

# ./configure --prefix=/usr/local/apache \
> --enable-module=most \
> --enable-shared=max
# make
# make install

# ./configure --prefix=/usr/local/apache \
> --enable-module=cgi \
> --enable-module=include \
> --enable-module=auth
# make
# make install

# /usr/local/apache/bin/apachectl start

If Apache is working correctly, you can view the manual at the following URL:

http://<your-host-name>/manual/

http://<your-host-name>/

The section, Apache 2.0 Configuration, describes configuring the Web server for OnSearch.

Configuring Apache

# /usr/local/apache/bin/httpd -l
Compiled-in modules:
  http_core.c
  mod_env.c
  mod_log_config.c
  mod_mime.c
  mod_negotiation.c
  mod_status.c
  mod_include.c
  mod_autoindex.c
  mod_dir.c
  mod_cgi.c
  mod_asis.c
  mod_imap.c
  mod_actions.c
  mod_userdir.c
  mod_alias.c
  mod_access.c
  mod_auth.c
  mod_setenvif.c
suexec: disabled; invalid wrapper /usr/local/apache/bin/suexec

LoadModule auth_module /usr/local/apache/libexec/mod_auth.so
LoadModule cgi_module /usr/local/apache/libexec/mod_cgi.so
LoadModule includes_module /usr/local/apache/libexec/mod_include.so

If any of these modules are missing, consult INSTALL in the Apache source code archive.

Enable Handlers

Then uncomment the following lines in httpd.conf.

AddHandler cgi-script .cgi

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml