Linux Knowledge Base on CD
==========================

Requirements
------------

Recent Linux kernel version [such as 2.0.36 or 2.2.x]
Web Server [such as Apache 1.3]
30M free disk space for minimal install [run from CD]
200M free disk space for full install [run from Hard Drive]

The Linux KB is installed as a web site, so you need a web browser such
as Netscape or Lynx to view the contents.  The search engine uses
ht://dig, which it will install for you.

To Install
----------

1] Log in as root.
2] Mount the Linux KB CD with a command such as "mount /mnt/cdrom".
3] Cd to the root of the CD directory. "ex: cd /mnt/cdrom"
4] Execute the install script with the command "./install".  Or you
   can use "./install -v" if you want a verbose installation.
5] A few questions will be asked.  Answer them according to your
   preference.

To Run
------

Fire up your favorite web browser and point it to http://localhost/.
Lynx users can use http://localhost/lynx.html.  See "known issues",
below, for information about installation for public web access.

To Report Bugs
--------------

Email linuxkb@cheek.com with a detailed description of what happened, how
you got it to happen, and what you expected to happen.

To Uninstall
------------

Use rm -rf on the directory you installed the Linux KB in.  Since
everything copied to the hard drive is underneath that directory
structure, uninstalling is that simple!

You must also delete the changes, if any, to your Apache configuration.
The Linux KB will change the access.conf and srm.conf files in your config
directory, typically /etc/httpd/apache/conf.  The original files will be
saved in that same directory, with a .linuxkb extension.  Restore these
original files and restart apache.

Known Issues
------------

*** Installing without C++ libraries

The ht://dig source is written in C++, so the C++ libraries must be
installed.  On a system that uses RPM [Caldera OpenLinux or Red Hat],
these packages are libg++-devel and libg++-devel-static.  To check if
they are installed, type:

rpm -qa | grep libg++

and look for these packages.  To install, mount your Linux installation cd
in your CD drive, change to the Packages/RPMS directory, and type:

rpm -i libg++*

*** Installing as a virtual server

By default, the install utility with this CD will modify the document root
of the Apache web server.  On a system that supports virtual hosts, you
may wish to install the CD as a virtual host.  The following configuration 
is recommended:

<VirtualHost your.ip.address.here>
ServerName abc.def.com
ServerAdmin webmaster@def.com
DocumentRoot /opt/linuxkb/html
ErrorLog logs/linuxkb.errors
TransferLog logs/linuxkb.access
ScriptAlias /cgi-bin/ /opt/linuxkb/cgi-bin/
</VirtualHost>

*** Installing for public web access [ie, other than from the localhost]

This release of the Linux KB is preset for the localhost hostname.  As
such, you will experience abnormal results if you access the KB CD from a
computer other than the computer that that which the KB is installed.
To remedy this, the ht://dig database must be rebuilt, indexed from the
fully-qualified hostname you wish to use.  Follow these steps to do this:

* Note: you need to be logged in with superuser privileges to do this *

1] Ensure that the kb is installed on the target web server.  For
   instance, if I wanted to install the KB for browsing at
   http://seattle.cheek.com/, i would need to install the KB CD on the
   seattle.cheek.com machine.  Make sure that the KB is browseable on
   this machine.

2] Edit the linuxkb.conf file, typically in the /opt/linuxkb/htdig/conf/
   directory.  Find the line that says:

start_url:              http://localhost/http/ http://localhost/ftp/

3] Change all occurences of localhost to the hostname of the web server.
   This line may wrap if the last character on the line is a backslash
   ("\").  In my case:

start_url:              http://seattle.cheek.com/http/ \
                        http://seattle.cheek.com/ftp/

4] Exit and save this file.  cd to the bin directory inside htdig,
   normally /opt/linuxkb/htdig/bin.  Start execution of the rundig script
   with a command similar to the following:

./rundig -s -v -c /opt/linuxkb/htdig/conf/linuxkb.conf

   -s means shows statistics at the end, -v means be verbose, -c means
   use the specified configuration file.  Note that this config file is
   the one you edited previously.

   Once the rundig script finishes, if all goes well, your KB CD will be
   set up for public browsing.

*** Installing in a subdirectory of the document root [ie, to access as
    http://localhost/linuxkb/ instead of http://localhost/]

The Linux KB on CD is preconfigured for URL's relative to the document
root.  As such, if you move the KB to a subdirectory of the document root,
some of the links may no longer work.  Installing to a subdirectory of the
document root is not supported.
