integrating apache, jserv, and jrun with the inprise application server · 2002-05-21 · page 4 of...

Integrating Apache, JServ, and JRunwith the Inprise Application ServerScalable Multi-tier Architectures with the Inprise Application Server, theApache Web Server, Apache JServ, and Allaire JRun

January 2000

Salil [email protected]

Technology Tower Suite1000191 Coronado AveSan Carlos CA 94070-2805(650) 551-1600 voicehttp://www.customware.com/

OF 23

1 Table of Contents

1 TABLE OF CONTENTS.....................................................................................................................................................3

2 OVERVIEW...............................................................................................................................................................................4

3 CONVENTIONS USED IN THIS PAPER...................................................................................................................4

4 INSTALLING THE APACHE WEB SERVER........................................................................................................5

4.1 D OWNLOADING A PACHE.................................................................................................................................................5 4.2 C ONFIGURING THE A PACHE DISTRIBUTION................................................................................................................5 4.3 C OMPILING & I NSTALLING A PACHE............................................................................................................................6 4.4 B ASIC A PACHE O PERATIONS ..........................................................................................................................................7

5 INSTALLING JRUN WITH THE APACHE CONNECTOR............................................................................7

5.1 O BTAINING JR UN..............................................................................................................................................................7 5.2 I NSTALLING JR UN.............................................................................................................................................................7 5.3 D EALING WITH E XISTING A PACHE I NSTALLATIONS WITHOUT DSO S UPPORT..............................................9 5.4 M AKING SURE THAT JR UN USES THE CORRECT JVM, CLASSPATH , COMMAND LINE ARGUMENTS , ETC . 95.5 S TARTING & S TOPPING JR UN .......................................................................................................................................9 5.6 T ROUBLESHOOTING AND VIEWING LOGS.................................................................................................................10

6 INSTALLING JSERV.........................................................................................................................................................10

6.1 D OWNLOADING JS ERV..................................................................................................................................................10 6.2 C ONFIGURING THE JS ERV DISTRIBUTION .................................................................................................................11 6.3 C OMPILING AND I NSTALLING JS ERV.........................................................................................................................12 6.4 A Q UICK T EST..................................................................................................................................................................13 6.5 G ENERAL C ONFIGURATION OF JS ERV.......................................................................................................................13 6.6 T ESTING THE G ENERAL C ONFIGURATION................................................................................................................14

7 APPENDIX JSCONF THE JSERV CONFIGURATION FILE,/OPT/JSERV/SERVLETS/JSERV.CONF...........................................................................................................................15

8 APPENDIX JSPROPS: THE JSERV PROPERTIES FILE,/OPT/JSERV/SERVLETS/JSERV.PROPERTIES..........................................................................................................17

9 APPENDIX JSZONECONFIG: JSERV ZONE CONFIG,/OPT/JSERV/SERVLETS/SERVLETS.PROPERTIES...............................................................................................20

10 ABOUT THE AUTHOR................................................................................................................................................23

OF 23

2 Overview

This paper describes how to install and deploy the Inprise Application Server along with theApache web server, and two different servlet engines, Apache JServ, and Allaire JRun, on Solaris.

The paper describes the following scenarios, on Solaris:

n IAS4 + Apache Web Server + JServ servlet enginen IAS4 + Apache Web Server + JRun servlet engine

Descriptions of the following scenarios are found in the documentation for the Inprise ApplicationServer:

n IAS4 & built-in Java Web Server & Servlet Engine with “everything in-process”n IAS4 & built-in Java Web Server & Servlet Engine with each component in a

separate process (all on the same machine or each on multiple machines orcombinations thereof)

A future revision of this white paper may describe several other scenarios that are also easily possiblewith the Inprise Application Server, and may be important to some customers:

n IAS4 + Netscape Enterprise Server + JRun servlet enginen IAS4 + Microsoft Internet Information Server (IIS) + JRun servlet engine

3 Conventions used in this paper

On Solaris and other Unix operating systems, we install all our software underneath the directory“/opt”. This is just a choice we have made, and not a requirement You can install any of thesoftware anywhere you wish in the filesystem – when reading the examples, just replace “/opt” withwhatever is appropriate in your environment.

Sometimes, the location where the software is configured and compiled is different from where it iseventually installed. In those cases, we will use “/download” as our staging area. This is anarbitrary choice – you can choose any location in the filesystem as your staging area.

Our prompt contains the current directory followed by “>”, followed by the commands that userwould type. E.g.,

/opt/apache> ls

Root access is not required for any of the installations described here. Of course if you do not haveroot access, you cannot install to directories that allow write access only to root, and moreimportantly, cannot run servers that listen on port numbers below 1024, like 80 for HTTP.

Although low-level Unix details such as umasks etc. are not explicitly addressed by this whitepaper, we felt it was important to remind you that when installing IAS on Solaris, it is easier to getit up & running if you set your umask to 002, than to leave it at the standard 022.

OF 23

4 Installing the Apache Web Server

4.1 Obtaining Apache

Apache has been the most popular web server on the Internet since April of 1996. The May 1999WWW server site survey by Netcraft found that over 57% of the web sites on the Internet are usingApache (over 60% if Apache derivatives are included), thus making it more widely used than allother web servers combined.

The Apache server can be downloaded from http://www.apache.org/ or ftp://ftp.apache.org/dist/

For this paper, we downloaded Apache version 1.3.9 for Solaris. The Solaris distribution isprovided in source form, which requires you to configure the distribution and compile it, beforeinstalling.

Assume that the Apache distribution was downloaded and unpacked in /download/apache_1.3.9:

/download/apache_1.3.9>ls -1ABOUT_APACHEAnnouncementINSTALLKEYSLICENSEMakefileMakefile.tmplREADMEREADME.NTREADME.configureWARNING-NT.TXTcgi-bin/conf/config.layoutconfig.status*configure*htdocs/icons/logs/src/

The file INSTALL contains lots of good information.

4.2 Configuring the Apache distribution

This is the first step, and it is important that you do this correctly. Notice that at the top-level of thedistribution is an executable called “configure”. This executable auto-configures the rest of theapache distribution based on the platform on which it is being run, and based on parameters passedto it.

For our purposes, configure should be invoked as follows:

/download/apache_1.3.9> ./configure--prefix=/opt/apache--enable-rule=SHARED_CORE--enable-module=so

OF 23

Note that the command is shown on separate lines for readability, but should be issued all on oneline. Note also that options to configure are specified with two dashes, not just one.

The “prefix” option controls where Apache will be installed, when we give the “make install”command later.

The “enable-rule=SHARED_CORE” and “enable-module=so” options enable the so-called“DSO” option of Apache. It allows additional modules that provide special handling of requests tocertain URLs (e.g., servlet engines) to be installed later, without having to recompile Apache. So itis important to specify these options now because servlet engines we will use, and possibly otherweb server extension modules, will want to take advantage of this Apache feature.

The DSO feature uses the dlopen()/dlsym() system calls for dynamic loading of modules. Mostpopular operating systems are supported (Linux, FreeBSD, OpenBSD, NetBSD, BSDI, SunOS,Solaris, Irix, HPUX, Digital Unix, Unixware, AIX, SCO, ReliantUnix, DGUX, MacOS, MacOSX Server, OpenStep/Mach, and DYNIX/ptx), but not all. See the INSTALL file for more detail.

The INSTALL file also enumerates every single option to configure.

4.3 Do you need to use a staging area?

Whether or not you use a staging area for Apache as we do here is up to you. You could have justcopied the distribution to the location you wanted it installed (/opt/apache) and configured it there asfollows:

/opt/apache > ./configure--enable-rule=SHARED_CORE--enable-module=so

In particular, note that the other products this paper covers do not have built-in support for stagingareas. It may therefore be less confusing for you to not use staging areas at all.

Our Apache instructions here continue with the assumption that we are using staging areas.

4.4 Compiling & Installing Apache

Type the following commands in your staging area to compile and install Apache.

/download/apache_1.3.9> make/download/apache_1.3.9> make install

“make” will expect the Gnu C/C++ compiler, gcc, to be in the path, and use it to compile theApache distribution. Please visit http://www.gnu.org/ if you do not have gcc already. Any ANSI-Ccompiler will suffice; gcc version 2.7.2 or above are known to work; but gcc 2.91.66 isrecommended because it is easier to obtain (from GNU or Cygnus), easier to build on most Unixflavors, and more robust and reliable. On that note, you might consider using GNU make (gmake)because it is a far more robust make tool than /usr/ccs/bin/make on Solaris. As of this writing, thelatest version of gmake is 3.77.

“make install” will install Apache to the directory you specified in the “prefix” option to“configure” (/opt/apache in this document).

OF 23

Note for the paranoid hackers: the “make install” command really does install only under the prefix(/opt/apache) – no other files or directories are touched. You can also override the directory specifiedin the --prefix command as follows:

/download/apache_1.3.9> make install root=/someotherplace/apacheSee the INSTALL file for other related topics.

4.5 Basic Apache Operations

If Apache is installed by root, then it is automatically configured to listen at port 80 (the standardHTTP port); otherwise, it is automatically configured to listen at port 8080. This documentassumes that Apache was installed by a non-root user.

After installing, the configuration files make interesting reading, particularly:

/opt/apache/conf/httpd.conf

You need not read any of it initially, however. Start the Apache web server as follows:

/opt/apache/bin/apachectl start

and stop it as follows:

/opt/apache/bin/apachectl stop

Once the web server is up, try exercising it by pointing a web browser at:http://yourmachine.yourcompany.com:8080/ . Follow the links from there to access the Apache webserver manual. The documentation is also on the web at: http://www.apache.org/docs/

5 Installing JRun with the Apache Connector

5.1 Obtaining JRun

JRun is a Servlet Engine, and one of the earliest to market (and thus a market leader) in thiscategory. JRun also includes its own web server, but it is typically used only as a servlet engine,along with a higher-performance web server.

JRun can be downloaded from http://jrun.com/ or ftp://ftp.allaire.com/pub/jrun/

JRun was originally developed by Live Software, which has been acquired by Allaire Corporation(makers of Cold Fusion). Allaire is continuing to develop, support, market, and sell JRun.

For this paper, we downloaded a 30-day evaluation copy of JRun Pro 2.3.3 for Solaris.

5.2 Installing JRun

Unlike Apache & JServ, JRun is provided in binary format. JRun integrates with web servers usingthe appropriate extension-module technology for each web server. JRun has these “connectors”available for all the popular web servers, and even some unpopular ones.

Unlike Apache on Solaris, we found it more convenient to not use separate staging and install areasfor JRun. The following listing shows that we have unpacked the JRun archive in the location wewant to install it.

OF 23

/opt/jrun> lsLicense.txt Release.txt jsm-default/README bin/ lib/README.apache cfanywhere_readme.txt migration.resultREADME.nes connectors/ properties/README.novell contrib/ servlets/README.powertier docs/ temp/README.webl examples/ webl/README.zeus install.sh*Readme.txt instantdb/

The script “install.sh” will configure JRun by asking you a number of questions. These questions,and their answers (in bold) are shown below. After the answers, we indicate in parenthesis, whetherthe answer was the default answer.

Java found at /opt/jdk1.2.2/bin/javaTo migrate existing properties enter the older JRun roote.g.: /opt/JRun/2.2):

Enter Your JRun License Key (hit return for JRun free version):

Service Manager Admin Port for jsm-default: 56492 (default)Root Username for Remote JRun Admin: admin (default)Root Password for Remote JRun Admin: admin (default) 1 - Send *.cfm requests to <CF_Anywhere> 2 - Do not use <CF_Anywhere>Cold Fusion Handling Scheme: 2 (do not use CF_anywhere) (default) 1 - Map *.jsp requests to JSP 0.92 implementation 2 - Map *.jsp request to JSP 1.0 implementationJSP version: 1.0 (NOT default. Default is 0.92)Connector: 1 – Apache 1.2/1.3 2 – Netscape FastTrack/Enterprise 3 - Do not install a connector at this time

Select a connector to install: 1Enter the full path to the Apache conf directory:/opt/apache/confDo you want Apache DSO technology? YesApache version

Choices were 1.3.1-1.3.3, 1.3.4, 1.3.6(We chose the last one, since our Apache version was 1.3.9)

Connector proxy host: 127.0.0.1 (default)Connector proxy port: 8081 (default)Connector configuration was successful. RETURN to exit.

The connector proxy [host|port] are the host|port where the servlet engine listens for requests.Unlike the servlet engine built into the Java Web Server (bundled with Inprise Application Server),JRun’s servlet engine does not become part of the web server process. It is a separate process towhich the web server will forward all servlet-related requests, via the host|port specified here. Noticethat we’ve chosen 127.0.0.1 here since we expect to run the servlet engine on the same machine asthe web server.

Note that as part of the JRun installation, Apache’s httpd.conf file will be modified to include JRundirectives.

See the README and the README.apache files for more detail.

OF 23

5.3 Dealing with Existing Apache Installations without DSO Support

Notice that we answered Yes when we were asked whether to use DSO support for Apache. If yourapache installation does not have support for DSO, then your choices are:

1. reconfigure and recompile apache with DSO support, or

2. recompile apache with the JRun module built in

So if your existing Apache install does not already have DSO support there is no getting aroundrecompiling Apache.

5.4 Making sure that JRun uses the correct JVM, classpath, command line arguments, etc.

Once JRun is installed in /opt/jrun, it can be configured by modifying files in:

/opt/jrun/jsm-default/properties

The file jsm.properties is of particular interest because it controls some fundamental aspects of theservlet engine, like the JVM. Our jsm.properties file looked something like this:

jrun.rootdir=..jrun.api21=falseredirect.stderr=trueredirect.stdout=trueadmin.port=56492admin.bindaddress=*java.securitymanager=java.path=/opt/jrun/examples/jni/NativeHelloWorldjava.exe=/opt/jdk1.2.2/bin/java

java.classpath=/opt/jrun/lib/jrun.jar:/opt/jrun/lib/servlet.jar:/opt/jrun/lib/jsp.jar:/opt/jrun/lib/xml4j.jar:/opt/jrun/lib/xt.jar:/opt/jrun/lib/fesi.jar:/opt/jrun/lib/cfanywhere.jar:/opt/jrun/lib/NetComponents.jar:/opt/jrun/lib/OROMatcher.jar:/opt/jrun/lib/jrunadmin/jrunadmin.jar:/opt/jrun/classes:/opt/jrun/jsm-default/classes:/opt/jrun/instantdb/Classes:/opt/jrun/lib/jrunadmin/swing.jar:/opt/jrun/webl/WebL.jar:/opt/jrun/examples/jni:/opt/ias/ejb_jars/ejbcontainer/cartbeans.jar:/opt/ias/lib/vbjorb.jar:/opt/ias/lib/ins.jar:/opt/ias/lib/vbejb.jar

java.args=-native -Dvbroker.agent.port=8322 \-Dorg.omg.CORBA.ORBClass=com.inprise.vbroker.orb.ORB \-Dorg.omg.CORBA.ORBSingletonClass=com.inprise.vbroker.orb.ORB

Notice that we modified the java.exe property to use the JVM that we wanted. Notice also that tojava.classpath we have added the jar files associated with the Inprise Application Server (in thisscenario, installed in /opt/ias) so that our servlets can easily become EJB clients. And for similarreasons, we’ve added CORBA/VisiBroker-related arguments to the java.args property. For moredetails on these properties, refer to the VisiBroker Programmers Manual.

5.5 Starting & Stopping JRun

JRun has a command similar to Apache to start and stop the servlet engine:

OF 23

/opt/jrun/jsm-default/jsmctl [start|stop]

With Apache and JRun configured as above, you can start and stop them in either order. Of course,both of them have to be running in order for you to invoke servlets.

Upon issuing “jsmctl start” you should see something like:

Starting jrun:JRun 2.3.3 build 153 starting…Log started: Thu Oct 31 12:00:00 PDT 1999JRun Servlet Engine (JCP) Started.JRun Connector Proxy Started on port 8081.JRun Servlet Engine (JWS) Started.JRun Web Server Started on port 8080.JRun 2.3.3 build 153 Ready.…

The “Java Web Server” mentioned above is a low-end web server that ships with JRun. We willnot be using this web server since we’re obviously using the higher-end Apache web server instead.If you have installed as root, that web server starts on port 8000, not 8080.

By default, servlets are placed in a directory named “servlets” in the top-level of the JRuninstallation directory, i.e., /opt/jrun/servlets

To verify your JRun installation, try invoking the sample Counter servlet from a browser viaApache as follows:

http://yourmachine.yourcompany.com:8080/servlet/Counter

This servlet sends the browser a cookie containing an initial value of 10 and increments this counteron each subsequent visit.

5.6 Troubleshooting and viewing logs

You can view the Standard Out and Standard Error of your servlets by viewing the following files

/opt/jrun/jsm-default/logs/stdout.log/opt/jrun/jsm-default/logs/stderr.log

You can view the Standard Out and Standard Error of the servlet engine itself by viewing:

/opt/jrun/jsm-default/logs/event.log/opt/jrun/jsm-default/services/jse/logs/event.log/opt/jrun/jsm-default/services/jse/logs/error.log

6 Installing JServ

6.1 Obtaining JServ

JServ is a free, 100% pure Java servlet engine, compliant with the JavaSoft Java Servlet APIs 2.0specification. The Apache JServ project is part of the Java Apache Project. JServ can be downloadedfrom:

OF 23

http://java.apache.org/jserv/index.html or ftp://ftp.apache.org/java/jserv/dist

At this moment, the Apache JServ distribution contains only a module for the Apache Web Server(mod_jserv).

6.2 Configuring the JServ distribution

Like Apache, JServ is distributed in source format. We assume that JServ has been downloaded andunpacked in the location /download/ApacheJServ-1.0:

/download/ApacheJServ-1.0> lsINSTALL config.status*Makefile config.cacheMakefile.am configure*Makefile.in configure.inREADME docs/acinclude.m4 example/aclocal.m4 index.htmlconf/ libtool*config.log src/

Like Apache, JServ must be auto configured with the configure script provided with thedistribution.

IMPORTANT NOTE: JServ’s configure script requires Perl version 5.003 or later. If you have anolder version of Perl, or if there is no Perl in your path, then the configure script will fail with anerror. To complicate matters, due to a bug in the configure script, the error message is incorrect andextremely misleading:

“Apache not configured with DSO”

…even though you have correctly configured it with DSO as described above in the Apache install.

The solution is to obtain Perl 5.003 or later and make sure that is the first perl in your PATH(preferably the only perl in your PATH), and preferably also installed in /usr/bin/perl.

The other solution, which is the one we used, is to edit the two scripts in the Apache Web Server (not JServ) distribution to explicitly use the proper version of Perl.

The two scripts are:

/opt/apache/bin/apxs/opt/apache/bin/dbmanage

We changed the first line in both of these scripts from “#!/usr/bin/perl”, to “#!/opt/perl/bin/perl”,which is where our Perl 5.003 was installed.

Having installed Perl as described above, and having configured the scripts to use the correct Perl,we are ready to call JServ’s configure:

/download/ApacheJServ-1.0> ./configure--prefix=/opt/jserv--with-apache-install=/opt/apache--with-jdk-home=/opt/jdk1.2.2--with-jsdk=/opt/JSDK2.0

OF 23

Note that the command is shown on separate lines for readability, but should be issued all on oneline. Note again that options to configure are specified with two dashes, not just one.

The “prefix” option controls where JServ will be installed, when we give the “make install”command later.

The “with-apache-install” option controls which Apache installation the JServ module will beadded to. It is not recommended that you add the JRun and JServ modules to the same Apacheinstallation!

The “with-jdk-home” option tells configure the location of the JDK we wish to use.

And the “with-jdsk” option tells configure the location of the Java Servlet Development Kit(JSDK). The JSDK serves as the reference implementation for the Java Servlet API. The JSDKdistribution is available from Sun at http://java.sun.com/ . The JSDK exists to provide Servlet APIson top of JDK 1.1.x. If you are only interested in developing servlets with JDK 1.2 and later, thereis no need to use the JSDK as the servlet API is bundled with JDK1.2 – in this case there is noneed to specify this option to configure. There is one gotcha here though: this version of JServexactly version 2.0 of the JDSK in order to operate properly. Any other version (older ornewer), including the version that comes with the JSP jar file, is not supported. Therefore, consideradding the jar file for JSDK2.0 near the beginning of your CLASSPATH, to ensure that no JDKclass definitions override the JSK2.0 ones.

Our next step will be to follow the directions specified in the output of a successful configure.Example output from a successful configure:

Configuration complete.

Apache Directory: /opt/apacheApache Version: 1.3Module Type: dynamic (DSO will be used to link mod_jserv into serverdynamically)Apache include flags: -I/opt/apache/include

Run make to compile the Java portion of Apache JServ.

Then, to run the example configuration, put this in your httpd.conf:

Include /opt/jserv/example/jserv.conf

Then try visiting the URL:

http://yourmachine:SERVER_PORT/example/Hello

If that works then you have successfully setup Apache JServ.If that does not work then you should consult the FAQ-O-MaticURL referenced below.You might consider putting frequently used options into ./configure-options

For further information please read the documentation in the docsdirectory.

Many frequently asked questions are answered in the FAQ-O-Matic:

http://java.apache.org/faq/

6.3 Compiling and Installing JServ

As we did with Apache, we now compile the distribution with make, and install it with makeinstall:

OF 23

/download/ApacheJServ-1.0> make/download/ApacheJServ-1.0> make install

It is important to note that despite the similarity in the look and feel of the Apache and JServinstallers, JServ at the time of this writing does not actually support staging. Attempting to usestaging will result in a confusing configuration.

6.4 A Quick Test

As the output of configure specifies, you will need to edit file /opt/apache/conf/httpd.conf. Inparticular, adding a line of the form:

Include /opt/jserv/example/jserv.conf

…will allow you to run the sample servlet (Hello) that is in the examples subdirectory of the JServdistribution.

Then ensure that your set-up is working by pointing your browser at:

http://yourmachine.yourcompany.com:8080/example/Hello

Again, a reminder that if you’ve installed as root, the default port number is 80, not 8080.

6.5 General Configuration of JServ

The quick test is sufficient to test the installation but is not the general solution. A more generalapproach is to first add a line of the following form to file /opt/apache/conf/httpd.conf:

Include /opt/jserv/servlets/jserv.conf

Next, in directory /opt/jserv, create a subdirectly named “servlets”. This is where your servletclasses will go. You will also need to create a file named jserv.conf in the /opt/jserv/servletsdirectory because we’ve obviously configured Apache’s httpd.conf to include that file. Save yourselftime by copying /opt/jserv/examples/jserv.conf into /opt/jserv/servlets. Repeat the process for filejserv.properties:

/opt/jserv> mkdir servlets/opt/jserv> cd servlets/opt/jserv/servlets> cp ../example/jserv.conf ./opt/jserv/servlets> cp ../example/jserv.properties .

In jserv.conf, change the values of the attributes ApJServProperties, ApJServLogFile, andApJServMount to the following:

ApJServProperties /opt/jserv/servlets/jserv.propertiesApJServLogFile /opt/jserv/servlets/jserv.logApJServMount /servlet /servlets

The first line specifies the name of the file that contains the properties for the servlet engine itself –more on that shortly. The second line specifies where we want log messages to go. And the thirdline specifies that this servlet engine will be handling URLs of the form http://host:port/servlet/*and that the servlets will be located in subdirectory servlets.

The complete jserv.conf file is shown in Appendix JSCONF.

OF 23

We now turn our attention to the jserv.properties file. Just as we did for JRun, we must set certainservlet engine wide properties that will allow our servlets to become EJB and CORBA clients. Thefollowing settings for properties wrapper.bin.parameters and wrapper.classpath accomplish that:

wrapper.bin.parameters=-native -Dvbroker.agent.port=8322 \-Dorg.omg.CORBA.ORBClass=com.inprise.vbroker.orb.ORB \-Dorg.omg.CORBA.ORBSingletonClass=com.inprise.vbroker.orb.ORB

wrapper.classpath=/opt/jserv/src/java/ApacheJServ.jarwrapper.classpath=/opt/JSDK2.0/lib/jsdk.jarwrapper.classpath=/opt/ias/ejb_jars/ejbcontainer/cartbeans.jarwrapper.classpath=/opt/ias/lib/vbjorb.jarwrapper.classpath=/opt/ias/lib/ins.jarwrapper.classpath=/opt/ias/lib/vbejb.jar

Note that the wrapper.bin.parameters properties are shown on separate lines for readability, butshould be specified all on one line.

Next we define a zone named “servlets” (corresponding to our subdirectory “servlets”) and specifywhere the properties for that zone are found. See the JServ documentation for more information aboutservlet zones.

zones=servletsservlets.properties=/opt/jserv/servlets/servlets.properties

The complete jserv.properties file is shown in Appendix JSPROPS.

One last file that is required for this setup, is /opt/jserv/servlets/servlets.properties, the one we justspecified as the value to servlets.properties. Save yourself time by copying the sample from theexamples directory as follows:

/opt/jserv/servlets> cp ../example/example.properties servlets.properties

Now change the value of the repositories property to be your “servlets” directory as follows:

repositories=/opt/jserv/servlets

Multiple repositories for servlets can be specified by specifying multiple lines beginning with“repositories=”.

The complete servlets.properties file is shown in Appendix JSZONECONFIG.

6.6 Testing the General Configuration

Write a simple servlet and compile it and place the .class file in /opt/jserv/servlets. Or if you’vepreviously installed JRun, simply copy Counter.class from the JRun servlets directory and place itin /opt/jserv/servlets.

After ensuring that the Apache web server is running, try accessing your servlet as usual:

http://yourmachine.yourcompany.com:8080/servlet/Counter

You should now be able to drop arbitrary servlets into the /opt/jserv/servlets directory and accessthem with URLs similar to the above.

OF 23

7 Appendix JSCONF:The JServ Configuration File, /opt/jserv/servlets/jserv.conf

################################################################################ Apache JServ Configuration File ################################################################################

# Note: this file should be appended to httpd.conf# Tell Apache on win32 to load the Apache JServ communication moduleLoadModule jserv_module libexec/mod_jserv.so

# Whether Apache must start JVM or not (On=Manual Off=Autostart)# Syntax: ApJServManual [on/off]# Default: "Off"ApJServManual off

# Properties filename for Apache JServ in Automatic Mode.# In manual mode this directive is ignored# Syntax: ApJServProperties [filename]# Default: "./conf/jserv.properties"ApJServProperties /opt/jserv/servlets/jserv.properties

# Log file for this module operation relative to Apache root directory.# Syntax: ApJServLogFile [filename]# Default: "./logs/mod_jserv.log"# Note: when set to "DISABLED", the log will be redirected to Apache error logApJServLogFile /opt/jserv/servlets/jserv.log

# Protocol used by this host to connect to Apache JServ# (see documentation for more details on available protocols)# Syntax: ApJServDefaultProtocol [name]# Default: "ajpv11"ApJServDefaultProtocol ajpv11

# Default host on which Apache JServ is running# Syntax: ApJServDefaultHost [hostname]# Default: "localhost"#ApJServDefaultHost

# Default port that Apache JServ is listening to# Syntax: ApJServDefaultPort [number]# Default: protocol-dependant (for ajpv11 protocol this is "8007")ApJServDefaultPort 8007

# Passes parameter and value to specified protocol.# Syntax: ApJServProtocolParameter [name] [parameter] [value]# Default: NONE# Note: Currently no protocols handle this. Introduced for future protocols.

# Apache JServ secret key file relative to Apache root directory.# Syntax: ApJServSecretKey [filename]# Default: "./conf/jserv.secret.key"# Warning: if authentication is DISABLED, everyone on this machine (not just# this module) may connect to your servlet engine and execute servlet# bypassing web server restrictions. See the documentation for more informationApJServSecretKey DISABLED

# Mount point for Servlet zones# (see documentation for more information on servlet zones)# Syntax: ApJServMount [name] [jserv-url]# Default: NONE# Note: [name] is the name of the Apache URI path to mount jserv-url on# [jserv-url] is something like "protocol://host:port/zone"# If protocol, host or port are not specified, the values from# "ApJServDefaultProtocol", "ApJServDefaultHost" or "ApJServDefaultPort"# will be used.# If zone is not specified, the zone name will be the first subdirectory of# the called servlet.

OF 23

# Example: "ApJServMount /servlets /myServlets"# if user requests "http://host/servlets/TestServlet"# the servlet "TestServlet" in zone "myServlets" on default host# thru default protocol on defaul port will be requested# Example: "ApJServMount /servlets ajpv11://localhost:8007"# if user requests "http://host/servlets/myServlets/TestServlet"# the servlet "TestServlet" in zone "myServlets" will be requested# Example: "ApJServMount /servletsajpv11://jserv.mydomain.com:15643/myServlets"# if user requests "http://host/servlets/TestServlet" the servlet# "TestServlet" in zone "myServlets" on host "jserv.mydomain.com" using# "ajpv11" protocol on port "15643" will be executedApJServMount /servlet /servlets

# Whether <VirtualHost> inherits base host mount points or not# Syntax: ApJServMountCopy [on/off]# Default: "On"# Note: This directive is meaninful only when virtual hosts are being usedApJServMountCopy on

# Executes a servlet passing filename with proper extension in PATH_TRANSLATED# property of servlet request.# Syntax: ApJServAction [extension] [servlet-uri]# Defaults: NONE# Notes: This is used for external tools such as JSP (Java Servlet Pages),# GSP (GNU Server Pages) or Java server side include.#ApJServAction .jsp /servlets/nl.nmg.jsp.JSPServlet#ApJServAction .gsp /servlets/com.bitmechanics.gsp.GspServlet#ApJServAction .jhtml /servlets/org.apache.servlet.ssi.SSI

# Enable the Apache JServ status handler with the URL of# "http://servername/jserv/" (note the trailing slash!)# Change the ".your_domain.com" to match your domain to enable.<Location /jserv/> SetHandler jserv-status

order deny,allow deny from all allow from localhost 127.0.0.1</Location>

############################## W A R N I N G ################################### Remember to disable or otherwise protect the execution of the Apache JServ ## on a production environment since this may give untrusted users to gather ## restricted information on your servlets and their initialization arguments ################################################################################

OF 23

8 Appendix JSPROPS:The JServ Properties File, /opt/jserv/servlets/jserv.properties

#################################### Apache JServ Configuration File ####################################

################################### WARNING##################################### Unlike normal java properties, JServ configurations# have some important extentions:## 1) commas are used as token separators# 2) multiple definitions of the same key# are concatenated in a comma separated list.################################################################################

# Execution parameters#######################

# The Java Virtual Machine interpreter# Syntax: wrapper.bin=[filename]# Default: "/usr/bin/java" for Unix systems# "c:\jdk\bin\java.exe" for Win32 systemswrapper.bin=/opt/jdk1.2.2/bin/java

# Arguments passed to java interpreter (optional)# Syntax: wrapper.bin.parameters=[string]# Default: NONEwrapper.bin.parameters=-native -Dvbroker.agent.port=8322 -Dorg.omg.CORBA.ORBClass=com.inprise.vbroker.orb.ORB -Dorg.omg.CORBA.ORBSingletonClass=com.inprise.vbroker.orb.ORB

# Apache JServ entry point class# Syntax: wrapper.class=[classname]# Default: "org.apache.jserv.JServ"wrapper.class=org.apache.jserv.JServ

# Arguments passed to main class after the properties filename# Syntax: wrapper.class.parameters=[string]# Default: NONE# Note: currently not used

# PATH environment value passed to the JVM# Syntax: wrapper.path=[path]# 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 wether Unix or Win32) characters# Under Win32 (windows-dir) and (windows-system-dir) will be# automatically evaluated to match your system requirements

# CLASSPATH environment value passed to the JVM# Syntax: wrapper.classpath=[path]# 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 wether Unix or Win32) characters.# JVM must be able to find JSDK and JServ classes and any# utility classes used by your servlets.#wrapper.classpath=wrapper.classpath=/opt/jserv/src/java/ApacheJServ.jarwrapper.classpath=/opt/JSDK2.0/lib/jsdk.jarwrapper.classpath=/opt/ias/ejb_jars/ejbcontainer/cartbeans.jarwrapper.classpath=/opt/ias/lib/vbjorb.jarwrapper.classpath=/opt/ias/lib/ins.jarwrapper.classpath=/opt/ias/lib/vbejb.jar

OF 23

# An environment name with value passed to the JVM# Syntax: wrapper.env=[name]=[value]# Default: NONE on Unix Systems# SystemDrive and SystemRoot with appropriate values on Win32 systems

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

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

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

# General parameters######################

# Set the port JServ will listen to.# Syntax: port=[1024,65535] (int)# Default: 8007port=8007

# Servlet Zones parameters###########################

# List of servlet zones JServ manages# Syntax: zones=<servlet zone>,<servlet zone>... (Comma separated list ofString)# Default: <empty>zones=servlets

# Configuration file for each servlet zone# Syntax: <servlet zone name as on the zones list>.properties=<full path toconfigFile> (String)# Default: <empty>servlets.properties=/opt/jserv/servlets/servlets.properties

# Security parameters#####################

# Enable/disable the execution of org.apache.jserv.JServ as a servlet.# This is disabled by default because it may give informations that should# be restricted.# Note that the execution of JServ as a servlet is filtered by mod_jserv# by default so that both sides should be enabled to let this service work.# This service is useful for installation and configuration since it gives# feedback about the exact configurations JServ is set with, but it should# be disabled when both installation and configuration processes are done.# Syntax: security.selfservlet=[true,false] (boolean)# Default: false#security.selfservlet=true

# Set the maximum number of socket connections JServ may handle simultaneously.# (this number does not identify the maximum number of concurrent servlet# requests: see the JServ protocol specification for more info on this)# Syntax: security.maxConnections=(int)>1# Default: 50# security.maxConnections=50security.maxConnections=1024

# List of IP addresses allowed to connect to JServ. This is a first security# filtering to reject possibly unsecure connections and avoid the overhead# of connection authentication.# Syntax: security.allowedAddresses=<IP address>,<IP Address>... (Commaseparated list of IP adresses)# Default: <empty list>security.allowedAddresses=127.0.0.1

# Enable/disable connection authentication.

OF 23

# NOTE: unauthenticated connections are a little faster since authentication# handshake is not performed at connection creation.# WARNING: disable authentication only if you can protect the intrusion on# the port JServ listens on with other systems or do it at your own risk.# Syntax: security.authentication=[true,false] (boolean)# Default: truesecurity.authentication=false

# Authentication secret key.# The secret key is passed as a file that must be kept secure and must# be exactly the same of those used by clients to authenticate themselves.# Syntax: security.secretKey=<secret key file> (String)# Default: <empty>#security.secretKey=

# Length of the randomly generated challenge string (in bytes) used to# authenticate connections. 5 is the lowest possible choice to force a safe# level of security and reduce connection creation overhead.# Syntax: security.challengeSize=(int)>5# Default: 5security.challengeSize=5

# Logging parameters####################

# Enable/disable JServ tracing, used for debugging and development.# WARNING: tracing is a very costy operation in term of performance and# its disabled by default. Note that trace logs may become really big# since each servlet connection may generate many Kb of log.# Syntax: log=[true,false] (boolean)# Default: falselog=false

# Set the name of the trace/log file. To avoid possible confusion about# the location of this file, an absolute pathname is recommended.# On Unix, this file must have write permissions by the owner of the JVM# process. In other words, if you are running Apache JServ in manual mode# and Apache is running as user nobody, then the file must have its# permissions set so that that user can write to it.# Syntax: log.file=<log file name> (String)# Default: NONElog.file=jserv.log

# Enable the timestamp before the log message# Syntax: log.timestamp=[true,false] (boolean)# Default: truelog.timestamp=true

# Use the given string as a data format# (see java.text.SimpleDateFormat for the list of options)# Syntax: log.dateFormat=(String)# Default: [dd/MM/yyyy HH:mm:ss:SSS zz]log.dateFormat=[dd/MM/yyyy HH:mm:ss:SSS zz]

# Enable/disable channels, each logging different part of the code# self-explained by their names.# Syntax: log.channel.<channel name>=[true,false] (boolean)# Default: falselog.channel.servletLog=truelog.channel.init=truelog.channel.terminate=truelog.channel.serviceRequest=truelog.channel.authentication=truelog.channel.requestData=truelog.channel.responseHeaders=truelog.channel.signal=truelog.channel.exceptionTracing=truelog.channel.servletManager=true

OF 23

9 Appendix JSZONECONFIG:JServ Zone Config, /opt/jserv/servlets/servlets.properties

################################################################################ Servlet Zone Configuration File ################################################################################

################################ W A R N I N G ################################## Unlike normal Java properties, JServ configurations have some important# extentions:## 1) commas are used as token separators# 2) multiple definitions of the same key are concatenated in a# comma-separated list.################################################################################

# List of Repositories#######################

# The list of servlet repositories controlled by this servlet zone# Syntax: repositories=[repository],[repository]...# Default: NONErepositories=/opt/jserv/servlets

# Classloader parameters#########################

# Enable servlet class autoreloading.# Syntax: autoreload.classes=[true,false] (boolean)# Default: trueautoreload.classes=true

# Enable servlet resourced autoreloading (properties and other loadedresources)# Syntax: autoreload.file=[true,false] (boolean)# Default: trueautoreload.file=true

# Set the number of millisecond to wait before giving up on initializing aservlet.# (a timeout of zero means no timeout)# Syntax: init.timeout=(long)>0# Default: 10000 (10 secs)init.timeout=10000

# Set the number of millisecond to wait before giving up on destroying aservlet.# (a timeout of zero means no timeout)# Syntax: destroy.timeout=(long)>0# Default: 10000 (10 secs)destroy.timeout=10000

# Set the number of millisecond to wait before invalidating an unused session.# Syntax: session.timeout=(long)>0# Default: 1800000 (30 mins)session.timeout=1800000

# Set how frequently (milliseconds) to check for timed-out sessions.# Syntax: session.checkFrequency=(long)>0# Default: 30000 (30 secs)session.checkFrequency=30000

# SingleThreadModel Servlets parameters########################################

# Set the initial capacity of the STM servlets pool.

OF 23

# Syntax: singleThreadModelServlet.initialCapacity=(int)>1# Default: 5singleThreadModelServlet.initialCapacity=5

# Set the number of servlet instances should be added to the pool if foundempty.# Syntax: singleThreadModelServlet.incrementCapacity=(int)>1# Default: 5singleThreadModelServlet.incrementCapacity=5

# Set the maximum capacity of the STM pool# Syntax: singleThreadModelServlet.maximumCapacity=(int)>1# Default: 10singleThreadModelServlet.maximumCapacity=10

################### S E R V L E T P A R A M E T E R S ######################

################################## N O T E ##################################### When "classname" is specified, it means a Java dot-formatter full class name# without the ".class". For example, a class with source file named# "Dummy.java" with a package name "org.fool" is defined as "org.fool.Dummy".## Since each servlet may have lots of private initialization data, Apache JServ# allows you to store those servlet initArgs in a separate file. To do this,# simply do not set any initArgs in this file: Apache JServ will then look for# a file named "[servlet classname].initargs" in the same directory of that# class. Note that this may work with even class archives.###############################################################################

# Startup Servlets###################

# Comma or space delimited list of servlets to launch on startup.# This can either be a class name or alias.# Syntax: servlets.startup=[classname or alias],[classname or alias],...# Default: NONE# servlets.startup=hello,snoop,org.fool.Dummy

# Servlet Aliases##################

# This defines aliases from which servlets can be invoked.# Each alias give a new instance of the servlet. This means that if a servlet# is invoked both by class name and by alias name, it will result in _TWO_# instances of the servlet being created.# Syntax: servlet.[alias].code=[classname] (String)# Default: NONE# servlet.snoop.code=SnoopServlet# servlet.hello.code=org.fool.Dummy

# Global Init Parameters#########################

# Parameters passed here are given to each of servlets. You should put# configuration information that is common to all servlets.## The value of the property is a comma delimited list of "name=value" pairs# that are accessible to the servlet via the method getInitParameter()# in ServletConfig.# Syntax: servlets.default.initArgs=[name]=[value],[name]=[value],...# Default: NONE# servlets.default.initArgs=common.to.everybody=Hi everybody!

# Servlet Init Parameters##########################

# These properties define init parameters for each servlet that is invoked# by its classname.# Syntax: servlet.[classname].initArgs=[name]=[value],[name]=[value],...# Default: NONE# servlet.org.fool.Dummy.initArgs=message=I'm a dummy servlet

OF 23

# Aliased Servlet Init Parameters##################################

# These properties define init parameters for each servlet that is invoked# by its alias.# Syntax: servlet.[alias].initArgs=[name]=[value],[name]=[value],...# Default: NONE# servlet.snoop.initArgs=message=I'm a snoop servlet# servlet.hello.initArgs=message=I say hello world to everyone

OF 23

10 About The Author

This white paper was written by CustomWare at Inprise’s invitation to review their IAStechnology.

Salil Deshpande is President & Chief Technical Officer of CustomWare, a company that providestraining & consulting on Enterprise Java Beans (EJB) and other Enterprise Java and J2EEtechnologies, including CORBA & IIOP. CustomWare is an authorized training and consultingpartner for most of the enterprise Java vendors, such as Borland/Inprise, BEA/WebLogic, IBM, SunMicrosystems, Persistence Software, and many others. Prior to CustomWare, Salil was thePresident of a training & consulting company focusing on CORBA, which was acquired byCORBA vendor Visigenic Software. Salil received an MS in EE/CS from Stanford University in1991 and a BS in EE/CS from Cornell University in 1989.

integrating apache, jserv, and jrun with the inprise application server · 2002-05-21 · page 4 of...

Documents