Attachmate Worldwide  |   Contact Us  |   The Attachmate Group
Extend. Manage. Secure. More than 30 years in the business. Over 65,000 customers.

Technical Notes

Installing Reflection for the Web 2008 on a Mainframe with Tomcat
Technical Note 2342
Last Reviewed 10-Dec-2009
Applies To
Reflection for the Web 2008 (All Editions)
Summary

This technical note describes how to install Tomcat and the Reflection for the Web 2008 management server on a mainframe under UNIX Systems Services (USS) on z/OS.

There are several steps to installing the Reflection for the Web 2008 management server on a mainframe. (Note: If you want to install Reflection for the Web 2104, Reflection for the Web 2011, or Reflection Security Gateway 2014 on a mainframe, see Technical Note 2659.)

  • Java version 1.5 or higher* must be installed on the mainframe. Note: This technical note assumes that Java is already installed on the mainframe. You can obtain the version of Java appropriate for your operating system version from IBM.

* The management server also runs on Java version 1.4.2, but requires that you run Tomcat 5. (Reflection for the Web 2008 ships with Tomcat 6.) The steps in this technical note are based on Java version 1.5 or higher and Tomcat 6. If you need help installing with Java version 1.4.2 and Tomcat 5, contact technical support: http://support.attachmate.com/contact/.

  • Install and configure Tomcat (the servlet engine) on the mainframe.
  • Install Reflection for the Web on the mainframe.

Note the following:

  • You must have a minimum 2GB of disk space allocated.
  • You must have root or su privileges to install Reflection for the Web on the mainframe.

The following topics are covered in this technical note:

Installing and Configuring Tomcat on the Mainframe

Once Java is installed on the mainframe, follow the steps below to install and configure Tomcat (the servlet engine) on the mainframe.

Installing Tomcat

  1. Create a directory called ReflectionServer in the Hierarchical File System (HFS):
mkdir ReflectionServer
  1. Using an FTP client, transfer (in binary mode) the zipped Tomcat file, \install\nonautomated\tomcat.zip, located with the downloaded product files (or on the Reflection for the Web CD), to the location on the mainframe that you created in the previous step, for example:
/u/ReflectionServer
  1. Enter the following command to extract the Tomcat files to /u/ReflectionServer:
jar -xvf tomcat.zip

Converting the Shell Script Files on the Mainframe

The shell scripts (*.sh) in the /ReflectionServer/jakarta-tomcat-6.0.18/bin directory need to be converted from ASCII to EBCDIC. The simplest way to do this is to FTP them to your PC using binary mode and then upload them to the /ReflectionServer/jakarta-tomcat-6.0.18/bin directory using ASCII. The scripts should now be readable in TSO or USS. Note: Proper script conversion is critical to the success of your Reflection for the Web installation.

Follow the steps in the sections below to download, edit, upload, and set permissions for the shell script files.

Note: When editing a file in a text editor, be sure to use a text editor that does not add carriage return characters to your file.

Download the .sh Files

  1. Navigate to /u/ReflectionServer/jakarta-tomcat-6.0.18/bin.
  2. Using an FTP client, transfer the following files in binary mode to a directory on your PC (C:\sh):
catalina.sh
setclasspath.sh
setenv.sh
shutdown.sh
startup.sh
version.sh
svsetup.sh
  1. Use WordPad to open each file, and then Save as type "Text Document – MS-DOS Format." Be sure to change the file extension from .txt to .sh.
  2. Familiarize yourself with the general appearance of the file, such as the formatting. This will enable you to verify the readability of the file in a later step in the Upload the .sh Files section.

Setting Up JRE Environment for Tomcat

  1. In your PC directory (C:\sh), open the setenv.sh file in a text editor.
  2. Edit the # Sets environment variables for Tomcat section:
    1. Set the JAVA_HOME variable path so that it corresponds to the Java location on your mainframe. Note that the location will vary depending on the Java version you have installed and the directory to which you installed it.
    2. Edit the CATALINA_OPTS variable to remove the –server option and to specify the maximum java heap size.

The edited section of your setenv.sh file should now look like the following:

# Sets environment variables for Tomcat
JAVA_HOME=/usr/lpp/java/J1.5
CATALINA_BASE=${CATALINA_HOME}
# Remove the -server option if a non-Sun JDK is used.
CATALINA_OPTS="-Xmx512m"

Upload the .sh Files

Using an FTP client, transfer the following files in ASCII mode to the /u/ReflectionServer/Jakarta-tomcat-6.0.18/bin directory on the mainframe:

catalina.sh
setclasspath.sh
setenv.sh
shutdown.sh
startup.sh
version.sh
svsetup.sh

To verify that your files are readable in USS, use the following commands:

cat catalina.sh
cat setclasspath.sh
cat setenv.sh
cat shutdown.sh
cat startup.sh
cat version.sh
cat svsetup.sh

The files should appear as they did in step 4 of Download the .sh Files.

Verifying the .sh File Permissions and Ownership

On the mainframe, change the file permission of the *.sh files using the follow command:

chmod 755 *.sh

Verify that the ownership on the files you just uploaded are correct. Perform a long listing (ls -l) of the files to compare the ownership. The owner and group should be identical to other files in the /bin directory. If the ownership and group are not correct, then change the ownership using the chown command. (For information on the chown command, refer to your mainframe documentation or the man pages.)

Modifying the HTTP and HTTPS Port Values

If another web server was present on the mainframe when Tomcat was installed, you need to modify Tomcat's HTTP and HTTPS port values to avoid port conflicts with the other web server.

Modifying the HTTP Port Value

Follow these steps to modify the Tomcat HTTPS and HTTP port values:

  1. Navigate to the /u/ReflectionServer/jakarta-tomcat-6.0.18/conf directory.
  2. Using an FTP client, transfer the server.xml file in binary mode to a directory on your PC.
  3. Open the server.xml file in a text editor. (Note: Permissions for the server.xml file should be set to 755.)
  4. To modify the HTTP port, locate an entry in the server.xml file that begins with the following:
<!-- A "Connector" represents an endpoint by which requests are received and responses are returned. Documentation at :
Java HTTP Connector: /docs/config/http.html (blocking & non-blocking)
Java AJP Connector: /docs/config/ajp.html
APR (HTTP/AJP) Connector: /docs/apr.html
Define a non-SSL HTTP/1.1 Connector on port 80
-->
    1. Change the default HTTP port from 80 to a port that is not already in use. For example, change the number from 80 to 8880, shown in red below.
    2. Change the redirectPort from 443 to the HTTP port you have defined, for example, 8443 (shown in red below). After editing, the entry should look like this:
<!-- A "Connector" represents an endpoint by which requests are received and responses are returned. Documentation at :
Java HTTP Connector: /docs/config/http.html (blocking & non-blocking)
Java AJP Connector: /docs/config/ajp.html
APR (HTTP/AJP) Connector: /docs/apr.html
Define a non-SSL HTTP/1.1 Connector on port 8880
-->
<Connector port="8880" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />

<!-- A "Connector" using the shared thread pool-->
<!--
<Connector executor="tomcatThreadPool"
port="8880" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />
-->
  1. Using an FTP client, transfer the server.xml file in binary mode to the following directory on the mainframe:
/u/ReflectionServer/jakarta-tomcat-6.0.18/conf

Modifying the HTTPS Port Value

To use HTTPS with Tomcat when using the IBM Java JDK, you need to modify the server.xml HTTPS connector parameters.

  1. Open the server.xml file in a text editor.
  2. Make the following modifications to the file:
    1. Modify the connector HTTPS port, sslProtocol, and add an algorithm parameter.
    2. The keystoreFile can be the relative path to Reflection for the Web’s Tomcat conf/keystore file. Use keytool to import the certificate into keystore.

The file should now look something like the following:

<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!-- https_connector_placeholder_begin -->
<Connector port="8443"
protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150"
scheme="https" secure="true"
keystoreFile="conf/keystore" keystorePass="changeit"
keystoreType="JKS" clientAuth="false" algorithm="IbmX509" sslProtocol="TLS" />
<!-- https_connector_placeholder_end -->
    1. Modify sslProtocol and add an algorithm parameter for X.509 authentication, as shown below:
<!-- Define an SSL HTTP/1.1 Connector on port 444 for X.509 client authentication-->
<Connector port="444"
minProcessors="5" maxProcessors="75" enableLookups="false"
acceptCount="10" debug="0" scheme="https" secure="true"
keystoreFile="conf/keystore" keystorePass="changeit"
keystoreType="JKS" clientAuth="true" algorithm=”IbmX509” sslProtocol="SSL"/>

Replace Current Policy Files with Unlimited Strength Jurisdiction Policy Files

IBM's Java SDKs ship with limited jurisdiction policy files. If you use HTTPS or SSL, we strongly recommend that you replace the current policy files with unlimited strength jurisdiction policy files, which can be obtained from the following link. Locate and download the appropriate jurisdiction policy files for your environment to your workstation.

Unpack the ZIP file that you downloaded from IBM. To replace the files on the mainframe, local_policy.jar and US_export_policy.jar, transfer (in binary mode) the files from your workstation to the <java install directory>/jre/lib/security/ directory on the mainframe:

<java install directory>/jre/lib/security/local_policy.jar
<java install directory>/jre/lib/security/US_export_policy.jar

Installing and Configuring the Management Server on the Mainframe

Now that Java and Tomcat are installed, you are ready to install the Reflection for the Web 2008 management server on the mainframe:

  1. Create an rweb directory under /u/ReflectionServer/jakarta-tomcat-6.0.18/webapps/.
  2. Using an FTP client, transfer (in binary mode) the file \install\nonautomated\rweb.war located with the downloaded product files (or on the Reflection for the Web CD) to the /u/ReflectionServer/jakarta-tomcat-6.0.18/webapps/rweb directory on the Mainframe.
  3. Navigate to /u/ReflectionServer/jakarta-tomcat-6.0.18/webapps and enter the following command to extract the Reflection for the Web files:
jar –xvf rweb.war

This command extracts the Reflection for the Web files and creates the Reflection for the Web directory structure.

  1. Using an FTP client, transfer (in binary mode) the web.xml file to your PC from the mainframe:
/u/ReflectionServer/jakarta-tomcat-6.0.18/webapps/rweb/WEB-INF/web.xml
  1. Edit the web.xml file:
    1. Open the file web.xml in a text editor on your PC.
    2. In the web.xml file, replace the value for rwebdata_location_placeholder with /<PathTo>/ReflectionData (in our example, /u/ReflectionServer/ReflectionData). If the ReflectionData directory does not already exist, you must create it.

These values configure SSL to use the specified port. The resulting lines look like this:

<web-app>
<context-param>
<param-name>ReflectionData</param-name>
<param-value>/u/ReflectionServer/ReflectionData</param-value>
</context-param>
    1. Save the file.
  1. Using an FTP client, transfer (in binary mode) the web.xml file from your PC to the mainframe directory below:
/u/ReflectionServer/jakarta-tomcat-6.0.18/webapps/rweb/WEB-INF/web.xml

Note: Permissions for the web.xml file should be set to 644.

Starting Tomcat

To start Tomcat, follow these steps:

  1. Navigate to the /u/ReflectionServer/jakarta-tomcat-6.0.18/bin directory.
  2. At the prompt, enter the following command:
./startup.sh

You can configure Reflection for the Web to start automatically on USS using a Proc. For example:

//HOSTMCT PROC
//STEP1 EXEC PGM=BPXBATCH,REGION=0M,TIME=NOLIMIT,
// PARM='SH /usr/lpp/reflect/jakarta-tomcat-5.0.28/bin/
// startup.sh run'
//STDOUT DD PATH='/usr/lpp/reflect/jakarta-tomcat-5.0.28/logs/stdout.l-
// og',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//STDERR DD PATH='/usr/lpp/reflect/jakarta-tomcat-5.0.28/logs/stderr.l-
// og',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//STDENV DD DUMMY

Editing the PropertyDS.xml file

If you are using security, you will need to update the file, PropertyDS.xml, which is stored in the ../ReflectionData folder. Note: The file will be created once Tomcat is started.

  1. Using an FTP client, transfer (in binary mode) the PropertyDS.xml file to a temporary directory on your workstation.
  2. Open PropertyDS.xml in a text editor on your workstation.
  3. In the PropertyDS.xml file replace the value “443” with the value you are using for SSL (in our example, 8443).

Example:

<CORE_PROPERTY NAME="CS.HostPort">
<STRING>8443</STRING>
</CORE_PROPERTY>
  1. Using an FTP client, transfer the PropertyDS.xml file (in binary mode) to the ../ReflectionData directory.

Launching Reflection for the Web

Reflection for the Web opens by launching http://myhost.mycompany.com:port/rweb/AdminStart.html.

For example:

http://10.10.2.115:8081/rweb/AdminStart.html

The default password for Reflection for the Web Administrative WebStation is admin.

Related Technical Notes
2659 Installing Reflection Management Server on a Mainframe USS Partition

horizontal line

Did this technical note answer your question?

           


Need further help? For technical support, please contact Support.