Technical Notes

Installing Reflection for the Web on UNIX or Linux
Technical Note 1699
Last Reviewed 30-May-2008
Applies To
Reflection for the Web 2008 (All Editions)
Reflection for the Web version 8.0 through 9.6
Summary

Use this document to manually install Reflection for the Web to a machine running UNIX or Linux. This information is helpful if you experience difficulties with an automated installer or if no automated installer is available to install Reflection for the Web on your platform.

This technical note includes information about installing and configuring Java SDK, Tomcat, and Reflection for the Web on a UNIX or Linux machine. For information about installing on Mac OS X, see Technical Note 2343.

This information in this note is organized into the following sections:

Conventions Used in this Document

The instructions provided in this document apply to both UNIX and Linux systems; however, for ease of use, the term UNIX is used throughout this document.

This document assumes that you will install the Java SDK, Tomcat, and Reflection for the Web into the directories noted below. If any of these applications are installed in different locations, such as /opt, make the necessary path changes when following the steps provided in this document.

Beginning in Reflection for the Web 2008, the Tomcat directory no longer includes the version number, /jakarta-tomcat/; previous versions did, for example, /jakarta-tomcat-5.0.28/. This technical note will refer to the current Tomcat directory, /jakarta-tomcat/.

• Java Software Developer's Kit (Java SDK) version 1.5 or higher for Reflection for the Web 2008; Java SDK 1.4 or higher for earlier versions: /usr/java
• Tomcat: /usr/local
• Reflection for the Web: /usr/local/jakarta-tomcat/webapps/rweb

Before You Begin

Note the following before you install Reflection for the Web:

• For best results, proceed through each section in this technical note in the order presented.
• The steps presented in this document require that you are logged on to your UNIX system as root.

Attachmate Technical Support recommends that you review the Reflection for the Web Installation Guide, which is available with the product and online:

For additional Reflection for the Web resources, see Technical Note 1668.

Obtaining and Installing the Java SDK

If Java is already installed on your UNIX machine, skip to Installing and Configuring Tomcat. If Java is not yet installed, follow the steps below to obtain and install the correct version of Java.

Note the following:

• For HP-UX, obtain the Java SDK from http://www.hp.com/products1/unix/java/. The exact file needed depends upon your version of HP-UX. Follow the installation instructions obtained in the downloaded files, and then proceed to the next section.
• For AIX, obtain the Java SDK from http://www-106.ibm.com/developerworks/java/jdk/aix/service.html?SDFticket=. The exact file needed depends upon your version of AIX. Follow the installation instructions obtained in the downloaded files, and then proceed to the next section.

To obtain and install Java for other UNIX systems, follow these steps:

1. Navigate to the /usr directory. Create a sub-folder named /java:

2. Go to http://java.sun.com/ and download the correct Java SDK (version 1.5 or higher for Reflection for the Web 2008; Java SDK 1.4.x or higher for earlier versions) for your environment. Select the product for your UNIX operating system, and download the SDK.
3. Use the chmod command to configure the Java file with execute permissions for owner, group, and other:

4. Run the self-extracting file and extract the file into the /usr/java directory. For example, enter the following at the prompt:

5. Add Java's /bin directory to your $PATH.

6. To verify that your environment has been successfully configured, type the following at the prompt:

Installing and Configuring Tomcat

Once Java is installed, follow the steps below to install and configure Tomcat, the servlet runner.

1. Copy the zipped Tomcat file, \install\nonautomated\tomcat.zip, located with the downloaded product files (or on the Reflection for the Web CD) to /usr/local.
2. Enter the following command to extract the Tomcat files to /usr/local:

3. In the /usr/local/jakarta-tomcat/bin directory, open the setenv.sh file in the editor of your choice.
4. Set the JAVA_HOME and, if necessary, JSSE_HOME environment variable paths so that they correspond to your directory structure.

• The JSSE is incorporated in JDK version 1.4 or higher, so the JSSE_HOME variable should be left blank, JSSE_HOME=.
• JDK version 1.5 or higher (for Reflection for the Web 2008); JDK 1.4 or higher (for earlier versions) is recommended; however, if you are running JDK version 1.3x, the JAVA_HOME variable must point to the JDK installation directory, and the JSSE_HOME variable must point to the JSSE installation directory, typically <1.3x JDK installation path>/jre/lib/ext.

• Beginning with Rweb 9.5, 1.3 Java is no longer fully tested or supported.

5. Save and exit the file.
6. Use the following chmod command to configure all the .sh files with full access permissions for owner, and read and execute permissions for group and other.

Modifying the HTTPS and HTTP Port Numbers

If no other web server is configured on the machine where Tomcat was installed, skip to Installing and Configuring Reflection for the Web.

If another web server was present on the UNIX machine when Tomcat was installed, you may need to modify Tomcat's HTTPS and HTTP port numbers to avoid interference with the other web server.

When choosing a new port, select ports above 1024 (available to non-root users). Follow the steps below to change the Tomcat port numbers.

1. Navigate to /usr/local/jakarta-tomcat/conf.
2. Open the server.xml file in the editor of your choice.
3. To modify the HTTPS port, locate the following entry:

4. To modify the HTTP port, locate the following entry:

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. Also change the redirectPort from 443 to the HTTPS port you have defined, for example, 8443. After editing the entries should look like this:

5. Save the file.

Installing and Configuring Reflection for the Web

Now that Java and Tomcat are installed, you are ready to install Reflection for the Web.

Follow these steps to install and configure Reflection for the Web.

1. Copy the file \install\nonautomated\rweb.zip from the Reflection for the Web product package to /usr/local/jakarta-tomcat/webapps.
2. Navigate to /user/local/jakarta-tomcat/webapps and enter the following command to extract the Reflection for the Web files:

3. Now, edit the web.xml file to specify the ReflectionData directory location and the SSL port value:
   1. Navigate to the /usr/local directory and create a new directory named ReflectionData (if one does not already exist).
   2. Navigate to /usr/local/jakarta-tomcat/webapps/rweb/WEB-INF.
   3. Open the file, web.xml, in the text editor of your choice.
   4. In the web.xml file, replace the value for rwebdata_location_placeholder with /usr/local/ReflectionData (or the location and name of the directory you created in step 3a) and the value for https_port_placeholder with the HTTPS port number (configured in the previous section Modifying the HTTPS and HTTP Port Numbers). This configures SSL to use the specified port. The resulting lines look like this:

5. Save the file.

Configuring Reflection to Use HTTPS

If you do not plan to use HTTPS, skip to the next section, Starting Tomcat.

If you plan to use HTTPS to access the web server, you must use a server certificate.

You can configure Reflection to use either a self-signed certificate, or a Certificate Authority (CA) signed SSL server certificate. For information about Tomcat and CA-signed certificates, see Technical Note 1702.

Follow the steps below to start the Certificate Wizard, and then follow the Wizard instructions to create a self-signed certificate or to import a CA-signed certificate.

Note: This command must be run from the console that has a graphical UI or from a graphical user interface, such as Reflection X.

1. Navigate to the directory where CertWizard.jar is located; look in /usr/local/jakarta-tomcat/WRQUtilities.
2. At the prompt, enter the following command on a single line:

Starting Tomcat

To start Tomcat:

1. Navigate to /usr/local/jakarta-tomcat/bin.
2. At the prompt, enter the following command:

Note the following

• If you are using Java SDK version 1.3.x and Tomcat does not start, refer to the JavaTM 2 Runtime Environment, Standard Edition Installation Notes at http://java.sun.com/j2se/1.3/jre/install-linux.html. Under Known Problems, locate the issue tracked as number 4466587, and follow the workaround instructions.
• There is no visible indication in the shell when startup.sh has successfully started Tomcat, and it may take a while before Tomcat is fully started and responsive on its listening ports. Use the ps or top command to see if it is running.

Accessing Reflection for the Web

To start Reflection for the Web Administrative WebStation, open your web browser and enter the appropriate URL for your configuration into the Address field, replacing the <server name> and <port #> sections with your site specific information:

For HTTPS

For HTTP

Note: By default, the administrative password is admin.

Stopping Tomcat

If you need to stop Tomcat, navigate to /usr/local/jakarta-tomcat/bin and enter:

Optional: Security Proxy Server and Metering

For information about manually installing and configuring Reflection for the Web's security proxy server feature on UNIX systems that are not supported by the automated installation methods, see Technical Note 1812.

Note: Beginning in Reflection for the Web 2008, the security proxy server is not included in the Standard Edition.

To enable the optional metering feature in Reflection for the Web, see Technical Note 1824.

Troubleshooting

If you experience difficulties getting Tomcat to start, or getting Reflection for the Web to load, check the log files located at /jakarta-tomcat/logs.

Related Technical Notes

1668	Reflection for the Web Information Resources
1702	Implementing a CA Signed Certificate for Tomcat
1788	Reflection Terminal Emulation Products and Linux/UNIX Workstations
1812	Setting Up the Reflection for the Web Security Proxy Server in UNIX, Linux, or Mac OS X
1824	Installing Reflection for the Web Metering Server in UNIX
2343	Installing Reflection for the Web on Mac OS X
9988	Reflection for the Web Technical Notes