TCPRUN 'STACK' TAG CHECKING INHIBITS ALTERNATE SSL/STACK USE
APAR Identifier ...... PI59963 Last Changed ........ 16/12/02
TCPRUN 'STACK' TAG CHECKING INHIBITS ALTERNATE SSL/STACK USE
Symptom ...... IN INCORROUT Status ........... CLOSED PER
Severity ................... 3 Date Closed ......... 16/05/31
Component .......... 5735FAL00 Duplicate of ........
Reported Release ......... 630 Fixed Release ............ 999
Component Name TCP/IP V2 FOR V Special Notice
Current Target Date .. Flags
SCP ...................
Platform ............
Status Detail: SHIPMENT - Packaged solution is available for
shipment.
PE PTF List:
PTF List:
Release 540 : UI38295 available 16/05/31 (1000 )
Release 620 : UI38296 available 16/05/31 (1000 )
Release 630 : UI38297 available 16/05/31 (1602 )
Parent APAR:
Child APAR list:
ERROR DESCRIPTION:
Customer is attempting to configure an additional pool of SSL
servers (SS2*) for use with an alternate TCP/IP stack (TCPIP2)
on a given system, where the default TCP/IP stack and SSL server
pool (TCPIP / SSL*) already are configured and in use.
With the use of alternate configuration values generated by the
SSLPOOL utility, the SS2* servers continue to fail at startup
with messages:
...
DTCRUN1028E :Stack.TCPIP2 specified in SYSTEM DTCPARMS D1
does not match "TcpipUserid TCPIP" in the TCPIP DATA file
DTCRUN1099E Server not started - correct problem and retry
...
An attempt to use a server profile exit (TCPRUNXT) to create
a server-private instance of the needed TCPIP DATA file (at
the applicable pool server common-use SFS directory) does
not resolve this problem.
LOCAL FIX:
None.
PROBLEM SUMMARY:
****************************************************************
* USERS AFFECTED: All users of the z/VM SSL server, especially *
* those establishing a server pool for use *
* with an alternate TCP/IP stack. *
****************************************************************
* PROBLEM DESCRIPTION: *
****************************************************************
* RECOMMENDATION: APPLY PTF *
****************************************************************
For a given TCP/IP server environment, the TCPIPUSERID statement
in the TCPIP DATA file must be suitably configured to identify
the TCP/IP stack server with which TCP/IP client commands are to
interact. When a DTCPARMS file ':stack.' tag has been
configured for a given TCP/IP server, the TCPRUN exec compares
the TCPIPUSERID statement and ':stack.' tag values, to ensure
that server will interact with the correct TCP/IP stack.
For an environment where an appropriate configuration already
has been established for a given TCP/IP stack and its servers,
the ':stack.' tag checking performed by TCPRUN inhibits the
setup and configuration of other servers for use with an
alternate TCP/IP stack server. This happens because only one
instance of the TCPIP DATA file (and, its TCPIPUSERID statement
and value) can exist for the given system. Attempts to startup
a server for the alternate stack fail with the DTCRUN1028E error
message being reported, as previously described.
If one customizes the TCP/IP server profile exit (TCPRUNXT), via
its 'SETUP' exit call, to create a server-private instance of a
suitable TCPIP DATA file (created at the minidisk or SFS
directory accessed at CMS file mode A by the server), this
effort also yields the same startup failure. This occurs
because the applicable TCPIPUSERID value is not used by the
':stack.' tag checking performed by TCPRUN (content of only the
TCPIP DATA file referenced by TCPRUN prior calls to the TCPRUNXT
exit is used).
PROBLEM CONCLUSION:
The TCPRUN exec has been updated to provide support for an
added DTCPARMS file server configuration tag -- :TcpDataFile.
With this tag, one can specify the file name and file type of an
'alternate' TCP/IP data file that is to be referenced when
server initialization is performed. When the designated file is
confirmed to exist, its TCPIPUSERID and HOSTNAME statement
values will be acquired and used for server initialization
processing. In addition, the file identified by the
:TcpDataFile. tag is copied to the minidisk or SFS directory
accessed at CMS file mode A as the file 'TCPIP DATA', to ensure
appropriate TCP/IP data file content is referenced by the
subject server, after its initialization is complete.
Additional TCPRUN messages, described later, have been added to
provide information regarding the specific TCP/IP data file that
is used during sever initialization.
In addition, the SSLPOOL command has been updated to include
applicable :TcpDataFile. tags and values within its produced
PLANINFO file, for the case when a (TCP/IP stack) user ID
parameter value -- different from the 'TCPIP' default -- is used
in conjunction with the PLAN option of this command.
The revised information that follows will be included in any
future updates to the following publication(s):
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
SC24-6238-07 -- z/VM: TCP/IP Level 630 Planning and
Customization
Chapter 5. General TCP/IP Server Configuration
Section: DTCPARMS Tags
Page: 48
SC24-6238-03 -- z/VM: TCP/IP Level 620 Planning and
Customization
Chapter 5. General TCP/IP Server Configuration
Section: DTCPARMS Tags
Page: 46
SC24-6125-05 -- z/VM: TCP/IP Level 540 Planning and
Customization
Chapter 5. General TCP/IP Server Configuration
Section: DTCPARMS Tags
Page: 44
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* 'Table 7. DTCPARMS Tags for Configuring Servers', is updated
as follows:
- The description of the ':stack.' tag is modified:
:Stack.stackID
If specified, the TCP/IP stack user ID (stackID) is
compared to that cited by the TCPIPUSERID statement in the
TCP/IP data file (TCPIP DATA, by default), or an equivalent
such file, as designated by a :TcpDataFile. tag. If the
compared user ID values do not match, the server is not
started.
- An entry and description for the ':TcpDataFile.' tag is
added:
:TcpDataFile.fname ftype
If specified, identifies a particular TCP/IP data file that
is to be referenced when the subject server is initialized.
When not specified, the first available instance of the
file TCPIP DATA is referenced by default.
If a file type (ftype) is not supplied for the specified
value, 'DATA' is used by default.
The file cited by this tag is copied to the minidisk or
directory accessed at CMS filemode A, to avoid potential
content conflicts with a TCPIP DATA file that might exist
elsewhere in the CMS search order of the server. The
copied instance is deleted at completion of a normal server
shutdown.
(For levels 620 and 540, the 'Table 7' reference is instead to
'Table 6')
----------------------------------------------------------------
(Level 630)
Chapter 16. Configuring the SSL Server
Section: Step 4: Update the DTCPARMS File for the SSL DCSS
Management Agent Server
Page: 532
(Level 620)
Chapter 18. Configuring the SSL Server
Section: Step 4: Update the DTCPARMS File for the SSL DCSS
Management Agent Server
Pages: 594-595
(Level 540 - This change is not applicable)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* The :TcpDataFile. tag is added to the list of tags after the
lead-in sentence that begins as 'Tags that are significant
for...', and, to the ensuing example:
Tags that are significant for the SSL DCSS Management Agent
are:
:DCSS_Parms.
:For.
:Stack.
:TcpDataFile.
For example:
:Nick.SSTDCSSM :Type.server :Class.ssl_dcss_agent
:Stack.TCPIPTST
:TcpDataFile.TCPIPTST DATA
:For.SST*
...
* The second bullet item after the 'Additional Notes' heading
is modified as follows:
* When an SSL DCSS Management Agent server is deployed for
use with a TCP/IP server other than the default of TCPIP,
the DTCPARMS :Type.server. entry for that SSL server pool
must include an appropriate :Stack.userid definition.
Similarly, an applicable :TcpDataFile. tag definition
might be required, to ensure the correct TCP/IP data file
TCPIPUSERID value is referenced. Otherwise, an
association with the correct TCP/IP server will not be
established, or, the agent server might not initialize.
----------------------------------------------------------------
(Level 630)
Chapter 16. Configuring the SSL Server
Section: Step 5: Update the DTCPARMS File for the SSL Server
Pool
Pages: 533-534
(Level 620)
Chapter 18. Configuring the SSL Server
Section: Step 5: Update the DTCPARMS File for the SSL Server
Pool
Pages: 596-597
(Level 540 - This change is not applicable)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* The :TcpDataFile. tag is added to the list of tags after the
lead-in sentence that begins as 'Tags that are significant
for...', and, to the ensuing example:
Tags that are significant for the SSL server are:
:AdminIDIlist.
...
:Stack.
:TcpDataFile.
:Timestamp.
...
For example:
* SSL Server Pool for TCPIPT Test Stack
:Nick.SST* :type.server :Class.ssl
:Stack.TCPIPTST
:TcpDataFile.TCPIPTST DATA
:VMlink. .DIR VMSYS:TCPMAINT.SSLPOOL_SST <. A FORCERW>
...
* The second bullet item after the 'Additional Notes' heading
is modified as follows:
* When an SSL server is deployed for use with a TCP/IP server
other than the default of TCPIP, the DTCPARMS :Type.server.
entry for that SSL server pool must include an appropriate
:Stack.userid definition. Similarly, an applicable
:TcpDataFile. tag definition might be required, to ensure
the correct TCP/IP data file TCPIPUSERID value is
referenced. Otherwise, an association with the correct
TCP/IP server will not be established, or, the agent server
might not initialize.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
GC24-6235-04 -- z/VM: TCP/IP Level 630 Diagnosis Guide
Chapter 14. SSL Server Diagnosis
Section: Diagnosing Problems /
Heading: Symptom - The SSL Server Does Not Initialize
Pages: 188-189
GC24-6235-03 -- z/VM: TCP/IP Level 620 Diagnosis Guide
Chapter 14. SSL Server Diagnosis
Section: Diagnosing Problems /
Heading: Symptom - The SSL Server Does Not Initialize
Pages: 180-181
GC24-6123-04 -- z/VM: TCP/IP Level 540 Diagnosis Guide
Section: Diagnosing Problems /
Heading: Symptom - The SSL Server Does Not Initialize
Page: 178
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* The text for 'Analysis' step '1', sub-step 'b' is revised as
follows:
b. Verify that the TCPIPUSERID statement of the TCP/IP data
file (TCPIP DATA, by default) referenced by the SSL
server cites the correct TCP/IP server virtual machine.
If a DTCPARMS :TcpDataFile. tag designates an alternate
TCP/IP data file for use, verify the specified file is
accessible by the SSL server (and, that its content is
correct). In addition, confirm that the correct TCP/IP and
DCSS Management Agent servers have been identified by a
DTCPARMS :Stack. tag defined for the subject server.
(For level 540, the 'sub-step b' reference does not apply)
* The text for 'Analysis' step '4', sub-step 'a' is revised as
follows:
a. Verify that the TCPIPUSERID statement of the TCP/IP data
file (TCPIP DATA, by default) referenced by the SSL
server cites the correct TCP/IP server virtual machine.
If a DTCPARMS :TcpDataFile. tag designates an alternate
TCP/IP data file for use, verify the specified file is
accessible by the SSL server (and, that its content is
correct). In addition, confirm that the correct TCP/IP
server is identified by a DTCPARMS :Stack. tag defined
for the subject SSL server.
(For level 540, the above is added as sub-step 'b' to a
modified Step '2'):
2. If the server cannot connect to the TCP/IP virtual
machine:
a. Verify that the TCP/IP server is started.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
GC24-6237-07 -- z/VM: TCP/IP Level 630 Messages and Codes
Chapter 19. TCP/IP Utilities
Section: TCPRUN Messages
Pages: 555-556
GC24-6237-03 -- z/VM: TCP/IP Level 620 Messages and Codes
Chapter 20. TCP/IP Utilities
Section: TCPRUN Messages
Page: 575
GC24-6124-04 -- z/VM: TCP/IP Level 540 Messages and Codes
Chapter 20. TCP/IP Utilities
Section: TCPRUN Messages
Page: 515
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* The new message descriptions that follow are added:
----------------------------------------------------------------
New Message:
1046 Using TCP/IP data file: file_ID
Explanation:
The indicated file (file_ID) is the TCP/IP data file that will
be referenced for server initialization and operation. When a
DTCPARMS :TcpDataFile. tag is configured to designate a
specific TCP/IP data file for use, a second instance of this
message is reported to cite that file.
System Action:
Command processing continues.
System Programmer Response:
None.
Severity: Informational
----------------------------------------------------------------
New Message:
1050I File file_ID copied for server use as
file: TCPIP DATA A
Explanation:
The indicated file (file_ID) has been designated by a DTCPARMS
:TcpDataFile. tag, as the TCP/IP data file that is to be
referenced server initialization and operation (when
applicable). The listed file is copied as indicated, to avoid
potential content conflicts with a TCPIP DATA file that might
exist elsewhere in the CMS search order of the server.
System Action:
Command processing continues.
System Programmer Response:
None.
Severity: Informational
TEMPORARY FIX:
COMMENTS:
**** PE16/10/03 FIX IN ERROR. SEE APAR PI70089 FOR DESCRIPTION
MODULES/MACROS:
DTCUME DTCUMEB SSLPOOL TCPRUN
SRLS:
SC24623807
GC24623504
GC24623707
SC24623803
GC24623503
GC24623703
SC24612505
GC24612304
GC24612404
RTN CODES:
CIRCUMVENTION:
MESSAGE TO SUBMITTER: