Diagnosing failed z/OS FTP client connections to mft.bmc.com

Knowledge Article

Diagnosing failed z/OS FTP client connections to mft.bmc.com
This procedure describes how to collect FTP and GSK trace details for z/OS batch jobs which fail to connect to mft.bmc.com using PGM=FTP.
BMC AMI Enterprise Common Components
All BMC products.
BMC AMI Enterprise Common Components
All BMC products.
Why can't my z/OS FTP client connect to mft.bmc.com?

For details on using mft.bmc.com, please read:

For customer who wish to use SFTP to connect to mft.bmc.com, please read: z/OS FTP client connections to mft.bmc.com occur on port 990 with the following requirements:
  • First time users need to use a web browser to login to https://mft.bmc.com to initialize a customer folder before attempting a z/OS FTP client connection;
  • z/OS FTP client connections to mft.bmc.com require TLS authentication.
  • Install "DigiCert Global Root G2 certificate" in the keyring that will be used by the z/OS FTP client (see the KEYRING parm in the FTP.DATA settings of the SYSFTPD DD allocation);
  • If the z/OS FTP client connection goes through a SOCKS proxy server, the FTP.DATA settings need to include a SOCKSCONFIGFILE statement so that the settings in that file will be adopted for the connection;
  • Open ports 990 (control) and 30000-31000 (data) in the firewall and/or AT-TLS policy configurations;
  • Whitelist IP addresses for mft.bmc.com in the customer firewall:
    • 198.147.194.181 (primary)
    • 198.147.194.182 (secondary)
    • 198.175.230.239 (DR)
For an up-to-date list of IP addresses and port information for mft.bmc.com, visit the File server and certificate information page.

IBM references for diagnosing z/OS FTP client connections:

When DEBUG ALL is used in FTP.DATA (SYSFTPD DD) settings and SSL/TLS authentication fails due to an error, the job output should contain ftpAuth and/or authServer messages with return codes that can be found in the z/OS Cryptographic Services guide under: Secure Socket Layer (SSL) function return codes. For a complete list of codes and explanations, download the following IBM guide:

The IBM z/OS Communications Server: IP Diagnosis Guide has some useful diagnostic procedures: The following JCL can be used to gather a detailed FTP trace along with a GSK (Global Security Kit) trace. Both are helpful when diagnosing connection problems when TLS or ATTLS does not complete a successful certificate handshake:
 
//GSKTRACE JOB CLASS=P,MSGCLASS=X,NOTIFY=&SYSUID,REGION=0M            
//*------------------------------------------------------------------*
//*        This JCL is intended for customers who cannot complete    *
//*        a TLS-authenticated connection to mft.bmc.com.            *
//*                                                                  *
//*        The LIST command requires a protected data connection     *
//*        on passive port range: 30000-31000.                       *
//*                                                                  *
//*        The CEE environment variables below will:                 *
//*        1) force use of TLS v1.2 (best security);                 *
//*        2) capture a GSK trace for debug purposes.                *
//*                                                                  *
//*        Update SET FILE statement below for GSK TRACE file.       *
//*        Update SET USER/PSWD with your BMC credentials.           *
//*                                                                  *
//*        Use "DEBUG ALL" in SYSFTPD DD to test control connection. *
//*        Use "DEBUG SEC CMD SOC(3) FLO" to test data connection.   *
//*------------------------------------------------------------------*
//*        Connect to mft.bmc.com on port 990 using TLS v1.2         *
//*------------------------------------------------------------------*
//  EXPORT SYMLIST=(SERVER,USER,PSWD,FILE)                            
//   SET SERVER='mft.bmc.com'                              
//   SET   USER='BMC_Support_Central_USER'                       
//   SET   PSWD='BMC_Support_Central_PASSWORD'                        
//   SET   FILE='/tmp/mft.gsk.trc'                                    
//FTP      EXEC PGM=FTP,PARM='&SERVER 990 (TIMEOUT 720 EXIT=8'        
//SYSPRINT DD   SYSOUT=*                                              
//OUTPUT   DD   SYSOUT=*                                              
//CEEOPTS  DD   *,SYMBOLS=JCLONLY                                     
ENVAR("GSK_PROTOCOL_TLSV1_2=1",                                       
"GSK_TRACE=0xFFFF",                                                   
"GSK_TRACE_FILE=&FILE")                                               
/*                                                                   
//SYSFTPD  DD   *                                                     
DEBUG             ALL                                                 
KEYRING           *AUTH*/* ; or use userid/FTP.TLS.KEYRING.           
EPSV4             TRUE     ; CLIENT use EPRT/EPSV for IPv4 sessions.  
FWFRIENDLY        TRUE     ; FTP client is firewall-friendly.         
PASSIVEIGNOREADDR TRUE     ; FTP client ignores IP in PASV reply.     
SECURE_MECHANISM  TLS      ; or use TLSMECHANISM ATTLS.               
SECURE_HOSTNAME   OPTIONAL ; Authentication of hostname is OPTIONAL.  
SECUREIMPLICITZOS FALSE    ; Required as mft.bmc.com is a unix server.
/*                                                                    
//SYSIN    DD   *,SYMBOLS=JCLONLY                                     
&USER                                                                 
&PSWD                                                                 
LOCSTAT                                                               
LIST                                                                  
CLOSE                                                                 
QUIT                                                                  
/*                                                                    
//*------------------------------------------------------------------*
//*        Format GSK TRACE file to appear in STDOUT of job output.  *
//*------------------------------------------------------------------*
//FORMAT   EXEC PGM=BPXBATCH,REGION=0M,TIME=NOLIMIT,                  
// PARM='SH ls -l &FILE;echo;gsktrace &FILE'                          
//STDOUT   DD   SYSOUT=*                                              
//STDERR   DD   SYSOUT=*
BMC AMI Enterprise Common Components
All BMC products.
Attachment(s):