head	1.5;
access;
symbols;
locks; strict;
comment	@# @;


1.5
date	98.11.26.14.44.07;	author tommy;	state Exp;
branches;
next	1.4;

1.4
date	98.11.25.21.23.43;	author stefano;	state dead;
branches;
next	1.3;

1.3
date	98.11.12.00.16.28;	author stefano;	state Exp;
branches;
next	1.2;

1.2
date	98.10.13.06.23.39;	author vadim;	state Exp;
branches;
next	1.1;

1.1
date	98.09.16.04.42.23;	author ed;	state Exp;
branches;
next	;


desc
@@


1.5
log
@Made some more configure improvements.

Added updated INSTALL doc, would like some feedback before I
start writing the HTML version.

Removed JServSSI from makefiles and regenerated .deps

Made src/c not actually put the mod_jserv.so in the apache tree
until you do a make install.
@
text
@
                         A P A C H E   J S E R V
                              Version 1.0b1
         Installation instructions for Apache JServ on Unix systems.
     
NOTE:  This file contains the same instructions as /docs/install/howto.unix_install.html

  What About Win32?
  -----------------

  For NT/9* see docs/install/howto.win32_install.html

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

  See the README file for requirements.

  The   easy steps to building Apache JServ
  -----------------------------------------


  Step 1 - Choose how to add the Apache JServ module to Apache
  ------------------------------------------------------------

  There are two choices:
    
     o  Compile it in -  This requires that you have a source 
        distribution of the Apache server handy as it adds our
	source to that tree and lets Apache build the Apache JServ
        module into itself statically.    
 
     o  DSO - This requires that you have an installation of Apache 1.3.*
        that was configured to have DSO support when it was built.  If you're
	not sure whether yours does follow the instructions on configuring 
        Apache JServ for DSO and the configure script will tell you.


  Step 2 - Configure Apache
  -------------------------

  If you are using a source distribution then you have to configure apache
  first (some generated header files are needed for JServ Apache to pass its
  configure checks).  You do not need to worry about specifying the Apache JServ
  module.

  If you are using DSO then you can ignore this step.  If you have a source
  distribution and would like to build it with DSO support and install it
  for use by Apache JServ then use the following options when configuring
  Apache:

  --enable-rule=SHARED_CORE --enable-module=so

  Step 3 - Configure Apache JServ
  -------------------------------

  Now you are ready to configure Apache JServ.  To do this you may (or may not)
  need to specify quite a few arguments to configure.  These are:

  o  Apache Dir

     For DSO use:

     --with-apache-install=/path/to/apache/installation

     NOTE: The configure script will check the default installation dir
     so if you have it there you may leave this argument out.	

     For a static compile use:

     --with-apache-src=/path/to/apache/source

     NOTE: For those using a source distribution we will configure apache
     for you (taking care to preserve your previous configuration) if you
     use this option:

     --enable-apache-conf	

  o  JDK programs

     In order to find java, javac, and jar you can use the following options.
     By default we will first look at the JDK_HOME and JAVA_HOME environment
     variables, if they aren't set then will check your PATH
     environment variable.  The results from using the PATH can be overriden
     by:

     --with-jdk-home=/path/to/jdk

     And we will use these then.  If they aren't found here we will tell you
     and default back to whatever is in your PATH.

     NOTE: By default debugging symbols are left of the JServ classes, you
     can put them back in by using this:

     --enable-debugging

     NOTE: By default the jar file is not compressed, this can be changed like so:
 
     --enable-compressed-jar

  o  JSDK classes

     Being a servlet engine we need to know where your servlet classes are.
     If they are not in your CLASSPATH then you need to specify them like so:

     --with-jsdk=/path/to/jsdk

  Step 4 - Build
  --------------

  Once you have configured JServ Apache you can run make. If you are
  using a source distribution then you also have to run make in the
  Apache source directory.

  See the HTML docs for info on setting up and running servlets.
  
@


1.4
log
@Removed because obsoleted by install docs
@
text
@d1 114
a114 29
This file is intended to provide a bare-bones introduction, enough to
get your system running using Apache JServ at a basic level.  After that,
you will probably want to refer to the HTML documentation in the docs
subdirectory.

How to install:
--------------

  Unix Systems:
    1) In this directory, run the configure script.  You may need to
       specify the location of the Apache installation, using
       the --with-apache-dir={directory} option.

       You may want to use the Apache configure/Configure tool
       (for 1.3/1.2, respectively) -- in that case, you should also
       supply a --enable-apache-conf argument, and possibly
       --prefix={directory} to be given to the Apache configure
       script; examples are shown below:

       ./configure --with-apache-dir=/usr/local/src/apache_1.3.1
                   --enable-apache-conf --prefix=/usr/local/etc/httpd

       ./configure --with-apache-dir=/usr/local/src/apache_1.2.6
                   --enable-apache-conf

       You may want to specify the [alternative] location for the Java
       runtime support with --with-jdk-home={directory} option. Please note
       that this option overrides the $JAVA_HOME environment variable value
       (it used to be the other way around).
a115 201
    2) If you specified --enable-apache-conf, then almost
       everything is taken care of, other than actually running
       make in the Apache directory.  If not, you will need to do
       the following by hand:

       Add mod_jserv to your Apache Configuration file; Apache
       provides documentation on how to do this, but here are
       some hints.
       a) If you're using 1.3, this can be done by running
          the top-level configure script with the line:
          --activate-module=src/modules/jserv/mod_jserv
       b) For either 1.2 or 1.3, if you're modifying the
          Configuration file (in the src directory) directly,
          you can add one of the following lines to that file,
          and (in the src directory) run ./Configure:
		Apache 1.3:
		    AddModule modules/jserv/mod_jserv.o
		--------------
		Apache 1.2:
		    Module jserv_module modules/jserv/mod_jserv.o

          *NOTE*: You must add the following to the EXTRA_LIBS
          line in the configuration: "-L./modules/jserv -ljserv"

    3) Compile Apache, and once you've configured JServ, it should
       run.  Information on how to configure JServ is shown at the
       after the next section, as it's the same for Unix and Windows.


  Win32 Systems:

    1) Create a directory under the Apache modules source tree called "jserv"
        ex. "apache/src/modules/jserv"

    2) Copy all files from this tree into that directory.

    3) In this new-created dir issue "nmake -f Makefile.nt"

    4) Copy "ApacheModuleJServ.dll" into your modules directory

    5) Add to Apache "httpd.conf" file this line
        "LoadModule jserv_module modules/ApacheModuleJServ.dll"

    6) Note that you will need to compile Apache, since JServ uses
       libraries which are not distributed with the Apache executable.

  Standalone wrapper 
	The steps for making these, for Unix and Win32, are described in
	more depth in the HTML documentation which can be found in the
	docs subdirectory of the Apache JServ tree.

Apache Directives:
------------------

There are many other options available, but the following directives
are enough to get Apache JServ working:

ApJServProperties [filename]
    Properties filename for Apache-JServ in "Automatic" Mode (which
    is what these instructions document)

    In the conf subdirectory, there is a file called jserv.properties
    which is a good framework; edit it, and provide the full pathname
    to it, as in the following examples:
	ApJServProperties /usr/local/jserv/conf/jserv.properties
	ApJServProperties C:\Program Files\Apache JServ\conf\jserv.properties

ApJServMount [name] [jserv-url]
    This directive offers quite a bit of flexibility and configurability
    in how servlets map to class files.  To get Apache JServ working, however,
    all you need is the following:

	ApJServMount /servlets /root

    Note: it is necessary to set up a root zone in the jserv.properties
    file for this to work; the sample jserv.properties file mentioned
    above does this.

    Here is a more complete explanation of what this directive does:

    This creates a mount point for an Apache-JServ "zone".  Multiple
    ApJServMount directives are allowed.
    Default: NONE
           [name] is the name of the Apache virtual path to mount jserv-url on
           [jserv-url] is something like "protocol://host:port/zone"
                    if protocol, host or port are not specified then the values
                    from "ApJServDefaultProtocol", "ApJServDefaultHost" or 
                    "ApJServDefaultPort" (other Apache directives) will be used.
                    if zone is not specified all zones will be mounted as sub
                    directories of "name"
                        EX: "ApJServMount /servlets ajpv11:localhost:8007"
                            if user requests "http://host/servlets/kzla/Class"
                            the servlet "Class" in zone "kzla" will be executed
                        EX: "ApJServMount /servlets /kzla"
                            if user requests "http://host/servlets/Class"
                            the servlet "Class" in zone "kzla" on default host
                            thru default protocol on default port will be
                            executed

ApJServSecretKey [filename]
    Apache-JServ secret key file relative to Apache root directory.  This
    defaults to "DISABLED", which disables authentication, and it is not
    strictly necessary to configure this directive; however, it this may
    present certain security issue.  We advise either using
    authentication or restricting access to the machine and the port on which
    Apache JServ listens.

    The contents of this file aren't important (so long as the file contains
    a small amount of text or binary data), but protecting it from potential
    intruders is.

    The authentication Apache JServ provides merely verifies the identities
    of the client and server; it provides no encryption, which means that
    if sensitive data is being transmitted, other measures (such as securing
    the machine) will be necessary to protect it.

    Changing the port (with ApJServPort) may also improve security.

    At present, no exploits are known which would allow a user to gain
    access to a machine through the Apache JServ engine; but it is possible
    that an attacker with direct access to Apache JServ and sufficient
    knowledge of the servlets in use could gain authorized access through
    them, depending on the servlets in use.
    
ApJServAction [extension] [servlet-uri]
    Executes a servlet passing filename with proper extension in
    PATH_TRANSLATED property of servlet request.
    This is not necessary, unless you want to use JServSSI, GNU Server Pages
    (GSP), GnuJSP or other, similar template/page-compilation systems.

    Defaults: NONE

       EX: ApJServAction .jhtml /servlets/org.apache.jserv.servlets.JServSSI

Properties:
-----------

These are found in Apache JServ properties file, and are also explained
(with examples) in the sample jserv.properties file which is provided
with the Apache JServ distribution.

wrapper.bin=[filename]
    The JAVA Virtual Machine binary
    Default: "/usr/bin/java" for Unix systems
             "c:\jdk\bin\java.exe" for Win32 systems

wrapper.bin.parameters=[string]
    Optional arguments passed to java binary
    Default: NONE

wrapper.class=[classname]
    Class executed by JAVA Virtual Machine
    Default: "org.apache.jserv.JServ"

wrapper.class.parameters=[string]
    Optional arguments passed to java class after this properties filename
    Default: NONE

wrapper.path=[path]
    PATH environment value passed to JAVA Virtual Machine
    Default: "/bin:/usr/bin:/usr/local/bin" for Unix systems
             "c:\(windows-dir);c:\(windows-system-dir)" for Win32 systems
    Notes: if more than one line is supplied these will be concatenated using
           ":" or ";" (depending whether Unix or Win32) characters
           Under Win32 (windows-dir) and (windows-system-dir) will be
           automatically evaluated to match your system requirements

wrapper.classpath=[path]
    CLASSPATH environment value passed to JAVA Virtual Machine
    Default: NONE (Sun's JDK/JRE already have a default classpath)
    Notes: if more than one line is supplied these will be concatenated using
           ":" or ";" (depending whether Unix or Win32) characters

wrapper.env=[name]=[value]
    An environment name with value passed to JAVA Virtual Machine
    Default: NONE on Unix Systems
             SystemDrive and SystemRoot wit appropriate values on Win32 systems

wrapper.env.copy=[name]
    An environment name with value copied from caller to JAVA Virtual Machine
    Default: NONE

wrapper.env.copyall=[true/false]
    Copies all environment from caller to JAVA Virtual Machine
    Default: "false"

wrapper.protocol=[name]
    Protocol used for signal handling
    Default: "ajpv11"

port=[number]
    Port used by Apache-JServ and for signal handling
    Default: 8007

security.authentication=[true/false]
    Whether Apache-JServ uses or not security (also signal handling uses this)
    Default: "true"

security.secretKey=[filename]
    File used by Apache-JServ and signal handling as a secret password
    Default: NONE
@


1.3
log
@Fixed Typo
@
text
@@


1.2
log
@Documented the --with-jdk-home option.
@
text
@d21 1
a21 1
                   --enable-apache-conf -prefix=/usr/local/etc/httpd
@


1.1
log
@a basic walk through of the installation procedure (this assumes
a few changes which haven't been made yet)
@
text
@d25 5
@

