Technical Notes

Upgrading to Reflection for the Web 2008
Technical Note 2349
Last Reviewed 13-Nov-2008
Applies To
Reflection for the Web version 7.0 through 9.6
Reflection for the Web 2008 R1
Summary

This note describes how to upgrade to Reflection for the Web 2008 R2 from Reflection for the Web 7.x, 8.x, 9.x or Reflection for the Web 2008 R1.

For information about upgrading from Reflection for the Web version 5.x or 6.x, see Technical Note 2350.

When you upgrade, it is strongly recommended that you follow the steps in the order they are presented:

Note the following:

• The term "Reflection management server" refers to the Administrative WebStation plus the terminal emulation files.
• If after upgrading, you receive error messages when trying to make a secure connection, see Technical Note 1956, Error Message: "Invalid or missing authorization token."
• If you have server replication enabled in your environment, you must disable replication before you upgrade Reflection for the Web:

1. Configure the master server and each slave server as a standalone server.
2. Upgrade all servers, following the instructions in this technical note.
3. Configure the master server to master mode and define the slave servers.
4. Configure the slave servers to slave mode and point each slave server to the master server.

Step I: Uninstall Reflection for the Web 7.x, 8.x, 9.x, or Reflection for the Web 2008 R1 Components

For all installation methods, prior to uninstalling Reflection for the Web, copy and save the following files:

• cacerts in the [Reflection management server installation]/_jvm/lib/security/ directory.
• any files that you customized in the [Reflection management server installation]/jakarta-tomcat-[version number]/webapps/rweb/ or [Reflection management server installation]/jakarta-tomcat-[version number]/webapps/rweb/gm/ directory.
• if you used the UDC Mapping tool in the Administrative WebStation to assign custom characters to EBCDIC values and you want to retain those mappings, save a copy of the udc.xml file that is in the <Reflection management server installation>/ReflectionData/ directory.

Remove Reflection for the Web 7.x, 8.x, 9.x, or Reflection for the Web 2008 R1 files from your server. To uninstall a previous version:

• If you used an automated installer, follow one of these procedures:
  • Windows: Go to Start > Programs > WRQ (or Attachmate for version 9.x or higher) Reflection for the Web > WRQ (or Attachmate for version 9.x or higher) Reflection for the Web Uninstallation.
  • Windows: Run uninstaller.exe from the <installation folder>\_uninst\ folder.
  • Linux or Solaris: Run uninstaller.sh from the <installation directory>/utilities/ directory. An X11 window is required to run the graphical interface. Ensure that you have root access, and then enter this command:

• On other platforms, shut down the Reflection servers, save these files and directories (in addition to those listed above for all installation methods), and then uninstall:

• The web.xml file in the [Reflection management server installation]/jakarta-tomcat-[version number]/webapps/rweb/WEB-INF/ directory.
• Any unprotected, static sessions in the [Reflection management server installation]/jakarta-tomcat-[version number]/webapps/rweb/session/ directory. These sessions may also be saved in other directories within the webapps directory.
• The [Reflection management server installation]/ReflectionData/ directory.

• The [security proxy installation]/conf/ directory and the [security proxy installation]/keystores/ directory. This saves your server.properties file and your certificates.

• The web.xml file in the [metering server installation]/jakarta-tomcat-[version number]/rwebmeter/WEB-INF/ directory.

• The Tomcat keystore in the [tomcat installation]/jakarta-tomcat-[version number]/conf/ directory.

Step II: Reboot the Server(s) from which You Uninstalled Reflection

If you are running in a Windows environment, restart the server(s) from which you uninstalled Reflection for the Web components.

For all other environments, restarting the servers(s) is not necessary; proceed to Step III.

Step III: Install Reflection for the Web 2008 Components

Install the Reflection for the Web 2008 components now. When you upgrade from a previous version,

• Install Reflection for the Web 2008 in a non-web-servable space. This must be a directory that is inaccessible to your web server. Install Reflection for the Web 2008 in the same directory structure that Reflection for the Web used in the previous version.
• Select and follow an installation procedure described in the InstallGuide.html file, located at the root of the product installation package (or CD) for your platform. The Reflection for the Web 2008 Installation Guide is also available on the Support site at http://support.attachmate.com/manuals/rweb2008.html.

Step IV: Upgrade Outdated Files

The steps to upgrade outdated files vary depending on how you originally installed Reflection for the Web.

If you installed using an automated installer:

This section includes information about retaining settings for the management server, servlet runner, security proxy server, and metering server if you originally installed Reflection for the Web using an automated installer.

Note the following:

• To retain customized settings and imported certificates, and to upgrade JCE policy files and UDC files, follow the steps in the "For all installation types:" section.
• To upgrade sessions that were not saved using the Session Manager or that were manually edited, see the topic, Upgrading from an Earlier Version - Static Sessions, in the Installation Guide: http://docs.attachmate.com/reflection/rweb/2008/R2/readme/en/html/readme_static.html.

Reflection management server and servlet runner

Reflection management server and servlet runner settings have been retained. If you did not customize files or add certificates to the management server trusted list, no further upgrade steps are necessary.

Security proxy server

To ensure that you can edit your existing secure sessions or create new secure sessions in the Session Manager, export the security proxy server settings to the Administrative WebStation.

1. Run the Security Proxy Wizard.
2. Click Save to save your settings. You are prompted to export your settings to the management server.

3. Ensure that the management server name, port, and context are correct, and then click Export.

For detailed configuration information, see the tutorial, Setting Up the Security Proxy, in the Administrative WebStation.

Metering server

Upgrade of the metering server is complete. To ensure that your settings were saved correctly, open the Metering Configuration tool. For detailed configuration information, see the tutorial, Setting Up the Metering Component, in the Administrative WebStation.

If you installed using archive files (a manual installation):

Note: Several of the steps below reference the ReflectionData directory. The default location of ReflectionData is as follows. Note, however, that the automatic installation program employs a different default location than the one shown here.

Ensure that these files are copied or edited correctly.

Reflection management server:

• Copy the old ReflectionData directory into your new Reflection management server directory structure. If you are copying this directory into the default location (listed above), you do not need to edit the web.xml file.

• The SSL port is set as 443 by default. If you need to change the port number, start the management server. Then, open PropertyDS.xml in the ReflectionData directory. Change the value from 443 to the appropriate port number in the section below:

Security proxy server:

Copy the /conf/ and /keystores/ directories that you saved in Step I into the new security proxy installation.

To ensure that you can edit your existing secure sessions or create new secure sessions in the Session Manager, export the security proxy server settings to the Administrative WebStation.

1. Run the Security Proxy Wizard.
2. Click Save to save your settings. You are prompted to export your settings to the management server.

3. Ensure that the management server name, port, and context are correct, and then click Export.

For detailed configuration information, see the tutorial, Setting Up the Security Proxy, in the Administrative WebStation.

Metering server:

If you have copied the ReflectionData directory into the default location, you do not need to edit the web.xml file.

If you do need to specify a non-default location for ReflectionData, edit the web.xml file. Copy the path to the ReflectionData directory from the web.xml file you saved into the new web.xml file in [metering server installation path]/jakarta-tomcat-[version number]/webapps/rwebmeter/WEB-INF directory.

Servlet runner:

Copy the Tomcat keystore you saved into [installation path]/jakarta-tomcat/conf/.

In a text editor, open <installation path>/jakarta-tomcat-[version number]/conf/server.xml. Make necessary modifications to the HTTP port and HTTPS port.

If necessary, upgrade your JDK or JRE to Java SE 6.

For all installation types:

The following procedures to upgrade outdated files apply to all Reflection for the Web installation types.

JCE policy files

If you installed the JCE unlimited strength policy files from the Sun web site to support 192-bit and 256-bit AES encryption in your previous version of Reflection, the downloaded files are uninstalled from the management server without notification during an automated uninstallation.

If you installed using an automated installation, the JRE version 6.0 was installed. To continue supporting 192-bit and 256-bit AES encryption, download and install the most recent version of the JCE unlimited strength jurisdiction policy files from the Sun web site. For more details, see the Security Proxy Wizard help (Security Proxy Wizard > Proxies > Add or Modify > Add or Modify > Help).

Customized login and links lists

If you customized the login and links list pages, copy the LauncherHTML.jsp file from the backup of the [Reflection management server installation]/jakarta-tomcat-[version number]/webapps/rweb/gm/ directory into the [Reflection management server installation]/jakarta-tomcat-[version number]/webapps/rweb/templates directory.

In Reflection for the Web 2008 R2, you can use JSP templates to embed dynamic Reflection sessions in custom web pages that you create. The product includes an <rweb_context>/templates folder with instructions on how to use templates (templates.txt) and sample templates that you can use as a starting point for creating your own template. (In a default installation, the templates folder is located in /ReflectionServer/jakarta-tomcat/webapps/rweb/templates.) Use the webapps/rweb/templates/samples/customloginpage.jsp as a guide to see how the new Reflection applet tag elements are inserted into your custom content. For more information, see Technical Note 2386.

Note: The Reflection for the Web 2008 links list does not currently support Reflection for UNIX and OpenVMS 2008 or Reflection for IBM 2008 connections.

Once your custom page is complete, use the General Settings page of the Reflection for the Web Administrative WebStation to specify the name of your customized login/links list page.

UDC mapping

If you saved your UDC Mapping settings by saving the udc.xml file in Step I, copy the udc.xml file into the new ReflectionData directory in Reflection for the Web 2008.

Trusted certificates

Automatic installation: If you added certificates to the management server trusted list, the imported certificates are stored in the cacerts file. This file was automatically saved during uninstallation of your previous version in the root of the Reflection management server installation, and renamed. The new name is created by appending an underscore and a three-digit number to the original file name, for example, cacerts_000. Copy this file into the new <Reflection management server installation>/_jvm/lib/security/ directory, and then rename the file to cacerts.

Manual installation: Copy the old cacerts into the [Reflection management server installation]/_jvm/lib/security/ directory.

SSL client certificates or SSH user keys

If you enabled client authentication in version 7.x or 8.x, each client computer had a client certificate client.pfx file in its user.home folder. This directory contains required files for host-based authentication. The certificates should now be stored in the RWEB_PREFS folder on the user's computer. To find the folder, click About Reflection on the Help menu of a terminal session, then click the System Information tab.

If you used the Secure Shell transport in HP or VT sessions and you authenticated using user keys in earlier versions of Reflection for the Web, the public/private key pairs were installed in the clients' user.home\.ssh\ directories. The key pairs should now be stored in the RWEB_PREFS\.ssh folder on the user's computer. To confirm the location of this folder, to find the folder, click About Reflection on the Help menu of a terminal session, then click the System Information tab.

Customized files

To retain any unprotected static sessions, see the topic, Upgrading from an Earlier Version - Static Sessions, in the Installation Guide: http://docs.attachmate.com/reflection/rweb/2008/R2/readme/en/html/readme_static.html.

To retain your settings if you saved the LauncherHTML.jsp file from your version 7.x or 8.x installation, save LauncherHTML.jsp in your new Reflection for the Web installation at [Reflection management server installation]/jakarta-tomcat/webapps/rweb/gm/.

IIS Integration

If your previous installation of Reflection for the Web was integrated with IIS and you installed using an automated installer, the integration was detected and settings were reconfigured during the installation. You will need to stop and restart IIS and the Reflection management server service for integration to take effect.

If you installed using an archive file, re-run the IIS Wizard. (In an automated installation in Windows, for example, go to Start > Programs > Attachmate Reflection for the Web > Utilities > IIS Wizard. For more information, see Technical Note 2195.) Enter the HTTPS port number, click Next, and then Finish.

Note: If you are using Windows Server 2003 or if the server has multiple web sites, see Technical Note 2195 for more information about integrating Reflection for the Web with IIS.

Step V: Update Printing Sessions

When upgrading from Reflection for the web 7.x or 8.x to Reflection for the Web 2008, your printer sessions, print setup, and the test print feature may no longer function.

If you experience this problem, follow the steps below.

1. Open the Reflection for the Web Administrative WebStation and click Session Manager.
2. Click the printer session link and then click Save Settings.
3. Repeat steps 1 and 2 for each printer session.

Additional Resources

For more information about Reflection for the Web 2008, see the following resources:

Obtaining Reflection for the Web

Maintained customers are eligible to download the latest product releases from the Attachmate Download Library web site: https://download.attachmate.com/Upgrades/. For more information about logging into and using the Attachmate Download Library, see Technical Note 0200.

Documentation

Reflection for the Web 2008 documentation is available on the Attachmate Support site: http://support.attachmate.com/manuals/rweb2008.html.

Technical Notes

See Technical Note 9988 for a list of Reflection for the Web technical notes.

Related Technical Notes

0200	Using the Attachmate Download Library (FAQ)
1665	Upgrading Reflection for the Web from an Evaluation Copy to a Licensed Copy
1956	Error Message: "Invalid or missing authorization token"
2195	Integrating Reflection for the Web with IIS
2350	Upgrading to Reflection for the Web 2008 from Reflection for the Web Version 5.x or 6.x
2386	Using Templates in Reflection for the Web 2008
9988	Reflection for the Web Technical Notes