j run setup guide

7/31/2019 j Run Setup Guide

1/34

LIVE SOFTWARE, INC.

JRun SetupGuide

Version 2.3


2/34

J R U N I N S T A L L A T I O N G U I D E

1

L I VE SO F T WAR E , I N C .

JRun Setup Guide

Version 2.3

1999 Live Software, Inc.20245 Stevens Creek Blvd, Suite 100

Cupertino, CA [email protected]

http:/ / www.livesoftware.com


3/34


2

What is JRun?..................................................................................................................3

JRun Services ..................................................................................................................5

Requirements for JRun.....................................................................................................6

Installation Options:.........................................................................................................6

Instructions for JRun Installation with Apache under UNIX/Linux: ..................................6Running JRun Setup for Windows systems.......................................................................8

Running JRun Setup for Unix systems..............................................................................8Running JRun Setup for Other Java systems .....................................................................8

Running JRun Setup for MacOS systems..........................................................................8

JRun Setup Wizard ..........................................................................................................8

Proxy Host and Port .......................................................................................................14

Select JRun Service Manager ......................................................................................... 14

Installing a connector for IIS .......................................................................................... 14

Installing a connector for Netscape.................................................................................15

Netscape Connector Types .............................................................................................16Server Version............................................................................................................... 16

Netscape https or httpd directory ....................................................................................16

Installing a connector for Apache ...................................................................................17Commiting the data........................................................................................................17

IIS/PWS Server Configuration .......................................................................................18

.JRun Mapping with IIS 4.0 ...........................................................................................20

Security with IIS 4.0 ......................................................................................................20

Netscape Server Configuration.......................................................................................21

WebSite Pro Server Configuration .................................................................................22

Mapping a URL Prefix to Run Servlets ..........................................................................22

Mapping a URL Prefix to Run a Specific Servlet ............................................................23

Multi-Homing and URL Prefixes ...................................................................................24Mapping File Extensions to JRun ...................................................................................26

Java-Based Servers Configuration ..................................................................................28

Installing a new License Key.......................................................................................... 28JRun Directory Structure................................................................................................31

JSE Service Directory Structure .....................................................................................32


4/34


3

What is JRun?JRun was first developed by LiveSoftware in 1997 as software for servlet enabling

Web servers. Today, JRun has evolved into a Java server with various capabilities.JRun is a robust, cross-platform Java server that includes an award winning Java

servlet runner, a Java Server Pages (JSP) compilation engine, and an optional Javaweb server. JRun is used today for servlet-enabling Web servers and enjoys the

widest Web server compatibility coverage of any servlet engine on the markettoday.

JRun supports Novell Netware, UNIX, LINUX, Windows NT, Windows 95/98, andMacOS. In addition, it has a simple design allowing it to work with a large variety

of existing Web servers including Netscape, WebStar, OReillys WebSite Pro,Microsoft IIS, Microsoft Personal Web Server (PWS), and Apache. With JRun,

organizations can deploy dynamic Web sites on almost any platform.

JRun ArchitectureThis section explains the architecture of JRun and the responsibilities of its maincomponents. Understanding the JRun architecture will eventually allow you to takefull advantage of what this flexible environment has to offer. A core advantage of

JRun is its ability to be extended and built upon.

The main component of JRun is the JRun Service Manger (JSM). The JSM isresponsible for loading and initializing services, or protocol-independent

components that provide specific functionality. Three such services are includedwith JRun:

JRun Servlet Engine (JSE) Service: JSE is responsible for running and handlingJava Servlets. JSE is at the heart of the JSM as it allows any service to run servlets.

JRun Connector Proxy Service: The connector proxy service facilitatescommunication between any external source (such as a web server or application

server) and JSE.

JRun Web Server Service: The web service is a fast and light-weight all-Java web

server that is provided as a basic web server so that servlets and web pages can runindependent of a native web server.

Chapter

1


5/34


4

Relationship to the Web Server

The JRun Service Manager runs as its own process, or as an independent entity. Theservices that are included within the JSM (JRun Servlet Engine, JRun Connector

Proxy Service, and JRun Web Server) run as independent processes as well, or "out-of-process." A web server (for example, Apache) simply acts as a client that talks

indirectly to applicable services.

There are several advantages to this out-of-process model. Servlet developers can

now select the type of Java Virtual Machine (JVM) they want to run with theirservlets independent of the JVM that is supplied by their web server. For example, a

servlet developer running Netscape's Enterprise Server can choose to run his or herservlets (including servlets generated from files with the .jsp extension) with Sun's

or Microsoft's JVM rather than the JVM included with the Netscape server(additionally, JRun Pro allows you to run multiple JVMs at the same time). The out-

of-process model includes several additional advantages: increased stability of theweb server, the ability to bring a web server up and down independently of JRun,

and the ability for a single service (particularly the JRun Servlet Engine) to talk tomultiple web servers.

Because a web server acts as a client that talks indirectly to the services, in order for

a web server to talk to JRun Servlet Engine (JSE), it needs to establish some sort ofconnection. JRun provides and installs a native connector in the web server that is

responsible for making the connection from the web server to JSE. When a requestcomes in for a servlet, the native connector opens a socket connection to the JRun

Connector Proxy Service residing within JSM. The JRun Connector Proxy Serviceserves as a transparent communicator and translates the request coming from the

native connector on to the JSE Service. The JSE Service handles the request andsends its reply back to the JRun Connector Proxy service.

The JSE Service does not know how to talk through sockets this is why it relies on

the JRun Connector Proxy service to talk through the socket back to the web server.Figure 1 illustrates the communication between web servers and the JRun Servlet

Engine Service.


6/34


5

Figure 4-1: JRun Architecture

JRun ServicesWith release 2.3, JRun includes an API allowing advanced developers to create and

deploy custom Java services and virtually any platform. These are managed withinthe JRun Enterprise Services Manager (See Figure 1-2). This is quite useful as it

provides a simple mechanism for developing and deploying servers across multipleplatforms---without changing any code. In addition, the JRun Services API handles

basic threading and connection management.

JRun ServletRunner

SMTPService

CustomService A

CustomService B

Figure 1-2: JRun Services Manager Architecture


7/34


6

Installing JRun

Requirements for JRun

In order to use JRun all you need is a Java Development Kit. On Windowsplatforms JRun ships with a Java Runtime Environment (JRE) so if you do not plan

on using JSP you do not need to download a JDK (JSP makes use of the Javacompiler that comes with the JDK). On non-Windows platforms JRun does not

ship with a JRE so a JDK must be installed already.

It is also recommended that you have at least 32MB of RAM. The more memory

the better your system will perform.

Installation Options:

JRun comes with four installation options:

Windows Installer this is a self extracting exe for Windows 95,98, NT andNovell.

.sit archive this is a StuffIt file for MacOS installations.

tar archive a compressed tar file.

In addition users of the Apache Server and Netscape Enterprise Server may need to

take additional steps. Please see the README.apache and README.nes files in the

root level of the distribution for more information on these platforms. UnderWindows this is not required for either server.

Instructions for JRun Installation with Apache underUNIX/Linux:

Chapter

2


8/34


7

JRun supports two methods for running servlets with your Apache server. For

all versions of Apache JRun can be compiled into the server by following thedirections for Apache Static Module under the appropriate version (1.2 or

1.3). Static module usage is recommendly only for those whose systems do not

support Dynamic Shared Objects, or DSO for short.

Using DSO support the JRun Apache module can be used much like a dll on

Windows. It is recommended to use DSO if you are using a 1.3.x version ofApache. Not only is it easier to build Apache using DSO module, some

platforms (like RedHat Linux 5.2) come with Apache pre-built with DSOsupport, which means that Apache need not be recompiled.

After building and installing Apache it needs to be configured to talk to JRun. This

is done via the Connector Wizard which is documented later in this chapter.

Apache DSO Module :

NOTE: You must have Apache 1.3.x in order for this to work

Configure Apache with the following command:

./configure -prefix=/user/local/apache -enable-

rule=SHARED_CORE \ --enable-module=so

Then type make and then make install when Apache completes.

Apache Static Module 1.2 :

Copy the JRun source files from connectors/apache/src into your Apachesrc/modules/jrun directory (create it if it does not exist).

Add the Module line below to your Apache 'Configuration' file in the src

directory:

Module jrun_module modules/jrun/libjrun.a

From the src directory run the Configure script to create a new Makefile, then

recompile Apache.

Apache Static Module 1.3 :


9/34


8

For Apache 1.3.x, use the following command to add the JRun library to your

Apache server:

./configure -prefix=/user/local/apache \

-activate-module=src/modules/jrun/libjrun.a

Note that the '--prefix' entry and other entries may be different. The operativeentry is the '--activate-module' entry

Recompile Apache by typing make and then make install.

Running JRun Setup for Windows systems

To install JRun, simply execute the self-extracting download file. As the JavaRuntime Environment (JRE) is included in the download, you need not have

downloaded the JDK in advance. If you do have a version of the JDK alreadyinstalled, JRun ignores it and uses the one packaged with the download. Oncethe installer has created the appropriate directories and extracted the system

files, it will invoke the JRun Connector Wizard to guide you through platformspecific installation steps.

Running JRun Setup for Unix systems

To install under Unix systems (including Linux) you need to download the Unixshell installer and run it. Make sure that it has execute permissions set before

you try to execute it.

Running JRun Setup for Other Java systems

To install JRun on any Java enabled platforms download the .zip archive, unzipit and follow the directions in the README file.

Running JRun Setup for MacOS systems

Download the MacOS JRun installer and run it through your StuffIt uncompressor,then click on the JRun icon on your desktop.

JRun Setup Wizard

The JRun Setup Wizard assists you in installing connectors for allowing your native


10/34


9

web server (or Java-based web servers) to utilize the features of the JRun Servlet

Engine.

The following window should open at the end of the installation process:

Figure 2-1: Initial JRun connector wizard screen.

The next step is to click on the 'Next' button to continue. You will now be presentedwith a text field that requires the location of your JRun installation. In most

situations, this field should already contain the correct directory.


11/34


10

Figure 2-2: Locating JRun installation.

If the correct directory is not listed, click the 'Browse' button to select your JRun

root directory:

Figure 2-3: Selecting the JRun root directory.

Once you have selected the correct directory, click the 'Next' button in the mainwizard window.


12/34


11

Figure 2-4: Selecting older JRun root for migration.

If you have property settings from an older JRun that you would like to preserve the

migration panel will let you put these into your new JRun tree.

Figure 2-5: Selecting remote admin.


13/34


12

This information will be used to allow you connect to run the JRun Administration

tool remotely, note this is only applicable to JRunPro users.

Figure 2-6: Default Server Selection.

The Default Server Selection panel lets you select if you want to use the JWS (JRun

Web Server) or an external web server.


14/34


15/34


14

Figure 2-9: Proxy Host, Proxy Port and JSM selection.

Proxy Host and PortThe proxy host and port are used to specify the where exactly connector will beconnecting to. A host and port other than the default maybe necessary if you happen

to be running more than one JRun Servlet Engine proxy on the same machine.

Select JRun Service Manager

Since it is now possible to have multiple JRun Service Managers's (JSM's) it isnecessary to distinguish which JSM the connector will be communicating with. The

initial installation of JRun will only have one JSM named default.

After selecting the Proxy and JSM information the next panel will be the server

specific panel, the 'IIS 3.0/4.0' panel in this case:

Installing a connector for IIS


16/34


15

Figure 2-10: JRun connector for Microsofts IIS.

For IIS, you will need to select the location of your IIS '/scripts' directory. AddJRun as a global filter to IIS. Additionally, you should check the 'Add JRun as a

global filter to IIS' if you want IIS to automatically detect that you are trying to runa servlet.

Installation of connectors for the other servers is very similar to the IIS

configuration. Following is the interface for the Netscape Server connector.

Installing a connector for NetscapeInstalling a connector for Netscape requires a few bits of information: ConnectorType, Server Version, and the Netscape https or httpd directory.


17/34


16

Figure 2-11: Netscape connector settings.

Netscape Connector TypesJRun provides two Connector Types that may be configured for the Netscape webserver. The Java connector is an all Java connector that implements Netscape's

Server Applet api. This connector can be used if a Native connector for yourplatform is not yet available. Choosing this connector requires that Java be enabledfor your Netscape server prior to installing this connector. See your Netscape server

docs for information on how to Java enable your Netscape server. The Nativeconnector is a .so or .dll native plugin for the Netscape web server. This native

connector uses NSAPI to talk to the web server. The native connector isrecommended over the Java connector since NSAPI is a more natural and stable api

than the Server Applet api.

Server VersionThe Server Version box is only recommended if you've chosen a Native connector.

You must specify your Netscape server version so the connector installer will knowwhich .dll or .so file to use to configure your web server with.

Netscape https or httpd directoryThe file browsing field in the middle is needed to allow you to specify the location

of your https or httpddirectory for which the connector will be configured for.They are usually named with a httpd-xxxx or a https-xxxx under your

netscape/suitespot directory.


18/34


17

Installing a connector for ApacheThe following is the interface for the Apache server connector.

Figure 2-12: Selecting the Apache configuration directory.

The Apache conf directory is the directory containing the srm.confand httpd.conf

files. On Unix platforms you will also be able to select 'Do Not Use DSO' if youplan on compiling youre the JRun module into your Apache server. On Windows,

using DSO is the only option however it is important (for both Windows and Unix)to select the correct Apache Version as Apache 1.3.4 is incompatible with earilier

versions.

Commiting the dataOnce you have filled out the appropriate fields, clicking on Next will commit the

data to configure your web server. A dialog box with a status message along withoptions to configure another web server, or to finish, will be displayed when the

configuration has been complete. Clicking on finish completes the configuration by

closing the wizard. Following is the dialog box that may pop up if the configurationhas been successful.


19/34


18

Figure 2-14: Success dialog.

Note that under some servers, additional steps may be required, like compiling the connector

first.

IIS/PWS Server ConfigurationDefault Document Mappings and Security

NOTE: The following configuration steps are not necessary, they are donefor you and the instructions are included here for informational purposes

only steps are included here to.

IIS 3.0:Using regedit.exe, open the following key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Param

etes\Script Map

Under this key, add a new entry for your file extension that points to the JRun DLL. For

example, to add an entry for SHTML files, you could use:

Figure 2-15: IIS 3.0 Registry entry.

Be sure to enter the correct location of your JRUN.DLL file. Restart your

server.


20/34


19

IIS 4.0:

Under IIS 4.0, you can use the IIS Management Console to open the propertysheet for a specific virtual server or for the entire server (global):

Figure 2-16: IIS 4.0 Configuration button.

Under the 'Home Directory' tab, select the 'Configuration' button. You will

now be presented with a window that lists all of the 'Application Mappings'.Click on the 'Add' button and add an entry for JRUN.DLL to a particular

extension:

Figure 2-17: Adding an IIS 4.0 mapping for JRUN.DLL.

For this example, we'll use .shtml (Note that you may need to rename amapping that already uses this extension or use another extension). After hitting

'OK', your new mapping is now present:


21/34


20

Figure 2-18: New mapping in IIS 4.0.

You can now set any .shtml file as a default document.

.JRun Mapping with IIS 4.0You can also map the .jrun extension which will allow you to run servletsusing:

http://localhost/SnoopServlet.jrun

Security with IIS 4.0Because you can map extensions using IIS to JRun, this now means you can use

NT's native security on these mapped files as you would any other file.Also, with .jrun files, you can add security to blank 'place holders' for servlets.

For example, you can create a blank file called 'SnoopServlet.jrun' in your rootweb directory and give it restricted security access.

Now when someone accesses

http://localhost/SnoopServlet.jrun

They will first need to authenticate prior to running the servlet. This user name

is then available to you in the AUTHENTICATION header.


22/34


23/34


22

WebSite Pro Server ConfigurationBe sure you have installed WebSite Pro from the WebSite Pro CD and installed the

latest WebSite Pro patch from O'Reilly's web site.

Install JRun and follow any options for installing JRun for WebSite Pro that areavailable.

Now follow the instructions below for configuring WebSite Pro for utilizing

JRun's features. Be sure to also read the remainder of this document on how tostart and use JRun.

Mapping a URL Prefix to Run ServletsTo map a URL prefix to JRun, use the WebSite Pro Server Properties program

to add a new Mapping. For example, if you would like to run a servlet via thefollowing URL:

http://yourhost.com/servlet/SampleServlet

You will need to add a Documents mapping for '/servlet/' to WebSite Pro. Startby running the WebSite Pro 'Server Properties' application. You will start in the

following window:

Figure 2-18: WebSite Pro Administrator.

Now select the 'Mapping' tab to adjust the WebSite Pro mappings:


24/34


23

Figure 2-19: WebSite Pro mappings tab.

Add (or replace the current) a 'Document URL Path' of '/servlet/' that maps to

the location of your 'jrun.isa' file and '\servlet\' appended to the end. Forexample, your /servlet/ mapping might point to:

C:\JRun\connectors\wsapi\jrun.isa\servlet\

Of course the drive and JRun directory would depend on where you installedJRun. Once this setting has been made, it will allow you to run any servlet via

'/servlet/' URL.

Mapping a URL Prefix to Run a Specific ServletTo map a specific servlet, you would following the same steps, but add the

servlet name to the end. For example:

C:\JRun\connectors\wsapi\jrun.isa\servlet\SnoopServlet

Note the '/snoop/' mapping in the following window:


25/34


24

Figure 2-20 Mapping /snoop under WebSite Pro.

Now when a request for '/snoop/' is made, the 'SnoopServlet' would run.

Multi-Homing and URL PrefixesIf you are using multiple identities in WebSite Pro, you will need to prepend toyour URL mappings the nickname that you assigned to your identity. For

example, when setting up your identity, you were asked for a nickname:


26/34


25

Figure 2-21: URL Prefix under WebSite Pro.

This nickname appears as the 'URL Prefix' entry in your 'Identity' tab:

Figure 2-22: Identity tab after nickname added for URL prefix.


27/34


26

This 'nickname' should be used in front of your 'Document URL Path'

mappings. For example, to map the identity above '/devel' to run servlets, youwould use:

/devel/servlet/

The same way you used the regular '/servlet/ mapping:

Figure 2-23: Adding a mapping for /devel/servlet

Mapping File Extensions to JRunAdding file extension mappings is a two step process. First, under the Mappingtab, then Content Types, add an entry for your extenion that maps to

'wwwserver/isapi', for example, for .snoop:


28/34


27

Figure 2-24: Adding Content Type.

Then in the Associations section, add an entry for .snoop to the location of your

JRun.isa file, for example:

Figure 2-25: Adding an Association under WebSite Pro.


29/34


28

That's it. Now you can request files of that extension and they will be mapped toJRun.

Note: For every URL prefix or file extension you add to WebSite Pro to be

mapped to a servlet, you will also need to add that mapping to the JRun Admin.

Java-Based Servers Configuration

To configure your Java-based web server or servlet engine to communicate with

JRun, follow these steps:1) Copy the 'jrun.jar' file from the JRun distribution into your server's or servlet

engine lib/classes directory. (Some applications may require you to add theJRun.jar to the classpath, see your server's/servlet engine's documentation.)

2) Create an alias called 'JRunConnector' that points to the following class:com.livesoftware.jrunconn.JRunConnector

3) Set up two init parameters as follows:proxyhost=localhost

proxyport=8081

4) You may need to change the port number if you have configured JRun

differently. Note that the above values are also the default values, so if you areusing those values, setting them is optional.

5) Now use your server's/servlet engine's administrator to map certain requests

to JRun, for example:/servlet=JRunConnector*.jsp=JRunConnector

/msservlets=JRunConnector

6) Requests that fall into those mappings will be "forwarded" to JRun.

An example of why this is useful is, for example, if you wanted to run someservlets under the Microsoft JVM. You can run JRun under the MS JVM, then

map requests from Java Web Server, for example, from /msservet toJRunConnector, allowing you to run both Sun JVM servlets and Microsoft JVM

servlets.

Installing a new License KeyWhen installing a license key for a JRun Service Manager (i.e. for JRunProfessional), you should first launch your JRun Admin:


30/34


29

Figure 2-26: JRun Administrator.

For each of the JRun Service Managers that are listed, select it and click'Configure'. Then select the 'License' tab and you should see something like the

following:


31/34


30

Figure 2-27: JRun Services default manager license tab.

Now click the 'Add' button and enter your license key. For example, for a JRunPro 5 concurrent JVM license, you might enter something like the following:

Figure 2-28: License Key tab.


32/34


31

Notice that the 'Product Name' field is in all lower-case while the 'License Key'

field should be typed in exactly as provided to you. Be sure to hit the "Enter"key after entering the Product Name and License Key so that both fields turn

from white to violet colored as in the image above. Again, remember to enter

your license key for each JSM instance you have installed (i.e. jsm-admin andjsm-default). Now 'Save' your settings and restart all of your JRun ServiceManagers.

JRun Directory StructureThis section covers the directory structure used by JRun and the types of files thatare contained in each directory. In addition, the types of files that should be placed

in each of the directories will be covered.

JRun Directory Structure:

||----- bin|----- classes|----- connectors|----- examples|----- jre|----- jsm-default| || |----- logs| |----- properties| |----- services| || |----- jcp| |----- jse| |----- jws| || |----- htdocs|----- lib|----- properties|----- servlets

Following is a description of each of the main directories and their use:

Bin This directory is used first to find native libraries that might be used

with your servlet. JRun first searches this directory, then will lookthrough your system's PATH environment. This is where JDBC driver

libraries might be placed.

Classes This directory is looked at by the JRun class loader for finding class

files. Class files in this directory cannot be dynamically reloaded. Thisis a good location for "permanent" classes such as third-party class


33/34


32

libraries, or other packages that you know will not be changing often

or are support classes for your servlets.

Connectors This directory contains the JRun connectors for connecting native

servers like IIS, Apache, and Netscape servers to the JRun ServletEngine via the JRun Connector Proxy.

Htdocs

This directory contains the HTML version of the JRun documentation

(this file) as well as the default HTML documents for the JRun WebServer.

Examples This directory contains one or more example servlets.

Jre This directory contains the Java Runtime Environment. These filesshould generally be left alone and are used by JRun exclusively.

Jsm-default This directory contains the default JRun Service Manager.

Lib This directory contains the JRun library. These files should not bealtered and this directory will generally not be used other than by

JRun.

Properties This directory contains the JRun property files that specifyconfiguration options. The JRunAdmin is used to modify these files,

or they can be modified manually.

Servlets This directory contains servlet available to all JSMs.

JSE Service Directory Structure||----- jse

|----- logs|----- properties

|----- servlets|----- sessions


34/34


Following is a description of each of the JSE directories and their use:

Logs

This directory contains the default log file, event.log that your servlets

generate via the log() method. In addition, the error.log file is generatedhere. This error log contains any miscellaneous messages generated byJRun or your servlet.

Properties This directory contains the JRun property files that specify all of the

configuration options. The JRunAdmin is used to modify these files, orthey can be modified manually.

Servlets This directory contains a collection of sample servlets that can be run byJRun. In addition, this directory is where you will place your servlets

for deployment. For servlets with package names, be sure to include the

complete directory structure. For example, if your servlet's packagename is `testing' and your class name is `TestServlet,' then you wouldhave a subdirectory called `testing' in the `servlets' directory and a file

called `TestServlet.class' within the `testing' directory.

Note: You may wish to remove the sample servlets once JRun is used

for live deployment.

Sessions This directory contains the session file used by JRun for swapping user

session data in and out during server startup and shutdown.