The install script tells you if the World Wide Web server is missing a feature, that OnSearch needs. The section, "Configuring Apache," describes the changes to httpd.conf that OnSearch needs.$ 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.
The Web server must have:
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.
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.
System Requirements
Automatic Installation
If for some reason the automatic installation doesn't work,
refer to "Manual Installation."
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.
$ su Password: # perl install
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.
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.
I'm going to install OnSearch in /usr/local/apache2/htdocs/onsearch. Is this okay (y/n)? y
OnSearch will use /usr/local/apache2/htdocs as its top-level document directory. Is this okay (y/n)? y
Creating directories. Copying files. Building indexing daemon. Setting permissions.
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.
Refer to the OnSearch User Guide, which you can open
from the, "About," page for instructions on how to
configure OnSearch and index documents.
If you can't find http.conf, try this command.
Also edit the values of CC and CFLAGS if
necessary for compilers other than GCC.
Then build and install onindex.
Also edit the TROFF variable if necessary.
Then install the man page for onindex.
Refer to the htpasswd manual page for further information.
Refer to the OnSearch User Guide, which you can open
from the, "About," page, for information about
configuring OnSearch and indexing documents.
To determine if Perl uses the I/O abstraction layer, use
the following shell command.
To do this, add the following line to httpd.conf,
outside of any directory wrappers.
This workaround assumes that Apache was build with
mod_env. You can verify this by typing at
the shell prompt:
The perlrun(1)
manual page describes the PERLIO options.
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:
If Apache is working correctly, you can view the manual at the
following URL:
The section, Apache 2.0 Configuration,
describes configuring the Web server for OnSearch.
If any of these modules are missing, consult
INSTALL in the Apache source code archive.
Change the lines:
You can also add these options for the entire Web site. The
comments in http.conf and the Apache manual provide
further information.
The following section configures the OnSearch admin
page to use passwords.
The install script creates onpasswd with
the user name, "onsearch," password, "onsearch," but you can
select any user name and password you like.
To create the onpasswd file, use the following
shell command.
Then uncomment the following lines in httpd.conf.
Manual Installation
Note: Some Web servers set the site name name using
Listen instead of ServerName.
ServerName
DocumentRoot
User
If find can't locate the file, then check the Apache
installation before continuing.
To find the settings mentioned above, either view the file
with a text editor or more, or use a shell command
something like this.
# find / -name "httpd.conf"
Substitute the actual path of httpd.conf in the example.
# egrep '^(ServerName|DocumentRoot|User|Listen}' /path/of/httpd.conf
For example, if DocumentRoot is
/usr/local/apache/htdocs, then OnSearch's working
directory will be
/usr/local/apache/htdocs/onsearch. The
following instructions use this example.
If you want to install OnSearch in a
different subdirectory, open onsearch.cfg in a text
editor and edit the value of OnSearchDir with the
name of the subdirectory.
# mkdir /usr/local/htdocs/onsearch
# mkdir /usr/local/htdocs/onsearch/admin
# mkdir /usr/local/htdocs/onsearch/cache
# mkdir /usr/local/htdocs/onsearch/doc
# mkdir /usr/local/htdocs/onsearch/images
# mkdir /usr/local/htdocs/onsearch/plugins
# mkdir /usr/local/htdocs/onsearch/webpages
# mkdir /usr/local/htdocs/onsearch/uploads
# mkdir -p /usr/local/spool/onsearch
# mkdir -p /usr/local/var/run/onsearch
# cp onsearch.cfg /usr/local/htdocs/onsearch
# cp -R html/* /usr/local/htdocs/onsearch
# cp images/* /usr/local/htdocs/onsearch/images
# cp -R cgi/* /usr/local/htdocs/onsearch
# cp doc/* /usr/local/htdocs/onsearch/doc
# cp plugins/* /usr/local/htdocs/onsearch/plugins
# chown -R nobody /usr/local/htdocs/onsearch
# chown -R nobody /usr/local/spool/onsearch
# chown -R nobody /usr/local/var/run/onsearch
# chmod 0755 /usr/local/htdocs/onsearch/*.cgi
# chmod 0755 /usr/local/htdocs/onsearch/admin/adminform.cgi
# chmod 0755 /usr/local/htdocs/onsearch/plugins/*
# chmod 0700 /usr/local/var/run/onsearch
# cd lib && (perl Makefile.PL LIB="/usr/local/apache/htdocs/onsearch/lib" && make install)
# make clean
# cd ..
# cd src && make install
# make clean
# cd ..
# cd doc && make all
# make clean
# cd ..
This creates a default administrator user name
onsearch, password onsearch. You can change
the password, or add users by adding them with
htpasswd and adding the users to ongroup.
# /usr/local/apache/bin/htpasswd -nb onsearch onsearch >/usr/local/etc/onpasswd
# echo "onsearch: onsearch" >/usr/local/etc/ongroup
<Directory /usr/local/apache/htdocs/onsearch>
Options ExecCGI Includes
AddHandler cgi-script .cgi
AddType text/html .shtml
AddHandler server-parsed .shtml
</Directory>
<Directory /usr/local/apache/htdocs/onsearch/admin>
AuthType Basic
AuthName OnSearch
AuthUserFile /usr/local/etc/onpasswd
AuthGroupFile /usr/local/etc/ongroup
require group onsearch
</Directory>
Appendices
Perl Configuration
Unicode Support
OnSearch's HTML filtering relies on Unicode support which was
first built into Perl in version 5.6.1. If you have an
earlier version of Perl, change the Plugin entries in
onsearch.cfg for the text/html and
text/xml MIME types from, plugins/html,
to, plugins/text. You will be able to index
HTML and XML documents, but OnSearch will not recognize
international characters.
Perl I/O Abstraction Layer
In some early releases of Perl version 5.8, OnSearch's
background processing causes increased memory usage and
reduced search times if Perl is configured with the I/O
abstraction layer. If you can not upgrade Perl, the
following workarounds help avoid the abstraction layer
incompatibilities.
The value of, "useperlio," should be,
"undef."
If the value is, "define," then you can get Perl to
use normal (Unix) I/O with either of the following methods.
# perl -V | grep 'useperlio'
SetEnv PERLIO :unix
# /path-to-httpd/httpd -l
Then build and install Perl as usual.
sh Configure -Uuseperlio -des
Apache Installation
Apache 1.3
This section describes how to build and install Apache 1.3.19 from the
source code distribution, from
http://www.apache.org, and configure it
to work with OnSearch.
README.configure also describes many other configurations.
To use OnSearch, you must enable at least
mod_cgi, mod_auth, and mod_include.
Building them should be enabled by default, but this example
shows how to enable them explicitly.
# ./configure --prefix=/usr/local/apache \
> --enable-module=most \
> --enable-shared=max
# make
# make install
Start the Apache server:
# ./configure --prefix=/usr/local/apache \
> --enable-module=cgi \
> --enable-module=include \
> --enable-module=auth
# make
# make install
NOTE: This configuration omits many
standard features and is recommended only if you plan
to use the Web server with OnSearch.
# /usr/local/apache/bin/apachectl start
http://<your-host-name>/manual/
You should then be able to view the Apache home page at the following
URL:
http://<your-host-name>/
Apache 2.0
OnSearch can use the default installation of Apache versions
2.0.x. To build and install the Web server, use the
following shell commands.
Then edit the Listen and ServerName lines
as described in httpd.conf, and start the
server.
# ./configure
# make
# make install
Browsing to the Web server's address should display
the Apache default home page.
# /usr/local/apache2/bin/apachectl start
Configuring Apache
Note: In all versions of Apache, it may be
necessary to add a unique user and group ID for the Web
server, in order index from within OnSearch. You will also need to
adduser and addgroup (or useradd
and groupadd) the Web server's unique user and group.
Apache 1.3
Configuring Apache requires several steps:
Load Modules
If you installed Apache with the configuration described in
Apache Installation, you will
need to load modules by using LoadModule statements
in httpd.conf, as described below.
However, if the Web server does not have Dynamic Shared
Object support enabled, you can determine which modules are
already loaded with the following shell command.
The modules that OnSearch needs are: mod_cgi,
mod_include, and mod_auth. If any of these
are not compiled into the Web server, you'll need to load
them dynamically by adding the following lines to
httpd.conf if they are not already present.
# /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
The file paths in the examples are those of a standard
Apache directory layout used in Apache Installation. You may need
to adjust the paths depending on the Web server's
configuration.
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
Enable Handlers
To enable the handlers for CGI scripts and server side
includes, uncomment the relevant lines in
httpd.conf.
So that they look like the following:
#AddHandler cgi-script .cgi
.
.
.
#AddType text/html .shtml
#AddHandler server-parsed .shtml
AddHandler cgi-script .cgi
.
.
.
AddType text/html .shtml
AddHandler server-parsed .shtml
Add Permissions
The easiest way to add permissions for OnSearch is to add the
following sections to httpd.conf.
This template is contained in the file
doc/conf.tmpl.
You must edit the <Directory ...> line with
the name of the directory where OnSearch is installed.
<Directory /usr/local/apache/htdocs/onsearch>
Options ExecCGI Includes
AddHandler cgi-script .cgi
AddType text/html .shtml
AddHandler server-parsed .shtml
</Directory>
This template is contained in the file
doc/auth.tmpl. It must be added in this format if
you want to use passwords with OnSearch.
Again, you must edit the
<Directory...> line with the name of the
OnSearch admin subdirectory.
<Directory /usr/local/apache/htdocs/onsearch/admin>
AuthType Basic
AuthName OnSearch
AuthUserFile /usr/local/etc/onpasswd
AuthGroupFile /usr/local/etc/ongroup
require group onsearch
</Directory>
Create onpasswd and ongroup Files
This step requires the htpasswd utility, which
should be installed with the Apache server (in
/usr/local/apache/bin in these examples).
Create the ongroup file with the following command.
# htpasswd -nb onsearch onsearch >/usr/local/etc/onpasswd
To change the user name or password, or add and delete
users, consult the Apache documentation.
# echo 'onsearch: onsearch' > /usr/local/etc/ongroup
Restart the Server
The final step is to restart the server.
# /usr/local/apache/bin/apachectl restart
Apache 2.0 Configuration
Install Apache as described in Apache Installation, and make certain
the Web server is operating correctly.
Also add doc/auth.tmpl and doc/conf.tmpl
to httpd.conf and create the password and group
files as described in the Apache
1.3 installation section.
$Id: INSTALL.html,v 1.26 2005/08/13 22:46:40 kiesling Exp $
AddHandler cgi-script .cgi
AddType text/html .shtml
AddOutputFilter INCLUDES .shtml