Skip to main content

Software  >  Networking  >  Communications Server  >  

MustGather: Collect Troubleshooting Data / Read First / Fix List for TELNET and TN3270E SSL for the z/OS Communications Server
 Technote (troubleshooting)
 
Problem(Abstract)
This document describes common problems, diagnostic tips (troubleshooting) and recommended maintenance for Telnet on the z/OS operating system.

This document replaces information APARs II3135 and II13369.
 
Resolving the problem
Table of Contents

Common Telnet Problems, Express Logon Feature and SSL failures

Telnet Restrictions and Recommended Settings

Telnet Recommended Maintenance (including SNAEXT maintenance)

Additional Recommended (non-IP) Maintenance

Gathering Diagnostic Output

Common Links:


Common Telnet Problems



Problem:
EZZ6012I TELNET BPX1AIO ACCEPT FAILED, RC = 00000000 RSN = 11020223
Solution:
See OMVS APAR OW42128

Problem:
EZZ6012I TELNET BPX1AIO ACCEPT FAILED, RC=7F RSN=7662024D

Solution:
MAXSOCKETS was reached in SYS1.PARMLIB(BPXPRMxx)


Back to Top

Express Logon Feature


Problem:
ICH408I message logging onto selected application.

Solution:
This is usually the result of an invalid application name defined in RACF PTKTDATA Profile.

Refer to the z/OS Communications Server IP Configuration Guide and the z/OS Security Server RACF Security Administrator's Guide for more information on the Express Logon Feature.

Additional information:

The PassTicket is validated by RACF when the application sends the RACROUTE command to RACF. RACF compares the application name passed in the RACROUTE command to the application
name defined in PTKTDATA Profile.

There are several ways to determine the application name:
    1. To determine application ID for APPC, CICS, IMS,TSO, VM, and MVS Batch, refer to the z/OS Security Server RACF Security Administrator's Guide, section Defining Profiles PTKTDATA class.
    2. Some applications do not pass any application name to RACF on the RACROUTE command. For these applications, RACF uses the default definition defined for MVS Batch Jobs.
    3. Some other applications (mostly OEMs) pass the VTAM-defined application name. For these applications refer to the product's reference manual to determine how RACF is called or obtain the application name from RACF msg ICH408I for a logon attempt.
.
Once the correct application name has been defined to RACF PTKTDATA Profile, the application ID defined must be coded in the application ID popup window of the client.



Back to Top

SSL Initialization and Handshake Failures

Problem:
Telnet SSL Handshake Fails, FFFFFFFE (-2), GSK_ERROR_NO_CERTIFICATE, after IPLing system. RACF databases are used to store the certificate.

Solution:
  1. Ensure that the server certificate is marked as the default certificate.
  2. Re-create certificate and key ring in RACF database



Problem:
EZZ6035I TELNET DEBUG CLIENT IPADDR..PORT xx.xx.xx.xx..xxx
CONN: 00009AF1 LU: MOD: EZBTTSMT
RCODE: 6002-00 SSL/TLS handshake failed.
PARM1: 000001F7 PARM2: PARM3: GSK_SECURE_SOCKET_INIT ,
(PARM1,1F7 = (503),Socket read request would block)

Solution:
  • If this is a HOD client that does not accept negotiated SSL, then change the Telnet-negotiated setting from YES to NO.
  • If this is a PCOMM client, ensure that the password for the key database file (.kdb) has not expired. Use the certificate management utility (v5.7) to check. Programs->IBM Personal Communications->Utilites-> Certificate Management and then open under the key database file pulldown. If the password has expired, the client will terminate the connection during the handshake.



Problem:
EZZ6035I TELNET DEBUG PROFILE WARNING,LINE: 0 MOD:
RCODE: 600F-00 SSL task setup failed.
PARM1: 00000004 PARM2: PARM3:
(PARM1 04 = means, GSK_KEYFILE_BAD_PASSWORD)
EZZ6035I TELNET DEBUG PROFILE ERROR,LINE: 127 MOD: EZBTDPR
RCODE: 6004-00 SSL initialization failed.

Solution:
  1. Verify that the password is correct
  2. Verify that the stash file is in the same directory as the key ring file.




Problem:
EZZ6035I TELNET DEBUG CLIENT IPADDR..PORT 10.40.2.11..1690
CONN: 00000017 LU: MOD: EZBTTSMT
RCODE: 6002-00 SSL/TLS handshake failed.
PARM1: 00000006 PARM2: PARM3: GSK_SECURE_SOCKET_INIT
(PARM1,06 = GSK_KEY_LABEL_NOT_FOUND)

Solution:
List the certificates in the key ring database and check to ensure they are defined correctly on both the server and client.




Problem:
EZZ0677I THE CLIENT CONFIG SOCKET 3 TIMED OUT, after customizing TN3270 SECURE port.
NOTE:
This could also inhibit the stack from coming down cleanly; a force may be required.

Solution:
Check the following:
  1. Check system log for 0C4 abend prior to EZZ0677I message. Proceed to steps 2-4.
  2. Make sure that hlq.SGSKLOAD and CBC.SCSBDLL are APF authorized. Issue MVS display prog command to confirm.
  3. Make sure the STEPLIB DD in the TCPIP started proc has library hlq.SGSKLOAD.
  4. If RACF is used to manage certficates, make sure that hlq.SGSKLOAD is program controlled.
Refer to the z/OS Security Server RACF Command Language Reference guide for more information
on program control.



Problem:
EZZ6035I TELNET DEBUG PROFILE WARNING,LINE:
RCODE: 600F-00 System SSL initiation failed.
PARM1: 0000006A PARM2: PARM3: GSK_ENVIRONMENT_INIT
(PARM1,6A = (106),

The System SSL runtime is unable to decrypt a key database.
Either the supplied database password is incorrect or the database is damaged.

Solution:
  1. Ensure that the correct key database password is used.
  2. Re-create the database if the error persists.




Problem:
EZZ6035I TELNET DEBUG 207.133.71.245..53663 768
CONN: 00000CF7 LU: MOD: EZBTTSMT
RCODE: 6002-00 SSL handshake failed.
PARM1: FFFFFFF1 PARM2: 00000000 PARM3: 00000000
(PARM1, FFFFFFF1= (-15) means GSK_ERROR_BAD_CERT)

Solution:
Ensure that the server certificate in the key ring database specified in TELNETPARMS section of Profile matches the server certificate stored in the client's key ring database.




Problem:
EZZ6035I TELNET DEBUG 10.77.57.6..1071 493
CONN: 0001E295 LU: MOD: EZBTTSMT
RCODE: 6002-00 SSL handshake failed.
PARM1: FFFFFF9D PARM2: 00000000 PARM3: 00000000
(PARM1 FFFFFF9D,(-99) means GSK_ERROR_UNKNOWN_ERROR

Solution:
  1. Ensure that the key ring is defined in RACF database
  2. Ensure that the CASE is correct for the name of the key ring
  3. Ensure that the userid for the TCPIP started task and the owner of the key ring are the same.
Note: If using hardware encryption:
      • CSFSERV facility class must be active and the userid for TCPIP started task must have read access to CSFSERV resource.
      • Ensure that APARS OW52700 and OW50359 are installed.




Problem:
EZZ6034I TELNET CONN 0001CC01 LU **N/A** CONN DROP ERR 6002
IPADDR..PORT 10.66.16.46..1047 EZBTTSMT
Received after adding the renewed CA certificate to the RACF key ring database.

Solution:
  1. Add the certificate using the same userid as the one used for the original certificate.
  2. Try using the RACDCERT REMOVE command to delete the expired certificate from the key ring. This will ensure the server is getting the correct certificate.




Problem:
EZZ6035I TELNET DEBUG DETAIL CLIENT 598
IP..PORT: xxx.xx.xx.xx..xxxx
CONN: 00001179 LU: MOD: EZBTTSMT
RCODE: 6002-00 SSL/TLS handshake failed.
PARM1: 000001B5 PARM2:00000000 PARM3:GSK_SECURE_SOCKET_INIT
where x1B5 = 437 decimal = GSK_ERR_CONNECTION_CLOSED

Solution:
This return code may be received if the name in the server's certificate does not match the exact
name representing the IP Address on System z. The system programmer can request that a DNS alias be created with an alias that matches the name on the certificate and retry to establish the secure session.


Back to Top


System SSL Return Codes

For a detailed description of return codes see: z/OS V1R10.0 System SSL Programming Guide

The following may be returned by gsk_secure_soc_init
GSK_ERROR_NO_CIPHERS -1 = FFFFFFFF
GSK_ERROR_NO_CERTIFICATE -2 = FFFFFFFE
GSK_ERROR_BAD_CERTIFICATE -4 = FFFFFFFC
GSK_ERROR_UNSUPPORTED_CERTIFICATE_TYPE -6 = FFFFFFFA
GSK_ERROR_IO -10 = FFFFFFF6
GSK_ERROR_BAD_MESSAGE -11 = FFFFFFF5
GSK_ERROR_BAD_MAC -12 = FFFFFFF4
GSK_ERROR_UNSUPPORTED -13 = FFFFFFF3
GSK_ERROR_BAD_CERT_SIG -14 = FFFFFFF2
GSK_ERROR_BAD_CERT -15 = FFFFFFF1
GSK_ERROR_BAD_PEER -16 = FFFFFFF0
GSK_ERROR_PERMISSION_DENIED -17 = FFFFFFEF
GSK_ERROR_SELF_SIGNED -18 = FFFFFFEE
GSK_ERROR_BAD_MALLOC -20 = FFFFFFEC
GSK_ERROR_BAD_STATE -21 = FFFFFFEB
GSK_ERROR_SOCKET_CLOSED -22 = FFFFFFEA
GSK_ERROR_GSK_INITIALIZATION_FAILED -23 = FFFFFFE9
GSK_ERROR_HANDLE_CREATION_FAILED -24 = FFFFFFE8
GSK_ERROR_BAD_DATE -25 = FFFFFFE7
GSK_ERROR_BAD_KEY_LEN_FOR_EXPORT -26 = FFFFFFE6
GSK_ERROR_NO_PRIVATE_KEY -27 = FFFFFFE5
GSK_BAD_PARAMETER -28 = FFFFFFE4
GSK_ERROR_INTERNAL -29 = FFFFFFE3
GSK_ERROR_WOULD_BLOCK -30 = FFFFFFE2
GSK_ERROR_LOAD_GSKLIB -31 = FFFFFFE1
GSK_ERROR_API_NOT_AVAILABLE -32 = FFFFFFE0
GSK_ERROR_BAD_KEYPAIR -33 = FFFFFFDF
GSK_ERROR_BAD_CRL -34 = FFFFFFDE
GSK_ERROR_VALIDATION -35 = FFFFFFDD
GSK_ERROR_CRYPTO -36 = FFFFFFDC
GSK_ERROR_ASN -37 = FFFFFFDB
GSK_ERROR_LDAP -38 = FFFFFFDA
GSK_SOC_BAD_V2_CIPHER -40 = FFFFFFD8
GSK_SOC_BAD_V3_CIPHER -41 = FFFFFFD7
GSK_SOC_BAD_SEC_TYPE -42 = FFFFFFD6
GSK_SOC_NO_READ_FUNCTION -43 = FFFFFFD5
GSK_SOC_NO_WRITE_FUNCTION -44 = FFFFFFD4
GSK_SOC_BAD_SEC_TYPE_COMBINATION -45 = FFFFFFD3
GSK_ERROR_UNKNOWN_ERROR -99 = FFFFFF9D


The following may be returned by gsk_secure_soc_read:
GSK_ERROR_BAD_BUFFER_SIZE -100 = FFFFFF9C
GSK_ERROR_BAD_SSL_HANDLE -101 = FFFFFF9B
GSK_ERROR_TIMEOUT -102 = FFFFFF9A
GSK_ERROR_BAD_BUFFER -103 = FFFFFF99

The following may be returned by gsk_secure_soc_reset
GSK_ERROR_NOT_SERVER -50 = FFFFFFCE
GSK_ERROR_NOT_SSLV3 -51 = FFFFFFCD
GSK_ERROR_NOT_SSLV3_CLIENT -52 = FFFFFFCC
GSK_SECURE_SOC_RESET_OK 0

The following may be returned by gsk_uninitialize
GSK_CLOSE_OK 0
GSK_ERROR_CLOSE_FAILED -1


Back to Top

TELNET Restrictions and Recommended Settings


  • Restriction when defining the USSTCP statement
      USSTCP is a reserved statement, which is not to be used as an actual USS table name.
      If used, profile parsing errors can occur when TCPIP is initializing.
  • Recommended parameter settings for TIMEMARK and SCANINTERVAL
      TIMEMARK 10800
      SCANINTERVAL 1800








    Back to Top

    TELNET Recommended Maintenance


    TCP/IP z/OS 1.4 R140
    UQ74694, UQ86798, UQ86801, UQ87416, UK05441, UK05752
    UK05808, UK06272, UK06522, UK07406, UK08515, UK08677
    UK10652, UK12132, UK12219, UK13700, UK14946, UK15952
    UK19160



    TCP/IP z/OS 1.5 R150
    UQ86799, UQ87417, UQ90904, UQ91833, UQ95752, UK00763,
    UK05809, UK06267, UK07407, UK08516, UK08678, UK10653,
    UK12220, UK13701, UK14947, UK15953, UK09149, UK19161



    TCP/IP z/OS 1.6 R160
    UQ90905, UK00764, UK01710, UK04612, UK05810, UK06015,
    UK06268, UK07408, UK08517, UK08679, UK09370, UK10654
    UK12221, UK13702, UK14948, UK15954, UK16260, UK09150
    UK19162, UK19833, UK21577, UK25193, UK26062
    NOTE: For problems with TELNET running in it's own ASID,
    search on R160 TSASO


    TCP/IP z/OS 1.7 R170
    UK05811, UK06146, UK06269, UK07409, UK08518, UK08680
    UK09371, UK10655, UK12222, UK13703, UK14949, UK15955
    UK16261, UK09151, UK19163, UK19834, UK21578, UK25193
    UK26063, UK25806, UK35064, UK37693

    NOTE: For problems with TELNET running in it's own ASID,
    search on R170 TSASO



    TCP/IP z/OS 1.8 R180
    UK15163, UK15227, UK16016, UK19642, UK16746, UK19164, UK19835
    UK21579, UK25194, UK26064, UK26931, UK32220, UK36476, UK35528
    UK35065, UK36476, UK33081, UK37694, UK38529, UK39235

    NOTE: For problems with TELNET running in it's own ASID,
    search on R180 TSASO



    TCP/IP z/OS 1.9 R190
    UK26932, UK32221, UK36477, UK35529, UK35066, UK36477, UK33082
    UK37695, UK38530, UK39236, UK43003



    TCP/IP z/OS 1.10 R1A0

    UK37692, UK38528, UK43002


    Back to Top




    Additional Recommended (non-IP) Maintenance
    (Non-Telnet fixes that cause Telnet Symptoms)

    OA11652 addresses a problem in OMVS that causes the TELNET server to appear hung.
    OA11841 addresses a problem in VTAM that causes connection failures in a cross domain
    environment
    OA15828 Telnet Session Hangs. This apar is VTAM R170 only. PTF UA25451
    OA16468 TCP/IP TN3270 ABEND S422 WHEN SECURE PORTS ARE DEACTIVATED AND
    REACTIVATED THRU VARY OBEYFILE CMD WITH SSL DOING CRL VALIDATION
    OA17750 TELNET HANGS DUE TO ASYNCIO ARQ FREECHAIN
    OA20897 R160 UA34674, R170 UA34675, R180 UA34676, R190 UA34677
    OA07194 R707 UA10329
    OA10029 R706 UA15714
    OA22488 UA37083 R190 only. Various OPEN/CLOSE ACB failures


    Back to Top

    Gathering Diagnostic Output for TELNET problems

    The most common form of diagnostic output is the CTRACE, option TELNET.

    CTRACEs can be written to TCPIP's data space (in which case a dump will be needed)
    or to a data set using an external writer.

    • CTRACE, option TELNET, written to TCPIP's data space:
      1. Set the BUFSIZE value in SYS1.PARMLIB member CTIEZBTN to
      BUFSIZE(32M) or higher if possible. 32M is the default.

      2. Stop and restart TELNET so the new BUFSIZE value gets picked up
      3. Start CTRACE
        TRACE CT,ON,COMP=SYSTCPIP,SUB=(telnet_jobname)
        R xx,OPTIONS=(TELNET),END
      4. Set up the dump of TCPIP and TCPIP dataspace.
        DUMP COMM=(dump failure title)
        R aa,JOBNAME=(telnet_jobname),CONT
        R bb,SDATA=(ALLNUC,CSA,LPA,LSQA,RGN,SWA,SQA,TRT),CONT

        *This will leave an outstanding WTOR that we will reply to take the dump.
      5. Re-create the problem
      6. Now reply to take the dump
        R xx,END
  • CTRACE, option TELNET, written to a data set using an external writer:
      External Writer:

      //CTTCP PROC
      //* REFER: SYS1.PROCLIB(CTTCP)
      //* COMPID: OPER
      //* DOC: THIS PROCEDURE IS THE IPCS CTRACE1 EXTERNAL
      //* WRITER PROC USED BY TCP/IP .
      //*
      //IEFPROC EXEC PGM=ITTTRCWR
      //TRCOUT01 DD DSNAME=MEGA.IPCS.CTRACE1,UNIT=SYSDA,
      // VOL=SER=STORGE,
      // SPACE=(4096,(100,10),,CONTIG),DISP=(NEW,CATLG)
      //

      1. Start the external writer using the following command:
        TRACE CT,WTRSTART=CTTCP,WRAP
      2. Turn on and connect the external writer for CTRACE
        TRACE CT,ON,COMP=SYSTCPIP,SUB=(telnet_jobname)
        R xx,OPTIONS=(IPADDR(aaa.bbb.ccc.ddd)),CONT
        R xx,OPTIONS=(TELNET),WTR=CTTCP,END
      3. Recreate the problem.
      Note and report the following information:
        * Time failure occurred
        * Client IP Address
        * Client LU name
      4. Turn off the CTRACE,disconnect and stop the external writer:
        TRACE CT,ON,COMP=SYSTCPIP,SUB=(telnet_jobname)
        R nn,WTR=DISCONNECT,END
        TRACE CT,OFF,COMP=SYSTCPIP,SUB=(telnet_jobname)
        TRACE CT,WTRSTOP=CTTCP,FLUSH

    Things to consider when running CTRACE (TELNET):
    1. When running the Telnet Server under the TCPIP stack, the jobname parameter will be for TCPIP.
    1. TCPIP captures ctraces in its data space. So, when capturing the traces in a dump add these parameters to the dump command:
        DSPNAME=('tcpip_procname'.TCPIPDS1)



    In some cases, the support team will ask for the following additional documentation:
    • IP PACKET TRACE
      - filter on the failing client's IP Address
    • VTAM VIT (API and PIU) and BUFFER traces
      - see SNA Diagnosis VOL1 for more information on these traces




    Back to Top



    To send the documentation in for Level 2 support to review, please visit :
    http://www.ibm.com/support/docview.wss?rs=852&uid=swg21298465


    z/OS Communications Server Hints and Tips:
    http://www.ibm.com/software/network/commserver/support/

    • Back to top
    •  
     
     

    Copyright and trademark information
    IBM, the IBM logo and ibm.com are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.
    Rate this page
    Please take a moment to complete this form to help us better serve you.
    This material provides me with the information I need.




    This material is clear and easy to understand.




    Did the information help you to achieve your goal?
    What updates, improvements, or related information would you like to see in this document?
    Your response will be used to improve our document content. Requests for assistance, if applicable, should be submitted through your normal support channel as we cannot respond from this site.
    Input the verification number to submit feedback:
    Document information
     Product categories:
     Software
     Networking
     Enterprise Connectivity
     z/OS Communications Server
     All
     Operating system(s):
      z/OS
     Software version:
      1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10
     Reference #:
      1318807
     IBM Group:
     Software Group
     Modified date:
     2009-09-02

    Translate My Page
     
     

    Rate this page

    Help us improve this page. Your response will be used to improve our document content. Requests for assistance, if applicable, should be submitted through your normal support channel as we cannot respond from this site.