Redirector troubleshooting checklist

1. Check the Z and I Emulator for Web infocenter for Redirector-related information.
2. Learn about basic Redirector configuration issues.
3. Understand the types of disconnections.
4. Check the configuration of the Redirector.
5. Check to see if the Redirector is active.
6. Check for messages.
7. Verify both sides of the Redirector connections.
8. Check the status of the Telnet ports.
9. Check your system configuration for Java.
10. Verify key databases.
11. Check to see if client authentication through the Z and I Emulator for Web Redirector fails
12. Gather trace information.

1. Check the Z and I Emulator for Web infocenter for Redirector-related information.

   Search for technotes related to the Redirector on the Z and I Emulator for Web page at https://zieweb.hcldoc.com/help/index.jsp> by taking the following steps:

   1. Enter Redirector in the search field.
   2. Click Go.
2. Learn about basic Redirector configuration issues.
   Refer to Redirector configuration tips.
3. Understand the types of disconnections.

   Disconnection errors can typically be classified as one of two types:

   • disconnection after a definite period of inactivity
   • random disconnection

   Disconnections that occur after a period of inactivity are normally caused by inactivity timers at the host connection or on some network device. You can debug connections that disconnect randomly by first determining which network device terminated the connection. Z and I Emulator for Web provides several traces to capture the disconnect event. See Gather trace information below.

4. Check the configuration of the Redirector.
   1. Verify that the inbound IP address and ports defined for the Redirector path are correctly defined as the destination in the client configuration.
   2. Verify that the outbound IP address and port defined for the Redirector path is the correct IP address and port of the Telnet server.
   3. Verify that any network devices will allow traffic on the port you have configured to use for the Redirector.
5. Check to see if the Redirector is active.
   1. With the Service Manager started, use the Administrator client to log on to Z and I Emulator for Web and check the status of the Redirector. If you can successfully log on, the Z and I Emulator for Web Service Manager is already active and you will not need to start it. The Redirector can only be active when the Service Manager is active.
   2. Check to see if the Redirector is listening on the defined port by using the netstat command for your operating system.
6. Check for messages.
   1. Check for System messages to determine what is causing your problem and what you should do to solve it. Note that most error messages related to the Redirector begin with RDR.
   2. Check for messages issued on the client, especially COMM messages in the emulator OIA.
   3. Check for messages on the Telnet server. Refer to your Telnet server documentation for more information regarding Telnet error messages.
7. Verify both sides of the Redirector connections.
   1. Test both segments of the Redirector connection using the ping command:
      1. On a Z and I Emulator for Web client workstation, ping the Redirector IP address and host name to verify that the workstation TCP/IP configuration is working. For example, if the Redirector workstation has an IP address of 255.123.123.3, type ping 255.123.123.3. If the workstation has a host name of redirectorws, type ping redirectorws.
      2. On the Redirector workstation, ping the Z and I Emulator for Web client IP address and host name to verify the server TCP/IP configuration is working.
      3. On the Redirector workstation, ping the TN3270 server machine by IP address and the host name to verify the server TCP/IP configuration is working.
      4. On the TN3270E server machine, ping the Z and I Emulator for Web Redirector by IP address and host name to verify that the TCP/IP connection is working from the server end.
      5. Make appropriate changes to the server, the client, or the Redirector based on the results you receive. All network connections must be accessible by host name and IP address.
   2. Test both segments of the Redirector connection using your operating system's native Telnet command. This is possible only on segments that are not using SSL.

      On the Redirector and client computers, use Telnet to see if the ports defined on the Telnet server or on other Redirectors configured in series are accessible through the firewall and network. This process can help isolate the source of the problem to the network between the Redirector and Telnet server or the network between the client and the Redirector. If your Telnet session from the Redirector to the Telnet server also fails to connect, or it also disconnects in a similar way that the Z and I Emulator for Web client disconnects, the problem may be a network or Telnet server problem that is unrelated to the Redirector. If this Telnet session from the Redirector server to the Telnet host stays connected even when the client workstation disconnects, this may indicate a problem between the Redirector server and client workstation. If the telnet sesssion only fails when it is configured to connect to the telnet server by passing through the Redirector, then the problem may be Redirector related.

      1. On the Redirector workstation, use telnet to check the connection. For example, on Windows, take the following steps:
         1. Click Start > Run on the Redirector workstation.
         2. Type telnet and click OK.
         3. Click Connect > Remote system on the Telnet window menu bar.
         4. Type the host name of the Telnet server and the port you want to connect to in the Host Name field and Port field on the Connect window.
         5. Accept the default TermType.
         6. Click Connect. If this fails to connect, you have discovered the source of your problem.
         7. Try using the telnet command, but this time use the Redirector IP address and Redirector port in the Telnet connection window. If you can not connect to your Telnet server by establishing a connection that passes through your Redirector, the Redirector may be malfunctioning. Be sure you are only attempting this test if the Redirector is configured in passthru mode and the host connection is non-SSL.
      2. Do a simlar test from the client workstation to the Redirector and to the server by repeating the steps above. If step #f above works but this step fails, this may indicate a network connectivity problem between the client machine and the Redirector.

      Consult your operating system documentation for instructions on how to run Telnet on other platforms.

      If you receive no messages, the port is open. If you receive Connect failed with 'Host name', then the port is not active. Remember to disconnect after you test each port by selecting Connect > Disconnect from the Telnet window menu.

8. Check the status of the Telnet ports (only if the connection fails in step #f of 'Verify both sides of the Redirector connections'.
   1. Type Netstat -a at a command prompt on the Redirector workstation to see if the ports are active.
   2. Type Netstat -a at a command prompt on the Telnet server to see if the ports are active.
   3. On the client workstation, if you are not able to connect to an SSL-enabled Telnet session, use Telnet to see if the ports defined on the Redirector are accessible through the firewall and network from the client workstation. Consult your firewall documentation for more information. For example, on Windows, take the following steps:
      1. Click Start > Run on the client workstation.
      2. Type telnet and click OK.
      3. Click Connect > Remote system on the Telnet window menu bar.
      4. Type the host name of the Redirector in the Host Name field on the Connect window.
      5. Type the Redirector port (as defined in the Z and I Emulator for Web Session properties on the client) in the Port field on the Connect window.
      6. Accept the default TermType.
      7. Click Connect.
   4. Try using the telnet command, but this time, use the Redirector IP address and Redirector port in the telnet connection windows. If you cannot connect to your Telnet server by establishing a connection that passes through the Redirector, the Redirector may be malfunctioning. Be sure you are only attempting this test if the Redirector is configured in passthrough mode and the host connection is non-SSL.
   5. The final test is to repeat the previous step, but this time from the actual client machine. If Steps C and D work but this step fails, this may indicate a network connectivity problem between the client machine and the Redirector.

   Consult your operating system documentation for instructions on how to run Telnet on other platforms.

   If you receive no messages, the port is open. If you receive Connect failed with 'Host name', then the port is not active. Remember to disconnect after you test each port by selecting Connect > Disconnect from the Telnet window menu.

9. Check your system configuration for Java.

   You may possibly bypass some potential Java problems that can occur when running the Redirector by passing some additional paramters to Java. For more information, refer to Java Registry parameters.

10. Verify key databases.

    If you are using SSL on the Redirector under Windows or AIX with a self-signed certificate, verify that the Z and I Emulator for Web server key database and the CustomizedCAs.class have been created. Note that with a public authority, you do not need to create the the CustomizedCAs.class files. On AIX, be sure that the certificate files have the correct access authority of 755.

    1. To create the Z and I Emulator for Web server key database file, take the following steps:
       1. If any existing CustomizedCAs.class files exist, back them up to a different directory or delete them.
       2. Use any open source Key and Certificate Management utility to create a new CMS java keystore file, for example, ServerKeyStore.jks. Enter the password zieweb for the keystore file. Make sure that you select to store the password to a file. If you set an expiration date for the password, be sure to take note of when the password will expire since Z and I Emulator for Web will stop functioning when the password expires.

          You can verify the Z and I Emulator for Web server key database file and customizedCAs.* file by simply opening them and verifying that the passwords work. If they work, the certificates have not expired.

       3. Extract Certificate as a Base64 .arm file or binary .br file to /zieforweb/bin.
       4. Save the file to ServerKeyStore.jks in the \zieforweb\bin directory.
    Add the .arm certificate file. Label the certificate appropriately.
    2. Restart the Z and I Emulator for Web Service Manager.
    3. Modify or create a Redirector service with client-side security.
    4. Modify or create a session to connect to the above configured redirector with SSL enabled.
    5. Prior to connecting at the client, delete the temporary cache prior to starting the session and restart the browser.

Gather trace information.

Before you call HCL Support, you will want to gather important tracing information.

Enabling the Z and I Emulator for Web client and Redirector traces

Take the following steps to enable the Z and I Emulator for Web client and Redirector traces. The strategy is to start all the traces at the same time and then examine them after capturing the disconnect event.

1. To enable the Z and I Emulator for Web client trace, start a transport level-three trace using the trace facility provided by the Z and I Emulator for Web client with debug components. For more information, refer to Transport traces.
2. To begin enabling the Redirector trace, first stop the Z and I Emulator for Web Service Manager and erase the existing trace file.
3. Log on as the Z and I Emulator for Web Administrator.
4. Under Redirector Service, select Change Configuration. Select log Connections = Yes and enter a file name. If you do not specify a directory, the log file is created in \ZIEForWeb\lib\. Enter an IP address of the client you are using to recreate this problem.
5. Select Services and then Service Manager Trace. Enable the Trace and set it to level three.
6. Restart the Z and I Emulator for Web Redirector Service.
7. With only one client connecting to the Z and I Emulator for Web Redirector, try to recreate the problem.
8. Find the following four files and prepare to send them to HCL Support:
   • \privtae\NCoDServices.RAS
   • the log file that you specified above
   • Java Console log
   • trace.tlg
9. If you are capturing errors for a secure Redirector connection, enable tracing of the SSL portion of the Redirector code.

Enabling tracing of the SSL portion of the Redirector code

The Z and I Emulator for Web Redirector currently supports SSL only on Windows and AIX platforms.

To enable tracing of the SSL part of the Redirector code, follow these steps on the system where Redirector is running:

1. Stop the ServiceManager if it is currently started.
2. Set an environment variable:

   On Windows platforms, add the following system variable under Environment in the Windows Control Panel:

   Variable name= GSK_TRACE_FILE
   variable value= (filespec=where you want the trace to be located, for example, c:\gsktrace.trc)

   On the AIX platform, export the GSK_TRACE_FILE file.