Skip directly to searchSkip directly to the site navigationSkip directly to the page's main content

IBIS-Q System Documentation - Web Server Setup

Tomcat Notes

This document does not contain step by step instructions on how to install a Java sdk/runtime or the Tomcat application server on a Windows or Linux box. There are plenty of these tutorials/instructions available on the web and in books. This document does contain the specific items changed and any notes on topics that partain to how the Java JVM and Tomcat were setup/what needs to be configured. Throughout this document it is assumed that the application server (Tomcat) is a dedicated set for the IBISPH applications although other applications could be hosted. The next section serves as an index and also provides a simple outline of the general steps needed to get the IBISPH systen up and going.

INSTALLATION STEPS

  1. Download and install J2SE JDK 1.5+ from Sun's site. As of 1/2005, IBISPH doesn't use any of the new features of Java Version 1.5 but there have been some speed and XML improvements that are worthwhile. Tomcat 5.x requires Java JVM 1.5+, while Tomcat 4.x can use either JVM (any 1.2+ JVM). However, the IBISPH applications are built using Java 1.4.2 and 1.5.1.
  2. Download the Tomcat app server package from the Apache Jakarta Download page. Scroll down to tomcat section and get the latest production tomcat.X.Y.Z.tar/exe.
  3. Install Tomcat
  4. Setup/configure the Tomcat Java JVM
  5. Edit/configure the system's default Deployment Descriptor (web.xml)
  6. Edit/configure the system's control file (server.xml)
  7. Physically delete/remove the standard Tomcat webapp(s)
  8. Deploy the webapp(s)
  9. Copy jdbc jars to [CATALINA_HOME]/common/lib
  10. Copy/remove/manage the XML related jars
  11. Create/copy the default welcome and 404 error pages

MISC NOTES



TOMCAT INSTALL OVERVIEW

Tomcat comes in either zip, tar, rpm, or widnows exe format for the specified OS and CPU. Basically what happens is that the tomcat system files are extracted into a directory. The main thing that the system needs is to have the Java enviroment setup and two envirnment varaibles that should be set, which are:
  • JAVA_HOME = JDK Root dir (needs to include the tools.jar. typically this path is like: d:\java\1.5.1\ or /usr/java1.5.1 and has subdirectories like bin/ & lib/).
  • CATALINA_HOME = tomcat root dir (e.g. D:/tomcat or /usr/local/tomcat5).
  • CATALINA_OPTS = Contains command line arguments like JVM memory settings. This value is NOT required for the system to run but it is the easiest way to set the JVM settings. Another way is to modify the catalina.sh or catalina.bat file located in the [CATALINA_HOME]/bin directory.

See the Tomcat Jarkarta website for more information on setup.

NOTE: If multiple Tomcat's are setup on the same box, then modify the startup (.sh/.bat) catalina files and specify the appropriate JAVA_HOME and CATALINA_HOME variables in those files. There are other ways to make this work as well - that's simply one. Listed below are the changes made to the startup.bat and catalina.bat file.
startup.bat:
REM Commented out the usage of the existing Tomcat4 env variable:
REM if not "%CATALINA_HOME%" == "" goto gotHome

catalina.bat (added to the top and switch back at the bottom):
set TEMP_JAVA_HOME=%JAVA_HOME%
set TEMP_CATALINA_HOME=%CATALINA_HOME%
set JAVA_HOME=d:\java\1.5.1
set CATALINA_HOME=d:\tomcat5


For Linux, modified the catalina.sh file to have this at the top:

JAVA_HOME=/usr/local/java/jdk1.5.0_02
JAVA_OPTS="-Djava.awt.headless=true"
CATALINA_HOME=/usr/local/jakarta-tomcat-5.5.9
CATALINA_OPTS="$CATALINA_OPTS -server -Xms1024m -Xmx1024m -Xmn256m"


SETUP TOMCAT TO RUN IN IT'S OWN ACCOUNT

This runs Tomcat as something other than root/system. Doing this simply locks down the possibility of a stray application getting on the system and being able to do damage. This is outlined in the Wrox Apache Tomcat 5 book and is also discussed in numerous websites like jGuru. Listed below are some general steps from the book:
  • create a "tomcat" account which owns and has the privs to where tomcat will be installed and ran from.
  • Make sure the tomcat account has the JAVA_HOME and CATALINA_HOME enviro variables.

WINDOWS:
  • the tomcat account should be removed from all groups.
  • IF running as a service, the Services utility can be used to select a user account for use when launching Tomcat (Admin Tools). Double click the tomcat service, [Log On] tab, then "log on as" and enter the un/pw.
  • Else IF NOT as a service, then use the Window's runas command:
    runas /user:tomcat c:\tomcat\bin\startup.bat

LINUX:
  • create both a tomcat user and tomcat group (adduser)
  • Secure the tomcat file system.
  • Secure the JVM

For more specifics on file privs etc. see: Chapter 15, Tomcat Security, of Professional Apache Tomcat 5. ISBN: 0-7645-5902-8


WINDOWS TOMCAT SETUP

Run the .exe file which runs a windows setup. This steps you through everything and installs a tomcat service which can auto start on system startup.

NOTE: If you want the system out log, you'll need to check the Tomcat service's "allow to interact with the system" checkbox.

If this step is done by hand, simply unzip the installation package and set the enviroment variables. You can then run the [CATALINA_HOME]/tomcat/bin/startup.bat to start, and press [Ctrl]-c in the system out window to stop the server or run the shutdown.bat file located in the same bin directory.

LINUX TOMCAT SETUP

IMPORTANT: For the Batik Graphics to be able to convert SVG to JPEG on Unix, the headless enviroment variable or Java system property must be set.
Env Var: JAVA_OPTS='-Djava.awt.headless=true'
JVM 1.4+ System Property: java.awt.headless=true
See Paul Leo's system setup document for the main meat.



MULTIPLE TOMCAT SETUPS ON SAME SERVER

For mulitple installs on the same server did the following:
  • Installed into different directories
  • Modified both installed catalina.sh (linux) (or catalina.bat for windows) files as described
  • Changed the server ports to be unique e.g. <Server port="8005"
  • Changed the connector ports to be unique e.g. <Connector port="8080"
  • Added unique jvmRoute attribute to the Engine element e.g. <Engine jvmRoute="tomcat4"



JVM MEMORY SETTINGS

Add the JVM memory settings within the env var CATALINA_OPTS (JAVA_OPTS also works but will apply the settings to any JVM request). There isn't a hard and fast rule on what these numbers should be because it depends on a variety of factors. The Apache Tomcat5 book recommends setting the Xms and Xmx the same to minimize the time it takes to grow the heap. It is recommended to specify a considerably lower value than the amount of physical RAM in your system, so the operating system and other applications will also have enough space. Otherwise the swap memory of the operating system will be used, which can result in high disk activity (thrashing), and reduced system performance. See Bea's JVM Tuning Page for info on how to tune WebLogic and general JVM settings.

NOTE: This settings are for Sun's JVM. Other JVMs may have different command line settings.

Basically there are 3 main values that should be set. These are the min heap size "Xms" the max heap size "Xmx" and the server flag "server". Example:
LINUX: CATALINA_OPTS="$CATALINA_OPTS -server -Xms256m -Xmx512m"
WINDOWS: set CATALINA_OPTS=-server -Xms256m -Xmx512m

NOTE: Server mode instructs the JVM to perform more extensive run-time optimization. This flag MUST be the first aurgument/parameter specified otherwise it will be set as a "client" (according to http://java.sun.com/docs/hotspot/PerformanceFAQ.html). Specifying the "server" flag means that right after startup the system will have slightly slower execution, but after the JVM had enough time to optimize the code, the execution should be faster.


GARBAGE COLLECTION

IMPORTANT NOTE: It appears that when specifying garbage collection that if large amounts of memory (greater than 256M) are specified then the incremental compacting GC should not be used for performance reasons (-Xincgc). This bottleneck was experienced when running Tomcat4 with Java 1.4 on Susue Linux 9, and heap of 512m to 1024m. According to Sun on JVM 1.3, if you need lots of memory and experience a GC delay, try setting the "eden" sizes: -XX:NewSize=128m -XX:MaxNewSize=128m (or set a ratio of old to new via -XX:NewRatio=8). Another way to set this size is using -Xmn256m. Eden is where all new objects are created. According to Sun, most objects are short term objects and as such are better off caught in a small memory area that is quickly and easily garbage collected (e.g. don't have to go through a huge memory pool). The long term objects are then copied into the perm heap area and GC'd differently. Also, turn on GC messages by issuing this on the command line: -verbose:gc -Xloggc. Can also profile heap usage by -Xrunhprof:heap=all or other option, try -Xrunhprof:help. Also see jvmstat tool. Also note that these settings are for Sun JVMs 1.4+.

JVM 1.5:
This might be something to try also: Use the parallel young generation collector (-XX:+UseParallelGC) along with the adaptive size policy feature (-XX:+UseAdaptiveSizePolicy).

JVM LINKS


NOTES:
Tried CATALINA_OPTS of: -server -Xms256m -Xmx256m -heapsize32m -freememory20m but these heap and free mem settings wouldn't work as documented.

ANOTHER OPTION - EDIT CATALINA.SH (linux) or CATALINA.BAT (windows)

Can also set the JVM memory settings by modifying this script file which is typically used to start Tomcat. These files can also be modified for the HOME enviro vars so that the enviroment variables are not needed/used. Both of these files are located in the [CATALINA_HOME]/bin directory.

WINDOWS SERVICE: If Tomcat was installed on Windows as a service then the enviro variable should be set. Or, if installed you should be able to set by going to: Start / Programs / Apache / Tomcat 5.0 / Configure Tomcat.

This will open up a dialog box to change settings. Click the middle tab, Java VM. There is a text area to add Java Options. After the last entry/value, add -Xms###m -Xmx###m. Click Apply or OK, and restart the Tomcat service.

NOTE: This requires Tomcat to be started and the system apps to not be removed as outlined/semi-recommended in this document.

EXAMPLE JVM SETTINGS FROM COCOON V2:
(default)64128256384
Xms0000
Xmx 64100228356
heapsize 6080208236
freememory 1202020


So if you see errors like:
java.lang.OutOfMemoryError <<no stack trace available>>
java.lang.OutOfMemoryError <<no stack trace available>>
Exception in thread "main"
		
Then you'll need to increase the stack space.


EDIT TOMCAT'S MAIN DEPLOYMENT DESCRIPTOR SYSTEM WEB.XML

The file $CATALINA_HOME/conf/web.xml is the default system Deployment Descriptor for all web applications. Each IBISPH application specifies most of these settings but it's still a good idea to have a default welcome page and general error pages even though the IBISPH apps specify these.

IMPORTANT: Make a backup copy of this file before editing. Also note that the elements are ordered and that these elements MUST be in an exact order. See Bea's web.xml defs for more info on each element.


ENABLE / DISABLE DIRECTORY LISTINGS AND MAKE HTTP READ ONLY

Edit the $CATALINA_HOME/conf/web.xml file and locate the main servlet element's init params (located in the upper section). Change the parameter's value with the 'param-name' of 'listings' from 'true' to 'false'. Tomcat defaults with the system being in read only mode but it's best to make sure explicitly. Add a 'init-param' element like given below. "Read-Only" means that HTTP DELETE and PUT requests are rejected.
<servlet>
	<servlet-name>default</servlet-name>
	<servlet-class>org.apache.catalina.
		servlets.DefaultServlet</servlet-class>
	. . .
<init-param> 
	<param-name>listings</param-name>
	<param-value>false</param-value>
</init-param>
<init-param> 
	<param-name>readonly</param-name>
	<param-value>true</param-value>
</init-param>
. . .
		

REMOVE / COMMENT OUT INVOKER SERVLET

Comment out or delete the servlet invoker definition and mapping:
<servlet>
	<servlet-name>invoker</servlet-name>
. . .
		and 
<servlet-mapping>
	<servlet-name>jsp</servlet-name>
	<url-pattern>*.jsp</url-pattern>
</servlet-mapping>
		

SET DEFAULT SYSTEM WELCOME PAGES

The welcome pages are simply a list of files/urls that will be called if a general, non specific application request is made to the system. If it is a general request to an application e.g. http://ibis.health.utah.gov/ibisph-view then the "ibisph-view" application will have a welcome list that will be used (as well as a default servlet call). If an application is installed as the "root" application or has it's application path set to "/" then it's welcome pages will be used first for the system. Else, the files listed here will be used in the order they are listed (e.g. if it can't find the first welcome file it will go to the next one). Also, note that the items listed MUST be a file and NOT an application servlet call.

BOTTOM LINE: This isn't needed because the view system is the default/root app and it provides these pages. However, below is a sample of what this would look like if it was needed.
<welcome-file-list>
	<welcome-file>index.html</welcome-file>
	<welcome-file>/ibisph-view/index.html</welcome-file>
<welcome-file-list>
		

SET ERROR PAGE

At a very minimum, the HTTP 404 code should be handled in case a request is made to the general system that does not exist (same bottom line as the welcome pages).
<error-page>
	<error-code>404</error-code>
	</location>http://health.utah.gov/error</location>
<error-page>
		

SETTING DEFAULT SESSION TIMEOUT

This value really isn't needed for IBISPH since each app already specifies this value in their respective web.xml files. In any case if a default is wanted for the system set this value:
<session-config>
	<session-timeout>30</session-timeout>
</session-config>
		
"default" SERVLET NOTE: This is required for the system to function. Also, if any of the applications need to serve files then the url pattern of "/" is needed. Without this pattern there is no process to locate and stream back data files. If not specified then each app needs to have a file serving servlet...



EDIT / CONFIGURE SYSTEM SERVER.XML

This is the main configuration file that controls the host engine and application contexts.
IMPORTANT: Make a backup copy of this file before editing.

See Demystifying Tomcat 4's server.xml File for more info on each element. Or Tomcat's docs.

CHANGE SHUTDOWN PORT AND SIGNATURE

<Server port="8007" shutdown="remoteshutdown" debug="0">
		

CHANGE CONNECTOR'S PORT AND ENABLE COMPRESSION

Leave at 8080 for OIT. I change it to 80 so I don't have to do localhost:8080 in my development enviroment. Also, for faster development, leave the compression off. Some sites might want to use 80 if on Linux there's a way to keep on 8080 and remap 80 to it (see Paul Leo's setup document).
<Connector port="80"
	maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
	enableLookups="false" redirectPort="8443" acceptCount="100"
	connectionTimeout="20000" disableUploadTimeout="true" 

	*** BELOW IS FOR TOMCAT 5 ONLY AND ONLY FOR PRODUCTION ***
	compression="on"  compressionMinSize="2048" 
	noCompressionUserAgents="gozilla, traviata" 
	compressableMimeType="text/html,text/xml"
>
		

CONFIGURE ACCESS LOGS TO BE READABLE FOR TRENDING PACKAGES

If this app server is being front ended by Apache, perforance can be increased by not logging access. If this is the case, then skip this. Else, within the Engine element set a value element to be like the one below (pattern attribute is the key):
<Valve className="org.apache.catalina.valves.AccessLogValve" 
	directory="logs"
	prefix="access"
	suffix=".log"
	resolveHosts="true"
	pattern="common"
/>
		
And, define the actual logger class. Within the Host element make sure there's an entry like:
<Logger className="org.apache.catalina.logger.FileLogger" 
	directory="logs" 
	prefix="localhost_log." 
	suffix=".txt" 
	timestamp="true"
/>
		
See http://www.faqchest.com/prgm/tomcat-l/ tmct-02/tmct-0210/tmct-021056/tmct02101513_20837.html for more specifics.

TURN OFF UNPACK and AUTO DEPLOY

For speed, and security, remove the autodeploy and unpacking of wars from a production enviroment. For development, leave these on and also set the 'appBase' set to the CVS/ IBIS folder's webapps directory. This allows for everything to be kept in one directory for easy backups and easier management of all the related project work products. Note that you can leave the WAR packed for even tighter security. This doesn't allow for hot patching of files and according to the docs will be a little slower than when compared with a fully extracted war.
<Host name="localhost" debug="0" appBase="webapps" 
	unpackWARs="false" autoDeploy="false">
		

REMOVE ALL OTHER WEBAPP CONTEXTS

For a production enviroment, comment out or remove all the defined "Context" elements which includes examples, ROOT, etc. These elements are contained within the Host element and look like:
<Context path="/examples" docBase="examples" debug="0"
	. . .
		

ADD IBISPH VIEW SYSTEM CONTEXT

For OIT where the view system is to be the default/root app add the following:
<Context path="" docBase="ibisph-view" debug="0" 
	reloadable="false" crossContext="false"
/>
<Context path="/ibisph-view" docBase="" debug="0" 
	reloadable="false" crossContext="false"
/>
		
NOTES: For development, leave the reloadable="true" so that the app will auto reload whenever any of the class files change (e.g. if re-compiled). For those that do NOT want cookie support, add the cookies="false" attribute to the Context element. Session objects will then use URL re-writing.

TWO CONTEXTS FOR A GIVEN APP: Tomcat requires a default/root app. Tomcat also auto creates contexts within applications it finds within it's default appBase folder. So if the view system is setup as the default app, Tomcat will auto create a context with the path of "/ibisph-view/". The problem/issue is if there are 2 contexts both pointing to the same docbase then you'll get 2 instances of the same app within the webapp server container/JVM which run seperately but use/share the same files. So for something like artifacting, you'll have files which have navigation built for potentially two different contexts. In the old way of artifacting a hash was used which really could get things messed up pretty quick - scarry. To get around this create a blank or a dummy docBase which matches the /ibisph-view path. This forces Tomcat to not auto create a working "ibisph-view" app. Note that Tomcat 559 will complain if a base of "dummy" or any other invalid/non existant directory name is specfied. It doesn't complain about "" being used. There are other ways around this also like not having a "base" webapps directory and simply having a single app under a single virtual host. Also can put directory outside of the base directory then the path looks funny etc.

ANOTHER WAY NOTES: Specify the Host appBase attribute to be: webapps/ibisph-view then set the docBase of the context to / and the admin's docBase to ../ibisph-admin. The blank dummy context can then be removed. The view system as of Oct, 2005 handles both contexts being used. However, with artifacting, the first time the page is artifacted is how the menuing system will be saved. So if the ibisph-view/home/Welcome.html is hit first then all of it's navigation will be ibisph-view/... (which works) but then if someone else comes and hits a page as the root/default app then some pages will have the ibish-view context while others will have navigation links that have a blank context.

WARS, AUTODEPLOY, CONTEXTS: if a context is specified, the war won't auto redeploy (even if enabled). To get around this you need to delete the app's files and then the system will auto deploy the war (assuming enabled and the war is in the webapps directory).

DEVELOPMENT DIRECTORY NOTE: If you have your webapp located outside the normal directory specified with the Host elelment then you'll need to explicitly point to that directory in the "docBase" attribute.



NOTE ABOUT APP SERVLET MAPPING (web.xml): You can have a blank servlet alias but then everything will be funneled through that servlet. So all requests for jsps javascripts, css, etc. would all hit that servlet and not be served up as web content.

ADD IBISPH ADMIN SYSTEM CONTEXT

The data admin system needs a context due to it's JNDI/JDBC db connection. The opening of this context element is:
<Context path="/ibisph-admin" docBase="ibisph-admin" debug="0" 
	reloadable="false" crossContext="true">
	*** JNDI/JDBC RESOURCE ELEMENTS GO HERE - SEE NEXT SECTIONS ***
</Context>
		
If you're wanting the ability to auto reload JSPs without having to clear the Tomcat's work/build directory then set reloadable="true"

See the sections below on how to configure the JNDI JDBC data source resource elements needed. Note that while similar, these elements differ and can be quite picky about what elements and attribute settings will allow the system to work with the version of that database's jdbc build/jar. If there are problems then you'll need to read that vendors jdbc docs on how to setup for tomcat or googlize it. Also note that the configurations are set for local development. For production systems the username, password, and URL type information will all need to be set as needed.

IBISPH-ADMIN CONTEXT MATCHING DEPLOYMENT PATH: The "ibisph-admin" context must be defined and must match the deployment path. This is because for jndi data sources to be found for servlets that auto load the context path MUST match the actual deployment path. So for admin you can set the path to be admin but because autoload is set in the ibisph-admin deployment descriptor, the app will try to autoload based on that ibisph-admin context path and thus will throw because the context isn't defined. However, the admin context will work - you just won't be able to connect to a db!!!

MYSQL JNDI / JDBC RESOURCE

FOR TOMCAT 4.x: mysql-connector-java-3.0.9-stable-bin.jar. Also tested the mysql-connector-java-3.1.6-bin.jar with the configuration below and it worked!!! However, for TOMCAT 5, this does NOT work (at least with 3.0.x or the 3.1.x driver).
<Context path="/ibisph-admin" docBase="ibisph-admin" 
	debug="0" reloadable="false" crossContext="true"
>
	<Resource name="jdbc/hl_ibisph_admin" auth="Container" 
		type="javax.sql.DataSource"
	/>
	<ResourceParams name="jdbc/hl_ibisph_admin">
		<parameter>
			<name>driverClassName</name>
			<value>com.mysql.jdbc.Driver</value>
		</parameter>
		-or (both work)-
		<parameter>
			<name>driverClassName</name>
			<value>org.gjt.mm.mysql.Driver</value>
		</parameter>

		<parameter>
			<name>url</name>
			<value>
				jdbc:mysql://localhost:3306/ibisph
					?autoReconnect=true
			</value>
		</parameter>
		<parameter>
			<name>username</name>
			<value>the_ibisph_owner_username</value>
		</parameter>
		<parameter>
			<name>the_ibisph_owner_password</name>
			<value>ibisph</value>
		</parameter>
		<parameter>
			<name>maxWait</name>
			<value>100</value>
		</parameter>
		<parameter>
			<name>maxIdle</name>
			<value>1</value>
		</parameter>
		<parameter>
			<name>maxActive</name>
			<value>10</value>
		</parameter>
		<parameter>
			<name>removeAbandoned</name>
			<value>true</value>
		</parameter>
		<parameter>
			<name>removeAbandonedTimeout</name>
			<value>60</value>
		</parameter>
	</ResourceParams>
</Context>
		
Note About the JDBC Factory: Some sites show a factory parameter which according to the Apache Tomcat book is not needed. The factory is only needed for older tomcats that use Tyrex data source factory by default (Tomcat 4.0.04 up to 4.1.3). So don't include a Resource/ResourceParams/parameter element like this:
<parameter>
	<name>factory</name>
	<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
</parameter>
			

FOR TOMCAT 5.5.x: jars tried: mysql-connector-java-3.0.16-ga-bin.jar and mysql-connector-java-3.1.6-bin.jar. Tried different configs and different jars but couldn't get anything to work except and this resource setup:
<Context path="/ibisph-admin" docBase="ibisph-admin" debug="0" 
	reloadable="false" crossContext="true"
>
	<Resource name="jdbc/hl_ibisph_admin" auth="Container" 
		type="javax.sql.DataSource" maxActive="100" 
		maxIdle="30" maxWait="10000" 
		username="the_ibisph_owner_username" 
		password="the_ibisph_owner_password"
		driverClassName="com.mysql.jdbc.Driver"
		url="jdbc:mysql://localhost:3306/ibisph
			?autoReconnect=true"
	/>
</Context>
			

ORACLE JNDI/JDBC RESOURCE

This configuration has been tested and works for associated Oracle JDBC versions 8.x and 9.x (all named classes12.zip).
<Context path="/ibisph-admin" docBase="ibisph-admin" debug="0" 
	reloadable="false" crossContext="true"
>
	<Resource name="jdbc/hl_ibisph_admin" auth="Container" 
		type="oracle.jdbc.pool.OracleConnectionPoolDataSource"
	/>
	<ResourceParams name="jdbc/hl_ibisph_admin">
		<parameter>
			<name>factory</name>
			<value>oracle.jdbc.pool.
				OracleDataSourceFactory
			</value>
		</parameter>
		<parameter>
			<name>url</name>
			<value>
				jdbc:oracle:thin:[USERNAME]/
					[PASSWORD]@[CONNECT]
			</value>
		</parameter>
	</ResourceParams>
</Context>
		

MS SQL SERVER JNDI/JDBC RESOURCE

<Context path="/ibisph-admin" docBase="ibisph-admin" debug="0" 
	reloadable="false" crossContext="true"
>
	<Resource name="jdbc/hl_ibisph_admin" 
		scope="Shareable" type="javax.sql.DataSource"
	/>
	<ResourceParams name="jdbc/hl_ibisph_admin">
		<parameter>
			<name>url</name>
			<value>
			  jdbc:microsoft:sqlserver://10.228.0.98:1433;
			  DatabaseName=ibisph;user=ibisph_admin_owner;
			  password=ibisph
			</value> 
		</parameter>
		<parameter>
			<name>driverClassName</name>
			<value>
			  com.microsoft.jdbc.sqlserver.SQLServerDriver
			</value>
		</parameter>
	</ResourceParams>
</Context>
		

OPTIONAL HTTPS CONFIGURATION

HTTPS allows data sent to/from the server to be encrypted using Secure Socket Layer (SSL). This secure data communication is desirable when dealing with sensative query datasets or sensitive indicator profiles etc. Note that to be effective, an authentication and authorziation mechanism needs to be utilized in addition to the encrypting of the data transferred. Also note that a seperate installation of the application should also be considered to ensure that all requests and traffic are authrozied and encrypted.

The basic steps are:
  1. If you are running a 1.3 JVM (version 1.4+ already has this bundled in), download JSSE 1.0.3 (or later) from http://java.sun.com/products/jsse/ and either make it an installed extension on the system, or else set an environment variable JSSE_HOME that points at the directory into which you installed JSSE.
  2. Create a certificate keystore by executing the following command:
    Windows: %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
    Unix: $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
    and specify a password value of "changeit".
  3. Uncomment the "SSL HTTP/1.1 Connector" entry in $CATALINA_HOME/conf/server.xml and tweak as necessary.

See the Tomcat SSL how to/setup documentation for more detailed instructions.


DELETE / REMOVE INSTALLED TOMCAT WEBAPPS FILES

Physically delete/remove the standard Tomcat webapp(s) which were auto installed. Even if the app's context is removed from/doesn't exist in the server.xml the app will still load/be available (the Host's autodeploy attribute doesn't control this either - it's only a default for war files placed in the root of the webapps directory). These apps are located in the [CATALINA_HOME]/webapps directory (or where ever specified in the server.xml file) and can include:
  • tomcat-docs
  • ROOT
  • jsp-examples
  • servlets-examples
  • webdav

If the manager and/or admin apps are to be kept then see how to secure Admin and Manager in Chapter 15 of the Apache Tomcat book already mentioned on this page. Otherwise these should also be removed from the [CATALINA_HOME]/server/webapps directory. These apps are in a directory named:
  • admin
  • manager



DEPLOY THE IBISPH VIEW and ADMIN WEBAPPS

Physically copy all the files from the development enviroment's webapps directory (located under the [CATALINA_HOME]/webapps directory). Typically, all of these files are put into an archive (a gzip file) which is known as a web archive (WAR) which as a .war file extension. The following steps outline the procedure:
  • Stop Tomcat
  • Delete or move the existing admin or view deployment from the webapps dir.
  • Create the [CATALINA_HOME]/webapps/ibisph-view and ibisph-admin directories.
    NOTE: If the webapps directory was changed in the server.xml file then you'll need to go to that location.
  • Copy the entire webapp ibisph-view and ibisph-admin directories to the directories created in the previous step -or- unzip the associated .war deployment file into the respective directory (this needs to include all the directory structures etc).
  • Update any global properties as needed for that application's particilar enviroment
  • Start Tomcat
  • Test

CLEAN OLD ADMIN JSPs: When redoing classes/Major changes to JSPs etc. DELETE the [CATALINA_HOME]/work/localhost/ibisph directory.

IF AUTO DEPLOY IS ON: copy the WAR to the webapps/ directory.

NOTE: For the above to work, you can NOT have an app context defined. If you do, then Tomcat will not auto extract the war - you'll have to remove the existing directory/files first. Also, for faster recognition of the newly deployed war, restart Tomcat.

USING THE MANAGER APP: http://localhost:8080/manager/install?path=/ibisph&war=jar:file:d:/ibisph.war!/


COPY SYSTEM WIDE COMMON JARS TO [CATALINA_HOME]/common/libs

Copy the common, system wide, JDBC libs/zips/jars (e.g. Oracle/MySQL/SQL Server jdbc drivers) into the [CATALINA_HOME]/common/lib folder. Note that for the ibisph applications the JDBC drivers are the only drivers that qualify to be placed in this folder. All other jars are packaged within the application. The exception to this are the XML packages which are discussed later. If there are any common application jars these would be placed in Tomcat's "shared" folder. Since the IBISPH applications are designed for minimum system administration on other non-dedicated app servers, each application contains all of it's needed java packages (other than core packages like JDBC drivers, the servlet extensions etc.).

ORACLE NOTES:
  • The Oracle jdbc jars have historically all been named classes12.zip regardless of their jdbc version or the related db version.
  • Oracle 9i requires an Oracle 9i driver because of the character set issues in the latest jdbc standard. So, if you're connecting to a 9i db then you MUST use a 9i jdbc driver (will still be named classes12.zip).
  • Change name of zip files to jar (Tomcat seems to only look for/recognize jar files.

MY SQL NOTES:
Have experienced issues with different verions of Tomcat, MySQL JDBC drivers, and Context/Resource connection configurations. See ibisph-admin MySQL Context section for more info.

SQL SERVER NOTES:
Not much experience but the jdbc version that was tested used/needed the following 3 jar files:
  • msbase.jar
  • msutil.jar
  • mssqlserver.jar



COPY / MANAGE XML RELATED JARS

This is a semi mess. See the seperate "Java 1.4 & 1.5 XML Parsers.txt" file for a more detailed discussion. The following steps are for DEDICATED IBISPH application server installations ONLY!!! To effectively delete a jar, simply rename it to something with an unrecognized file extension like .xxxx (e.g. anything other than .zip, .tar., .jar etc.).

TOMCAT 4 [CATALINA_HOME]/common/endorsed folder (Tomcat 5.5.4's endorsed is empty):
  • Rename/delete xmlParserAPIs.jar
  • Rename/delete xercesImpl.jar

If running any Java JVM 1.4.x:
  • Copy xalan.jar from ibisph-view/WEB-INF/lib into Tomcat's endorsed folder
IMPORTANT: If deploying to a non IBISPH dedicated server, the XML issues will need to be addressed if either application doesn't perform as expected.



DEFAULT WELCOME AND ERROR PAGES

This isn't needed because the IBIS-PH View System deployment has these pages already specified. Also, for Utah's deployment it is the default/root app.

NOTE ABOUT APP SERVLET MAPPING (web.xml): You can have a blank servlet alias but then everything will be funneled through that servlet. So all requests for jsps javascripts, css, etc. would all hit that servlet and not be served up as web content.

NOTE ABOUT PAGE REDIRECTION: Tomcat doesn't support alias's. Need to use Apache? TO get a servlet outside of the "ROOT" context to work, must do a redirect e.g. if webapps/ROOT/index.jsp contains:
<%response.sendRedirect("ibisph-view/Transform
	?xml=home/home.xml
	&xslt=home.xslt"); 
%>
		
Then in the conf/web.xml put the index.jsp in the <welcome-file-list> section. The jsp:forward doesn't work because of a different context. The welcome file list doesn't support URI's - must be a file. Can associate a servlet with an extension like *.ibis then have an index.ibis in the file list. The file must merely exist and then the servlet would be called. The redirect does the job until Apache with true alias's can be setup.


IBISQ CGI Tomcat Setup/Configuration

After many hours of searching/reading/trials and errors here's the only way I could get this work on Tomcat5.

  • Enable Tomcat's CGI Servlet Handler. Rename the tomcat/server/lib/servlets-cgi.renametojar to servlets-cgi.jar
  • Enable CGI in tomcat/conf/web.xml. Uncomment/enter this servlet entry:
    <servlet>
    	<servlet-name>cgi</servlet-name> 
    	<servlet-class>org.apache.catalina.servlets.
    		CGIServlet</servlet-class
    	> 
    	<init-param>
    		<param-name>debug</param-name>
    		<param-value>255</param-value>
    	</init-param>
    	<init-param>
    		<param-name>cgiPathPrefix</param-name>
    		<param-value>cgi-bin</param-value>
    	</init-param>
    	<init-param>
    		<param-name>executable</param-name>
    		<param-value>
    		  d:/tomcat/webapps/ibisq/cgi-bin/hi_iq_func.exe
    		</param-value>
    	</init-param>
    	<load-on-startup>10</load-on-startup>
    	</servlet>
    
    	<servlet-mapping>
    		<servlet-name>cgi</servlet-name>
    		<url-pattern>/cgi-bin/*</url-pattern>
    	</servlet-mapping>
    		
    NOTES:
    • These entries are also able to be made in the ibisph-view web.xml file.
    • You can have mulitple cgi servlet entries as long as they are named differently (and of course you'd want different url mappings...).
    • debug = 0 is minimal info. 255 allows a page to be returned when testing ibisq urls directly. This page shows all the request info etc.
    • giPathPrefix is critical. I tried many settings here and could only get it to work as set.
    • executable is required. If this entry is not here then it assumes perl. Much time was spent on this setting as well. Tried putting the cgi exe in the path (e.g. tomcat/bin). It worked there as long as there was another copy in the webapps/ibisq/cgi-bin directory. Never could figure this out. The easiest way was simply to put in the full explicit path to the exe.
    • Mapping didn't work with /ibisq/cgi-bin but would only work with /cgi-bin. Again I'm not sure why/how this works because it doesn't seem like it would considering the url needed.

  • Create an IBISQ context in the tomcat/conf/server.xml
    Even though this is not a standard web app (tomcat complains about it) this is still required and doesn't work without it.
  • Update the IBISQ URL located in the webapps/ibisph-view/deployment_specific.properties
    http://localhost:8080/ibisq/cgi-bin/hi_iq_func.exe

    NOTES:
    • The context needs to match and the ".exe" is required to work - at least on windows.
    • This is confusing since the cgi servlet mapping should only catch for root /cgi-bin requests but that's how it works. Tried different mappings all unsuccessfully.



TEST URLS

Note: favorite bookmarks are stored in the user's area under my favorites (for IE) and typically in C:\Documents and Settings\username\Application Data\Mozilla\Firefox\Profiles\default.7pi\bookmarks.html for NS/FF.

LOCAL / DEVELOPMENT MACHINE:
General Tomcat
Admin System (assuming the app is using the "ibisph-admin" context path)
Local View System (assuming the app is the default app, if not add the appropriate app context path)


BATIK 1.5 - HOW TO WORK ON LINUX AND JARS NEEDED

TO WORK ON LINUX: export JAVA_OPTS='-Djava.awt.headless=true' need Java 1.4.1+ for this to work.

??? Might work with CATALINA_OPTS ???

JARS NEEDED (for transcoding):
  • batik-awt-util.jar
  • batik-bridge.jar
  • batik-css.jar
  • batik-dom.jar
  • batik-ext.jar
  • batik-gvt.jar
  • batik-parser.jar
  • batik-script.jar
  • batik-svg-dom.jar
  • batik-transcoder.jar
  • batik-util.jar
  • batik-xml.jar

NOT NEEDED:
  • svg-gen
  • swing
  • extensions
  • gui-util



ORACLE INFO / CONNECTION CACHE NOTE FROM CASTER FAQ

<database name="..." engine="oracle" >
	<driver class-name="oracle.jdbc.driver.OracleDriver"
		url="jdbc:oracle:thin:@localhost:1521:TEST" >
			<param name="user" value="SYSTEM"/>
			<param name="password" value="manager"/>
	</driver>
	...
</database>
		

ORACLE CACHE VERSION:
<database name="..." engine="oracle" >
	<data-source 
		class-name="oracle.jdbc.pool.OracleConnectionCacheImpl"
	>
		<params URL="jdbc:oracle:thin:@localhost:1521:TEST" 
			user="SYSTEM" password="manager"
		/>
	</data-source>
	...
</database>
		



JNDI ENTRIES - HOW TO (server.xml)

Added JNDI enties for system urls as a way around using property files. Then could put all properties into the web.xml as parameters thus not needing property files. These are put into the conf/server.xml file. Need to be in the form of:
<env-entry>
	<env-entry-name>ibisph/homeURL</env-entry-name>
	<env-entry-value>http://localhost:8080/ibisph-view/Transform
		?xslt=home.xslt
		&xml=home/home.xml
	</env-entry-value>
	<env-entry-type>java.lang.String</env-entry-type>
</env-entry>
		

SECURITY

JAAS Security == to Spring/ACEGI


WAR SYMBOLIC LINKS

The context configuration needs something like:
<Context path="/myApp" docBase="myApp" debug="0">
  <Resources 
	className="org.apache.naming.resources.FileDirContext" 
	allowLinking="true"
  />
</Context>
		
With the default catalina.policy, this still won't work if your jar is outside of the web-app, and you are running "-security". In this case you also need to edit catalina.policy to grant rights to the file.


URLS / LINKS

The information provided was retrieved on: Mon, 18 November 2019 4:49:18.

Content updated: Wed, 4 Nov 2015 09:26:28 MST