Technical Notes

Installing Reflection for the Web on Mac OS X
Technical Note 2343
Last Reviewed 30-May-2008
Applies To
Reflection for the Web 2008 (All Editions)
Reflection for the Web version 8.0 through 9.x
Summary

Use this document to manually install Reflection for the Web to a machine running Mac OS X or Mac OS X Server. 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.

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

Conventions Used in 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 included the version number, 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.
• When installing Reflection to a Mac OS, use the Terminal application to perform UNIX installation and configuration commands.
• Install Reflection to Mac OS 10.2 or higher, which has Java 1.4.x pre-installed.

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

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

Installing and Configuring Tomcat

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

Note: By default, Mac OS X Server version 10.5 includes Tomcat 6.0, and Reflection for the Web 2008 includes Tomcat 6.0.14. Reflection for the Web 8.0 – 9.x includes Tomcat 5.0, but can be configured to use version 4.1. If you plan to retain Tomcat version 4.1, skip to Installing and Configuring Reflection for the Web.

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 is recommended for Reflection for the Web 2008, JDK 1.4 or higher is recommended for earlier versions; 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 Reflection for the Web 9.5, Java 1.3 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 and running on the Mac machine when Tomcat was installed, you may need to modify Tomcat's HTTPS and HTTP port numbers to avoid conflict 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. For details regarding 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 installing to a Mac OS X Server, you must configure the appropriate user and group permissions for the Tomcat process and all the files it needs to access.
• 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 the following:

• By default, the administrative password is admin.
• On Mac OS X Server, if you chose to retain Tomcat version 4.1, the server is configured to use port 9006 for http and port 8443 for https. To verify this setting, view /Library/Tomcat/conf/server.xml and look for the following lines:

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 Mac OS X 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 following for additional information:

• The log files located at /Library/Tomcat/logs.
• If ports below 1024 are being used for http or https, verify that you are logged in as root before running ./startup.sh.

Related Technical Notes

1668	Reflection for the Web Information Resources
1699	Installing Reflection for the Web on UNIX or Linux
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
2342	Installing Reflection for the Web on a Mainframe with Tomcat