This Function Component addresses the need TDI to be able to issue privileged z/OS commands, including RACF, ACF2 and TopSecret commands.
The z/OS environment requires a number of parameters for this FC to function properly.
If NULL or empty, Security_Type of the conversation is ATB_SECURITY_SAME and the identity under which the IBM TDI is started is used with a default profile. Otherwise, Security_Type of the conversation is ATB_SECURITY_PROGRAM and the TSO command will be executed under the identity of the user specified using the profile of that user.
If NULL or empty, the conversation will succeed only if the user specified is granted surrogate authorization on the system where the REXX script is deployed.
The z/OS TSO Command Line Function Component is able to execute TSO/E shell commands.
This component is only responsible for execution of the command it is passed - it will not construct shell commands and will not understand the business logic associated with the commands it is executing.
The Function Component is given the command line on input and returns the execution status and the output generated by the command. Architecturally this FC consists of a Java layer, a USS shared library and a REXX script component: The Java layer passes the command to the shared library, the shared library passes it to the REXX script through APPC and the REXX script executes the TSO/E command and passes back the result.
Specific business logic of a higher level can be built on top of this Function Component - for example a Connector or Adapter that manages RACF users. This Connector could construct the correct RACF commands (that correspond to add, modify, and so forth) and use the FC internally to execute them.
The z/OS TSO Command Line FC throws an exception:
When the following message is logged: "CTGDKB012E Could not execute TSO command. The command returned return code: 26". These could be the possible reasons for this:
ATB80043I Calling program did not specify both a userid and a password and/or surrogate authorization check failed.
Make sure we have specified both a valid username and password.
ATB80049I Value specified on Local_LU_name parameter is not the name of the system base LU or the name of a NOSCHED LU
You may look for another LU defined as "BASE=YES" in the output from the "D APPC,LU,ALL" command.
Service: ATBRCVW
ATB80100I From VTAM macro APPCCMD: Primary error return code: 0018, secondary error return code: 0000, sense code: 08640001.
The specified userid is not authorized to execute the command or to execute the data set containing the TDIEXEC REXX script.
An Entry object with an Attribute named command whose
value is the TSO/E command to be executed.
An Entry object with the following Attributes:
The APPC conversation can be performed in two modes: Security_Same and Security_Progam.
Whether the conversation will be held in the Security_Program mode
depends on whether the User Name Function Component parameter
contains a non NULL value.
The REXX script is the component that actually executes the TSO
command.
TDI will be allowed or disallowed to execute the TSO
command depending on the privileges of the user id specified in the
z/OS TSO Command Line Function Component configuration.
To minimize the chances that the REXX script ability to execute
TSO commands is maliciously exploited, the following optional deployment
strategy can be applied:
A specific dataset is created for the REXX script - this
dataset will contain the REXX script only and no other members. In
RACF the access to the dataset will be limited to only those users
that we want to allow to execute that script. The same user(s) will
then need to be specified in the z/OS TSO Command Line Function Component
configuration.
Other options for restricting the access to the REXX script include
limiting the access provided by APPC:
The APPC/MVS calls use pseudonyms for actual calls, characteristics, variables, and so on. For example, the return_code parameter for APPC/MVS
calls can be the pseudonym atb_ok. The integer value for the atb_ok
pseudonym is 0. APPC/MVS provides several pseudonym files in the header
file data set SYS1.SIEAHDR.H that define
the pseudonyms and corresponding integer values for different languages
and communication calls.
The ATBPBREX pseudonym file is provided for
APPC/MVS calls. This pseudonym file contains REXX assignment statements
that simplify writing transaction programs in REXX. The TDIEXEC REXX
script uses internally this pseudonym file therefore the ATBPBREX
file should be available in the header file data set SYS1.SIEAHDR.H
on the underlying z/OS environment.
If this file does not exist on your z/OS environment it could be
copied from somewhere else or it can be created by using this sample
ATBPBREX file:
If we decide to create the file, a new FB 80 z/OS data set has
to be allocated, and the TDIEXEC script has to be edited to use a
different data set. If creating a data set named, for example, ROOT.MYATBREX, the TDIEXEC should be edited
like this:
The provided ATBPBREX file
is just an example and may not be applicable on every z/OS environment.
Before using the TSO Command Line Function Component, a REXX script
must be deployed on a z/OS dataset and APPC configured accordingly:
The z/OS TSO Command Line Function Component contains a REXX script
named TDIEXEC that executes a TSO/E command
and returns the command output.
This REXX script has to be copied to a FB 80 z/OS dataset where
it will be invoked from.
The z/OS TSO Command Line Function Component contains a JCL named TDITP.jcl that defines the TP Profile data
for the REXX script.
You customize the JCL according to the z/OS system environment
and execute it.
In detail, in order to deploy the FC we should:
We can find the TDITP.jcl JCL
and TDIEXEC REXX script in the tso_fc subfolder of the IBM TDI installation
folder (only on z/OS).
For example, this can be done
from the TSO shell or menu 6 of ISPF with the following commands:
To do so, follow the instructions within the TDITP.jcl
JCL. Basically we need to specify these names:
You may also create our own class of transaction
initiators by adding a similar definition - 'CLASSADD
CLASSNAME(MYCLASS) MSGLIMIT(1000) MAX(10) MIN(1) RESPGOAL(1)'.
The definition needs to be activated with the 'SET ASCH=xx' system
command in which the 'xx' are the last two characters of the ASCHPMxx
USER.PARMLIB member.
The minimum number of started
transaction initiators should correspond to the expected number of
transactions running at a time.
If either or both of them are not running, they need
to be started using these commands: 'S APPC,SUB=MSTR,APPC=xx' and 'S
ASCH,SUB=MSTR,ASCH=xx'. The 'xx' are the last two characters
of the APPCPMxx and ASCHPMxx USER.PARMLIB members.
This can be ensured by checking the
APPC configuration file which by default is located in the USER.PARMLIB
data set. The PARMLIB member named APPCPMxx (where 'xx' can vary, for example, APPCCPM00 or APPCPM1A) contains definitions of all local
LUs. The base logical unit for transaction scheduler is marked with
'BASE'.
The LU names defined in that file must
correspond to the VTAM application definitions for APPC/MVS located
in the USER.VTAMLST members.
For example here
are the definitions of the BASELU logical unit:
File: USER.PARMLIB(APPCPM00)
File: USER.VTAMLST(A01APPC)
Even if a LU is defined it still may not be active. You
can check if a LU is actually active by executing the following system
command: 'D APPC,LU,ALL', which will display information
about all LUs. To activate a particular LU use the VTAM command VARY
ACT (for example, 'V NET,ACT,ID=A01APPC', where 'A01APPC'
is the name of the VTAMLST member).
You
can submit it from ISPF by typing 'sub' in front of the name
of the JCL. Notes:
"z/OS environment Support", in IBM TDI V7.1 Installation and Administrator Guide.
Function Component Output
Authentication
Authorization
Required pseudonym file
/****START OF SPECIFICATIONS******************************************/
/* */
/*01* MODULE-NAME = ATBPBREX */
/* */
/*02* DESCRIPTIVE-NAME = Interface Declaration File for LU 6.2 */
/* Protocal Boundary Interface - REXX */
/* */
/*02* COMPONENT = APPC Component (SCACB) */
/* */
/*01* PROPRIETARY STATEMENT= */
/****PROPRIETARY_STATEMENT********************************************/
/* */
/* */
/* LICENSED MATERIALS - PROPERTY OF IBM */
/* THIS EXEC IS "RESTRICTED MATERIALS OF IBM" */
/* 5647-A01 (C) COPYRIGHT IBM CORP. 1998 */
/* */
/* STATUS= HBB6606 */
/* */
/* EXTERNAL CLASSIFICATION: GUPI */
/* */
/* END OF EXTERNAL CLASSIFICATION */
/* */
/****END_OF_PROPRIETARY_STATEMENT*************************************/
/* */
/* */
/*01* DISCLAIMER = */
/* */
/* THIS SAMPLE SOURCE IS PROVIDED FOR TUTORIAL PURPOSES ONLY. A */
/* COMPLETE HANDLING OF ERROR CONDITIONS HAS NOT BEEN SHOWN OR */
/* ATTEMPTED, AND THIS SOURCE HAS NOT BEEN SUBMITTED TO FORMAL IBM */
/* TESTING. THIS SOURCE IS DISTRIBUTED ON AN 'AS IS' BASIS */
/* WITHOUT ANY WARRANTIES EITHER EXPRESSED OR IMPLIED. */
/* */
/*01* FUNCTION = LU 6.2 REXX pseudonym file */
/* */
/*01* METHOD OF ACCESS: */
/* */
/* If you are using interpreted REXX provided by TSO/E the */
/* EXECIO command should be used to read this file. */
/* */
/*01* DISTRIBUTION LIBRARY: AIEAHDR */
/* */
/*01* CHANGE-ACTIVITY: */
/* */
/* FLAG LINEITEM FMID DATE ID COMMENT */
/* $01=OY54027 HBB4420 920505 PDI8: MAKE PART AVAILABLE IN HBB4420 */
/* $P1=PKB0817 HBB4430 920729 PDI8: Support of Conversation State */
/* constants. */
/* $L1=APPCP HBB6603 960105 PDE6: APPC/MVS PC support */
/****END OF SPECIFICATIONS********************************************/
/* *****************************************************************/
/* Conversation State Values @P1A*/
/* *****************************************************************/
atb_initialize_state = 2 /*@P1A*/
atb_send_state = 3 /*@P1A*/
atb_receive_state = 4 /*@P1A*/
atb_send_pending_state = 5 /*@P1A*/
atb_confirm_state = 6 /*@P1A*/
atb_confirm_send_state = 7 /*@P1A*/
atb_confirm_deallocate_state = 8 /*@P1A*/
atb_defer_receive_state = 9 /*@L1A*/
atb_defer_deallocate_state = 10 /*@L1A*/
atb_sync_point_state = 11 /*@L1A*/
atb_sync_point_send_state = 12 /*@L1A*/
atb_sync_point_dealloc_state = 13 /*@L1A*/
/* *****************************************************************/
/* Conversation Type Values */
/* *****************************************************************/
atb_basic_conversation = 0
atb_mapped_conversation = 1
/* *****************************************************************/
/* Data Received Values */
/* *****************************************************************/
atb_no_data_received = 0
atb_data_received = 1
atb_complete_data_received = 2
atb_incomplete_data_received = 3
/* *****************************************************************/
/* Deallocate Type Values */
/* *****************************************************************/
atb_deallocate_sync_level = 0
atb_deallocate_flush =1
atb_deallocate_confirm = 2
atb_deallocate_abend = 3
/* *****************************************************************/
/* Error Direction Values */
/* *****************************************************************/
atb_receive_error = 0
atb_send_error = 1
/* *****************************************************************/
/* Fill Values */
/* *****************************************************************/
atb_fill_ll = 0
atb_fill_buffer = 1
/* *****************************************************************/
/* Lock Values */
/* *****************************************************************/
atb_locks_short = 100
atb_locks_long = 101
/* *****************************************************************/
/* Prepare to Receive Type Values */
/* *****************************************************************/
atb_prep_to_receive_sync_level = 0
atb_prep_to_receive_flush = 1
atb_prep_to_receive_confirm = 2
/* *****************************************************************/
/* Notify Type Values */
/* *****************************************************************/
atb_notify_type_none = '00000000'X
atb_notify_type_ecb = '00000001'X
/* *****************************************************************/
/* Request To Send Received Values */
/* *****************************************************************/
atb_req_to_send_not_received = 0
atb_req_to_send_received = 1
/* *****************************************************************/
/* Return Code Values */
/* *****************************************************************/
atb_ok = 0
atb_allocate_failure_no_retry = 1
atb_allocate_failure_retry = 2
atb_conversation_type_mismatch = 3
atb_pip_not_specified_correctly = 5
atb_security_not_valid = 6
atb_sync_lvl_not_supported_lu = 7 /*@L0A*/
atb_sync_lvl_not_supported_pgm = 8
atb_tpn_not_recognized = 9
atb_tp_not_available_no_retry = 10
atb_tp_not_available_retry = 11
atb_deallocated_abend = 17
atb_deallocated_normal = 18
atb_parameter_error = 19
atb_product_specific_error = 20
atb_program_error_no_trunc = 21
atb_program_error_purging = 22
atb_program_error_trunc = 23
atb_program_parameter_check = 24
atb_program_state_check = 25
atb_resource_failure_no_retry = 26
atb_resource_failure_retry = 27
atb_unsuccessful = 28
atb_deallocated_abend_svc = 30
atb_deallocated_abend_timer = 31
atb_svc_error_no_trunc = 32
atb_svc_error_purging = 33
atb_svc_error_trunc = 34
atb_take_backout = 100 /*@L0A*/
atb_deallocated_abend_bo = 130 /*@L0A*/
atb_deallocated_abend_svc_bo = 131 /*@L0A*/
atb_deallocated_abend_timer_bo = 132 /*@L0A*/
atb_resource_fail_no_retry_bo = 133 /*@L0A*/
atb_resource_failure_retry_bo = 134 /*@L0A*/
atb_deallocated_normal_bo = 135 /*@L0A*/
/* *****************************************************************/
/* Reason Code Values @L0A*/
/* *****************************************************************/
atb_invalid_vote_read_only = 1 /*@L0A*/
atb_invalid_wait_for_outcome = 2 /*@L0A*/
atb_invalid_action_if_problems = 3 /*@L0A*/
atb_extract_exit_not_specified = 4 /*@L0A*/
atb_extract_exit_failed = 5 /*@L0A*/
atb_no_active_tp = 6 /*@L0A*/
atb_service_error = 7 /*@L0A*/
/* *****************************************************************/
/* Return Control Values */
/* *****************************************************************/
atb_when_session_allocated = 0
atb_immediate = 1
atb_when_conwinner_allocated = 100
/* *****************************************************************/
/* Security Type Values */
/* *****************************************************************/
atb_security_none = 100
atb_security_same = 101
atb_security_program = 102
/* *****************************************************************/
/* Send Type Values */
/* *****************************************************************/
atb_buffer_data = 0
atb_send_and_flush = 1
atb_send_and_confirm = 2
atb_send_and_prep_to_receive = 3
atb_send_and_deallocate = 4
/* *****************************************************************/
/* Status Received Values */
/* *****************************************************************/
atb_no_status_received = 0
atb_send_received = 1
atb_confirm_received = 2
atb_confirm_send_received = 3
atb_confirm_dealloc_received = 4
atb_take_syncpt = 5 /* @L0A*/
atb_take_syncpt_send = 6 /* @L0A*/
atb_take_syncpt_dealloc = 7 /* @L0A*/
/* *****************************************************************/
/* Sync Level Values */
/* *****************************************************************/
atb_none = 0
atb_confirm = 1
atb_syncpt = 2 /* @L0A*/
/* *****************************************************************/
/* Set Syncpt Options Values @L0A*/
/* *****************************************************************/
atb_syncpt_options_nochange = 0 /*@L0A*/
atb_vote_read_only_no = 1 /*@L0A*/
atb_vote_read_only_yes = 2 /*@L0A*/
atb_wait_for_outcome_no = 1 /*@L0A*/
atb_wait_for_outcome_yes = 2 /*@L0A*/
atb_action_if_problems_commit = 1 /*@L0A*/
atb_action_if_problems_backout = 2 /*@L0A*/
...
/********************************************************************/
/* Get psuedonym definition file for REXX for the LU6.2 Verbs */
/* sys1.sieahdr.h(atbpbrex) */
/********************************************************************/
"alloc f(datain) da('ROOT.MYATBREX') shr reuse"
"execio * diskr datain (stem linelist. finis"
do x = 1 to linelist.0
interpret linelist.x
end
drop linelist.
"free f(datain)"
...
Setting up the native part of the FC
OGET 'TDI_install_dir/tso_fc/TDIEXEC' '<TDIEXEC_dataset>(TDIEXEC)'
OGET 'TDI_install_dir/tso_fc/TDITP.jcl' '<TDITP.jcl_dataset>(TDITP)'
LUADD
ACBNAME(BASELU)
BASE
SCHED(ASCH)
TPDATA(SYS1.APPCTP)
TPLEVEL(SYSTEM)
SIDEINFO
DATASET(SYS1.APPCSI)
VBUILD TYPE=APPL
BASELU APPL ACBNAME=BASELU, X
APPC=YES, X
AUTOSES=0, X
DDRAINL=NALLOW, X
DLOGMOD=#BATCH, X
DMINWNL=5, X
DMINWNR=5, X
DRESPL=NALLOW, X
DSESLIM=10, X
LMDENT=19, X
MODETAB=LOGMODES, X
PARSESS=YES, X
See also