z/tpf EE V1.1 z/tpfdf V1.1 TPF Toolkit for WebSphere Studio V3 TPF Operations Server V1.2 IBM Software Group TPF Users Group Fall 2006 z/tpf FTP Client Support Name: Jason Keenaghan Venue: Main Tent AIM Enterprise Platform Software IBM z/transaction Processing Facility Enterprise Edition 1.1.0 Any references to future plans are for planning purposes only. IBM reserves the right to change those plans at its discretion. Any reliance on such a disclosure is solely at your own risk. IBM makes no commitment to provide additional information in the future.
z/tpf FTP Client Overview z/tpf previously provided support only for a file transfer protocol (FTP) server Transferring files to or from the z/tpf file system had to be initiated at the remote system (eg, UNIX, Linux, Windows, z/os, etc.) z/tpf s FTP server does not support secure FTP (FTPS) There is an increased usage of the file system on z/tpf Configuration files generated offline must be transferred to z/tpf Trace files, dump files, and data files generated by z/tpf must be transferred offline FTP client support is now available on z/tpf Applications and operators can initiate file transfers directly from z/tpf to remote systems Optionally transfer files securely using FTPS Addresses TPFUG Requirement: DS04001 PUT File System z/tpf GET FTP Server 2
FTP Client Application Interface Applications can use z/tpf-specific application programming interfaces (APIs) to initiate file transfers in one of two ways: Persistent connections tpf_ftpconnect Connects to the specified FTP server and returns a session ID tpf_ftpsetopts Set file transfer options for a given session: binary vs. text passive vs. non-passive automatically create missing directories append to or replace existing files transfer timeout tpf_ftpgetopts Gets the current file transfer options for a given session tpf_ftpput Puts a file to a remote FTP server tpf_ftpget Gets a file from a remote FTP server tpf_ftpdisconnect Disconnects from a remote FTP server Single transfer tpf_ftpput1 Put a single file to a remote FTP server tpf_ftpget1 Get a single file from a remote FTP server FTP client sessions cannot be shared across processes 3
FTP Client Operator Interface ZFTPC command enables operators to initiate file transfers from z/tpf Interactive mode Establish a persistent FTP session to a remote server Optionally: alter transfer options, change local or remote working directory, list directory contents, or display current session status Put or get file to/from FTP server Repeat steps (2) and (3) as necessary End the FTP session Single command mode Specify the destination and necessary transfer options on a single command z/tpf will automatically start a session, perform the transfer, and then end the session Manage and monitor active FTP client sessions Display active sessions Abandon long-running file transfers Force disconnect of long-running or hung sessions 4
FTP Client Session Limiting For various reasons, you might decide to limit the number of active FTP client sessions on your z/tpf system Two mechanisms for FTP client session limiting MAXFTPC parameter on ZNKEY command and SNAKEY macro Prevents applications from creating new FTP client sessions when this threshold value is reached z/tpf operator can still create new FTP client sessions Allows operators to transfer files to and from the z/tpf file system regardless of the activity being generated by applications and other operators Network services database (NSD) connection limiting Prevents both applications and operators from creating new FTP client sessions when this threshold value is reached If this method is selected, it is recommended to reserve some number of sessions (n) that would be reserved for operator creation n = NSD Limit MAXFTPC 5
FTP Client Operator Profiles FTP client profiles allow operators to setup default transfer options for remote systems that are frequently accessed Simplifies the amount of information that must be specified to initiate a file transfer Profiles are shared across all processors and subsystems Profiles can be used in both interactive and single command modes Each user-named profile contains the default transfer options to be used when establishing the session IP address or hostname of the remote FTP server User authentication information (user ID, location of.netrc file, and account) Secure FTP vs. traditional FTP Binary vs. text Passive vs. non-passive mode Automatically create missing directories Append to or replace existing files Transfer timeout value 6
FTP Client Interactive Mode Example ZFTPC CONNECT MACHINE-linuxtpf.pok.ibm.com USER-keenagj NETRC-/.netrc FTPC0001I 13.27.25 TPFDEF - ATTEMPTING FTP CONNECTION FTPC0002I 13.27.25 TPFDEF - CONNECTED - SESSION ID 1 ZFTPC APPEND SESSIONID-1 FTPC0006I 13.29.52 SESSION ID 1 - APPEND COMPLETED SUCCESSFULLY ZFTPC PWD SESSIONID-1 FTPC0058I 13.34.22 SESSION ID 1 - PWD COMPLETED SUCCESSFULLY PWD - /home/keenagj END OF DISPLAY ZFTPC GET SESSIONID-1 REMOTE-maketpf.cfg LOCAL-/tmp/maketpf.cfg FTPC0005I 13.33.13 SESSION ID 1 - STARTING FILE TRANSFER FTPC0006I 13.33.13 SESSION ID 1 - GET COMPLETED SUCCESSFULLY ZFTPC DISCONNECT SESSIONID-1 FTPC0006I 13.42.17 SESSION ID 1 - DISCONNECT COMPLETED SUCCESSFULLY 7
FTP Client Interactive Mode with Profile Example ZFTPC DEFINE NAME-linux MACHINE-linuxtpf.pok.ibm.com USER-keenagj NETRC-/.netrc APPEND-Y FTPC0008I 13.54.58 linux DEFINED ZFTPC CONNECT NAME-linux FTPC0001I 13.55.29 linux - ATTEMPTING FTP CONNECTION FTPC0002I 13.55.29 linux - CONNECTED - SESSION ID 2 ZFTPC PWD SESSIONID-2 FTPC0058I 13.55.45 SESSION ID 2 - PWD COMPLETED SUCCESSFULLYSS PWD - /home/keenagj END OF DISPLAY ZFTPC GET SESSIONID-2 REMOTE-maketpf.cfg LOCAL-/tmp/maketpf.cfg FTPC0005I 13.56.10 SESSION ID 2 - STARTING FILE TRANSFER FTPC0006I 13.56.11 SESSION ID 2 - GET COMPLETED SUCCESSFULLY ZFTPC DISCONNECT SESSIONID-2 FTPC0006I 13.56.15 SESSION ID 2 - DISCONNECT COMPLETED SUCCESSFULLY 8
FTP Client Single Command Mode with Profile Example ZFTPC DEFINE NAME-linux MACHINE-linuxtpf.pok.ibm.com USER-keenagj NETRC-/.netrc APPEND-Y FTPC0008I 13.54.58 linux DEFINED ZFTPC GET NAME-linux REMOTE-/home/keenagj/maketpf.cfg LOCAL- /tmp/maketpf.cfg FTPC0001I 14.16.17 linux - ATTEMPTING FTP CONNECTION FTPC0002I 14.16.17 linux - CONNECTED - SESSION ID 3 FTPC0005I 14.16.17 SESSION ID 3 - STARTING FILE TRANSFER FTPC0006I 14.16.17 SESSION ID 3 - GET COMPLETED SUCCESSFULLY FTPC0003I 14.16.17 SESSION ID 3 - DISCONNECTED 9
libcurl Open Source URL Transfer Library z/tpf s FTP client support uses libcurl to handle the FTP protocol and the actual transfer of files from one system to another libcurl is an open source library that provides client APIs for transferring files Supports FTP and FTPS (using OpenSSL) Supports additional protocols as well (eg, HTTP, HTTPS, etc.) For additional information about libcurl, see http://curl.haxx.se/libcurl The libcurl library is not shipped with the z/tpf product If you wish to use the FTP client, you must download libcurl following the instructions from the z/tpf Downloads website If libcurl is not installed, then both the FTP client APIs and the ZFTPC command are disabled File System FTP Server Protocol Interpreter FTP Server Data Transfer Process Application Commands Data libcurl File System z/tpf APIs libcurl APIs FTP Client Protocol Interpreter FTP Client Data Transfer Process Open SSL ZFTPC Command 10
SSL Application Configuration Files In order to establish secure sockets using OpenSSL, z/tpf middleware packages must obtain user-specific configuration information: Version of Secure Sockets Layer (SSL) or Transport Layer Security (TLS) to use Location of certificate authority (CA) certificates Location of client certificates for peer authentication Location of SSL private keys Ciphers to use SSL application configuration files provide a standardized format for specifying this information Users create the configuration files offline and transfer them to z/tpf Configuration files must be placed in the appropriate subdirectory of /etc/ssl in the z/tpf file system, based on the application or middleware that will use them z/tpf middleware packages (like FTP client) make use of the new tpf_ssl_getconfig API to read in the desired configuration file Configuration information is returned to the middleware in a structured format Middleware can then pass the information on to the OpenSSL library 11
SSL Application Configuration Files Sample Format # This configuration file may be used with the FTP client. USESSL=try VERSION=TLSv1 CIPHER=RC4-MD5,RC4-SHA,DES-CBC-MD5,DES-CBC3-MD5 VERIFYPEER=1 CAINFO=/etc/ca/certauth.conf CERTIFICATE=/certs/512ccert.pem CERTTYPE=PEM KEY=/certs/512ckey.pem KEYTYPE=PEM 12
Secure FTP Using SSL Application Configuration Files Two types of SSL application configuration files are supported by the z/tpf FTP client Machine-specific configuration files /etc/ssl/ftpc/machine.conf Default configuration file /etc/ssl/ftpc/ftpc.conf Configuration files indicate whether or not a secure FTP session should be established, and if so, what options and parameters are to be used z/tpf FTP client APIs always consult the configuration files to determine if a secure or traditional FTP session should be established Application programmer does not need to decide, nor provide the necessary information Administrator can determine which machines should have secure FTP sessions and which do not need to be secure ZFTPC command has optional SSL=YES NO TRY parameter to optionally override setting in configuration file 13
FTP Client and z/tpf s File System Security File system security support (PJ30915) provides 2 types of security controls within the z/tpf system File protection Command protection File protection ensures that operators using the ZFILE commands can only manipulate files that he/she owns or files that belong to a group that he/she is a member of ZFTPC command acts as an extension of the ZFILE command Operators cannot transfer files from z/tpf that he/she does not have permission to read or that do not belong to a group that he/she is a member of Operators cannot transfer files to z/tpf into a directory that he/she does not have permission to update When an operator logs off the file system, all active FTP client sessions that were started by that operator will automatically be disconnected Command protection allows you to limit which operators have permission to issue the ZFTPC command For more information about file system security, see the presentation in the Database Subcommittee 14
FTP Client Available on z/tpf PUT 3 PJ31266 FTP client support for z/tpf PJ31296 Port of libcurl 7.15.4 for z/tpf Follow APEDIT instructions to download the supported version of the libcurl library NOTE: Before building the code associated with both APARs, you must update the CONFIG macro in SIP Stage 1 to include the LIBCURL=YES parameter and regenerate maketpf environment switches 15
Trademarks IBM, WebSphere, and z/os are trademarks of International Business Machines Corporation in the United States, other countries, or both. Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others. Notes Performance is in Internal Throughput Rate (ITR) ratio based on measurements and projections using standard IBM benchmarks in a controlled environment. The actual throughput that any user will experience will vary depending upon considerations such as the amount of multiprogramming in the user's job stream, the I/O configuration, the storage configuration, and the workload processed. Therefore, no assurance can be given that an individual user will achieve throughput improvements equivalent to the performance ratios stated here. All customer examples cited or described in this presentation are presented as illustrations of the manner in which some customers have used IBM products and the results they may have achieved. Actual environmental costs and performance characteristics will vary depending on individual customer configurations and conditions. This publication was produced in the United States. IBM may not offer the products, services or features discussed in this document in other countries, and the information may be subject to change without notice. Consult your local IBM business contact for information on the product or services available in your area. All statements regarding IBM's future direction and intent are subject to change or withdrawal without notice, and represent goals and objectives only. Information about non-ibm products is obtained from the manufacturers of those products or their published announcements. IBM has not tested those products and cannot confirm the performance, compatibility, or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. Prices subject to change without notice. Contact your IBM representative or Business Partner for the most current pricing in your geography. This presentation and the claims outlined in it were reviewed for compliance with US law. Adaptations of these claims for use in other geographies must be reviewed by the local country counsel for compliance with local laws. 16