This is version . It is not the current version, and thus it cannot be edited.
[Back to current version]   [Restore this version]

Running JSPWiki on the Mainframe#

This a summary of hints and tips on running JSPWiki in Tomcat on the mainframe.

What's the big deal ?#

The IBM Mainframe runs a whole series of operating systems:

  • z/OS (formerly called OS/390 and MVS
  • z/Linux
  • VSE
  • TPF
  • z/VM (Hypervisor that can run all the OS's mentioned above)
  • CF code
  • anymore ?

The "flagship operating system" is z/OS, mainly used by financial institutions and multinationals. z/OS runs on IBM proprietary hardware, the current model is IBM System z10.
You can also run it under a Hercules emulator.

z/OS offers Unix System Services. So basically you can run Unix-type applications on the mainframe, at least that's the theory. In practice, most applications cannot be easily ported.

For Java this is different, Java offers real platform independence, so running Java applications on the mainframe is not a big deal.

The major big difference with other OS's is the default encoding, which is EBCDIC (CP037 or Cp1047). This is also true for Java applications, although you can start a JVM with ' -Dfile.encoding=ISO8859-1' (IBM WebSphere Application Server does so)

For most Systems programmers, running JSPWiki on the mainframe is a natural choice:

  • you know your way around in the environment
  • you can reuse your existing backup procedures
  • reuse your existing disaster recovery procedures
  • integrate with your existing RACF/ACF2 security package

Installing Tomcat#

  • download Tomcat
  • unzip it
  • binary upload it to the mainframe
  • ascii->ebcdic convert your shell scripts
  • this stuff should go in a read-only mounted HFS, you can then create instances in (for example) /var/tomcatxx (anticipating about 36^2 instances) :

total 120
lrwxrwxrwx   1 $$BPXRT  FUSPOS        22 Sep 26  2006 bin -> /usr/local/tomcat/bin/
drwxrwx---   3 WIKI00U  USIZOS05    8192 Feb  9 09:25 conf
lrwxrwxrwx   1 $$BPXRT  USIZOS05      21 Jan 28 10:21 lib -> /usr/local/tomcat/lib
drwxrwx---   2 WIKI00U  USIZOS05   28672 Feb 11 06:00 logs
drwxrwx---   2 WIKI00U  USIZOS05    8192 Jan 12 06:58 temp
drwxrwxr-x   5 WIKI00U  USIZOS05    8192 Feb 10 08:50 webapps
drwxrwx---   3 WIKI00U  USIZOS05    8192 Jan 12 07:07 work
metskem@xat1:/var/tomcat00/webapps>cd webapps
total 10304
drwxrwxr-x  10 WIKI00U  USIZOS05    8192 Jan 12 13:44 ROOT
lrwxrwxrwx   1 $$BPXRT  USIZOS05      30 Jan 28 10:47 docs -> /usr/local/tomcat/webapps/docs
lrwxrwxrwx   1 $$BPXRT  USIZOS05      38 Jan 28 10:47 host-manager -> /usr/local/tomcat/webapps/host-manager
lrwxrwxrwx   1 $$BPXRT  USIZOS05      33 Jan 28 10:47 manager -> /usr/local/tomcat/webapps/manager

  • run it as a batchjob, or better, run it as a started task (STC)
    an example STC proc:
//TOMCAT PROC ID='00',ACTION='run',JMXPORT='5001'                    
// PARM='SH /usr/local/sys2/bin/ &ID &ACTION &JMXPORT'      
//STDOUT   DD  SYSOUT=*,RECFM=VB,LRECL=1024,HOLD=YES                 
//STDERR   DD  SYSOUT=*,RECFM=VB,LRECL=1024,HOLD=YES                 
This can be started with the following operator commands :
S tomct,jobname=tomcat00,ID=00,ACTION='run' 
S tomct,jobname=tomcat00,ID=00,ACTION='stop'
With an example startup script:
# setup DB2 JDBC stuff:
export LIBPATH=/usr/lpp/db2810/jcc/lib:$LIBPATH
export ID=$1
export ACTION=$2
export JMXPORT=$3
export CATALINA_HOME=/var/tomcat$ID
export JAVA_HOME="/usr/lpp/java/J6.0_64"
#export JAVA_OPTS=" -Xmx256M  -Xshareclasses:name=RaboDefaultCache,verbose,groupAccess -Xscmx100M "
export JAVA_OPTS=" -Xmx256M  "
if [ $ACTION != stop ]
   echo "using JMX port $JMXPORT"
   export JAVA_OPTS="$JAVA_OPTS$ID/conf/jaas.config \
   -Ddb2.jcc.propertiesFile=/var/tomcat$ID/conf/ \$JMXPORT \ \ \$ID/conf/jmxremote.password \$ID/conf/jmxremote.access"
umask 007

Installing JSPWiki#

Basically the same procedure

  • download JSPWiki
  • unzip it
  • binary upload to tomcat's webapp directory (do not just drop the warfile !)
  • customize your (and optionally web.xml and jspwiki.policy)

Authentication (and authorization) against SAF #

You probably don't want to run production with the default userdatabase.xml / groupdatabase.xml.
So here are some options to use your SAF security system (RACF, ACF2, TopSecret).

Tomcat realm#

Attached you will find a RACFRealm(info) implementation.
This can be used when you have configured Container Managed Authentication.

  • drop this jar file in tomcat's lib directory
  • configure the following (example) in your server.xml:
    <Resource name="RACFDatabase" auth="Container"
	      description="RACF database"/>
    <Realm className="nl.rabobank.hdw.tomcat.realm.RACFRealm"/>
  • create an EJBROLE class profile with the name <userid>.<roleName> and permit users/groups.
    So if your tomcat runs with userid TOMCAT75, you need profile TOMCAT75.manager for the manager application.

Recycle tomcat and fire up the tomcat manager application, you should be prompted (Basic Authentication) for your RACF Userid/password.

If you want to use this for JSPWiki, simply enable Container Managed Authentication in the web.xml (see the web.xml for instructions), and create profiles for the roleNames that are mentioned in JSPWiki's web.xml (Admin / Authenticated)

There is one big disadvantage of this way of authentication, and that is that you don't get useful error messages back. In our shop we had complaints from people that could not login because of expired passwords or revoked userids and during their login attempt they were not told so. (the JAAS login module has a solution for this, skip to the next paragraph)

JAAS Login module#

The JAAS login module is just what it says. It's an implementation of the

To use it in JSPWiki :

  • drop the attached racfloginmodule(info) in tomcat's lib directory
  • configure this in
jspwiki.loginModule.class = nl.rabobank.hdw.auth.login.RACFLoginModule
  • do not use Container Managed Authentication in this case

That's it, recycle your tomcat and login

Pit falls#

Assuming ASCII#

Some Java applications make the false assumption that the default encoding is ASCII, and those don't run correctly on the mainframe.

So when doing IO (files, sockets) think about what the encoding is for the data you are writing/reading :

String encoding = "ISO8859-1";
String fileName = "/tmp/myWonderfulFile";
// reading :
BufferedReader in = new BufferedReader(new InputStreamReader(new FileInputStream(new File(fileName)), encoding));
// writing :
BufferedWriter out = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(new File(fileName)), encoding));

// Specify an encoding when using the getBytes method to convert a String to a ByteArray:

byte myBytes = myString.getBytes("8859_1");

// Also specify an encoding when creating a String from a ByteArray:

String myString = new String(myBytes, "8859_1"); 

Shell script files in DOS format#

If your shell scripts are in DOS format (instead of Unix format) they don't run.
The easiest way to check this is use your favorite Editor (UltraEdit or something else) and convert them to Unix format.
You can also check it with the hexdump command:

metskem@xat1:/usr/local/tomcat/bin>hexdump | grep '0d 15'
You should not see that many '0d 15' occurrences.

You can strip off these hex'15' chars with (example) :

cat | tr -d '\r' >

Add new attachment

Only authorized users are allowed to upload new attachments.

List of attachments

Kind Attachment Name Size Version Date Modified Author Change note
racfloginmodule.jar 20.4 kB 1 18-Feb-2009 07:44 Harry Metske properly handle return/reason codes
racfrealm.jar 15.6 kB 1 17-Feb-2009 07:38 Harry Metske a new version that uses JUL instead of commons-logging
« This particular version was published on 11-Feb-2009 09:08 by Harry Metske.