TCP/IP for VSE/ESA
TCP/IP for VSE was developed by Connectivity Systems International, Inc. (CSI) and is part of z/VSE as TCP/IP for VSE/ESA. The product can be licensed directly from CSI or from IBM as part of z/VSE.
For more information about configuring TCP/IP for VSE/ESA, setting up FTP, TN3270, and SSL, see Security on IBM z/VSE, SG24-7691, which is available at this website:
This chapter provides an overview of TCP/IP for VSE/ESA 1.5F and the latest information that is available for z/VSE 5.1. We also describe special networking options.
This chapter includes the following topics:
2.1 Overview
The CSI TCP/IP for VSE product was the first solution on the market for connecting a production z/VSE system to today’s Internet world. It provides a comprehensive and flexible set of interfaces and applications to participate fully in the global business arena. This includes many optional and third-party products that bring the full power and reliability of mainframe computing to the e-commerce world. For more information about CSI, see this website:
2.2 Standard features
TCP/IP for VSE runs on VSE/ESA 2.1 through to the latest z/VSE versions. It provides its own pseudo task manager within a single partition to support a virtually unlimited number of connections without the use of up standard VSE partitions and subtasks.
TCP/IP for VSE also includes the following features:
•Support for almost any hardware network connection.
•Extensive monitoring and tuning capabilities that can be extended to any level of granularity, including specific destination addresses.
•Customizable security features to protect network access and data encryption.
•Built-in connection management provides queuing and automatic detection and clean-up of dead connections.
•A complete set of servers, including File Transfer Protocol (FTP), LPD, HTTPd, and TELNETD for TN3270 access.
•Other support software, such as PDF creation.
2.3 Other optional features
TCP/IP for VSE provides the following optional features:
•General Print Services (GPS) enables CICS and IBM VTAM 3270 applications to print directly to TCP/IP based printers.
•SSL and Transport Layer Security (TLS) provides support for secure connections the use modern cryptography by using RSA with x509v3 certificates for authentication, triple-DES and AES for bulk data encryption, and SHA for secure hashes and digital signatures.
•SecureFTP provides user authentication, confidentiality, and data integrity by using digitally signed certificates, data encryption, and secure hash functions for VSE-based FTP servers and clients.
•SeeTCPIP is a system and network monitor that helps identify and correct system bottlenecks to improve system performance.
2.4 Applications that are provided with TCP/IP for VSE
TCP/IP for VSE provides the following applications:
•FTP
•Telnet TN3270 Server
•Email
•LPR client for printing
•Web server
•PDF conversion
•Automation daemon for automatically sending Power LST queue entries by using FTP, email, or LPR
•REXEC client for sending commands to a remote REXEC daemon
•Ping, Traceroute, Discover, and other tools to analyze the network from VSE
A structured file system is also provided that allows access to SAM (disk and tape), VSAM (ESDS and KSDS), Power (RDR PUN and LST queues), Librarian, VTOC, HFS, ICCF, Epic managed, and data spaces, from all these applications.
2.5 Application programming interfaces
You can create your own TCP/IP applications with the APIs that best suit your company’s programming expertise. When possible, use the following APIs that are provided by IBM:
•IBM EZASMI macro and the EZASOKET call interfaces can also be used seamlessly with TCP/IP for VSE
•IBM LE/VSE C Run-Time Socket API
•SOCKET MACRO interface for Assembler programs
In addition to these APIs, you can use the following CSI interfaces:
•Basic socket interface (BSD Sockets) for C, Cobol, Assembler, or any other language that supports standard call and save linkage.
•Enhanced Pre-Processor is a language-independent API that is similar to the IBM CICS EXEC interface.
•Socket interface for REXX programming.
•SSL/TLS callable interface with which you can create secure socket client and server applications on VSE.
•Cryptographic algorithms, such as RSA, DES, AES, or SHA-1 can be called by using the CryptoVSE API for usage in any VSE application.
•The Common Encryption Cipher Interface with which you can encrypt and securely store data on any disk or tape device that is attached to VSE.
2.6 Setting up and running TCP/IP for VSE
Setting up and running TCP/IP is a relatively simple process. A single partition must be dedicated with at least 20 megabytes of virtual storage. The JCL for starting a sample TCP/IP partition is shown in Example 2-1.
Example 2-1 JCL to start the TCP/IP stack
* $$ JOB JNM=TCPIP15F,DISP=K,CLASS=8
* $$ LST CLASS=F,DEST=(,AFTPTODS),DISP=D RBS=40
// JOB TCP15F00 TCP/IP STARTUP JOB FOR ZVSE51DS
// OPTION LOG,NOSYSDMP
// LIBDEF PHASE,SEARCH=(CSILIB.TCPT15F,CSILIB.TCPIP15F)
// LIBDEF SOURCE,SEARCH=(CSILIB.ZVSE51DS)
// SETPFIX LIMIT=(512K,2048K)
// EXEC IPNET,SIZE=IPNET,PARM='ID=00,INIT=TCP15F00',DSPACE=8M
/*
/&
This example should run in the F8 partition. The * $$ LST card allows SYSLST output to be automatically transferred by using FTP based on commands that are contained in a AFTPTODS.L library member.
TCP/IP stores all configuration files and command scripts in a library.sublibrary with the .L member type.
The // EXEC card contains the following parameters that control running the TCP/IP:
•PARM='ID=00'
This sets the stack identifier. Stack ID 00 is the default and should be used by most installations. Multiple stacks can be run by specifying an ID= 00 - 99. Therefore, the maximum number of stacks that can be run on a single VSE image is 100.
•INIT=TCP15F00
The INIT= tells IPNET to read the librarian member TCP15F00.L and run the commands that are contained in it (TCP15F00.L). A job similar to Example 2-2 can be used to create this librarian member.
Example 2-2 JCL to catalog a TCP/IP startup member
// JOB TCP15F00 CATALOG TCP/IP 1.5F STARTUP FOR ZVSE51DS
// EXEC LIBR,PARM='MSHP'
ACCESS SUBLIB=CSILIB.ZVSE51DS
CATALOG TCP15F00.L REP=YES
*
* * EXECUTING TCP/IP COMMANDS FROM TCP15F00.L
SET IPADDR = 192.168.0.188
EXEC TCPCOMMN
EXEC TCPOSAX1
EXEC TCPOSAX2
EXEC TCPROUTE
EXEC TCPFILES
EXEC TCPUSERS
EXEC TCPFTPD
EXEC TCPNAMES
EXEC TCPELSTF
EXEC TCPDNS
EXEC TCPDIAGN
* EXEC TCPMESSG
* EXEC TCPTELND
* EXEC TCPLPD
* EXEC TCPGPSD
/+
/*
/&
|
Note: The lib.sulib that is used in Example 2-2 on page 36 is first in the LIBDEF SOURCE search chain of the // EXEC IPNET job that is used to start TCP/IP. This is important because we want to ensure that we pick up the correct initial configuration member.
|
Rather than placing all the commands in a single member, it can be useful to break the configuration commands into separate librarian members, and then run them in the base TCP15F00.L, as shown in Example 2-2. The commands perform the following tasks:
•SET IPADDR = 192.168.0.188
This sets the IP address of this stack and must be unique in the network.
•EXEC TCPCOMMN
TCPCOMMN.L contains common settings that are used by all stacks in this VSE environment, as shown in Example 2-3.
Example 2-3 TCP/IP startup configuration member
// JOB TCPCOMMN CATALOG TCP/IP STARTUP CONFIGURATION MEMBER
// EXEC LIBR,PARM='MSHP'
ACCESS SUBLIB=CSILIB.CONFIG
CATALOG TCPCOMMN.L REP=YES
*
* * EXECUTING TCP/IP COMMANDS FROM TCPCOMMN.L
SET MASK = 255.255.255.0
SECURITY ON,BATCH=ON,AUTO=ON
STEALTH ON
ASECURITY ICMP=NO
CHECKSUM HARDWARE
VERIFY_MEMORY ON
DOWNCHECK OFF
DYNAMIC_ROUTE OFF
DEFINE TRANSLATION,TYPE=SINGLE,MEMBER=IPXLATE,DEFAULT=OS_02
/+
/*
For more information about what these commands do, see the CSI TCP/IP Commands Reference manual.
2.7 FTP hints
Most companies want to set up and run an FTP server on the VSE system. The FTPDAEMN is the program that services FTP clients that are connecting to the FTP server on VSE. The client automation daemon that is created with a DEFINE EVENT command with ACTION=FTP connects to an FTP server, and other applications might also automatically establish FTP connections. You want to be sure to have enough FTP server sessions available for all clients to be serviced efficiently.
2.7.1 Internal FTP server suggestions
An internal FTP server is defined with a command similar to what is shown in the following example:
DEFINE FTPD,ID=FDAA0021,PORT=21,COUNT=3,ZEROERR=NO, -
WELCOME=TCPWELCM,IDLETIME=36000,UNIX=BIN,SENDFAST=YES, -
DYNFILE=NO,ALLOWABORT=YES,EXTTYPES=YES,TIMEOUT=9000, -
EXTRADATA=ACCEPT
With the COUNT=3 settings, a maximum of three clients can be connected into the VSE FTP server simultaneously. However, it is a good idea to have more than one DEFINE FTPD because there is a small window of time (about 1/30th of a second) when a new client is connecting that the single FTP server is not in a listen state. This window can cause a client connection to be rejected. Most clients automatically retry the connection; to avoid this, you can issue a second DEFINE FTPD with the same keyword values (especially the same port number) as the first DEFINE FTPD. The ID= must be different on the second DEFINE FTPD, as shown in the following example:
DEFINE FTPD,ID=FDBB0021,PORT=21,COUNT=3,ZEROERR=NO, -
WELCOME=TCPWELCM,IDLETIME=36000,UNIX=BIN,SENDFAST=YES, -
DYNFILE=NO,ALLOWABORT=YES,EXTTYPES=YES,TIMEOUT=9000, -
EXTRADATA=ACCEPT
The other parameters of the DEFINE FTPD should also be reviewed and set based on your installation requirements.
2.7.2 Using external FTPBATCH servers
Another alternative is to set up and use external FTPBATCH servers in place of the internally defined FTP servers or in addition to them. This configuration provides the following advantages:
•Uses multiple processors. The z/VSE turbo dispatcher does not run multiple subtasks from a single partition on multiple processors at the same time. However, separate partitions can run on different processors simultaneously.
•The internal FTP servers share a single file I/O subtask. External FTPBATCH servers use a dedicated file I/O server for each FTP session.
•Virtual storage usage is segregated for the external FTPBATCH server.
•Recoverability can be expedient by releasing a new FTPBATCH server.
Example 2-4 JCL for an FTPBATCH server
// JOB FTPB2121
// OPTION LOG
// OPTION SYSPARM='00'
// EXEC FTPBATCH,SIZE=FTPBATCH,PARM='FTPDPORT=2121,UNIX=BIN,MAXACT=12'
SET IDLETIME 36000 / 300= 120 SECONDS TO TERMINATE IDLE SESSIONS
/*
Any files that are defined in the TCP/IP file system must have assigns and DLBLs so the sample job that is shown in Example 2-4 can access these files.
The external FTP server that is shown in Example 2-4 is set to listen on port 2121. Another trick that can be used is to have your AUTOFTP events use the external FTP server by using a script similar to what is shown in Example 2-5.
Example 2-5 Using an auto-FTP script
CATALOG AFTPTEST.L REP=YES
LOPEN 127.0.0.1 2121
LUSER xxxxxxxx
LPASS xxxxxxxx
OPEN ip-addr
USER yyyyyyyy
PASS yyyyyyyy
LCD /POWER/LST/F
CD /ZVSE52DS
SETVAR &LFN = &PWRNAME + "." + &PWRNUMB + "." + &PWRSUFF
SETVAR &PCNAME = &LFN + ".LST"
LSITE CC OFF
LSITE STRIP ON
PUT &LFN &PCNAME
CLOSE
LCLOSE
/+
This causes the internal automation daemon (CLIENTD) to use the external FTPBATCH server that is listening on port 2121. Thus, the automation daemon is the FTP client that is sending FTP commands that are contained in the script file to the external FTPBATCH server.
2.8 Partition priorities
You should use weighted balanced partition priorities, with TCP/IP having a higher weight than the socket application partitions. The following example shows priorities with TCP/IP running in the F8 partition:
PRTY BG=FB=FA=F7=F6=F5=F4=F3=F2=C=P=R=W=S=Y=Z=T=F8,F9,F1
PRTY SHARE,BG=100,F2=100,F3=100,F4=100,F8=400
The workload of applications and TCP/IP should be viewed as a single unit of work. This is from stress testing that is performed on our system by using 72 simultaneous FTPBATCH jobs.
2.9 Security
Automatic Security is available and can be used to eliminate maintaining home grown security programs. It provides the following features:
•ICMP=NO to turn off ping sweep hackers
•BLOCKIP=YES can be used to block after multiple violations; for example:
– IPN497I ANONYMOUS denied access to SXTYPASS Password-check from 192.187.96.94
– IPI107I All traffic with 192.187.96.94 is prevented
•Works with DEFINE USER for resources
For more information about setting up and using automatic security, see this website:
Consider the following security issues as you proceed:
•The DEFINE USER command can be used to restrict user IDs to specific directories in the file system, as shown in the following example:
DEFINE USER,ID=GSEUSER1,ROOT='POWER.LST.A'
Limits GSEUSER1 to just Power LST queue class A.
•The DIAG CONNREJ command can be used to display rejected connection attempts.
•STEALTH ON causes no responses to rejected hack attempts.
•DIAG GETVIS monitors TCP/IP and system GETVIS usage.
2.10 Remote running with REXX
Here is a tip about how to start a remote run client from REXX.
The original problem is that when the address link is used to call the TCP/IP CLIENT phase from REXX, this works only once. However, it might fail because of missing internal usage during other calls. Example 2-6 shows an extract from a REXX procedure that uses address link.
Example 2-6 Using address link to start the TCP/IP CLIENT phase
t = 0
t=t+1;SYSIPT.t = "SET DEBUG=ON"
t=t+1;SYSIPT.t = "SET HOST="hostname
t=t+1;SYSIPT.t = "SET USERID="userid
t=t+1;SYSIPT.t = "SET PASSWORD="passwd
t=t+1;SYSIPT.t = "COMMAND ls -l"
t=t+1;SYSIPT.t = "COMMAND ./bin/myscript.sh"
t=t+1;SYSIPT.t = "QUIT"
SYSIPT.0 = t
address link "CLIENT APPL=REXEC"
The solution for multiple sequential calls is writing a second REXX procedure to call (instead of loading) CLIENT under REXX. Change the code extract that is shown in Example 2-6 to the lines that are shown in Example 2-7.
Example 2-7 Using a second REXX procedure to call the TCP/IP REXEC client
cmd1="ls -l"
cmd2="./bin/myscript.sh"
rc=REXXEXEC(userid,passwd,hostname,cmd1,cmd2)
This way, all parameters are passed to a second REXX procedure REXXEXEC, which connects to the internal REXEC client and processes all passed commands.
Example 2-8 shows the relevant parts of the REXXEXEC procedure.
Example 2-8 Sample REXX procedure to start the TCP/IP REXEC client
x=ASSGN('STDOUT','SYSLOG')
narg=arg()
if narg < 4 then do
say 'Invalid number of arguments passed to REXXEXEC.'
say 'You need at least USERID, PWD, HOST, CMD'
exit 8
end
/* Save the passed data */
ruser=arg(1)
rpass=arg(2)
rhost=arg(3)
cmndno=3
loopcnt=narg-3
/* Connect to the internal REXEC client */
call OPEN
x=ASSGN('STDOUT','SYSLST')
sendbuf='REXEC'
Call send
call receive
sendbuf='SET DEBUG=ON'
Call send
call receive
sendbuf='SET HOST='rhost
Call send
call receive
sendbuf='SET USER='ruser
Call send
call receive
sendbuf='SET PASS='rpass
Call send
call receive
/* Process all of the commands passed */
do loopcnt
cmndno=cmndno+1
rcomd=arg(cmndno)
sendbuf='c 'rcomd
Call send
call receive
end
sendbuf='QUIT'
Call send
call receive
call close
exit 0
The following examples show the subroutines open, send, receive, and close. Example 2-9 shows the open routine.
Example 2-9 The open routine
open: /* Start of routine */
x = SOCKET('CLIENT','OPEN',,,,SYSID)
if x = 0 then do
say 'Unable to connect to internal CLIENT.'
say 'Check STACK availability or SYSID settings'
say errmsg
exit 4
end
return
Example 2-10 shows the send routine.
Example 2-10 The send routine
send: /* Start of routine */
say sendbuf
x=SOCKET(handle,'SEND',sendbuf)
if x = 0 then do /* If it failed... */
say errmsg /* Tell us why */
call close /* Close the connection */
exit 8 /* And terminate the program */
end /* If it worked... */
return /* Return to caller */
Example 2-11 shows the Receive routine.
Example 2-11 Receive routine
receive: /* Start of routine */
do forever /* Do until we find a match */
X = SOCKET(HANDLE,'RECEIVE') /* Receive a response */
if x > 4 then do /* If it failed... */
say errmsg /* Tell us what went wrong */
call close /* Close the connection */
exit x /* And terminate the program */
end /* Otherwise... */
say buffer /* What came back ? */
loc=POS('Ready:',buffer) /* Look for another keyword */
if loc > 0 then return /* And if we found it, it's okay */
loc=POS('Error:',buffer) /* Look for another keyword */
if loc > 0 then do /* Oops */
x=ASSGN('STDOUT','SYSLOG') /* Output to SYSLOG only */
say 'REXEC Client command failure. Check SYSLST'
exit 4
end
end
Example 2-12 shows the close routine.
Example 2-12 The close routine
close: /* Start of routine */
x = SOCKET(handle,'CLOSE') /* Close the SOCKET */
return /* Return to caller */
2.11 Version checking
A new batch utility CIALSHPH can be used to verify that downloaded phases have a matching SHA-1 hash. This can ensure that the bits and bytes of any phase or librarian member are at the correct maintenance level. For more information, see the TCP/IP documentation that is listed in “Online resources” on page 228.
2.12 Datagram analysis
A new utility SVSESRVR captures datagrams from a data space. These datagrams can then be investigated by the SeeTCPIP product on a system that is running Windows. Run the SVSESRVR command with a job similar to the JCL shown in Example 2-13.
Example 2-13 JCL to run the SVSESRVR utility
// JOB SVSESRVR
// OPTION SYSPARM='00'
// EXEC SVSESRVR,SIZE=SVSESRVR
TRACEDSP 256K default size of dataspace
TRACETIM 60 default sampling time
/*
After the datagrams are captured, use SeeTCPIP on a system to pull the dataspace of datagrams that were captured by SVSESRVR. This creates an nnn.pcap file on the system and starts the Wireshark datagram analysis tool against the .pcap file.
2.13 Known problems
This section describes the issues that we encountered during our tests.
2.13.1 Routing in a subnet
In this section, we describe a configuration tip that you can use to manage routing problems in a subnet.
Problem
If you notice routing problems in your subnet (perhaps after a switch or router update), check your route configuration. For example, if you have a class C network and your z/VSE has the IP 192.168.0.3, you have a configuration as shown in the following example:
SET IPADDR = 192.168.0.3
SET MASK = 255.255.255.0
Possible solution
If your router has IP 192.168.0.1, you add the following route statements:
DEFINE ROUTE,ID=SUBNETR,LINKID=OSA,IPADDR=192.168.0.0
DEFINE ROUTE,ID=ALL,LINKID=OSA,IPADDR=0.0.0.0,GATEWAY=192.168.0.1
The first route (ID=SUBNETR) routes all packets for the subnet directly (without the use of the gateway). For all other packets, it uses the gateway, as set in the second route (ID=ALL).
2.13.2 Using SSL ciphers
Some supported cipher suites are no longer recommended and some do not work.
Problem
TCP/IP for VSE supports the SSL ciphers 01, 02, 08, 09, 0A, 2F, and 35. Recent tests showed that 01 and 08 do not work anymore, at least when the client is a Java application, such as VSE Navigator.
Solution
Use the AES cipher suites 2F and 35 whenever possible. For security reasons, DES-related cipher suites should no longer be used.
2.13.3 Secure SSL port
Do not rely on a default port value when 'SSL=CLIENT' in FTPBATCH is used.
Problem
The default port number for FTPBATCH always is 21, whereas the default port for secure FTP often is 990.
Solution
When FTPBATCH is used with ‘SSL=CLIENT’, the port number must always be explicitly specified on the OPEN command, as shown in the following example:
OPEN ipaddr port
2.13.4 SSL client does not verify the server certificate
You should be aware that when the GSK API is used, a connection can be established even when a non-existing key ring is referenced.
Symptom
An SSL client does not verify the server certificate. The connection is established even when a non-existing key ring is referenced; for example, for FTPBATCH, as shown in the following example:
// EXEC FTPBATCH,SIZE=FTPBATCH,PARM='SSL=CLIENT'
SET SSL PRIVATE CRYPTO.KEYRING.nnnn
In this example, there is no nnnn.PRVK, nnnn.CERT, and nnnn.ROOT members or they can contain keys that are not related to the server certificate.
Reason
This is the intended behavior of the CSI implementation of the GSK API. An SSL client does not read the key ring. Therefore, function gsk_secure_soc_init by default uses handshake type GSK_AS_CLIENT_NO_AUTH.
2.13.5 TLS issue with IBM Personal Communications 6.0.7
Here is a problem that we experienced when we moved from PCOM 6.0.5 to 6.0.7.
Problem
Personal Communications 6.0.7 displays message “The Local Security Authority Cannot Be Contacted”.
TCP/IP for VSE/ESA issues the following messages:
TEL927I TELNETDS diagnostic: SSLRSRBD RC=00000004 RS=000001A8
TEL927D TELNETDS diagnostic: SSLHSINI RC=FFFFF3E4 RS=00000186
TEL917I Daemon Resetting Telnet Termname: nnnn IPaddr: n.n.n.n
This setup worked with PCOM 6.0.5.
Reason
PCOM 6.0.7 tries to use TLS 1.1, which is not supported by TCP/IP for VSE/ESA. A fix should be provided by PCOM to allow the use of TLS 1.0.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.