z/OS FTP TLS/SSL Client Instructions

Instructions for setting up z/OS FTP TLS/SSL client access to a remote FTP TLS or FTP SSL Server
The z/OS FTP TLS/SSL client can be used to provide secure file transports to and from remote FTP servers, including other z/OS systems, as long as they are running FTP TLS or FTP SSL. The file transports can be done from the MVS side of z/OS, unlike SFTP, so files do not need to be copied to/from UNIX datasets to MVS datasets, before/after the transfer. However, not all servers will support FTP TLS or FTP SSL, so you may have to transfer your files using the z/OS SFTP client. Your contact at the remote site should provide you with the type of server that they support. All references in these instructions to FTP, excluding any stating non-secure FTP, should be read as z/OS FTP TLS/SSL client. The steps for using FTP TLS/SSL as a client (batch job connecting to a remote FTP TLS or FTP SSL server) are 1. From your contact at the remote site get the Hostname/IP address of the remote server and the userid that you will use to logon to their server. Have your contact at the remote site email their server certificate to you. Your contact at the remote site should tell you whether their server supports SSL or TLS and tell you whether their server requires client authentication. 2. Send a request specifying your requirements to the Help Desk. Provide the following to the Help Desk: Description: SETUP REQUEST FOR FTP TLS/SSL CLIENT Hostname/IP address for the remote server: Your User ID on the remote server: Whether the remote server requires client authentication: The remote servers certificate as an attachment: Include any other information on the certificate or the remote server that you obtained from your contact at the remote site. 3. When your Help Desk ticket has been closed, you will receive an email with a client certificate to send to the remote site if they require client authentication. You can then set up the batch job for FTP TLS/SSL. Note If connection to the remote FTP server succeeds, but file transfers fail, there may be a firewall blocking the transfer. Contact z/OS Network Support if you have such issues.

FTP TLS/SSL Batch Jobs

There are two methods of doing batch FTP TLS/SSL jobs. One is to execute the FTP program provided by IBM, the other is to execute the ADM200 program provided by the Office of the CIO. The ADM200 program is a COBOL wrapper around FTP. It provides the following functions in addition to the file transfer: - Creates a "Wrapper" around FTP so that if the FTP connection is terminated, then ADM200 will try to reconnect and complete the File Transfer. - ADM200 creates batches of FTP Commands if the FTP "quit" command is found or "break-" is found. One batch will connect to the FTP Server, execute the FTP commands and disconnect. If more batches are left, the ADM200 will connect again, execute the FTP commands, and disconnect. If many files are being FTP'd or big files are being FTP'd, it is beneficial to break the FTP into batches so that a retry will not have to start all the way at the beginning of the FTP commands. If a retry is needed, the whole "Batch" is tried again, not just the command that failed. - ADM200 allows for an optional input file to customize your FTP job. Parameters can be specified in this file which will allow you to specify the number of retries that you want to take, specify sleep (or delay) times between retries, specify error codes on which to terminate the FTP process, specify analysts that should receive notification through Lotus Notes (through XMITIP), and specify comments to send to the console log. - ADM200 can interpret the FTP Return Code into an English error message, when FTPCODES and FTPREPLY are present. - ADM200 ignores the AUTOTAPEMOUNT TRUE parameter, so if your data is on tape (or virtual tape), you will need to add an IEBGENER step prior to the ADM200 step.

FTP Batch Job Example using PGM=ADM200 For those who have been using the ADM200 job for non-secure FTPs, there are some changes. 1. Remove the SYSTCPD DD card if present. 2. Add the SYSFTPD DD card. If already present, see description for SYSFTPD DD card. 3. If the remote server supports TLS, the PARM statement includes r TLS to indicate that this is a TLS transfer. If the remote server doesnt support TLS, but supports SSL, the PARM statement should not include r TLS, so that it will use the secure mechanism of SSL as specified in the FTPCDATA file.

//FTP1 EXEC PGM=ADM200, // REGION=8192K, // PARM='-r TLS ???.???.???.??? (EXIT' //* PARM='???.???.???.??? (EXIT' //SYSFTPD DD DSN=TCPIP.USER.SEZAPARM(FTPCDATA), // DISP=SHR //NETRC DD DSN=xxx7. NETRC, // DISP=SHR //FTPINPT DD DSN=ftpcmddsn, // DISP=(SHR,KEEP,KEEP) //INPUT DD DSN=&&INPUT, DISP=(NEW,DELETE,DELETE), // DCB=(BLKSIZE=27920,LRECL=80,RECFM=FB), // SPACE=(TRK,(5,1),RLSE) //OUTPUT DD DSN=&&OUTPUT,DISP=(NEW,DELETE,DELETE), // DCB=(BLKSIZE=27930,LRECL=133,RECFM=FB), // SPACE=(TRK,(5,1),RLSE) //SYSIN DD DSN=parmdsn,DISP=SHR //FTPCODES DD DSN=xxx7. FTPCODES, // DISP=SHR //FTPREPLY DD DSN=xxx7. FTPREPLY, // DISP=SHR //MSGTEXT DD DSN=&&MSGTEXT, // DISP=(NEW,PASS,DELETE), // DCB=(BLKSIZE=27920,LRECL=80,RECFM=FB), // SPACE=(TRK,(5,1),RLSE) //SYSPRINT DD SYSOUT=Q //SYSTSPRT DD SYSOUT=Q //SYSTSIN DD DUMMY //SYSOUT DD SYSOUT=Q //* //XMITMSG EXEC PGM=IKJEFT1B, // REGION=4M, // DYNAMNBR=50 //STEPLIB DD DSN=MVS7.XMITIP.LOAD, // DISP=SHR //SYSEXEC DD DSN=MVS7.XMITIP.EXEC, // DISP=SHR //SYSTSIN DD DSN=xxx7.XMIT.EMAIL, // DISP=SHR //SENDFILE DD DSN=&&MSGTEXT, // DISP=(OLD,DELETE,DELETE)

//SYSTCPD DD DSN=TCPIP.USER.SEZAPARM(IPDPR), // DISP=SHR //SYSTSPRT DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=*

PARM=-r TLS ???.???.???,??? (EXIT ???.???.???.??? is the IP address or the hostname of the FTP TLS/SSL server that you wish to connect to. If a hostname is used instead of an IP address, place a period immediately behind the hostname. This will eliminate unnecessary Domain Name Server searches. r TLS should only be used if the remote server supports TLS. (EXIT tells FTP to terminate if an error occurs. The step executing will get a non-zero return code. If you exclude the (EXIT, FTP will not stop on errors. REGION-2048K XMITMSG FTP Requirement, Region must be at least 2048k.

step sends the Lotus Notes message

DDNAME DDNAME DESCRIPTION =============================================================== ========================= SYSFTPD FTP Client Data File (Required by FTP TLS/SSL). The settings in the provided client data file, FTPCDATA, should meet the requirements of most FTP jobs. It is possible that you will need your own copy of this dataset, should you need to alter the configuration in a way that is not possible to change with a LOCSITE command. Should you need to create your own version of this file, request a copy of the file form z/OS network systems rogramming. If you are migrating from non-secure FTP to FTP TLS/SSL and have your own copy of the FTP client data file, you no longer need your own copy if your only change was to set AUTOTAPEMOUNT to TRUE, since that setting is specified in TCPIP.USER.SEZAPARM(FTPCDATA). Since ADM200 ignores the AUTOTAPEMOUNT TRUE statement, if you need this you will have to add an IEBGENER step prior to the ADM200 step. If you need your own copy of the FTP client data file, request a copy of the FTPCDATA member from z/OS network systems programming and put your changes into it.

NETRC Account specific data set for FTP logon to FTP servers, containing logon ID and password for specified IP address. If not used the logon ID and password are included in the data set referenced on the FTPINPT DD statement. Using the NETRC DD ensures that the password will not be displayed in the job output. The keyword parameters are MACHINE, LOGIN, and PASSWORD. These keyword parameters must be capitalized. The values for the keywords are case sensitive. Example: MACHINE 127.0.0.1 LOGIN userid1 PASSWORD pswrd1 MACHINE 255.255.255.255 LOGIN userid2 PASSWORD pswrd2 Each account should have their own NETRC data set because userids and passwords are placed in this data set. Therefore the data set prefix should be a RACF secured production name to keep it secure. The data set should be allocated with the following parameters: RECFM=FB,LRECL=80,BLKSIZE=27920 The IP Address from the PARM=???.???.???.??? is searched for in the NETRC data set. If found the userid and password will be used to logon to the FTP Server. If not found, and the FTP Server requires a userid and password, the Proc Step will terminate with return code of 0013 - Open Error. FTPINPT Required by ADM200 - Used to create FTP "INPUT" DD. These are the FTP Cards ("put"/"dir"/etc...). The Data from FTPINPT will be batched (batches are determined by a "quit" or "-break-" in the FTP Cards). The Batch of FTP commands will be written to "INPUT" DD and Program "FTP" is called. Ensure that sequence numbers are off in this member. Example: put 'MVS.HOST.FILE' remote.file.name get remote.file.name 'MVS.HOST.FILE' (replace get remote.file.name 'MVS.HOST.FILE' Need to modify the //SYSFTPD DD data set with catalog information if the data set is not already allocated. INPUT Required by FTP, Created from FTPINPT. The FTP program will process the FTP commands from "INPUT" DD.

OUTPUT Required by FTP, Sysout from the called FTP program. Read by ADM200 to capture the errors and warnings. After every call to program FTP, the OUTPUT DD will be interrogated to determine the results of the File Transfer. SYSIN for: Optional file, if present ADM200 will parse the 80 bytes looking

TERMINATE= - The FTP Return Code will be matched up with this list to determine if the error should terminate the FTP process. TERMINATE= cards should at least include: 27000 Mainframe File Not Found 99000 Mainframe FTP Command Unrecognized FTP will terminate with CONDITION CODE = 8 SLEEP= - The FTP return code will be matched with this list to determine if the error will cause ADM200 to sleep (or delay) for a period of time before trying the FTP again. "ANALYST=" - If present and MSGTEXT is present, ADM200 will create an XMIT card(s) and XMIT DSN to send as a Lotus Note to the specified analyst(s). Example: ANALYST=jam.doe@cio.ne.gov (sent to: jam.doe@cio.ne.gov) ANALYST=jdoe@aaa.bbb.ccc (sent to: jdoe@aaa.bbb.ccc) "XCOMMENT=" - Sends Comments to Console Log if present (Up to 5 comments, 50 char long). The comments included in the XCOMMENT= card will be written to the console log in "Red" letters (stay on console). This is useful for FTP errors that are not handled by the ADM200 job. A message to not call the analyst can be written to the console. "SLEEPTIME=" - Number of seconds for ADM200 to "sleep" when FTP Return Code = Sleep Sysin Card. Must be Numeric 3 characters between 001-999. DEFAULT VALUE IS 120 Seconds. "RETRY=" - Number of Retries that will be attempted if FTP Fails. Must be Numeric 2 characters between 01-99. DEFAULT VALUE IS 4 Retries. FTPCODES Optional file, if present the FTP Return Code will be converted to an English description of the error. Sample of contents of file found in USR.COMMON.JCL(FTPCODES).

FTPREPLY Optional file, if present the FTP Return Code will be converted to an English description of the error. Sample of contents of file found in USR.COMMON.JCL(FTPREPLY). MSGTEXT Optional file, if present will contain the Lotus Note to send to the Analyst(s) in ANALYST= sysin.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + CONDITION CODE=0000 - FTP Completed Successfully. + +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + CONDITION CODE=0004 - FTP Terminated because FTP was + + tried "Retry Max" times and it + +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + CONDITION CODE=0008 - FTP Terminated because FTP return + + code matched a TERMINATE= RC. + +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + CONDITION CODE=0013 ADM 200 terminated because NETRC DD was + + specified, but IP in link Parm was not found in + + NETRC data set + +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

FTP Batch Job Example using PGM=FTP For those who have been using PGM=FTP for non-secure FTPs, there are a some changes. 1. Remove the SYSTCPD DD card if present. 2. Add the SYSFTPD DD card. If already present, see description for SYSFTPD DD card.

3. If the remote server supports TLS, the PARM statement includes r TLS to indicate that this is a TLS transfer. If the remote server doesnt support TLS, but supports SSL, the PARM statement should not include r TLS, so that it will use the secure mechanism of SSL as specified in the FTPCDATA file.

//FTP2 EXEC PGM=FTP, // PARM='-r TLS ???.???.???.??? (EXIT', // REGION=2048K //* PARM='???.???.???.??? (EXIT', //* REGION=2048K //SYSFTPD DD DSN=TCPIP.USER.SEZAPARM(FTPCDATA), // DISP=SHR //NETRC DD DSN=zzz7.NETRC,DISP=SHR //INPUT DD DSN=ftpcmddsn,DISP=SHR //OUTPUT DD SYSOUT=Q //SYSPRINT DD SYSOUT=Q
PARM=???.???.???,??? (EXIT ???.???.???.??? is the IP address or the hostname of the FTP server that you wish to connect to. If a hostname is used instead of an IP address, place a period immediately behind the hostname. This will eliminate unnecessary Domain Name Server searches. r TLS should only be used if the remote server supports TLS. (EXIT tells FTP to terminate if an error occurs. The step executing will get a non-zero return code. If you exclude the (EXIT, FTP will not stop on errors. REGION-2048K FTP Requirement, Region must be at least 2048k.

DDNAME DDNAME DESCRIPTION ======== =============================================================== === SYSFTPD FTP Client Data File (Required by FTP TLS/SSL). The settings in the provided client data file, FTPCDATA, should meet the requirements of most FTP jobs. It is possible that you will need your own copy of this dataset, should you need to alter the configuration a way that is not possible to change with a LOCSITE command.

Should you need to create your own version of this file, request a copy of the file form z/OS network systems programming. If you are migrating from non-secure FTP to FTP TLS/SSL and have your own copy of the FTP client data file, you no longer need your own copy if your only change was to set AUTOTAPEMOUNT to TRUE, since that setting is specified in TCPIP.USER.SEZAPARM(FTPCDATA). If you need your own copy of the FTP client data file, request a copy of the FTPCDATA member from z/OS systems programming and put your changes into it. NETRC Account specific data set for FTP logon to FTP servers, containing logon ID and password for specified IP address. If not used the logon ID and password are included in the data set referenced on the INPUT statement. Using the NETRC DD ensures that the PASSWORD will not be displayed in the job output. INPUT Required by FTP. These are the FTP commands to execute. ("put"/"dir"/etc...) OUTPUT Required by FTP, Output for the FTP functions.

SYSPRINT Messages output