######################################################################
###                         JSERV                                  ###
######################################################################

The netcgi library provides support for the JServ protocol that
was orignally developed for the Java Apache Project (mod_jserv),
and that is now also used by the Jakarta Project (mod_jk).

Whenever possible, use mod_jserv for now. mod_jk is only the better
choice if one of the newer protocols (ajp-1.3 or 1.4) is used, but
these are not yet implemented in netcgi.

See also examples/jserv.

======================================================================
BUILDING mod_jserv
======================================================================

If you don't have already mod_jserv.so for your Apache: You need
http://java.apache.org/jserv/dist/ApacheJServ-1.1.2.tar.gz. You don't need
the JSDK classes (but a Java compiler; only to satisfy the configure script).
Do:
  mkdir -p jsdk/javax/servlet
  touch jsdk/javax/servlet/Servlet.class
This way the configure script thinks you have the JSDK classes.
  ./configure --with-apxs=/usr/sbin/apxs --prefix=/tmp/jserv --with-JSDK=jsdk
(Maybe you need --enable-EAPI, too)
Then do 
  cd src/c
  make
The resulting mod_jserv.so was in src/c/.libs (i.e. where libtool stores
libraries before installation).

----------------------------------------------------------------------
Sample httpd.conf for mod_jserv
----------------------------------------------------------------------

LoadModule jserv_module       /usr/lib/apache/mod_jserv.so
AddModule mod_jserv.c

<IfModule mod_jserv.c>

# The mode jservd is started. "off" means that the web server starts jservd,
# "on" means that the web server finds an already started jservd.
ApJServManual off

# The path to jserv.properties:
ApJServProperties /etc/httpd/jserv.properties
ApJServLogFile /var/log/httpd.jserv_log
ApJServLogLevel info
ApJServDefaultProtocol ajpv12

# Where jservd can be found:
ApJServDefaultHost localhost
ApJServDefaultPort 8007

# The secret key must be the same that is specified in jserv.properties:
ApJServSecretKey /path/to/secret/file/containing/anything

# This means that the root zone is mounted under /servlets. (Ocamlnet
# does not support the zone concept, so use the root zone always.)
ApJServMount /servlets /root

# Note: you can also mount further jservd servers by:
# ApJServMount /path protocol://host:port/zone, e.g.
# ApJServMount /servlets8008 ajpv12://localhost:8008/root
</IfModule>

----------------------------------------------------------------------
Sample jserv.properties for mod_jserv
----------------------------------------------------------------------

# wrapper.bin must be the name of the jserv daemon. (In the original
# design, it is the path to the JVM executable.)
wrapper.bin=/path/to/ocamlnet_executable

# bindaddress and port determine on which network interface and which
# port the jserv daemon listens. It must be possible that the web server
# reaches this port.
bindaddress=localhost
port=8007

# It is strongly recommended to use a password for the connection between
# the web server and jservd (especially, if bindaddress is not "localhost").
# The contents of the file security.secretKey are used as password.
# This file must be the same file as the file defined by
# ApJServSecretKey in httpd.conf.
security.authentication=true
security.secretKey=/path/to/secret/file/containing/anything
security.challengeSize=5

======================================================================
BUILDING mod_jk
======================================================================

This is a transscript of what I have recently done to build and install
mod_jk for Apache 1.3. mod_jk also supports Apache 2.0, IPlanet,
Domino, and IIS.

You need autoconf, automake and libtool as prerequisites (these are
GNU tools, look at gnu.org for downloads). You don't need neither JDK
nor Tomcat.

- Get the sources. You need the "jakarta-tomcat-connectors" archive.
  I downloaded
  http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.0.3/
    src/jakarta-tomcat-connectors-4.0.2-01-src.tar.gz

- Unpack the archive:
  tar xzf jakarta-tomcat-connectors-4.0.2-01-src.tar.gz
  cd jakarta-tomcat-connectors-4.0.2-01-src/jk/native

- Create the build environment:
  sh buildconf.sh

  This outputs
    libtoolize --force --automake
    automake -a --foreign -i
    aclocal
    autoconf
  for me without additional messages.

- Configure:
  ./configure --with-apxs=/usr/sbin/apxs --enable-EAPI
  works for me

- Compile:
  make

  This creates the file apache-1.3/mod_jk.so for me.

- Install:
  cp apache-1.3/mod_jk.so /usr/lib/apache
  - or whereever your Apache modules reside.

----------------------------------------------------------------------
IMPORTANT HINTS for mod_jk
----------------------------------------------------------------------

Unlike mod_jserv, mod_jk does not start or stop the application server.
This means that the application server must already be running when
the first servlet request happens.

Another difference is that mod_jk does not support authentication for
the ajp-1.2 protocol.

Certain header fields are not transferred to the application server:
Zone, Servlet name, document root, path info, path translated, 
script name, server signature. Because of this, netcgi computes some
of these fields as follows:

  - If the path of the request URI contains the substring /servlets/,
    the path component following /servlets/ will become the servlet name,
    and the rest of the URI will become the path info. The script name is
    set accordingly. Example: The URI 
	http://sample.net/dir/servlets/xy/z?a=1
    sets the fields as follows:
        Servlet name: xy
        Path info: /z
        Script name: /dir/servlets/xy
    The fields zone, path translated, server signature are never set.

  - If the path of the request URI does not contain the substring
    /servlets/, the servlet name and the script name are both set to the
    request URI path, and path info remains empty.

You can set the substring /servlets/ to a different value by specifying
the property jakarta.servletSubString in the jserv.properties file.
The empty string disables this feature.

netcgi does not accept a worker.properties file as input, so you have
to create the corresponding jserv.properties file.

----------------------------------------------------------------------
Sample http.conf for mod_jk
----------------------------------------------------------------------

LoadModule jk_module /usr/local/httpd/mod_jk.so
AddModule mod_jk.c

<IfModule mod_jk.c>
JkWorkersFile /etc/httpd/workers.properties
JkLogFile /var/log/httpd.jk_log
JkLogLevel info
JkMount /servlets/* myworker
</IfModule>

----------------------------------------------------------------------
Sample workers.properties
----------------------------------------------------------------------

worker.list=myworker

worker.myworker.port=8007
worker.myworker.host=localhost
worker.myworker.type=ajp12

----------------------------------------------------------------------
Sample jserv.properties
----------------------------------------------------------------------

(You still need this file! This file is the second argument on the command
line when the application server is started.)

bindaddress=localhost
port=8007
security.authentication=false

# Set this to the prefix in JkMount:
jakarta.servletSubString=/servlets/

# List the hosts that are allowed to connect:
security.allowHost=localhost
