| |
QuickStart Instructions for PASSPORT WEB TO HOST® on IBM WebSphere Application Server
Background Information
IBM WebSphere Application Server started life as a “servlet express” in 1998 and since then IBM have shipped several versions and editions for the different operating systems and platforms. IBM WebSphere Application Server V5 was a major rewrite of the previous versions code base and was the first time that it was coded from a common code base, so IBM WebSphere Application Server across all deployment platforms, from Intel x86 to the mainframe now uses substantially the same code. This coupled with the singularly familiar and easy to use Administration console should mean that these instructions are valid for installing PASSPORT WEB TO HOST on to IBM WebSphere Application Server on ANY platform.
Also, with WAS V5 and later, applications are installed using the administrative console or the “wsadmin” scripting interface. The WebSphere administrative console is the graphical, web-based tool that you use to configure and manage an entire WebSphere cell. It supports the full range of product administrative activities, such as creating and managing resources, applications, viewing product messages, and so on.
As of August 2007, we had successfully tested installation of PASSPORT WEB TO HOST on IBM WebSphere Application Server V6.1 (Windows and z/OS platforms). This document provides instructions on how to install PASSPORT WEB TO HOST on a Windows server running IBM WebSphere Application Server V6.1.
PASSPORT WEB TO HOST EAR file
PASSPORT WEB TO HOST is packaged as an Enterprise Application Archive file (EAR) file and it must run out of an expanded directory structure. An EAR is a zipped file so the contents can be expanded using a product such as WinZip. Our EAR file includes a Web Archive (WAR) file that contains all the PASSPORT installation files so if you prefer to work directly with it then you may do so. Different application servers have different functionality with regard to deployment and expanded directory structure as discussed below:
- Deploy compressed archive to working directory- On some application servers (such as IBM WebSphere V5 and higher), the deployment process expands the EAR/WAR file automatically into a working directory and from that point forward, the expanded directory is considered to be the application. For these application servers, you deploy the compressed EAR/WAR file and work in the resulting directory structure. The instruction below discusses this deployment method.
- Deploy expanded archive as working directory- On other application servers (such as BEA WebLogic), the deployment process expands the EAR/WAR file into a temporary directory and (conceptually), the compressed EAR/WAR file is still considered to be the application. For these application servers, you must expand the EAR/WAR file manually and then deploy the expanded directory structure, which becomes your working directory. For more information, please refer to QuickStart Instructions for PASSPORT WEB TO HOST® on BEA WebLogic Application Server.
1. Check your system requirements
Before installing PASSPORT WEB TO HOST, make sure that your web server meets the following system requirements. If these requirements are not met, you may have unpredictable results.
- TCP/IP connection to the host
- Web server such as HTTP server
- IBM WebSphere application server
2. Starting the IBM WebSphere administrative console on the server
The way you access the administrative console is the same whether you have a standalone server environment or a distributed server environment. Instructions below are for a standalone server environment.
- To access the administrative console, make sure that application server, server1, is running by using this command:
Windows: <profile_home>\bin\serverStatus -all
UNIX: <profile_home>/bin/serverStatus.sh –all
- If the status of server1 is not STARTED, start it with the following command:
On Windows: <profile_home>\bin\startServer server1 (or from Program Group)
On UNIX: <profile_home>/bin/startServer.sh server1
Note: <profile_home> default on Windows would be C:\Program files\IBM\WebSphere\AppServer1\
Note: <hostname> is your host name or IP address for the machine running the application server.
The administrative console loads and you are asked to log in. Once the server is started and you are signed in you can proceed with the installation of PASSPORT WEB TO HOST.
3. Installing PASSPORT WEB TO HOST®
Note: If you’re upgrading to a newer version, it is very important to follow these instructions to preserve your PASSPORT configuration files.
- From the menu on the left select Applications ->Enterprise Applications ->Install or Applications ->Install New Application.
- Specify the location of the “passweb.ear” file to install.
Note: the EAR file can either be on the web application server (Remote file system) or on any accessible location by the administrative console (Local file system). The screen shot below is using Local file system path to access the EAR file from a shared drive P:\ on the network.
Enlarge Image
- Click Next
- The 1st step of the installation allows you to set the installation options. These settings like application name, file permission, etc., primarily determine whether default settings will be used (as in our sample) or if you will override them during the installation. On this screen you can change the application name from the default “passweb” to anything you like. In our example, we used “PASSPORT”.
Enlarge Image
- Click Next
- Step 2 & 3 allows you to map modules to application servers and web servers. We used the defaults for our installation. Click Next to continue.
Note: The Context Root name is the name being used in the URL to launch PASSPORT WEB TO HOST.
Enlarge Image
- Step 4 displays a summary of the installation options selected. See below.
Enlarge Image
- Click Finish to install the application. The screen below appears during the installation. Watch out for any error messages.
Enlarge Image
- Review the installation messages and click Save to save the configuration.
4. Starting PASSPORT WEB TO HOST ® on IBM WebSphere
- Once the application is installed we need to start it. Go back to Applications ->Enterprise Applications and select the “PASSPORT” and click the Start button. See below.
Enlarge Image
- If all works then the following screen is displayed. Else an error message is displayed and this will need to be resolved before using PASSPORT WEB TO HOST.
Enlarge Image
5. Starting the PASSPORT WEB TO HOST® administrator web site and configuration program
Note: <servername> is the name or IP address of the installed location of IBM WAS. This URL is case sensitive (use a capital I for Index)
This starts the PASSPORT WEB TO HOST administrator page. There are four sections: Configure, Deploy, Support, and Documentation. Each section provides pertinent information to help you quickly complete the installation and configuration.
- Click on the Configure link from the administrator web site. This link opens up another Internet Explorer window with the administration configuration program running inside it.
Note: The first time you click on this icon an ActiveX component will be downloaded and expanded. The following message appears: Security Warning - Do you want to install and run PASSPORT WEB TO HOST signed and distributed by Zephyr Corporation. This is the PASSPORT digital signature obtained from VeriSign Commercial Software Publishers. The purpose of the digital signature is to ensure the software is valid and has not been tampered with or corrupted during the download process.
Note: If you are running Windows XP SP2, you might also be alerted by the Information Bar to allow the downloading and installing of the ActiveX control before making a successful connection. The message appears as: The previous site might require the following ActiveX control: 'PASSPORT WEB TO HOST for Internet Explorer' from Zephyr Development Corporation'. Click here to install...
- The first time you start the administrator configuration program you will be warned with an ‘Invalid license code’ message, you will need to click on the Purchase button to enter your evaluation or purchase license code. You will then be prompted to fill in the system administrator information and you have the option to set a password. This is an important security measure as it ensures that only authorized administrator(s) can make changes to the PASSPORT environment.
6. Create a session profile
In the left pane, do the following:
- Expand 3270 Display by clicking the "+" symbol to the left.
- Highlight Sessions.
- Click the right mouse button to bring up the pop-up floating menu.
- Select New.
- The Add New Session Profile dialog box appears.
- Enter a name for the new session profile and press the OK button.
- The Session Profile property sheet appears.
- Enter a description for the new session profile, if desired.
- Enter the Host Name or IP Address.
- Enter any other necessary connection information.
Note: If you're required to establish a secure socket layer connection to your host then check the option Enable Secure Connection on this screen. In order for the SSL connection to take place, both the client and the server must have SSL configured. Check with your host administrator for more information. If you're having a connection problem with an SSL session on Windows Vista, please review the Troubleshooting Tips section for more information.
- Click OK.
The name of the session profile that you have just created appears in the right pane.
7. Create a User (optional)
In the left pane, do the following:
- Highlight Users.
- Click the right mouse button to bring up the pop-up floating menu.
- Select New.
- The New User dialog box appears.
- Enter a user name (UserID) and description.
- Click on the 3270 Display tab.
- Highlight the session name that was created previously.
- Click the Add button to add the session to the list of assigned display sessions.
- Click OK.
8. Test the session profile from the server
In the right pane, do the following:
- Highlight the name of the session profile you just created.
- Click the right mouse button to bring up the pop-up floating menu.
- Select Connect.
- A new Internet Explorer window is opened and the selected session profile will be launched.
If PASSPORT WEB TO HOST fails to load or if the mainframe screen does not appear, follow the troubleshooting tips details below.
9. Launch the session profile from a client PC
Before launching a PASSPORT WEB TO HOST session profile, the client PC must meet the following system requirements. If these requirements are not met, you may have unpredictable results.
- Windows Vista, XP, or Windows 2000 (with the latest service pack applied)
- Internet Explorer version 6.0 or higher
- TCP/IP connection to the web server
- TCP/IP connection to the host
To launch a PASSPORT WEB TO HOST session:
- To start the desired session profile access the following (default) URL: http://<servername>:9080/passweb/Eclient/Index.htm
Note: <servername> is the name or IP address of the installed location of IBM WAS. This URL is case sensitive (use a capital I for Index)
- PASSPORT launch page is displayed and you are prompted for a user name or session name. Enter the user name or session name created previously and click the Submit button.
- If you’ve entered a user name, a browser window appears containing the list of available sessions for this user.
- Click on the session name you want to start.
Note: The first time you run a PASSPORT WEB TO HOST session from a client PC, the ActiveX components are downloaded to the client PC and expanded. The following message appears: Security Warning - Do you want to install and run PASSPORT WEB TO HOST signed and distributed by Zephyr Corporation. This is the PASSPORT digital signature obtained from VeriSign Commercial Software Publishers. The purpose of the digital signature is to ensure the software is valid and has not been tampered with or corrupted during the download process.
Note: If you are running Windows XP SP2, you might also be alerted by the Information Bar to allow the downloading and installing of the ActiveX control before making a successful connection. The message appears as: The previous site might require the following ActiveX control: 'PASSPORT WEB TO HOST for Internet Explorer' from Zephyr Development Corporation'. Click here to install...
- Press the YES button to continue.
- If PASSPORT WEB TO HOST fails to load or if the host screen does not appear, follow the troubleshooting tips details below.
You are now ready to use PASSPORT WEB TO HOST
10. Troubleshooting Tips
Remember: If you need to talk to Zephyr Technical Support about your connection problem, you will have to completely fill out the support request form from our web site and obtain your INCIDENT ID number.
- If you cannot launch a session, or if the text data of the Ecomes.zwh file is displayed in your browser window, you will need to follow the troubleshooting instructions displayed in the browser. If this occurs, it is generally caused by the security setting on the browser or a firewall that is preventing the downloading or execution of ActiveX components.
- If you are able to launch a session ( Tip: If PASSPORT WEB TO HOST has been successfully loaded and is running, the PASSPORT menus are merged with the IE menus and the PASSPORT toolbar and button bars appear) but do not get a host connection, you should get an error message generated by PASSPORT. When receiving the error, you can find solutions in the following places:
- Sometimes, the host may not handle error processing correctly or may not handle it at all. In these instances, you may not get an error message. To resolve your connection issue, you will have to:
- Click the Communication->Connection Log menu command to view the connection log. The connection log displays the Telnet negotiation commands sent between PASSPORT and the host system. This can be used to determine why the connection failed.
- Search our knowledgebase under the Support section on our web site. Many of the common connection problems are reported here.
Search our documentation for common connection problems.
- If you still cannot get a connection, the last alternative is to run a Low Level Trace and email it to Zephyr Technical Support for analysis. To expedite your request, you will need to completely fill out a support request form on our web site under the Support section.
Note: see Running a Trace in our documentation for instructions on how to do this.
- If you’re upgrading to a newer version of PASSPORT WEB TO HOST, it is very important to back up all of your PASSPORT configuration files BEFORE the upgrade as they will be overwritten during installation. The following folders, subfolders and files below will need to be back up and copy back to the same location after the upgrade is performed:
Eclient\Groups
Eclient\Users
Eclient\3270dsp
Eclient\3270prt
Eclient\5250dsp
Eclient\5250prt
Eclient\Vtdsp
Eclient\Wysedsp
Note: Keep in mind that if you are not utilizing any of the above components of WEB TO HOST then it is not necessary to copy that particular folder. For example, if you only configured 3270 sessions on the original server, then the 5250dsp, Vtdsp and Wysedsp folders would not be required. Also, if you are not utilizing the Users and/or Groups feature of WEB TO HOST, then you don’t have to copy those folders.
If you cannot get a PASSPORT SSL session to connect from a Windows Vista PC, it is possible that your host is only configured to use the DES cipher suite for secure connection. By default, Windows Vista disables this feature for security purposes. You will need to either re-configure SSL on your host to use a different cipher suite, or follow the steps below to enable the DES cipher suite on your Windows Vista PC to allow PASSPORT to work:
- Go to Start Menu, and type gpedit.msc in the Start Search and press <ENTER>. There might be an UAC elevation prompt. Just allow the action and proceed with the next step.
- Under Computer Configuration in Group Policy Object Editor, expand Administrative Templates, expand Network, expand SSL Configuration Settings, and then double-click SSL Cipher Suite Order.
- Select Enable and append TLS_RSA_WITH_DES_CBC_SHA,SSL_RSA_WITH_DES_CBC_SHA, at the beginning of the pre-populated string value. (Beware of the ending comma and there should not be any embedded space inside the string).
- Click OK and restart your computer. (Note: gpupdate command will update the Group Policy settings but reconfiguration of SChannel.dll requires restart.)
|
|
PASSPORT PC TO HOST®
