Planning to use system REXX

System REXX starts automatically during Master Scheduler Initialization and should run in the SYSSTC service class. There is a SYS1.PARMLIB member (CTIAXR00) for controlling Component Trace (Errors are traced by default) and also a SYS1.SAMPLIB member (AXR00) that may be tailored and copied into SYS1.PARMLIB to override IBM® supplied defaults. Additionally, IEASYSnn supports a parmlib concatenation of AXRnn members. For more information, see z/OS MVS Initialization and Tuning Reference. If no alternative AXRnn member has been configured and AXR00 is not found, REXX&SYSCLONE is the default value assigned to CPF and SYS1.SAXREXEC the default value assigned to REXXLIB.

The System REXX address space (AXR) and eight TSO Server address spaces (AXR01-AXR08) in which TSO=YES requests are processed must have user IDs defined and be connected to the installation's designated RACF® group for system address spaces. This RACF group must have READ authority to the SYS1.PARMLIB and SYS1.SAXREXEC data sets. You must ensure that there are matching entries in either the started procedures table (ICHRIN03) or that a STARTED class profile has been defined that matches each new address space name. If you prefer, both the started procedures table and STARTED class profile might be in place. This action ensures that the correct user ID and system group characteristics are assigned.

The following RACF commands can be used to accomplish this simply and dynamically. If SYS1 is not the RACF group name, substitute it with the correct group name.

ADDUSER AXR     DFLTGRP(SYS1)
ADDUSER AXR01   DFLTGRP(SYS1)
ADDUSER AXR02   DFLTGRP(SYS1)
ADDUSER AXR03   DFLTGRP(SYS1)
ADDUSER AXR04   DFLTGRP(SYS1)
ADDUSER AXR05   DFLTGRP(SYS1)
ADDUSER AXR06   DFLTGRP(SYS1)
ADDUSER AXR07   DFLTGRP(SYS1)
ADDUSER AXR08   DFLTGRP(SYS1)

RDEFINE STARTED AXR*.* STDATA(USER(=MEMBER),GROUP(SYS1))

SETROPTS RACLIST(STARTED) GENERIC(STARTED) REFRESH

For details, see the topic "Using Started Procedures" in the z/OS Security Server RACF Security Administrator's Guide.

Alternatively, after you substitute installation preferences for user ID and group name, add the following statements to ICHRIN03 which must then be recompiled and link-edited. Also, recognize that an IPL is required for the updated started procedures table to take effect.

Below are entries to be added to ICHRIN03:

*
DC CL8'AXR' PROCEDURE NAME
DC CL8'AXR' USERID
DC CL8'SYS1' GROUP NAME
DC XL1'00' TRUSTED ATTRIBUTE BIT
DC XL7'00' RESERVED
*
DC CL8'AXR01' PROCEDURE NAME
DC CL8'AXR01' USERID
DC CL8'SYS1' GROUP NAME
DC XL1'00' TRUSTED ATTRIBUTE BIT
DC XL7'00' RESERVED
*
DC CL8'AXR02' PROCEDURE NAME
DC CL8'AXR02' USERID
DC CL8'SYS1' GROUP NAME
DC XL1'00' TRUSTED ATTRIBUTE BIT
DC XL7'00' RESERVED
*
DC CL8'AXR03' PROCEDURE NAME
DC CL8'AXR03' USERID
DC CL8'SYS1' GROUP NAME
DC XL1'00' TRUSTED ATTRIBUTE BIT
DC XL7'00' RESERVED
*
DC CL8'AXR04' PROCEDURE NAME
DC CL8'AXR04' USERID
DC CL8'SYS1' GROUP NAME
DC XL1'00' TRUSTED ATTRIBUTE BIT
DC XL7'00' RESERVED
*
DC CL8'AXR05' PROCEDURE NAME
DC CL8'AXR05' USERID
DC CL8'SYS1' GROUP NAME
DC XL1'00' TRUSTED ATTRIBUTE BIT
DC XL7'00' RESERVED
*
DC CL8'AXR06' PROCEDURE NAME
DC CL8'AXR06' USERID
DC CL8'SYS1' GROUP NAME
DC XL1'00' TRUSTED ATTRIBUTE BIT
DC XL7'00' RESERVED
*
DC CL8'AXR07' PROCEDURE NAME
DC CL8'AXR07' USERID
DC CL8'SYS1' GROUP NAME
DC XL1'00' TRUSTED ATTRIBUTE BIT
DC XL7'00' RESERVED
*
DC CL8'AXR08' PROCEDURE NAME
DC CL8'AXR08' USERID
DC CL8'SYS1' GROUP NAME
DC XL1'00' TRUSTED ATTRIBUTE BIT
DC XL7'00' RESERVED

For details, see the topic "The Started Procedures Table (ICHRIN03)" in the z/OS Security Server RACF System Programmer's Guide. A full example of ICHRIN03 can be found in SYS1.SAMPLIB.

The System REXX address space (AXR) and its TSO Server address spaces should run in the SYSSTC service class and should not be explicitly classified to a different service class. The service class can be displayed by issuing DISPLAY JOBS,AXR from the operator console.

The System REXX address space, AXR, is non-cancelable. If absolutely necessary, you can terminate the AXR address space by issuing the FORCE AXR,ARM command. Using the FORCE command can have ramifications for your system, so read FORCE command in z/OS MVS System Commands before using it.

The ENF signals that SYSREXX issues when the AXR address starts and ends are listed in ENF event codes and meanings. The operator can restart AXR by using the AXRPSTRT procedure, found in SYS1.PROCLIB. The syntax for restarting AXR can be one of the following:

START AXRPSTRT
START AXRPSTRT,AXR=aa
START AXRPSTRT,AXR=(aa,bb,...)

where aa and bb are AXRnn parmlib members in SYS1.PARMLIB. If no parmlib members are specified, values from AXR00 are applied if it exists; otherwise, default values are assigned.

You can use the command prefix (CPF) defined in AXR00 to invoke a REXX exec or the SYSREXX STATUS command from a console rather than specifying the MODIFY AXR command. The installation has the option of defining the prefix to be SYSTEM or SYSPLEX in scope. See z/OS MVS Planning: Operations for more details about CPF processing. The MODIFY AXR command is discussed in z/OS MVS System Commands.

The installation should:

Evaluate the security issues involved with System REXX, including who should have access to the data sets in the REXXLIB concatenation.
Determine who should be allowed to issue MODIFY AXR to submit an exec for execution or to display status from an operator console.

The resource entity for the MODIFY AXR,<exec name> command is MVS™.SYSREXX.EXECUTE.<exec name> and the resource entity for the SYSREXX STATUS command is MVS.SYSREXX.STATUS. Both profiles are defined under the OPERCMDS class. For the MODIFY AXR,SYSREXX STATUS command, if SAF cannot decide whether the request is authorized, it will be allowed. For the MODIFY AXR,<exec name> command, if SAF cannot decide whether the request is authorized, it will be allowed only if the invoking console has MASTER authority.

The AXRUSER() keyword parameter in SYS1.PARMLIB(AXRnn) is optional. No default is assigned to this keyword if an AXRnn member is omitted from SYS1.PARMLIB. When AXRUSER(siteuserid) is added to SYS1.PARMLIB(AXRnn), it signifies to System REXX that the security token for siteuserid can be used by the invoker when the AXREXX macro is coded with SECURITY=BYAXRUSER. The siteuserid must already be defined to RACF. System REXX uses the RACF SURROGAT class resource SYSREXX.siteuserid to verify that siteuserid is authorized to perform this role and will subsequently extract the security token associated with siteuserid. This security token is then subsequently used to set up the security environment for any requests specifying SECURITY=BYAXRUSER. This process is necessary for requests that are initiated under the MASTER address space and other address spaces that do not have bonafide security environments. An example of this is an MPF exit invoking a REXX exec in response to a particular message. This process differs from the way JES uses the SURROGAT class in which the submission of a job could be performed on behalf of another user.

Any defined user ID can be selected by specifying AXRUSER(siteuserid) in SYS1.PARMLIB(AXRnn) where siteuserid is the user ID chosen by the installation to be used as the surrogate user ID. The only access requirement for the surrogate user ID is READ authority to SYS1.SAXREXEC and to any data sets included in the REXXLIB concatenation, unless the installation has imposed some access requirements of its own. Use of the surrogate user ID can be further restricted through universal access control and adding just the surrogate user ID to the permission list.

The following RACF commands are used to establish a surrogate user environment for System REXX. Substitute your installation preferences for siteuserid and sitegroupid.

ADDUSER siteuserid DFLTGRP(sitegroupid)
RDEFINE SURROGAT SYSREXX.siteuserid UACC(NONE)
PERMIT SYSREXX.siteuserid CL(SURROGAT) ID(siteuserid) ACCESS(READ)
SETROPTS RACLIST(SURROGAT) REFRESH

For example, if AXRSROGT is the preferred siteuserid specification and SYS1 is the RACF group name it is connected to, the following commands are entered by the RACF Security Administrator to complete the setup.

ADDUSER axrsrogt DFLTGRP(sys1)
RDEFINE SURROGAT SYSREXX.axrsrogt UACC(NONE)
PERMIT SYSREXX.axrsrogt CL(SURROGAT) ID(axrsrogt) ACCESS(READ)
SETROPTS RACLIST(SURROGAT) REFRESH

For more information, see z/OS Security Server RACF Command Language Reference.

The parmlib member AXRnn provides the user with the ability to specify a set (concatenation) of data sets from which SYSREXX attempts to fetch execs. This set of data sets is referred to as the REXXLIB concatenation. SYS1.SAXREXEC contains execs that IBM provides and in general should not be modified. When SYS1.SAXREXEC is not specified in the REXXLIB concatenation, it is appended to the end. For details about AXRnn processing, see z/OS MVS Initialization and Tuning Reference. Any execs that are added to the concatenation cannot start with the letters A through I that are reserved for IBM execs.